Huasfan/dsh-tool-git

dsh-tool-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#

本地源码方式（开发 / 快速验证）：

方式一：挂 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    # 单次调用超时（毫秒），默认 30000

Config 为 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 — 构建、测试与贡献流程
- RELEASE-NOTES.zh.md — 各版本发布说明

License

MIT