JohnXu22786/worktree-mgr

README 摘要

worktree-mgr 为 dsh （DeepSeek Harness，运行在 Cordis 插件框架之上的插件化 harness）提供「任务隔离工作区」能力的插件。 模型并行处理多个任务时，每个任务都在独立的 git 工作区 （git worktree）与独立分支中完成，互不污染主工作区；任务结束自动提交、合并、清理。整个生命周期—— 创建 / 同步 / 总览 / 收尾 / 批量清理 ——由 5 个工具 + 1 个 CLI 覆盖，全程零手工 git 操作。 核心概念 概念 说明 任务（task） 一项独立工作，如 add-search-box 。工具以任务名为入口 分支 由任务名自动派生： / ，默认 wtm/add-search-box ，也可显式指定 工作区 位于 vault 目录下（默认平台数据目录 wtm/vaults/ / ），与主仓库隔离 账本 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 bundle 安装（推荐） 在包含本…

分类