BOWLUNA/dsh-zcode-git

dsh-zcode-git

给 DeepSeek Harness 智能体用的一等公民 Git 工具。

DSH 本身没有任何 git 工具，模型只能通过 bash 手搓命令。这个插件注册六个结构化工具，
并解决 bash 路线的三个根本问题：

| 用 bash 的问题 | 本插件的做法 |
| --- | --- |
| 输出形态随用户配置变化（color.ui、core.pager、core.quotepath、diff.external、status.relativePaths、alias） | 每次调用都钉死这些配置，并解析 porcelain / NUL / %x1f 等机器可读格式 |
| git commit -m "..." 要同时活过 cmd.exe、PowerShell 与 POSIX sh —— 三者转义规则不同，且都不会「碰巧」保住 %PATH%、$(...) 或换行 | 构造 argv 数组：参数根本不经过任何 shell |
| 在 bash 里，git status 与 git push --force 权限一样大 | 读操作与写操作分开，写操作走 harness 的审批服务 |

环境要求

- DeepSeek Harness >=0.1.5-rc.2 =0.1.6-alpha.1 =20，harness 自带的那份运行时即满足
- PATH 上有一个 git 二进制

安装

dsh plugin --profile web add dsh-zcode-git

包自带 patch 声明，profile 的 bundles 会自动更新。装完重启 Harness —— bundle 层在启动时读取。

手工挂载：

cordis.patch.yml
- insert:
- id: tool-git
name: dsh-zcode-git

工具清单

| 工具 | 类型 | 作用 |
| --- | --- | --- |
| git_status | 读 | 分支、upstream、ahead/behind，以及 staged / modified / conflicted / untracked / ignored 五类清单 |
| git_diff | 读 | 逐文件行数统计 + unified diff，可用 paths、staged、contextLines 收窄 |
| git_log | 读 | 提交记录，返回 {hash, shortHash, author, date, subject}，limit 限流，paths / revision 过滤 |
| git_branch | 读 + 写 | list / create / switch / delete；写操作需审批 |
| git_commit | 写 | 可选先 paths 暂存，再提交 message；需审批 |
| git_stash | 读 + 写 | list / push / pop / apply / drop；写操作需审批 |

所有工具都接受可选的 path 指定仓库目录，默认取会话工作目录，相对值按会话目录解析。

状态码

git_status 输出 git 自己的两列码 —— 先索引态、后工作区态，所以 .M 是未暂存的改动，
M. 是已暂存的改动。同时也会把词形（index / worktree 字段）返回给偏好的调用方。

安全边界

绝不经过 shell。 每次调用都走 ctx.subprocess.spawn 的 argv 数组。Harness 的另一个接缝
ctx.shell 收的是一整行命令字符串，用它就等于把每个参数重新交给 shell 解析 ——
而不存在一套同时对 cmd.exe、PowerShell 和 POSIX sh 正确的转义（cmd.exe 在双引号内部
依然展开 %VAR%）。所以参数干脆不进 shell。含 "、  、$(...)、%PATH%、换行、
中文的提交信息会逐字节原样存入仓库。

输出被钉死。 以下配置在每次调用时强制覆盖（紧跟在 git 之后），因为每一项都会改变本插件
所解析的字节：

color.ui=false              core.pager=cat
core.quotepath=false        status.relativePaths=false
log.showSignature=false     log.date=default
diff.noprefix=false         diff.mnemonicPrefix=false
diff.external=              advice.detachedHead=false

行为类配置则刻意不覆盖：user.name、user.email、core.autocrlf、hooks、
core.sshCommand 是用户的意图，不是噪声。子进程环境额外注入 GIT_TERMINAL_PROMPT=0，
让需要凭据的操作立即失败而不是卡在一个没人能回答的提示上；以及 GIT_OPTIONAL_LOCKS=0，
让读操作不会因为别的窗口占着 index.lock 而失败。

写操作需审批。 git_commit，以及 git_branch / git_stash 的写入动作，都会在
执行前调用 ctx.approval.request()。如果 profile 没有装审批服务，写操作会被拒绝而不是放行
—— 「静默无保护的 git commit」正是本插件要消除的东西。只有在你明确接受这一点时，
才把 requireApprovalForWrites 设为 false。

路径先校验。 绝对路径、.. 穿越、UNC 路径、驱动器相对形式（C:foo）、
NTFS 备用数据流、Windows 保留设备名、控制字符，都在任何进程启动之前被拒绝。
git 自己也会拦大部分，但先校验能给出精确消息，并让明显敌意的输入连进程都不进。

刻意不提供： push、fetch、pull、reset、clean、rebase、remote、config 写入。
在 bash 里这些至少还躺在一行人类能读的命令里；做成工具就变成「一次调用摧毁工作区、
只靠一个提示框把关」。fetch 与 push 还牵涉凭据与主机密钥处理，值得单独设计，而不是在这里加个复选框。

配置

| 键 | 默认 | 含义 |
| --- | --- | --- |
| timeoutMs | 30000 | 单次调用超时 |
| maxDiffLines | 500 | 默认补丁行数上限（钳制在 10–5000） |
| maxLogEntries | 50 | git_log 默认条数（钳制在 1–500） |
| requireApprovalForWrites | true | 写操作是否需要审批 |

patch 条目是整键替换而非深合并，所以要把想保留的键写全：

- insert:
- id: tool-git
name: dsh-zcode-git
config:
timeoutMs: 60000
requireApprovalForWrites: true

开发

npm test          # node --test

95 个测试，除 harness 的 peer 包外零依赖，分六层：

- test/parse.test.js —— 纯解析器，喂录制的 git 输出
- test/validate.test.js —— 路径、提交信息、分支名、revision 校验
- test/exec.test.js —— spawn spec，喂记录用的假实现
- test/tools.test.js —— 工具行为，喂假 subprocess 服务
- test/e2e.test.js —— 真实 git 二进制 + 真实临时仓库
- test/schema.test.js —— 与 harness、provider 的 schema 兼容性

给后来写 DSH 工具插件的人

本插件里有四处设计，是因为「显而易见的做法」会失败，而且都不是在出错的地方报错。

① ctx.tools.register() 不编译任何东西。 它只校验 output.schema，然后原样存下定义。
parameters 的作者 DSL 不会被转换 —— 所以直接注册原始定义对象，等于把一个没有顶层 type
的裸属性 map 送给模型 provider，整个请求被拒。必须包一层：
ctx.tools.register(defineTool(definition))。而且 provider 只报字母序第一个工具的名字，
于是错误指向一个本身没问题的工具。

② parameters 与 output.schema 用的是两套 DSL。 parameters 是扁平属性 map
（{ path: { type: "string" } }）；output.schema 是裸 JSON Schema
（{ type: "object", properties: { ... } }）。把后者交给 parameters 会抛
parameters.type must be a value schema object；把前者交给 output.schema 会抛
schema.type must be string/…。

③ schema 关键字对版本敏感。 property 内的 required: true 在 dsh-tools 0.1.5-rc.2
上被接受、在 0.1.6-alpha.2 上被拒绝（UNSUPPORTED_SCHEMA）；顶层 required: [...] 数组
两边都拒绝。工具 schema 里出现 enum 会让某个 provider 拒绝整个 function schema，报
must be a JSON Schema of 'type: "object"', got 'type: null'。所以本插件一个都不用，
而是在代码里强制同样的约束 —— 顺带得到了更好的错误消息：
unsupported action "x"; expected one of list, create, switch, delete。

④ 返回值必须与 schema 严格一致。 在 schema 声明为 string 的位置放 null，
会让这一轮以 INVALID_TOOL_OUTPUT 失败，而此时 git 已经执行成功了。
没有值就省略字段，不要送 null。

⑤ 渲染器在工作已完成之后运行。 渲染器读了 execute 从未返回的字段，会在 harness 内部抛错，
把一次本来成功的调用变成失败的一轮。test/tools.test.js 之所以要拿每个工具的输出驱动它自己的
渲染器，就是为这个。

许可

MIT