moai-workflow-worktree

MoAI 工作树管理

用于并行开发 SPEC 的 Git 工作树管理系统，提供隔离的工作区、自动注册以及与 MoAI-ADK 的无缝集成。

核心理念：每个 SPEC 都应拥有独立的工作区，从而实现真正的并行开发，避免上下文切换带来的开销。

快速参考（30 秒）

什么是 MoAI 工作树管理？ 一种专用的 Git 工作树系统，可为每个 SPEC 创建隔离的开发环境，实现无冲突的并行开发。

主要功能：

• 隔离工作区：每个 SPEC 都有自己的工作树，Git 状态彼此独立
• 自动注册：工作树注册表会跟踪所有活动工作区
• 并行开发：可同时开发多个 SPEC
• 无缝集成：适用于 /moai plan、/moai run、/moai sync 工作流
• 智能同步：需要时自动与基础分支同步
• 自动清理：自动清理已合并的工作树

快速访问：

• CLI 命令：请参阅 Worktree Commands Module，位于 modules/worktree-commands.md
• 管理模式：请参阅 Worktree Management Module，位于 modules/worktree-management.md
• 并行工作流：请参阅 Parallel Development Module，位于 modules/parallel-development.md
• 集成指南：请参阅 Integration Patterns Module，位于 modules/integration-patterns.md
• 故障排除：请参阅 Troubleshooting Module，位于 modules/troubleshooting.md

使用场景：

• 并行开发多个 SPEC
• 隔离的测试环境
• 功能分支隔离
• 代码审查工作流
• 实验性功能开发

---

实施指南（5 分钟）

1. 核心架构 - 工作树管理系统

用途：为并行开发 SPEC 创建隔离的 Git 工作树。

主要组件：

1. 工作树注册表 - 跟踪所有工作树的中央注册表
2. 管理器层 - 核心工作树操作，包括创建、切换、移除和同步
3. CLI 界面 - 易于使用的命令界面
4. 模型 - 用于存储工作树元数据的数据结构
5. 集成层 - MoAI-ADK 工作流集成

注册表结构：

注册表文件以 JSON 格式存储工作树元数据。每个工作树条目包含标识符、文件路径、分支名称、创建时间戳、上次同步时间、状态（活动或已合并）以及基础分支引用。配置部分定义工作树根目录、自动同步偏好设置，以及已合并分支的清理行为。

文件结构：

工作树系统会在用户的全局主目录中创建专用目录结构。通过 moai worktree new <name> 创建的工作树位于主目录项目根目录下（/worktrees/projects///）；L2 持久注册表仍位于工作树根目录（~/.moai/worktrees/{ProjectName}/），其中包含中央注册表 JSON 文件和各个 SPEC 的独立目录。每个 SPEC 目录都包含用于存储工作树元数据的 .git 文件，以及项目所有文件的完整副本。

详细参考：请参阅 Worktree Management Module，位于 modules/worktree-management.md

---

2. CLI 命令 - 完整命令接口

用途：将每项 worktree 任务映射到实际执行该任务的命令。

进入 worktree 是启动器的职责——moai worktree 没有创建动词：

• moai cc -w <name> — 在 worktree 中工作
• moai cc -w <name> --spawn — 在新的 tmux 窗口中打开 worktree，同时保留当前会话

检查 worktree 时，直接使用 git：git worktree list。

管理命令如下，由 moai worktree --help 列出：

命令	用途
sync [branch-name]	将 worktree 与基础分支同步
remove [path]	移除 worktree
clean	清理过时的 worktree 引用
recover	修复 worktree 注册表
done [branch-name]	完成 worktree 并清理
snapshot	捕获工作树状态快照，以供防护验证
verify	根据快照验证工作树状态，并检查 Agent 响应
restore	将工作树恢复到快照中的 HEAD 状态

此表是帮助输出的副本。moai worktree --help 是权威列表；两者不一致时，以帮助输出为准。

详细参考：请参阅 modules/worktree-commands.md 中的 Worktree 命令模块。该模块中的命令示例早于当前命令集；如与上表不同，以本表和 moai worktree --help 为准。

---

3. 并行开发工作流 - 隔离的 SPEC 开发

用途：实现真正的并行开发，无需切换上下文。

工作流集成：

在使用 /moai plan 的规划阶段，会创建 SPEC，启动器（moai cc -w <name>）会进入对应的隔离 worktree。

在开发阶段，隔离的 worktree 环境提供独立的 Git 状态，无需切换上下文。

在使用 /moai sync 的同步阶段，worktree 同步命令可确保顺利集成，并支持冲突解决。

在清理阶段，worktree clean 命令会自动清理并维护注册表。

并行开发的优势：

1. 上下文隔离：每个 SPEC 都有自己的 Git 状态、文件和环境
2. 零切换成本：可即时切换 worktree
3. 独立开发：可同时处理多个 SPEC
4. 安全试验：为实验性功能提供隔离环境
5. 顺利集成：自动同步并解决冲突

工作流示例：

首先，为 SPEC-001 创建一个 worktree，并填写类似“用户身份验证”的描述，然后切换到该目录。接着运行 /moai run SPEC-001，在隔离环境中开发。然后返回主仓库，为 SPEC-002 创建另一个 worktree，并填写“支付集成”作为描述。切换到该 worktree，运行 /moai run SPEC-002 进行并行开发。需要时，可在不同 worktree 之间切换并继续开发。最后，在准备好集成时，同步两个 worktree。

详细参考：请参阅 modules/parallel-development.md 中的并行开发模块。

---

4. 集成模式 - MoAI-ADK 工作流集成

用途：与 MoAI-ADK Plan-Run-Sync 工作流无缝集成。

集成点：

在 Plan 阶段与 /moai plan 集成时，创建 SPEC 后，通过启动器进入 worktree：在其中运行 moai cc -w <name>，或运行 moai cc -w <name> --spawn 在新的 tmux 窗口中打开它。

在 Development 阶段与 /moai run 集成时，worktree 隔离可提供干净的开发环境，独立的 Git 状态可避免冲突，并自动跟踪注册信息。

在 Sync 阶段与 /moai sync 集成时，创建 PR 前运行 SPEC 对应的 sync 命令。PR 合并后，运行带有 merged-only 标志的 clean 命令，以移除已完成的 worktree。

自动检测模式：

系统会检查父目录中的注册文件，以检测 worktree 环境。检测到后，会从当前目录名称中提取 SPEC ID。

配置集成：

MoAI 配置支持 worktree 设置，包括用于自动创建 worktree 的 auto_create、用于自动同步的 auto_sync、用于自动清理已合并分支的 cleanup_merged，以及用于指定 worktree 目录位置并替换项目名称的 worktree_root。

详细参考：参阅 Integration Patterns 模块，位于 modules/integration-patterns.md

---

5. --spawn — 在新的 tmux 窗口中启动队友会话

用途：在 worktree 中启动 Claude 或 GLM 会话，同时保留当前会话。

启动命令（moai cc、moai glm）通常会替换正在运行的 shell，这适用于“现在在这里工作”，但无法实现“继续工作，并在旁边启动队友”。--spawn 会改为在新的 tmux 窗口中重新执行相同命令，然后返回，以便调用方继续工作。

与 -w <name> 组合使用时，只需一条命令即可在隔离的 worktree 中打开队友会话：

moai glm -w feat-auth --spawn   # Explicit all-GLM session in .claude/worktrees/feat-auth
moai cc -w feat-auth --spawn    # Claude teammate, same worktree
moai glm -w feat-auth --spawn   # all-GLM teammate

行为：

• 新窗口以分离模式创建，因此焦点仍留在调用方的窗格中。打印出的窗格 ID（例如 %7）可用于切换到该窗格。
• 启动的窗口从项目根目录开始，因此较短的 -w <name> 值会解析为 .claude/worktrees/<name>/（若 <MoaiHome>/worktrees/projects/<project-key> 下存在同名 worktree，则会重新进入该 worktree）。
• --spawn 由 MoAI 处理，不会传递给 Claude Code。-- 透传标记之后的参数保持不变。
• 参数会进行 shell 引号处理，因此包含空格或 shell 元字符的 worktree 名称也能完整传递给启动的进程。

要求 — 如果不满足以下任一条件，系统会明确报错，而不会静默回退，因为回退会替换调用方的会话，正是 --spawn 要避免的情况：

缺少项	提示信息
$TMUX（未处于会话中）	tmux session required for --spawn
tmux 二进制文件	--spawn requires the tmux binary
PATH 中的 moai 二进制文件	--spawn needs the moai binary in PATH

这些检查运行前不会修改任何设置，因此拒绝执行不会影响环境。启动的命令会在新窗口中自行完成后端设置。

平台说明：tmux 仅支持 POSIX，因此 Windows 上无法使用 --spawn，并会提示缺少二进制文件。在原地通过 -w 进入 worktree 则适用于所有平台。

详细参考：启动器的 spawn 入口点——标志剥离、带 shell 引号处理的命令重构，以及 tmux 窗口调用。

---

高级实现（10+ 分钟）

同步策略

默认情况下，moai worktree sync 会将基分支合并到 worktree 中；--strategy rebase 会将 worktree 变基到基分支上，而 --base 用于选择基分支。如果同步因冲突而停止，请在 worktree 中使用常规 git 命令解决冲突，然后重新运行 sync。

未提供的功能

moai worktree 不提供共享或团队注册表模式、按开发者设置前缀、选择性同步模式、冲突自动解决或交互模式、工作树模板，以及浅克隆、后台、并行或缓存选项。进入工作树后再准备工作树；现有标志请参阅 modules/worktree-commands.md。

---

配合使用效果良好

命令：

• /moai plan - 创建 SPEC 并自动设置工作树
• /moai run - 在隔离的工作树环境中开发
• /moai sync - 与自动工作树同步集成
• /moai feedback - 改进工作树工作流

技能：

• moai-foundation-core - 并行开发模式
• moai-workflow-project - 项目管理集成
• moai-workflow-spec - 由 SPEC 驱动的开发
• moai-ref-git-workflow - 优化 Git 工作流

工具：

• Git worktree - Git 原生工作树功能
• Cobra - CLI 命令框架和格式化输出

---

快速决策指南

对于新的 SPEC 开发，使用带自动设置的工作树隔离模式。主要方法是工作树隔离，辅助模式是与 /moai plan 集成。

对于跨多个 SPEC 的并行开发，每个 SPEC 使用一个工作树和一个会话。主要方法是维护多个工作树，辅助模式是在各自的 tmux 窗口中打开每个工作树，并运行 moai cc -w <name> --spawn。

对于团队协作，为每位开发者分配自己的工作树和分支。主要方法是按开发者隔离，辅助模式是通过基准分支和拉取请求进行集成。

对于代码审查工作流，使用隔离的审查工作树。主要方法是隔离审查，辅助模式是在审查完成后进行干净的同步。

对于实验性功能，使用自动清理的临时工作树。主要方法是创建临时工作树，辅助模式是通过自动移除进行安全试验。

模块详解：

• 工作树命令：完整的 CLI 参考请参阅 modules/worktree-commands.md
• 工作树管理：核心架构请参阅 modules/worktree-management.md
• 并行开发：工作流模式请参阅 modules/parallel-development.md
• 集成模式：MoAI-ADK 集成请参阅 modules/integration-patterns.md
• 故障排除：问题解决方法请参阅 modules/troubleshooting.md

完整示例：请参阅 references/examples.md 外部资源：请参阅 references/reference.md

常见的自我安慰

自我安慰	事实
“这么小的改动没必要隔离工作树”	并行工作进行时，在 main 上进行小改动也会导致合并冲突。工作树可以避免这种情况。
“我直接在 main 分支上工作就好，这样更快”	在 main 上工作会阻止其他 Agent 写入。工作树支持并行工作。
“只读 Agent 出于安全考虑也需要隔离工作树”	只有当某个 Agent 的工具列表中没有任何可写入的工具时，才无需隔离。生成时的模式参数已弃用且会被忽略，因此不会阻止任何操作。仅省略 Write、Edit 和 NotebookEdit 并不足够：Bash 可以通过 shell 写入，任何其他会修改文件的工具（另一个 shell、MCP 工具，或会生成写入者的 Agent）也可以写入。只要存在任何此类工具，就无法保证只读，因此隔离并非多余。
“我可以跳过工作树清理，git 会处理”	过时的工作树分支会不断累积，并让 git worktree list 变得混乱。使用后务必清理。
“Agent 提示词中使用绝对路径没问题，因为工作树的结构相同”	指向主仓库的绝对路径会完全绕过工作树隔离。请使用相对路径。

危险信号

• 在团队模式下启动的实现 Agent 未进行隔离：worktree
• 启动时进行了隔离的 Agent，其工具列表中没有可用于写入的工具：worktree（不必要的开销）
• Agent 提示词中包含主项目目录的绝对路径，作为写入目标
• 团队会话结束后未清理 worktree（遗留分支仍然存在）
• 在隔离 worktree 的 Agent 提示词中的 Bash 命令里执行 cd /absolute/project/path

验证

• 实现团队成员使用隔离：worktree（检查 Agent 启动参数）
• 未使用隔离：worktree 启动的团队成员不含可用于写入的工具（检查工具列表中是否有 Write、Edit、NotebookEdit、Bash 以及其他任何会修改文件的工具；只要存在其中任何一种，就无法保证只读）
• Agent 提示词中仅使用相对路径引用写入目标文件
• 会话结束后，git worktree list 显示没有遗留 worktree
• 在 Claude Code >= 2.1.97 上验证 worktree CWD 隔离（检查版本）
• Hook 脚本（handle-worktree-create.sh、handle-worktree-remove.sh）已存在且可执行