paradoxSCH/dsh-worktree

dsh-worktree

为 DeepSeek Harness（DSH）子代理提供隔离的 Git worktree。并行任务在独立 checkout 中工作，不直接修改主工作区；任务结束后可以审阅、验证、提交、交付、归档或恢复结果。

[!IMPORTANT]
当前 alpha 版本支持已发布的 DSH 0.1.0-rc.6 及后续 0.1.x 版本。

安装

插件安装到全局 DSH profile，不会修改业务项目的 package.json。

Web profile：

dsh plugin --profile web add @paradoxsch/dsh-worktree@alpha

Headless profile：

dsh plugin --profile headless add @paradoxsch/dsh-worktree@alpha

检查是否安装成功：

dsh plugin --profile web why @paradoxsch/dsh-worktree
dsh --profile web --dump-config

第一次使用

让 Agent 使用 subagent_worktree 委派任务，子代理会自动进入独立 worktree。Web profile 的侧边栏底部会出现 Worktrees，可以在其中查看状态、diff 和可用操作。

委派默认等待子代理返回结果；需要并行执行时可以设置 run_in_background: true，之后通过 DSH 的 job_output 查看结果、通过 job_kill 停止任务。每次委派都是独立子任务。

也可以使用 /worktree 命令手动管理：

/worktree list
/worktree create working-state managed
/worktree review
/worktree validate
/worktree doctor

不带子命令的 /worktree 等同于 /worktree list。 来自 list/create 的返回结果。

选择任务起点

| 模式 | 子代理从哪里开始 | 适合场景 |
| --- | --- | --- |
| working-state | 当前 HEAD，加上 staged、unstaged 和非 ignored 的 untracked 变更 | 继续当前正在进行的工作；默认值 |
| head | 当前已提交的 HEAD | 不希望继承未提交修改 |
| fresh | 远端最新基线 | 与本地当前分支无关的独立任务 |

ignored 文件默认不会复制。确实需要的普通 ignored 文件可以写入仓库根目录的 .worktreeinclude；.env、密钥和证书等敏感内容即使列在其中也不会复制，请通过 DSH credentials 或运行环境提供。

选择保留方式

| 模式 | 任务结束后的行为 |
| --- | --- |
| ephemeral | 用于一次性任务；clean checkout 自动移除，有修改时仍会保留 |
| managed | 默认值；clean checkout 可自动移除，有修改的结果保留供审阅和交付 |
| permanent | 长期保留，直到用户明确处理 |

managed worktree 默认处于 detached HEAD。需要推送或创建 Pull Request 时，先使用 branch 创建分支。

审阅和交付

| 操作 | 结果 |
| --- | --- |
| review | 查看相对任务基线的 diff 和 untracked 文件，不修改仓库 |
| validate | 在 worktree 中运行管理员配置的验证命令 |
| commit | 提交 worktree 当前修改 |
| branch | 为 detached worktree 创建分支 |
| handoff | 将 commits、staged、unstaged 和 untracked 状态交付到当前会话 checkout |
| merge | 将已提交结果以 non-fast-forward merge 合入当前会话的 clean 分支 |
| push | 将当前分支非强制推送到 origin |
| pr | 推送当前分支并通过 GitHub CLI 创建或复用 Pull Request |
| archive | 保存可恢复结果并释放 checkout 占用的磁盘空间 |
| restore | 从 archive 恢复 worktree |
| discard | 永久删除未交付结果，需要明确确认 |

常用命令：

/worktree commit
/worktree branch
/worktree handoff
/worktree merge
/worktree push
/worktree pr
/worktree archive
/worktree restore
/worktree discard  confirm

handoff 和 merge 的目标是运行命令时当前 DSH 会话的 checkout。目标不属于同一仓库、存在未提交修改或不满足安全条件时，操作会停止并报告原因。

创建 Pull Request 需要已登录的 GitHub CLI：

gh auth status

没有 gh 不影响本地创建、审阅、commit、branch、handoff、merge、archive 和 restore。

安全与恢复

- 有修改的 worktree 不会被自动丢弃。
- 删除、合并、提交、推送和 Pull Request 等操作会在执行前重新检查 worktree 状态。
- ignored 文件和常见敏感文件默认不进入新 worktree。
- push 不使用 force；merge 要求目标 checkout clean。
- worktree 解决并行写冲突，但不替代 DSH sandbox 或审批策略。
- 默认持久化数据位于 $DSH_HOME/plugins/dsh-worktree。

诊断环境和记录：

/worktree doctor

进程崩溃或操作中断后重新核对 Git 与持久化状态：

/worktree recover
如果 recover 返回 manual 项目，请在继续 merge、discard 或删除磁盘目录前处理报告中的 identity/path 问题。

卸载

dsh plugin --profile web remove @paradoxsch/dsh-worktree
dsh plugin --profile headless remove @paradoxsch/dsh-worktree

卸载 Bundle 不会删除 retained 或 archived 结果。确认不再需要这些结果后，再单独处理 $DSH_HOME/plugins/dsh-worktree 中的数据。

License

MIT