dsh-worktree-space

dsh plugin --profile web add dsh-worktree-space

<a id="chinese"></a>

Worktree Space

简体中文 · [English](#english) · [更新日志](docs/CHANGELOG.md)

Worktree Space：一任务一空间，工作多路并行。把一个涉及一个或多个 Git 仓库的工作任务放进独立的任务空间目录——参与的每个仓库都在同一个任务分支上各开一个 worktree；任务空间自动注册为 DSH 工作区，会话直接在任务空间里开工；多个任务各建一个任务空间并行推进、互不干扰。建空间时可以定下这个任务要不要部署验收，勾了它，一条通过的冒烟记录就是收尾合并的闸门。任务结束时把任务分支合并回目标分支、移除 worktree，并把空间里遗留的文档归档到指定目录；也可以把未处理的提交和合并冲突交给一个 agent 会话处理。

两条路各有侧重，可以只看其中一条：在面板上手动点完全程（[使用](#-使用)），或者让 Agent 用工具自动编排（[进阶用法](#-进阶用法让-agent-全自动编排)）。完整步骤、异常流程与错误码都在 [《Worktree Space 使用指南》](USAGE.md)。


<img src="docs/img/isolation-model.png" alt="Worktree Space隔离模型" width="960">

<img src="docs/img/user-story-flow.png" alt="Worktree Space使用流程" width="960">

📺 视频介绍：Worktree Space 插件介绍（B 站）

📑 目录

• [🚀 安装](#-安装)
• [🔧 环境要求](#-环境要求)
• [⚡ 快速开始](#-快速开始)
• [✨ 功能](#-功能)
• [📂 任务目录结构](#-任务目录结构)
• [🛠️ 使用](#-使用)　面板手动流程：[➕ 创建](#-创建-worktree-space) · [🗂️ 管理](#-管理-worktree-space) · [🚢 部署验收](#-部署验收) · [🏁 结束](#-结束-worktree-space)（[组合行为](#各选项组合的行为)）
• [🤖 进阶用法：让 Agent 全自动编排](#-进阶用法让-agent-全自动编排)
• [🤖 把提交与冲突交给 agent](#-把提交与冲突交给-agent)
• [⚙️ 插件配置](#-插件配置)
• [🔐 权限与失败边界](#-权限与失败边界)
• [📝 操作日志](#-操作日志)
• [📄 配套文档](#-配套文档)

🚀 安装

网页端，从命令行安装：

dsh plugin --profile web add dsh-worktree-space

卸载：dsh plugin --profile web remove dsh-worktree-space；更新时先卸载再重新安装。

桌面端在插件管理页里操作：侧边栏 → 插件，在「插件包名」填 dsh-worktree-space，点「安装」；

卸载时在插件列表里点开 Worktree Space，进「插件详情」页，右上方点「卸载」按钮。

🔧 环境要求

• Node.js >=22.19.0
• Git：所有 worktree 与分支操作都由它执行，不随插件分发，需在 PATH 上
• DSH >=0.2.0-rc.1 <0.3.0-0，即 0.2.x（下界自 0.2.0-rc.1 起，不含 0.3.0 线的预发布）
• 客户端：网页端与桌面端均可用；桌面端由人工验证，命令行矩阵未覆盖

五个官方版本逐个实测通过：0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.1、0.2.1-rc.2、0.2.1-rc.3，

每个版本都用该版本自己的 DSH CLI 在一次性 profile 里跑通了安装、启动、卸载、回滚。这套验证覆盖的是

命令行与网页端的路径；桌面端（Electron）只做了人工安装可用性确认，未纳入脚本矩阵。逐条记录见

[docs/store-evidence.md](docs/store-evidence.md)。

DSH 会强制校验清单里 peerDependencies 声明的 DSH 版本范围：运行时的版本不满足，就在安装前或启动时

拒绝加载，并给出 dsh plugin allow-version 的精确豁免命令。engines.dsh 之类的字段只是声明，不会阻止加载。

实测范围之外的版本一律按未知处理，不拿宽泛范围冒充证据；遇到版本相关的问题请到

Issues 反馈。

⚡ 快速开始

一次完整任务的最短路径：在仓库工作区里与 Agent 确认需求，由它在任务空间内完成修改，

你验收后合并回各仓库当前检出的分支。全程无需手动执行 git 命令。

第一步：在仓库工作区与 Agent 理清需求

先在本仓库的工作区会话中说明任务范围：涉及哪些仓库、要达到什么效果、以什么标准判定完成。

这一步必须早于任何 git 操作——需求未定时创建任务空间，中途变更方向意味着已建的 worktree

与已产生的提交都要重来。

需求明确后，Agent 会逐项确认任务空间的位置、参与的仓库、起点分支以及是否启用部署验收。

其中是否部署验收在创建任务空间时即固定，事后无法追加或更改，须在此步一并确定。

第二步：发送提示词，创建任务空间并派单

需求确定后，向该会话发送：

创建一个任务空间并派单，将已确定好的需求通过 worktree 方式检出并执行修改实现；

修改完成后通知我验收，验收通过后再合并。

Agent 据此创建任务空间——每个参与仓库一份 worktree，共用一条任务分支——并开启一个任务会话，

把需求作为任务书交付。任务会话在独立目录中修改代码，不影响各仓库当前的检出。

第三步：验收后提交合并

任务会话完成修改后通知你。先验收：在所给 worktree 中确认实现是否符合需求、测试是否通过。

验收通过后，回到派单的会话发送：

现在验收通过，请合并到各仓库当前检出分支，并删除任务空间。

Agent 执行合并、移除 worktree、归档遗留内容，并按需删除分支。若某个仓库停在冲突或未提交的改动上，

它不会强制继续，而是指出受阻的仓库，待对应会话处理后再合并。

✨ 功能

• 从会话里建任务空间。 勾选要参与的仓库（默认全选）、给任务起名、定分支前缀、指定任务空间放哪。

每个参与的仓库都会得到一份位于 <分支前缀><任务名> 的 worktree（前缀默认 task/）。起点默认是各仓库

当前的 HEAD；面板另有一个下拉，列出所有已勾选仓库共有的分支，没有单独指定起点的仓库都从这里开始，

而每张卡片也可以只给那一个仓库另选起点。走工具调用时，baseRef / baseRefs 接受任意 ref（含提交）。

• 唯一一项交付选择：这个任务要不要部署验收。 任务信息最后就是一个勾选框 —— 部署到 Docker，

勾上后会多出一个 部署脚本 输入框（留空则用 工作区/.worktree-space/deploy/deploy.sh）。

它之所以在建的时候就问，是因为交付策略只在创建时落一次，事后没有入口能加、能改：没勾等于定了

「这个任务不做验收」，之后也不会有任何东西再提起这件事。反过来，勾了却找不到可用的入口脚本时

创建会被直接拒绝，而不是留一个永远部署不起来的任务空间。

其余收尾时的决定 —— 合到哪条分支、要不要删分支、冲突怎么办、遗留文档怎么处理 —— 都不在这里预定，

留给结束任务那一刻当场决定。

• 部署验收（勾了才有）。任务空间自带一个部署根：源码根的 .worktree-space/deploy/ 会被复制进来，

入口脚本提供 up（起环境、写验收地址）与 smoke（跑冒烟、把结果写进 .state.json）。

每个任务的环境身份互不相同，任务之间不会互相顶掉。合并之前有一道闸门：<部署根>/.state.json

里没有一条 result: "pass" 的 lastSmoke，合并就被拒；面板会问「冒烟还没过，仍要结束吗？」，

这份豁免只有人能给。

• 注册成工作区，名字是 <上级>/<任务名>，同时开一个会话，工作目录就是这个任务空间 —— 在任务空间里

改代码，不会动到源码检出。

• 管理页面，分三个视图（入口见「管理 Worktree Space」一节）：
• 工作区视图：哪些工作区可以建任务空间，以及每个工作区里有几个仓库；
• Git 仓库视图：扫到的每个 Git 仓库，以及它链接的 worktree；
• 任务空间视图：把每个任务下面的仓库列在一起（分支、改动数、是否被锁定、是否可清理），

任务行下面就是它的部署卡片。

• 给任务补仓库：任务进行到一半才发现少一个仓库时，在任务行上点「添加仓库」—— 候选就是 Git 仓库视图里

那一列，任务已经有的不会重复列出；也可以直接填一个仓库目录，它会注册成工作区，因此同样进入 Git 仓库视图。

新仓库在任务现有分支上开 worktree，起点默认各仓库当前的 HEAD，也可指定分支或提交。新仓库可以位于不同目录

甚至不同磁盘；只有在把提交交给 agent 时才可能需要批准提权（见使用指南）。本版本不支持从任务里移除仓库。

• 结束任务：在任务行上点「结束任务」，默认把各仓库的分支合并回它的目标分支、删掉 worktree、把任务

空间里的文档归档到选定的目录，最后注销这个工作区；任务空间里还有会话在干活时先拒绝。合并往哪儿做、

冲突怎么办，见「结束 Worktree Space」。

• 新建任务空间与结束任务空间也在工作区列表自己的 ⋯ 菜单里 —— 前者只对包含代码仓库的工作区显示，

后者只对确属任务空间的目录显示，点开的就是同一个对话框。

• 界面跟随 DSH 的语言设置，管理页、对话框、配置项与错误提示均有中英文。

勾了「部署到 Docker」的任务另有一层前提：这台机器上要有可用的容器引擎，见[部署验收](#-部署验收)。

📂 任务目录结构

术语：Worktree Space 容器（下称容器）＝插件存放任务空间的专用目录，也就是容器根目录

worktree-space/。下文每段第一次提到容器时写全称，同段之后用简称。

容器根是容器根目录的简称，指同一个目录：既指那个目录本身（区域），也指设置项里要填的路径（路径）。

~/workspace/                           根工作空间：项目都挂在这一层，也存放 Worktree Space 容器根目录
├── repo-x/                            项目 x 的主工作区（本身就是仓库）
├── project1/                          项目 1 的主工作区（下面若干仓库）
│   ├── repo-a/
│   └── repo-b/
├── deep-path/project2/                项目 2 的主工作区，目录位置埋得更深
│   ├── repo-c/
│   └── repo-d/
└── worktree-space/                    容器根目录：插件专用区
    ├── repo-x/                        项目层，名字就是源工作区目录名
    │   └── task-x/                    任务空间 —— 同时是会话的工作目录
    │       ├── .worktree-space/       插件专属目录：插件自己的东西全在这里
    │       │   ├── worktree-space.json  任务的记录：分支、起点、项目、仓库、部署策略与创建时间
    │       │   ├── worktree-space.md    由上面的记录渲染出来，给人读的分支、起点与约定
    │       │   └── deploy/              部署根：源码根 .worktree-space/deploy/ 的副本，.state.json 在这里
    │       └── repo-x/                位于 <分支前缀>task

…(truncated)