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