Worktree Space

简体中文 · English · 更新日志

Worktree Space：一任务一空间，工作多路并行。把一个涉及一个或多个 Git 仓库的工作任务放进独立的任务空间目录——参与的每个仓库都在同一个任务分支上各开一个 worktree；任务空间自动注册为 DSH 工作区，agent 会话直接在任务空间里开工；多个任务各建一个任务空间并行推进、互不干扰。任务完成时可把任务分支合并回目标分支、移除 worktree，并将任务空间里遗留的文档归档到 指定目录；也可选择把未处理的提交和合并冲突交给 agent 处理。

[!IMPORTANT] Beta（实验性）：把提交和合并冲突交给 agent 处理的功能处于实验性验证阶段，行为可能继续调整；它默认 显示，如需隐藏这两个入口，将插件配置里的「交由 agent 解决冲突入口」设为「隐藏」（见实验性一节）； 本文档其余部分描述的是不借助 agent 的标准流程。遇到问题请在 GitHub Issues 里反馈。

📑 目录

• 🚀 安装
• ✨ 功能
• 📂 任务目录结构
• 🔧 环境要求
• 🔐 权限与失败边界
• 🛠️ 使用　⚙️ 配置 · ➕ 创建 · 🗂️ 管理 · 🏁 结束　各选项组合
• 🤖 实验性：把提交与冲突交给 agent　两个按钮 · 流程和步骤
• 📝 操作日志
• 📄 配套文档

🚀 安装

网页端，从命令行安装：

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

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

桌面端在插件管理页里操作：侧边栏 → 插件，在「插件包名」填 dsh-worktree-space，点「安装」； 卸载时在插件列表里点开 Worktree Space，进「插件详情」页，右上方点「卸载」按钮。

✨ 功能

• 从会话里建任务。 选源码根、给任务起名、选分支前缀、勾选要参与的仓库、指定任务空间放哪。每个仓库都会得到 一份位于 <分支前缀><任务名> 的 worktree（前缀默认 task/），起点可以是各仓库当前的 HEAD， 也可以指定某个分支或提交。

• 注册成工作区，名字是 <上级>/<任务名>，同时开一个会话，工作目录就是这个任务空间 —— Agent 可以 在任务空间里改代码，不会动到源码检出。

• 管理页面，分三个视图（两种入口与各自默认值见「管理 Worktree Space」一节）：

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

  三个视图都能搜索，也能用「待处理」筛出需关注的行（有改动、被锁定、可清理，或状态读取失败）； 每行左边的箭头能单独折叠，筛选旁的按钮可以一次全部展开或折叠。

• 给任务补仓库：任务进行到一半才发现少一个仓库时，在任务行上点「添加仓库」—— 候选就是 Git 仓库视图里 那一列，任务已经有的不会重复列出；也可以直接填一个仓库目录，它会注册成工作区，因此同样进入 Git 仓库视图。 新仓库在任务现有分支上开 worktree，起点默认各仓库当前的 HEAD，也可指定分支或提交。新加的仓库可以和原来的 仓库不在同一个公共目录、甚至不在同一个磁盘上：合并与收尾都不受影响（合并是逐仓库读它自己的源仓库做的）， 受影响的只是交接给 agent 提交时会话的工作目录盖不住那些源仓库的 .git，需要在那个会话里批准提权。 本版本不支持从任务里移除仓库。

• 结束任务：在任务行上点「结束任务」，默认把各仓库的分支合并回它的目标分支、删掉 worktree、把任务 空间里的文档归档到选定的目录，最后注销这个工作区；工作区里仍有会话运行时先拒绝。合并往哪儿做、 冲突怎么办，见「结束 Worktree Space」。

• 结束任务空间也在这个工作区列表自己的 ⋯ 菜单里 —— 只对确属任务空间的目录显示。

• 新建任务空间同样在那个 ⋯ 菜单里 —— 只对包含代码仓库的工作区显示，点开的就是同一个创建对话框。

• 界面完整支持中英双语。 管理页面、创建与结束对话框、配置项及其说明、按钮与错误提示，全部随 DSH 的语言 设置切换；插件向宿主注册 zh 与 en 两套文案（各 214 条），不自带语言开关。插件列表里的名称、描述与图标 只有英文一份。

• 无额外服务依赖。 入口开关、扫描深度和目录上限均由插件自身配置控制（见配置）。支持 DSH 主题。

• 可开关的操作日志。 容器根下的 worktree-space-log.jsonl 记录这个任务空间做过什么，默认开启， 排查和复现直接读它；见操作日志。

📂 任务目录结构

术语：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.json    任务的记录：分支、起点、项目、仓库与创建时间
    │       ├── worktree-space.md      由上面的记录渲染出来，给人读的分支、起点与约定
    │       └── repo-x/                位于 <分支前缀>task-x 的 worktree
    ├── project1/
    │   ├── hotfix/
    │   │   ├── repo-a/                都以 <分支前缀>hotfix 开 worktree
    │   │   └── repo-b/
    │   └── task-a/
    │       ├── repo-a/
    │       └── repo-b/
    ├── project2/                      目录位置埋得深不影响它落在同一个容器里
    │   └── task-b/
    │       ├── repo-c/
    │       └── repo-d/
    ├── archived-docs/                 归档根（默认）：非 Git 产物收在这里
    │   └── project1/                  按项目归档
    │       └── hotfix-20260926-020933/   「任务名-YYYYMMDD-HHMMSS」，每个任务一层
    ├── README.md                      第一次使用时由插件写入：这里是 Worktree 专用区
    └── worktree-space-log.jsonl   操作日志：插件发的每条 git 命令、每个错误与警告

~/my-archive/                          归档根：可以在插件设置改成指定的目录
└── project2/                          结构一样：项目一层，任务名加时间戳一层
    └── task-b-20260926-020933/

Worktree Space 容器根推荐落在根工作空间的下一层（~/workspace/worktree-space），放在哪儿只看路径上盘根下面的 第一个目录：所以 ~/workspace/project1 和 ~/workspace/deep-path/project2 推荐的是同一个 容器，项目各自埋多深都不影响。创建时仍可指定其它路径。

项目名就是源工作区目录名，插件自动分层，无需填写：同一个 Worktree Space 容器里跑多个项目时，各项目下同名的任务 （都叫 hotfix）因此各占一层，不会挤在一起。源工作区本身就是仓库时（工作区目录 = ~/workspace/repo-x）， 项目层与仓库层同名，得到 repo-x/task-x/repo-x —— 这处重复是有意接受的：布局深度恒定为三层，插件与 客户端都不需要额外信息就知道哪一层是哪一层。

Worktree Space 容器根是插件的专用区：第一次在这底下建任务空间时，插件会写一份 README.md 说明这里是 Worktree 专用区、 不要直接 git init 或 clone（已经有了就不覆盖）。反过来说，容器根本身要已经是 Git 仓库（下面有 .git）， 创建会被拒绝，且一个目录都不会建出来。

归档根底下再分两层：<项目>/<任务名>-<YYYYMMDD-HHMMSS>/。归档结构因此与 Worktree Space 容器结构同形，一个项目的归档收在自己 那一层里；默认档就在容器根下，整块只多出 archived-docs 这一个目录和操作日志那个文件（见操作日志）。删掉 worktree 不会删除对应的 Git 分支；结束任务会先把分支合并回去，再删 worktree。

🔧 环境要求

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

四个官方版本逐个实测通过：0.1.7-rc.1、0.1.7-rc.2、0.2.0-rc.1、0.2.0-rc.2， 每个版本都用该版本自己的 DSH CLI 在一次性 profile 里跑通了安装、启动、卸载、回滚。这套验证覆盖的是 命令行与网页端的路径；桌面端（Electron）只做了人工安装可用性确认，未纳入脚本矩阵。逐条记录见 docs/store-evidence.md。

DSH 会强制校验清单里 peerDependencies 声明的 DSH 版本范围：运行时的版本不满足，就在安装前或启动时 拒绝加载，并给出 dsh plugin allow-version 的精确豁免命令。engines.dsh 之类的字段只是声明，不会阻止加载。 实测范围之外的版本一律按未知处理，不拿宽泛范围冒充证据；遇到版本相关的问题请到 Issues 反馈。

🔐 权限与失败边界

本插件在运行时会读写文件、并调用 git；这两类权限就是它的功能本身，无法裁剪为零。运行期依赖都由 DSH profile 提供，不随插件分发 —— 安装本插件不会引入新的运行期第三方依赖，也不连接任何外部服务、不上报遥测。

权限一览：

权限	范围
文件读取	所选工作区目录（广度优先扫描，跳过 node_modules、dist、build、vendor 与隐藏目录，.worktrees 除外）；任务空间与 Worktree Space 容器根下的记录文件；各 worktree 的 .git 标记文件；结束任务时为判断合并是否仍留冲突而读回变更文件的内容
文件写入	只写任务空间与 Worktree Space 容器根下的文件，以及配置选定的归档目录（见配置），结束时删除的是插件自己创建的 worktree 与文档；合并时另在系统临时目录里建一份临时检出，用完即删。不写源码仓库检出里的文件，也不写 DSH 数据目录
命令执行	只调用 git（git -C <目录> <子命令>，固定参数、不经 shell，全部走同一处 runGit）。add 与 commit 不在其中：插件不代写提交，未提交的改动会让该仓库停下（见下表）；交给 agent 的提交由宿主里的那个会话自己执行
操作日志	容器根下的 worktree-space-log.jsonl，默认开启：改动仓库状态的 git 命令、任何失败的 git 命令、每个操作的结论、每个错误与警告（带错误码）。可在插件设置里关掉，关掉不影响已有文件。不含任何文件内容，URL 里的凭据写入前抹掉；不发送到任何地方，不离开这台机器
网络	无：插件自身不发任何 HTTP 请求，也不执行任何 git push；它发出的 git 子命令全是本地操作
凭据	不读取、不保存、不转发；插件不接触密钥
全局资源	不装全局包、不起常驻进程或服务、不写系统目录

逐条说明（读什么、写什么、执行哪些子命令、失败时怎么办）见 PERMISSIONS.md； 一次性 Profile 的安装、启动、卸载与回滚验收证据见 docs/store-evidence.md。

失败边界（绝不静默）：

情形	行为
扫描目录数超过上限	抛错并提示 Worktree scan limit reached; choose a more specific Workspace.，请换一个更具体的工作区
任一 git 命令失败	抛出 git <参数> failed (exit N): <stderr>，把 Git 自己的诊断原样带出
结束任务时某仓库还有未提交的改动	停下该仓库（force 才丢弃）：uncommitted work is waiting in <worktree>; commit it before the task can be finished；插件不代写提交，其余仓库继续，结果里逐条报出
合并已解决但没有提交	the merge in <worktree> is resolved but not committed，现场原样保留
解决后的文件里仍有冲突标记	the resolved merge still has conflict markers in <files>，原样保留，不替任何一方取舍
试合并撞上冲突	不自动 merge --abort，保留合并现场（mergeSite 与 conflictedFiles），待解决并提交后可继续
真合并撞上期间的新提交	试合并通过后，真合并时目标分支出现新提交，插件撤销本次合并（merge --abort，分支恢复原状）并原样带出 Git 的诊断；worktree 与任务分支保留，再次点「继续结束任务」会重新试合并
worktree 删除失败	报 failed to remove the worktree (uncommitted changes? force it deliberately)，保留该 worktree 并报告，可用 git worktree prune 清理
任务目录非空	保留目录与工作区注册，不强行删除
无法确认的事实	在文档里写「未知」，不把「没有搜到」推断成「不访问」

🛠️ 使用

⚙️ 配置

在界面里改（推荐）：侧边栏 →「插件」→ Worktree Space →「插件详情」页的配置区，和其它插件的配置在同一处， 保存后立即生效，无需重启。也可以直接改配置文件：DSH 数据目录下 profiles/<profile>/cordis.patch.yml 里这个插件的 config: 区块，改完重启 DSH 生效。

设置	取值	默认	说明
面板入口（新会话下方）	显示 / 隐藏	隐藏	侧边栏面板列表里那一行，整页打开管理页面（页面自带左侧导航和「返回会话」）；默认隐藏
侧边栏底部入口	显示 / 隐藏	显示	侧边栏底部那个快捷入口，以对话框打开同一个管理页面
交由 agent 解决冲突入口	显示 / 隐藏	显示	结束任务对话框里「交由 agent 提交」「交由 agent 解决冲突」两个实验性入口；隐藏时走标准流程：自己提交、自己解决冲突，再点继续结束任务
扫描深度	1–5 层	3 层	从工作区目录（第 0 层）往下找 Git 仓库的层级数
最大遍历目录数	500 / 1000 / 2000 / 3000 / 5000 / 10000	2000	一次扫描最多读取的目录数；超出上限时提示改用更小的工作区
扫描忽略的目录名	任意目录名列表	内置 23 个	扫描永远不会进入这些名字的目录。插件自带 23 个各语言的依赖与编译输出目录（node_modules、target、__pycache__、Pods 等），可以添加自己的，也可以移除内置的——移除内置项需要二次确认，因为代价落在下一次扫描上。最多可添加 200 个。名字不区分大小写；点右侧「修改」打开对话框，可搜索、增删，保存后才写入配置
默认分支前缀	任意文本	task/	新建任务空间时默认用的前缀；在新建面板里改动并勾选「设为默认分支前缀」，点创建时一并写回这里
Worktree Space 容器根目录	默认 / 指定目录	默认	新建任务空间默认放哪。推荐用默认：它按下面的规则从源工作区推导，落在根工作空间的下一层，因此同一根工作区下的所有项目——无论各自埋得多深——都会落进同一个容器，彼此的任务不会挤在一起。若改用指定目录，而它与项目目录没有公共目录，agent 处理提交与冲突的会话需要手动提权
指定 Worktree Space 容器根目录	任意路径	留空	只在「指定目录」这一档生效；留空则按推荐规则推导。新建面板里改动 Worktree Space 容器根并勾选「设为默认 Worktree Space 容器根目录」，点创建时把这两项一并写回
归档文档位置	跟随容器根 / 指定目录	跟随容器根	归档文档存到哪个根目录下；两档都在该根目录下再建一层 <项目>/<任务名>-<YYYYMMDD-HHMMSS>，时间戳是归档那一刻的本地时间，精确到秒。默认档收在 Worktree Space 容器根自己的 archived-docs 里，与任务空间建在哪一层无关
指定归档目录	任意路径	留空	只在「指定目录」这一档生效；留空则收在 Worktree Space 容器根的 archived-docs 里

扫描覆盖全部工作区；按广度优先逐层进行，每层最多同时读 8 个目录。任何一层只要发现 .git 就认定是 仓库；node_modules、dist、build、vendor 等目录和隐藏目录会跳过（.worktrees 除外）。

➕ 创建 Worktree Space

术语：源码根＝交给插件的工作区目录（它自己是一个仓库，或者它顶层装着若干仓库）；源码树＝该 目录连同下面的一切。新建对话框里的提示把它称作「仓库目录」。

1. 在会话里，点输入框上方的 新建 Worktree Space。
2. 为任务命名 —— 会转成小写，空格、中文和其它字符都换成连字符（hotfix-placeorder）；名字不合法时 给出具体原因。
3. 按需修改 分支前缀。分支名就是这个前缀加上任务名；留空则用配置里的默认前缀（默认 task/）， 输入框下方显示当前生效的前缀。所填前缀与默认前缀不一致时，才会出现 设为默认分支前缀 勾选框 —— 勾选后，点「创建并打开」时把该前缀写回插件设置。
4. 设置任务空间放哪 —— 也就是 Worktree Space 容器根，要放在仓库目录旁边（不在它里面，也不是它的上层目录）。界面 会填好推荐值：根工作空间的下一层 worktree-space，通常无需修改；也可指定其它路径，此时输入框下方 会出现 设为默认 Worktree Space 容器根目录 勾选框，勾选后，点「创建并打开」时把该路径写回插件设置， 其下方的说明注明该选择的代价。推荐规则和目录结构见任务目录结构。
5. 勾选任务要参与的仓库（每张仓库卡片上标出它当前 HEAD 所在的分支），并选择分支起点。
6. 点 创建并打开。新工作区会直接开一个会话，工作目录就是任务空间。

如果任务空间已经建好、但工作区注册失败，对话框说明原因，并提供重新注册的入口。注册之后它就是一个正常的任务空间，可以走结束任务正常收掉。

🗂️ 管理 Worktree Space

打开 管理页面，两种入口：

• 侧边栏底部的 Worktree Space（默认显示）—— 以对话框打开；
• 侧边栏「新会话」下方的 Worktree Space 行（默认隐藏，在配置里打开）—— 在主区域整页打开。

两种形态共用同一条左侧导航：整页形态的第一项是 返回会话（面板占用会话所在的主区域，故保留返回入口）， 下面三项切换视图；导航底部是 ⚙ 插件设置，跳到宿主的插件页改本插件的配置。

三个视图的区别见功能一节：工作区视图展示可建任务空间的工作区，Git 仓库视图展示扫描到的每个 Git 仓库及其 worktree，任务空间视图展示每个任务及其各仓库。 右侧的统计会跟着视图变（N 个任务 / N 个工作区 / N 个仓库 · M 个 Worktree），搜索或筛选时显示 可见 / 总数。

面板每次打开都会重新扫描，但会先用宿主缓存的上一次扫描结果绘制界面，打开即可显示数据，扫描 结束后自动更新（标题栏会显示「正在扫描所有工作区…」）。这份记忆只放在 DSH 实例的内存里：既不写磁盘， 也会在实例关闭时随之清空。

🏁 结束 Worktree Space

在任务行上点 结束任务，或在工作区列表的 ⋯ 菜单里点 结束任务空间。对话框会先说明接下来会 发生什么：未提交的文件、待合并的提交、合并到哪个分支，以及任务空间里的文档（确实有东西可归档时， 才会出现「归档文档」选项）。「合并回目标分支」默认选中；「删除分支」和「强制」默认不选。

结束任务空间是一条标准流程，分三步：

1. 提交：未提交的改动须先由用户提交，插件不代为提交。 只要计划里还有未提交改动的仓库、而「强制」没勾， 「确认结束任务」就一直不可用——这些改动不是插件这一侧能写的，worktree 也不会带着它们被移除。计划下方 会逐个点名这些仓库，并列出各自的改动数。在各自的 worktree 中执行 git add 与 git commit（提交信息由用户编写）； 提交后关闭并重新打开对话框——对话框每次打开都会重读计划，那些仓库就不再拦着「确认结束任务」了。 也可勾选 强制，即放弃这些改动，它们会随 worktree 一并丢弃。需要代为处理时， 交由 agent 提交会把提交工作交给一个 agent 会话（见实验性一节）。正处在未完成合并中的仓库不走这 一步，那一份交给第 3 步。

2. 合并：先反着试一次，再正着合。 真正的合并是把任务分支合并进目标分支（默认是该仓库源检出 所在的分支），落点在源仓库身上。但在动目标分支之前，插件先在任务空间自己的 worktree 里反着试 一次：把目标分支合进任务分支。两种结果：

• 干净：把这次试合并撤销掉（worktree 回到试合并前的样子），再按常规把任务分支 --no-ff 合并进 目标分支——目标分支上留下的是正常的合并提交，历史顺序不变。目标分支若没被任何 checkout 占用，就在 一个临时 worktree 里合并（合并完丢弃），源检出不动。
• 冲突：不中止、不还原，这次试合并就停在任务分支的 worktree 里——该 worktree 保持 MERGE_HEAD， 冲突文件带着冲突标记、原样躺在该 worktree 的工作区里（例如 ~/workspace/worktree-space/project1/hotfix/repo-a/src/app.ts）。 目标分支未被触碰，源仓库的检出也不变。

为什么反过来试：真合并一旦冲突，现场就落在源仓库及其检出上，需要中止并逐处取舍；先反着试一次， 冲突就落在插件自身的 checkout（任务分支的 worktree）里——该处可就地处理，且不触碰源码检出。

3. 冲突：停止，等待用户在现场解决。 只要有仓库停在冲突上，整个结束操作就是部分完成 （failed: true，Worktree Space 容器保留，其余仓库可能已经合并并移除）。结果里每个仓库行给出 mergeInProgress、 mergeSite（冲突现场所在目录）和 conflictedFiles。对话框此时显示「发生合并冲突，请处理后重新结束 任务。」，往下走的入口是面板底部的 继续结束任务。

现场就是任务分支自己的 worktree（例如 ~/workspace/worktree-space/project1/hotfix/repo-a），它正处在一次未完成的合并里。 在现场将冲突解决、git add，再用一条说明取舍的 git commit 完成本次合并提交——目标分支和 源仓库的检出全程未被触碰；提交要落在那个 worktree 上，它的索引在源仓库的 .git/worktrees/<名字>/ 下。 需要由 agent 处理该冲突时，使用 交由 agent 解决冲突（见实验性一节）。

点 继续结束任务 之后重复同一套判断：目标分支已经在任务分支里就跳过试合并、直接做真正的合并；否则 再试一次，冲突仍原样保留在该 worktree 中，由用户再次解决。

如果现场还留着没提交的解决结果、或者文件里仍有冲突标记，插件不替它提交，而是原样保留该现场并 提示用户处理，处理完成后再点 继续结束任务。

「删除分支」平时需要先有合并：不选合并，它也一起不可用。要放弃一个任务空间而不是结束它 ——什么都不合并，worktree 移除、分支连同上面的提交一起丢弃——同时选中「强制」即可，那是唯一允许 删除未合并分支的方式；放弃也是唯一跳过第一步提交的组合。

各选项组合的行为

合并回目标分支	删除分支	强制	会发生什么
✓			「确认结束任务」先不可用：自己把每个 worktree 里的未提交改动提交到各自的任务分支（不提交就一直停在这一步，结果点名那个 worktree），再把任务分支以 --no-ff 合并进它那一行选定的目标分支（默认是该仓库源检出所在的分支）；移除 worktree；分支保留。停在冲突上的仓库原地保留、其余照常结束
✓	✓		同上，并在合并成功后删除分支（git branch -d，所以未合并的分支删不掉）
✓		✓	合并照做，但强制跳过提交那一步：worktree 里未提交的改动随 worktree 一起丢弃，插件不代为提交；分支保留
✓	✓	✓	合并、强制删除分支（git branch -D）；分支已合并，所以并不额外丢东西
			什么都不合并：「确认结束任务」先不可用；自己把改动提交掉（改动留在保留下来的分支上），再移除 worktree 和任务空间，分支保留（随时可以自己合）
		✓	同上但不提交：未提交的改动随 worktree 一起丢弃；分支保留
	✓	✓	放弃：不合并、不提交，强删分支，分支上未合并的提交连同 worktree 里未提交的改动一并丢弃

无论哪种组合，有三条不变：

1. 元数据总是被清除。 任务空间里插件自己生成的两份记录 —— worktree-space.json 和由它渲染出的 worktree-space.md —— 每次结束都会清掉。更早的空间里还可能留着 README.en.md，它同样会被清除；最早期 还会有另一份插件自己写的 README.md，那个不清除——不假定它归本插件所有。
2. 其余内容按「归档文档」的选择处理。 不选就直接丢弃。
3. 没做完的仓库原样保留。 改动没人提交、或者合并停在冲突上的仓库会原样保留、记为未完成（其余仓库照常 结束），任务空间目录和它的工作区注册也因此都留下。

反过来，只有所有仓库都真的移除了、任务空间目录下不再剩下 worktree，任务空间目录和工作区注册才会一起删除，其中的会话落到「未分组」但对话记录保留。

「结束任务」按钮的颜色跟着这件事走：橙色是常规收尾（合并可以回退，没有东西被丢）；只有对话框能 明确列出「哪些内容将被丢弃」时才是红色——也就是选择放弃任务空间（不合并、强制删分支），而 worktree 里还有未提交的文件、或者分支上还有未合并的提交。

🤖 实验性：把提交与冲突交给 agent

本节功能默认显示：如需隐藏，将插件配置里的「交由 agent 解决冲突入口」设为「隐藏」。隐藏时结束任务走 标准流程，插件不代写提交、也不代为取舍冲突——它会停下并交代清楚现场：未提交的改动须在各自 worktree 中 提交，冲突解决并提交后点「继续结束任务」，提示行说的就是这条路径。

结束任务时，插件可开启一个 DSH agent 会话代为完成两件事：提交未提交的改动、解决停在冲突上的合并。

两个按钮和它们做什么

• 计划里有未提交改动的仓库 → 交由 agent 提交：开一个会话，把每个 worktree 的改动 git add 并提交， 提交信息说明改动内容与改动原因（语言和风格随该仓库已有的提交）。
• 有仓库停在合并冲突上 → 交由 agent 解决冲突：开一个会话，读两边的变更、弄清各自想做什么，写出同时保留 双方意图的版本，git add 之后用一条说明取舍方式的提交信息执行 git commit，完成本次合并提交。

两种情形都：不 push，不动其它仓库或任务空间，不把分支合并回目标分支——那一步是插件的。

这些仓库共用一个会话（冲突阶段同一个仓库已有第 1 步开的那个会话时，直接复用）。工作目录取它们边界的共同 祖先：仓库的边界是它的 worktree，宿主报出了主检出路径时是「worktree 与主检出」的共同祖先。共同祖先只剩 盘根时（仓库跨盘，或任务空间与仓库都直接放在盘根下）也仍然只有一个会话，工作目录取任务空间，提权 在那个会话里批准。

流程和步骤

1. 计划里有未提交改动时点 交由 agent 提交：插件开一个会话并交办。勾了 强制 时这一步跳过，也不开 会话。
2. 会话结束后，插件重读一次计划（每个 job 一次；会话仍在运行时重新武装这次读取）。
3. 读到的计划里那些仓库都没有未提交文件时，标题换成绿状态灯加绿字：提交阶段「已完成提交，可以继续 结束任务」，冲突阶段「合并冲突已处理完成，可以继续结束任务。」
4. 点 确认结束任务 或 继续结束任务 接着走。
5. 停在冲突上时点 交由 agent 解决冲突，重复第 2-4 步。
6. 只改了文件却没提交（或冲突标记还在）时，插件不代为提交：现场原样保留，结果中写明未完成， 由用户收尾后再点 继续结束任务。
7. 第三步的试合并：agent 把目标分支合进任务分支并提交之后，按 继续结束任务 时「目标分支是否已经在 任务分支里」通常答「是」，试合并直接跳过；只有目标分支又有人推了新提交，才照样先试一遍。

面板底部的 确认结束任务 或 继续结束任务 始终由用户操作确认才会执行。

📝 操作日志

容器根下有一个 worktree-space-log.jsonl，默认开着，记录这次任务空间里发生过的每一步：

• 改动仓库状态的 git 命令，以及任何一条失败的 git 命令（哪怕失败的是只读命令）。 成功的只读查询不记，否则文件会被 git status 的回声淹没。
• 每个操作的结论：创建成功还是失败、结束任务收掉了哪些 worktree。
• 插件遇到的每个错误和警告，带一个错误码，码能直接定位到源码里出问题的那一行。

开关： 插件设置里可以关掉。关掉只是不再写新记录，磁盘上已有的日志原样保留—— 那常常是某次工作唯一的一份账。想清掉就自己删文件。

它不发送到任何地方，就是容器根下的一个文件；容器根被删，日志一起没。 写日志失败也不会影响任何操作。

📄 配套文档

文档	内容
PERMISSIONS.md	权限与失败边界的完整声明：读什么、写什么、执行哪些 git 子命令、失败时如何处理
docs/store-evidence.md	一次性 profile 的安装、启动、卸载与回滚验收步骤与逐版本记录
CHANGELOG.md	版本发布历史
GitHub Issues	问题反馈