dsh-worktree-switch
Verifieddsh-worktree-switch · v0.5.1 · MIT · Web UI
A New Session switch that puts the conversation into a throwaway Git worktree under the project's worktree pool (`<project>/.dsh/worktrees` by default), plus a panel to inspect and discard the copies.
Install
dsh plugin add dsh-worktree-switch Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-worktree-switch
在新会话屏幕的输入框工具行里放一个 Worktree 开关。默认打开(按项目的隔离默认):
打开时立刻在 <项目根>/.dsh/worktrees/<名字> 建一份仓库副本,并把这条会话的工作
目录切进去;在发出第一条消息之前再关掉,会话会被切回项目目录,开关自己刚建的干净
副本也一并删掉——关掉就是撤销这次隔离。副本不会自动消失、也不会自动合并,用户可以
在 Worktrees 面板里把它丢弃,或者自己把分支合回源仓库。会话在副本里时,宿主半还会
给模型一条工作区说明,并拒绝把 git 指向主检出的 shell 调用(可关)。
新建副本默认以创建前刚拉取到的 origin/<默认分支> 为基点,而不是主检出的本地 HEAD
(见「创建基点」)。语义基线与有意偏离见
ADR-0005。
「关掉」现在只做撤销,不叫回收:只有开关为这条会话创建、没有产生提交、也没有未提交
改动的副本,才会在离开时被删掉(检出与分支一起);有内容的副本保留并给一次性提示,归属
不是这条会话的副本同样保留,但只在开关的 hover 里说明。归属记在副本自己的 Git admin dir
里,宿主重启后仍然可证;会话头部常驻 ⎇ 分支名 badge,面板新增「遗留分支」分组。开关
位置是会话状态、项目默认只决定新会话,见
ADR-0007;离开即撤销的取舍见
ADR-0006。
它做什么
- 开关(
conversation.input.left槽,只在空白新会话的 hero 上出现):显示本会话 当前的副本状态——检查中 / 关闭 / 创建中 / 离开中 / 就绪(显示名字)/ 失败(显示原因 + 重试)/ 不可用(项目不是 Git 仓库)。开关位置表示这条会话在哪里运行:会话在副本里 时恒为开;不在副本时等于这个项目的隔离默认(新会话要不要隔离,按项目记忆)。项目 默认不再决定一条已经在副本里的会话该不该搬走。会话在副本里、项目隔离默认为关时,hover 说明「本会话在副本里运行;这个项目的新会话从源检出开始」。 - 创建发生在开关打开的那一刻,早于第一条消息;关闭(拨回)把会话切回项目目录;
只有开关为这条会话创建、仍在创建基点、也没有未提交改动的副本会被撤销(检出和分支一起
删)。有提交或改动的副本留在池里,开关的 hover 带上保留原因,界面顶部给一次性提示并
提供「打开面板」;归属不是本会话的副本(例如
/new继承来的)同样留下,但只在 hover 里说明,不弹提示。hover 的离开失败提示收窄成「拨回后没能离开」,只在有错误时出现。 副本默认从创建前刚拉取到的origin/<默认分支>起;baseRef: 'head'或远端取不到时回退为本地HEAD(见「创建基点」)。副本名 = 分支名 = 池内 目录名,形如quiet-harbor-3fa9,由插件生成,短且唯一。 - 归属记在副本里:创建成功后,插件往该副本自己的 Git admin dir
(
.git/worktrees/<名字>/dsh-worktree-switch.json)写一条{ sessionId, createdAt, baseCommit }。它随副本删除自动消失,不进工作区、不产生未跟踪 文件,宿主重启后仍然读得到。升级前就存在的副本没有标记,一律按「归属不明」保留:不补写、 不猜。副本被手工改成 detached 时,撤销只移除检出,永不删任何分支。 - 会话头部 badge:非空白会话的头部常驻
⎇ 分支名(conversation.session.header.utilities)。hover 给副本绝对路径、仓库根与副本内未提交 数;它订阅会话当前工作目录的变化,cd出去就消失,副本被建出来也会自己出现。点击打开 Worktrees 面板并高亮当前副本。空白 hero 与面板页不显示:那两处分别由开关和面板本身表达 同一件事。 - 创建失败不回落:提示词不发送,错误就地显示。从检查开始、到副本就绪之前、离开副本
的过程中(或失败之后),开关通过
ctx.conversation.blocks把该会话的输入框置为"暂停 发送";重试成功、关掉开关(确认不要隔离)或副本就绪时才解除。关掉开关是明确的退出 方式——它表示"这条会话就在原目录里跑",而不是假装隔离成功。 - 会话范围说明:会话在副本里时,宿主半跟着每轮请求给模型补一条上下文(紧跟工作目录那
行):当前目录是
<项目>的 linked worktree 副本,git 与文件操作在副本里做,主检出是源。 它会随恢复会话、每次进/出副本重新推导,回到项目目录后自动消失。这是提示,不是权限 边界——真正的写隔离仍取决于沙箱根(见「已知边界」)。 - 主检出守卫:会话在副本里时,
tools/pre-execute会拦下“把 git 指向主检出”的 bash 调用(命令里出现主检出的绝对路径,或workdir落在主检出里),拒绝原因直接告诉模型 在副本里该怎么做(git fetch origin main+merge/rebase)。这是启发式拦截,不是 沙箱边界:cd ..之类的相对逃逸、shell 变量展开不在它的覆盖范围内;配置guardSourceCheckout: false可关掉。拦下的是 git,主检出里的普通写入仍然由沙箱放行。 - 面板(侧边栏条目 + 自己的页面):按项目列出该仓库的所有 linked worktree(包括
手工
git worktree add出来的),含名字、分支、路径、创建时间和未提交改动数;丢弃 需要第二次确认,且有未提交改动时拒绝丢弃并说明原因。目录被手工删掉、Git 注册还在 的副本标成「目录已丢失」,走同一套丢弃(先删分支、再worktree prune,删不掉就报错而 不悄悄 prune)。detached 副本只展示,丢弃只移除检出、永不删分支。 - 遗留分支:每份副本之外,面板单独成组列出「名字符合生成格式(
<词>-<词>-<4位hex>)、 但已没有任何 checkout」的分支,含提交数、最近提交 subject 与时间;删除需要第二次确认, 且只删分支。普通 feature 分支、以及仍被 checkout 的分支永远不会出现在这一组。 - 当前副本:面板按会话快照里当前主视图的那条会话推导「我在副本里」,给它高亮;不新增 宿主事件。侧边栏入口在有东西要清理时显示计数。
- 计数口径:入口计数 = 遗留分支数 + 本次宿主生命周期内被保留的副本数(有内容而保留、 或删除失败后留在磁盘上的那一份)。归属别的会话、只在离开时留下来的副本不计入——它不是 遗留。宿主重启后后者不可知,计数退化为只数遗留分支——这是有意说出来的诚实下限,不是 bug。
- 会话身份不变:会话仍然建在源项目的工作区里,起始目录不变,插件只改会话的工作 目录(一条持久化事件,重开会话仍然生效)。
/new 继承的副本
/new(= /clear,由 dsh-new-session 提供)在原地
开一段新对话:新会话沿用当前会话的工作目录。会话在副本里时,新会话就继承同一份副本,
既不会另建一份,也不会因为项目的隔离默认是关而被搬回源检出。开关跟着工作目录投影重查:
/new 继承、离开、宿主把会话搬回源检出,位置都会在重查后对齐事实;空白会话若因外部原因
被搬回源检出、而隔离默认仍为开,会重新补建一份副本(只在还没发第一条消息时)。
继承来的副本仍归创建它的会话所有。在新会话里拨回开关只是普通离开:会话回到源检出,
副本留在磁盘上,不弹一次性提示,也不计入侧边栏的清理计数;hover 里那句「开关不删这份
副本:它不是为这条会话建的」说明原因。这条跨插件前提也记在 dsh-new-session 的 README 里。
安装
# 本地 checkout
dsh plugin --profile web add /home/ubuntu/code/deepseek-plugins/packages/dsh-worktree-switch
dsh --profile web --dump-config # 应能看到 "# == dsh-worktree-switch" 和 "# == worktree" 两层
cordis.patch.yml 会插入两行:@deepseek-ai/dsh-experimental-worktree(提供
ctx.worktrees,行 id 特意用 worktree,与官方 tool-worktree bundle 的行 id 相同,避免
重复注册服务)和本插件自己。装完需要重启正在运行的 Web profile。
构建产物由 prepare 脚本(tsdown)产出;改完源码后重新 pnpm --filter dsh-worktree-switch build
即可。外部安装的插件不在 pnpm run dev:web 的监视范围内,client-hmr 每 500ms 轮询
lib/client.js,重新构建后页面会自动换上新的浏览器半。
在 GUI 里走一遍
- 重启正在跑的 Web profile。
- 新建会话(hero 屏幕):输入框工具行最左侧出现 Worktree 开关;默认打开的项会先显示 "检查中",随即"正在创建",然后显示这条会话的副本名。
- 按回车发消息:助手的工作目录已经是
<项目根>/.dsh/worktrees/<名字>,源仓库的 未提交内容留在原地;会话头部出现常驻的⎇ 分支名,hover 能核对路径、仓库根和未提交数。 - 侧边栏出现 Worktree 入口:打开后按项目列出磁盘上的副本与遗留分支,含创建时间、 未提交改动、提交数等;当前会话所在的副本高亮。有东西要清理时入口会带计数。
- 想丢弃一份副本:点两次 Discard(第二次是确认);有未提交改动时按钮禁用并说明原因。 遗留分支同样点两次删除;目录已丢失的副本行标「目录已丢失」,走同一套丢弃。
- 开关只在空白会话上出现:发第一条消息之前关掉,会把会话切回项目目录,并撤销开关刚建的
空副本;若副本里有提交或改动,副本保留,开关 hover 说明原因,页面顶部给一次性提示与
「打开面板」;归属不是本会话的副本(比如从副本里
/new出来的新会话)只回源检出、 副本留在原处,不弹提示。发过消息之后开关消失,副本留在池里,由面板丢弃。拨开关同时 记住这个项目的隔离默认。
配置
副本目录
副本目录(池)由 cordis.patch.yml 里那一行 worktree 决定,也就是 harness
worktree 服务自己的 directory 选项——本插件不另存一份设置,status / list /
discard 都按“仓库里有哪些 linked worktree”去认副本,所以服务把池挪到哪里,插件就
跟到哪里。本包默认是 .dsh/worktrees。
要改成别的目录,在 profile 自己的 patch 层覆盖同一行即可(后层按行 id 覆盖,整块
config 替换):
# ~/.dsh/profiles/web/cordis.patch.yml
- id: worktree
name: '@deepseek-ai/dsh-experimental-worktree'
config:
directory: worktrees # 相对项目根;这里就会落在 <项目根>/worktrees/<名字>
两条硬约束:
- 必须留在项目根内部。会话的沙箱写入边界是不可变的会话起始目录,池在项目根外时 创建副本会被直接拒绝。
- 目录对每个项目都生效(是相对路径,不是在某个绝对位置开池)。若想按项目不同,只能 在项目里放不同的 profile——目前没做这种粒度。
行 id 撞车:dsh 0.2.2 的 Forge bundle(@deepseek-ai/dsh-experimental-forge-bundle)
也插入一行 id: worktree。Loader 按行 id 只留一条、后层覆盖,所以本包的
directory: '.dsh/worktrees' 只在本包的层排在那份 bundle 之后时才生效——默认情况正是
如此(profile 先列宿主 bundle,再列装进来的插件)。如果你手动调整了 bundle 顺序,请在
profile 的 patch 层里按上面的写法重新声明 directory,否则池会静默退回 harness 的默认
目录(.agents/worktrees)。这条只影响目录位置,开关、面板与丢弃逻辑都按服务实际用的
池子工作。
改完重启 profile 生效。已经在旧目录里的副本不会消失:面板列的是仓库的所有 linked worktree,所以新旧目录的副本都会出现,可以照常丢弃。
开关默认与基点
| 字段 | 默认 | 含义 |
|---|---|---|
defaultEnabled |
true |
用户从未在这个项目上拨过开关时,新会话是否默认隔离。用户拨过一次后,按项目记在浏览器 localStorage 里,优于此项。 |
guardSourceCheckout |
true |
会话在副本里时,用 tools/pre-execute 拒绝把 git 指向主检出的 bash 调用。关掉就只剩提示。 |
baseRef |
'fresh' |
创建副本前从 origin 拉取默认分支作为基点;head 则直接基于本地 HEAD、不联网。 |
创建基点
新建的副本默认不从本地 HEAD 起。开关真正要建副本之前(拨开开关、且只有那一刻),
宿主半只从 origin 拉一个分支——默认分支。解析顺序是 refs/remotes/origin/HEAD →
main → master,拉取带 5 秒超时,副本以拉取到的那个提交为基点。只拉这一个分支,其他
分支和 tag 都不动。
baseRef默认是fresh:如上所述。主检出落后于远端时,新会话仍从团队已经推上来的 代码开始。baseRef: 'head':完全跳过默认分支解析与 fetch,直接基于主检出的本地HEAD,不联网。 这是「把 feature 分支里未推送的工作带进副本」的逃生门,也是离线时的确定行为。
回退一律不阻断创建:没有 origin 远端、远端没有可识别的默认分支、fetch 失败或超时,
都静默回退到本地 HEAD,副本照建。唯一会显式说出来的是「有远端、找到了默认分支、fetch 没
成功」这一种:开关的 hover 提示里会多一句「基点:本地 HEAD(远端未取到)」,开关本身的
文案不变。
只有「即将创建副本」会联网:已经在副本里的会话、status、release、discard 都不 fetch。
在 profile 自己的 patch 层设置(和 defaultEnabled 一样,没有 GUI 控件):
# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-worktree-switch
name: dsh-worktree-switch
config:
baseRef: 'head'
baseRef 只接受 fresh / head 两个字面量,写成别的会让插件在挂载时失败、profile 起不
来,而不是静默选另一个基点。
目录与命名
<项目根>/.dsh/worktrees/
├─ .gitignore # worktree 服务建池时写入(内容 "*"),池本身不进版本库
└─ quiet-harbor-3fa9/ # 一份副本;同名分支 quiet-harbor-3fa9
名字不带 wt/ 前缀:池路径已经把“这是什么”说清楚了。名字、分支、目录三者是同一个
字符串,git branch 里看到的名字就是磁盘上的目录名。
已知边界(接受,不修)
- 副本里看不到未跟踪的项目本地资产:
.dsh/skills、.agents/skills、AGENTS.local.md/CLAUDE.local.md。被 git 跟踪的AGENTS.md照常可见。 - 会话记录里的起始目录仍指向源项目根;任何信任该字段的功能("在终端打开"、按目录 定位文件)显示的是源项目根,而不是副本。这是刻意的:沙箱边界与侧边栏归属都依赖它。
- 沙箱边界仍是源项目根,因此副本不是"写隔离",它隔离的是提交与未提交改动: 助手在副本里改的文件不会落到源检出的工作树里,但同一会话仍可写源项目根下的文件。 主检出守卫只覆盖 bash 里明显指向主检出的 git 调用,是提示之外的兜底,不是权限。
- 不自动合并、不自动回收、不支持多仓库、不识别旧插件的
.worktree-space/目录。 - 不追溯旧副本:升级前留下的副本没有归属标记,离开时按
not-owned保留——只在开关的 hover 里说明「开关不删这份副本:它不是为这条会话建的」,需要时在面板里手动丢弃。插件 不会为了「修好这件事」而猜。 - 离开别人的副本不算遗留:
/new继承来的、其他会话创建的副本,离开时返回keptReason: 'not-owned'——会话回到源检出,副本留在磁盘上,不弹一次性提示、不计入清理 计数,只在开关的 hover 里说明。它仍出现在面板里,由拥有它的会话或显式丢弃处理。 - 开关位置是会话状态:项目的隔离默认只决定新会话要不要隔离;已经在副本里的会话只能由
用户拨回离开,挂载与
/new都不会搬动它。 - 计数会退化:「被保留的副本」只是本次宿主生命周期内的知识;宿主重启后入口计数只剩 遗留分支可数(面板与本节都写明,避免用户以为计数一直准)。
- detached 副本永远不会被开关自动删掉:只展示、只允许显式丢弃检出,且不删任何分支。 这比「猜一个分支名去删」安全,代价是用户要自己回收它。
- 归属标记在
.git/worktrees/里:不进版本库、不进工作区、不产生未跟踪文件;但用户rm -rf掉副本目录后,标记要等 Git 注册被 prune 才消失,那期间面板会把该行标成 「目录已丢失」,走同一套清理。
实现
宿主半(src/index.ts)做三件事:拿 cordis.patch.yml 挂上的 ctx.worktrees 和
ctx.sessionController,把下面七个动词注册成 /api/dsh-worktree-switch/<verb> 上的精确
Fetch 路由(src/host/routes.ts),说 client-request / server-response 信封;另注册一条
systemPrompt.context(worktree-switch:scope),内容来自 SessionScopeRegistry,由这些
动词、agent/created 和每次组装时的目录校验共同维护。「归属」这条记录由
src/host/ownership.ts 读写,落在副本自己的 Git admin dir 里。
| 动词 | 入参 | 行为 |
|---|---|---|
status |
{ sessionId } |
解析仓库根、本会话是否已在某个 linked worktree 里、源仓库未提交改动数 |
prepare |
{ sessionId } |
幂等;必要时经 ctx.worktrees.create 建副本并切目录,同名冲突自动换名重试 |
release |
{ sessionId } |
把会话切回项目目录;仅在「有归属 + 仍在基点 + 工作区干净」时撤销副本(检出 + 分支),否则保留并返回 keptReason(dirty / not-owned)与原因。只有有内容(dirty)的保留,以及删除失败后抛错、副本留在磁盘上的那一次,登记为「宿主保留的副本」;not-owned 的离开不登记、不计入清理计数。删除失败抛错,不吞成「保留」 |
scope |
{ sessionId } |
轻量回答「这条会话在副本里吗」:先读宿主内存里按会话记录的副本,读不到再对当前目录做一次检测;不读源仓库 status、不切目录 |
list |
{ path } |
列出该仓库除主检出外的所有 linked worktree(名字/分支/路径/创建时间/改动数/prunable),外加遗留分支(提交数/最近提交/时间)与本次宿主保留的副本数(有内容与删除失败的保留) |
discard |
{ path, name } |
干净才删:git worktree remove + git branch -D;prunable 行先删分支再 prune;detached 副本只移除检出;改动非空则拒绝 |
discardBranch |
{ path, branch } |
只删一个遗留分支:要求名字是生成格式、且不在任何 checkout 的 HEAD 上;已删过再删也算成功 |
创建走 harness 的 worktree 服务(沿用它的沙箱、filter 覆盖和失败语义);status/list/
discard 是人在界面上的显式动作,用 ctx.subprocess 直接跑 Git,与会安装的
dsh-worktree-space 一致。浏览器半(src/client/index.tsx)注册五个槽:开关、keyed
main 面板页、sidebar.panellist 入口与计数、conversation.session.header.utilities 的
⎇ badge、shell.overlay 的一次性提示;状态机在 src/client/state.ts,不依赖 React。
校验
pnpm --filter dsh-worktree-switch typecheck
pnpm --filter dsh-worktree-switch test
pnpm build # 构建全部包并校验 exports / bundle patch 文件存在
测试有三条接缝:宿主半的七个动词(真实临时 Git 仓库 + 真实服务,tests/host.spec.ts)、
浏览器半的槽注册与渲染(真实 SlotRegistry + 假 connection/conversation,
tests/*.client.spec.tsx),以及插件公开的配置契约(tests/config.spec.ts:baseRef
只接受 fresh / head)。不断言内部 Git 调用次数,也不测上游 worktree 服务自己的
Git 细节。
浏览器半为什么自带一个 tests/client-harness.ts 而不是用官方的
@deepseek-ai/dsh-client-test-runtime:该包 0.2.1-rc.5 发布版会 import
@deepseek-ai/dsh-client-ui-renderer/src/...,而发布产物里没有 src/,装上也跑不起来。
为此测试侧另有两处上游缺口的补丁,都只影响开发依赖:dsh-client-store 的运行依赖
zustand/immer 在发布清单里只写在 devDependencies(所以本包自己也装了这两个);
dsh-client-ui-primitives 同样漏声明了整条工具链,测试里把它 mock 到实际渲染到的
Tooltip。
发布
prepare 会在 npm 打包前跑 tsdown,所以发布出去的是预构建产物,用户
dsh plugin add dsh-worktree-switch 无需构建授权:
pnpm --filter dsh-worktree-switch publish --access public
包元数据里的 repository.directory 指向本仓库的这个子目录,收录到社区目录
(awesome-dsh-plugin / dsh-market)后 npm 包会自动关联回仓库;收录步骤见仓库根
README 的「社区目录」一节。