Ralph多智能体编排实战指南

Ralph + 多智能体编排：从理论到实践的完整指南

摘要：本文系统讲解 Ralph Loop 多智能体编排框架的核心思想、架构设计和实战流程。从 LLM 自评估不可靠这一根本问题出发，深入剖析 Ralph 如何通过"外部验证 + 文件系统记忆 + 新鲜上下文迭代"三大机制实现可靠的自主开发。文章包含完整的代码示例和可操作的 step-by-step 教程，帮助读者从零搭建自己的多智能体开发流水线。

目录

1. 什么是 Ralph？

Ralph 是一套多智能体编排方法论和工具生态，由澳大利亚开发者 Geoffrey Huntley 于 2025 年提出。它的名字来源于《辛普森一家》中的 Ralph Wiggum——一个虽然笨拙但永不放弃的角色。正如其名，Ralph 的哲学是：“让 Agent 不断尝试，直到外部验证通过，而不是让它自己判断’我做好了’”。

在最简单的形态下，Ralph Loop 就是一行 shell 命令：

while :; do cat PROMPT.md | claude -p –dangerously-skip-permissions; done

但在这行命令背后，是一套完整的自主开发方法论。从 2025 年到 2026 年，Ralph 生态已经发展出多个成熟的实现：

2. 核心痛点：为什么 LLM 不能自己喊停

2.1 问题本质

传统的 AI Agent 开发范式（如 ReAct = Reasoning + Acting）遵循以下循环：

用户指令 → Agent 思考 → Agent 执行 → Agent 自评"完成" → 停止

这种模式存在一个根本性的缺陷：LLM 的自我评估不可靠。

阿里巴巴在分析从 ReAct 迁移到 Ralph 的实践中明确指出：“LLMs exit too early because their self-assessment is unreliable”（LLM 过早退出，因为它们的自我评估不可靠）。

2.2 三个典型失败场景

场景一：过早宣布完成

用户: "给我写一个用户登录系统"
Agent: 写了 login() 函数 → "完成了！"
实际: 没有密码加密、没有 session 管理、没有错误处理、没有测试

LLM 倾向于"取悦用户"，它会在完成一个最简实现后就声称完成，而不是交付一个生产就绪的系统。

场景二：上下文污染

第 1 轮: Agent 做了一个错误决策
第 2 轮: Agent 基于第 1 轮的错误继续推理
第 3 轮: 错误被放大，Agent 陷入死循环
…
第 N 轮: 上下文窗口爆满，token 成本飙升，输出质量下降

长对话导致的上下文累积不仅推高成本，更会让 Agent 在错误的道路上越走越远。

场景三：验证缺失

Agent 写了代码，但它有没有运行测试？测试通过了吗？Lint 检查过了吗？传统 Agent 循环中，这些验证步骤常常被跳过——Agent 认为"我写的代码应该是对的"。

2.3 问题根源分析

3. Ralph 的解决方案：五大核心原则

Ralph 通过以下五大原则（The Ralph Tenets）系统性地解决上述问题：

原则一：新鲜上下文 = 可靠性

每次迭代 → 清空上下文 → 重新读取规格文件 → 重新理解当前状态 → 执行一个任务 → 提交 → 退出

关键设计：每个循环迭代都是一个全新的 Agent 会话。Agent 不依赖上一轮的"记忆"，而是从文件系统中重新读取：

• specs/*.md — 需求规格
• IMPLEMENTATION_PLAN.md — 当前进度
• AGENTS.md — 操作指南
• src/* — 源代码

这样做的好处：

• ✅ 上下文永远不会膨胀
• ✅ 每轮决策基于最新状态
• ✅ Token 成本可控
• ✅ 错误不会跨迭代传播

原则二：文件即状态，Git 即记忆

Agent 之间不通过对话传递信息，而是通过文件系统：

Agent_1 完成 → git commit → 更新 IMPLEMENTATION_PLAN.md
↓
Agent_2 启动 → git pull → 读取 IMPLEMENTATION_PLAN.md → 知道该做什么

这形成了一个可审计、可恢复、可并行的状态管理系统。

原则三：计划可丢弃

传统开发中，重新做计划成本很高。但在 Ralph 中：

# 计划错了？重新生成即可
./loop.sh plan # 成本：一个规划循环（几分钟）

因此，不要花太多时间追求完美计划——计划是动态的，随执行不断更新。

原则四：Stop Hook — 拦截过早退出

这是 Ralph 最核心的机制之一。Stop Hook 是一个外部检查点，在 Agent 声称"完成"时触发：

# 伪代码：Stop Hook 机制
def ralph_loop(task):
while True:
agent = spawn_fresh_agent(task)
result = agent.execute()

# 外部验证 —— 不信任 Agent 的自我评估
if not verify_externally(result):
update_plan_with_failure(result)
continue # 再来一轮

if all_gates_passed(result):
commit_and_push(result)
break

常见的验证门禁（Gates）：

• 测试通过：pytest / npm test 必须全部通过
• 类型检查：mypy / tsc –noEmit 零错误
• Lint 检查：eslint / ruff 零警告
• 构建成功：npm run build / cargo build 无错误
• 完成标记：PRD 中所有任务项打勾

原则五：验证标准前置

在开始任何工作之前，先定义"什么叫完成"：

## specs/authentication.md

# 用户认证系统

## 验收标准
– [ ] 用户可以用 email + 密码注册
– [ ] 密码使用 bcrypt 加密存储
– [ ] 登录成功后返回 JWT token
– [ ] Token 有效期 24 小时
– [ ] 错误密码 5 次后锁定账户 15 分钟
– [ ] 所有 API 的测试覆盖率达到 80%+
– [ ] 类型检查零错误
– [ ] ESLint 零警告

有了明确的验收标准，Agent 就不能随便说"我做好了"。

4. 从零搭建 Ralph Loop（单 Agent 版）

在进入多智能体编排之前，我们先从最基础的单 Agent Ralph Loop 开始。这是理解整个 Ralph 生态的基石。

4.1 环境准备

# 确保已安装 Claude Code
claude –version

# 创建项目目录
mkdir my-ralph-project && cd my-ralph-project
git init

4.2 项目目录结构

my-ralph-project/
├── loop.sh # Ralph 循环脚本
├── PROMPT_plan.md # 规划模式的 Prompt
├── PROMPT_build.md # 构建模式的 Prompt
├── AGENTS.md # 操作指南（初始为空！）
├── IMPLEMENTATION_PLAN.md # 实现计划（Ralph 自动生成）
├── specs/ # 需求规格（一个文件一个主题）
│ ├── authentication.md
│ ├── data-model.md
│ └── api-design.md
├── src/ # 源代码
│ ├── index.ts
│ └── lib/ # 共享工具库
└── tests/ # 测试

4.3 编写 Spec 文件

Spec 文件是 Ralph 的"需求文档"，遵循 “一句话不含’和’” 规则——每个 Spec 只描述一个关注点：

<!– specs/authentication.md –>
# 用户认证

## 功能描述
用户使用 email 和密码进行注册和登录。

## 详细需求
1. 注册接口：POST /api/auth/register
– 接收 email, password, name
– 密码长度 8-64 字符
– 返回用户 ID 和 JWT token

2. 登录接口：POST /api/auth/login
– 接收 email, password
– 返回 JWT token
– 5 次失败后锁定 15 分钟

3. Token 刷新：POST /api/auth/refresh
– 接收 refresh_token
– 返回新的 access_token

## 验收标准
– [ ] 所有接口测试覆盖率 ≥ 80%
– [ ] 密码使用 bcrypt (cost=12) 加密
– [ ] JWT 使用 RS256 算法
– [ ] ESLint 零警告
– [ ] TypeScript 类型检查通过

<!– specs/data-model.md –>
# 数据模型

## 实体
– User: id, email, password_hash, name, created_at, locked_until
– Session: id, user_id, refresh_token, expires_at, created_at

4.4 编写 Prompt 文件

这是 Ralph Loop 的核心——两个 Prompt 文件分别指导 Plan 和 Build 阶段。

PROMPT_plan.md（规划模式——只做差距分析，不写代码）：

0a. 使用最多 250 个并行 Sonnet 子代理研究 `specs/*`，学习应用规格。
0b. 研究 @IMPLEMENTATION_PLAN.md（如果存在），了解当前计划状态。
0c. 研究 `src/lib/*`，了解共享工具和组件。
0d. 参考：应用源代码在 `src/*` 中。

1. 研究 @IMPLEMENTATION_PLAN.md（如果存在；它可能是错误的），使用最多 500 个 Sonnet 子代理研究 `src/*` 中现有代码，与 `specs/*` 对比。使用 Opus 子代理分析发现，按优先级排序，创建/更新 @IMPLEMENTATION_PLAN.md 为待实现项目的清单。

重要：只做规划。不要实现任何功能。不要假设功能缺失；先用代码搜索确认。
用 Opus 子代理完成复杂推理（调试、架构决策）。

最终目标：我们想实现 [你的项目目标]。考虑缺失的元素并相应规划。
如果某个元素缺失，先搜索确认它不存在，然后在 specs/FILENAME.md 中编写规格。

PROMPT_build.md（构建模式——逐个任务实现）：

0a. 使用最多 500 个并行 Sonnet 子代理研究 `specs/*`，学习应用规格。
0b. 研究 @IMPLEMENTATION_PLAN.md，了解当前进度。
0c. 参考：应用源代码在 `src/*` 中。

1. 你的任务是按照规格实现功能，使用并行子代理。遵循 @IMPLEMENTATION_PLAN.md，选择最重要的待办事项。在修改之前，先用 Sonnet 子代理搜索代码库（不要假设未实现）。你可以使用最多 500 个并行 Sonnet 子代理进行搜索/读取，只用 1 个 Sonnet 子代理进行构建/测试。复杂推理（调试、架构决策）使用 Opus 子代理。
2. 实现功能或解决问题后，运行改进代码单元的测试。如果测试缺失，你需要按规格添加。深度思考。
3. 发现问题时，立即用子代理更新 @IMPLEMENTATION_PLAN.md。问题解决后更新并移除该项。
4. 测试通过后，更新 @IMPLEMENTATION_PLAN.md，然后 `git add -A`，`git commit`（描述变更），`git push`。

99999. 重要：编写文档时，记录"为什么"——测试和实现的重要性。
999999. 重要：单一数据源，不要迁移/适配器。如果与你工作无关的测试失败，作为增量的一部分解决它们。
9999999. 一旦没有构建或测试错误，创建 git tag。如果没有 tag，从 0.0.0 开始，每次递增 patch。
99999999. 调试问题时可以添加额外日志。
999999999. 用子代理保持 @IMPLEMENTATION_PLAN.md 最新——未来的工作依赖于此，避免重复工作。每轮完成后尤其要更新。
9999999999. 学到关于如何运行应用的新知识时，用子代理更新 @AGENTS.md，但保持简洁。
99999999999. 发现的任何 bug，解决它或用子代理记录在 @IMPLEMENTATION_PLAN.md 中，即使与当前工作无关。
999999999999. 完整实现功能。占位符和存根浪费精力，导致重复工作。
9999999999999. @IMPLEMENTATION_PLAN.md 变得很大时，定期清理已完成的项目。
99999999999999. 如果在 specs/* 中发现不一致，使用 Opus 子代理（要求 ultrathink）更新规格。
999999999999999. 重要：@AGENTS.md 只保留操作指南——状态更新和进度记录放在 IMPLEMENTATION_PLAN.md。臃肿的 AGENTS.md 会污染未来每个循环的上下文。

4.5 编写循环脚本

loop.sh：

#!/bin/bash
set -euo pipefail

# 参数解析
MODE="${1:-build}"
PROMPT_FILE=""
MAX_ITERATIONS=0

case "$MODE" in
plan)
PROMPT_FILE="PROMPT_plan.md"
MAX_ITERATIONS="${2:-3}" # 规划通常 1-3 轮足够
;;
build)
PROMPT_FILE="PROMPT_build.md"
MAX_ITERATIONS="${2:-0}" # 0 = 无限循环
;;
*)
echo "用法: $0 {plan|build} [最大迭代次数]"
exit 1
;;
esac

# 检查 Prompt 文件
if [ ! -f "$PROMPT_FILE" ]; then
echo "错误: $PROMPT_FILE 不存在"
exit 1
fi

CURRENT_BRANCH=$(git branch –show-current)
ITERATION=0

echo "═══════════════════════════════════════"
echo " Ralph Loop 启动"
echo " 模式: $MODE"
echo " Prompt: $PROMPT_FILE"
echo " 分支: $CURRENT_BRANCH"
echo " 最大迭代: $([ $MAX_ITERATIONS -gt 0 ] && echo $MAX_ITERATIONS || echo '无限')"
echo "═══════════════════════════════════════"

while true; do
# 检查是否达到最大迭代次数
if [ $MAX_ITERATIONS -gt 0 ] && [ $ITERATION -ge $MAX_ITERATIONS ]; then
echo ""
echo "═══════════════════════════════════════"
echo " 已达到最大迭代次数: $MAX_ITERATIONS"
echo "═══════════════════════════════════════"
break
fi

echo ""
echo "┌───────────────────────────────────────"
echo "│ 第 $((ITERATION + 1)) 轮迭代开始…"
echo "│ 时间: $(date '+%Y-%m-%d %H:%M:%S')"
echo "└───────────────────────────────────────"

# 执行 Ralph
cat "$PROMPT_FILE" | claude -p \\
–dangerously-skip-permissions \\
–output-format=stream-json \\
–model opus \\
–verbose

# 自动推送
git push origin "$CURRENT_BRANCH" 2>/dev/null || {
echo "推送失败，尝试设置上游分支…"
git push -u origin "$CURRENT_BRANCH"
}

ITERATION=$((ITERATION + 1))

echo ""
echo "═══════════════════════════════════════"
echo " 第 $ITERATION 轮完成"
echo " 最新提交: $(git log -1 –oneline)"
echo "═══════════════════════════════════════"

# 检查是否所有任务完成
if [ -f "IMPLEMENTATION_PLAN.md" ]; then
REMAINING=$(grep -c '^\\- \\[ \\]' "IMPLEMENTATION_PLAN.md" 2>/dev/null || echo "0")
if [ "$REMAINING" = "0" ]; then
echo ""
echo "🎉 所有任务已完成！"
break
fi
echo " 剩余任务: $REMAINING"
fi
done

chmod +x loop.sh

4.6 运行 Ralph

# 第一步：生成实现计划（规划模式）
./loop.sh plan

# 第二步：开始构建（构建模式，迭代 20 次）
./loop.sh build 20

# 或者持续构建直到完成（Ctrl+C 停止）
./loop.sh build

4.7 运行时的监控要点

当你运行 Ralph 时，你应该坐在循环之上，而不是循环之中（Sit ON the loop, not IN it）：

• 👀 观察失败模式：Agent 在哪些任务上反复失败？是 Prompt 不够清晰，还是 Spec 有歧义？
• 📝 更新 AGENTS.md：记录 Agent 应该知道的操作细节
• 🔧 调整 Spec：如果 Agent 持续误解需求，说明 Spec 需要更明确
• ⏸️ 适时暂停：发现问题模式时，Ctrl+C 暂停，调整 Prompt/Spec 后继续

5. 多智能体编排架构设计

单 Agent 循环适用于简单项目，但对于复杂系统，我们需要多智能体协同。这就是 Ralph 编排层的价值。

5.1 从"循环"到"编排"

单 Agent Ralph Loop 的核心循环：

┌──────────────────────────────────────────┐
│ while true: │
│ agent = spawn() │
│ agent.execute(task) │
│ if verify(): break │
└──────────────────────────────────────────┘

多智能体编排在此基础上增加了角色分工和流水线并行：

┌─────────┐ ┌──────────┐ ┌──────────┐
│ PRD │────▶│ 架构 │────▶│ 实现 │
│ Agent │ │ Agent │ │ Agent │
└─────────┘ └──────────┘ └──────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ 代码 │◀────│ 测试 │
│ 审查 │ │ Agent │
└──────────┘ └──────────┘

5.2 四种多 Agent 编排模式

Ralph 生态（以 Maestro-Flow / Ralph Orchestrator v2 为代表）支持四种编排模式：

模式一：Delegate（异步委派）

主 Agent 子 Agent 1
│ │
├── 委派任务1 ────────────▶ │
│ ├── 执行
├── 委派任务2 ────────────▶ │ (不等待)
│ └── 完成 → 通知主 Agent
├── 继续其他工作
│
└── 收到通知 → 汇总结果

适用场景：独立子任务，主 Agent 不需要立即获得结果。

模式二：Team（角色协作）

┌─────────────────────────────────────────────────┐
│ Team Lead (Opus) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Planner │ │ Builder │ │Validator │ │
│ │ (Opus) │ │ (Sonnet) │ │ (Sonnet) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ 制定计划 实现功能 验证结果 │
└─────────────────────────────────────────────────┘

适用场景：需要多种技能协作的复杂任务。每个角色有自己的专业 Prompt 和模型配置。

模式三：Wave（依赖并行）

任务A (无依赖)
│
┌──────┼──────┐
▼ ▼ ▼
任务B 任务C 任务D (依赖A，可并行)
│ │ │
└──────┼──────┘
▼
任务E (依赖B,C,D全部完成)

适用场景：有依赖关系但同层可并行的任务图。

模式四：Swarm（蚁群探索）

┌── Agent1: 搜索方案A
│
主Agent ──┼── Agent2: 搜索方案B
│
├── Agent3: 搜索方案C
│
└── 收集所有方案 → 评估 → 选择最优

适用场景：需要广泛探索方案空间的场景（架构选型、技术调研）。

5.3 "帽子"系统（Hat-based Architecture）

Ralph Orchestrator v2 引入了创新的**"帽子"角色系统**——Agent 通过戴上不同的"帽子"来切换角色，通过类型化事件进行通信：

// 概念示例：帽子角色定义
const hats = {
architect: {
model: "opus",
prompt: "你是一个系统架构师…",
events: ["design.proposed", "design.revised"]
},
builder: {
model: "sonnet",
prompt: "你是一个前端开发者…",
events: ["code.written", "test.passed", "test.failed"]
},
reviewer: {
model: "sonnet",
prompt: "你是一个代码审查者…",
events: ["review.approved", "review.changes_requested"]
}
}

// Agent 通过事件通信
orchestrator.on("design.proposed", (data) => {
orchestrator.dispatch("builder", { task: data.implementationTask })
})

orchestrator.on("code.written", (data) => {
orchestrator.dispatch("reviewer", { code: data.diff })
})

5.4 流水线设计：ADR Ralph 的三阶段模式

ADK Ralph（Rust 实现）展示了一个经典的三阶段流水线设计：

用户输入
│
▼
┌─────────────────────────────────────────────┐
│ 阶段1: PRD Agent │
│ 模型: Gemini 3.1 Pro │
│ 输入: 用户需求描述 │
│ 输出: 结构化 PRD（功能、验收标准、约束） │
│ 门禁: PRD 通过 schema 验证 │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 阶段2: Architect Agent │
│ 模型: Gemini 3 Pro │
│ 输入: PRD 文档 │
│ 输出: 系统设计 + 任务分解 │
│ 门禁: 设计评审通过 │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 阶段3: Ralph Loop Agent │
│ 模型: Gemini 2.5 Flash │
│ 输入: 任务列表 + 设计文档 │
│ 过程: 逐个任务执行（Ralph Loop 模式） │
│ 每个任务: 实现 → 测试 → 通过 → 提交 │
│ 门禁: 所有测试通过, lint 通过, 构建成功 │
└─────────────────────────────────────────────┘
│
▼
交付物: 完整实现 + 测试 + 文档

关键设计决策：

• 不同阶段使用不同能力的模型——PRD 需要强推理（Pro），实现需要快速执行（Flash）
• 每个阶段有独立的验证门禁
• 阶段间通过文件系统传递状态，不依赖上下文

6. 实战：构建完整的多智能体开发流水线

现在，我们来构建一个完整的实战项目。我们将使用 ralph-teams（轻量多 Agent 编排器）来实现一个任务管理 API。

6.1 安装与初始化

# 安装 ralph-teams
npm install -g ralph-teams

# 创建项目
mkdir task-manager && cd task-manager
git init
npm init -y

# 交互式配置 Ralph
ralph-teams setup

ralph-teams setup 会引导你完成以下配置：

? 选择后端 (Select backend):
❯ Claude (claude CLI)
Codex (codex CLI)
Copilot (gh CLI)
OpenCode (opencode CLI)

? 选择工作流预设 (Workflow preset):
minimal – 无规划/验证子代理，最快
❯ balanced – 仅 Epic 级规划，Epic 级验证
full – 全流程规划+验证，最严谨

? 最大并行 Epic 数 (Max parallel epics):
❯ 3

? 每 Epic 最大故事数 (Max stories per epic):
❯ 5

这会生成配置文件 ralph.config.yml：

backend: claude
preset: balanced
parallelism: 3
max_stories_per_epic: 5
model_overrides:
teamLead: opus
epicPlanner: opus
builder: sonnet
validator: sonnet

6.2 编写 PRD

# 交互式创建 PRD（AI 辅助）
ralph-teams init

AI 会询问你关于项目的需求，然后生成结构化的 PRD。你也可以手动编写 prd.json：

{
"project": "任务管理 API",
"description": "一个 RESTful 任务管理后端服务",
"epics": [
{
"id": "epic-1",
"name": "用户认证系统",
"description": "用户注册、登录、Token 管理",
"stories": [
{
"id": "story-1.1",
"name": "用户注册",
"description": "POST /api/auth/register – email + password 注册，返回 JWT token",
"acceptance": [
"密码 bcrypt 加密存储",
"返回有效 JWT token",
"email 唯一性校验",
"单元测试覆盖率 > 80%"
]
},
{
"id": "story-1.2",
"name": "用户登录",
"description": "POST /api/auth/login – email + password 登录，返回 JWT token",
"acceptance": [
"5次失败后锁定15分钟",
"返回 access_token + refresh_token",
"集成测试通过"
]
},
{
"id": "story-1.3",
"name": "Token 刷新",
"description": "POST /api/auth/refresh – 使用 refresh_token 获取新 access_token",
"acceptance": [
"过期 refresh_token 返回 401",
"新 token 包含正确用户信息"
]
}
]
},
{
"id": "epic-2",
"name": "任务 CRUD",
"description": "任务的创建、读取、更新、删除操作",
"stories": [
{
"id": "story-2.1",
"name": "创建任务",
"description": "POST /api/tasks – 认证用户创建新任务",
"acceptance": [
"未认证返回 401",
"标题必填校验",
"截止日期格式校验"
]
},
{
"id": "story-2.2",
"name": "任务列表与筛选",
"description": "GET /api/tasks – 分页、筛选、排序",
"acceptance": [
"支持状态筛选",
"支持分页 (limit/offset)",
"只能看到自己的任务"
]
}
]
}
]
}

6.3 验证 PRD

# 检查 PRD 结构是否正确
ralph-teams validate

# 预览工作计划
ralph-teams summary

输出示例：

📋 项目: 任务管理 API
━━━━━━━━━━━━━━━━━━━━━━

📦 Epic 1: 用户认证系统 (3 stories)
✅ story-1.1: 用户注册
✅ story-1.2: 用户登录
✅ story-1.3: Token 刷新

📦 Epic 2: 任务 CRUD (2 stories)
✅ story-2.1: 创建任务
✅ story-2.2: 任务列表与筛选

总计: 2 Epics, 5 Stories
预估: 无依赖的 Epic 可并行执行

6.4 启动多 Agent 执行

# 启动 Ralph 多 Agent 编排（3 个 Epic 并行）
ralph-teams run –parallel 3

# 或者限制只执行单个 Epic
ralph-teams run –max-epics 1

执行时的内部工作流：

┌─────────────────────────────────────────────────────┐
│ Team Lead (Opus) 启动 │
│ │
│ 分析 PRD → 识别依赖关系 → 决定执行顺序 │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Epic 1 团队 │ │ Epic 2 团队 │ (并行执行) │
│ │ │ │ │ │
│ │ TeamLead → │ │ TeamLead → │ │
│ │ Planner → │ │ Builder → │ │
│ │ Builder→ │ │ Valid.→ │ │
│ │ Valid. │ │ Merge │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ 收集结果 → 生成报告 │
└─────────────────────────────────────────────────────┘

6.5 监控进度

# 查看日志
ralph-teams logs

# 查看状态
ralph-teams status

输出示例：

📊 Ralph Teams 状态
━━━━━━━━━━━━━━━━━━

🟢 Epic 1: 用户认证系统
├─ 🟢 story-1.1: 用户注册 — PASS (2m 34s)
├─ 🟢 story-1.2: 用户登录 — PASS (3m 12s)
└─ 🔵 story-1.3: Token 刷新 — RUNNING…

🟢 Epic 2: 任务 CRUD
├─ 🔴 story-2.1: 创建任务 — FAIL (重试 2/3)
└─ ⬜ story-2.2: 任务列表 — WAITING

━━━━━━━━━━━━━━━━━━
进度: 2/5 完成, 1 运行中, 1 失败, 1 等待

6.6 失败处理与重试

当 Agent 失败时（比如测试不通过），Ralph 会自动重试：

story-2.1: 创建任务 — 第 1 次尝试
❌ 测试失败: "Task title validation missing"
→ 更新 IMPLEMENTATION_PLAN.md 记录失败原因

story-2.1: 创建任务 — 第 2 次尝试（自动）
Agent 读取失败记录 → 理解问题 → 修复代码
❌ 测试失败: "Auth middleware not applied"
→ 更新 IMPLEMENTATION_PLAN.md

story-2.1: 创建任务 — 第 3 次尝试（自动）
Agent 读取所有失败记录 → 全面修复
✅ 所有测试通过!
→ git commit + push
→ 标记 story-2.1 完成

关键机制：每次重试都是一个全新 Agent，它从文件中读取之前失败的原因，然后尝试不同的方法——这比让同一个 Agent 在长对话中"再试一次"有效得多。

6.7 完整流程总结

1. 编写 Spec/PRD
│
▼
2. ralph-teams init ─── AI 辅助生成结构化 PRD
│
▼
3. ralph-teams validate ─── 验证 PRD 结构
│
▼
4. ralph-teams summary ─── 预览工作计划
│
▼
5. ralph-teams run ─── 启动多 Agent 编排
│
├── Team Lead 分析依赖
├── 并行分配独立 Epic
├── 每 Epic: Planner → Builder → Validator
├── 失败自动重试（全新上下文）
└── 通过后 git commit + push
│
▼
6. ralph-teams logs ─── 查看详细日志
│
▼
7. 代码审查 + 合并

7. 进阶话题

7.1 自定义 Stop Hook

Stop Hook 是 Ralph 的"守门人"。你可以根据项目需求自定义验证逻辑：

#!/usr/bin/env python3
"""自定义 Stop Hook：验证当前迭代是否应该停止"""

import subprocess
import sys
import json
from pathlib import Path

def run_tests() –> bool:
"""运行测试套件"""
result = subprocess.run(
["npm", "test"],
capture_output=True,
text=True
)
return result.returncode == 0

def run_lint() –> bool:
"""运行 Lint 检查"""
result = subprocess.run(
["npx", "eslint", "src/", "–max-warnings=0"],
capture_output=True,
text=True
)
return result.returncode == 0

def check_types() –> bool:
"""类型检查"""
result = subprocess.run(
["npx", "tsc", "–noEmit"],
capture_output=True,
text=True
)
return result.returncode == 0

def check_completion_markers() –> bool:
"""检查 PRD 中是否所有任务都标记完成"""
prd = json.loads(Path("prd.json").read_text())
all_stories = []
for epic in prd["epics"]:
all_stories.extend(epic["stories"])

# 检查 IMPLEMENTATION_PLAN.md
plan = Path("IMPLEMENTATION_PLAN.md").read_text()
incomplete = [s["id"] for s in all_stories if s["id"] not in plan or f"[ ] {s['id']}" in plan]

if incomplete:
print(f"未完成的故事: {incomplete}")
return False
return True

def main():
gates = [
("测试", run_tests),
("Lint", run_lint),
("类型检查", check_types),
("完成标记", check_completion_markers),
]

all_passed = True
for name, gate in gates:
print(f"🔍 检查 {name}…", end=" ")
if gate():
print("✅")
else:
print("❌")
all_passed = False

if not all_passed:
print("\\n❌ 验证未通过，继续下一轮迭代…")
sys.exit(1)

print("\\n✅ 所有验证通过！")
sys.exit(0)

if __name__ == "__main__":
main()

将 Stop Hook 集成到循环脚本中：

# 在 loop.sh 的每次迭代后调用
cat "$PROMPT_FILE" | claude -p –dangerously-skip-permissions

# Stop Hook 检查
if python3 stop_hook.py; then
echo "✅ 验证通过，可以停止"
break
else
echo "🔄 验证未通过，继续迭代"
fi

7.2 知识积累与反馈学习

一个成熟的 Ralph 系统应该具备从失败中学习的能力。以 Ralph Zero 的 “Librarian Agent” 机制为例：

流程：
1. 每次迭代后，Builder Agent 记录学习到的经验
2. Librarian Agent 定期汇总所有经验
3. 提炼为 AGENTS.md 中的操作指南
4. 后续 Agent 启动时读取 AGENTS.md，避免重复错误

示例学习记录：
┌─────────────────────────────────────────┐
│ 📝 学习记录 #42 │
│ │
│ 问题: 使用 Prisma 的 createMany 时 │
│ 在 SQLite 上跳过验证 │
│ │
│ 解决: 在 sqlite 环境下使用循环 create │
│ 代替 createMany │
│ │
│ 影响文件: src/db/repository.ts │
│ 标签: #database #sqlite #prisma │
└─────────────────────────────────────────┘

7.3 跨模型调度策略

不同的任务适合不同的模型。一个成熟的编排策略应该根据任务特征选择合适的模型：

# 模型路由策略
model_routing:
# 规划和设计任务：最强推理能力
planning:
default: opus
fallback: sonnet

# 代码生成任务：平衡速度和质量
coding:
default: sonnet
simple_tasks: haiku # 简单机械任务用最快模型

# 代码审查任务：需要仔细检查
review:
default: sonnet

# 测试生成任务
testing:
default: sonnet

在 Ralph Loop 的 Prompt 中实现模型分层：

# PROMPT_build.md 中的模型选择策略

1. 使用 Sonnet 子代理进行搜索和读取（最多 500 并行）
2. 使用 Sonnet 子代理进行构建和测试（1 个）
3. 仅在以下情况使用 Opus 子代理：
– 调试复杂 bug
– 架构决策
– 分析 specs/* 中的不一致
– 更新关键设计文档
4. 简单机械工作直接完成，不浪费 Opus 资源

7.4 Docker 沙箱隔离

由于 Ralph 需要 –dangerously-skip-permissions（跳过所有权限确认），强烈建议在 Docker 中运行：

# Dockerfile
FROM node:20-slim

# 安装必要工具
RUN apt-get update && apt-get install -y \\
git \\
curl \\
&& rm -rf /var/lib/apt/lists/*

# 安装 Claude Code
RUN npm install -g @anthropic-ai/claude-code

# 创建工作目录
WORKDIR /workspace

# 复制项目文件
COPY . .

# 设置 OAuth Token（通过环境变量或挂载）
# docker run -e CLAUDE_OAUTH_TOKEN="sk-ant-oat01-…" …

CMD ["./loop.sh", "build"]

# 构建和运行
docker build -t ralph-runner .
docker run \\
-e CLAUDE_OAUTH_TOKEN="$CLAUDE_OAUTH_TOKEN" \\
-v $(pwd):/workspace \\
ralph-runner

7.5 多 Agent 并行的工作树隔离

当多个 Agent 并行工作时，需要隔离它们的工作空间：

项目仓库
├── .ralph/
│ └── worktrees/
│ ├── epic-1/ # Epic 1 的独立工作树
│ │ └── (完整项目副本)
│ ├── epic-2/ # Epic 2 的独立工作树
│ │ └── (完整项目副本)
│ └── epic-3/ # Epic 3 的独立工作树
│ └── (完整项目副本)

每个 Epic 在自己的工作树中执行，完成后合并回主分支：

# 为每个 Epic 创建独立工作树
git worktree add .ralph/worktrees/epic-1 epic-1-branch
git worktree add .ralph/worktrees/epic-2 epic-2-branch

# 并行执行
# (Agent 1 在 .ralph/worktrees/epic-1 中工作)
# (Agent 2 在 .ralph/worktrees/epic-2 中工作)

# 完成后合并
git merge epic-1-branch
git merge epic-2-branch

# 清理
git worktree remove .ralph/worktrees/epic-1
git worktree remove .ralph/worktrees/epic-2

8. Ralph 生态选型指南

看到这里你可能会问：这么多 Ralph 实现，我该选哪个？以下是选择建议：

决策树

你要做什么？
│
├── 想快速体验 Ralph 概念
│ └── 手写 shell loop.sh（本文第4章）
│ 最简单，5 分钟上手
│
├── 管理一个中小型项目，需要多 Agent 协同
│ └── ralph-teams
│ 轻量级，Team Lead 模式，Epic 级编排
│ 安装: npm install -g ralph-teams
│
├── 需要完整的开发生命周期管理
│ └── ADK Ralph (Rust) 或 Ralph Zero (Python)
│ PRD → 架构 → 实现完整流水线
│ 支持 14+ LLM 提供商
│
├── 需要高度自定义的工作流编排
│ └── Maestro-Flow 或 Ralph Orchestrator
│ 40+ 预设命令链，4 种编排模式
│ 帽子角色系统，事件驱动架构
│
└── 在 VS Code 中使用
└── RalphDex (VS Code 扩展)
持久化文件驱动，可视化仪表板
支持并行多 Agent 循环

快速对比

9. 总结与展望

核心要点回顾

Ralph 方法论的精髓

“坐在循环之上，而不是循环之中” — Ralph Orchestrator 哲学

你的角色不是与 Agent 对话，而是：

• 📝 定义清晰的 Spec 和验收标准
• 👀 观察 Agent 的失败模式
• 🔧 持续优化 Prompt 和流程
• ✅ 确保验证门禁有效

展望

Ralph 生态正在快速发展中（截至 2026 年 7 月）：

• 社区聚合：多个独立实现正在向共同模式收敛（PRD 驱动、文件记忆、外部验证）
• 企业集成：Azure Foundry、AWS 等企业平台的适配
• 模型无关：从单一 Claude 后端发展到支持 14+ LLM 提供商
• 知识积累：从一次性执行到持续学习和知识复用
• 多模态扩展：从纯代码到设计稿→代码、文档→代码等多模态输入

开始你的第一个 Ralph 项目

# 5 分钟快速开始
mkdir my-first-ralph && cd my-first-ralph
git init

# 创建你的第一个 Spec
echo "# Hello World API
## 验收标准
– [ ] GET /hello 返回 { \\"message\\": \\"Hello, Ralph!\\" }
– [ ] 包含单元测试
– [ ] ESLint 零警告" > specs/hello.md

# 创建 Prompt（使用第 4 章的模板）
# 创建 loop.sh（使用第 4 章的脚本）

# 运行
./loop.sh plan # 生成计划
./loop.sh build 5 # 执行 5 轮

# 见证 Ralph 自动完成你的第一个项目 🎉

参考资源

• Geoffrey Huntley’s Ralph Wiggum — Ralph Loop 的起源
• Ralph Playbook — 完整的实践指南
• ADK Ralph — Rust 实现的 Ralph 流水线
• Ralph Zero — Python Agent Skills 编排器
• ralph-teams — 轻量多 Agent 团队编排
• Ralph Orchestrator — 帽子系统的多 Agent 框架
• AWS Ralph Loop Sample — AWS 官方 Ralph 示例

作者的话：Ralph 不只是一个工具，更是一种思维方式。它教会我们如何与 AI Agent 有效协作——不是让 AI 代替你思考，而是让 AI 在一个你设计好的框架内高效执行。希望这篇文章能帮助你理解和实践 Ralph 多智能体编排，构建出真正可靠的 AI 驱动开发流程。

如果你在实践过程中遇到问题，欢迎在评论区交流讨论！ 🚀