Mastra 中的 Ralph Wiggum 自主循环从 Ralph Plan 交互规划到 Completion Scorer 落地实践【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以 Mastra 仓库中的ralph-plan技能为骨架系统讲解如何通过协作式对话把模糊目标打磨成结构化的 ralph-loop 命令background / setup / tasks / testing 四段式并结合仓库中的探索文档与核心源码深入解析该模式在 Mastra Agent Network 中的工程化落地即把完成度判定统一建模为返回 0/1 的 Completion Scorer让 Agent 在外部校验测试通过、构建成功的驱动下自主迭代直到任务真正完成。读完本文你将掌握 ralph 命令的构建方法、交互式规划的提问策略以及如何用createScorercompletion配置写出可运行的自主循环代码。Ralph Loop让 Agent 反复失败直到成功Ralph Wiggum Loop 是仓库 explorations/ralph-wiggum-loop-integration.md 中定义的自主 Agent 执行模式AI Agent 持续、迭代地工作直到满足明确的完成标准才停止。其核心哲学是让 Agent 反复失败直到它成功Let the agent fail repeatedly until it succeeds。这一模式的关键特征包括持久迭代Persistent IterationAgent 持续循环执行而不是一次生成就结束上下文保留Context Preservation每一轮迭代都能看到之前运行的结果失败信息成为下一轮的输入明确的完成标准Completion Criteria有清晰的成败度量例如测试通过构建成功安全控制Safety Controls最大迭代次数、超时限制防止无限循环失败即数据Failure as Data每一次失败尝试都为下一次迭代提供修正依据。在 Mastra 中ralph-plan技能.claude/skills/ralph-plan/SKILL.md正是为这个循环生成命令的规划助手它不直接执行任务而是通过与用户的多轮协作对话产出一个聚焦、可执行、分节清晰的 ralph-loop 命令。Ralph 命令的四段式结构一份完整的 ralph 命令由四个明确的 XML 小节构成外加一个完成承诺标记background Context about the task, the users 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 promiseCOMPLETE/promise when all tasks are done.四个小节的分工如下小节作用关键内容background提供任务上下文任务背景、用户的专业水平、总体目标setup准备工作清单编号步骤激活相关技能、探索当前状态、需要做的研究tasks具体可执行任务编号列表具体且可验证testing完成验证步骤构建命令、运行/测试方式、校验步骤promiseCOMPLETE/promise完成承诺所有任务完成后输出交互式规划五步流程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帮助用户建立background小节Agent 应该扮演什么专家/角色persona用一句话概括核心目标是什么Step 3规划 Setup 步骤Plan Setup Steps确定setup小节的内容需要哪些技能或工具需要先做什么探索/研究需要什么环境准备Step 4拆解任务Break Down Tasks与用户一起把目标拆成具体的、编号的任务确保任务具体且可验证verifiable按依赖关系排序先做依赖项在合适的地方补充实现细节。Step 5定义测试Define Testing确立testing小节如何构建/编译改动如何运行并验证成果成功是什么样子九条规划准则从模糊描述到可执行命令ralph-plan技能明确给出了九条准则它们是保证命令质量的关键保持追问Be Inquisitive主动深挖细节就实现细节、边界情况、假设连续追问。不要接受模糊描述——深入下去直到清晰为止。识别缺口Identify Gaps主动指出任何缺失、含糊、或日后可能引发问题的点。技能文档给出了三个典型追问范例你提到了创建 endpoint但还没有指定请求/响应格式——它应该长什么样这个任务依赖对 X 工作原理的理解但目前没有对应的研究步骤——我们要加一个吗如果处理器抛出错误会怎样UI 应该处理这种情况吗研究代码库Research the Codebase不要只问用户——主动探索代码库填补知识空白。例如用户说添加一个像 tools tab 那样的 tab就去搜索并阅读 tools 的实现理解其中的模式、文件结构和约定。研究结果用于在任务中给出具体的文件路径和函数名、找出可遵循的既有模式、发现需要一并修改的依赖代码、给出具体的实现细节而非模糊指令。保持迭代Be Iterative不要立即产出完整命令。多提问、讨论选项、逐步细化。具体化Be Specific模糊的任务会造成混乱。技能文档给出了正反示例差Improve the UI改进 UI好Create a /processors endpoint that lists processors, mimicking the /tools endpoint创建一个列出处理器的/processorsendpoint仿照/toolsendpoint包含上下文Include ContextSetup 步骤应包含研究/探索环节以理解既有代码。参考既有模式Reference Existing Patterns尽量指向已有的相似实现供 Agent 遵循。考虑依赖Consider Dependencies任务排序要让依赖项先完成。控制范围Keep Scope Focused一份 ralph 命令应有清晰、可达成的范围。若范围过大建议拆成多条 ralph 命令。示例对话流把想法收敛成计划技能文档给出了一个典型的多轮对话节奏规划助手始终遵循先问清、再起草、后确认的循环用户I want to add a new feature to the playground我想给 playground 加一个新功能助手让我们来规划一下。你能告诉我更多信息吗你要加什么功能它影响 playground 的哪一部分有没有类似的功能可以参考其实现模式用户[提供细节]助手明白了。让我先起草 background 小节background [Draft background based on discussion] /background这个描述准确抓住了目标吗需要调整哪里吗[然后逐个小节继续迭代……]注意对话的节奏先问开放性问题收集信息每起草一个小节就立即请求用户确认得到反馈后再进入下一个小节直到四个小节全部收敛。输出格式与关键注意事项当计划最终确定后把完整的 ralph 命令放进一个代码块方便用户直接复制background ... /background setup ... /setup tasks ... /tasks testing ... /testing Output promiseCOMPLETE/promise when all tasks are done.重要输出 ralph 命令时要避免使用双引号和反引号字符因为它们会在命令被复制执行时干扰格式化。改用单引号或者改写措辞彻底避免引号。落地一Completion 就是返回 0/1 的 Scorerralph-plan负责规划而规划出的测试通过才算完成这一逻辑在 Mastra 中由完成度评分器Completion Scorer落地。仓库探索文档 explorations/ralph-wiggum-loop-integration.md 给出了一个关键洞察Completion checks are justMastraScorersthat return 0 (not complete) or 1 (complete).这统一了两件事Evals离线评测与Completion运行时循环控制。同一个原语不同上下文。这个设计在核心源码中已经实现。查看 packages/core/src/loop/network/validation.ts 顶部的注释/** * Network Completion Scorers * * Completion checks are just MastraScorers that return 0 (failed) or 1 (passed). * This unifies completion checking with the evaluation system. */CompletionConfig 完整配置packages/core/src/loop/network/validation.ts 中定义了CompletionConfig各字段与默认值如下字段类型默认值说明scorersMastraScorer[]无使用默认 LLM 检查用于判定任务是否完成的评分器每个返回 0未完成或 1完成strategyall \| anyallall表示所有评分器都必须通过any表示至少一个通过即可timeoutnumber60000010 分钟所有评分器的总超时时间毫秒parallelbooleantrue是否并行运行评分器onComplete(result: CompletionRunResult) void—评分完成后回调suppressFeedbackbooleanfalse为true时#### Completion Check Results反馈消息不会写入 memory避免污染后续迭代的对话历史从源码结构看runCompletionScorersvalidation.ts#L238-L306是执行核心并行模式下用Promise.race对全部评分器与超时做竞争超时后通过Promise.allSettled收集已完成的评分结果并置timedOut: true串行模式下则在all策略遇到失败、any策略遇到成功时提前短路。最终complete的判定为all时要求结果数与评分器数相等且全部通过any时只要有一个通过。CompletionContext评分器能看到的网络状态评分器运行时通过run.input拿到完整的CompletionContextvalidation.ts#L46-L74包含iteration当前迭代号从 1 开始maxIterations允许的最大迭代数messages对话线程中的全部消息originalTask发起本次网络运行的原始任务selectedPrimitive本轮选中的原语{ id, type: agent | workflow | tool | none }primitivePrompt/primitiveResult发给原语的输入及其执行结果networkName、runId、threadId、resourceIdcustomContext来自请求的自定义上下文落地二在 Agent 上配置完成度评分器规划阶段的测试通过才算完成可以在 Agent 定义时直接声明为默认网络配置。以下代码继承自探索文档 ralph-wiggum-loop-integration.md 的 Quick Start并结合源码类型补全了上下文import { Agent } from mastra/core/agent; import { Memory } from mastra/memory; import { createScorer } from mastra/core/evals; import { execSync } from child_process; // 创建完成度评分器跑测试全过返回 1否则返回 0 const testsScorer createScorer({ id: tests, description: Run unit tests to verify code works, }).generateScore(async ({ run }) { try { execSync(npm test, { stdio: pipe }); return 1; // Tests passed } catch { return 0; // Tests failed } }); const agent new Agent({ id: code-migrator, instructions: You help migrate code between frameworks., model: openai(gpt-4o), memory: new Memory(), agents: { coder: codingAgent }, // 默认网络选项循环最多 20 轮全部评分器通过才算完成 defaultNetworkOptions: { maxSteps: 20, completion: { scorers: [testsScorer], strategy: all, }, }, }); // 运行网络 —— 使用默认完成度评分器 const result await agent.network(Migrate all tests from Jest to Vitest); for await (const chunk of result.fullStream) { if (chunk.type network-validation-end) { console.log(Completion: ${chunk.payload.passed ? ✅ : ❌}); } }completion配置也可以按次调用时传入覆盖 Agent 默认值packages/core/src/agent/agent.types.ts#L449-L473 中NetworkOptions.completion的文档即注明Uses MastraScorers that return 0 (not complete) or 1 (complete). By default, the LLM evaluates completion.。落地三三种完成度评分器写法1. 代码型评分器访问完整网络状态评分器通过run对象拿到run.input即CompletionContext、run.output被评估的原语结果、run.runId与run.requestContext。下面示例来自探索文档展示如何读取迭代号、原始任务、选中原语和消息历史import { createScorer } from mastra/core/evals; // 简单评分器跑测试 const testsScorer createScorer({ id: tests, description: Run unit tests, }).generateScore(async () { try { execSync(npm test, { stdio: pipe }); return 1; } catch { return 0; } }); // 上下文感知评分器读取完整网络状态 const progressScorer createScorer({ id: progress, description: Check progress, }).generateScore(async ({ run }) { // run.input 即 CompletionContext const ctx run.input; console.log(Iteration: ${ctx.iteration}); console.log(Task: ${ctx.originalTask}); console.log(Primitive: ${ctx.selectedPrimitive.id}); console.log(Result: ${run.output}); // 等价于 ctx.primitiveResult // 检查消息历史中是否已出现代码块 const hasCodeOutput ctx.messages.some(m m.content?.includes?.()); return hasCodeOutput ? 1 : 0; }); // 使用自定义请求上下文requestContext const envScorer createScorer({ id: env-check, description: Environment-aware check, }).generateScore(async ({ run }) { const isProd run.requestContext?.env production; // 生产环境执行更严格的检查 return isProd ? runStrictChecks() : 1; });2. LLM 型评分器LLM 当裁判当需要在代码校验之外叠加 LLM 评估时可以在createScorer配置中传入judgeLLM-as-judge。这在源码 packages/core/src/evals/base.ts 的ScorerJudgeConfig中有完整类型定义judge可配置model、instructions还可选配tools让内部 judge Agent 在打分前调用只读工具独立核验、memory、maxSteps、inputProcessors/outputProcessors等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. ; }, }); // LLM 评分器与代码评分器组合使用 completion: { scorers: [taskCompleteScorer, testsScorer], }3. 默认 LLM 完成度检查未配置 scorers 时当不配置任何scorers时网络循环会使用内置的默认 LLM 检查。源码 validation.ts#L395-L529 中的runDefaultCompletionCheck用结构化输出约束模型返回{ isComplete, completionReason, finalResult }并通过scorerId: default-completion标记。它只回答是否完成不负责生成最终结果——最终结果来自原语的输出。落地四完成度检查的运行机制完成度检查只回答一个问题这算完成了吗Is this done?它不生成最终结果。最终结果始终是原语的输出。探索文档中的对照表配置实际运行内容无completion.scorers默认 LLM 检查配置了completion.scorers: [...]使用你自己的评分器所有检查默认 LLM 或自定义评分器都返回统一结构{ complete: boolean, // 任务完成了吗 completionReason: string, // 为什么 }从源码看CompletionRunResultvalidation.ts#L161-L172还额外携带scorers每个评分器的得分、reason、耗时、totalDuration与timedOut标记。评分器自身抛异常时会被捕获并记为score: 0、errored: truevalidation.ts#L96-L102这与合法地评 0 分可区分便于消费方如 goal step 暂停目标据此做出不同反应。整个网络循环的流程如下┌─────────────────────────────────────────────────────────────────┐ │ Agent Network Loop │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. Routing Agent 选择原语agent/workflow/tool │ │ ↓ │ │ 2. 执行选中的原语 │ │ ↓ │ │ 3. 运行完成度评分器 │ │ 未配置时使用默认 LLM 评分器 │ │ ↓ │ │ ┌───────┴───────┐ │ │ Score0 Score1 │ │ (未完成) (完成) │ │ │ │ │ │ ▼ ▼ │ │ 4. 注入反馈 5. 完成 ✅ │ │ │ │ │ └──────────► 回到第 1 步 │ │ │ └─────────────────────────────────────────────────────────────────┘从 packages/core/src/loop/network/index.ts 的实现看循环由 routing step 与各原语执行 step 组成routing step 让路由 Agent 输出{ primitiveId, primitiveType, prompt, selectionReason }当primitiveId none时视为完成完成度判定则统一交由 validation 模块的评分器处理。评分结果会通过formatCompletionFeedbackvalidation.ts#L335-L365格式化为#### Completion Check Results反馈消息注入下一轮迭代。落地五流式事件观测循环进度网络循环把每个阶段以流式 chunk 暴露给调用方。NetworkChunkTypepackages/core/src/stream/types.ts#L831-L858中与循环控制相关的事件包括routing-agent-start、routing-agent-text-delta、agent-execution-start/end、workflow-execution-start/end、tool-execution-start/end以及专门用于完成度评分的network-validation-start/network-validation-end和结构化输出的network-object/network-object-result。探索文档给出了消费这些事件、实时观测循环的示例for await (const chunk of result.fullStream) { switch (chunk.type) { case network-validation-start: console.log(Running ${chunk.payload.checksCount} scorers...); break; case network-validation-end: console.log(Complete: ${chunk.payload.passed ? ✅ : ❌}); for (const scorer of chunk.payload.results) { console.log( ${scorer.scorerName}: ${scorer.score}); } break; case routing-agent-start: console.log(Iteration ${chunk.payload.inputData.iteration}); break; } }落地六从规划到代码 —— 自主循环的参考实现仓库 explorations/ralph-wiggum-loop-prototype.ts 提供了一份更底层的参考实现展示了不用 Agent Network、直接用单 Agent 循环实现 Ralph Wiggum 模式的思路注意该文件为仓库中的探索原型标注了设计意图非核心包正式 API。其核心executeAutonomousLoop(agent, config)的流程是按maxIterations循环调用agent.generate(contextualPrompt)每轮把前contextWindow默认 5 次迭代的结果成功/失败、输出摘要、错误信息拼进上下文让 Agent 从历史失败中学习通过completion.check()如testsPassing(npm test)、buildSucceeds(npm run build)、lintClean(npm run lint)做外部校验支持maxTokens预算、iterationDelay间隔、onIterationStart/onIteration回调成功或到达maxIterations时返回AutonomousLoopResult含迭代明细、总 token、总耗时。探索文档 agent-network-vs-ralph-wiggum.md 对两种模式做了对照分析Agent Network 的优势是路由 多原语编排弱点是完成判定依赖 LLM 自评可能幻觉Ralph Wiggum 的优势是程序化外部验证弱点是单 Agent、没有路由智能。文档的结论是二者互补并给出了统一自主循环的桥接设想verify/override/llm-only三种校验模式。而在 explorations/network-validation-bridge.ts 中这一设想被实现为可运行的桥接参考networkWithValidation每轮执行网络后运行校验检查按mode决定是否采纳 LLM 的完成判断失败时把校验错误作为[VALIDATION FEEDBACK FROM PREVIOUS ITERATION]消息注入下一轮同时提供createValidationTools()把runTests/runBuild/runLint/checkTypes/runCommand封装成路由 Agent 可直接调用的工具。完整用法模式汇总探索文档归纳了四种典型用法1. 默认仅 LLM 完成度检查// 不配 scorers —— 使用内置 LLM 评估 await agent.network(Build a landing page);2. 仅代码评分器完全替代 LLM// 评分器完全替代默认 LLM 检查 await agent.network(Migrate to Vitest, { completion: { scorers: [testsScorer, buildScorer], }, });3. 混合评分器await agent.network(Build API, { completion: { scorers: [ testsScorer, // 代码型 qualityScorer, // LLM 型 apiScorer, // 代码型 ], strategy: all, }, });4. 任一通过策略await agent.network(Fix the bug, { completion: { scorers: [testsScorer, manualApprovalScorer], strategy: any, // 测试通过 或 人工审批 任一即可 }, });使用 Scorer 的收益综合探索文档与源码实现把完成度判定统一为 Scorer 带来五点收益统一原语Unified PrimitivesEvals 与 completion 使用同一个createScorerAPI见 packages/core/src/evals/base.ts#L1869-L1897 的createScorer定义与MastraScorer类可复用Reusable评测用的 scorer 可以直接当完成度检查用可组合Composable代码型与 LLM 型 scorer 可自由混合可观测ObservableScorerResult携带score、passed、reason、duration配合network-validation-start/end流式事件可全程观测可测试Testable每个 scorer 都可以独立测试。结语从.claude/skills/ralph-plan/SKILL.md的交互式规划到explorations目录中的模式设计文档再到packages/core/src/loop/network/validation.ts中的正式实现Mastra 中形成了一条完整的规划 → 编码 → 验证链路先用ralph-plan的追问式对话把模糊目标收敛成带background / setup / tasks / testing的结构化命令再把命令中的完成标准翻译为返回 0/1 的 Completion Scorer最后让 Agent Network 在外部校验的驱动下自主迭代。这种让 Agent 反复失败直到成功的模式特别适合测试可自动验证的机械性改造任务——而完成与否的判定始终掌握在确定性的代码手里而不是 LLM 的自我感觉里。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考