在 DSH 环境下开发多仓库项目时，智能体容易因忘记切换目录或分支而将代码写入错误位置。该插件通过构建多仓库功能工作区，确保每个功能在独立目录中运行，且所有组件仓库同步在同一个功能分支上。
插件介绍¶
这是一个 DSH 插件，用于多仓库功能工作区编排，由 TY-ang 维护。它将一组仓库绑定为一个“集”（Set），存储在 $DSH_HOME/worktree-flow/sets/<name>.json。在创建功能时，插件会为每个组件仓库创建一个 git worktree，所有 worktree 共享同一个功能分支。功能根目录被自动注册为 DSH 工作区，会话沙盒将精确落在这个功能范围内。
核心功能¶
- 多仓库功能工作区：每个功能对应一个目录，每个组件仓库对应一个 git worktree。
- 共享功能分支：所有组件 worktree 复用同一个功能分支，避免分支混乱。
- 自动注册为 DSH 工作区：功能根目录自动注册，会话可在此范围内操作。
- 沙盒隔离：会话只能写入功能根目录，无法触及主仓库或其他功能目录。
- 预创建分支：创建功能时即 checkout 到指定分支，写入默认落对位置。
- 身份说明注入：会话启动时自动注入当前功能布局和分支约束。
- 环境医生：诊断环境完整性，包括目录归属、Git 所有权、分支引用等。
- 自动发现：扫描参考目录邻近的 Git 仓库，支持批量绑定组件。
- 实时共享文档：支持配置项目级文档源，会话可直接读取最新内容。
- 分支类型自定义：支持自定义分支命名规则（如 Bugfix/功能/发布）。
安装与启用¶
使用以下命令安装插件（需指定 profile）：
dsh plugin --profile web add github:TY-ang/dsh-worktree-flow
安装后重启 dsh web。该包声明了 dsh.bundle，会自动加入配置文件堆栈。这是一个私有包，未发布到 npm registry。
典型用法¶
配置¶
进入 Settings → Worktree Flow 页面。在配置页创建“集”，绑定组件路径。支持选择非 Git 目录并初始化仓库。配置包含共享文档源、分支类型定义等。
命令操作¶
# 查看功能状态
/worktree status [feature]
# 创建新功能
/worktree create [name] --branch <full-branch> [--components a,b] [--base ref] [--set name] [--dry-run] [--register-components]
# 诊断环境
/worktree doctor [--set name]
# 同步现有功能，迁移旧版清单
/worktree sync
# 打开指定功能（确保已注册）
/worktree open <feature>
# 完成并归档功能
/worktree finish <feature> [--cleanup] [--force] [--keep-registered]
# 显示当前配置
/worktree config show [--set name]
适用场景与注意¶
适用场景：多仓库前端/后端/API 联合开发，需要严格的功能隔离和分支管理。
注意事项：
* 需要 Node.js >= 22。
* Worktree-root 和组件路径必须是绝对路径，支持 ~。
* Windows 环境下有严格限制：
* DSH 进程不能是高完整性或系统级别，需以普通用户身份运行。
* 组件创建依赖原生 git worktree add，需确保 Git 验证通过。
* 插件不会修改全局 git config、更改 Owner/ACL 或切换 Windows 用户。
* 请确保 DSH、Codex 和 IDE 运行在同一 Windows 账户下。
* 环境医生仅提供只读诊断，不自动修复环境或信任问题。
* 归档（finish）仅移除注册记录，不会删除文件和分支。
该插件通过物理隔离和预配置分支，解决了多仓库开发中的路径与分支混乱问题。适合需要严格功能隔离的开发流程。更多详情请访问 GitHub 或 SkillHub。
