dsh-git

为 DeepSeek Harness 代理提供危险编辑前的自动检查点、结构化 Git 工具和经审批的写入操作，统一封装于一个 npm 包中。

English | 中文

功能概述

1. 自动回滚保护。 每次危险操作前——包括 write、edit、str_replace_editor，以及默认启用的 bash——系统都会将工作区快照保存到 refs/harness-checkpoints/。git_checkpoint_restore 工具可恢复相应状态。由于 Shell 命令无法直接接入代理的编辑管线，系统提示定义了强制执行的 Git 安全流程：每次变更工具调用前创建检查点，变更后使用 git_status 验证，发生错误时恢复检查点。
2. 结构化仓库状态。 git_status、git_diff 和 git_log 返回从 porcelain v2 解析的类型化数据，使模型可以直接基于仓库状态进行推理，无需解析终端格式。
3. 持久化的会话级检查点。 快照以本地引用的形式存储在 refs/harness-checkpoints/ 下，不会被推送或清理；回滚操作不会删除未跟踪文件。不存在检查点时（通常发生在干净状态后的首次编辑），git_checkpoint_restore 会从 HEAD 恢复。

所有变更工具均通过 Harness 界面进行审批，使用与 bash 相同的审批机制。

工具

工具	用途
git_status / git_diff / git_log	工作区结构化读取
git_commit	提交暂存变更（审批门控）
git_restore	丢弃工作区变更（审批门控）
git_checkpoint / git_checkpoint_restore	手动快照 / 回滚（审批门控；无快照时回退到 HEAD）

环境要求

• DeepSeek Harness——dev checkout 或本地构建即可；所需的 @deepseek-ai/* 包随安装自带，声明为 peer
• 主机上有 git 可执行文件

安装

通过 Harness 插件命令安装：

dsh plugin --profile web add dsh-git

dsh plugin 会在 profile 内执行 pnpm add dsh-git，并通过包的 dsh.bundle.patch 自动注册 bundle。重启后，三个插件（git-local、tool-git、git-checkpoint-policy）和七个 git_* 工具全部生效。

也可以手动安装 npm 包，然后挂载插件：

cd ~/.dsh/profiles/

npm install dsh-git

- insert:
    - id: git-local
      name: 'dsh-git/local'
    - id: tool-git
      name: 'dsh-git/tool'
    - id: git-checkpoint-policy
      name: 'dsh-git/checkpoint-policy'

改完 profile 的 cordis.patch.yml 后重启。

不要将 dsh-git/git 作为插件条目挂载。定义模块会自动注册 ctx.git；将其与 git-local 一并挂载会导致重复服务错误。

验证

1. 确认“设置 → 插件清单”中包含 git-local、tool-git 和 git-checkpoint-policy。
2. 运行 git_status，确认返回包含 branch: 的结构化报告。
3. 运行 git_commit，批准操作后确认返回 committed 。
4. 编辑文件，确认 refs/harness-checkpoints/ 下生成检查点引用，并使用 git_checkpoint_restore 恢复编辑前的状态。

开发

构建后的 lib/ 目录通过 ./sync.sh [UPSTREAM_DIR] 从上游 Harness 仓库（https://github.com/deepseek-ai/deepseek-harness 的 packages/git/）同步。该脚本会将各组件的 lib/ 目录复制到 lib//，将内部的 @deepseek-ai/dsh-git 导入重写为包自引用 dsh-git/git，并固定版本。src/ 与 tests/ 位于上游仓库；本仓库发布构建产物。

已知限制

• 不支持远端和 PR 操作；push、fetch 以及 gh 工作流仍由 Shell 驱动。
• 检查点恢复不会删除未跟踪文件；git clean 的支持暂未提供。
• refs/harness-checkpoints/* 为本地引用，不会被 fetch、push 或清理。
• 未挂载审批服务时，变更工具将在没有审批门控的情况下运行。
• @deepseek-ai/* peer 依赖由 Harness 提供，而非作为 registry 包发布；dsh-git 必须安装在兼容版本 Harness 的 profile 中。

相关项目

• dsh-git-identity —— 把提交作者钉到环境身份。
• dsh-gh-bridge —— 把 macOS Keychain 的 GitHub token 桥进沙箱 gh。
• dsh-auto-blame —— 自动 blame。