Multi-AI Workflow (MAW)：AI工作流编排框架，让Claude、Codex、Gemini协同开发-平芜编程栈

1. 项目概述：Multi-AI Workflow (MAW) 是什么？

如果你和我一样，每天都在和代码打交道，那你肯定遇到过这种场景：想用Claude来规划一个复杂功能，又想让Codex来执行具体的代码生成和测试，最后可能还需要Gemini来分析一下架构图或者性能瓶颈。过去，我们只能在不同工具、不同窗口之间来回切换，复制粘贴，手动协调，整个过程既低效又容易出错。

Multi-AI Workflow (MAW) 就是为了解决这个痛点而生的。它不是一个简单的脚本集合，而是一个完整的、可编程的AI工作流编排框架。你可以把它想象成一个“AI调度中心”，它允许你通过一个统一的命令行接口，将不同的AI模型（目前主要是Claude、Codex和Gemini）串联起来，让它们各司其职，协同完成一个复杂的开发任务。

它的核心思想是“让合适的AI做合适的事”。Claude擅长逻辑推理和规划，Codex在代码生成和执行上无人能及，而Gemini则在多模态理解和分析上表现出色。MAW通过预设的七种工作流模式，帮你自动化了任务分发、上下文传递和结果整合的过程。比如，你可以启动一个“五阶段协作”工作流，它会自动让Claude分析上下文，让Codex和Gemini并行进行代码级和架构级分析，再让Claude综合结果进行原型设计和实现，最后让所有AI一起进行审计。整个过程一气呵成，你只需要在开始时下达一个指令。

这个项目非常适合全栈开发者、技术负责人和任何希望将AI深度集成到开发流程中的工程师。无论你是想快速修复一个bug，还是系统性地重构一个模块，MAW都能提供一套标准化的、可复用的协作范式，将AI从“聊天伙伴”升级为真正的“开发协作者”。

2. 核心架构与设计哲学拆解

2.1 分层架构：从CLI到AI桥接

MAW的架构设计得非常清晰，遵循了“核心-桥接-技能”的分层模式，这保证了它的扩展性和稳定性。我们来拆开看看每一层都在做什么。

最上层是TypeScript CLI核心。这是用户直接交互的入口，所有命令如maw workflow plan或maw delegate codex都在这里被解析和执行。CLI层负责工作流引擎的调度、会话状态的管理以及用户指令的路由。它本身不直接调用AI，而是作为一个“指挥家”。

中间层是Python AI桥接层。这是整个框架的“翻译官”和“适配器”。为什么用Python？因为像Gemini这样的AI服务，其官方SDK或社区CLI工具往往对Python的支持最完善。桥接层封装了与各个AI后端交互的细节。例如，gemini_bridge.py可能封装了调用Gemini API的复杂逻辑，处理认证、格式化请求、解析响应；codex_bridge.py则可能是对Codex CLI工具的命令行封装。CLI核心通过子进程调用这些Python脚本，实现了与不同AI服务的解耦。这种设计意味着，未来要接入新的AI（比如GPT），你只需要写一个新的xxx_bridge.py，然后在技能注册表中注册即可，核心引擎几乎不用改动。

最下层是技能和配置。技能是预定义的可复用任务模块，比如“与Gemini协作”、“报告生成器”。它们通常包含特定的提示词模板、处理逻辑和输出格式。配置则集中管理了各个AI的启用状态、CLI路径、工作流默认参数等。这种模块化设计让MAW不仅是一个工具，更是一个平台。

2.2 会话管理：贯穿始终的上下文粘合剂

多AI协作最大的挑战之一是上下文丢失。AI A不知道AI B刚才说了什么，导致每次交互都像是从头开始。MAW的“统一会话”机制巧妙地解决了这个问题。

当你启动一个工作流时，MAW会生成一个唯一的会话ID。这个ID会像一根线，穿过所有后续的AI调用。无论是Claude做规划，还是Codex执行代码，或是Gemini分析图表，它们产生的输入、输出、中间状态都会被关联到这个会话ID下，并持久化存储（通常是SQLite数据库）。

这样做有几个巨大的好处：

状态持久化：你可以随时中断工作流，过几天再通过maw session resume <id>命令恢复，所有历史上下文都在。
跨AI上下文传递：MAW会在调用下一个AI时，自动将之前相关的对话历史和结果作为上下文附上。例如，在“五阶段模式”中，Phase 2的Codex和Gemini能同时看到Phase 1中Claude收集的项目背景。
审计与复盘：所有交互记录都可查，这对于理解AI的决策过程、调试复杂工作流至关重要。Dashboard的可视化功能正是基于这些会话数据。

这个设计体现了MAW的一个核心哲学：将一次性的AI对话，升级为可管理、可追溯、可复用的工程项目。

2.3 智能路由与沙箱安全

“智能路由”是MAW里一个听起来很酷，实则非常实用的功能。当你使用maw run “分析这段代码”时，你并没有指定用哪个AI，MAW会自己判断。

它的内部逻辑可能基于简单的规则引擎：如果任务描述中包含“代码”、“测试”、“实现”等关键词，则路由给Codex；如果包含“架构”、“设计”、“图表”、“分析”等，则优先路由给Gemini；如果任务描述比较抽象，涉及“规划”、“步骤”、“方案”，则交给Claude。这省去了用户手动选择的麻烦，尤其在快速尝试时非常高效。

另一个不容忽视的设计是安全沙箱。让AI（尤其是Codex）直接在你的项目目录里写代码是有风险的。MAW通过配置中的sandbox级别来控制AI的“权限”。

read-only：AI只能读文件，不能修改。适用于代码分析、审计场景。
workspace-write：AI可以修改当前工作目录下的文件。这是日常开发最常用的模式。
full-access：理论上允许更广的操作（需谨慎使用）。

在实现上，这通常是通过在调用Codex CLI时，通过参数或环境变量限制其文件系统访问范围来实现的。这是一个负责任的设计，防止了误操作导致系统文件被篡改的风险。

3. 七种工作流模式深度实操指南

MAW预设的七种工作流模式是其精髓所在，它们覆盖了从简单到复杂、从执行到设计的各种场景。理解每种模式的适用时机和内部流转，是高效使用MAW的关键。

3.1 轻量级模式：Lite 与 Lite-Plan

Lite模式是最简单的“执行-反馈”循环。你给一个任务，MAW直接调用Claude（默认）去执行，没有前置规划，也没有后续审查。它的流程就是：用户任务 -> AI直接执行 -> 返回结果。

实操心得：不要小看Lite模式。它最适合那些定义极其明确、步骤单一的“微任务”。比如“把项目里所有的var改成let/const”，或者“给这个JSON文件格式化缩进”。我常用它来做一些重复性的代码格式化、注释补全工作。它的速度最快，因为省去了所有“思考”环节。但切记，任务必须足够简单明确，否则AI很容易跑偏。

Lite-Plan模式在Lite之前加了一个“快速规划”步骤。AI会先花很少的token，快速生成一个1-3步的执行计划，然后立刻去执行。流程是：用户任务 -> 快速规划 -> 执行 -> 结果。

这个模式适用于那些你心里大概有数，但又不至于简单到一步就能完成的任务。例如：“给这个API端点添加基础的输入验证”。AI可能会规划成：1. 检查请求体结构；2. 添加Joi或Validator.js验证规则；3. 返回验证错误响应。然后它再按这个计划去写代码。

两者的选择：我的经验法则是，如果你能用一个清晰的句子描述清楚具体要改哪一行、改成什么样，用Lite。如果需要稍微想一下“先做什么、后做什么”，就用Lite-Plan。它是在速度和可靠性之间一个很好的折中。

3.2 核心开发模式：Plan 与 TDD-Plan

Plan模式是MAW的默认模式，也是一个标准的、完整的开发工作流。它模拟了一个严谨开发者的思考过程：分析、计划、评审、执行、验证。

我以“实现用户登录功能”为例，拆解一下Plan模式的实际运行：

规划阶段：Claude会分析你的项目结构（读取package.json、现有路由文件等），理解“用户登录”需要什么（数据库模型、路由、控制器、密码加密、JWT生成等），然后输出一个详细的实现步骤列表。
评审阶段：这是一个关键且容易被忽略的步骤。MAW会（通常还是Claude）对这个计划进行可行性评审，检查是否有遗漏（比如忘了密码重置）、技术选型是否合理（用bcrypt还是argon2？）。这个阶段常常能提前发现设计缺陷。
执行阶段：Claude开始按照评审后的计划，一步步地生成代码。它会创建或修改文件，并给出详细的解释。
验证阶段：执行完成后，Claude会检查生成的文件，运行简单的逻辑验证（比如语法检查），并给出一个总结。

避坑技巧：Plan模式耗时较长，适合在功能开发的主线上使用。我建议在执行前，先通过maw workflow plan --dry-run “任务”看看AI生成的计划是否靠谱，确认无误后再正式运行。这能避免AI在错误的方向上浪费大量token和时间。

TDD-Plan模式是Plan模式的变体，强制引入了测试驱动开发（TDD）的“红-绿-重构”循环。这对于保证代码质量至关重要。

它的流程是：

写测试（红）：AI首先根据任务描述，编写一组会失败的单元测试或集成测试。例如，为“用户登录”编写测试：调用登录接口传入错误密码应返回401。
确认失败：MAW（或集成你的测试运行器）运行这些测试，确认它们如预期般失败。
实现功能（绿）：AI编写最小化的代码，唯一目的就是让刚才的测试通过。
重构：在测试保护下，AI对代码进行优化，改善结构、消除重复。

这个模式非常适合开发核心业务逻辑、工具函数或API。我常用它来开发那些边界条件复杂、容易出错的模块。最大的好处是，交付物自带测试用例，这比单纯生成代码价值高得多。

3.3 设计与协作模式：Brainstorm 与 Five-Phase

当任务从“如何实现”上升到“如何设计”时，就需要更高级的模式了。

Brainstorm模式模拟了一个技术方案评审会。AI会扮演多个角色（通常是架构师、开发工程师、测试工程师），围绕一个主题进行“辩论”和“发散思考”。

比如，你输入maw workflow brainstorm “该用GraphQL还是RESTful API？”。MAW内部的Claude可能会启动三个并行的对话线程：

架构师角色：考虑长期维护性、生态、性能、学习曲线。
开发工程师角色：考虑开发效率、工具链支持、代码复杂度。
测试工程师角色：考虑接口可测试性、Mock难度、自动化测试覆盖。

每个角色会从自己的视角输出观点，然后MAW会综合这些观点，给出一个权衡后的建议。这个模式的价值在于打破思维定式，强迫你（通过AI）从多个角度审视问题，特别适合做技术选型或架构决策。

Five-Phase模式是MAW的“旗舰”模式，代表了多AI协作的巅峰。它将一个复杂任务拆解为五个专业阶段，并动态分配最合适的AI参与。

我结合一个真实案例“重构一个老旧的身份验证模块”来说明：

Phase 1: 上下文分析 (Claude)：Claude会像一位资深顾问，先通读你的项目代码，理解现有身份验证的逻辑（可能是基于Session的）、依赖库、存在的问题（比如安全性不足、难以扩展）。它会生成一份详细的现状分析报告。
Phase 2: 并行分析 (Codex + Gemini)：这是最精彩的部分。Codex和Gemini会同时工作，但侧重点不同。
- Codex进行代码级分析：找出重复的验证逻辑、硬编码的密钥、不安全的密码比较方式等具体代码问题。
- Gemini进行架构级分析：评估当前架构是否符合OAuth2.0或JWT的最佳实践，识别单点故障风险，甚至画出当前的架构图。两者分析结果会汇总给下一个阶段。
Phase 3: 原型设计 (Claude)：Claude作为“总设计师”，综合Phase 1和Phase 2的输入，设计新的身份验证方案。例如，决定采用JWT，设计Token刷新机制，规划需要新建的AuthService、JwtStrategy等模块，并输出核心接口的定义和伪代码。
Phase 4: 实现 (Claude)：基于原型，Claude开始动手编写完整的、可运行的代码。它会处理各种边界情况，比如Token过期、黑名单处理、与现有用户模型的集成等。
Phase 5: 审计 (Claude+Codex+Gemini)：最后，所有AI一起上阵进行最终审查。Claude检查逻辑一致性，Codex进行代码安全扫描和风格检查，Gemini评估最终架构图。只有三方都“点头”，工作流才算完成。

这个模式产出质量极高，但耗时也最长，适合用于那些影响深远、复杂度高、容错率低的核心模块重构或新系统开发。

3.4 自动化迭代模式：Ralph Loop

Ralph Loop模式灵感来源于一种让AI自我迭代的“Ralph技巧”。它的逻辑非常直接：给AI一个任务和一个明确的“完成承诺”信号（比如输出<promise>COMPLETE</promise>），然后让它不停地尝试，直到输出这个信号为止。

流程是一个循环：固定提示词（包含任务和之前所有尝试的历史） -> AI执行 -> 检查输出是否有完成信号 -> 没有则进入下一轮。

这个模式威力巨大，但使用门槛也高。关键在于设计“可自动验证的成功标准”。例如：

“写一个函数计算斐波那契数列，并包含通过所有单元测试的代码。” （成功标准：测试通过）
“将这篇英文文章翻译成中文，确保专业术语准确。” （成功标准：难以自动判断，不适合Ralph）
“优化这个SQL查询，直到在测试数据集上的执行时间低于100ms。” （成功标准：性能指标可测量）

核心技巧：为了让Ralph Loop更有效，你需要在初始提示词中清晰地定义“完成”的客观条件，并尽可能让AI在每次迭代中能进行自我验证。例如，提示词可以写成：“你的任务是构建一个TODO API。你必须编写完整的Express.js服务器代码，包含GET/POST/PUT/DELETE端点，并使用内存数组存储数据。在代码最后，你必须运行一个自包含的测试来验证所有端点工作正常，只有当所有测试都通过时，你才输出<promise>COMPLETE</promise>。”这样，AI在每次迭代中都会尝试运行测试，根据测试结果调整代码。

我通常用它来处理那些有明确终点、但实现路径可能多样的任务，比如算法实现、数据清洗脚本编写、或者通过反复运行测试来调试代码。务必设置--max-iterations参数，防止陷入无限循环。

4. 从安装到上手的全流程实操记录

4.1 环境准备与一键安装

MAW依赖Node.js和Python环境。我的机器是macOS，以下是我的安装实录。

首先，确保基础环境就绪：

# 检查Node.js版本，需要 >= 18 node --version # 检查Python版本，需要 >= 3.9 python3 --version

如果未安装，建议使用nvm和pyenv来管理版本，避免影响系统原有环境。

接下来是安装Claude Code CLI，这是与Claude交互的桥梁。你需要去Claude官网注册并获取CLI工具的安装权限。通常也是一条命令：

# 具体命令请以Claude官方文档为准，此处为示例 npm install -g @anthropic-ai/claude-code

完成这些预备工作后，MAW的安装就非常简单了。官方推荐的一键安装脚本确实好用：

git clone https://github.com/haoyu-haoyu/Multi-AI-Workflow.git cd Multi-AI-Workflow ./install.sh

这个install.sh脚本做了以下几件关键事：

将编译好的MAW CLI核心复制到~/.maw/目录下。
在~/.maw/bin/下创建名为maw的全局可执行脚本。
将~/.maw/bin/加入你的shell环境变量（PATH）。
将预定义的Claude Code斜杠命令（如/gemini,/maw）复制到Claude Code的命令目录~/.claude/commands/下。

安装完成后，务必重启终端或者执行source ~/.zshrc（或~/.bashrc）来刷新PATH。然后验证安装：

maw --version # 如果看到版本号输出，说明安装成功 maw --help # 查看所有可用命令

4.2 首次运行与基础配置

安装成功后，我们先不急着配置复杂的API Key，而是用最基本的Claude功能来体验一下。MAW的默认配置已经启用了Claude（假设你的Claude Code CLI已正确配置并登录）。

让我们从一个最简单的Lite模式开始，感受一下AI直接执行任务：

# 进入你的一个项目目录，比如一个Node.js项目 cd ~/my-node-project # 让AI帮你做一件小事：给package.json文件添加一个脚本 maw workflow lite "在package.json里添加一个名为 'format' 的脚本，使用prettier格式化src目录下的所有.js和.jsx文件"

几秒钟后，你应该能看到Claude的输出，它直接给出了修改后的package.json文件内容，或者告诉你具体要添加哪几行。你可以检查一下，如果没问题，就手动复制过去。这就是最基本的协作。

接下来，我们试试需要点规划能力的Lite-Plan模式：

# 假设项目里有一个简单的Express服务器文件 app.js maw workflow lite-plan "在app.js里添加一个简单的健康检查端点 '/health'，返回 { status: 'ok' }"

这次，你会先看到AI快速生成的计划：“1. 导入Express Router（如果需要）。2. 定义GET /health路由。3. 返回JSON响应。” 然后它才会去执行。这个流程更稳健。

4.3 配置Codex与Gemini桥接（进阶）

要解锁MAW的全部威力，需要配置Codex和Gemini。这里以Gemini为例（Codex配置类似，取决于你使用的具体CLI工具）。

重要提示：由于网络限制，直接使用Gemini的官方API可能不便。MAW的Gemini桥接设计支持通过代理API访问，这需要你自行准备可用的API服务。

定位桥接配置文件：

# 桥接脚本通常在这里 ls -la ~/.maw/skills/collaborating-with-gemini/scripts/ # 你应该能看到一个类似 gemini_bridge.py 的文件

编辑配置文件：

# 使用你喜欢的编辑器，比如VSCode或vim code ~/.maw/skills/collaborating-with-gemini/scripts/gemini_bridge.py

在文件中，你需要找到配置API密钥和基础URL的地方。它可能看起来像这样：

# 示例配置位置 API_KEY = os.getenv("GEMINI_API_KEY", "your-api-key-here") BASE_URL = os.getenv("GEMINI_BASE_URL", "https://api.gemini.example.com/v1") # 替换为你的代理地址

将your-api-key-here替换为你从代理服务商处获取的API Key，将https://api.gemini.example.com/v1替换为代理服务商提供的实际API端点地址。

测试桥接：配置完成后，可以在终端直接测试桥接脚本是否工作：
```
cd ~/.maw/skills/collaborating-with-gemini/scripts/ python gemini_bridge.py "你好，请简单介绍一下你自己。"
```
如果看到Gemini的回复，说明桥接配置成功。
在MAW中测试：
```
# 使用delegate命令直接委托任务给Gemini maw delegate gemini "用Mermaid语法画一个简单的客户端-服务器交互序列图"
```
如果一切正常，Gemini会返回一段Mermaid代码。你可以将其复制到支持Mermaid的Markdown编辑器中查看图表。

Codex的配置过程类似，你需要确保codexCLI命令在终端中可以直接运行，然后MAW就能通过maw delegate codex调用它了。

4.4 在Claude Code中无缝使用斜杠命令

MAW安装脚本已经将斜杠命令文件复制到了~/.claude/commands/目录。当你打开Claude Code（通常是桌面应用或IDE插件）时，你应该能在输入框里通过/触发命令补全。

例如，在Claude Code的聊天界面中：

/gemini 分析下面这段代码的复杂度：[粘贴你的代码]

Claude Code会识别/gemini命令，并将任务和上下文通过MAW的桥接发送给Gemini处理，最后将结果返回当前聊天窗口。这实现了在Claude的界面内无缝调用其他AI的能力，体验非常流畅。

同样，你可以使用/maw workflow plan “实现一个用户注册功能”来直接启动一个完整的工作流，所有交互和输出都会在Claude Code的会话中呈现。

5. 实战案例：使用Five-Phase模式开发一个Markdown博客API

光说不练假把式。我们用一个完整的实战案例，来演示如何用MAW的Five-Phase模式，从零开始构建一个简单的Markdown博客后端API。假设我们使用Node.js + Express + 文件系统存储。

任务描述：“创建一个简单的Markdown博客后端API。功能包括：获取文章列表、根据ID获取单篇文章、创建新文章、更新文章。文章以Markdown文件形式存储在本地posts目录，元数据（标题、日期、摘要）存储在一个meta.json文件中。”

5.1 Phase 1 & 2: 上下文与并行分析

我们启动工作流：

cd ~/dev # 在一个空目录或新项目目录 maw workflow five-phase “创建一个简单的Markdown博客后端API...(如上描述)”

Phase 1 (Claude上下文分析)：Claude会分析当前目录。由于是空目录，它会识别到这是一个全新的Node.js项目。它会“思考”这个任务需要：Express框架、body-parser中间件、文件系统fs模块、用于解析Markdown的库（如marked）、以及一个结构化的数据存储方式（meta.json + .md文件）。它会生成一个初步的项目结构规划。

Phase 2 (Codex + Gemini并行分析)：

Codex会聚焦于代码实现细节：检查Express路由的最佳写法，考虑异步文件操作的错误处理，规划meta.json的数据结构（数组 of 对象），并评估使用marked库的安全性（是否需要清理输入）。
Gemini会从架构层面分析：评估文件系统存储的优缺点（简单 vs 不适合高并发），建议API设计遵循RESTful规范（GET /posts, GET /posts/:id, POST /posts, PUT /posts/:id），并可能画出一个简单的组件关系图。

5.2 Phase 3 & 4: 原型设计与实现

Phase 3 (Claude原型设计)：Claude综合前两阶段的分析，输出详细的设计文档。它会定义：

项目结构：

blog-api/ ├── package.json ├── app.js (主入口) ├── routes/ │ └── posts.js (文章路由) ├── controllers/ │ └── postController.js (业务逻辑) ├── storage/ │ ├── posts/ (存放.md文件) │ └── meta.json (存放元数据) └── utils/ └── markdownParser.js (Markdown解析工具)

API规范：详细定义每个端点的URL、HTTP方法、请求体、响应格式。
核心算法：描述如何同步meta.json和posts/目录下的文件，如何生成唯一的文章ID等。

Phase 4 (Claude实现)：Claude开始“敲代码”。它会：

初始化项目 (npm init -y) 并安装依赖 (express,body-parser,marked,uuid)。
创建app.js，搭建Express服务器基本骨架，引入中间件和路由。
编写routes/posts.js，定义四个路由端点，并映射到控制器。
编写controllers/postController.js，实现核心业务逻辑：读取/写入文件、更新meta.json、解析Markdown。
创建utils/markdownParser.js，封装marked库的使用，可能添加基本的XSS过滤。
创建初始的storage/目录和空的meta.json文件。

整个过程是迭代的，Claude会一个文件一个文件地生成，并给出解释。你可以看到它如何思考错误处理（try-catch）、如何设计异步函数、如何组织代码结构。

5.3 Phase 5: 多AI审计与交付

Phase 5 (Claude+Codex+Gemini审计)：

Claude会进行逻辑复审：检查四个API端点功能是否完整，控制流是否正确，错误信息是否清晰。
Codex会进行代码扫描：检查是否有安全漏洞（如路径遍历攻击），代码风格是否一致，是否有未处理的Promise拒绝。
Gemini会进行架构复审：评估最终的实现是否与最初的设计一致，文件存储方案是否在预期范围内，并可能生成最终的系统架构图。

审计结束后，MAW会输出一份汇总报告，指出发现的问题（如果有）以及最终的代码交付物。至此，一个具备基本CRUD功能的Markdown博客API后端就创建完成了。你可以立即运行node app.js并用手边的API测试工具（如curl或Postman）进行测试。

这个案例展示了Five-Phase模式如何将一个大任务分解，并让不同的AI在各自擅长的阶段发挥作用，最终产出结构清晰、经过多重审查的可用代码。

6. 常见问题、排查技巧与进阶心得

在实际使用MAW几个月后，我积累了一些踩坑经验和进阶技巧，分享给大家。

6.1 安装与配置问题

问题1：安装后maw命令未找到。

排查：执行echo $PATH，检查~/.maw/bin是否在PATH中。
解决：手动将export PATH="$HOME/.maw/bin:$PATH"添加到~/.zshrc或~/.bashrc，然后source对应文件。

问题2：Claude Code斜杠命令不生效。

排查：检查~/.claude/commands/目录下是否存在maw.md,gemini.md等文件。
解决：MAW安装脚本可能没复制成功。手动从项目claude-commands/目录复制文件到~/.claude/commands/。并确保Claude Code已重启或重新加载命令。

问题3：Gemini/Codex桥接调用失败，提示连接错误或认证失败。

排查：
1. 首先在终端直接运行桥接Python脚本进行测试（见4.3节），确认问题出在桥接本身还是MAW调用环节。
2. 检查桥接脚本中的API Key和Base URL配置是否正确。
3. 检查网络连接，如果是代理API，确认其可用性。
解决：根据桥接脚本的错误信息调整配置。对于网络问题，可能需要配置脚本使用HTTP代理（在Python脚本中添加requests库的代理设置）。

6.2 工作流执行中的问题

问题4：工作流执行到一半卡住或报错。

排查：MAW有详细的日志。尝试在命令后添加--verbose或-v标志，查看具体哪一步出了错。
解决：常见原因有：
- Token超限：AI响应过长。尝试将复杂任务拆分成更小的子任务。
- 文件权限问题：AI尝试写入没有权限的目录。检查当前工作目录的权限，或使用沙箱模式。
- 依赖缺失：AI生成的代码需要安装未提及的依赖。根据错误提示手动安装。
- 上下文过长：在复杂项目中，Phase 1收集的上下文可能超出AI token限制。可以尝试在更具体的子目录下运行工作流，减少初始上下文。

问题5：AI生成的代码质量不高或跑偏。

解决：
- 提供更精确的指令：模糊的指令得到模糊的结果。明确指定技术栈、代码风格、目录结构。例如，不说“实现登录”，而说“使用Express和JWT实现用户登录接口，密码用bcrypt加密，返回access和refresh token”。
- 使用TDD-Plan模式：用测试来约束AI的实现方向，质量更有保障。
- 迭代优化：不要指望一次成功。先用Lite或Plan模式生成一个草稿，然后基于结果提出更具体的改进指令，进行第二轮迭代。MAW的会话管理让这种迭代非常方便。

问题6：Ralph Loop陷入无限循环，无法达到完成状态。

排查：检查--completion-promise设置是否明确且可被AI识别。查看每次迭代的输出，看AI是否在向目标靠近。
解决：
- 强化完成条件：在提示词中更精确地定义“完成”。例如，不仅要求输出特定标签，还要求代码必须能通过一组给定的测试用例（可以将测试代码也放在初始提示词中）。
- 降低迭代次数：设置合理的--max-iterations（如10-20次），避免无意义消耗。
- 切换AI：尝试--ai claude或--ai codex，不同AI的逻辑能力不同。

6.3 进阶使用技巧

技巧1：混合使用工作流和直接委托。Five-Phase模式虽好，但耗时。对于大型项目，我经常混合使用：用Five-Phase模式做顶层模块设计和核心逻辑开发；用Plan或TDD-Plan模式开发单个功能点；用maw delegate codex快速生成工具函数或单元测试；用maw delegate gemini分析日志或生成文档图表。灵活搭配，效率最高。

技巧2：善用会话管理。对于一个长期功能开发，我会在开始时maw session new feature-auth创建一个会话。之后所有相关的、零散的AI指令（无论是工作流还是直接委托）都指定这个会话ID（或通过环境变量设置）。这样，所有上下文都关联在一起，AI始终记得之前做了什么，避免了重复解释。

技巧3：定制和扩展技能。MAW的技能系统是可扩展的。如果你有重复性的特定任务（比如为你的团队生成特定格式的API文档），可以编写自己的技能。技能本质上是一个包含特定提示词模板和可能有一些处理逻辑的模块。研究~/.maw/skills/下的现有技能，你可以模仿创建自己的，然后用maw skill install ./my-custom-skill安装。

技巧4：将MAW集成到CI/CD或自动化脚本中。对于某些重复性任务，比如每天自动生成代码质量报告、自动为新增的API端点生成基础测试用例，你可以写一个Shell脚本或Git Hook，在脚本中调用maw workflow lite或maw delegate命令，实现开发流程的局部自动化。

MAW不是一个魔法黑盒，而是一个强大的杠杆。它放大了你作为开发者的规划和协调能力，将繁琐的、模式化的任务交给AI协作网络去处理，让你能更专注于真正需要创造力和深度思考的部分。熟练掌握它，就像拥有了一支随时待命的、精通不同领域的AI助手团队。