dsh-git-seam：DeepSeek Harness 的結構化 Git 工具與提交門禁

前言¶

DeepSeek Harness（DSH）智能體通常通過 bash 工具執行 git 命令。這種方式有兩個主要問題：一是模型可能盲目提交而未檢查變更；二是解析命令輸出（如中文路徑、Windows 換行符）不可靠。dsh-git-seam 旨在解決這兩個問題，提供確定性的 porcelain 解析，並強制執行“diff-before-commit”的審查策略。

插件定位¶

這是一個客戶端插件（類別：客戶端），由 qt-11564 維護。它爲 DSH 代理提供了 6 個結構化 git 工具，以及一個策略層，用於在允許提交前強制執行審查。

安裝與啓用¶

通過官方命令安裝：

dsh plugin --profile web add github:qt-11564/dsh-git-seam

安裝完成後重啓 profile。驗證安裝：

dsh --profile web --dump-config

在對話中，6 個 git_* 工具會自動出現。

配置¶

在配置文件中添加以下內容：

- id: git-seam
  name: dsh-git-seam
  config:
    maxBytes: 32768              # 輸出字節預算，超限會截斷並提示
    requireDiffBeforeCommit: true # 開啓 diff-before-commit 門禁
    requireCommitApproval: true   # 將 git_commit 路由至審批服務
    timeoutMs: 30000              # 單命令超時時間

核心功能¶

插件提供以下 6 個工具：

工具	輸入	輸出
`git_status`	`cwd?`	分支信息、ahead/behind 狀態、暫存/未暫存/未跟蹤文件列表、clean 標誌
`git_diff`	`spec?` (worktree/–staged/A..B), `path?`	文件統計 (+N/-M) + 拼接後的 diff
`git_log`	`range?`, `path?`	提交記錄：hash、作者、日期、主題
`git_show`	`ref` (必填), `path?`	提交元數據 + 統計 + 拼接後的 diff
`git_branch`	`cwd?`	當前分支 + 所有本地分支
`git_commit`	`message` (必填), `paths?`	新 hash + 摘要（需經過門禁和審批）

Diff-Before-Commit 門禁機制¶

git_commit 在 tools/pre-execute 階段檢查：
1. 上一步必須是同一次會話中成功的 git_diff（之前的 diff 不算，失敗的 diff 也不算）。
2. 提交涉及的文件必須包含在 diff 的覆蓋集合中（無路徑提交檢查暫存區，有路徑提交檢查指定路徑）。
3. 未跟蹤文件豁免（因爲 diff 無法展示）。
4. 成功提交後，下一次提交需要重新 diff。

拒絕時會明確指出違規文件，並提示模型重新運行 git_diff。

適用場景與限制¶

適用場景：需要智能體在本地安全地管理 Git 倉庫，且必須強制審查變更才能提交的場景。

已知限制：
- 不支持破壞性歷史操作（reset, checkout, revert, merge, rebase）。
- 不支持 stash、遠程操作（push/pull/fetch）或子模塊。
- 不支持 blame、GPG 簽名或 LFS。
- 遠程提供商（GitHub/GitLab REST）暫不支持，僅限本地 git。
- 門禁只驗證文件覆蓋，不驗證內容新鮮度（編輯 diff 後再提交仍通過）。
- 提交仍可通過 bash 命令繞過，門禁保護的是工具路徑而非沙箱。

結語¶

該插件通過確定性的解析和強制性的提交門禁，降低了智能體操作 Git 的風險，適合對提交審查有嚴格要求的 DSH 工作流。

目錄頁：dsh-git-seam
GitHub 倉庫：github.com/qt-11564/dsh-git-seam