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 <id>
/worktree validate <id>
/worktree doctor

不带子命令的 /worktree 等同于 /worktree list。<id> 来自 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 <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

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