Git 安全工具集ZSLlearn/dsh-git-tools

dsh-git-tools

面向 DeepSeek Harness 智能体预设的结构化、带安全防护的 git 工具——一个零依赖的 Cordis 插件（纯 ESM，无 npm 依赖），经过真实仓库测试加固。

目录

| 路径 | 说明 |
|---|---|
| src/index.js | 插件本体：apply 注册 10 个 git 工具；仅使用 ctx.get('subprocess') / ctx.get('fs') / ctx.tools.register |
| test/register-check.mjs | 零依赖自检：针对 mock 上下文运行 apply，断言 10 个完整的工具 schema + 防护规则 |
| docs/dsh-git-tools-plan.md | 设计文档：架构决策、安全防护清单、完整测试矩阵、迭代/修复日志 |
| testdata/ | 测试夹具（一次性、已被 gitignore）：一个带有裸远程仓库的分叉仓库、一个中文名仓库、一个临时仓库、一个非仓库目录 |

插件

10 个模型工具：git_repo、git_status、git_log、git_branch、git_diff、git_stage、git_commit、git_reset、git_push、git_fetch。

| 工具 | 功能 | 防护规则 |
|---|---|---|
| git_repo | 仓库根目录、当前分支、HEAD、远程仓库、git 版本 | 只读 |
| git_status | 分支、上游跟踪、领先/落后、已暂存/未暂存/未跟踪/冲突 | 只读 |
| git_log | 最近提交（哈希、作者、日期、主题）；count/branch/path 过滤 | 只读 |
| git_branch | 分支及当前标记、上游、领先/落后计数；all 用于远程引用 | 只读 |
| git_diff | name-status / numstat / --stat / 完整统一 diff；base/target/path | 只读 |
| git_stage | 对显式路径执行 git add / git restore --staged | 必须提供路径 |
| git_commit | 提交已暂存的更改；allow_empty/amend 需显式选择 | 必须提供提交信息 |
| git_reset | soft / mixed / hard 重置 | hard 需要 confirm: true |
| git_push | 推送分支或标签 | force 需要 confirm: true（使用 --force-with-lease） |
| git_fetch | 从远程仓库或 all 获取；默认 prune | 近似只读 |

设计亮点：

- 安全优先：除非模型传入 confirm: true，否则 reset --hard / push --force 拒绝执行；强制推送使用 --force-with-lease；不提供 git clean / checkout -- . / branch -D / push --delete；所有地方都禁用交互式提示（不会挂起）；命令以原始 argv 运行，绝不通过 shell。
- 结构化输出：将 porcelain 格式解析为带类型的字段，而非自由形式的 shell 文本。
- 上下文安全：按列表截断并带有 truncated 标志，通过 exec.signal 实现协作式取消，显式设置超时。

在 DeepSeek Harness 中安装 / 使用

将预设行直接指向源文件（绝对路径在任何地方都可用；Windows 盘符会被预设加载器转换为 file: URL）：

agent.cordis.yml under ~/.dsh/.agent-presets//
- id: dsh-git-tools
name: 'D:/absolute/path/to/dsh-git-tools/src/index.js'

或者执行 npm install dsh-git-tools 并引用包名。完整设计、测试矩阵和迭代日志请参阅计划文档。

自检
sh
node test/register-check.mjs

针对模拟的 Cordis 上下文运行 apply，并断言全部 10 个工具均以完整的 schema 注册，受保护的工具暴露 confirm，且在缺少 subprocess 服务时执行能够优雅失败——从而捕获预设挂载校验无法发现的 schema 编译回归。

要求

- PATH 中存在 git（或在 Windows 上回退到已知的 C:\Program Files\Git\cmd\git.exe）
- 一个 harness subprocess 服务（DeepSeek Harness 中的标准配置）

许可证

MIT