前言¶

讓代理在倉庫裏幹活，一個常見的麻煩是所有改動都落在同一個工作區：上一個任務的更改還沒提交，下一個任務已經開工，未提交內容攪在一起；想靠切分支隔離，又得先處理當前現場。

Git 原生的 worktree 允許同一個倉庫同時維護多個檢出，每個檢出掛自己的分支。dsh-task-worktree 做的事，就是把這套能力接入 DeepSeek Harness（下稱 DSH）的會話模型：每個任務一個隔離檢出，主工作區保持不動，交付與清理動作由人執行。

下面介紹它的定位、功能與用法。

這是什麼¶

dsh-task-worktree 是 Letter2025 維護的社區插件，許可證爲 MIT，一句話定位：Complete Git worktree support for DeepSeek Harness——爲每個任務提供隔離的 git worktree 檢出與持久化清單。

在 DSH「一切皆插件」的架構下，它提供三件事：

1、每個任務獲得獨立的 git worktree 檢出，分支名自動加 worktree/ 前綴（允許斜槓）；
2、檢出按倉庫記錄在 manifest 裏，狀態在會話與重啓後仍保留；
3、交付與清理操作（合併回主分支、提交、刪除）僅限人類執行，模型無法觸達。

核心功能¶

每個任務一個獨立檢出¶

每創建一個任務 worktree，插件會在 <repo>/.dsh-worktrees/ 下做一次獨立檢出，並自動創建帶 worktree/ 前綴的分支。主工作區完全不動。

使用 worktree 的會話在會話頭顯示分支徽標，不創建工作區條目。

持久化清單¶

所有 worktree 按倉庫記錄在 manifest 中，寫入爲原子操作（tmp + rename），狀態在會話與重啓後仍保留。/worktree prune 負責清理 checkout 已不存在的記錄，並移除過期的工作區註冊。

模型工具與人類命令的分工¶

模型側拿到三個工具：

• worktree_create：創建任務 worktree，可用 includeUncommitted 把主工作區的未提交更改一併帶入；
• worktree_list：列出倉庫託管的 worktree；
• worktree_status：查看狀態。

人類命令覆蓋全流程：

/worktree mode-on                        # 開啓 worktree 模式
/worktree mode-off                       # 關閉 worktree 模式
/worktree create <name> --carry          # 手動創建，--carry 帶入未提交更改
/worktree list                           # 列出
/worktree status                         # 查看狀態
/worktree finish worktree/<name> <msg>   # 在 worktree 分支上提交併保留
/worktree bring-back worktree/<name>     # 將分支合併回主分支
/worktree remove worktree/<name> --force # 刪除 worktree 與分支
/worktree prune                          # 清理失效記錄

其中 finish / bring-back / remove 這三個交付與清理操作僅限人類執行，模型無法觸達。

安裝¶

要求 DeepSeek Harness 0.1.0-rc.7 包線、Git 2.31+、Node 20+。滿足後執行：

dsh plugin --profile web add dsh-task-worktree

插件的 @deepseek-ai/* 依賴只是 peerDependencies，由宿主提供，插件不會向 profile 安裝基礎設施副本。

典型用法¶

開啓 worktree 模式¶

有兩種方式。

第一種：空白會話時在 dock 下拉選擇 “Worktree mode”（可選填分支名，自動加 worktree/ 前綴），隨後發送首條消息，觸發模型調用 worktree_create。

第二種：不選模式，直接讓代理執行：

用 worktree 隔離幹活，任務叫 xxx

另外，/worktree mode-on 與 /worktree mode-off 用於手動開啓或關閉該模式。

收尾¶

經過上面的步驟，任務已經在獨立的檢出和分支上進行。收尾時按需選擇：

/worktree bring-back worktree/<name>      # 將分支合併回主分支（要求主工作區乾淨）
/worktree finish worktree/<name> <msg>    # 在 worktree 分支上提交併保留
/worktree remove worktree/<name> --force  # 刪除 worktree 與分支（--force 同時刪除未提交更改）

檢查與清理¶

/worktree list
/worktree status
/worktree prune

prune 會清理 checkout 已不存在的記錄，並移除過期的工作區註冊。

安全設計¶

• 交付與清理操作（finish / bring-back / remove）僅限人類執行，模型無法觸達；
• bring-back 要求主工作區乾淨（MAIN_DIRTY），且拒絕在 worktree 內運行；
• remove 拒絕刪除當前會話正在工作的 worktree（IN_USE）；
• 所有 git 操作通過 ctx.subprocess（harness 託管）執行；
• manifest 寫入爲原子操作（tmp + rename）。

本地開發¶

如果要參與開發，倉庫提供兩個入口：

npm test              # 冒煙測試
npm pack --dry-run    # 發佈前檢查 tarball

適用場景與注意¶

適合的場景：

• 多個任務並行推進，不想讓未提交更改互相干擾；
• 任務中斷後希望狀態保留，換個會話或重啓後還能查到；
• 希望合併、刪除這類操作由人手動確認，而不是交給模型。

注意事項：

• 插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（本項目爲 MIT）；
• 版本要求：DeepSeek Harness 0.1.0-rc.7 包線、Git 2.31+、Node 20+。

小結¶

dsh-task-worktree 把 git worktree 的任務級隔離流程搬進了 DSH：模型負責創建與幹活，交付與清理留在人手裏，狀態跨會話保留。如果你經常在同一個倉庫裏並行多個任務，可以按上面的步驟試一遍。

• 社區目錄頁：https://www.skillhub.cn/plugins/Letter2025/dsh-task-worktree
• GitHub 倉庫：https://github.com/Letter2025/dsh-task-worktree

需要說明的是，skillhub.cn 是獨立的社區目錄站點，與 DeepSeek / 幻方沒有官方從屬關係。