任务工作区管理 JohnXu22786/worktree-mgr

worktree-mgr

为 dsh（DeepSeek Harness，运行在 Cordis 插件框架之上的插件化 harness）提供「任务隔离工作区」能力的插件。

模型并行处理多个任务时，每个任务都在独立的 git 工作区（git worktree）与独立分支中完成，互不污染主工作区；任务结束自动提交、合并、清理。整个生命周期——创建 / 同步 / 总览 / 收尾 / 批量清理——由 5 个工具 + 1 个 CLI 覆盖，全程零手工 git 操作。

核心概念

| 概念 | 说明 |
| 任务（task） | 一项独立工作，如 add-search-box。工具以任务名为入口 |
| 分支 | 由任务名自动派生：<prefix>/<任务slug>，默认 wtm/add-search-box，也可显式指定 |
| 工作区 | 位于 vault 目录下（默认平台数据目录 wtm/vaults/<仓库slug>/），与主仓库隔离 |
| 账本 | vault 下的 index.json，持久化「任务 ↔ 分支 ↔ 路径」映射（JSON 格式，原子写入 + 互斥锁） |
| 基分支 | 任务合并的目标分支，默认主工作区当前分支 |

特性

- 任务驱动：给模型一个任务名，分支名、路径、账本记录全部自动生成，无需指定分支
- 分支名安全：任务名 → slug 规范化（段内 ..、.lock 结尾、段首点等非法形态在源头修正），ref 合法性双重校验；不同任务派生同一 slug 时拒绝创建
- 未提交改动检测：基分支脏时拒绝合并（防止混入未完成工作）；任务工作区脏时默认自动快照提交
- 合并目标一致性：合并前校验「主工作区当前分支 == 账本基分支」「工作区当前分支 == 账本任务分支」，不一致一律拒绝——杜绝改动被提交到错误分支却报告成功的静默错误
- 同步与收尾分离：wtm_merge 只合并不清理，wtm_finish 提交→合并→删工作区→删分支→清记录；重试场景自动跳过已完成的合并（不产生重复空 merge 提交）
- 批量清理：wtm_purge 一次收尾多个任务，单任务失败不中断其余，任一失败即非零退出码
- 仓库级配置：<仓库根>/.wtm.json 支持分支前缀、消息模板、种子文件（带路径越界防护）、生命周期触发器（固定工作目录）
- 并发安全：账本写操作带互斥锁——锁内含唯一 token 与心跳刷新，陈旧锁仅在进程崩溃后回收，释放时绝不误删后继持有者的锁
- 失败恢复：创建中途失败自动回滚已创建的 worktree 与分支；合并冲突给出 git merge --abort 恢复指引
- 跨平台：Windows（cmd）与 POSIX（sh）触发器执行；路径比较大小写/分隔符归一化
- 零依赖、免构建：纯 Node ESM，node >= 21 即可，安装即用

安装

在 DSH 中安装（从 GitHub）

从 GitHub 安装最新版本到 profile：

dsh plugin --profile demo add github:JohnXu22786/worktree-mgr

移除：

dsh plugin --profile demo remove worktree-mgr

方式一：作为 dsh bundle 安装（推荐）

在包含本目录的路径下：

dsh plugin --profile demo add ./worktree-mgr

- package.json 声明了 dsh.bundle.patch → cordis.patch.yml，dsh 会自动把插件行插入 profile 的配置层；
- 该层默认 root: !!js process.cwd()（以 dsh 启动目录为主仓库），可按需覆盖；
- 本包为纯 JavaScript，无构建步骤，从 git 安装也不会缺产物。

方式二：overlay 加载（不装进 profile）

dsh --profile demo --patch ./examples/overlay.yml

overlay.yml 与插件行配置结构一致，适合临时挂载或改配置。

方式三：独立 CLI

npm link # 或 node bin/wtm.js ...
wtm begin "Add Search Box"

快速开始

1. 为任务创建隔离工作区（自动派生分支 wtm/add-search-box） wtm begin "Add Search Box"

2. 在 <vault>/add-search-box 中自由修改代码（或让模型在任务工作区目录中工作）

3. 查看所有任务的状态（脏/领先/落后） wtm status

4. 只同步不回填清理：把任务改动合并回基分支，工作区保留 wtm merge "Add Search Box"

5. 收尾：快照提交 → 合并 → 移除工作区 → 删除分支 → 清账本 wtm finish "Add Search Box"

6. 批量收尾 wtm purge "Task A" "Task B" # 指定任务 wtm purge --all # 全部任务

所有命令支持 --json 输出结构化结果，便于脚本与 harness 消费。

CLI 参考

bin/wtm.js 可独立使用（npm link 后为 wtm，或 node bin/wtm.js）；每个子命令都支持 --json，结构化结果输出到 stdout。

| 命令 | 说明 | 退出码 |
| wtm begin <task> | 创建隔离工作区（--base、--branch、--note、--root） | 0 成功 / 1 失败 |
| wtm merge <task> | 任务分支合并回基分支，工作区保留（--mode、--message） | 0 / 1 |
| wtm finish <task> | 收尾并清理（--mode、--message） | 0 / 1 |
| wtm status | 全部任务总览 | 0 / 1 |
| wtm purge [task...] | 批量收尾；--all 表示全部 | 0，任一任务失败为 1 |
| wtm help | 打印用法 | 0（裸 wtm 为 2） |

退出码语义：0 成功；1 操作失败（--json 模式下失败信息在 JSON 载荷中，且 purge 任一子任务失败同样为 1）；2 用法错误（未知或缺失命令）。WTM_ 环境变量对 CLI 同样生效。

工具接口（模型可见）

| 工具 | 作用 | 关键参数 |
| wtm_begin | 为任务创建隔离工作区 | task(必填), base, branch, note, root |
| wtm_merge | 同步：任务分支合并回基分支（工作区保留） | task(必填), mode(commit/refuse), message, root |
| wtm_finish | 收尾：提交→合并→清理工作区与分支 | task(必填), mode(commit/abandon/keep), message, root |
| wtm_status | 任务总览（存在性/脏状态/领先落后） | root |
| wtm_purge | 批量收尾 | tasks, all, mode, message, root |

mode 语义

- commit（默认）：先自动快照提交任务工作区的未提交改动，再合并回基分支，最后清理
- refuse：任务工作区有未提交改动时直接拒绝（仅 wtm_merge）
- abandon：丢弃任务全部改动，强制清理工作区并删除分支（不可恢复，谨慎使用）
- keep：仅解除管理，工作区与分支原样保留（仅 wtm_finish）

安全边界（工具与 CLI 一致）：

- 基分支工作区存在未提交改动 → 拒绝合并（wtm_merge / wtm_finish 的 commit 模式）
- 主工作区当前分支与账本基分支不一致、任务工作区当前分支与账本记录不一致 → 拒绝操作（防止改动落错分支）
- 任务分支已存在、任务已登记、工作区目录已存在、不同任务派生同一工作区路径 → 拒绝创建
- 任务名或分支名非法（git ref 规则）→ 在任何 git 操作之前拒绝
- 种子文件路径越界（../x 等逃逸仓库/工作区）→ 拦截并告警
- 调用被取消（exec.signal abort）→ 干净返回；创建中途失败自动回滚已创建的 worktree 与分支

插件接入说明（harness 如何加载它）

本插件遵循 dsh 的标准插件协议，共三块拼图：

worktree-mgr/
├── package.json # ① dsh.bundle manifest：声明本包是一个配置层 ├── cordis.patch.yml # ② 配置层内容：向 profile 插入插件行 ├── index.js # ③ 入口模块：导出 name / inject / apply └── src/ # 实现：naming/config/vault/git/triggers/ops/tools

① bundle manifest（package.json）：

{
"name": "worktree-mgr",
"type": "module",
"main": "index.js",
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

② 配置层（cordis.patch.yml）：

- insert:
- id: worktree-mgr
name: worktree-mgr # 按包名解析，Node 模块解析找到 index.js config: root: !!js process.cwd()

③ 入口模块（index.js）导出：

export const name = 'worktree-mgr'
export const inject = ['tools'] // 声明依赖 tools 注册表
export function apply(ctx, config = {}) {
ctx.tools.register(...) // 注册 5 个工具
}

加载顺序：profile 组装 → 本 bundle 的 patch 层插入插件行 → 加载器等待 tools 服务就绪 → 调用 apply(ctx, config) → 工具 schema 自动汇入系统提示词，模型即可调用。

工具定义形态（与 dsh 工具约定一致）：

{
name: 'wtm_status',
description: '...', // 模型可见描述
parameters: { // JSON Schema 对象
type: 'object',
properties: {
root: { type: 'string', description: '仓库路径' }
}
},
output: {
schema: { type: 'object', properties: { ok: { type: 'boolean' }, ... }, required: ['ok'] },
render: (args, value) => [{ type: 'text', text: '...' }] // 模型可见内容
},
async execute(args, exec) { ... } // 返回规范 JSON；exec.signal 支持取消 }

事件/钩子接口：插件本身不订阅 harness 事件；生命周期扩展通过仓库级配置的 触发器（triggers）实现——在 on_begin / on_merge / on_finish 三个节点执行仓库配置的 shell 命令，注入 WTM_TASK / WTM_BRANCH / WTM_BASE / WTM_PATH / WTM_ROOT 环境变量。触发器有固定工作目录：on_begin 在新工作区内执行，on_merge / on_finish 在主仓库根目录执行。触发器失败只记警告，不中断主流程。

配置

优先级（低 → 高）：内置默认 < 插件行 config < 仓库 .wtm.json < 环境变量 WTM_

| 键 | 默认 | 说明 |
| root | process.cwd() | 主仓库路径（仅插件行/工具参数） |
| vault | 平台数据目录 wtm/vaults/<仓库slug>/ | 任务工作区与账本存放目录；相对路径按仓库路径解析 |
| prefix | wtm | 分支前缀，派生分支为 <prefix>/<slug> |
| commitMessage | chore(wtm): snapshot {task} | 快照提交模板，占位符 {task} {branch} {base} |
| mergeMessage | merge(wtm): fold {task} into {base} | 合并提交模板 |

环境变量：WTM_ROOT（工具与 CLI 均生效）、WTM_VAULT、WTM_PREFIX、WTM_COMMIT_MESSAGE、WTM_MERGE_MESSAGE（WTM_ROOT 优先级低于工具参数与插件配置）。

仓库级配置 <仓库根>/.wtm.json

{
"prefix": "wtm",
"vault": "D:/wtm-vaults",
"commitMessage": "chore(wtm): snapshot {task}",
"mergeMessage": "merge(wtm): fold {task} into {base}",
"seed": { "files": ["docs/AGENTS.md"] },
"triggers": {
"on_begin": ["pnpm install"],
"on_merge": ["pnpm lint"],
"on_finish": []
}
}

- vault 必须位于仓库工作树之外（否则主工作区会被 vault 目录持续弄脏，插件会直接拒绝）；
- seed.files：创建任务工作区时从主仓库复制到工作区的文件（如团队约定文档）；路径必须位于仓库/工作区内，越界条目会被拦截并告警；
- triggers.：生命周期钩子命令数组，见上文「事件/钩子接口」。

未知键会产生警告并被忽略；损坏的 .wtm.json 不阻塞操作，仅告警。

安全说明（重要）

- 仓库配置即代码：.wtm.json 的 seed.files 会把仓库内的文件复制进工作区，triggers. 会以当前用户权限执行任意 shell 命令。只应在可信仓库中启用本插件——克隆并操作不可信仓库时，仓库自带的 .wtm.json 等同于自动获得你的执行权限。无需此能力时留空 seed/triggers 即可。
- 快照提交包含未跟踪文件：任务工作区脏时，默认快照会 git add -A 提交全部改动（含未跟踪文件，如构建产物）。不想把大目录纳入历史，请先在任务工作区维护 .gitignore，或使用 refuse 模式手动处理。
- abandon 不可恢复：wtm_finish --mode abandon 与批量 wtm_purge 会强制删除工作区并删除任务分支（-D），其中的改动无法恢复，仅应在确认丢弃时使用。

账本与并发

- 账本：<vault>/index.json，{version: 1, records: [{task, branch, base, path, createdAt, updatedAt, note?}]}
- 写入原子（临时文件 + rename），且全程持有 .lock 互斥锁；
- 锁内含持有者唯一 token 与 30s 心跳刷新：进程崩溃后锁超过 5 分钟判定陈旧并回收；释放时校验 token，绝不误删后继持有者的锁；等待超时默认 5 秒。

开发与测试

npm test # node --test，零第三方依赖
npm run typecheck # 可选：需 dev 安装 typescript + @types/node

测试覆盖：命名规则、配置合并、账本（原子写/锁/陈旧回收/损坏恢复）、git 输出解析、触发器、生命周期编排（fake git 注入）、工具 schema、以及调用真实 git 的集成测试（begin → 改文件 → status → finish 全链路）。

目录结构

worktree-mgr/
├── package.json # bundle manifest + 元数据 ├── cordis.patch.yml # 插件配置层 ├── index.js # dsh 插件入口（name/inject/apply） ├── bin/wtm.js # 独立 CLI ├── README.md # 文档（EN） ├── README.zh.md # 文档（ZH） ├── LICENSE # MIT 许可 ├── src/ │ ├── naming.js # 任务名→分支映射与 ref 校验 │ ├── config.js # 配置合并与模板渲染 │ ├── vault.js # 账本持久化（原子写/锁） │ ├── git.js # git 执行层与输出解析 │ ├── triggers.js # 生命周期触发器 │ ├── ops.js # 生命周期编排（begin/merge/finish/status/purge） │ └── tools.js # dsh 工具定义 ├── examples/ │ ├── .wtm.json.example # 仓库配置示例 │ └── overlay.yml # dsh overlay 示例 └── tests/ # node:test 单元 + 集成测试

许可

MIT — 见 LICENSE。