Git 提交门控工具qt-11564/dsh-git-seam

dsh-git-seam

为 DeepSeek Harness（dsh）智能体提供结构化 git 工具——核心差异化是 diff-before-commit 门控（拒绝盲提交）与 确定性 porcelain 解析（中文/UTF-8 路径、空格、CRLF 在 Windows 和 Linux 上稳定解析）。

智能体获得六个工具——git_status、git_diff、git_log、git_show、git_branch、git_commit——外加一层策略：把"先审阅再提交"从模型自觉变成强制保证。

为什么不用 bash 敲 git？

模型本来就能通过 bash 工具跑 git。bash 给不了的是：

- 保证，而不是建议。git_commit 只有在同一轮里先用 git_diff 审阅过、且审阅范围覆盖本次提交的全部文件时才放行；审阅之后才 stage 的文件（比如经 shell git add）会被拦截并点名。bash 无法强制这一点，只能祈祷。
- 确定性解析。所有命令固定 LC_ALL=C、GIT_TERMINAL_PROMPT=0、core.quotepath=false，用机器格式（status --porcelain=v1 -z、diff --numstat、log --format=…）。中文文件名、带 BOM 的 UTF-8 内容、空格、重命名、CRLF——由代码解析，不靠模型运气。
- 看得懂的审批。git_commit 的审批带真实逐文件清单：path (+N/-M)，未跟踪文件标 (new file)。bash 的升级审批只会给你一条命令字符串。
- 明确可行动的失败。非 git 仓库、缺 user.email、../ 越界——返回带下一步指引的错误，而不是原始 stderr。

安装

从 GitHub（推荐）
dsh plugin --profile web add github:qt-11564/dsh-git-seam

或从 npm（发布后）
dsh plugin --profile web add dsh-git-seam

然后重启 profile。可用 dsh --profile web --dump-config 验证（找到 git-seam 行），或直接新开对话——六个 git_* 工具会自动出现。

配置

- id: git-seam
name: dsh-git-seam   # 本地安装时也可用 ./index.mjs
config:
maxBytes: 32768               # 输出字节上限；超限给截断提示 + spill 路径
requireDiffBeforeCommit: true  # diff-before-commit 门控（设 false 关闭）
requireCommitApproval: true    # git_commit 走审批服务
timeoutMs: 30000               # 单条命令超时，超时杀掉

工具

| 工具 | 入参 | 输出 |
|---|---|---|
| git_status | cwd? | 分支、ahead/behind、staged/unstaged/untracked 三区、clean 标记 |
| git_diff | spec?（工作区 / --staged / A..B）、path? | 逐文件 +N/−M 统计 + 截断 unified diff |
| git_log | range?、path? | 提交列表：hash、作者、日期、标题 |
| git_show | ref（必填）、path? | 提交元数据 + 统计 + 截断 diff |
| git_branch | cwd? | 当前分支 + 全部分支 |
| git_commit | message（必填）、paths? | 新 hash + 摘要；受门控和审批约束 |

门控如何工作

git_commit 在 tools/pre-execute 上被检查：

1. 最近一次 git 动作必须是同一轮内成功的 git_diff（上一轮的 diff 不算，失败的 diff 不算）。
2. 提交将包含的每个文件都必须在审阅 diff 的覆盖集内：无 paths 提交核对 staged 集合，paths 提交核对给定路径。
3. 未跟踪文件豁免——git diff 结构上无法显示它们，审查走 fs 读取路径；审批清单里仍会列出。
4. 一次成功的提交使审阅失效，下次提交需要新的 diff。

拒绝时点名校验失败的文件并告诉模型该怎么做（run git_diff again）。门控是普通的 tools/pre-execute 监听器——随插件卸载而消失，与其余策略链正常组合。

已知限制与延后项

- 无破坏性历史操作——reset/checkout/revert/merge/rebase 不在范围，git_commit 是唯一写操作。
- 无 stash、远程操作（push/pull/fetch）、submodule。
- 无 blame、GPG 签名、LFS。
- 远程 provider（GitHub/GitLab REST）延后——仅本地 git。
- 门控校验的是文件覆盖，不是内容新鲜度：diff 之后文件又被编辑、再提交，不会被检测（为了保持门控廉价可预测的刻意取舍）。
- 模型仍可经 bash 绕过工具提交；门控保护的是工具路径，不是沙箱。

开发

npm install            # 安装 selftest 所需的 tsx
npm test               # 13 用例自测：门控语义、审批清单、完整提交流程

自测用 mock ctx + 真实 git fixture 仓库（真实 porcelain 输出）驱动真实插件模块。测试中 @deepseek-ai/dsh-tools 的解析：要么 npm i @deepseek-ai/dsh-tools，要么在 node_modules/@deepseek-ai/dsh-tools 下放一个 dev 垫片，re-export 你本地 harness 仓库的 packages/core/tools/src/schema.ts。

许可证

MIT