dsh-git-tools

gitnpmMIT

Runs git in the Host process so push, pull and fetch work inside the agent sandbox; exposes 8 agent tools (status, diff, log, stage, commit, push, fetch, pull) and 11 slash commands including /git-status, /git-commit, /git-tag and /git-name-set.

下载量 / Downloads

672

Install

dsh plugin --profile web add dsh-git-tools

Sandbox test

This plugin has not been tested yet. Submit a test →

README

本仓库创建于 2026年10月2日 10:33，配套的快捷命令让你能直接联通 GitHub 仓库。

dsh-git-tools

给 DeepSeek Harness 的 agent 用的 Git 工具，git 在宿主进程中执行。

版本与测试环境

项目 · 版本

已验证的 DSH 版本 · 0.1.1-rc.2 与 0.1.7-rc.2

Node.js · v24.9.0（DSH 随包自带）

Git · 2.55.0.windows.3

操作系统 · Windows 11（build 10.0.26200）

兼容性范围

本插件已在两个不同年代的 DSH 版本上实测通过，两者都能正常加载并注册全部

8 个 agent 工具与 13 个斜杠命令：

DSH 版本 · 场景 · 结果

0.1.1-rc.2 · 全局 CLI（dsh web --port 8080） · ✅ 通过

0.1.7-rc.2 · DSH Desktop · ✅ 通过

之所以能跨这两个版本，是因为插件只使用两者共有的 API：

宿主服务 ctx.subprocess（执行 git）与 ctx.commands（注册斜杠命令）
命令注册字段仅用 name / description / handler / input.hint

刻意避开的字段

CommandDefinitionId（来自 @deepseek-ai/dsh-commands/brand）只存在于较新版本，

0.1.1-rc.2 的 brand 模块仅导出 CommandId。它的类型声明是：

export interface CommandDefinition {
    readonly name: string;
    readonly description: string;
    readonly input?: CommandInputDescriptor;
    readonly recordInput?: boolean;
    readonly handler: (invocation) => CommandResult | Promise<CommandResult>;
}

没有 definitionId。 早期版本曾依赖该字段，导致在 0.1.1-rc.2 上加载时报：

SyntaxError: The requested module '@deepseek-ai/dsh-commands/brand'
does not provide an export named 'CommandDefinitionId'

现已完全移除。因为 definitionId 在新版中本就是可选字段，移除不影响新版行为，

却让旧版也能加载。

其他说明

package.json 的 peerDependencies 声明了 @deepseek-ai/cordis@^4.0.1 与

@deepseek-ai/dsh-tools@^0.1.1-rc.2（下限设为已验证的最低版本，以便旧版也能安装）。

这两个包由 DSH 运行时注入，不需要 pnpm 安装，安装时若出现 missing peer 警告可以忽略。

升级 DSH 后请重新验证。 尤其是斜杠命令的注册契约与命令名规则

（/^[a-z][a-z0-9_-]*$/）属于宿主内部约定，跨版本可能变化；本插件之所以兼容两个版本，

正是因为它只依赖这些约定中最稳定的部分。

使用新版本专有 API 会立刻破坏旧版兼容。若确需使用，请在本文档的兼容表中

注明最低版本要求。

为什么需要它

agent 的 shell 运行在 workspace-write 文件沙箱里，实测该环境无法访问网络：

受限进程拿不到 TLS 凭据句柄，任何 https:// 请求都会失败（包括 GitHub、gitee、百度）。

同时 git 不读 Windows 系统代理（WinINET），所以即使 FLClash 开着系统代理，

沙箱内的 git fetch / pull / push 依然失败。

本插件通过 ctx.subprocess 在宿主进程里 spawn git。宿主进程不受 agent 沙箱约束，

因此这些联网操作可以正常工作。这与官方 dsh-workspace-changes 插件执行

git diff-tree 的方式一致。

提供的工具

工具 · 作用 · 是否联网

git_status · 分支、upstream、ahead/behind、逐文件状态 · 否

git_diff · 工作区 / 暂存区 / 指定 rev 的 diff · 否

git_log · 最近提交列表 · 否

git_stage · 暂存或取消暂存（all 或指定路径） · 否

git_commit · 创建提交（支持 all、amend） · 否

git_fetch · 抓取远端并报告 ahead/behind · 是

git_pull · 抓取并集成（支持 rebase） · 是

git_push · 推送到远端（支持 set-upstream） · 是

所有工具都接受可选 cwd，默认使用当前会话的工作目录。

提供的斜杠命令（人类使用）

在输入框直接输入即可，不经过模型，在宿主进程中执行 git：

命令 · 选项 · 是否联网

/git · — · 否

/git-status · cwd=<dir> · 否

/git-diff · --staged rev=<rev> cwd=<dir> · 否

/git-log · n cwd=<dir> · 否

/git-commit · --all --amend <message> cwd=<dir> · 否

/git-fetch · --prune remote=<name> cwd=<dir> · 是

/git-pull · --rebase remote=<name> branch=<name> cwd=<dir> · 是

/git-push · --set-upstream remote=<name> branch=<name> cwd=<dir> · 是

/git-name-set · name=<name> email=<email> remote=<url> cwd=<dir> · 否

/git-tag-show · [version] cwd=<dir> · 否

/git-tag · <version> [<remote>] message=<text> rev=<rev> cwd=<dir>；或 --push [version] [<remote>] · 是

每一个命令都支持 cwd=<dir>，用于指定仓库所在目录（见下方「关于仓库定位」）。

参数类型约定

记号 · 含义 · 例子

<x> · 必填值 · <message>

[x] · 可选 · [cwd=<dir>]

--flag · 开关，写了就生效，不带值 · --staged

key=<v> · 键值对，必须带 = · cwd=D:\repo

⚠️ 值参数漏掉 = 会失效：cwd=D:\repo ✅；cwd D:\repo ❌（被当成两个无关的词）。

两个关键参数：`cwd` 与 `remote`

这两个是寻址参数——它们不提供新能力，只负责把命令指向正确的目标。

`cwd=<dir>`：指定操作哪个仓库

所有 9 个命令都支持，这是最常用的参数。

项目 · 说明

指定什么 · git 在哪个目录执行，也就是操作哪个仓库

默认值 · 省略时使用当前会话的工作目录

写法 · cwd=D:\path\to\repo 或 cwd=D:/path/to/repo（两种斜杠都行）

必须是仓库 · 目录不是 git 仓库时会明确报错，不会静默失败

路径含空格 · 目前不支持（解析按空格分词），请避免

什么情况下必须写 cwd=：

会话工作目录本身不是 git 仓库时。典型情形是工作区指向一个"容器目录"，

真正的仓库在它的子目录里：

工作区根      D:\Githubrep                              ← 不是仓库
真正的仓库    D:\Githubrep\skills-introduction-to-github  ← 仓库在这里

此时每个命令都要带 cwd=：

/git-status cwd=D:\Githubrep\skills-introduction-to-github
/git-commit cwd=D:\Githubrep\skills-introduction-to-github "改了什么"
/git-push   cwd=D:\Githubrep\skills-introduction-to-github

一劳永逸的替代方案：把 DSH 工作区直接指向仓库根目录。

之后所有命令零参数，也不再需要 cwd=。

`remote=<...>`：指定远端——注意语义有两种

remote= 在两类命令里含义完全不同，这是最容易搞混的地方。

（下表只列出涉及远端的命令，不是命令全集；全集见上面的命令表。）

命令 · remote= 填什么 · 例子 · 效果

/git-push<br>/git-pull<br>/git-fetch · 远端名 · remote=origin · 对哪个已配置的远端操作

/git-name-set · URL · remote=https://github.com/you/repo.git · 把这个仓库的 origin 改指向新地址

为什么容易错：remote=upstream 在 push/pull/fetch 里是合法的（"名叫 upstream 的远端"），

但在 /git-name-set 里会被拒绝，因为它期待一个 URL。

/git-push remote=upstream                    ✅ 远端名，推到名为 upstream 的远端
/git-name-set name=X email=x@y.com remote=upstream          ❌ 被拒绝：这需要 URL
/git-name-set name=X email=x@y.com remote=https://...git    ✅ URL，改写 origin

基本信息：

项目 · 说明

适用命令 · 只有 /git-push、/git-pull、/git-fetch（其余命令不涉及远端）

默认值 · origin——git 克隆仓库时自动创建的默认远端

什么时候需要改 · 见下方「多个远端的场景」

多个远端的场景（默认 origin 不够用时）：

# 先在终端里添加一个远端（插件没有添加远端的命令）
git remote add gitee https://gitee.com/you/repo.git
git remote add upstream https://github.com/original/repo.git

之后就能用 remote= 区分：

/git-push remote=gitee          推到 Gitee 而不是 GitHub
/git-fetch remote=upstream      从原始仓库（你 fork 的来源）取更新
/git-pull remote=upstream branch=main   把原始仓库的 main 合并进来

查看当前有哪些远端：插件没有专门命令，用终端 git remote -v，

或让 agent 执行。

`/git-name-set`：配置提交身份与仓库指向

一次性设置提交身份，并可选地把当前仓库指向另一个远端地址：

/git-name-set name=ZhangSan email=zhangsan@example.com
/git-name-set name=ZhangSan email=zhangsan@example.com remote=https://github.com/zhangsan/repo.git

参数 · 必填

…(truncated)

Rendered from the README published on npm. Formatted only, not edited.

Versions

Published on npm:：2，最后更新 2026-10-02

Links

GitHub · Homepage · npm

dsh-git-tools

Install

Sandbox test

README

dsh-git-tools

版本与测试环境

兼容性范围

刻意避开的字段

其他说明

为什么需要它

提供的工具

提供的斜杠命令（人类使用）

参数类型约定

两个关键参数：cwd 与 remote

cwd=<dir>：指定操作哪个仓库

remote=<...>：指定远端——注意语义有两种

/git-name-set：配置提交身份与仓库指向

Versions

Links

Same category

两个关键参数：`cwd` 与 `remote`

`cwd=<dir>`：指定操作哪个仓库

`remote=<...>`：指定远端——注意语义有两种

`/git-name-set`：配置提交身份与仓库指向