前言¶
在 DSH “一切皆插件”的思路下，dsh-worktree 以插件形式接入。它解決的是一個具體問題：多個 DSH 子代理同時處理同一倉庫時，並行寫入容易互相干擾。該插件讓子代理在獨立 Git worktree 中工作，任務結束後再審閱、驗證、提交、合併、推送、創建 Pull Request、歸檔或恢復結果。
這是什麼¶
倉庫所有者是 paradoxSCH，倉庫地址爲：
https://github.com/paradoxSCH/dsh-worktree
包信息如下：
@paradoxsch/dsh-worktree
0.1.0-alpha.2
MIT
package.json 聲明的 Node 要求是：
>=22.19.0
當前 alpha 版本支持已發佈的 DSH：
0.1.0-rc.6
0.1.x
插件會安裝到全局 DSH profile，不會修改業務項目的 package.json。
安裝與啓用¶
先選擇要安裝的 DSH profile，再執行安裝命令。
Web profile：
dsh plugin --profile web add @paradoxsch/dsh-worktree@alpha
Headless profile：
dsh plugin --profile headless add @paradoxsch/dsh-worktree@alpha
安裝完成後，可以檢查當前 profile 是否能看到這個插件：
dsh plugin --profile web why @paradoxsch/dsh-worktree
dsh --profile web --dump-config
典型用法¶
委派子代理¶
讓 Agent 使用以下委派能力，子代理會自動進入獨立 worktree：
subagent_worktree
如果任務需要並行執行，可以設置：
run_in_background: true
之後通過 DSH 的任務接口查看結果或停止任務：
job_output
job_kill
手動管理 worktree¶
也可以使用 /worktree 命令手動管理。常用命令如下：
/worktree list
/worktree create working-state managed
/worktree review <id>
/worktree validate <id>
/worktree doctor
/worktree recover
命令中的 <id> 表示某個 worktree 標識。
審閱和交付¶
/worktree 支持以下交付操作：
/worktree review <id>
/worktree validate <id>
/worktree commit <id> <message>
/worktree branch <id> <branch-name>
/worktree handoff <id>
/worktree merge <id>
/worktree push <id>
/worktree pr <id> <title>
/worktree archive <id>
/worktree restore <id>
/worktree discard <id> confirm
這些命令覆蓋審閱、驗證、提交、分支、交付、合併、推送、Pull Request、歸檔和恢復等路徑。
任務起點與保留方式¶
創建 worktree 時，事實中支持以下模式值：
working-state
head
fresh
ephemeral
managed
permanent
其中 working-state、head、fresh 用於選擇任務起點；ephemeral、managed、permanent 用於選擇保留方式。
關於敏感文件，已確認的行爲是：
ignored文件默認不會複製。.env、密鑰和證書等敏感內容即使列在.worktreeinclude中也不會複製。
安全與恢復¶
已確認的安全約束包括：
- 有修改的 worktree 不會被自動丟棄。
- 刪除、合併、提交、推送和 Pull Request 等操作會在執行前重新檢查 worktree 狀態。
push不使用 force。merge要求目標 checkout clean。worktree解決並行寫衝突，但不替代 DSH sandbox 或審批策略。
創建 Pull Request 需要已登錄的 GitHub CLI。可以先檢查：
gh auth status
默認持久化數據位於：
$DSH_HOME/plugins/dsh-worktree
環境診斷和狀態恢復可以使用：
/worktree doctor
/worktree recover
適用場景與注意¶
適合在 DSH 中讓多個子代理並行處理同一個倉庫，同時希望每個任務擁有獨立 checkout，並在任務結束後保留可審閱、可交付、可恢復的結果。
注意：
- 該插件隨當前 DSH 進程權限運行，安裝前應檢查源碼、
package.json和 MIT 許可證。 - 插件安裝到全局 DSH profile，不會修改業務項目的
package.json。 - 卸載 Bundle 不會刪除 retained 或 archived 結果。
卸載¶
卸載命令如下：
dsh plugin --profile web remove @paradoxsch/dsh-worktree
dsh plugin --profile headless remove @paradoxsch/dsh-worktree
確認不再需要 retained 或 archived 結果後，再單獨處理：
$DSH_HOME/plugins/dsh-worktree
結尾¶
dsh-worktree 的主要價值，是把 DSH 子代理的並行寫入隔離到獨立 Git worktree 中，並提供審閱、驗證、提交、合併、推送、Pull Request、歸檔和恢復的交付鏈路。若需要查看源碼、許可證或反饋問題，可訪問：
https://github.com/paradoxSCH/dsh-worktree
