Mastra 中的 Ralph 命令规划：用结构化协作方法构建可执行的自主循环任务

Mastra 中的 Ralph 命令规划：用结构化协作方法构建可执行的自主循环任务

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

导读

在 Mastra 仓库中，Ralph（Ralph Wiggum Loop）是一种让代理"反复失败直至成功"的自主执行模式：代理持续迭代、保留上下文、直到满足完成标准（测试通过、构建成功）才停止。而 .claude/commands/ralph-plan.md 描述的 Ralph Plan，正是为这种模式服务的"命令规划器"——一个引导 Agent 与用户进行多轮对话、把模糊目标逐步细化成结构化 Ralph 命令的协作流程。读完本文，你将掌握 Ralph 命令的四段式结构（background / setup / tasks / testing）、五步规划流程、九条规划准则，以及如何在 Mastra 源码中定位支撑这一模式的完成度评分器与自主循环实现，从而独立编写出可复制、可执行、可验证的高质量 Ralph 命令。

一、Ralph 命令与 Ralph Plan 的定位

1.1 Ralph 命令：自主循环的最小可执行单元

Ralph 命令本质上是给 Agent 的一份"作战计划"，它把一次自主执行拆解为四个强制区块，并以一个 promise 作为完成信号。这与仓库 explorations/ralph-wiggum-loop-integration.md 中定义的 Ralph Wiggum Loop 理念完全一致：代理需要"持续迭代、保留每次运行的结果、依据清晰的完成标准（测试通过、构建成功）判断是否结束"，并受"最大迭代次数、超时"等安全控制约束。

从该集成文档看，Ralph 模式的五大关键特征为：

1. 持久迭代（Persistent Iteration）：代理持续循环执行；
2. 上下文保留（Context Preservation）：每一轮迭代都能看到此前运行的结果；
3. 完成标准（Completion Criteria）：有明确的成功度量（测试通过、构建成功）；
4. 安全控制（Safety Controls）：最大迭代次数、超时；
5. 失败即数据（Failure as Data）：每次失败的尝试都会反馈给下一轮迭代。

Ralph 命令的<tasks>区块正是完成标准的来源，<testing>区块则是完成标准的验证手段——二者共同构成自主循环的"退出条件"。

1.2 Ralph Plan：规划器而非执行器

Ralph Plan 是一个规划助手（planning assistant）。它的目标不是替你执行任务，而是通过提问、澄清、逐步细化，与你共同产出一份"重点明确、可落地"的 Ralph 命令。因此它天然是对话式、迭代式的：先理解目标，再逐段填充命令结构，最终给出完整命令供直接复制。

在 Claude Code 的命令体系里，这类文件位于.claude/commands/目录，被 slash command 机制加载为 Agent 的指令，让 Agent 在收到用户输入后扮演规划助手角色。

二、Ralph 命令的四段式结构

一份完整的 Ralph 命令由以下区块构成（这是 Ralph Plan 输出结果的唯一合法形态）：

<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.

各区块职责如下：

注意原文档特意要求输出格式中使用单引号而避免双引号与反引号，因为当命令被复制执行时，这些字符会干扰格式化。这一细节在输出完整命令时务必遵守。

三、五步规划流程：从目标到命令

Ralph Plan 将规划过程拆成五个明确步骤，每一步都对应命令结构中的一个或多个区块。

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

规划器需要向用户确认三件事：

• 高层目标是什么（What is the high-level goal?）；
• 涉及代码库的哪个部分（What area of the codebase does this involve?）；
• 是否存在约束或要求（Are there any constraints or requirements?）。

这一步产出是后续所有区块的事实基础。

Step 2：定义背景（Define Background）

帮助用户确定：

• 执行 Agent 应假定的专业身份/人设（What expertise/persona should the agent assume?）；
• 用一句话概括的核心目标（What is the core objective in one sentence?）。

这直接对应<background>区块。仓库中的示例 Agent 人设可以参考 explorations/ralph-wiggum-loop-prototype.ts 注释中的migrationAgent：它被定义为"测试迁移专家"，指令中明确列出"分析现有测试结构 → 识别需要改动的内容 → 执行修改 → 验证改动正确"，正是<background>应该达到的详细程度。

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

确定：

• 需要哪些技能或工具（What skills or tools are needed?）；
• 需要先做哪些探索/研究（What exploration/research is required first?）；
• 需要哪些环境准备（What environment setup is needed?）。

这对应<setup>区块。原文档第七条准则也强调：Setup 步骤应包含"研究/探索以理解现有代码"，比如用户说"像 tools tab 一样加一个 tab"时，执行者应先阅读 tools 的实现来理解模式、文件结构和约定。

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

与用户协作，把目标拆成：

• 具体的、编号的、可验证的任务；
• 按依赖关系逻辑排序（先做被依赖的部分）；
• 在有助于理解的地方附带实现细节。

这对应<tasks>区块。原文档给出的好例子与坏例子对比非常直观：

• 坏："Improve the UI"（过于模糊）；
• 好："Create a '/processors' endpoint that lists processors, mimicking the '/tools' endpoint"（具体、可验证、参考了现有模式）。

Step 5：定义测试（Define Testing）

确定：

• 如何构建/编译改动（How to build/compile changes）；
• 如何运行并验证工作（How to run and verify the work）；
• 成功看起来是什么样（What success looks like）。

这对应<testing>区块。测试是 Ralph 循环的完成标准载体——在 Mastra 的完成度评分机制中，一个典型的testsScorer就是通过执行npm test来判断"是否完成"的（详见下文第六节）。

四、九条规划准则

Ralph Plan 明确要求规划过程遵循九条准则，这是保证命令质量的核心约束：

1. 保持探究精神（Be Inquisitive）：主动追问实现细节、边界情况和假设。不要接受模糊描述，一直深挖到清晰为止。
2. 识别缺口（Identify Gaps）：主动指出缺失、模糊或后续会出问题的内容。原文档给出的三个示例追问：
   • "你说要创建一个 endpoint，但还没指定请求/响应格式——应该是什么样？"
   • "这个任务依赖对 X 的理解，但没有对应的研究步骤——要不要加一个？"
   • "如果处理器抛错怎么办？UI 应该处理这种情况吗？"
3. 研究代码库（Research the Codebase）：不要只问用户——主动探索代码库填补知识空白。例如用户提到"添加一个像 tools tab 一样的 tab"，就去搜索并阅读 tools 的实现，从而：在任务中给出具体的文件路径和函数名、识别需要遵循的现有模式、发现需要连带修改的依赖代码、提供具体的实现细节而不是模糊指令。
4. 保持迭代（Be Iterative）：不要立即产出完整命令，而是提问、讨论选项、逐步精化。
5. 保持具体（Be Specific）：模糊任务导致混乱，帮助用户把任务具体化。
6. 包含上下文（Include Context）：Setup 步骤应包含理解现有代码所需的研究/探索。
7. 参考现有模式（Reference Existing Patterns）：尽可能指出可遵循的既有相似实现。
8. 考虑依赖（Consider Dependencies）：任务排序要让依赖先完成。
9. 控制范围（Keep Scope Focused）：Ralph 命令应有清晰、可达的范围；范围过大时建议拆成多条 Ralph 命令。

五、示例对话流程：以 playground 新功能为例

原文档给出了一个完整的交互示例骨架，展示了规划器如何"先提问、再起草、逐段确认"：

用户：I want to add a new feature to the playground（我想给 playground 加一个新功能）

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

1. 你要加什么功能？
2. 它影响 playground 的哪一部分？
3. 有没有我应该参考的相似既有功能？

用户：（提供细节）

助手：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?

（继续对每个区块迭代……）

这个流程的核心是：每起草一个区块就停下来与用户确认，而不是一次性交出全部内容。仓库中 explorations/agent-network-vs-ralph-wiggum.md 也印证了这种"先理解、后结构化"的协作思路在 Ralph 相关探索中的地位。

六、Ralph 命令背后的运行机制：完成度评分器

规划出的<testing>区块，最终会落到 Mastra Agent Network 的**完成度评分（completion scoring）**机制上。仓库 explorations/ralph-wiggum-loop-integration.md 明确指出：完成度检查其实就是MastraScorer——返回 0 表示"未完成"，返回 1 表示"完成"，从而把离线评测（evals）与运行时循环控制统一到同一个原语上。

6.1 CompletionConfig 的真实定义

在 packages/core/src/loop/network/validation.ts 中，CompletionConfig接口与 Ralph Plan 文档描述的结构完全对应：

• scorers?: MastraScorer[]：要运行的评分器（返回 0 或 1）；
• strategy?: 'all' | 'any'：'all'表示全部通过才完成（默认），'any'表示至少一个通过即完成；
• timeout?: number：所有评分器的最大耗时（毫秒），源码中的默认值为600000（10 分钟），实现中通过setTimeout兜底，防止某个评分器永不返回而卡住循环；
• parallel?: boolean：是否并行运行评分器，源码默认true，且并行模式下采用 Promise 竞速（race）方式丢弃超时的迟到结果；
• onComplete?: (results: CompletionRunResult) => void：评分结束后的回调。

CompletionRunResult返回{ complete: boolean, completionReason?: string, scorers: ScorerResult[] }，其中ScorerResult包含score、passed、reason、scorerId、scorerName、duration等字段。特别注意：评分器只回答问题"这事做完了吗"，它不生成最终结果——最终结果来自 primitive（agent/workflow/tool）的输出。

6.2 CompletionContext：评分器可访问的完整运行状态

源码中CompletionContext（通过run.input传入评分器）提供了丰富上下文，这与 Ralph Plan 强调的"具体、可验证"一脉相承：

• iteration：当前迭代次数（从 1 开始）；
• maxIterations：允许的最大迭代次数；
• messages：会话线程中的全部消息（MastraDBMessage[]）；
• originalTask：发起本次网络运行的原始任务/提示词；
• selectedPrimitive：本轮选中的 primitive（{ id, type: 'agent' | 'workflow' | 'tool' | 'none' }）；
• primitivePrompt与primitiveResult：发送给 primitive 的输入及其结果；
• networkName、runId、threadId、resourceId：运行标识与记忆定位信息；
• customContext：请求携带的自定义上下文。

6.3 两类评分器的写法

代码型评分器（适合"测试通过""构建成功"这类硬性检查）：

import { createScorer } from '@mastra/core/evals'; import { execSync } from 'child_process'; const testsScorer = createScorer({ id: 'tests', description: 'Run unit tests to verify code works', }).generateScore(async ({ run }) => { try { execSync('npm test', { stdio: 'pipe' }); return 1; // 测试通过 } catch { return 0; // 测试失败 } });

LLM 型评分器（适合需要语义判断的场景，可叠加judge模型）：

const taskCompleteScorer = createScorer({ id: 'task-complete', description: 'LLM evaluates if task is complete', judge: { model: openai('gpt-4o-mini'), instructions: 'You evaluate task completion.', }, }).generateScore({ description: 'Evaluate if the task is complete', createPrompt: ({ run }) => { const ctx = run.input; // CompletionContext return ` Original task: ${ctx.originalTask} Latest result: ${ctx.primitiveResult} Is this task complete? Return 1 if yes, 0 if no. `; }, });

两类评分器可自由混用，配合strategy: 'all'或'any'组合成复杂的完成判定。这与 Ralph Plan 中"任务要具体可验证"的准则互为表里——<testing>里写的每条验证步骤，最终都会被翻译成这样一个或一组评分器。

6.4 自主循环的执行原型

仓库中的 explorations/ralph-wiggum-loop-prototype.ts 是这一模式的完整原型实现，它展示了 Ralph 循环与 Mastra 既有原语（Agent + Workflow）如何结合：

• CompletionChecker接口（check: () => Promise<{ success, message?, data? }>）是评分器的早期形态；
• 提供现成的检查器工厂：testsPassing（默认npm test，超时 300s）、buildSucceeds（默认npm run build，超时 600s）、lintClean（默认npm run lint，超时 120s）、outputContains（检查输出是否含特定字符串/正则）、allCheckersPassing（全部通过才算完成）；
• AutonomousLoopConfig给出了循环的安全控制参数：maxIterations（最大迭代次数）、maxTokens（token 上限）、iterationDelay（迭代间隔）、contextWindow（保留多少轮历史结果）、onIteration/onIterationStart（每轮回调）；
• executeAutonomousLoop实现主循环：每轮把前contextWindow轮的成败与输出摘要注入下一轮提示词（失败的尝试作为数据反馈给 Agent），再执行完成检查，直到成功或达到maxIterations。

这套参数与 Ralph Plan 命令结构高度同构：<tasks>决定每轮做什么，<testing>提供CompletionChecker，maxIterations等安全参数则防止循环失控。

6.5 验证桥接：LLM 判定与程序化验证互补

explorations/network-validation-bridge.ts 进一步演示了如何把 Ralph 风格的程序化验证接入 Agent Network 的既有循环，其mode概念值得在规划<testing>时参考：

• verify：LLM 判定完成且程序化验证通过才算完成；
• override：只认程序化验证，忽略 LLM 判定；
• llm-fallback：优先尝试程序化验证，未配置检查项时退回 LLM。

桥接文件同样提供了testsPass、buildSucceeds、lintPasses、typeChecks（npx tsc --noEmit）等验证工厂，并支持strategy: 'all' | 'any'、timeout、parallel配置——与 6.1 节的CompletionConfig语义一致。

七、输出格式与交付

当规划最终定稿后，Ralph Plan 必须把完整的 Ralph 命令放在一个可直接复制的代码块中呈现给用户：

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

交付时必须遵守两条硬性规则：

1. 避免双引号（"）与反引号（`）：它们会干扰命令复制执行时的格式化，改用单引号（'），或干脆改写以避免引号；
2. 以<promise>COMPLETE</promise>收尾：这是自主循环的终止信号，缺少它循环将无法按预期结束。

此外，整个规划会话由规划器主动发起——Ralph Plan 的启动方式就是先问用户"你想完成什么"（Begin by asking the user what they want to accomplish），然后倾听目标、提出澄清问题、逐段协作构建命令。

八、实战自查清单

把 Ralph Plan 的方法论固化成一份可复用的自查清单，规划任何命令时逐项核对：

1. 背景完整吗：<background>是否写明了任务背景、Agent 人设、单句核心目标？
2. 环境就绪吗：<setup>是否包含技能激活、现状探索、必要研究三个层面的步骤？
3. 任务可验证吗：每个<tasks>条目是否具体到"可以判定对错"？是否按依赖排序？
4. 测试可执行吗：<testing>是否给出了明确的构建命令、运行方式和成功标准？（如npm test、npm run build、npx tsc --noEmit）
5. 范围可控吗：任务范围是否过大？是否需要拆分为多条 Ralph 命令？
6. 语法干净吗：命令中是否残留双引号或反引号？
7. 终止明确吗：是否以<promise>COMPLETE</promise>结尾？

按照这份清单生成的 Ralph 命令，可以直接对接 Mastra Agent Network 的完成度评分机制（packages/core/src/loop/network/validation.ts）或自主循环原型（explorations/ralph-wiggum-loop-prototype.ts），把"反复失败直至成功"的自主执行从理念落到可运行、可观测的工程实践。

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