前言¶
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 倉庫。
