前言¶
在 DeepSeek Harness（DSH）里对同一个仓库开多个会话时，常见做法是切分支、再克隆一份仓库，或者直接在主 checkout 里改——主工作区容易被未提交改动污染，并行任务也更容易互相踩脚。Harness 本身提供 worktree 相关能力；dsh-worktree-toggle 把「把这次会话隔离出去」收成 composer 工具栏里的一次点击：新建 linked checkout、会话工作目录迁过去，主 checkout 保持原样。
下面介绍插件定位、能力、安装与用法，以及空闲清理与限制。事实以 GitHub 仓库 README 与 package.json 为准。
这是什么¶
dsh-worktree-toggle 是 DSH 的客户端插件，维护者为 wzciczw。简介（与目录页一致）：One-click git worktree launcher for DeepSeek Harness: start a session in a fresh worktree, with automatic cleanup of idle worktrees.
一句话：在 composer 分支 pill 旁增加一个固定宽度的 Worktree 开关；在符合条件的新会话里点开，Harness 的 worktrees 服务创建分支与 checkout，会话目录迁入 <repo>/.agents/worktrees/，后续工具、编辑、命令都在新 checkout 里执行。
核心功能¶
一键切换，无需手敲 git¶
- 开关出现在 composer 工具行，紧挨分支 pill；仅对 git 仓库里、尚未发出首条消息的空会话展示。
- 点击后不跑额外的预检 git 流程，等待主要来自 git 自身 checkout；UI 立即显示进度，不阻塞 composer 输入。
界面与状态¶
- 22 px 芯片，状态切换不改变宽度，不在输入区打印分支或 worktree 名，单行布局不变。
- 会话已在 worktree 内运行时，开关为勾选且只读；tooltip 可看到 checkout 路径。
与内置 worktree 一致的安全边界¶
创建走 Harness worktrees 服务，沿用现有 sandbox 与文件策略；checkout 保留策略与内置 create_worktree 工具一致。
空闲 worktree 自动清理¶
无会话活动达 3 天 的 worktree 会被清理以回收磁盘；分支保留，删除分两阶段，避免刚启动的 host 误删。
Host 侧清扫：挂载后约 20 秒首次运行，之后每小时一次：
- 首次清扫仅记录空闲 worktree（报告为
deferred）； - 若仍空闲，下次清扫移除；
- 只处理
<repo>/.agents/worktrees/下的 worktree，不碰别处 linked checkout； - 仍有 session 或 agent 使用时跳过；
- 使用
git worktree remove --force删除 checkout 文件（含未提交与未跟踪），分支不删。
状态文件：~/.dsh/dsh-worktree-toggle/gc-state.json（最近一次清扫）、~/.dsh/dsh-worktree-toggle/worktrees.json（本插件创建的 worktree）。其他方式创建的 worktree，在检测到 live session 时会被纳入跟踪。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前建议浏览源码与 MIT 许可证，确认符合你的安全策略。
环境要求（README / package.json）：
- DeepSeek Harness 0.2.1-rc.2 或更新（
dsh.compatibility:>=0.2.1-rc.2 <0.3.0）； - Node >= 22；
- Host
PATH上可用的 git 可执行文件。
插件市场（上架后）：Plugins → Discover → 搜索 dsh-worktree-toggle。
npm：
dsh plugin --profile <profile> add dsh-worktree-toggle
GitHub：
dsh plugin --profile <profile> add github:wzciczw/dsh-worktree-toggle
安装后重启 host（或等待 profile 重载），并刷新页面。README 注明在 Windows desktop build 上做过测试。
典型用法¶
- 在 git 仓库中打开新会话。
- 在 composer 工具行、分支 pill 右侧找到
Worktree开关。 - 点击开关。
Host 会在 <repo>/.agents/worktrees/ 下创建分支与 linked checkout，把会话工作目录迁入；开关变为勾选、只读的 Worktree 芯片。此后该会话内的操作均在新 checkout 中进行。
以下情况不显示开关：会话已在 worktree 外启动并完成首条消息；当前目录不是 git 仓库。
适用场景与注意¶
适合：同一仓库上并行多个 Harness 会话，希望主 checkout 保持干净、又不想每次手敲 git worktree；需要与内置 worktree 相同沙箱策略的隔离开发。
限制（README Limits）：
- 仅能在会话首条消息之前切换；已开始的会话不能中途改 worktree。
- 清理范围限定在仓库根下的
.agents/worktrees/。 - 清理后分支仍在，checkout 内未提交内容不会保留。
- 依赖 host 上的 git。
DSH 生态是「一切皆插件」；社区插件目录见 SkillHub 插件页，与 DeepSeek / 幻方无官方从属关系，不要当作官方应用商店。
结尾¶
dsh-worktree-toggle 把「会话级 git 隔离」收成 composer 旁的一次点击，并配合 .agents/worktrees/ 下的空闲清理，减轻并行开发与磁盘占用之间的权衡。
