前言¶
在 DeepSeek Harness（DSH）裏讓模型改代碼，常見做法是直接在主工作區裏動文件。多個任務並行、或希望主分支保持乾淨時，容易互相干擾，回滾和合並也費事。Qoder、Codex、Claude Code 等環境都有「每個任務單獨 checkout」的 worktree 工作流；DSH 本身是插件化宿主，社區插件可以把同類能力接進來。
下面介紹 dsh-task-worktree（維護者 epik7th），它是面向 DSH 0.2.0 宿主線 的 Git worktree 插件，fork 自 Letter2025/dsh-task-worktree，在目錄 SkillHub 中歸類爲工作流。每個任務在獨立 worktree 和分支上開發，狀態寫入 per-repo manifest，會話重啓後仍可恢復；主工作區不被自動註冊爲新 workspace，會話標題上的 branch badge 標明當前對話綁定的 worktree。
這是什麼¶
dsh-task-worktree 爲 DSH 提供完整的、任務粒度的 git worktree 支持：創建隔離 checkout、列出與查看狀態、把改動合併回主分支或在 worktree 分支上提交、清理目錄與分支。設計參考 Qoder 的 Worktree 執行環境、Codex 的 codex worktree create --permanent、Claude Code 的 --worktree 會話，並適配 DSH 的 session / workspace 模型。
與上游 npm 包 dsh-task-worktree@0.4.3 的關係：上游聲明的宿主 peer 與 dsh 0.2.0 不兼容，且瀏覽器端仍依賴 dsh 0.1.6 已移除的 sessions.current 字段；本 fork 提高 peer 範圍，並從主視圖 retention 推導當前會話（與 shell 一致）。工具、命令與安全模型沿用上游設計，詳見倉庫內 遷移記錄。
Worktree 物理路徑在 <repo>/.dsh-worktrees/；每個任務通常對應 worktree/<name> 形式的分支與相對路徑（名稱可含斜槓）。
核心功能¶
與常見產品的概念對應¶
| 本插件 | Qoder | Codex | Claude Code |
|---|---|---|---|
| 任務級隔離 checkout | Worktree 執行環境 | codex worktree create --permanent |
claude --worktree <name> |
目錄 <repo>/.dsh-worktrees/ |
後臺 worktree | .codex/worktrees/ |
.claude/worktrees/ |
| 持久化註冊表 | 按會話 | 全局索引 | 會話綁定 |
| 每任務獨立分支 | 分支選擇器 | — | worktree-<name> |
| 會話標記 | session badge | — | — |
| 合併回主分支 | Move to local | — | 退出/清理提示 |
| 在 worktree 分支直接提交 | Review & commit | worktree 內提交 | worktree 內提交 |
模型可調用的工具¶
交付與清理（finish / bring-back / remove）僅人類可操作，模型無法調用。
| 工具 | 作用 |
|---|---|
worktree_create {name, baseCommit?, includeUncommitted?} |
創建任務 worktree；可選把主工作區未提交改動帶入 |
worktree_list |
列出倉庫內受管理的 worktree（狀態 / 髒否 / 分支） |
worktree_status {name?} |
查看指定或當前會話所在 worktree 的狀態 |
人類命令（節選）¶
收尾、合併、刪除等操作通過 slash 命令完成，例如：
/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 的 stale workspace 註冊）
空白對話可在 dock 勾選 worktree 並選基準分支；等價地也可直接對模型說「用 worktree 隔離幹活，任務叫 xxx」，由模型調用 worktree_create。
安裝與啓用¶
在運行 Web GUI 的 profile 中，從公開 Git 倉庫安裝（包名 dsh-task-worktree）：
dsh plugin --profile desktop add github:epik7th/dsh-task-worktree
插件管理器的 install 字段也可填同一地址：github:epik7th/dsh-task-worktree。執行插件需要已 compose 的 dsh.bundle patch，add 會一併接線。
環境要求（README 原文）：
- DeepSeek Harness 0.2.0-rc.1 宿主線（含 rc.2 與 0.2.0 正式版）
- Git 2.31+
- Node 20+
注意：不要與上游 npm 包 dsh-task-worktree@0.4.3 同時安裝；宿主按包名解析 client bundle，兩個來源解析到同一包名會被拒絕。應先卸載其一再裝另一。
當前倉庫 package.json 版本爲 0.6.4，許可證 MIT。
典型用法¶
從空白對話進入 worktree 模式¶
- 在尚未發送消息的空白對話裏，dock 會出現 worktree 複選框和分支選擇器。選擇器默認展示新任務 worktree 的起始分支（一般爲倉庫當前分支），可搜索本地與 remote-tracking 分支；勾選後相當於
mode-on --base <branch>，並固定爲worktree_create的baseCommit。 - 發送第一條消息後，宿主會在你的消息前注入一條 instructions 上下文（界面顯示爲 injected-context 行），引導模型在本輪調用
worktree_create，在worktree/前綴分支下創建 worktree，並在 checkout 內用絕對路徑工作；結束時提醒可用的清理命令。 - 底層等價於執行類似：
git worktree add -b worktree/<name> <repo>/.dsh-worktrees/worktree/worktree/<name> <base>
不會註冊新 workspace，也不會切換對話；會話標題 badge 顯示綁定的分支名。模型在 worktree 目錄內繼續改代碼。
不用 GUI，直接口述任務¶
對模型說明例如：「用 worktree 隔離幹活，任務叫 xxx」。模型調用 worktree_create；name 同時作爲分支名與相對路徑。
任務結束後¶
由人選擇其一：
- 合併回主分支：
/worktree bring-back worktree/<name> - 在 worktree 分支提交保留：
/worktree finish worktree/<name> <msg> - 強制刪除：
/worktree remove worktree/<name> --force
用 /worktree list 與 /worktree status 覈對狀態；長期維護可用 /worktree prune 清理陳舊項。
適用場景與注意¶
適合：同一倉庫上並行多個 Agent 任務、希望主工作區目錄保持不動、需要可恢復的 worktree 註冊表、習慣 Qoder/Codex/Claude Code 式「一任務一 checkout」的 DSH 用戶。
分支選擇器限制：依賴 shell 的 workspaceFiles Remote 讀取 <repo>/.git；若服務不可用，或會話所在 checkout 的 loose refs 不在 workspace 根下，選擇器會提示並回退到 HEAD。非 Git 倉庫的工作區在 ref 讀取完成後不會提供 worktree 模式。
安全與信任：插件以當前 DSH 進程權限執行 Git 與子進程操作；安裝前請自行審閱 GitHub 源碼 與 MIT 許可證。DSH 生態強調「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
與上游並存：僅需 dsh 0.2.0 宿主線時請使用本 fork；若仍停留在上游所聲明的 ^0.1.7-rc.2 宿主 peer，應使用上游包而非本 fork。
結尾¶
dsh-task-worktree 把「按任務隔離的 Git worktree + 持久 manifest + 會話 badge + 人工控制的合併/提交/刪除」接到 DSH 0.2.0 上，主 sidebar 不堆 workspace，任務邊界卻清晰可追蹤。
