前言¶
在 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
