Claude Code Action 自动化解决方案实战指南：PR 审查、Issue 分诊与仓库维护工作流-育师

Claude Code Action 自动化解决方案实战指南：PR 审查、Issue 分诊与仓库维护工作流

【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action

本指南基于docs/solutions.md（Solutions & Use Cases）中的 8 个即用型自动化方案，系统讲解如何在 GitHub Actions 中集成 Claude Code Action，实现自动 PR 代码审查、按路径定向审查、外部贡献者审查、自定义审查清单、定时仓库维护、Issue 自动分诊、API 变更文档同步以及安全聚焦审查。每个方案均包含完整可复制的yaml工作流、关键配置解读与预期输出，并结合本仓库源码（action.yml、src/modes/detector.ts、src/github/operations/comments/、scripts/gh.sh、scripts/edit-issue-labels.sh等）剖析底层实现原理。读完本文，你将能够在自己的仓库中直接落地这些自动化工作流，并理解其权限模型、进度跟踪与内联评论机制的工作方式。

一、方案总览与通用配置骨架

docs/solutions.md覆盖了 8 个高频自动化场景，它们共享同一套集成骨架，仅在触发事件、权限声明与prompt内容上有所差异：

方案	触发事件	核心权限	核心输出
自动 PR 代码审查	`pull_request`(opened/synchronize)	`pull-requests: write`	PR 评论 + 内联注释
定向路径审查	`pull_request`+`paths`过滤	`pull-requests: write`	安全聚焦的 PR 评论
外部贡献者审查	`pull_request`+`if`条件	`pull-requests: write`	面向新贡献者的全面审查
自定义审查清单	`pull_request`	`pull-requests: write`	按清单逐项核对的总结评论
定时仓库维护	`schedule`/`workflow_dispatch`	`contents: write`、`issues: write`等	汇总发现问题的 Issue
Issue 自动分诊	`issues`(opened)	`issues: write`	自动分类、打标签
API 变更文档同步	`pull_request`+`paths`	`contents: write`	自动提交文档更新
安全聚焦审查	`pull_request`	`pull-requests: write`、`security-events: write`	带严重级别评级的漏洞分析

所有方案的通用最小骨架如下（细节将在各节展开）：

jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} # ...具体任务指令 claude_args: | --allowedTools "..."

几点通用要点：

permissions声明遵循最小化原则：审查类任务contents: read+pull-requests: write即可，涉及提交变更（文档同步）才需要contents: write；所有方案都带上id-token: write，为使用 OIDC 认证（如 Bedrock/Vertex/Foundry 或 workload identity federation）预留能力，具体认证方式见 docs/configuration.md。
fetch-depth: 1用于审查类任务（只读差异），而需要完整历史分析的任务（如定时维护中检查近期提交的 TODO、文档同步）应使用fetch-depth: 0。
claude_args中的--allowedTools是能力边界：Claude 只能调用白名单内的工具，这是防止越权操作的第一道闸门。

二、自动 PR 代码审查（Automatic PR Code Review）

适用场景：仓库中每个新打开或更新的 PR 都自动触发代码审查。这是最基础的方案，也是理解其余方案的前提。

2.1 基础版（无进度跟踪）

name: Claude Auto Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} Please review this pull request with a focus on: - Code quality and best practices - Potential bugs or issues - Security implications - Performance considerations Note: The PR branch is already checked out in the current working directory. Use `gh pr comment` for top-level feedback. Use `mcp__github_inline_comment__create_inline_comment` (with `confirmed: true`) to highlight specific code issues. Only post GitHub comments - don't submit review text as messages. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

关键配置解读：

触发条件：opened（PR 创建）和synchronize（提交新 commit）两个 action，保证每次变更都重新审查。
上下文注入：REPO与PR NUMBER是审查任务的"坐标"，prompt 中必须始终携带，Claude 才能定位目标仓库与 PR。
工具边界：Bash(gh pr comment:*)负责发表顶层评论，Bash(gh pr diff:*)/Bash(gh pr view:*)负责读取差异与 PR 详情，mcp__github_inline_comment__create_inline_comment负责内联注释。
分支状态：actions/checkout已默认检出 PR 分支，prompt 中明确告知 Claude 这一点，避免其重复 checkout。
预期输出：Claude 直接在 PR 上发布审查评论，并在合适位置添加内联注释。

2.2 增强版（带进度跟踪）

若希望像 v0.x 那样看到"审查中"的跟踪评论，只需一行配置：track_progress: true。

name: Claude Auto Review with Tracking on: pull_request: types: [opened, synchronize, ready_for_review, reopened] jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} track_progress: true # ✨ Enables tracking comments prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} Please review this pull request with a focus on: - Code quality and best practices - Potential bugs or issues - Security implications - Performance considerations Provide detailed feedback using inline comments for specific issues. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

进度跟踪的收益：

可视化进度指示：评论中展示"In progress"状态与勾选框，团队成员无需点开 Actions 页面即可了解审查进度。
保留完整上下文：自动携带 PR 详情、评论与附件，Claude 拥有完整审查背景。
迁移友好：适合从 v0.x 升级、怀念跟踪评论的团队。
兼容自定义 Prompt：你的 prompt 成为自定义指令，同时保留 GitHub 上下文注入。

预期输出流程：

Claude 创建跟踪评论："Claude Code is reviewing this pull request..."；
工作过程中持续更新评论，展示进度勾选框；
发布带内联注释的详细审查反馈；
完成后将跟踪评论更新为"Completed"。

源码级原理：track_progress: true的本质是强制切换运行模式。在 src/modes/detector.ts 的detectMode()中，只要trackProgress被设置且事件是实体类事件（PR、Issue、评论等），就直接返回"tag"模式——即使用prompt也会走 tag 模式的"带跟踪评论 + 完整实现能力"路径。同时validateTrackProgressEvent()（src/modes/detector.ts）会做严格校验：track_progress仅支持pull_request、issues、issue_comment、pull_request_review_comment、pull_request_review五类事件；对pull_request事件还要求 action 必须是opened、synchronize、ready_for_review、reopened、labeled之一，否则直接抛错。这与action.yml中track_progress输入项的说明一致（action.yml）。

跟踪评论的创建由 src/github/operations/comments/create-initial.ts 完成：createInitialComment()生成包含 spinner 动画、"Claude Code is working…" 文案与 Job Run 链接的初始评论（正文模板见 src/github/operations/comments/common.ts），并将claude_comment_id写入GITHUB_OUTPUT供后续步骤引用；若配置了use_sticky_comment: true，还会先检索 bot 的历史评论，命中则复用更新而非重复创建。后续进度更新与最终"Completed"状态则通过 src/github/operations/comments/update-claude-comment.ts 的updateClaudeComment()实现，该函数智能区分 PR review comment 与普通 issue/PR 评论 API，遇到 404 时自动回退。

三、仅审查指定文件路径（Review Only Specific File Paths）

适用场景：只有关键文件（认证、API、安全配置）变更时才触发审查，避免对无关改动消耗 token 与审查时间。

name: Review Critical Files on: pull_request: types: [opened, synchronize] paths: - "src/auth/**" - "src/api/**" - "config/security.yml" jobs: security-review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} This PR modifies critical authentication or API files. Please provide a security-focused review with emphasis on: - Authentication and authorization flows - Input validation and sanitization - SQL injection or XSS vulnerabilities - API security best practices Note: The PR branch is already checked out. Post detailed security findings as PR comments. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*)"

关键配置解读：

paths:过滤器：GitHub Actions 原生能力，仅在匹配路径（src/auth/**、src/api/**、config/security.yml）有变更时触发工作流。注意paths过滤只决定是否触发，不会改变检出内容。
场景化 prompt：既然触发前提是"关键文件变更"，prompt 直接声明这一点，并引导 Claude 聚焦认证授权、输入校验、注入漏洞与 API 安全最佳实践，审查意图更明确。
预期输出：仅在关键文件被修改时产出安全聚焦审查。

这类"按条件触发"的组合非常契合合规与安全审查流程：普通改动零成本通过，敏感区域改动自动进入深度人工 + AI 双重审查。

四、审查外部贡献者 PR（Review PRs from External Contributors）

适用场景：对首次贡献者或外部协作者采用更严格的审查标准，同时保持欢迎态度，帮助新人理解项目规范。

name: External Contributor Review on: pull_request: types: [opened, synchronize] jobs: external-review: if: github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} CONTRIBUTOR: ${{ github.event.pull_request.user.login }} This is a first-time contribution from @${{ github.event.pull_request.user.login }}. Please provide a comprehensive review focusing on: - Compliance with project coding standards - Proper test coverage (unit and integration) - Documentation for new features - Potential breaking changes - License header requirements Be welcoming but thorough in your review. Use inline comments for code-specific feedback. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr view:*)"

关键配置解读：

if:条件：github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'精确命中首次贡献者。GitHub 还提供MEMBER、COLLABORATOR、CONTRIBUTOR、NONE等取值，可按需组合出"成员免审 / 外部全审"的策略。
身份注入：CONTRIBUTOR: ${{ github.event.pull_request.user.login }}将贡献者用户名写入上下文，prompt 中可点名 @ 提及。
审查侧重：面向新人的审查重点放在编码规范符合性、测试覆盖、文档、破坏性变更与许可证头要求，并明确"Be welcoming but thorough"——既要全面也要友好。
预期输出：一份帮助新贡献者理解项目标准的详细审查。

进阶安全提示：当仓库接受外部贡献者时，可结合action.yml中的allowed_non_write_users输入处理"无写权限用户创建 Issue/PR"的场景（action.yml），同时参考 examples/issue-triage.yml 中allowed_non_write_users: "*"的用法。需注意处理非写权限用户的不可信内容会引入 prompt injection 风险，Action 会尽力从子进程环境中擦除 Anthropic、云厂商与 GitHub Actions 密钥，但只能在权限极有限的工作流中使用，并务必校验所有输出，详见 docs/security.md。

五、自定义 PR 审查清单（Custom PR Review Checklist）

适用场景：把团队自身的评审标准固化为结构化清单，让 AI 逐项核对、逐项反馈，保证审查口径统一。

name: PR Review Checklist on: pull_request: types: [opened, synchronize] jobs: checklist-review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} Review this PR against our team checklist: ## Code Quality - [ ] Code follows our style guide - [ ] No commented-out code - [ ] Meaningful variable names - [ ] DRY principle followed ## Testing - [ ] Unit tests for new functions - [ ] Integration tests for new endpoints - [ ] Edge cases covered - [ ] Test coverage > 80% ## Documentation - [ ] README updated if needed - [ ] API docs updated - [ ] Inline comments for complex logic - [ ] CHANGELOG.md updated ## Security - [ ] No hardcoded credentials - [ ] Input validation implemented - [ ] Proper error handling - [ ] No sensitive data in logs For each item, check if it's satisfied and comment on any that need attention. Post a summary comment with checklist results. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*)"

关键配置解读：

结构化清单：将"代码质量 / 测试 / 文档 / 安全"四大维度写成 Markdown checkbox 清单，Claude 天然擅长逐项核对勾选。
系统性审查：清单约束了审查顺序与覆盖面，避免 AI 只盯热门话题（如性能）而漏掉规范性问题。
团队定制：清单内容完全由团队定义——覆盖率阈值、是否要求 CHANGELOG、风格指南等均可调整，是"团队标准"落地的低成本方式。
预期输出：按清单逐项核对的结果汇总评论，对未达标项给出具体反馈。

实战技巧：清单可以做到很细。若要同时给出"通过/不通过"结论，可在 prompt 末尾追加Rate the overall result as APPROVED, CHANGES_REQUESTED, or COMMENT之类的成功标准，让输出具备机器可消费的结论字段（action.yml还提供structured_output输出，配合claude_args中的--json-schema可让结果成为结构化 JSON，见 action.yml）。

六、定时仓库维护（Scheduled Repository Maintenance）

适用场景：每周自动执行依赖检查、安全审计、旧 Issue 盘点与文档健康度验证，并把结果沉淀为一条汇总 Issue。

name: Weekly Maintenance on: schedule: - cron: "0 0 * * 0" # Every Sunday at midnight workflow_dispatch: # Manual trigger option jobs: maintenance: runs-on: ubuntu-latest permissions: contents: write issues: write pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 0 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} Perform weekly repository maintenance: 1. Check for outdated dependencies in package.json 2. Scan for security vulnerabilities using `npm audit` 3. Review open issues older than 90 days 4. Check for TODO comments in recent commits 5. Verify README.md examples still work Create a single issue summarizing any findings. If critical security issues are found, also comment on open PRs. claude_args: | --allowedTools "Read,Bash(npm:*),Bash(gh issue:*),Bash(git:*)"

关键配置解读：

双触发方式：schedulecron 表达式"0 0 * * 0"表示每周日零点自动运行；workflow_dispatch允许维护者在 Actions 页面手动触发，方便临时补跑。
fetch-depth: 0：与审查类任务的fetch-depth: 1不同，维护任务需要分析"近期提交"中的 TODO，必须拉取完整历史。
工具范围：Bash(npm:*)执行依赖与审计命令，Bash(gh issue:*)创建汇总 Issue，Bash(git:*)检查提交历史，Read读取文件（如 README 验证）。
权限升级：本任务需要contents: write与issues: write，权限面明显大于只读审查，符合其"写入"性质。
预期输出：一份汇总发现的周报式 GitHub Issue；若发现严重安全漏洞，还会在相关 PR 上评论提醒。

设计要点：这类任务的 prompt 是一份"任务清单"，Claude 按编号顺序执行。建议在 prompt 中明确输出物形态（"Create a single issue"），避免 AI 把结果散落在对话中。workflow_dispatch与 schedule 双通道也便于在 cron 失效或手动补跑时兜底。

七、Issue 自动分诊与打标签（Issue Auto-Triage and Labeling）

适用场景：新 Issue 一创建即自动分析其类型（bug / 功能请求 / 提问）、评估优先级（critical / high / medium / low）、建议标签并检查重复，最后自动打上标签。

name: Issue Triage on: issues: types: [opened] jobs: triage: runs-on: ubuntu-latest permissions: issues: write id-token: write steps: - uses: actions/checkout@v4 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} ISSUE NUMBER: ${{ github.event.issue.number }} TITLE: ${{ github.event.issue.title }} BODY: ${{ github.event.issue.body }} AUTHOR: ${{ github.event.issue.user.login }} Analyze this new issue and: 1. Determine if it's a bug report, feature request, or question 2. Assess priority (critical, high, medium, low) 3. Suggest appropriate labels 4. Check if it duplicates existing issues Use ./scripts/gh.sh to interact with GitHub: - `./scripts/gh.sh issue view [number]` to view the issue - `./scripts/gh.sh search issues "query"` to find similar issues - `./scripts/gh.sh label list` to see available labels Based on your analysis, add the appropriate labels using: `./scripts/edit-issue-labels.sh --add-label "label1" --add-label "label2"` (the issue number is read automatically from the workflow event) If it appears to be a duplicate, post a comment mentioning the original issue. claude_args: | --allowedTools "Bash(./scripts/gh.sh:*),Bash(./scripts/edit-issue-labels.sh:*)"

关键配置解读：

触发与权限：issues: [opened]监听新 Issue；issues: write是打标签与评论的最低权限。
上下文注入：ISSUE NUMBER / TITLE / BODY / AUTHOR 全部注入 prompt，Claude 无需额外读取即可开始分析。
受限工具封装：方案刻意不使用裸gh，而是通过本仓库提供的两个受限脚本收窄能力面：
- ./scripts/gh.sh：一个只允许issue view、issue list、search issues、label list四个子命令的 gh 包装器（scripts/gh.sh），自动将命令限定在GH_REPO/GITHUB_REPOSITORY指定的当前仓库，只放行--comments、--state、--limit、--label四个标志，且搜索查询禁止携带repo:、org:、user:限定符——防止 Claude 越权访问其他仓库或执行任意 gh 命令。
- ./scripts/edit-issue-labels.sh：从GITHUB_EVENT_PATH事件负载中自动读取触发 Issue 编号（不依赖参数，避免错标），仅接受--add-label/--remove-label，并通过gh label list过滤只操作仓库中真实存在的标签（scripts/edit-issue-labels.sh）。
重复检测：通过search issues搜索相似 Issue，命中则在原 Issue 评论中 @ 提及，形成自动去重闭环。
预期输出：新 Issue 被自动分类并打上正确标签，重复 Issue 被自动标记。

配套示例：本仓库 examples/issue-triage.yml 提供了另一形态的 Issue 分诊工作流，它使用/label-issue自定义斜杠命令（配合allowed_non_write_users: "*"与github_token输入），适合团队已维护.claude/commands/label-issue.md的场景。两份示例互补，可对比参考。

八、API 变更时的文档同步（Documentation Sync on API Changes）

适用场景：只要 API 源码路径发生变化，就自动让 Claude 更新 API 文档、OpenAPI 规范与示例，并把改动提交回 PR 分支，实现"代码即文档"的持续同步。

name: Sync API Documentation on: pull_request: types: [opened, synchronize] paths: - "src/api/**/*.ts" - "src/routes/**/*.ts" jobs: doc-sync: runs-on: ubuntu-latest permissions: contents: write pull-requests: write id-token: write steps: - uses: actions/checkout@v6 with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 0 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} This PR modifies API endpoints. Please: 1. Review the API changes in src/api and src/routes 2. Update API.md to document any new or changed endpoints 3. Ensure OpenAPI spec is updated if needed 4. Update example requests/responses Use standard REST API documentation format. Commit any documentation updates to this PR branch. claude_args: | --allowedTools "Read,Write,Edit,Bash(git:*)"

关键配置解读：

路径精确触发：paths限定src/api/**/*.ts与src/routes/**/*.ts，只有 API 层代码变动才触发同步，避免文档流程被无关提交打断。
检出 PR 头部分支：ref: ${{ github.event.pull_request.head.ref }}是关键——同步任务必须检出发起 PR 的分支，才能把文档改动直接提交回该分支。
读写权限：contents: write允许提交文件变更；fetch-depth: 0保证 git 操作（diff、commit、push）有完整历史可依。
工具边界：Read,Write,Edit允许读写编辑文件，Bash(git:*)负责 commit 与 push。
预期输出：API 文档随代码变更自动更新并提交回 PR 分支。

注意事项：此类"AI 直接改代码并提交"的工作流需要更严格的防护。建议配合action.yml中的use_commit_signing（GitHub 提交签名验证）或ssh_signing_key（SSH 签名，优先级更高）来保证提交可信（action.yml）；同时在 prompt 中给出明确的文档格式要求（如 "Use standard REST API documentation format"），约束输出风格。

九、安全聚焦的 PR 审查（Security-Focused PR Reviews）

适用场景：对敏感仓库进行深度安全分析，覆盖 OWASP Top 10 与常见高危漏洞模式，并给出带严重级别的分级发现。

name: Security Review on: pull_request: types: [opened, synchronize] jobs: security: runs-on: ubuntu-latest permissions: contents: read pull-requests: write security-events: write id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # Optional: Add track_progress: true for visual progress tracking during security reviews # track_progress: true prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} Perform a comprehensive security review: ## OWASP Top 10 Analysis - SQL Injection vulnerabilities - Cross-Site Scripting (XSS) - Broken Authentication - Sensitive Data Exposure - XML External Entities (XXE) - Broken Access Control - Security Misconfiguration - Cross-Site Request Forgery (CSRF) - Using Components with Known Vulnerabilities - Insufficient Logging & Monitoring ## Additional Security Checks - Hardcoded secrets or credentials - Insecure cryptographic practices - Unsafe deserialization - Server-Side Request Forgery (SSRF) - Race conditions or TOCTOU issues Rate severity as: CRITICAL, HIGH, MEDIUM, LOW, or NONE. Post detailed findings with recommendations. claude_args: | --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*)"

关键配置解读：

OWASP 对齐的 prompt 结构：将 OWASP Top 10 的十类漏洞逐条列出，外加硬编码密钥、不安全加密、不安全反序列化、SSRF、竞态条件/TOCTOU 等补充检查项，形成一份完整的安全排查手册。
严重级别评级体系：要求 Claude 对每项发现按CRITICAL, HIGH, MEDIUM, LOW, NONE五级评级，输出自带优先级，便于团队先处理高危项。
权限声明：security-events: write为将来对接 GitHub 安全告警 / CodeQL 类能力预留；fetch-depth: 1保持只读审查的最小检出。
可选跟踪：示例中注释了track_progress: true，安全审查通常耗时较长，启用跟踪评论可让团队实时看到审查进度（机制同本文 2.2 节）。
预期输出：一份带优先级的分级安全分析报告，附修复建议与内联定位。

十、所有方案的通用要点（Tips for All Solutions）

10.1 始终携带 GitHub 上下文

无论哪种任务，prompt 开头都应注入事件上下文。PR 审查类至少包含REPO与PR NUMBER；Issue 类还应包含 TITLE / BODY / AUTHOR：

prompt: | REPO: ${{ github.repository }} PR NUMBER: ${{ github.event.pull_request.number }} [Your specific instructions]

上下文缺失是审查"答非所问"的最常见原因——Claude 无法从空工作目录推断目标对象。

10.2 常用工具权限速查

用途	allowedTools 片段
PR 顶层评论	`Bash(gh pr comment:*)`
内联注释	`mcp__github_inline_comment__create_inline_comment`
文件读写	`Read,Write,Edit`
Git 操作	`Bash(git:*)`
依赖与审计	`Bash(npm:*)`
Issue 管理	`Bash(gh issue:*)`
受限 gh 封装	`Bash(./scripts/gh.sh:)`、`Bash(./scripts/edit-issue-labels.sh:)`

关于内联注释的提交时机（重要机制）：调用mcp__github_inline_comment__create_inline_comment时，只有传confirmed: true才会立即发布。省略该参数时，内联注释会被缓冲，待会话结束后由 Action 统一分类处理——真实审查评论正常发布，子代理的测试/探测性评论被过滤掉（这正是为了防止子代理的试探性注释污染 PR）。若要完全关闭分类、让所有内联注释即时发布，可在 Action 输入中设置classify_inline_comments: 'false'。该机制的配置项定义见 action.yml，缓冲评论的最终发布由 src/entrypoints/post-buffered-inline-comments.ts 负责（action.yml 中对应 "Post buffered inline comments" 步骤，仅当classify_inline_comments != 'false'时执行）。

10.3 最佳实践清单

Prompt 要具体：明确指出审查维度、期望输出格式与成功标准，避免开放式指令。
声明输出物形态：例如"Post a summary comment with checklist results""Create a single issue"，让结果可预期、可消费。
设置清晰的成功标准：如清单通过率、严重级别评级、是否要求 APPROVED/CHANGES_REQUESTED 结论。
提供仓库背景：在 prompt 中补充项目语言、技术栈、代码组织方式，显著提升审查准确度。
代码级反馈用内联注释：mcp__github_inline_comment__create_inline_comment定位到具体代码行，比长文评论更易被开发者消化。
严格收敛工具白名单：--allowedTools遵循最小权限；涉及写入/提交的任务（文档同步、定时维护）才放开contents: write与Bash(git:*)。
善用受限脚本：对外部输入敏感的流程（如 Issue 分诊）优先使用scripts/gh.sh这类白名单封装，从工具层杜绝越权命令。