企业官网建设流程全解析

使用MoAI-ADK做git worktree 并行开发，就能让多个 AI 代理在同一仓库里同时干活、互不打架：每条工作流拥有独立的工作树和分支，配合快照/校验/回退三分支守卫，以及远端分支保护规则，既快又安全。本文面向新手，带你从零跑通"创建 → 并行 → 守卫 → 清理"的完整流程。

MoAI-ADK 是一个基于 Go 的单二进制 AI 开发框架（Agentic development harness for Claude Code），内置 SPEC 驱动的plan → run → sync三阶段工作流、TRUST 5 质量门和 Claude×GLM 多模型成本控制。而"并行开发"正是它最能打的能力之一——一个仓库、多个目录、多个代理，各干各的，最后干净合并。

为什么并行 AI 开发会"打架"？

如果你同时开两个 AI 代理会话改同一个项目，大概率会遇到这三类事故：

• 文件互相覆盖—— 两个会话同时改同一个文件，后写的直接冲掉先写的
• 分支状态混乱—— 一个会话切分支，另一个会话的未提交变更就"迷路"了
• 半成品污染主干—— 没完成的代码被推上main，CI 全线变红

根本原因只有一个：两个代理共享同一份工作目录和同一个分支状态。

git worktree 如何解决冲突

Git 内置的 Worktree 机制允许同一个仓库同时检出多个目录：每个目录绑定自己的分支、维护独立的提交历史，而.git对象库共享一份。

MoAI-ADK 在这个基础上做了两层增强，让 AI 代理各就各位：

由此带来三个关键收益：

1. 文件系统级隔离—— 每个 AI 代理在自己的目录里写文件，天然不冲突
2. 独立 LLM 配置—— 每个工作树可以用不同后端：计划用moai cc（Claude），实现用moai glm（GLM，成本低）
3. 安全合并—— 只有完成的 SPEC 才合并回主干

快速上手：三条命令开一个并行工作树

进入工作树由启动器负责，管理由moai worktree（别名moai wt）负责，查询交给 git 本身：

# 1. 创建工作树并进入（Claude 后端） moai cc -w feat-auth # 2. 或换一个后端进入同一个工作树（GLM 后端） moai glm -w feat-auth # 3. 保留当前会话，在新 tmux 窗口里再开一个 moai cc -w feat-billing --spawn # 4. 随时查看当前有哪些工作树 git worktree list

-w后跟短名称时会在工作树目录下解析，不存在就当场创建；只有两个受信任前缀（~/.moai/worktrees/与项目内 worktrees 目录）下的既有工作树可以用绝对路径重新进入，其他绝对路径会被拒绝，防止工作树建到奇怪的地方。

在 tmux 里一次拉起多个并行代理非常方便：

moai glm -w SPEC-001 --spawn moai glm -w SPEC-002 --spawn moai cc -w SPEC-003 --spawn

SPEC 三阶段工作流：每个工作树一条流水线

在 MoAI-ADK 里，并行开发的最小单元是一张"卡片"（SPEC），每张卡片在自己的工作树里按三阶段推进：

# 终端 1（主检出）：写计划，产出 SPEC 文档 > /moai plan "实现用户认证系统" # 终端 2（新工作树）：进入并实现 $ moai glm -w SPEC-AUTH-001 > /moai run SPEC-AUTH-001 > /moai sync SPEC-AUTH-001

规则很简单：卡片之间并行，卡片内部串行——同一张卡片同一时刻只有一个写入者，不同卡片的代理各自写各自的卡片目录（.moai/specs/<SPEC-ID>/），从设计上杜绝冲突。

分支守卫：snapshot / verify / restore 三连

AI 代理不是人，它可能在没被要求的目录里乱写文件。MoAI-ADK 因此提供了状态守卫三原语，由编排在代理运行前后自动调用，你也可以手动使用：

第 1 步：拍照 snapshot

moai worktree snapshot --agent-name my-agent --out .moai/state/snap.json

捕获 HEAD、分支、porcelain 状态及.moai/specs/下的未跟踪文件，写入 JSON 快照。

第 2 步：对表 verify

moai worktree verify --snapshot .moai/state/snap.json --agent-name my-agent

用退出码机器可读地报告结果：

第 3 步：回滚 restore

moai worktree restore --snapshot .moai/state/snap.json --dry-run # 先看命令 moai worktree restore --snapshot .moai/state/snap.json # 再执行

把被跟踪文件回退到快照 HEAD 状态。注意 ⚠️ untracked 文件无法由 git 找回，命令只会列出路径提示你手动重建。

守卫实现见 state_guard.go，CLI 入口在 guard.go。

远端分支保护：给主干加一道保险

工作树解决了本地冲突，branch_protection.go 则通过 GitHub API 给远端分支上锁，模板里写死了这套保护规则：

• CI 必过——required_status_checks严格模式，核心检查项全绿才允许合并
• 禁止强推——allow_force_pushes: false，历史不可篡改
• 禁止删除——allow_deletions: false，分支删不掉
• 必须 PR 评审—— 至少 1 个 approving review，且解决所有对话（required_conversation_resolution）
• 管理员同样受限——enforce_admins: true

也就是说，无论哪个 AI 代理、走哪条 lane，想进主干都必须走 PR + CI + 评审，没有后门。

同步与清理：worktree 生命周期管理速查

并行跑多了，工作树会越积越多。moai worktree的子命令覆盖了全生命周期：

其中clean --stale的安全规则值得记住：只有同时满足"工作树干净 + 分支没有超出主干的独有提交"才会被移除；分支任何情况下都不会被删除，主检出和当前正在运行的工作树永远受保护，且默认只预览、加--yes才真正执行。

moai worktree clean --stale # 预览：打印待移除清单 moai worktree clean --stale --yes # 确认后执行 moai worktree done feature/SPEC-AUTH-001 --delete-branch # 合并完成后收尾

工厂模式：让并行规模上台阶

单项目多工作树已经能并行，而 v3.2 的**工厂模式（Factory Mode）**把它做成了一条装配线：一个主导会话（leader）盯着待办队列，若干条带编号的 lane 会话各自领卡片。

moai cc -f # 打开主导会话 moai cc -l # 新终端里加入 lane-1 moai cc -l # 再开一条，自动编号 lane-2

工厂模式的并行规则与 worktree 紧密咬合：

• 一张卡片，一个 worktree—— 新卡片在新工作树里开始，lane 全程待在自己的树里，远端合并前绝不丢弃
• 有写权限的子代理必须加 worktree 隔离（isolation: "worktree"），卡片目录之外的文件写入也不会撞车
• 每条 lane 最多并发 10 个Agent()子代理，容量靠配置分摊而不是靠自觉
• 按阶段分模型进一步省钱：计划用高推理模型集中做完，实现阶段用便宜模型多路并行

用 moai web 总览所有并行会话

开再多 lane 也不慌，moai web起一个本地控制台，Factory 界面把各条 lane、SPEC 流水线、会话注册表一屏看全：

最佳实践清单

• ✅命名规范：工作树直接用 SPEC ID（SPEC-AUTH-001），别用temp、feature-branch这类模糊名字
• ✅先起一条 lane 再扩：确认第一条 lane 真的在产出，再启动其余的
• ✅合并只走 git/PR：done只清理不合并，合并动作永远显式
• ✅定期清理：moai worktree clean --merged-only保持工作区清爽
• ✅按计划选模型：Plan 用 Opus 级、Run 用 GLM、Sync 用 Sonnet 级，把预算花在刀刃上
• ❌不要跳过 verify：代理跑完不做快照校验，等于把"乱写文件"的风险留到合并时才发现

深入阅读

想继续深入，推荐按这个顺序：

• 官方文档：worktree 完整指南 —— 命令参考 + 工作流 + 最佳实践全收录
• 官方文档：worktree 概述 —— L1/L2 两层结构与三阶段流程图解
• 官方文档：moai worktree CLI 参考 —— 全部子命令与选项
• 官方文档：工厂模式 —— leader/lane 编排细节
• 并行开发源码：internal/cli/worktree/ —— 全部子命令实现
• 状态守卫源码：internal/worktree/ —— 快照与 divergence 判定
• 分支保护源码：internal/cli/branch_protection.go

一条主线记住就不会迷路：worktree 管隔离，快照守卫管漂移，分支保护管主干——三者叠起来，多代理并行才既快又稳。