前言¶
在 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/ 下的空閒清理，減輕並行開發與磁盤佔用之間的權衡。
