前言¶

DSH 插件化擴展裏，一個常見問題是多個子代理同時處理同一倉庫時，工作目錄容易互相干擾。dsh-worktree 的做法是讓每個子代理進入自己的 git worktree：共享倉庫對象庫，但工作區彼此獨立。

下面介紹這個插件的定位、安裝方式、典型用法和已知限制。

這是什麼¶

dsh-worktree 是一個 DeepSeek Harness 插件，用於給 DSH 子代理提供基於 git worktrees 的文件系統隔離。

• GitHub 倉庫：CSY656/dsh-worktree
• 包名：dsh-worktree
• Owner：CSY656
• 許可證：MIT
• 版本要求：DeepSeek Harness next line，dsh >= 0.1.0-rc.6

它提供兩種入口：面向插件作者的 ctx.worktree 服務，以及面向人的 /worktree 斜槓命令。

核心功能¶

隔離位置與命名¶

worktree 位於：

<repoRoot>/.dsh/worktrees/<flatSlug>/

如果 slug 是嵌套形式，/ 會被扁平化爲 +。例如：

feature/demo → feature+demo
team/alice   → team+alice

對應分支使用 worktree-<flatSlug>，例如：

worktree-feature+demo

slug 校驗¶

創建 worktree 前會嚴格校驗 slug：

• 每段字符限制爲 [a-zA-Z0-9._-]
• 每段長度不超過 64
• 拒絕 .、..、//
• 拒絕首尾分隔符

創建後的盡力配置¶

創建 worktree 後，插件會盡力執行 setup：

• 複製項目 .dsh 配置
• 繼承 core.hooksPath
• 符號鏈接 node_modules、.venv、vendor
• 複製 .worktreeinclude 列出的忽略文件

變更保護¶

變更檢測採用 fail-closed：git 失敗會按“有變更”處理。因此，髒 worktree 會被保留並報告，而不是直接刪除。

臨時 worktree 清理¶

插件支持配置：

• sweepIntervalMs
• sweepMaxAgeMs

用於週期性清理 agent-* 臨時 worktrees。

安裝與啓用¶

從 GitHub 安裝¶

dsh plugin --profile default add github:you/dsh-worktree

pnpm >= 10 的處理¶

如果使用 pnpm >= 10，需要在 profile 的 pnpm-workspace.yaml 中允許構建：

allowBuilds:
  dsh-worktree: true

然後重新運行 add 命令。

npm 預構建安裝¶

README 也給出 npm 預構建安裝命令：

dsh plugin --profile default add dsh-worktree

安裝前檢查¶

dsh-worktree 以當前 DSH 進程權限運行。安裝前建議檢查源碼、許可證與依賴，確認其行爲符合你的安全要求。

典型用法¶

斜槓命令¶

/worktree create feature/demo
/worktree list
/worktree remove feature/demo

對應行爲：

• /worktree create feature/demo：創建 .dsh/worktrees/feature+demo，分支爲 worktree-feature+demo
• /worktree list：輸出 name/path/branch 行
• /worktree remove feature/demo：worktree 髒時拒絕刪除；加 --discard 可強制

Service API¶

插件作者可以通過 ctx.worktree 服務創建和管理 worktree：

const lease = await ctx.worktree.acquire('agent-abc1234', cwd)

// ... 將 worktree 路徑交給獨立子代理執行 ...

const { kept, path, branch } = await lease.release()

release 後：

• 乾淨的 worktree 會被移除
• 髒的 worktree 會被保留並報告

適用場景與注意¶

適合需要讓多個子代理並行修改同一倉庫，但不希望它們直接覆蓋同一工作區的場景。

使用時的限制如下：

• 僅進程內隔離有效；acp、claude-code、codex、dsh-sdk 等 out-of-process backends 會忽略 child-session cwd overrides
• 不跨進程共享，一個 DSH 實例擁有其 worktrees
• 沒有合併策略；保留下來的 worktree 由委派 agent 執行合併，例如：

git merge worktree-<flatSlug>

• 一行式 subagent 自動隔離需要 dsh-subagent/dsh-tool-subagent 的上游能力；在上游接受前，需要手動使用 ctx.worktree.acquire() 或 /worktree 命令

結尾¶

dsh-worktree 的價值在於把 DSH 子代理的文件系統隔離落到 git worktree 上，並通過 fail-closed 的變更保護降低誤刪髒工作區的風險。

它屬於 DSH 插件生態中的一個獨立插件；社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係，不應理解爲官方應用商店。

本次已覈實資料未給出可確認的目錄頁 URL；GitHub 倉庫爲 https://github.com/CSY656/dsh-worktree 。