工作树隔离 zhang-guo-wen/dsh-worktree

@guowenzhang/dsh-worktree

背景：DeepSeek Harness

DeepSeek Harness（dsh）是 DeepSeek AI 开源的 agent harness，几乎所有能力都是 Cordis 插件。它处于 developer preview 阶段、迭代很快，会有破坏性变更（文档站，0.1.7-alpha.）；本插件是独立第三方包，@deepseek-ai/ 运行时从宿主解析。

这个插件解决什么问题

DSH 的会话工作目录在创建时冻结，想在独立 Git worktree 里干活就得手工建 checkout 再开会话；本插件在新会话界面勾一下就做完这两件事。

截图

新会话屏幕上的 worktree 胶囊在 选择工作区 / 模式 那一行右端勾上 worktree，就建好 checkout 并把会话开在里面。

Worktree 设置页设置 → Worktree：创建子仓库、扫描层级、worktree 存储位置，右下角是 恢复默认 / 保存。

安装

npx @deepseek-ai/dsh plugin --profile web add @guowenzhang/dsh-worktree

来自 npm 官方源：。装完重启宿主；本地目录开发安装、git 源与排查见 AGENTS.md。

用法

在新 worktree 里开始会话

在 Git 仓库里开新会话时，选择工作区 / 模式 那一行的右端出现一个胶囊：⑂ ▾ │ ☐ worktree。左边是本地分支下拉——新分支从哪个本地分支开始，默认是当前会话所在 checkout 的分支，取不到就是 HEAD。列表在打开菜单时才去读，按最近提交排序，只列 refs/heads：远端分支或 tag 会让 git worktree add 悄悄进 detached HEAD，所以不给选。界面不提供分支名输入。

勾上 worktree 那一段就是全部动作，它按顺序跑四步：用 git worktree add -b 在主仓库上建 checkout（会话即使已经在某个 linked worktree 里，也会回溯到主仓库）；把新目录注册成一个工作区；用新目录作为 meta.cwd 启动会话；把该会话挂进工作区的账本——会话只通过这本账归属工作区，不挂的话它在 GUI 里是“未分组”，选择工作区 也没有名字可显示。之后浏览器再刷新一次会话目录并切到该会话：新会话是 Host 在客户端 Session Controller 之外创建的，不先拉一次目录，导航会以 unknown session 拒绝这个 id。

勾选是单向的：勾上就执行创建并开启会话，没有任何路径把它取消勾选。失败分两种。Host 拒绝（分支名冲突、不是仓库等）什么都没建：控件回到未勾选并显示原因，再勾是重试。建好了但没切过去（导航失败）时控件记住那个新会话，再勾是把它打开，不会建第二个 checkout。

每个会话独立、且不可更改：会话的工作目录是创建时冻结的头字段，所以这个控件只在会话还是空白（没跑过第一轮）时出现。这是设计约束，不是缺陷——想换目录只能新开会话。

控件什么时候出现

控件状态跟着会话和它所在目录走：

| 状态 | 控件 | 原因 |
| 空白会话，目录在主 checkout 里 | 可操作 | 选择还开着 |
| 会话已在某个 linked worktree 里 | 显示但锁住（base + 已勾选） | 它已经隔离好了；再给一次会在一个 checkout 里套出下一个 |
| 会话已跑过至少一轮 | 隐藏 | header.cwd 已冻结，Host 会拒绝 |
| 目录不是 Git 仓库 | 隐藏 | 没有可隔离的仓库 |

锁住的控件不提供任何更改——两段都禁用、chevron 收起，悬停提示当前 checkout 实际所在的分支。页面刷新会丢掉“这个 checkout 是我建的”这层记忆，所以锁住的控件显示该 checkout 自己的分支；分支名本身就是 -，来源照样看得出来。

选择 checkout 存放位置

设置 → Worktree，标题「worktree 配置」，三行，都是设置列一贯的左标签 / 右控件式：

- 创建子仓库 —— 默认关。打开表示 checkout 记录的子模块、以及嵌套在它里面的仓库都跟着一起创建；关闭表示只建父仓库自己。
- 扫描层级 —— 从仓库根往下找嵌套仓库的目录层数，默认 1（直接子目录）。未打开创建子仓库前这一行是禁用的。
- worktree 存储位置 —— 工作区内 / 仓库同级 / 用户目录，该行说明文字显示所选位置解析出的目录。

右下角 [恢复默认] [保存] 放在一起，保存即生效、不需要重启宿主——新策略会装回正在运行的服务实例上。离开页面会丢弃所有暂存改动。

| 值 | 界面 | 目录 |
| agents（默认） | 工作区内 | /.agents/worktree/，出现在工作区树里 |
| sibling | 仓库同级 | -wt-，建在仓库旁边，不进工作区树 |
| home | 用户目录 | ~/.agents/worktree/，整台机器共用 |

让模型操作 checkout

三个模型工具消费同一个服务，都不开会话——模型建出 checkout，由产品自己的新会话流程把会话放进去。worktree_create 建一个 linked checkout 并返回它的路径；worktree_list 列出该仓库的 checkout，主 checkout 在最前；worktree_remove 删除其中一个，拒绝主 checkout，也拒绝任何带未提交改动的 checkout，除非显式传 force。

// 一个会话里
worktree_create({ branch: 'fix/123' })
worktree_list()
worktree_remove({ path: '/abs/path' })

分支名

界面不收分支名，由 Host 推导：所选 base 分支名（/ 换成 -）+ 6 位随机数字，例如 dev-482913；base 不是本地分支（HEAD、某个 SHA、origin/x）时用 worktree-。base 本身不落盘，但照样看得见——工作区标题、checkout 目录、git branch 都带着这个生成出来的名字。

注意事项

- 不自动清理。 会话结束后 worktree 不会自动删除：未提交的工作绝不该被静默丢弃，删除只能显式发起。
- 删除不检查 live 会话。 删除一个仍有会话在跑的 checkout 目前不做拦截。
- 6 位随机后缀会撞名。 同一个 base 的两个 checkout 取自同一个空间，约百万分之一会撞上；那时 git worktree add 会直接报错，再勾一次即可。
- 默认位置会出现在 git status 里。 agents 把 checkout 放在 /.agents/worktree/ 下，是主 checkout 里的未跟踪目录。把 .agents/worktree/ 加进 .gitignore / .git/info/exclude，或改用 仓库同级 / 用户目录。
- 「用户目录」是整机共享的位置。 ~/.agents/worktree/ 不属于任何工作区：几个仓库的 checkout 会并排放在一起；它落在某个仓库里时，那里也需要你自己加 .gitignore。
- 不能从界面给分支起名。 分支在工作区标题里可见；需要指定名字就用 worktree_create 的 branch。
- 子模块是 detached HEAD，这是设计。 这是 gitlink 的语义，不是缺陷；要“带分支的子仓库”就用独立嵌套仓库。
- 只有真正的 .git 目录才算嵌套仓库。 一个子目录如果自己是别的仓库的 linked worktree（.git 是文件），或者是个子模块，都不会被镜像成新分支。
- 本地路径的子模块需要 Git 的 file 传输许可。 protocol.file.allow 是 Git 自己的安全开关，本插件不覆盖它：仓库的 .gitmodules 指向本地路径时，得由 git 配置（全局或仓库级）放行，否则创建会带着 Git 的原话失败并整体回滚。子模块用 https/ssh 时不受影响。
- 删 checkout 不会删分支。 worktree 的分支——包括为嵌套仓库建的、活在它们自己仓库里的那些——都会在删除后留下，和工作区自己的分支一样。
- 记忆共享，文件与授权不共享。 dsh-memory / dsh-claude-compat 会把 linked worktree 的 {project} 回溯到主仓库，所以同一仓库的所有 worktree 共享一份记忆，而文件与沙箱授权各自独立。这是有意的：隔离的是文件和授权，共享的是知识与上下文。

许可

插件本体是 Apache-2.0——见 LICENSE 与 NOTICE。

它不包含 DeepSeek Harness 的源码：harness 包是 peer 依赖，运行时从宿主解析。

延伸阅读

- AGENTS.md —— 安装变体、构建、组合接线、生效语义、发版步骤、设计决策、排查与测试运行方式。
- dsh-memory —— 姊妹记忆插件，它的 {project} 解析让同一仓库的所有 worktree 共享一份记忆。
- DeepSeek Harness 文档。