用途:在同一个仓库里为单个功能创建彼此隔离的本地工作区(Git worktree),尤其面向 Bun monorepo 与需要并发本地 Convex 开发的场景。核心契约是:一个功能一个分支、一个项目内 .worktrees/<branch-slug> 目录、一份复制的被忽略本地环境文件、一个隔离的运行时身份;只有依赖安装完成、本地目标均非生产、应用与本地数据库能在不与其他 worktree 共享端口和状态的情况下运行,才算就绪。
主要能力与步骤:
- 检查:从目标仓库和分支运行给定 preamble,读取 REPO_ROOT、IS_LINKED、IS_SUBMODULE、BRANCH 等状态,并读取根指令文件和包脚本。若非子模块的 linked worktree,则保留当前 worktree 继续 Bootstrap;否则在不改动源检出的前提下 fetch 远端,默认基于 origin/main 创建。
- 创建:设置短分支名与文件系统安全 slug,使用 .worktrees/<slug>。用 git check-ignore -q .worktrees 验证忽略状态,未忽略则先经仓库正常变更流程加入 .gitignore。创建命令为 git fetch origin main 与 git worktree add ".worktrees/$slug" -b "$branch" origin/main。源检出可以脏,但不得 stash、clean、reset、rebase、复制其被跟踪文件或基于其过期的 main 建分支。
- 引导:若为 Bun monorepo 或使用 Convex,完整阅读并遵循 BUN_CONVEX.md;否则使用仓库声明的包管理器与安装命令,优先使用仓库通用的 setup:worktree 脚本,但技能仍负责就绪判定并验证其效果。
- 就绪验证:确认分支与绝对路径正确、所需的被忽略 .env.local 文件位于相同相对路径(不打印值)、安装后 lockfile 未变、所有 Convex 选择器为 local:*、Convex URL 为回环地址、数据库状态位于本 worktree、分配的 app 与 Convex 端口在监听且不属于其他 worktree、应用在唯一 URL 上可响应、git status --short 无意外环境/依赖/生成文件变更。任一项失败则以 BLOCKED 报告具体命令与错误。
报告格式为 READY 或 BLOCKED,并列出 Worktree 绝对路径、分支与基线、复制环境文件数量(不显示值)、运行时 URL 与端口、验证命令与结果、摩擦点。清理时只停止工作目录属于该 worktree 的进程,仅在分支已合并、明确要求放弃或 POC 完成且结论已保存时,才从主检出运行 git worktree remove <exact-path>,并在工作不再需要时删除分支。
限制:技能未提供自动测试要求,除仓库所有者明确要求外不应运行或创建单元测试;不使用共享/云端数据库、缺失本地环境或端口冲突是该技能要防止的失败模式。价格、平台支持等未提供。