前言¶
在 DeepSeek Harness（DSH）里让模型改代码，常见做法是直接在主工作区里动文件。多个任务并行、或希望主分支保持干净时，容易互相干扰，回滚和合并也费事。Qoder、Codex、Claude Code 等环境都有「每个任务单独 checkout」的 worktree 工作流；DSH 本身是插件化宿主，社区插件可以把同类能力接进来。
下面介绍 dsh-task-worktree（维护者 epik7th），它是面向 DSH 0.2.0 宿主线 的 Git worktree 插件，fork 自 Letter2025/dsh-task-worktree，在目录 SkillHub 中归类为工作流。每个任务在独立 worktree 和分支上开发，状态写入 per-repo manifest，会话重启后仍可恢复；主工作区不被自动注册为新 workspace，会话标题上的 branch badge 标明当前对话绑定的 worktree。
这是什么¶
dsh-task-worktree 为 DSH 提供完整的、任务粒度的 git worktree 支持：创建隔离 checkout、列出与查看状态、把改动合并回主分支或在 worktree 分支上提交、清理目录与分支。设计参考 Qoder 的 Worktree 执行环境、Codex 的 codex worktree create --permanent、Claude Code 的 --worktree 会话，并适配 DSH 的 session / workspace 模型。
与上游 npm 包 dsh-task-worktree@0.4.3 的关系：上游声明的宿主 peer 与 dsh 0.2.0 不兼容，且浏览器端仍依赖 dsh 0.1.6 已移除的 sessions.current 字段；本 fork 提高 peer 范围，并从主视图 retention 推导当前会话（与 shell 一致）。工具、命令与安全模型沿用上游设计，详见仓库内 迁移记录。
Worktree 物理路径在 <repo>/.dsh-worktrees/；每个任务通常对应 worktree/<name> 形式的分支与相对路径（名称可含斜杠）。
核心功能¶
与常见产品的概念对应¶
| 本插件 | Qoder | Codex | Claude Code |
|---|---|---|---|
| 任务级隔离 checkout | Worktree 执行环境 | codex worktree create --permanent |
claude --worktree <name> |
目录 <repo>/.dsh-worktrees/ |
后台 worktree | .codex/worktrees/ |
.claude/worktrees/ |
| 持久化注册表 | 按会话 | 全局索引 | 会话绑定 |
| 每任务独立分支 | 分支选择器 | — | worktree-<name> |
| 会话标记 | session badge | — | — |
| 合并回主分支 | Move to local | — | 退出/清理提示 |
| 在 worktree 分支直接提交 | Review & commit | worktree 内提交 | worktree 内提交 |
模型可调用的工具¶
交付与清理（finish / bring-back / remove）仅人类可操作，模型无法调用。
| 工具 | 作用 |
|---|---|
worktree_create {name, baseCommit?, includeUncommitted?} |
创建任务 worktree；可选把主工作区未提交改动带入 |
worktree_list |
列出仓库内受管理的 worktree（状态 / 脏否 / 分支） |
worktree_status {name?} |
查看指定或当前会话所在 worktree 的状态 |
人类命令（节选）¶
收尾、合并、删除等操作通过 slash 命令完成，例如：
/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 的 stale workspace 注册）
空白对话可在 dock 勾选 worktree 并选基准分支；等价地也可直接对模型说「用 worktree 隔离干活，任务叫 xxx」，由模型调用 worktree_create。
安装与启用¶
在运行 Web GUI 的 profile 中，从公开 Git 仓库安装（包名 dsh-task-worktree）：
dsh plugin --profile desktop add github:epik7th/dsh-task-worktree
插件管理器的 install 字段也可填同一地址：github:epik7th/dsh-task-worktree。执行插件需要已 compose 的 dsh.bundle patch，add 会一并接线。
环境要求（README 原文）：
- DeepSeek Harness 0.2.0-rc.1 宿主线（含 rc.2 与 0.2.0 正式版）
- Git 2.31+
- Node 20+
注意：不要与上游 npm 包 dsh-task-worktree@0.4.3 同时安装；宿主按包名解析 client bundle，两个来源解析到同一包名会被拒绝。应先卸载其一再装另一。
当前仓库 package.json 版本为 0.6.4，许可证 MIT。
典型用法¶
从空白对话进入 worktree 模式¶
- 在尚未发送消息的空白对话里，dock 会出现 worktree 复选框和分支选择器。选择器默认展示新任务 worktree 的起始分支（一般为仓库当前分支），可搜索本地与 remote-tracking 分支；勾选后相当于
mode-on --base <branch>，并固定为worktree_create的baseCommit。 - 发送第一条消息后，宿主会在你的消息前注入一条 instructions 上下文（界面显示为 injected-context 行），引导模型在本轮调用
worktree_create，在worktree/前缀分支下创建 worktree，并在 checkout 内用绝对路径工作；结束时提醒可用的清理命令。 - 底层等价于执行类似：
git worktree add -b worktree/<name> <repo>/.dsh-worktrees/worktree/worktree/<name> <base>
不会注册新 workspace，也不会切换对话；会话标题 badge 显示绑定的分支名。模型在 worktree 目录内继续改代码。
不用 GUI，直接口述任务¶
对模型说明例如：「用 worktree 隔离干活，任务叫 xxx」。模型调用 worktree_create；name 同时作为分支名与相对路径。
任务结束后¶
由人选择其一：
- 合并回主分支：
/worktree bring-back worktree/<name> - 在 worktree 分支提交保留：
/worktree finish worktree/<name> <msg> - 强制删除：
/worktree remove worktree/<name> --force
用 /worktree list 与 /worktree status 核对状态；长期维护可用 /worktree prune 清理陈旧项。
适用场景与注意¶
适合：同一仓库上并行多个 Agent 任务、希望主工作区目录保持不动、需要可恢复的 worktree 注册表、习惯 Qoder/Codex/Claude Code 式「一任务一 checkout」的 DSH 用户。
分支选择器限制：依赖 shell 的 workspaceFiles Remote 读取 <repo>/.git；若服务不可用，或会话所在 checkout 的 loose refs 不在 workspace 根下，选择器会提示并回退到 HEAD。非 Git 仓库的工作区在 ref 读取完成后不会提供 worktree 模式。
安全与信任：插件以当前 DSH 进程权限执行 Git 与子进程操作；安装前请自行审阅 GitHub 源码 与 MIT 许可证。DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
与上游并存：仅需 dsh 0.2.0 宿主线时请使用本 fork；若仍停留在上游所声明的 ^0.1.7-rc.2 宿主 peer，应使用上游包而非本 fork。
结尾¶
dsh-task-worktree 把「按任务隔离的 Git worktree + 持久 manifest + 会话 badge + 人工控制的合并/提交/删除」接到 DSH 0.2.0 上，主 sidebar 不堆 workspace，任务边界却清晰可追踪。
