前言¶
在 DSH 中处理多个并行任务时，任务之间如果共用同一个仓库工作区，容易出现变更污染、合并目标不清、收尾不一致的问题。JohnXu22786/worktree-mgr 是一个 dsh 插件，为任务自动创建隔离的 git worktree 工作区，并管理创建、同步、收尾的全生命周期。
定位¶
该插件由 JohnXu22786 维护，许可证为 MIT。它面向 dsh 提供任务隔离工作区，避免并行任务污染主工作区。插件提供 5 个模型工具与 1 个 CLI，并支持 --json 结构化输出。运行环境要求 node >= 21，为纯 Node ESM，无构建步骤。
核心能力¶
- 任务驱动：根据任务名自动生成分支、工作区路径和台账记录。
- 分支名安全：任务名 slug 规范化，并做双重 ref 有效性检查；不同任务派生相同 slug 时拒绝创建。
- 未提交变更检测：基分支有未提交变更时拒绝合并；任务工作区默认自动快照提交。
- 合并目标一致性：校验主工作区当前分支与台账基分支、任务工作区当前分支与台账任务分支；不一致时拒绝。
- 同步与收尾分离：
wtm_merge只合并；wtm_finish提交、合并、删除工作区、删除分支、清理记录。 - 批量收尾：
wtm_purge可批量处理多个任务，单任务失败不中断其余任务，且失败返回非零退出码。 - 并发安全：台账写入使用互斥锁，锁包含唯一 token 与心跳刷新，崩溃后回收旧锁。
- 失败恢复：创建失败自动回滚 worktree 和分支；合并冲突提供
git merge --abort恢复指引。 - 跨平台触发器：支持 Windows(cmd) 与 POSIX(sh)，路径比较规范化大小写与分隔符。
- 仓库级配置：
.wtm.json支持分支前缀、消息模板、种子文件（路径逃逸保护）和生命周期触发器（固定工作目录）。
安装与启用¶
安装到指定 profile：
dsh plugin --profile demo add github:JohnXu22786/worktree-mgr
移除：
dsh plugin --profile demo remove worktree-mgr
本地安装：
dsh plugin --profile demo add ./worktree-mgr
package.json 中声明 dsh.bundle.patch 为 ./cordis.patch.yml。
overlay 加载：
dsh --profile demo --patch ./examples/overlay.yml
独立 CLI：
npm link
wtm begin "Add Search Box"
典型用法¶
创建任务工作区：
wtm begin "Add Search Box"
查看状态：
wtm status
只合并，不执行收尾删除：
wtm merge "Add Search Box"
收尾：提交、合并、删除工作区、删除分支并清理记录：
wtm finish "Add Search Box"
批量收尾：
wtm purge "Task A" "Task B"
wtm purge --all
帮助：
wtm help
所有命令支持 --json。WTM_* 环境变量同样适用于 CLI。
安全边界¶
- 基分支有未提交变更时，拒绝合并。
- 主工作区当前分支与台账基分支不一致，或任务工作区当前分支与台账任务分支不一致时，拒绝操作。
- 任务、分支或工作区已存在，或不同任务派生相同工作区路径时，拒绝创建。
mode abandon会丢弃全部任务变更、强制清理工作区并删除分支，不可恢复。
适用场景与注意¶
适合需要在多个任务之间隔离工作区、希望统一完成合并与清理的 dsh 使用场景。
从权限角度看，插件会以当前 dsh 进程权限运行，执行前需确认其对仓库、文件系统与配置文件的访问符合预期。安装前应检查源码、许可证和 .wtm.json 等配置；本文所核实许可证为 MIT。
参考资料¶
- GitHub：https://github.com/JohnXu22786/worktree-mgr
- 目录页：https://www.skillhub.cn/plugins/JohnXu22786/worktree-mgr
