前言¶

让代理在仓库里干活，一个常见的麻烦是所有改动都落在同一个工作区：上一个任务的更改还没提交，下一个任务已经开工，未提交内容搅在一起；想靠切分支隔离，又得先处理当前现场。

Git 原生的 worktree 允许同一个仓库同时维护多个检出，每个检出挂自己的分支。dsh-task-worktree 做的事，就是把这套能力接入 DeepSeek Harness（下称 DSH）的会话模型：每个任务一个隔离检出，主工作区保持不动，交付与清理动作由人执行。

下面介绍它的定位、功能与用法。

这是什么¶

dsh-task-worktree 是 Letter2025 维护的社区插件，许可证为 MIT，一句话定位：Complete Git worktree support for DeepSeek Harness——为每个任务提供隔离的 git worktree 检出与持久化清单。

在 DSH「一切皆插件」的架构下，它提供三件事：

1、每个任务获得独立的 git worktree 检出，分支名自动加 worktree/ 前缀（允许斜杠）；
2、检出按仓库记录在 manifest 里，状态在会话与重启后仍保留；
3、交付与清理操作（合并回主分支、提交、删除）仅限人类执行，模型无法触达。

核心功能¶

每个任务一个独立检出¶

每创建一个任务 worktree，插件会在 <repo>/.dsh-worktrees/ 下做一次独立检出，并自动创建带 worktree/ 前缀的分支。主工作区完全不动。

使用 worktree 的会话在会话头显示分支徽标，不创建工作区条目。

持久化清单¶

所有 worktree 按仓库记录在 manifest 中，写入为原子操作（tmp + rename），状态在会话与重启后仍保留。/worktree prune 负责清理 checkout 已不存在的记录，并移除过期的工作区注册。

模型工具与人类命令的分工¶

模型侧拿到三个工具：

• worktree_create：创建任务 worktree，可用 includeUncommitted 把主工作区的未提交更改一并带入；
• worktree_list：列出仓库托管的 worktree；
• worktree_status：查看状态。

人类命令覆盖全流程：

/worktree mode-on                        # 开启 worktree 模式
/worktree mode-off                       # 关闭 worktree 模式
/worktree create <name> --carry          # 手动创建，--carry 带入未提交更改
/worktree list                           # 列出
/worktree status                         # 查看状态
/worktree finish worktree/<name> <msg>   # 在 worktree 分支上提交并保留
/worktree bring-back worktree/<name>     # 将分支合并回主分支
/worktree remove worktree/<name> --force # 删除 worktree 与分支
/worktree prune                          # 清理失效记录

其中 finish / bring-back / remove 这三个交付与清理操作仅限人类执行，模型无法触达。

安装¶

要求 DeepSeek Harness 0.1.0-rc.7 包线、Git 2.31+、Node 20+。满足后执行：

dsh plugin --profile web add dsh-task-worktree

插件的 @deepseek-ai/* 依赖只是 peerDependencies，由宿主提供，插件不会向 profile 安装基础设施副本。

典型用法¶

开启 worktree 模式¶

有两种方式。

第一种：空白会话时在 dock 下拉选择 “Worktree mode”（可选填分支名，自动加 worktree/ 前缀），随后发送首条消息，触发模型调用 worktree_create。

第二种：不选模式，直接让代理执行：

用 worktree 隔离干活，任务叫 xxx

另外，/worktree mode-on 与 /worktree mode-off 用于手动开启或关闭该模式。

收尾¶

经过上面的步骤，任务已经在独立的检出和分支上进行。收尾时按需选择：

/worktree bring-back worktree/<name>      # 将分支合并回主分支（要求主工作区干净）
/worktree finish worktree/<name> <msg>    # 在 worktree 分支上提交并保留
/worktree remove worktree/<name> --force  # 删除 worktree 与分支（--force 同时删除未提交更改）

检查与清理¶

/worktree list
/worktree status
/worktree prune

prune 会清理 checkout 已不存在的记录，并移除过期的工作区注册。

安全设计¶

• 交付与清理操作（finish / bring-back / remove）仅限人类执行，模型无法触达；
• bring-back 要求主工作区干净（MAIN_DIRTY），且拒绝在 worktree 内运行；
• remove 拒绝删除当前会话正在工作的 worktree（IN_USE）；
• 所有 git 操作通过 ctx.subprocess（harness 托管）执行；
• manifest 写入为原子操作（tmp + rename）。

本地开发¶

如果要参与开发，仓库提供两个入口：

npm test              # 冒烟测试
npm pack --dry-run    # 发布前检查 tarball

适用场景与注意¶

适合的场景：

• 多个任务并行推进，不想让未提交更改互相干扰；
• 任务中断后希望状态保留，换个会话或重启后还能查到；
• 希望合并、删除这类操作由人手动确认，而不是交给模型。

注意事项：

• 插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（本项目为 MIT）；
• 版本要求：DeepSeek Harness 0.1.0-rc.7 包线、Git 2.31+、Node 20+。

小结¶

dsh-task-worktree 把 git worktree 的任务级隔离流程搬进了 DSH：模型负责创建与干活，交付与清理留在人手里，状态跨会话保留。如果你经常在同一个仓库里并行多个任务，可以按上面的步骤试一遍。

• 社区目录页：https://www.skillhub.cn/plugins/Letter2025/dsh-task-worktree
• GitHub 仓库：https://github.com/Letter2025/dsh-task-worktree

需要说明的是，skillhub.cn 是独立的社区目录站点，与 DeepSeek / 幻方没有官方从属关系。