PR 智能审查 nexpeakcore/deepseek-harness-pr-review

用 DeepSeek 做 AI 代码审查 —— 无头 PR 审查自动化

用 DeepSeek 做 AI 代码审查：无头 PR 审查自动化，逐条核对 PR 描述与真实代码是否相符，检查文档与实际是否一致，标出需求影响 —— 只在真正需要时才让人介入。

为什么

PR 描述会说谎。文档会过期。人工代码审查又慢又不一致。这个工具跑一个 DeepSeek Harness 智能体，它会：

- 审查代码本身 —— 阅读改动过的代码找缺陷，每个缺陷都要给出具体的失败场景；再由第二个智能体确认或驳回每个阻断项和重要项，确认的问题以行内评论落到对应代码行
- 逐条核对 PR 描述 —— 描述里的每句话都对照真实代码检查，并给出 file:line 证据
- 审查完全没有描述的 PR —— 这类 PR 恰恰最需要审查。从提交记录、分支名、标签、关联 issue 和 diff 还原意图，再拿代码对照它自己隐含的意图：没解释的范围扩张、没有测试或文档的行为变更
- 发现过期和编造的文档 —— 仓库文档里最多 60% 是错的；智能体把它们和真实代码比对（MATCH / STALE / WRONG / FABRICATED）
- 标出需求影响 —— 一次改动碰到哪些业务需求，是否破坏了什么（CHANGED / BROKEN / RISK）
- 无头运行 —— 一条命令，或者一个自动审查轮询器，盯住每个新 PR

演示

Dashboard: PR review with claim-by-claim evidence

工具正在审查它自己的 PR #9。描述里的每句话都变成一个编号断言，逐条对照真实代码检查，并附 file:line 证据 —— 页头也如实说明查到了什么：描述部分属实，2 个风险，2 份过期文档。标签页分别展示断言、文档、需求影响和审查讨论串。

仓库级页面（KPI、结论分布、每个开放 PR 的审查状态）也包含在内 —— 见 Web dashboard。

功能

| ✅ 代码审查 | 审查改动过的代码本身找缺陷 —— 正确性、错误处理、安全、并发、资源、性能、缺失的测试。每个问题都必须给出具体的失败场景，第二个智能体确认或驳回每个 BLOCKER/MAJOR，确认的问题以行内评论发到对应代码行 |
| ✅ 断言核对 | 把 PR 描述拆成可验证的断言，逐条对照代码检查并给出证据 |
| ✅ 无描述兜底 | PR 正文为空或只有模板套话：从提交、分支、标签、关联 issue 和 diff 重建声明，再检查内部一致性——重建结果回贴为描述，也就是作者本该写的那份 |
| ✅ 文档实况核对 | 文档对照真实代码：MATCH / STALE / WRONG / FABRICATED |
| ✅ 需求影响 | 按业务需求逐条分析 CHANGED / BROKEN / RISK |
| ✅ 人在回路 | 只在不确定时提 ≤20 词的确认问题——绝不猜 |
| ✅ 并行智能体 | 每条审查轴一个智能体（代码 / 声明 / 文档 / 影响），声明超过 15 条、代码超过 20 个文件就分片——40 条声明的 PR 也饿不死文档检查。并发在所有审查进程间全局限流 |
| ✅ 文档目标排序 | 任何智能体启动前，先按 diff 给文档打分（路径邻近度、变更符号、文件提及）——智能体核对一份有界、可复现的清单，而不是满仓库 grep |
| ✅ 仓库配置始终可信 | 添加仓库时先验证它存在且对你的 token 可见，拼写错误不会变成永久配置项。autoreview --check-repos（以及 /config 页面）标出 GitHub 已无法访问的条目，一键删除 |
| ✅ 自动审查轮询 | 自动审查新 PR，并在 diff 变化时重新审查——不只是 head SHA 变化时。rebase、合并基分支、修改提交信息、空提交都会移动 head 却不改一行代码，以前每一种都要付出一次完整的智能体扇出，还要再发一条通知，内容跟上一轮一模一样 |
| ✅ Web 面板 | 仓库配置管理、审查触发（Review now）、实时审查日志、指标：发现的 bug、需要看一眼、文档错误、结论、每个仓库的审查轮次 |
| ✅ 幂等 PR 评论 | 每个 PR 一条英文评论，原地更新——绝不重复 |
| ✅ 可追溯 | 每个阶段都往 sessions/ 写结构化 JSON |

安装

要求：Python 3.10+（推荐 3.11），gh 命令行已认证。

一行命令（推荐——自动探测 Python、创建 venv、修好 PATH）：

curl -fsSL https://raw.githubusercontent.com/nexpeakcore/deepseek-harness-pr-review/main/scripts/install.sh | bash

安装脚本会找一个 Python 3.10+ 解释器（macOS 上回退到 Homebrew），在 ~/.harness-pr-review/venv 创建隔离 venv，从 GitHub 安装包，把 harness-pr-review + autoreview 软链到 ~/.local/bin，再跑 doctor。
重跑即更新到最新版。

或者手动安装：

pip install git+https://github.com/nexpeakcore/deepseek-harness-pr-review.git

或者克隆下来开发：

python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]' # zsh needs quotes; SDK comes from PyPI (deepseek-harness-sdk)

然后认证：

gh auth login # required
export DEEPSEEK_API_KEY=sk-... # see .env.example
harness-pr-review doctor # verify everything is ready

改用 Claude 跑评审？那就不需要 DeepSeek 密钥——见 Agent backends。

密钥也可以放在 .env 文件里。会按顺序读取两个位置：先读 ./.env（开发用的检出目录），再读 ~/.harness-pr-review/.env（一行命令安装的场景，这样命令行在任何目录下都能用）。哪个文件先定义了密钥就用哪个，而真实的环境变量优先级永远高于这两个文件。

Agent backends

评审逻辑不关心是哪个智能体运行时读取工作区，所以后端只是一个环境变量。其余部分——阶段、提示词、schema、报告、评论——两种方式完全一致。

| HARNESS_PROVIDER | 运行时 | 凭据 |
| deepseek（默认） | DeepSeek Harness SDK，由 cordis/minimal.cordis.yml 组装 | DEEPSEEK_API_KEY |
| claude | 无头 claude -p（Claude Code 命令行） | 命令行当前已登录的凭据——有 Claude 订阅就够了，不需要额外的 API 密钥 |
| codex | 无头 codex exec（Codex 命令行） | 已有的 Codex 命令行登录；本项目不读取任何 API 密钥 |
| agy | 无头 agy（Antigravity 命令行） | 已有的 Antigravity 命令行登录；本项目不读取任何 API 密钥 |

export HARNESS_PROVIDER=claude
export HARNESS_CLAUDE_MODEL=sonnet # or opus / haiku / a full model id
harness-pr-review doctor # now checks for the claude binary, not the SDK
harness-pr-review owner/repo 123

或者用 Codex 跑同一条流水线：

export HARNESS_PROVIDER=codex
export HARNESS_CODEX_MODEL=gpt-5.5
harness-pr-review doctor
harness-pr-review owner/repo 123

或者用 Antigravity（agy）跑：

export HARNESS_PROVIDER=agy
export HARNESS_AGY_MODEL=gemini-3.8-flash
harness-pr-review doctor
harness-pr-review owner/repo 123

Codex 和 Antigravity 后端以非交互的无头模式运行。它们把 JSON 返回给 harness，由 harness 校验并自行写出评审分片文件；被评审的 PR 无法指挥命令行去改动它那个一次性的工作树。

阶段日志会写明实际运行的后端，所以万一某次评审悄悄用错了后端，在面板上一眼就能看出来：

[4/5] verify — starting agents 4 agents on claude/sonnet: claims-1, claims-2, docs, impact (cap 4 concurrent)

工作区是一个不可信的 PR，Claude 后端已按 SDK 后端所处的沙箱策略做了同等收紧：

- --tools Read,Grep,Glob,Write——没有 shell，不能编辑，不能联网。这个参数决定本次运行中哪些内置工具存在。单靠 --allowedTools 不构成边界：它只是预先批准哪些工具可以免提示运行，没列进去的工具依然存在，用户设置里的规则仍可批准它。两个参数都传，且来自同一份列表。
- 阶段 2（提取主张）以 --tools "" 运行——完全不给工具。这一步是文本进、JSON 出，它的提示词带着不可信的 PR 描述和
- diff，而且和阶段 3 不同，它没有沙箱工作区来限制它。
- --safe-mode、--setting-sources user 和 --strict-mcp-config 意味着 被审查仓库里提交的 CLAUDE.md、.claude/settings.json、钩子或 .mcp.json 不会被加载——PR 不能配置审查它的智能体。
- 每个智能体都在 --max-budget-usd 下运行，所以不再有进展的循环会停止花钱。上限覆盖智能体，含重试：每次尝试拿到的是剩余额度，而不是一份新的额度。

每个智能体的成本、会话 id 和任何权限拒绝都会写入 sessions/<owner>/<repo>/pr-<n>/claude-<axis>.json，和现有产物放在一起。harness_attempts 和 harness_total_cost_usd 记录每次尝试花了多少——信封本身只描述最后一次。

更新

最省事——内置自更新：

harness-pr-review update # installs the latest version from GitHub
harness-pr-review --version # show the installed version

或者手动：

用 pip 安装（不克隆）：

pip install -U git+https://github.com/nexpeakcore/deepseek-harness-pr-review.git

克隆下来开发：

git pull origin main # pull the latest code
pip install -e . # refresh entry points if pyproject.toml changed

更新之后：

- 自动审查轮询器（launchd/cron）下一轮就会用上新代码——不用重启。
- 正在运行的 Web 面板会一直用旧代码，直到重启：先停掉进程，再重新启动（harness-pr-review web）。
- 你现有的 sessions/ 数据和 autoreview.yml 都会保留——更新从不碰它们。

用法

执行 pip install -e '.[dev]' 之后，你会得到两个命令：

harness-pr-review doctor # check readiness: Python, gh, API key, SDK
harness-pr-review owner/repo 123 # review one PR (interactive)
harness-pr-review owner/repo 123 --skip-human # batch, no questions
harness-pr-review owner/repo 123 --no-post # don't post a comment
harness-pr-review https://github.com/owner/repo/pull/123 # paste a GitHub PR link
harness-pr-review ps # list running reviews and background processes (alias: list)
harness-pr-review stop 12345 # stop a running review or process by PID
harness-pr-review stop owner/repo 123 # stop review for a specific PR (or owner/repo#123)
harness-pr-review stop --all # stop all running review processes
autoreview --once # auto review: single pass
autoreview --daemon # auto review: every interval_minutes
autoreview --status # check if autoreview daemon is running
autoreview --stop # stop running autoreview daemon
autoreview --add-repo https://github.com/owner/repo --mode auto # add by link

（或者从源码运行：PYTHONPATH=src python -m src.run owner/repo 123）结果写入 sessions/<owner>/<repo>/pr-<n>/report.md（用 DSH_SESSION_ROOT 改目录）。

流水线

1. 快照 — 拉取 PR 元数据、diff 文件、提交、评审讨论串（GitHub REST + GraphQL）
2. 主张 — LLM 把描述拆成可验证的主张
3. 验证 — 智能体后端在一次性 worktree 里深挖：逐条验证主张，文档实况核对（MATCH/STALE/WRONG/FABRICATED），需求影响，评审讨论串状态。默认用 DeepSeek Harness，设 HARNESS_PROVIDER=claude 则用 Claude Code —— 见 智能体后端
4. 人工闸门 — 文档有误或主张存疑时请求确认（每个问题 ≤20 词）
5. 汇总 — 生成英文 report.md + 在 PR 上发两条评论：
- 报告 — 一条评论，每次复审原地编辑，PR 不会堆满过期报告。
开头是 Review complete 一行，带时间戳、轮次和受审提交。
- 轮次提醒 — 每轮一条新短评，给出头条数字（两项结论、bug、需关注、文档错误、主张）并附报告链接。
GitHub 对编辑不发通知，所以只有这部分能真正触达订阅者。
用 --no-ping 关闭，或在 autoreview.yml 里设 ping_comment: false。
- 开始通知 — 一轮开始时发出（快照之后、智能体运行之前），写明轮次和受审提交，PR 在评审进行中就能看到已被接手。每轮只发一次：同一 head 上恢复或重试的尝试不会重发。
关闭开关与轮次提醒相同。

运行测试

python -m pytest -v

Web 仪表盘

评审指标的 Web 仪表盘（已评审 PR、发现的 bug、需关注、文档错误、各仓库结论）。直接读 sessions/ —— 不用数据库。

pip install -e '.[web]'
DSH_SESSION_ROOT=sessions harness-pr-review web
harness-pr-review web # open http://127.0.0.1:6789

要跨登录和崩溃持续运行，加载一个 launchd 任务，其 plist 运行 scripts/dashboard.sh，带 RunAtLoad 和 KeepAlive（日志在 web.log），安装方式与 自动评审 下的轮询 plist 相同。
它运行检出目录里的代码，所以更新方式是 git pull 加 launchctl kickstart -k gui/$(id -u)/com.nexpeak.pr-review-web。

页面：仓库列表 → 仓库详情（KPI + 结论环形图 + PR 表格）→ PR 详情（标签页：Code / Claims / Docs / Impact / Threads / Confirm）。PR 表格列出 GitHub 上所有打开的 PR 及评审状态（未评审 / 评审中 / 已评审 N 轮 / 失败 · 中断 —— 会话从未产出发现且没有活动锁，即评审崩溃）。Bugs 统计已确认有误的项： BLOCKER + MAJOR 代码问题、FAIL 主张和 BROKEN 影响。Needs a look 统计 PARTIAL 主张和 RISK 影响 —— 值得人花时间，不显示会算错。文档错误统计 WRONG + FABRICATED + STALE 三类文档。代码轴之前的会话在读取时重新计数，所以仓库的 bug 总数会下降：其中的 PARTIAL 和 RISK 项会移到 Needs a look。每个打开的 PR 行都有一个 Review now / Re-review 按钮，点击后会用仓库的自动审查配置同步执行审查（autoreview.yml 里的 skip-human + post-comment 标志）。

自动审查

轮询 GitHub 上的新 PR（以及它们 diff 的变更），用批处理模式自动审查。每个仓库配置为 auto（轮询器审查它的 PR）或 manual（轮询器跳过它，改用命令行审查）。可以直接编辑 autoreview.yml，也可以用命令行，或者在网页仪表盘上改（Config 页 → 切换 Auto/Manual）。

autoreview.yml 已加入 gitignore——复制 autoreview.yml.example，填上你的仓库。仓库名保持私密。

autoreview.yml (copy from autoreview.yml.example)
org: your-org # default org for repo discovery
default_mode: manual # repos not listed → manual
interval_minutes: 2
post_comment: true
skip_human: true
drafts: false
skip_bots: true # skip bot PRs (Renovate/Dependabot)
repos:
your-repo: auto
another-repo: manual

autoreview --add-repo sample-app --mode auto # enable auto
autoreview --rm-repo sample-app # remove
autoreview --repos # list status
autoreview --once # single pass (cron/launchd)
autoreview --daemon # loop every interval_minutes

launchd 示例（登录时自动启动，每 2 分钟一次）：

<?xml version="1.0" encoding="UTF-8"?>

<plist version="1.0">
<dict>
<key>Label</key><string>com.nexpeak.pr-review</string>
<key>ProgramArguments</key>
<array>
<string>/Users/gianglh/work/harness/scripts/autoreview-once.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key><integer>120</integer>
<key>StandardOutPath</key>
<string>/Users/gianglh/work/harness/autoreview.log</string>
<key>StandardErrorPath</key>
<string>/Users/gianglh/work/harness/autoreview.log</string>
</dict>
</plist>

scripts/autoreview-once.sh 会加载 .env（API key 不写进 plist）。

并行审查。 autoreview.yml 里的 max_parallel（默认 1，上限 8）决定一轮同时审查多少个 PR；1 就是原来的串行行为。每次审查跑在自己的进程里，review.lock 按 PR 加锁，所以两个不同的 PR 绝不会共用工作区或评论。真正有用的上限是你的模型 API 并发数，而不是 CPU——一次审查大约 80% 的耗时都花在等模型上。review_timeout_minutes（默认 30）会杀掉卡住的审查，免得它一直占着槽位。
安装：

cp com.nexpeak.pr-review.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.nexpeak.pr-review.plist
会话清理。 每次审查都会在 sessions/<owner>/<repo>/pr-<n>/workspace 下保留一份完整克隆，合并后的 PR 会留下几百 MB 的残留。harness-pr-review clean 会删除所有已关闭或已合并 PR 的会话；开放 PR 的会话、GitHub 无法查询的 PR（仓库已删除、认证失败）的会话，以及仍在运行的审查的会话都会保留。用 --dry-run 预览。scripts/clean-sessions.sh 为 launchd 封装了它；带 StartCalendarInterval 的 plist（每天 03:00，日志写入 clean.log）安装方式与上面的轮询器相同：

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.nexpeak.pr-review-clean.plist

大型 PR。 审查一个包含大量文件的 PR 会展开成十几个甚至更多智能体，过去是全有或全无：在 review_timeout_minutes 处被杀掉，所有已完成的智能体都丢失，重试又在同一处耗尽时间。现在：

- 每个完成的智能体都保存在 sessions/.../checkpoints/ 下。对同一 head 的重试会复用它们，只运行缺失的部分。新的推送，或不同的 diff 或描述，会使它们失效。
- 轮询器在杀掉前两分钟给审查一个软截止时间。到达截止时间时，它停止启动新智能体，提前结束正在运行的智能体，并以退出码 75 退出（轮询器日志中记为 INCOMPLETE），而不是被杀掉；下一轮继续。三次这样的尝试之后，审查会交付已有结果，未完成的维度列为「Review gap」。
- 在同一 head 上持续失败的审查，第一次立即重试，之后等待时间逐渐增长（日志中记为 BACKOFF，上限一小时）；推送会重置它。状态保存在 PR 会话中的 retry-state.json 里。
- 回答不可用的智能体（文件缺失、JSON 格式错误）会再试一次。
- 超时现在会停止审查的整个进程树，而不只是第一个进程；被杀掉的 git 留下的 .git/index.lock 会在下次检出前清除，而不是让 PR 在每次重试时都失败。

harness-pr-review <repo> <pr> --force --resume 是轮询器重试的手动形式；单纯的 --force 仍然从头开始。

重新审查规则：PR 的 diff 与上次快照相比发生变化 → 所有阶段用 --force 重跑；PR 评论原地更新（绝不重复）。head 移动但 diff 未变——变基、合并基分支、修改提交信息、空提交——记为 SKIP-NO-CHANGE，不产生任何开销。上次审查从未完成的 PR 总是重跑，无论其 diff 看起来多么没变。

两个值得知道的后果：

- 报告中的 Review complete … commit <sha> 行列的是实际被审查的提交。经过 SKIP-NO-CHANGE 之后，PR 的 head 已经越过它，所以这个 SHA 会落后于分支，这是设计使然——它审查的 diff 仍然是 PR 当前的 diff。
- 基于 diff 的规则上线前审查过的会话，指纹与全新获取的不同，所以每个开放 PR 在轮询器第一次看到它时会多审查一次，之后就稳定了。

配置

| 环境变量 | 默认值 | 含义 |
| HARNESS_PROVIDER | deepseek | 智能体后端：deepseek、claude、codex 或 agy（见 智能体后端） |
| HARNESS_CLAUDE_MODEL | sonnet | claude 后端使用的模型 |
| HARNESS_CODEX_MODEL | gpt-5.5 | codex 后端使用的模型 |
| HARNESS_AGY_MODEL | gemini-3.8-flash | agy 后端使用的模型 |
| HARNESS_CODE_REVIEW | 1 | 代码审查维度：代码智能体（每约 20 个改动文件配一个），外加一个验证智能体处理 BLOCKER/MAJOR，并输出行内评论。设为 0 关闭该维度——审查结果会显示 Code: not reviewed |
| DEEPSEEK_API_KEY | — | DeepSeek API key（仅 deepseek 后端需要） |
| DSH_MODEL | deepseek-v4-flash | deepseek 后端使用的模型（智能体 + 主张提取） |
| DEEPSEEK_BASE_URL | https://api.deepseek.com/v1 | OpenAI 兼容端点 |
| DSH_SESSION_ROOT | sessions | 存放各阶段结果的目录 |

许可证

MIT © 2026 Nexpeak