dsh-worktree
Verified@guowenzhang/dsh-worktree · v2.4.0 · Apache-2.0 · Web UI
Git worktree isolation for DeepSeek Harness: create a worktree, register it as its own workspace, and start the session inside it
Install
dsh plugin add @guowenzhang/dsh-worktree Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
@guowenzhang/dsh-worktree
English | 中文
为什么做这个插件
我们的项目由多个仓库组成,也需要并行开发,因此需要用 Git worktree 创建隔离的工作区,避免不同任务的文件改动互相干扰。
这个插件让 DeepSeek Harness(DSH)在新会话界面勾选 worktree,就能创建独立工作区并在其中启动会话;也支持同时创建子模块和嵌套仓库的工作区。
插件列表的显示名称与介绍支持英文和中文,随 Harness 语言设置显示,英文为默认回退;英文名称为去掉 npm scope 的原包名,中文名称说明用途,安装仍使用不变的真实包名。
截图
选择起始分支,勾选 worktree 即可创建工作区并进入新会话。输入框中尚未发送的文字、引用和附件会一起迁移,不会自动发送;创建或切换失败时保留原草稿。

设置页分成三张卡片:最上面的「Git 账号」可以直接连接 GitHub / GitLab / Gitee、扫描本机已有授权,并从这里跳到「Git 账号」页查看项目,中间的「Worktree 设置」配置新会话是否自动开启 worktree、子仓库、扫描层级和存储位置,下面的「自动备份」是改动前保护的开关与变更记录页开关。有效修改自动保存并立即生效,无需「保存」或「恢复默认」按钮。

改动前保护
默认已开启。 AI 第一次改动某个已存在的文件之前,这个文件的当前内容会被复制到工作区外面,所以改坏了、或者被删了,都还能捡回来。
设置页下面的「自动备份」卡片里有三行开关可以随时改:会话文件保护(默认开)、拦截删除命令(默认开)和显示变更记录侧边栏(默认开)。改动即时生效,不需要重启。
副本放在 ~/.agents/file-guard/<会话哈希>/,目录结构和原工作区一致,恢复就是把文件复制回去——不需要任何工具或索引。工作区外的文件(其他目录、其他盘)放在 external/ 下并保留自己的路径。字节级复制,与格式无关:.docx、.pptx、.xlsx 和 .txt 一视同仁。
触发方式有两条:
- 自动:仅
write、edit在写入之前复制目标文件,每个文件约 1 毫秒。read、read_image等只读工具不会创建备份。 - 模型申报:AI 在改那些参数里看不出目标的文件时,应先调用
worktree_backup工具申报路径。它没有范围限制,工作区外与其他盘的路径都接受。返回结果里带着副本的绝对路径,恢复不需要再去检索。
删除类命令会被拦下。 bash / pwsh 里看起来要删文件的命令(rm、del、rd、Remove-Item 等)会被拒绝执行一次,并告诉 AI 先调 worktree_backup 申报目标再重试——因为删除一旦执行就无法恢复。命令里的引号内容不算,所以 echo "rm -rf /" 不会误伤。这一项可以在设置里关掉。
几条要知道的规则:
- 每个文件只备份一次。 同一会话里再改它不会覆盖第一份,因为值得留的正是"被改之前"那一版。
- 只备份已存在的文件。 AI 新建的文件没有"改动前"状态。但下个会话里再改它就会备份——那时它已经存在了。
- 每个会话一份,会话归档时整个删除。 触发就是归档那次写入本身——落盘即清理,普通归档与「停止并归档」一样立即。删除失败会记录会话、目录和原因,并在后续归档相关事件中重试;取消中的工具不会重建已归档会话的备份。只处理宿主运行期间发生的归档,不会追溯删除更早的。
- 没有大小上限。 一份完整副本约等于工作区体积;本机实测 243,529 个文件共 12.72 GB。
- 工作区外与其他盘的写入不在自动范围内,要靠 AI 调用
worktree_backup申报。如果 AI 没申报就改了,那个文件不会被备份——这也是为什么删除命令会被拦下来要它先申报。
需要完整的历史、跨机器或跨时间恢复,仍然应该用 Git 提交;这个功能解决的是"AI 刚刚改坏了、我想要回改动前那一版"。
侧边栏里的变更记录
默认开启。 右侧边栏提供一个「变更记录」页——在侧边栏自己的「开始」页里打开它,页内可用侧栏的刷新快捷键重新读取。它把这个会话及其子会话里被改动或删除的文件平铺成一行一个,不展示目录层次,每行只显示文件路径和一个还原按钮,不显示状态标签;已删除的文件路径加删除线,还原成功后移除删除线。子会话改动过的行会标出所属子会话,避免和本会话的同名文件混淆。
- 已修改指文件内容与副本不一致;已删除指文件已经不在了。内容仍与副本逐字节一致的文件不会列出——没有可还原的东西。
- 还原把那一份副本写回它对应的文件,文件被删过就连目录一起建回来。副本本身保留,所以同一行在之后又被改动时可以再还原一次。
- 对比:点一行的路径打开左右两栏——左边是本次会话首次改动这个文件之前的副本,右边是当前文件,按行对齐。改动的行着色并左右相对;折叠的横条代表一段没有改动的行。两栏各自横向滚动(两边的行长度可能不同),纵向滚动联动,打开时定位到第一处改动。
- 对比读取的是磁盘上的两份文件,不涉及 Git,所以装没装 Git 都一样能用。左侧是"本次会话第一次改动之前"的状态,因此显示的是那之后的所有变化——共享工作区里别的会话改的也会算进去。
- 二进制文件(
.docx、.xlsx、图片)、任一侧超过 2 MiB、或路径已经不是普通文件时,只显示大小而不做逐行对比;还原仍然可用。很大的文本文件只显示对比的开头并注明已截断。 - 每行各自显示结果:还原中、已还原、或宿主拒绝的原因。已还原的行会在下次读取时消失,因为文件此时与副本一致。
- 列表包含当前会话及其派生子会话的副本:子会话的行标出所属会话,还原也走子会话自己的工作目录。会话已停止、不在宿主内存里时照样能读——目录会从该会话持久化的记录里取,所以打开历史会话或已结束的子会话不会报"读取变更记录失败";只有宿主既没有该会话记录、而它又确实留有副本时才拒绝。副本随各自会话的归档删除。
- 设置页的显示变更记录侧边栏开关控制这个页面本身:关掉后不再注册——没有标签类型,侧栏的「开始」页里也没有入口——侧栏只留你选过的页面。关开关之前已经打开的标签会显示宿主的"这类内容还没有可用的查看方式",直到它被关闭。
Git 账号与项目
左侧栏新增一个「Git 账号」页,把这台机器上的 Git 身份集中到一处:登录 GitHub / GitLab(含 gitlab.arcuchi.com 这类自建地址)/ Gitee,设置提交用的全局 user.name 与 user.email,并直接浏览自己的项目。

- 登录方式:在「添加账号」里选择平台、确认服务器地址,再选择访问令牌或 SSH 密钥(不需要注册 OAuth 应用),可先用独立的验证连接按钮测试(只读、不保存)。令牌先由 Host 向平台验证账号身份,通过后才保存——存在 DSH 凭据库里(
$DSH_HOME/.credentials.yaml,仅当前用户可读),不会回传到页面或日志。GitHub 需要能列出仓库的权限(classic token 勾repo;fine-grained 需要 Metadata/Contents 读取),GitLab 需要read_api(或api),Gitee 需要projects与user_info权限。 - SSH 密钥登录:从本机
~/.ssh里选一把私钥(也可手填路径),Host 用一次非交互的ssh -T让平台确认这把钥匙属于哪个登录名;只保存私钥路径,不读取也不上传私钥内容,host key 写在临时文件里,不改你已有的known_hosts。连接检测有 5 秒总预算;GitHub / GitLab 在 22 端口不通时会再试 443 端口(ssh.github.com/altssh.gitlab.com)。若网络整体阻断 SSH,添加仍会保存为未验证账号(用密钥文件名占位,之后在同一网络添加同一密钥即可升级验证),Git 拉取/推送等网络恢复后可用。加密的私钥需要先加载到ssh-agent。SSH 账号不能列项目——项目列表需要同一主机上的访问令牌账号。 - 扫描本机已有授权:一次点击读取 Windows 凭据管理器里的
git:凭据、~/.git-credentials、gh auth token和GITEE_TOKEN等环境变量,并检查~/.ssh/config里明确绑定了已知平台的 SSH 密钥;每个候选都要通过平台验证才自动添加,重复账号(同平台、同服务器、同登录名、同登录方式)会跳过或刷新。扫描完成只弹一条普通通知,写出新增账号的登录名,不再铺一张结果卡片;未与 host 配对的 SSH 密钥仍只做提示,可在「添加账号」里手动选择。 - Git 身份:读取并写回全局 Git 配置;提交用的名称与邮箱对所有仓库生效。留空一个字段表示清除该键(
git config --global --unset)。Git 未安装或全局配置读不出来时,这一栏会说明原因并禁用输入。 - 我的项目:选中一个账号后按最近活动列出它的项目,可搜索、翻页,每行显示可见性、默认分支和更新时间,并提供复制 HTTPS 克隆地址与在浏览器打开。本版只读:不克隆、不创建 worktree;SSH 账号在项目区会直接说明为什么不能列出项目。每个账号单独一张小卡片,连接多个账号时一眼可分。

自建 GitLab 使用自签证书时,Host 的 Node 运行环境需要能信任该证书,否则验证与项目列表会报网络错误。扫描只在当前用户上下文读取凭据,不会弹出系统授权框或触发交互式登录。
连接设置也在设置 → 文件备份页的第一张卡片里,不用先打开「Git 账号」页就能添加账号、扫描本机授权或移除账号;卡片底部的「在『Git 账号』页查看项目」会直接切到项目列表。

安装
npx @deepseek-ai/dsh plugin --profile web add @guowenzhang/dsh-worktree
安装后重启 DSH。宿主需已安装 Git,且能通过 PATH 找到它。
注意事项
升级到 2.x:已移除面向模型的 Worktree 工具,请通过新会话控件创建;归档通知可能清理没有未提交改动的 worktree。调用旧模型工具的集成需要更新。
多仓库支持默认关闭:在设置中打开「创建子仓库」,按目录结构调整扫描层级(默认 1 层)。子模块按父仓库记录的提交检出,处于 detached HEAD;独立嵌套仓库会创建新分支。
未提交改动不会带入新工作区:worktree 从所选分支的提交创建,分支名自动生成。
默认存放在工作区内:路径为
<工作区>/.agents/worktree/<分支>。建议将.agents/worktree/加入 Git 忽略规则,或选择「仓库同级」「用户目录」。新会话可以自动开 worktree:打开「新会话默认开启 worktree」后,仓库里的第一个空白会话会自己建一个 checkout 并搬进去,不再询问。默认关闭。
归档可能清理 worktree:归档写入落盘即触发删除尝试(普通归档与「停止并归档」一样立即);有未提交改动时保留,分支不会删除。关闭宿主不会清理,手动移除工作区记录也不会删除文件。
清理前确认没有其他会话使用该目录:删除 worktree 不检查仍在运行的会话。
更多安装方式、配置与开发说明见 AGENTS.md。
许可
Apache-2.0,另见 NOTICE。