dsh-tool-git
Git 工具 —— 为 DeepSeek Harness 的 agent 提供 9 个结构化的模型可见工具，替代"用 bash 裸敲 git 命令再解析文本"：
| 工具 | 作用 | 关键参数 | 规范值（canonical value）要点 |
|---|---|---|---|
git_status | 工作区状态 | workdir? | branch/head/clean/staged/unstaged/untracked/conflicts 结构化列表 |
git_diff | 差异（默认未暂存） | staged? stat? paths? | diff 文本 或 stat 数字摘要；UI diff 卡片 |
git_log | 提交历史 | count? paths? | commits[]（hash/shortHash/author/date/subject） |
git_add | 暂存文件 | paths? 或 all? | 暂存后回读的 stagedFiles[] |
git_commit | 创建提交 | message（必填）body? amend? stageAll? | 新提交的 hash/shortHash/branch；空索引返回 reason: 'nothing-to-commit' |
git_branch | 分支 列表/创建/切换/删除 | action? name? startPoint? force? | branches[]（name/current/upstream）或操作结果 |
git_show | 查看提交或某 rev 下的文件 | rev path? stat? | commit 元数据 + patch（UI diff 卡片）或文件 content（UI read 卡片） |
git_restore | 丢弃工作区改动 / 取消暂存 | paths staged? source? | restored[] —— 实际被恢复的文件 |
git_merge | 合并分支/提交 | rev noFF? abort? message? | 新 HEAD，或冲突时的 conflicts[] |
所有工具均接受 workdir（默认会话工作区，相对路径基于它解析）。
兼容性
- 已针对 DeepSeek Harness 0.1.0-rc.6 验证（
package.json中 peer/dev 依赖的精确版本与该版本内置包一致）。 - Harness 插件接口在预览期仍在演进；升级
dsh后请重跑pnpm test确认兼容，发现问题欢迎反馈。 - 需要
git≥ 2.23（--porcelain=v2与git restore）。
安装
# 从 GitHub 安装（pnpm 会自动执行 prepare 构建 lib/index.js）
dsh plugin --profile web add github:Huasfan/dsh-tool-git
# 首次从 git 安装，pnpm 会拒绝执行构建脚本，需在 profile 的 pnpm-workspace.yaml 放行
# （dsh 会打印出具体键，复制进去即可）：
# allowBuilds:
# dsh-tool-git: true
# 建议锁定提交：github:Huasfan/dsh-tool-git#<commit-sha>本地源码方式（开发 / 快速验证）：
# 方式一：挂 bundle 补丁
dsh --profile web --patch /abs/path/to/dsh-tool-git/cordis.patch.yml
# 方式二：直接挂 TS 源码（loader 支持 .ts，含相对导入）
# name: '/abs/path/to/dsh-tool-git/src/index.ts'配置（cordis.yml）
- id: git-tool
name: dsh-tool-git
config:
gitPath: git # git 可执行文件，默认 "git"
timeoutMs: 30000 # 单次调用超时（毫秒），默认 30000Config 为 Schemastery schema：非法配置在加载期即失败并给出可操作的报错。
设计要点（遵循官方契约）
- 一个 canonical JSON 值：
execute只返回output.schema声明的结构化值；output.render负责模型可见文本。模型不必解析散文来取字段（遵循官方 tool authoring reference）。 - 非零退出是"领域结果"而非异常：git 失败（非仓库、pathspec 不匹配、hook 拒绝等）返回
{ ok: false, error }；基础设施故障（git 缺失、超时、取消）才抛错。超时落到error字段；取消复用TOOL_ABORTED抛AbortError。 - 协作取消：每个调用把
exec.signal透传给child_process.execFile。 - 无 shell 注入：
execFile+ 参数数组，命令串永不插值；环境固定LC_ALL=C、GIT_TERMINAL_PROMPT=0、GIT_PAGER=cat，读取类命令加--no-optional-locks。 - 注册即 effect：
ctx.tools.register(...)随插件卸载自动注销，无需手动清理。 - 机器可读解析：
git status --porcelain=v2 -z --branch，位置切片解析（路径可含空格），rename 的原始路径取紧随其后的裸记录。 - 工具自持 UI 卡片：纯函数
presentCall/presentResult，output.presentationMeta投影可回放的 diff 卡片与 read 卡片数据（git_diff、git_show），会话日志回放也能还原。
参考实现：@deepseek-ai/dsh-tool-bash。
开发
pnpm install # 所有开发依赖来自 npm，无需本机 dsh 安装
pnpm typecheck # tsc --noEmit（TS 5.8 strict + erasableSyntaxOnly）
pnpm test # vitest：28 例（解析器单测 + 真实临时 git 仓库集成）
pnpm build # esbuild 打包为 lib/index.js（prepare 同款）peer 依赖（@deepseek-ai/dsh-tools 等）精确锁定为 dsh 0.1.0-rc.6 同款版本； 运行期从 profile 的 in-box 依赖解析，无需另行安装。
文档
- [CONTRIBUTING.zh.md](CONTRIBUTING.zh.md) — 构建、测试与贡献流程
- [RELEASE-NOTES.zh.md](RELEASE-NOTES.zh.md) — 各版本发布说明
License
[MIT](LICENSE)