Mastra Ralph 循环命令规划指南：从四段式命令结构到 Agent 自主迭代实战

Mastra Ralph 循环命令规划指南：从四段式命令结构到 Agent 自主迭代实战

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本篇指南聚焦 Mastra 仓库中的 Ralph 循环（Ralph Loop）命令规划方法，围绕 .cursor/commands/ralph-plan.md 定义的交互式规划助手展开。你将在文中掌握 Ralph 命令的四段式结构（background / setup / tasks / testing）、五步规划流程与九条规划原则，并结合仓库内 explorations/ralph-wiggum-loop-prototype.ts、explorations/ralph-wiggum-loop-integration.md 等源码级资料，理解这种"让 Agent 反复失败直至成功"的自主迭代模式在 Mastra Agent Network 中的真实落地形态。

Ralph 循环：一种"失败即数据"的自主执行模式

在进入命令构建细节之前，先厘清 Ralph 循环的核心理念。仓库中的设计文档 explorations/ralph-wiggum-loop-integration.md 将其概括为一句话："Let the agent fail repeatedly until it succeeds"（让 Agent 反复失败，直到成功）。

它的五个关键特征构成了整个命令结构的设计依据：

1. 持久迭代（Persistent Iteration）：Agent 持续循环执行，而不是单次生成后立即结束；
2. 上下文保留（Context Preservation）：每一轮迭代都能看到之前各轮的执行结果；
3. 完成标准（Completion Criteria）：存在清晰的、可程序化验证的成功度量（如测试通过、构建成功）；
4. 安全控制（Safety Controls）：最大迭代次数、超时等硬性边界；
5. 失败即数据（Failure as Data）：每一次失败的尝试都会被作为上下文喂给下一轮迭代。

而在 Mastra 中，该模式已从"构想"演进为"已实现"。同一份集成文档的标题状态栏明确写着：IMPLEMENTED - The Agent Network with completion scorers IS the autonomous loop。也就是说，你在构建 Ralph 命令时设计出的"任务分解 + 验证 + 迭代"思路，与 Mastra Agent Network 内置的 completion scorers 机制是同一套心智模型。

Ralph 命令的四段式结构

Ralph 命令本质是一份结构化的、可直接交给 Agent 执行的指令文档，由四个 XML 标签段落外加一个完成承诺组成：

<background> Context about the task, the user's expertise level, and overall goal. </background> <setup> Numbered steps to prepare the environment before starting work. Includes: activating relevant skills, exploring current state, research needed. </setup> <tasks> Numbered list of specific, actionable tasks to complete. Tasks should be concrete and verifiable. </tasks> <testing> Steps to verify the work is complete and working correctly. Includes: build commands, how to run/test, validation steps. </testing> Output <promise>COMPLETE</promise> when all tasks are done.

background：交代任务语境

这一段回答"为什么做这件事、谁来做、做到什么程度"。规划时应当明确 Agent 应承担的专业人设（persona）以及用一句话概括的核心目标（core objective）。上下文越充分，Agent 后续在 setup 与 tasks 阶段的自主动作越有依据。

setup：可编号的环境准备步骤

这一段是以编号列表形式呈现的执行前置条件，覆盖三类动作：

• 激活相关技能（skills）：例如让 Agent 加载特定领域的能力或工具；
• 探索当前状态（exploring current state）：先读懂现状再动手，避免凭空修改；
• 必要的研究（research needed）：补足知识空白所需的调研步骤。

tasks：具体且可验证的任务清单

这是命令的主体。每一项任务都必须是具体的（concrete）和可验证的（verifiable），并且按依赖关系排序——被依赖的任务优先。规划原则中特别强调，任务中可以包含具体的文件路径、函数名和实现细节，让 Agent 不必猜测。

testing：验证工作完成度的步骤

包含构建/编译命令、运行与测试方式、以及"什么样子算成功"的判定标准。这一段落对应 Ralph 循环中"外部程序化验证"的灵魂——典型验证手段是npm test、npm run build、npm run lint等命令（这一点在 explorations/agent-network-vs-ralph-wiggum.md 中被概括为"Deterministic Validation：测试要么通过要么失败"）。

promise 完成承诺

命令末尾要求 Agent 在所有任务完成后输出<promise>COMPLETE</promise>。这是一个终结信号，让循环具备明确的退出条件，避免 Agent 无限徘徊。

五步规划流程：从模糊想法到可执行命令

规划助手的核心职责不是替用户直接生成命令，而是通过提问、澄清、迭代，与用户共同打磨出最终产物。流程分为五个步骤：

Step 1：理解目标（Understand the Goal）

先向用户澄清三个问题：

• 高层目标是什么？
• 涉及代码库的哪个区域？
• 是否存在约束或要求？

Step 2：定义背景（Define Background）

帮助用户确定：Agent 应扮演什么专业人设、核心目标如何用一句话概括。背景段落的草案可以先写出来，再与用户确认是否准确。

Step 3：规划 Setup 步骤（Plan Setup Steps）

确定：需要哪些技能或工具、需要先做哪些探索/研究、需要哪些环境准备。setup 中应当包含"研究并理解现有代码"的步骤——这是规划原则第 6 条明确要求的。

Step 4：分解任务（Break Down Tasks）

与用户协作完成：

• 把目标拆解为具体的编号任务；
• 确保每项任务具体且可验证；
• 按依赖关系排序（依赖项优先）；
• 在有助于执行的地方加入实现细节。

Step 5：定义测试（Define Testing）

确定：如何构建/编译改动、如何运行并验证工作、成功的样子是什么。这与 Ralph 循环强调的"外部验证"完全同构——explorations/ralph-wiggum-loop-prototype.ts 中testsPassing、buildSucceeds、lintClean等完成度检查函数正是这种验证思想的代码化。

九条规划原则：把命令打磨到可直接执行

文档给出的九条原则构成了规划助手的"行为准则"，也是判断一条命令是否合格的标准：

1. 保持探究（Be Inquisitive）：主动追问实现细节、边界情况和假设，不接受含糊描述；
2. 识别缺口（Identify Gaps）：主动指出缺失、含糊或未来可能出问题的点。文档给出了三个示范追问：
   • "你提到要创建 endpoint，但没有指定请求/响应格式——应该是什么样？"
   • "这个任务依赖理解 X 的工作原理，但缺少相应研究步骤——要不要加一个？"
   • "如果处理器抛错会怎样？UI 需要处理这种情况吗？"
3. 研究代码库（Research the Codebase）：不要只问用户，要主动探索代码库填补知识空白。例如用户说"加一个像 tools 标签页那样的标签页"，就去搜索并阅读 tools 的实现，理解其模式、文件结构和约定，从而在任务中给出具体文件路径和函数名；
4. 保持迭代（Be Iterative）：不要一次性生成完整命令，而是边提问边讨论边细化；
5. 具体化（Be Specific）：含糊任务导致混乱。文档给出正反例对比：
   • 差："Improve the UI"
   • 好："Create a '/processors' endpoint that lists processors, mimicking the '/tools' endpoint"
6. 包含上下文（Include Context）：setup 步骤应包含研究/探索以理解现有代码；
7. 参考现有模式（Reference Existing Patterns）：尽可能指向已有的类似实现供参考；
8. 考虑依赖（Consider Dependencies）：任务排序要保证依赖先行；
9. 聚焦范围（Keep Scope Focused）：命令应有清晰可达的范围，范围过大则拆分为多条 Ralph 命令。

这九条原则中，"研究代码库"尤其重要——它要求规划者把仓库内的真实文件路径、函数名和既有模式沉淀进任务描述，这正是 Ralph 命令区别于泛泛 prompt 的关键所在。

示例对话流：协作式规划的节奏

文档给出了一段典型的对话节奏，展示规划助手如何与用户一来一回地推进：

用户：I want to add a new feature to the playground

助手：Let's plan this out. Can you tell me more about:

1. What feature are you adding?
2. What part of the playground does it affect?
3. Are there similar existing features I should look at for patterns?

用户：[提供细节]

助手：Got it. Let me draft the background section first:

<background> [Draft background based on discussion] </background>

Does this capture the goal correctly? Should I adjust anything?

[Continue iteratively through each section...]

注意这个节奏：先抛三个结构化问题（做什么、影响哪、有无可参考模式），再逐段起草、逐段确认。每个段落都先给草案、再征求意见，而不是一次性抛出一整份命令让用户被动接受。

最终输出格式与引号规避

当计划最终定稿时，规划助手需要把完整的 Ralph 命令放进一个可复制的代码块中呈现给用户。其中有一条非常实用的硬性约束：

Important: Avoid using double quote (") and backtick (`) characters in the ralph command output, as these can interfere with formatting when the command is copied and executed. Use single quotes (') instead, or rephrase to avoid quotes entirely.

也就是说，最终命令文本中应避免双引号和反引号（它们会在命令被复制执行时干扰格式），改用单引号或直接改写语句绕开引号。最终交付形态如下：

<background> ... </background> <setup> ... </setup> <tasks> ... </tasks> <testing> ... </testing> Output <promise>COMPLETE</promise> when all tasks are done.

而每次新的规划会话，都从询问用户想完成什么开始——先听目标、再提澄清问题、然后引导用户逐段构建命令。

源码纵深：Ralph 循环在 Mastra 中的三种落地形态

理解了命令构建方法后，再回到仓库源码看这套思想在 Mastra 中的真实实现，能帮助你写出更贴合框架能力的命令（尤其是 testing 段落的设计）。

形态一：Ralph Wiggum 循环原型（自主迭代工作流）

explorations/ralph-wiggum-loop-prototype.ts 用 Mastra 原生原语演示了自主循环模式。核心 APIexecuteAutonomousLoop(agent, config)接收一个AutonomousLoopConfig，其中与命令 testing 段落直接对应的字段包括：

• completion: CompletionChecker——如何判定任务完成（如测试通过）；
• maxIterations——放弃前的最大迭代次数；
• maxTokens——可选，最大 token 预算；
• iterationDelay——可选，迭代间隔毫秒数；
• contextWindow——可选，纳入上下文的历史迭代条数（默认 5）；
• onIterationStart/onIteration——可选，迭代生命周期回调。

仓库还提供了开箱即用的完成度检查器工厂：testsPassing('npm test')、buildSucceeds('npm run build')、lintClean('npm run lint')、outputContains(pattern)，以及将多个检查器组合的allCheckersPassing(...)。循环的核心行为是：把前几轮的结果（成功状态、输出截断、错误信息）拼进下一轮的上下文 prompt，让 Agent "基于前次尝试继续推进，处理错误与未完成部分"。这正是 Ralph 命令 tasks 段"可验证、可迭代"语义的运行时体现。

形态二：Agent Network + Completion Scorers（官方落地）

根据 explorations/ralph-wiggum-loop-integration.md，Agent Network 与 completion scorers 的结合就是"已经实现的自循环"：完成度检查只是返回 0（未完成）或 1（完成）的MastraScorer，从而统一了离线评测（evals）与运行时循环控制（completion）两套场景——同一原语，不同上下文。

配置入口是agent.network(messages, { completion: { ... } })，CompletionConfig支持scorers（评分器数组）、strategy（'all' 全部通过或 'any' 任一通过）、timeout、parallel、onComplete回调。这为 Ralph 命令的 testing 段落提供了原生映射：你在命令里写的验证命令，落地时可以直接封装成一个或多个 completion scorer。

形态三：网络验证桥接（程序化验证 + LLM 评估）

explorations/network-validation-bridge.ts 展示了如何把 Ralph 风格的程序化验证接入 Agent Network 循环，其核心是NetworkValidationConfig中的mode三态：

• verify：LLM 判定完成且程序化验证通过；
• override：只看程序化验证，忽略 LLM 自评；
• llm-fallback：优先验证，未配置检查时回退到 LLM 判定。

配套的检查工厂覆盖测试、构建、Lint、类型检查、文件存在、文件内容匹配等，并支持createValidationTools()把验证能力暴露为路由 Agent 可调用的工具。这一设计解决了"纯 LLM 自评可能产生幻觉性完成"的问题——正如对比文档 explorations/agent-network-vs-ralph-wiggum.md 指出的，两者是互补关系：Agent Network 提供路由与多原语编排，Ralph 模式提供程序化验证。

核心源码与测试的深入指引

如果想继续深挖，建议按以下路径阅读当前仓库：

• Ralph 命令定义本身：.cursor/commands/ralph-plan.md（本文主题文档）；
• 自主循环原型实现：explorations/ralph-wiggum-loop-prototype.ts，重点看executeAutonomousLoop的上下文拼接与完成检查逻辑；
• 完成度评分核心实现：packages/core/src/loop/network/validation.ts，包含CompletionContext（iteration、originalTask、selectedPrimitive、primitiveResult等运行时状态）、runCompletionScorers（支持并行/串行、超时截止、短路策略）、默认 LLM 完成检查runDefaultCompletionCheck以及formatCompletionFeedback反馈格式化；
• Agent Network 循环主流程：packages/core/src/loop/network/index.ts，路由 Agent 的 primitive 选择（agent/workflow/tool/none）与执行、验证步骤的编排；
• 完成度评分测试：packages/core/src/loop/network/validation.test.ts，以及 packages/core/src/agent/agent-network.test.ts，可验证 scorer 的通过/失败、超时、策略组合等行为。

结语：把规划方法论落到实践

回顾全文，Ralph 命令规划的本质是一套"结构化、可验证、可迭代"的任务拆解方法论：用 background 建立语境，用 setup 铺垫环境与研究，用 tasks 落地具体可验证的动作，用 testing 给出程序化的完成判据，最后以<promise>COMPLETE</promise>明确收尾。而在 Mastra 中，这套方法论并非停留在文本层面——completion scorers 机制（packages/core/src/loop/network/validation.ts）已经让"测试通过才视为完成"这一 Ralph 理念成为 Agent Network 的运行时能力。

当你在 Mastra 项目中编写 Ralph 命令时，不妨直接对照CompletionContext中暴露的字段（原始任务、当前迭代、所选 primitive、primitive 结果、消息历史）来设计 testing 段落，把验证命令封装为 scorer；当范围过大时，遵循"聚焦范围"原则拆成多条命令，让每一条都能在有限迭代内闭环。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra