代码审查自动化

审查流水线（PR → CI → Bot → 人）

  [ 打开 / 更新 PR ]
        │
        ▼
  ┌─────────────┐     门禁：lint / test / 类型 / 安全扫描
  │  CI 工作流   │──── 产物：日志、覆盖率、SBOM（按需）
  └─────────────┘
        │
        ▼
  ┌─────────────┐     汇总：同一检查一条评论线程；链接文档与本地命令
  │  PR Bot     │──── 失败可复现：配置文件路径、抑制语法、issue 模板
  └─────────────┘
        │
        ▼
  ┌─────────────┐     语义：设计、边界情况、命名、演进策略、例外是否合理
  │ 人类 / Agent │──── 不重复 Bot 已标出的格式化问题
  └─────────────┘

强制（Enforce）与建议（Advisory）

新检查优先 report-only（或单独 workflow）收集基线，再切到 enforce；同一规则不要在「仅注释」与「阻塞合并」之间来回横跳，除非有数据支撑。

集成 AI 审查的完整 GitHub Actions workflow（可直接粘贴并替换 secrets 名称）：

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths-ignore:
      - "**/*.md"
      - "dist/**"
      - "**/package-lock.json"

jobs:
  ai-review:
    runs-on: ubuntu-latest
    if: >
      !github.event.pull_request.draft &&
      !contains(github.event.pull_request.title, '[skip-review]')
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed
        run: |
          git diff --name-only origin/${{ github.base_ref }}...HEAD \
            > changed_files.txt
          cat changed_files.txt

      - name: Run AI review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
        run: |
          # 调用审查脚本，输出 JSON 格式的审查意见
          node .github/scripts/ai-review.js \
            --changed-files changed_files.txt \
            --output review-output.json

      - name: Post review comments
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node .github/scripts/post-comments.js \
            --review review-output.json \
            --pr ${{ github.event.pull_request.number }}

结构化审查输出的 JSON 格式（review-output.json）：

{
  "summary": "共发现 2 处 P0，3 处 P1，1 处 P2",
  "comments": [
    {
      "file": "src/api/handlers.ts",
      "line": 42,
      "severity": "P0",
      "message": "用户 ID 直接拼入 SQL，存在 SQL 注入风险",
      "suggestion": "改用参数化查询：db.query('SELECT * FROM users WHERE id = $1', [userId])",
      "rule": "security/no-sql-injection"
    },
    {
      "file": "src/services/payment.ts",
      "line": 87,
      "severity": "P1",
      "message": "catch 块吞掉了 StripeError，调用方无法区分错误类型",
      "suggestion": "将 StripeError 映射为业务错误码后重新 throw",
      "rule": "error-handling/no-swallow"
    }
  ]
}

差异化策略：根据文件路径启用不同规则集：

// .github/scripts/ai-review.js 中的差异化策略
function getRulesForFile(filePath) {
  if (filePath.endsWith('.env') || filePath.includes('config/secrets')) {
    return ['security/no-plaintext-secrets', 'security/no-credentials'];
  }
  if (filePath.endsWith('.sql') || filePath.includes('migrations/')) {
    return ['db/reversible-migration', 'db/no-drop-without-backup'];
  }
  if (filePath.endsWith('.tsx') || filePath.endsWith('.jsx')) {
    return ['react/no-direct-mutation', 'a11y/interactive-aria-roles', 'security/no-dangerouslySetInnerHTML'];
  }
  return ['general/no-hardcoded-secrets', 'general/error-handling'];
}

与 reviewdog 集成的配置（.reviewdog.yml）：

runner:
  ai-review:
    cmd: node .github/scripts/ai-review.js --format rdjson
    format: rdjson
    reporter: github-pr-review
    level: warning
    fail_on_error: true
    filter_mode: added

误报标记格式（在源码注释中使用，由 AI 审查脚本识别后跳过该行）：

// ai-review-ignore: 此处 hardcoded 是测试环境 mock，非生产 secret
const MOCK_API_KEY = "test-key-not-real";

// ai-review-ignore: legacy code，已在 JIRA-1234 中记录迁移计划
const result = db.query(`SELECT * FROM users WHERE id = ${userId}`);

PR Bot 评论礼仪

• 一条检查一线程：同一工具的多条告警尽量折叠或汇总，避免刷屏。
• 可行动：给出文档链接、可本地复现的一条命令、修复或抑制的官方写法（含文件路径）。
• 误报路径：说明如何开 issue / 加 allowlist，而不是让作者在评论区「求放过」。
• 尊重草稿：Draft PR 默认跑轻量检查或仅 advisory，合流前再跑全量 enforce（与 workflow 实验室中的条件一致）。

噪声与度量

用数据驱动降噪：跟踪「Bot 评论数 / PR」「被标记为误报或无效的评论比例」「同一规则重复触发次数」「从打开 PR 到全绿的中位时间」。

• 合并后回顾：若某规则长期被忽略或大量抑制，改为 advisory 或收紧范围。
• 对生成物目录、锁文件、大资源使用 paths-ignore 或独立 job，避免无意义运行。
• 将「评论洪水」与「合并延迟」纳入团队复盘指标，与 enforce 列表一起审议。

人类审查 vs 自动化边界

自动化：语法与策略可穷举的规则、跨仓库一致的风格、安全与许可证基线、可重复构建与测试结果。

人类 / Agent：需求是否被正确实现、抽象是否合适、错误处理与可观测性是否匹配场景、是否引入隐性耦合或过度设计。

Workflow 片段实验室

勾选下方选项，生成可粘贴到 GitHub Actions 的示意片段：paths-ignore 列表与 jobs.<id>.if 条件（表达式需按你仓库的触发事件微调）。