前言¶
DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。在构建智能体工作流时，对代码改动进行审查是常见需求。如果直接在 Harness 中运行 LLM 进行代码审查，存在两个主要风险：一是 LLM 可能修改本地文件，二是敏感代码可能被未经授权的外部 Provider 获取。
dsh-pi-review 插件通过注册一个根 Agent 工具，在 Harness 的只读沙箱中启动独立的 Pi SDK Worker 来解决这些问题。它冻结确定性的 Git 快照，仅允许 Pi 以只读方式审查变更，并返回结构化的代码审查结果。
插件定位¶
这是一个 DeepSeek Harness 的只读 Pi Agent 代码审查插件。插件由 win4r 维护，开源协议为 MIT。它的主要作用是提供隔离、只读的 Git 改动审查能力，确保审查过程不会破坏本地仓库状态，也不会泄露敏感代码。
核心功能¶
插件提供以下核心能力：
- 冻结确定性 Git 快照：在审查前锁定 Git 状态，确保审查内容不变。
- 注册根 Agent 工具：在 Harness 中注册
pi_review_diff工具，供 Agent 调用。 - 独立 Worker 运行：在 Harness 的只读沙箱中启动独立的 Pi SDK Worker，避免宿主进程受到干扰。
- 结构化结果返回：返回包含分类、严重度策略和 Pi 用量统计的可验证结构化 finding。
- 严格权限限制：Pi 没有开放 bash、write、edit、扩展、Skill、Prompt 模板、上下文文件或持久化 Session。Pi 只能读取快照中的当前变更文件。
- 多范围支持：支持
unstaged、staged、working-tree、base、branch等多种 Git diff 范围。
安装与启用¶
安装插件前，建议固定已审计的 commit SHA，以确保环境一致性。
dsh plugin --profile web add -w github:win4r/dsh-pi-review#<commit-sha>
安装完成后，需要重启对应的 Profile 以使插件生效。重启后，可以在顶层对话中要求 Agent 调用 pi_review_diff 工具。
配置与模型¶
插件默认读取 Pi 的 ~/.pi/agent/auth.json 和 ~/.pi/agent/models.json 进行认证。建议在 cordis.patch.yml 中显式配置模型 ID，以避免依赖默认行为。
- insert:
- id: pi-review
name: '@charlesqin/dsh-pi-review'
config:
authority: direct-human
model: kimi-coding/k3
modelProfiles:
fast: kimi-coding/k3
deep: openai/gpt-5.3-codex
thinkingLevel: high
timeoutMs: 300000
maxDiffBytes: 524288
maxFiles: 200
maxOutputBytes: 524288
maxDiagnosticBytes: 65536
disposeGraceMs: 3000
requireFullSandbox: true
在配置中，Worker 固定设置 PI_OFFLINE=1，关闭 Pi 的启动更新和遥测操作，但模型请求仍需访问配置的 Provider。
使用方法¶
安装并重启 Profile 后，在对话中直接调用 pi_review_diff。以下是一些典型用法：
- 审查未提交改动：
请调用pi_review_diff，以working-tree范围审查当前仓库全部未提交改动，重点检查并发与错误处理。 - 审查已暂存改动：
请调用pi_review_diff，以staged范围审查 index 相对 HEAD 的已暂存改动。
工具参数如下：
| 参数 | 说明 |
|---|---|
scope |
审查范围：unstaged、staged、working-tree、base、branch。 |
paths |
可选的仓库相对路径过滤列表。 |
focus |
本次审查的重点（最多 2048 字节）。 |
severity_floor |
返回 finding 的最低严重度：critical、high、medium、low，默认 low。 |
model_profile |
可选的部署级模型别名，必须在 modelProfiles 中预先映射。 |
安全边界与限制¶
在使用插件时，需注意以下安全和限制事项：
- 只读沙箱的性质：只读沙箱保护的是本地文件不被 Worker 修改，不是数据保密边界。被选中的 diff 与变更文件内容会发送给配置的模型 Provider。
- Provider 安全：不要用未经授权的外部 Provider 审查私有、敏感或受监管代码。
- Enforcement 要求：默认要求 Harness 报告
full的 read-only enforcement。 - Worktree 限制：v0.2 版本只支持带物理
.git/目录的独立普通 worktree。linked worktree、.gitindirection file 等会被拒绝。 - 文件访问限制：二进制路径不开放额外文件读取。
staged、branch和commit审查不会打开 live worktree 文件。 - 命令执行限制：Worker 不执行 Pi 配置中的
!command。 - 依赖条件：需要至少一个有效
HEADcommit。全新且尚未提交的仓库会失败。
结语¶
dsh-pi-review 为 DeepSeek Harness 提供了一个安全、可控的代码审查方案。它通过冻结快照和严格限制权限，让 Agent 能够在不破坏环境的前提下完成代码审查。如需了解更多详情，请访问 GitHub 仓库。
