本仓库创建于 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` `/git-pull` `/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

参数	必填	写入位置	作用范围
`name=<name>`	✅	`git config --global user.name`	全机器所有仓库
`email=<email>`	✅	`git config --global user.email`	全机器所有仓库
`remote=<url>`	—	目标仓库的 `origin`（`remote set-url`）	仅该仓库
`cwd=<dir>`	—	—	指定要改远端的仓库

两点必须理解清楚：

身份是全局的，不是临时的。 git config --global 写入 ~/.gitconfig，之后本机所有仓库的提交都用这个名字和邮箱。想只影响单个仓库，请手动用 git config --local。
remote= 必须填 URL，不能填远端名。 填 remote=upstream 会被拒绝，因为这是"远端名"而非地址。它的作用是改变这个仓库推送的目标地址，而不是新建一个远端。

所有校验都在写入之前完成：参数有误时不会有任何副作用（不会写配置、不会改 remote）。

示例：

/git 列出全部命令与用法
/git-status
/git-commit 修复登录跳转
/git-commit --all 批量更新文档
/git-push --set-upstream
/git-pull --rebase
/git-diff --staged

也支持 key=value 形式的选项，用于覆盖默认值：

/git-status cwd=D:\some\other\repo
/git-push remote=upstream branch=release
/git-diff rev=origin/main...HEAD

关于仓库定位：命令默认以「会话工作目录」为仓库根。如果该目录本身不是仓库（例如工作区指向 D:\Githubrep 而仓库在其子目录），命令会返回一条明确提示，此时用 cwd=<路径> 指向真正的仓库，或直接把工作区改到仓库根目录。

版本管理（标签）

先理解：版本是什么

git 里没有自动的版本号。每 git commit 一次就产生一个提交，但提交只由哈希（如 9f6af9d）标识，无法用 v1.0.0 这样称呼它。

标签（tag）就是给某个提交起的名字，这才是"版本"：

提交 b237987 ──▶ C1
提交 8985e21 ──▶ C2
提交 816bced ──▶ C3  ◀── 标签 v1.0.0 指向这里

关键性质：

标签指向一个提交，所以任何版本都能被永久取回（只要该提交存在）
标签是本地对象，git tag 只写进你的本地仓库
必须推送到远端（/git-tag 创建时就会推送），GitHub 才会在 Tags 和 Releases 页显示它
删掉标签不影响提交；提交本身不会被标签"绑定"

两个命令

打标签与推送被合并进同一条命令，读写分离：/git-tag-show 只读，/git-tag 负责写和推。

命令	作用	联网
`/git-tag-show`	列出所有版本（最新在前，含哈希、日期、主题）	否
`/git-tag-show <version>`	查看某个版本：标签信息 + 改动的文件	否
`/git-tag <version> [<remote>]`	打标签并推送到远端（默认 `origin`）	是
`/git-tag --push [version]`	推送已存在的标签；省略版本则推送全部	是

完整工作流

# 1. 确认当前状态，想清楚给哪个提交打版本
/git-status cwd=D:\Githubrep\skills-introduction-to-github
/git-log 5 cwd=D:\Githubrep\skills-introduction-to-github

# 2. 打版本标签并推送（一步完成；省略远端则用 origin）
/git-tag v1.0.0 message=首个可用版本 cwd=D:\Githubrep\skills-introduction-to-github

# 3. 本地确认（列出全部版本）
/git-tag-show cwd=D:\Githubrep\skills-introduction-to-github

# 4. 若推送失败（标签已留在本地），只重推不重复创建
/git-tag --push v1.0.0 cwd=D:\Githubrep\skills-introduction-to-github

# 5. 随时回顾某个版本改了什么
/git-tag-show v1.0.0 cwd=D:\Githubrep\skills-introduction-to-github

参数细节

/git-tag <version>（创建 + 推送）

参数	必填	说明
`<version>`	✅	版本名，如 `v1.0.0`。第一个位置参数
`[<remote>]`	—	推送目标，第二个位置参数，如 `/git-tag v1.0.0 origin`；省略则用默认远端 `origin`。也可写成 `remote=<name>`，两者等价
`message=<text>`	—	给出则创建附注标签（带说明与打标签者信息）；省略则创建轻量标签
`rev=<rev>`	—	给指定提交打标签；省略则给当前 `HEAD` 打
`cwd=<dir>`	—	仓库目录

⚠️ 两个位置参数就是上限，且选项值不能含空格。 解析按空格分词，所以 message=first release 会变成 message=first 加一个游离词 release。命令不会把它当成推送目标——它会拒绝并说明原因（游离词若恰好是已配置的远端名，仍会被当作推送目标，所以给 message 赋值时请勿留空格）：

/git-tag v1.0.0 message=first release        ❌ 报 Unknown remote: release
/git-tag v1.0.0 origin message=first release ❌ 报 Too many arguments
/git-tag v1.0.0 message=first-release        ✅

第二个位置参数会对照 git remote 校验：写成未配置的名字会直接报错并列出可用远端，不会静默推到一个不存在的目标。remote=<name> 等价于第二个位置参数。

版本名规则（同时用内置正则与 git check-ref-format 双重校验）：

规则	例
不能含空格	❌ `v1 0`
不能含 `~ ^ : ? * [ \	`
不能含连续两个点	❌ `v1..0`
不能以 `.` 或 `-` 开头	❌ `-v1`
不能以 `.` 或 `.lock` 结尾	❌ `v1.0.0.lock`
允许斜杠（可做分层命名）	✅ `release/v1.0.0`

/git-tag --push [version]（只推送，不创建）

参数	必填	说明
`[version]`	—	省略则推送全部本地标签（`push --tags`）
`[<remote>]`	—	推送目标，第二个位置参数，默认 `origin`（`remote=<name>` 等价）
`cwd=<dir>`	—	仓库目录

⚠️ --push 之后的第一个词永远是版本名，所以 /git-tag --push origin 是在找名为 origin 的标签。想把全部标签推到某个远端，请写 remote=：

/git-tag --push origin              ❌ 报 "origin is a configured remote, not a tag"
/git-tag --push remote=origin       ✅ 全部标签推到 origin
/git-tag --push v1.0.0 origin       ✅ 只推 v1.0.0 到 origin

执行顺序：先创建（本地、快），再推送。两者各自报告结果；推送失败时标签已经存在 于本地，命令会明确告诉你这一点并给出重推命令，不会让你误以为版本没打成。

与 GitHub Releases 的关系

推送标签后，GitHub 会自动生成 Tags 页：

https://github.com/<用户>/<仓库>/tags

而 Releases 页需要额外一步（在标签基础上附加发布说明、二进制包）：

https://github.com/<用户>/<仓库>/releases

两种做法：

在 GitHub 网页上创建 Release（推荐）——打开 Tags 页，点标签右侧的 "Create release"，填标题和说明即可
等本插件后续支持 —— 创建 Releases 需要调用 GitHub API，目前未实现；本插件的标签命令只负责 git 侧的标签，不涉及 GitHub Releases API

已知限制

没有删除标签的命令。要删请用终端 git tag -d <版本>（本地）或 git push origin --delete <版本>（远端）
不能检出/切换到某个版本。查看用 /git-tag-show <版本>，真要切过去需要 git switch --detach <版本>
不支持签名标签（git tag -s）
没有"只创建不推送"的用法：/git-tag 一律创建后推送。推送失败时标签留在本地，用 /git-tag --push <版本> 单独重推；不需要推送的标签请在终端用 git tag 手动创建
一次 /git-tag --push 不带版本会推送全部标签，注意目标仓库是否需要这么多版本

提供的 agent 工具

与斜杠命令并列，模型也可以自主调用同名能力（git_status、git_commit 等）。两者的区别只是触发者：命令由人输入 / 触发，工具由模型按需调用。

设计说明

不做 force push：git_push 只使用 git 默认的非强制推送，没有提供 force 参数。
输出与语言环境无关：使用 --porcelain、-z、显式 --pretty=format，不依赖 LC_ALL。
凭据：GIT_TERMINAL_PROMPT=0 保证缺少凭据时快速失败而不是挂起。 Windows 上 credential.helper=manager 会从凭据管理器取票，无需交互。
超时：本地操作 120 秒，联网操作 300 秒。
--no-color 只用于接受它的子命令：实测（git 2.55）git diff 与 git log 接受 --no-color，而 git commit、git fetch、git pull、git push 拒绝它并直接以 error: unknown option 'no-color' 失败。切勿给后者添加该参数。
沙箱边界不变：agent 自己的 shell 仍受 workspace-write 限制，本插件没有放宽它，只是把 git 放到了宿主侧执行。

安装

本仓库根目录就是一个可安装的 DSH bundle（根 package.json 声明了 dsh.bundle.patch，指向根 cordis.patch.yml），所以三种方式都可以：

方式 1：从 GitHub 地址安装

DSH GUI 侧边栏 →「插件」页 →「添加插件」，填入仓库地址：

https://github.com/Yangi-252410/dsh-import-repositories

方式 2：从本地目录安装

先把仓库克隆到本机，然后填入该目录的绝对路径：

D:\Githubrep\dsh-git-tools

⚠️ 用正斜杠更稳妥（GUI 输入框里反斜杠可能被转义吃掉）：

D:/Githubrep/dsh-git-tools

方式 3：由 agent 安装

由具备 plugin_manager 工具的会话执行 install_bundle，target 填本地绝对路径。

安装后

项目	说明
生效范围	该 `DSH_HOME` 的这个 profile（同一根下的所有工作区；其他 `DSH_HOME` 不受影响）
生效时机	重启宿主进程 + 新会话（命令集与工具集在会话创建时固定）
出现内容	8 个 agent 工具（`git_status` 等）
斜杠命令	输入 `/git` 列出全部
`missing peer` 警告	可忽略，`@deepseek-ai/*` 由运行时注入

版本对应：package.json 的 version 字段（当前 1.2.3）是插件自身的版本，与仓库的 git 标签（如 v1.2.3）是两套编号——习惯上让它们对齐，但升插件版本不会自动打标签，反之打标签也不会自动改 package.json。查看已发布的版本请到仓库的 Releases 页。

多宿主与更新（重要）

装在哪里由 $DSH_HOME 决定，不由本仓库的位置决定：

$DSH_HOME/profiles/<profile>/          ← 插件的实际安装目录

DSH_HOME 的取值顺序（见 @deepseek-ai/dsh-home-paths）：显式配置 → 环境变量 DSH_HOME → 默认 ~/.dsh。桌面应用会把自己的 harness 目录设为 DSH_HOME；自定义启动脚本（例如 start-dsh-web.cmd 里的 set DSH_HOME=...）可以指向任意目录。

因此：不同的 DSH_HOME 就是不同的安装，彼此完全独立。 同一台机器上很容易同时存在多个：

宿主	`DSH_HOME`（示意）	profile
全局 CLI `dsh web`（环境里没设 `DSH_HOME`）	`~/.dsh`	默认或 `--profile` 指定
DSH 桌面应用	`%APPDATA%\dsh-desktop\harness`	`web`
自定义脚本启动的实例	脚本里 `set DSH_HOME=` 的目录	`--profile` 指定

在某一端安装或更新，其他端不会跟着变；同一个根下的多个进程（例如两个 dsh web）才共享同一份安装。想确认自己在哪一端，就在该端终端执行 "$env:DSH_HOME"，或直接看界面里 /git 有没有命令。

两种安装形态：更新方式不同

形态	出现位置	由谁创建	如何更新
普通 pnpm 安装	`profiles/<p>/node_modules/dsh-git-tools`	CLI `dsh plugin add` 或网页插件页	`dsh plugin --profile <p> rm dsh-git-tools`，再 `add <spec>`，然后重启进程
generation 快照	`profiles/.generations/live/<包名>+<版本>+<哈希>/`，并由 `profiles/<p>/package.json` 的 `pnpm.overrides` 指向它	只有桌面应用（日志形如 `generation-install: … promoted to …`）	在桌面插件页重新安装（源填本地路径最稳）。此时 `dsh plugin add` 只改依赖记录，不会重投影快照，代码不会变

更新步骤（通用）

确认目标端的根："$env:DSH_HOME"；
更新：CLI/网页端用 dsh plugin --profile rm|add <spec>；桌面端用插件页重装；
重启该宿主进程（Ctrl+C 后重新 dsh web，或重启桌面应用）；
新开会话——旧会话永远是旧命令表；
自检（都在 $DSH_HOME/profiles// 内）：
- package.json → dependencies["dsh-git-tools"] 的版本；
- pnpm-lock.yaml → 该包后面的 commit（git+…#<sha>）；
- node_modules/dsh-git-tools/index.js → 是否含新命令（例如 git-tag-show）；
- 界面上 /git 列出的命令。

两个必须知道的坑

git 依赖被 lock 钉死：add github:<owner>/<repo> 之后，pnpm-lock.yaml 记录的是当时解析到的 commit。再 add 同一个 spec 不会换 pin，必须 rm 之后再 add （或显式写 #main / #<sha>），否则会以为"更新了"其实还是旧代码。
填写过的 spec 不会被原样记录：package.json 里存的是解析后的版本号（如 1.2.3），所以只看依赖版本分不出当初是从本地路径还是 GitHub 装的。要看去 profiles//.plugin-manager/logs/*/generation.log（桌面端）或 pnpm-lock.yaml（CLI 端）。

已知限制

仅宿主插件，暂无 Web UI 面板（面板是下一步）。
git_push 依赖已保存在 Windows 凭据管理器中的凭据；没有缓存凭据时会失败并给出 git 的诊断信息。
冲突的 git_pull 会报错并把冲突留给用户解决，不会自动处理。

本仓库创建于 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 会立刻破坏旧版兼容。若确需使用，请在本文档的兼容表中注明最低版本要求。

为什么需要它

提供的工具

工具	作用	是否联网
`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` `/git-pull` `/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

参数	必填	写入位置	作用范围
`name=<name>`	✅	`git config --global user.name`	全机器所有仓库
`email=<email>`	✅	`git config --global user.email`	全机器所有仓库
`remote=<url>`	—	目标仓库的 `origin`（`remote set-url`）	仅该仓库
`cwd=<dir>`	—	—	指定要改远端的仓库

两点必须理解清楚：

身份是全局的，不是临时的。 git config --global 写入 ~/.gitconfig，之后本机所有仓库的提交都用这个名字和邮箱。想只影响单个仓库，请手动用 git config --local。
remote= 必须填 URL，不能填远端名。 填 remote=upstream 会被拒绝，因为这是"远端名"而非地址。它的作用是改变这个仓库推送的目标地址，而不是新建一个远端。

所有校验都在写入之前完成：参数有误时不会有任何副作用（不会写配置、不会改 remote）。

示例：

/git 列出全部命令与用法
/git-status
/git-commit 修复登录跳转
/git-commit --all 批量更新文档
/git-push --set-upstream
/git-pull --rebase
/git-diff --staged

也支持 key=value 形式的选项，用于覆盖默认值：

/git-status cwd=D:\some\other\repo
/git-push remote=upstream branch=release
/git-diff rev=origin/main...HEAD

版本管理（标签）

先理解：版本是什么

git 里没有自动的版本号。每 git commit 一次就产生一个提交，但提交只由哈希（如 9f6af9d）标识，无法用 v1.0.0 这样称呼它。

标签（tag）就是给某个提交起的名字，这才是"版本"：

提交 b237987 ──▶ C1
提交 8985e21 ──▶ C2
提交 816bced ──▶ C3  ◀── 标签 v1.0.0 指向这里

关键性质：

标签指向一个提交，所以任何版本都能被永久取回（只要该提交存在）
标签是本地对象，git tag 只写进你的本地仓库
必须推送到远端（/git-tag 创建时就会推送），GitHub 才会在 Tags 和 Releases 页显示它
删掉标签不影响提交；提交本身不会被标签"绑定"

两个命令

打标签与推送被合并进同一条命令，读写分离：/git-tag-show 只读，/git-tag 负责写和推。

命令	作用	联网
`/git-tag-show`	列出所有版本（最新在前，含哈希、日期、主题）	否
`/git-tag-show <version>`	查看某个版本：标签信息 + 改动的文件	否
`/git-tag <version> [<remote>]`	打标签并推送到远端（默认 `origin`）	是
`/git-tag --push [version]`	推送已存在的标签；省略版本则推送全部	是

完整工作流

# 1. 确认当前状态，想清楚给哪个提交打版本
/git-status cwd=D:\Githubrep\skills-introduction-to-github
/git-log 5 cwd=D:\Githubrep\skills-introduction-to-github

# 2. 打版本标签并推送（一步完成；省略远端则用 origin）
/git-tag v1.0.0 message=首个可用版本 cwd=D:\Githubrep\skills-introduction-to-github

# 3. 本地确认（列出全部版本）
/git-tag-show cwd=D:\Githubrep\skills-introduction-to-github

# 4. 若推送失败（标签已留在本地），只重推不重复创建
/git-tag --push v1.0.0 cwd=D:\Githubrep\skills-introduction-to-github

# 5. 随时回顾某个版本改了什么
/git-tag-show v1.0.0 cwd=D:\Githubrep\skills-introduction-to-github

参数细节

/git-tag <version>（创建 + 推送）

参数	必填	说明
`<version>`	✅	版本名，如 `v1.0.0`。第一个位置参数
`[<remote>]`	—	推送目标，第二个位置参数，如 `/git-tag v1.0.0 origin`；省略则用默认远端 `origin`。也可写成 `remote=<name>`，两者等价
`message=<text>`	—	给出则创建附注标签（带说明与打标签者信息）；省略则创建轻量标签
`rev=<rev>`	—	给指定提交打标签；省略则给当前 `HEAD` 打
`cwd=<dir>`	—	仓库目录

/git-tag v1.0.0 message=first release        ❌ 报 Unknown remote: release
/git-tag v1.0.0 origin message=first release ❌ 报 Too many arguments
/git-tag v1.0.0 message=first-release        ✅

版本名规则（同时用内置正则与 git check-ref-format 双重校验）：

规则	例
不能含空格	❌ `v1 0`
不能含 `~ ^ : ? * [ \	`
不能含连续两个点	❌ `v1..0`
不能以 `.` 或 `-` 开头	❌ `-v1`
不能以 `.` 或 `.lock` 结尾	❌ `v1.0.0.lock`
允许斜杠（可做分层命名）	✅ `release/v1.0.0`

/git-tag --push [version]（只推送，不创建）

参数	必填	说明
`[version]`	—	省略则推送全部本地标签（`push --tags`）
`[<remote>]`	—	推送目标，第二个位置参数，默认 `origin`（`remote=<name>` 等价）
`cwd=<dir>`	—	仓库目录

⚠️ --push 之后的第一个词永远是版本名，所以 /git-tag --push origin 是在找名为 origin 的标签。想把全部标签推到某个远端，请写 remote=：

/git-tag --push origin              ❌ 报 "origin is a configured remote, not a tag"
/git-tag --push remote=origin       ✅ 全部标签推到 origin
/git-tag --push v1.0.0 origin       ✅ 只推 v1.0.0 到 origin

与 GitHub Releases 的关系

推送标签后，GitHub 会自动生成 Tags 页：

https://github.com/<用户>/<仓库>/tags

而 Releases 页需要额外一步（在标签基础上附加发布说明、二进制包）：

https://github.com/<用户>/<仓库>/releases

两种做法：

在 GitHub 网页上创建 Release（推荐）——打开 Tags 页，点标签右侧的 "Create release"，填标题和说明即可
等本插件后续支持 —— 创建 Releases 需要调用 GitHub API，目前未实现；本插件的标签命令只负责 git 侧的标签，不涉及 GitHub Releases API

已知限制

没有删除标签的命令。要删请用终端 git tag -d <版本>（本地）或 git push origin --delete <版本>（远端）
不能检出/切换到某个版本。查看用 /git-tag-show <版本>，真要切过去需要 git switch --detach <版本>
不支持签名标签（git tag -s）
没有"只创建不推送"的用法：/git-tag 一律创建后推送。推送失败时标签留在本地，用 /git-tag --push <版本> 单独重推；不需要推送的标签请在终端用 git tag 手动创建
一次 /git-tag --push 不带版本会推送全部标签，注意目标仓库是否需要这么多版本

提供的 agent 工具

与斜杠命令并列，模型也可以自主调用同名能力（git_status、git_commit 等）。两者的区别只是触发者：命令由人输入 / 触发，工具由模型按需调用。

设计说明

不做 force push：git_push 只使用 git 默认的非强制推送，没有提供 force 参数。
输出与语言环境无关：使用 --porcelain、-z、显式 --pretty=format，不依赖 LC_ALL。
凭据：GIT_TERMINAL_PROMPT=0 保证缺少凭据时快速失败而不是挂起。 Windows 上 credential.helper=manager 会从凭据管理器取票，无需交互。
超时：本地操作 120 秒，联网操作 300 秒。
--no-color 只用于接受它的子命令：实测（git 2.55）git diff 与 git log 接受 --no-color，而 git commit、git fetch、git pull、git push 拒绝它并直接以 error: unknown option 'no-color' 失败。切勿给后者添加该参数。
沙箱边界不变：agent 自己的 shell 仍受 workspace-write 限制，本插件没有放宽它，只是把 git 放到了宿主侧执行。

安装

本仓库根目录就是一个可安装的 DSH bundle（根 package.json 声明了 dsh.bundle.patch，指向根 cordis.patch.yml），所以三种方式都可以：

方式 1：从 GitHub 地址安装

DSH GUI 侧边栏 →「插件」页 →「添加插件」，填入仓库地址：

https://github.com/Yangi-252410/dsh-import-repositories

方式 2：从本地目录安装

先把仓库克隆到本机，然后填入该目录的绝对路径：

D:\Githubrep\dsh-git-tools

⚠️ 用正斜杠更稳妥（GUI 输入框里反斜杠可能被转义吃掉）：

D:/Githubrep/dsh-git-tools

方式 3：由 agent 安装

由具备 plugin_manager 工具的会话执行 install_bundle，target 填本地绝对路径。

安装后

项目	说明
生效范围	该 `DSH_HOME` 的这个 profile（同一根下的所有工作区；其他 `DSH_HOME` 不受影响）
生效时机	重启宿主进程 + 新会话（命令集与工具集在会话创建时固定）
出现内容	8 个 agent 工具（`git_status` 等）
斜杠命令	输入 `/git` 列出全部
`missing peer` 警告	可忽略，`@deepseek-ai/*` 由运行时注入

多宿主与更新（重要）

装在哪里由 $DSH_HOME 决定，不由本仓库的位置决定：

$DSH_HOME/profiles/<profile>/          ← 插件的实际安装目录

因此：不同的 DSH_HOME 就是不同的安装，彼此完全独立。 同一台机器上很容易同时存在多个：

宿主	`DSH_HOME`（示意）	profile
全局 CLI `dsh web`（环境里没设 `DSH_HOME`）	`~/.dsh`	默认或 `--profile` 指定
DSH 桌面应用	`%APPDATA%\dsh-desktop\harness`	`web`
自定义脚本启动的实例	脚本里 `set DSH_HOME=` 的目录	`--profile` 指定

两种安装形态：更新方式不同

形态	出现位置	由谁创建	如何更新
普通 pnpm 安装	`profiles/<p>/node_modules/dsh-git-tools`	CLI `dsh plugin add` 或网页插件页	`dsh plugin --profile <p> rm dsh-git-tools`，再 `add <spec>`，然后重启进程
generation 快照	`profiles/.generations/live/<包名>+<版本>+<哈希>/`，并由 `profiles/<p>/package.json` 的 `pnpm.overrides` 指向它	只有桌面应用（日志形如 `generation-install: … promoted to …`）	在桌面插件页重新安装（源填本地路径最稳）。此时 `dsh plugin add` 只改依赖记录，不会重投影快照，代码不会变

更新步骤（通用）

确认目标端的根："$env:DSH_HOME"；
更新：CLI/网页端用 dsh plugin --profile rm|add <spec>；桌面端用插件页重装；
重启该宿主进程（Ctrl+C 后重新 dsh web，或重启桌面应用）；
新开会话——旧会话永远是旧命令表；
自检（都在 $DSH_HOME/profiles// 内）：
- package.json → dependencies["dsh-git-tools"] 的版本；
- pnpm-lock.yaml → 该包后面的 commit（git+…#<sha>）；
- node_modules/dsh-git-tools/index.js → 是否含新命令（例如 git-tag-show）；
- 界面上 /git 列出的命令。

两个必须知道的坑

git 依赖被 lock 钉死：add github:<owner>/<repo> 之后，pnpm-lock.yaml 记录的是当时解析到的 commit。再 add 同一个 spec 不会换 pin，必须 rm 之后再 add （或显式写 #main / #<sha>），否则会以为"更新了"其实还是旧代码。
填写过的 spec 不会被原样记录：package.json 里存的是解析后的版本号（如 1.2.3），所以只看依赖版本分不出当初是从本地路径还是 GitHub 装的。要看去 profiles//.plugin-manager/logs/*/generation.log（桌面端）或 pnpm-lock.yaml（CLI 端）。

已知限制

仅宿主插件，暂无 Web UI 面板（面板是下一步）。
git_push 依赖已保存在 Windows 凭据管理器中的凭据；没有缓存凭据时会失败并给出 git 的诊断信息。
冲突的 git_pull 会报错并把冲突留给用户解决，不会自动处理。

Yangi-252410/dsh-import-repositories

dsh-git-tools

版本与测试环境

兼容性范围

刻意避开的字段

其他说明

为什么需要它

提供的工具

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

参数类型约定

两个关键参数：cwd 与 remote

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

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

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

版本管理（标签）

先理解：版本是什么

两个命令

完整工作流

参数细节

与 GitHub Releases 的关系

已知限制

提供的 agent 工具

设计说明

安装

方式 1：从 GitHub 地址安装

方式 2：从本地目录安装

方式 3：由 agent 安装

安装后

多宿主与更新（重要）

两种安装形态：更新方式不同

更新步骤（通用）

两个必须知道的坑

已知限制

社区评论

Yangi-252410/dsh-import-repositories

dsh-git-tools

版本与测试环境

兼容性范围

刻意避开的字段

其他说明

为什么需要它

提供的工具

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

参数类型约定

两个关键参数：cwd 与 remote

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

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

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

版本管理（标签）

先理解：版本是什么

两个命令

完整工作流

参数细节

与 GitHub Releases 的关系

已知限制

提供的 agent 工具

设计说明

安装

方式 1：从 GitHub 地址安装

方式 2：从本地目录安装

方式 3：由 agent 安装

安装后

多宿主与更新（重要）

两种安装形态：更新方式不同

更新步骤（通用）

两个必须知道的坑

已知限制

社区评论

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

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

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

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

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

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

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

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