nexpeakcore/deepseek-harness-pr-review

使用 DeepSeek 进行 AI 代码审查 — 无头 PR 审查自动化

License: MIT
Python 3.10+
Built on DeepSeek Harness

使用 DeepSeek 进行 AI 代码审查：无头 PR 审查自动化，逐条验证
PR 描述中的声明是否与真实代码相符，检查文档是否与现实一致，
并标记需求影响——仅在必要时才引入人工介入。

为什么

PR 描述会说谎。文档会过时。人工代码审查既慢又不一致。
此工具运行一个 DeepSeek Harness 智能体，它可以：

- 审查代码本身 — 阅读变更的代码以查找缺陷，每个缺陷都附带
具体的失败场景；第二个智能体确认或驳回每个阻断项和主要问题，确认的问题会作为行内评论发布在其对应行上
- 逐条验证 PR 描述中的声明 — 描述中的每一句话都会
与实际代码进行核对，并附上 file:line 证据
- 审查完全没有描述的 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 词的确认问题——绝不猜测 |
| ✅ 并行 agent | 每个审查维度一个 agent（代码 / 声明 / 文档 / 影响），声明超过 15 条、代码超过 20 个文件时分片——因此一个含 40 条声明的 PR 不会饿死文档检查。所有审查进程的并发数全局设上限 |
| ✅ 排序后的文档目标 | 在任何 agent 运行之前，先根据 diff 对文档评分（路径邻近度、变更符号、文件提及）——agent 验证一个有界、可复现的列表，而不是 grep 整个仓库 |
| ✅ 保持真实的仓库配置 | 添加仓库时先验证其存在且对你的 token 可见，因此拼写错误不会成为永久配置项。autoreview --check-repos（以及 /config 页面）会标记 GitHub 已无法访问的条目，并可一键移除 |
| ✅ 自动审查轮询器 | 自动审查新 PR，并在 diff 变化时重新审查——而不仅仅是 head SHA 变化时。rebase、合并基分支、修改提交信息或空提交都会移动 head 而不改变任何一行，而每一次过去都会触发完整的 agent 扇出，并发送一条与上一轮内容完全相同的新通知 |
| ✅ Web 仪表盘 | 仓库配置管理、审查触发（Review now）、实时审查日志、指标：发现的 bug、需要查看、文档错误、裁决、每个仓库的审查轮次 |
| ✅ 幂等的 PR 评论 | 每个 PR 一条英文评论，原地更新——绝不重复 |
| ✅ 可追溯 | 每个阶段都将结构化 JSON 写入 sessions/ |

安装

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

一行命令（推荐——自动检测 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 需要引号；SDK 来自 PyPI（deepseek-harness-sdk）

然后认证：

gh auth login          # required
export DEEPSEEK_API_KEY=sk-...   # 参见 .env.example
harness-pr-review doctor         # 验证一切是否就绪

改用 Claude 运行审查？那就不需要 DeepSeek 密钥了——参见
Agent 后端。

密钥也可以放在 .env 文件中。会按顺序读取两个位置：
./.env（开发检出目录），然后是 ~/.harness-pr-review/.env（一行式安装，
这样 CLI 就能从任意目录运行）。第一个定义密钥的文件生效，而真实的
环境变量始终优先于两者。

Agent 后端

审查逻辑不关心哪个 agent 运行时读取工作区，因此后端只是一个环境变量。
其他一切——阶段、提示词、schema、报告、评论——两种方式完全相同。

| HARNESS_PROVIDER | 运行时 | 凭据 |
|---|---|---|
| deepseek（默认） | DeepSeek Harness SDK，由 cordis/minimal.cordis.yml 组合 | DEEPSEEK_API_KEY |
| claude | 无头 claude -p（Claude Code CLI） | CLI 已登录所用的任何凭据——Claude 订阅就够了，无需额外 API 密钥 |

export HARNESS_PROVIDER=claude
export HARNESS_CLAUDE_MODEL=sonnet   # 或 opus / haiku / 完整模型 id
harness-pr-review doctor             # 现在检查的是 claude 二进制文件，而不是 SDK
harness-pr-review owner/repo 123

阶段日志会记录实际运行的后端，因此悄悄使用了错误后端的审查在仪表盘中
可见：

[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、hook 或
.mcp.json 不会被加载——PR 无权配置审查它的 agent。
- 每个 agent 都在 --max-budget-usd 下运行，因此一个不再取得进展的循环
会停止花费。上限覆盖该 agent，包括重试：每次尝试获得的是剩余额度，
而不是一份全新的额度。

每个 agent 的成本、会话 id 以及任何权限拒绝都会落到
sessions///pr-/claude-.json，与现有产物放在一起。
harness_attempts 和 harness_total_cost_usd 记录每次尝试的花费——
信封本身只描述最后一次。
更新

最简单的方式——内置自更新：

harness-pr-review update     # 从 GitHub 安装最新版本
harness-pr-review --version  # 显示已安装的版本

或者手动更新：

通过 pip 安装（未克隆）：

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

为开发而克隆：

git pull origin main   # 拉取最新代码
pip install -e .       # 如果 pyproject.toml 有变动，刷新入口点

更新之后：

- 自动审查轮询器（launchd/cron）会在下一次运行时采用新代码——无需重启。
- 正在运行的 Web 仪表盘会一直使用旧代码，直到重启：停止进程，然后再次启动（harness-pr-review web）。
- 你现有的 sessions/ 数据和 autoreview.yml 会被保留——更新永远不会触碰它们。

用法

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

harness-pr-review doctor                # 检查就绪状态：Python、gh、API key、SDK
harness-pr-review owner/repo 123        # 审查一个 PR（交互式）
harness-pr-review owner/repo 123 --skip-human   # 批量，不提问
harness-pr-review owner/repo 123 --no-post      # 不发布评论
harness-pr-review https://github.com/owner/repo/pull/123  # 粘贴一个 GitHub PR 链接
autoreview --once                       # 自动审查：单次运行
autoreview --daemon                     # 自动审查：每隔 interval_minutes 运行
autoreview --add-repo https://github.com/owner/repo --mode auto  # 通过链接添加

（或者从源码运行：PYTHONPATH=src python -m src.run owner/repo 123）

结果会保存在 sessions///pr-/report.md（可通过 DSH_SESSION_ROOT 更改目录）。

流水线

1. 快照 — 获取 PR 元数据、diff 文件、提交、审查线程（GitHub REST + GraphQL）
2. 声明 — LLM 将描述拆分为可验证的声明
3. 验证 — agent 后端在一个一次性 worktree 中深入检查：
验证每条声明、文档现实核查（MATCH/STALE/WRONG/FABRICATED）、
需求影响、审查线程状态。默认使用 DeepSeek Harness，
使用 HARNESS_PROVIDER=claude 时使用 Claude Code——参见 Agent 后端
4. 人工关卡 — 当文档有误或声明不确定时，请求确认（每个问题 ≤20 个词）
5. 综合 — 英文 report.md + PR 上的两条评论：
- 报告 — 一条评论，在每次重新审查时原地编辑，这样 PR
永远不会堆满过时的报告。它以一行 Review complete 开头，
带有时间戳、轮次编号和已审查的提交。
- 一轮 ping — 每轮一条简短的新评论，包含标题数字
（两个结论、bug、需要查看、文档错误、声明）以及指向报告的链接。
GitHub 不会为编辑触发通知，所以这是唯一真正
能触达订阅者的部分。可通过 --no-ping 禁用，或在
autoreview.yml 中设置 ping_comment: false。

运行测试

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

页面：仓库列表 → 仓库详情（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 标志）同步运行审查。

演示数据已检入 sessions/demo/app/ —— 启动服务器并打开
http://127.0.0.1:6789/repos/demo/app/pr/7 查看示例审查（PR #8 显示
一个 CONTRADICTED 裁决 + FABRICATED 文档），可用于截图和文档。

自动审查

轮询 GitHub 以获取新 PR（及其 diff 的更改）并以批处理模式自动审查它们。每个仓库配置为 auto（轮询器审查其 PR）或
manual（轮询器跳过它；通过 CLI 审查）。直接编辑 autoreview.yml，通过 CLI，或
从 Web 仪表板（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 分钟一次）：

Labelcom.nexpeak.pr-review
ProgramArguments

/Users/gianglh/work/harness/scripts/autoreview-once.sh

RunAtLoad

StartInterval120
StandardOutPath
/Users/gianglh/work/harness/autoreview.log
StandardErrorPath
/Users/gianglh/work/harness/autoreview.log

scripts/autoreview-once.sh 会加载 .env（API 密钥不会进入 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

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

有两个值得了解的后果：

- 报告中的 Review complete … commit  行指明了实际被审查的提交。
在 SKIP-NO-CHANGE 之后，PR 的头部已经越过它，
因此该 SHA 按设计可能落后于分支——它所审查的 diff 仍然是
该 PR 所拥有的 diff。
- 在基于 diff 的规则发布之前审查过的会话，其指纹与
全新获取不同，因此每个打开的 PR 在轮询器第一次看到它时会多获得一次审查，然后
就稳定下来。

配置

| 环境变量 | 默认值 | 含义 |
|---|---|---|
| HARNESS_PROVIDER | deepseek | 代理后端：deepseek 或 claude（参见 代理后端） |
| HARNESS_CLAUDE_MODEL | sonnet | claude 后端使用的模型 |
| HARNESS_CODE_REVIEW | 1 | 代码审查轴：代码代理（每约 20 个变更文件一个）加上一个用于 BLOCKER/MAJOR 的验证代理，以及行内评论。0 将其关闭——审查随后显示 Code: not reviewed |
| DEEPSEEK_API_KEY | — | DeepSeek API 密钥（仅 deepseek 后端需要） |
| DSH_MODEL | deepseek-v4-flash | deepseek 后端使用的模型（代理 + 声明提取） |
| DEEPSEEK_BASE_URL | https://api.deepseek.com/v1 | OpenAI 兼容端点 |
| DSH_SESSION_ROOT | sessions | 存储各阶段结果的目录 |

许可证

MIT © 2026 Nexpeak