code-review

CI/CD 流程专用的 AI 代码审查 Agent。在 GitHub Actions 中引入后，自动审查本次提交的代码，通过 PR 评论 + GitHub issue 反馈。

工作方式

三个 Agent 协作，A→B 串行 + C 并行：

Agent	职责	输出
A 功能审查	阅读本次 diff，总结实现了什么功能	PR 评论「本次实现功能」section
B 质量审查	找出潜在缺陷，按严重程度创建 issue	GitHub issue（带 reviewer-generated + severity 标签）
C 修复检测	检查 open issue 是否被本次提交修复	关闭已修复的 issue

A 失败则 B 不跑；C 始终独立运行。最终汇总为一条 PR 评论（push 场景无 PR，改用 commit status check 兜底：成功 success / 失败 failure）。

特性

• 三 Agent AI 代码审查（A 功能 / B 质量 / C 修复检测）
• GitHub issue 闭环（创建 / 关闭 / 评论，PAT 鉴权）
• PR 评论通知（审查报告发到 PR 评论）
• push 场景 commit status check 兜底
• .cr-ignore.md 忽略机制（源码行内注释 + 配置文件条目）
• LLM 指数退避重试（最多 20 次，base 2s，上限 60s）
• 镜像发 GHCR（:sha-xxxxxxx / :latest / :main）

快速接入（GitHub 消费者）

1. 在你的仓库配置 4 个 Secrets

Secret	用途
GH_TOKEN	Fine-grained PAT，scope repo，限本仓库（用于创建/关闭 issue、发 PR 评论、写 commit status）
LLM_BASE_URL	OpenAI 兼容 API 地址
LLM_API_KEY	LLM token
LLM_MODEL	模型名（如 gpt-4o / deepseek-chat）

2. 预创建 4 个 label

在你的仓库 Issues → Labels 里手动创建（code-reviewer 创建 issue 时会打这些 label，GitHub 不支持自动创建 label，缺失会 422）：

• reviewer-generated（code-reviewer 自身标记，所有自动 issue 都带）
• critical（🔴 严重）
• warning（🟠 警告）
• suggestion（🟡 建议）

3. 复制以下 workflow 到 .github/workflows/code-review.yml

name: Code Review (AI)
on:
  pull_request:
    branches: [main, master]
  push:
    branches: [main, master]
permissions:
  contents: read
  issues: write
  pull-requests: write
  statuses: write
jobs:
  code-review:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Compute review range
        id: range
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            BASE="${{ github.event.pull_request.base.sha }}"
            HEAD="${{ github.event.pull_request.head.sha }}"
            PR_NUMBER="${{ github.event.pull_request.number }}"
          else
            HEAD="${{ github.sha }}"
            BASE="${{ github.event.before }}"
            PR_NUMBER=""
            if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
              BASE=$(git rev-parse HEAD~1)
            fi
          fi
          echo "BASE=$BASE" >> "$GITHUB_OUTPUT"
          echo "HEAD=$HEAD" >> "$GITHUB_OUTPUT"
          echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_OUTPUT"
      - name: Run code-reviewer
        run: |
          docker run --rm \
            -v "${{ github.workspace }}:/repo" \
            -e GH_TOKEN="${{ secrets.GH_TOKEN }}" \
            -e GITHUB_REPOSITORY="${{ github.repository }}" \
            -e PR_NUMBER="${{ steps.range.outputs.PR_NUMBER }}" \
            -e REVIEW_BASE_SHA="${{ steps.range.outputs.BASE }}" \
            -e REVIEW_HEAD_SHA="${{ steps.range.outputs.HEAD }}" \
            -e LLM_BASE_URL="${{ secrets.LLM_BASE_URL }}" \
            -e LLM_API_KEY="${{ secrets.LLM_API_KEY }}" \
            -e LLM_MODEL="${{ secrets.LLM_MODEL }}" \
            ghcr.io/yunkst/code-review:latest

镜像源：

docker pull ghcr.io/yunkst/code-review:latest

环境变量

必填

变量	说明
LLM_BASE_URL	OpenAI 兼容 API 地址
LLM_API_KEY	LLM token
LLM_MODEL	模型名
REVIEW_BASE_SHA	审查范围 base commit SHA（由 workflow 算好传入）
REVIEW_HEAD_SHA	审查范围 head commit SHA
GH_TOKEN	GitHub PAT（创建/关闭 issue、发评论、写 status）
GITHUB_REPOSITORY	仓库全名（owner/repo，GitHub Actions 自动注入）

可选

变量	默认	说明
PR_NUMBER	（空）	PR 编号。非空 → 报告发 PR 评论；空 → push 场景走 commit status check
MAX_TURNS	200	单个 Agent 最大对话轮数
MAX_DIFF_BYTES	50000	diff 截断阈值
REPORT_LANG	zh	报告语言
REPO_PATH	/repo	仓库挂载路径（容器内）

工具集

三个 Agent 共享 11 个工具（按白名单隔离）：

工具	A	B	C	用途
list_files	✅	✅	—	列出仓库文件
read_file	✅	✅	✅	读文件内容
list_directory	✅	✅	—	列目录
git_diff	✅	✅	✅	查 diff
git_log	✅	✅	—	查 commit 历史
git_show	✅	✅	—	查指定 commit
grep	✅	✅	✅	正则搜索
take_note	✅	✅	—	记笔记（A→B 传递）
read_notes	—	—	—	读笔记（注册但当前 Agent 白名单未启用）
create_issue	—	✅	—	创建 GitHub issue
close_issue	—	—	✅	关闭 GitHub issue

退出码

码	含义
0	审查成功完成（含空 range 跳过）
1	配置错误（缺必填环境变量 / git 初始化失败 / 拉 issue 列表失败）
2	Agent 失败（A / B / C 任一失败）

.cr-ignore.md 忽略机制

开发者标记「已知问题、暂不修复」的 issue，下次审查 Agent C 会自动关闭。两种形态：

1. 源码行内注释（问题定位到具体源码行）

# cr-ignore #42: 测试专用，不修复

Agent C 用正则 cr-ignore\s*#<iid> grep 搜索命中即关闭。

2. .cr-ignore.md 配置文件条目（问题在配置/binary/无明确文件位置）

在仓库根目录创建 .cr-ignore.md：

- issue: 42
- issue: 58

格式：- issue: <数字>，带 # 会被解析器跳过。

Contributing

见 CONTRIBUTING.md。

License

MIT，见 LICENSE。