跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt

Use this file to discover all available pages before exploring further.

Ralph Loop 会在现有 agent middleware 管线内运行一个验证优先的目标循环。它会让智能体在有上限的续跑轮次中持续工作，直到模型表达收尾意图，并且可信验证证据也确认通过。 中间件 provider 名称是 ralph-loop。

​
核心思路

Ralph Loop 不再只是“重试直到出现 <promise>DONE</promise>”。完成标记现在只表示模型的收尾意图，不代表任务已经被证明完成。 默认情况下，只有同时满足下面两个条件，Ralph Loop 才接受完成：
  • 最新 AI 回答包含 <promise>DONE</promise>。
  • 最新可信验证证据已经通过。
如果模型声明完成但没有通过验证证据，Ralph Loop 会拒绝这次完成，生成一个紧凑的续跑提示，清空当前 channel 的消息历史，并把运行重新跳回模型。

​
Goal Slash Command

当当前 agent 连接了 Ralph Loop 时，中间件会暴露一个 runtime slash command： 
/goal <objective>
这个命令由 RalphLoopMiddleware.meta.slashCommands 声明。下发给 composer 的 runtime command 类型是 insert_invocation，所以前端只插入 /goal ...，不会在客户端展开完整 prompt 模板。 默认 /goal 模板要求智能体遵循： 
Plan -> Act -> Verify -> Reflect -> Retry
模板还要求智能体在最终收尾前使用最强适用的验证器。如果目标涉及 UI 屏幕或视觉一致性，它会明确要求使用 Playwright Interactive 检查并比较结果。

​
完成标记

Ralph Loop 仍然使用这个标记： 
<promise>DONE</promise>
该标记表示“模型认为目标已经可以收尾”。它不会绕过验证。完成被接受后，中间件会从用户可见回答中移除该标记。

​
验证证据

Ralph Loop 会从配置的 verifier tools 中收集最近的 ToolMessage。默认可信验证工具列表是： 
["sandbox_shell"]
中间件会把验证输出匹配回发起它的 AI tool call，并记录：
  • 工具名
  • tool call id
  • 命令内容，如果存在
  • 状态，pass 或 fail
  • 输出内容
  • 观察时间
当工具输出表示非零退出码、超时或工具错误时，验证证据会被记录为失败。否则会被记录为通过。 Ralph Loop 不会在 middleware hook 中直接执行验证工具。模型必须通过正常 tool pipeline 调用工具，因此 streaming、HITL、工具调用限制、工具重试中间件等机制仍然生效。

​
工作方式

钩子行为
beforeAgent启动或恢复 Ralph Loop 状态。除非用户开始了新目标，或之前运行已经进入终态，否则 active 状态会跨 turn 保留。
wrapModelCall向系统消息追加验证优先的完成规则。重试时发送紧凑续跑提示，而不是完整历史消息。
afterModel提取验证证据，检查完成标记，用验证状态门控完成；然后决定接受完成、继续循环，或在预算耗尽时停止。
续跑提示会携带：
  • 原始目标
  • 当前迭代次数
  • 紧凑运行摘要
  • 上一次验证证据
  • 续跑原因
  • 下一步期望行为
它会要求智能体继续遵循 Plan -> Act -> Verify -> Reflect -> Retry，修复失败验证，在缺少验证证据时先运行验证器，并且只有在验证契约满足后才用完成标记收尾。 如果原始用户消息包含结构化内容片段，Ralph Loop 会把这些片段保留在续跑提示之后。

​
配置项

字段类型默认值说明
maxIterationsnumber20最大自动验证优先续跑轮次。
requireVerifierbooleantrue接受完成标记前，是否要求可信验证证据通过。
verifierToolNamesstring[]["sandbox_shell"]这些工具名对应的 ToolMessage 会被视为可信验证证据。
verifierInstructionsstring""关于智能体应如何验证目标的附加说明。
maxRuntimeSummaryCharsnumber4000续跑提示中携带的紧凑运行摘要最大长度。
示例： 
{
  "maxIterations": 8,
  "requireVerifier": true,
  "verifierToolNames": ["sandbox_shell"],
  "verifierInstructions": "最终收尾前运行相关测试命令。涉及 UI 一致性时，使用 Playwright Interactive 检查变更后的屏幕。",
  "maxRuntimeSummaryChars": 3000
}

​
运行时状态

Ralph Loop 会保存以下状态字段：
字段说明
ralphLoopIteration当前续跑迭代次数。
ralphLoopOriginalHumanContent原始用户消息内容或结构化消息片段。
ralphLoopOriginalTaskText从 runtime human input 中提取到的原始纯文本任务。
ralphLoopStatus当前运行状态：active、completed、blocked 或 budget_exhausted。
ralphLoopRunId当前 Ralph Loop 运行标识。
ralphLoopRuntimeSummary跨清理重试 turn 携带的紧凑摘要。
ralphLoopLastVerifier最近一次可信验证证据。
ralphLoopStopReason循环停止或继续的原因。
终态包括 completed、blocked 和 budget_exhausted。当用户开始新目标，或上一次运行已经是终态时，会启动新的运行。

​
预算耗尽

当达到 maxIterations，但验证优先完成契约仍未满足时，Ralph Loop 会停止重试，并在最新回答后追加包含验证信息的提示： 
Ralph Loop stopped after reaching <maxIterations> automatic retries before the verifier-first completion contract was satisfied.

Last verifier evidence:
...
运行状态会变为 budget_exhausted。

​
适用场景

当你希望智能体持续工作，直到有外部证据证明目标完成时，可以使用 Ralph Loop：
  • 需要通过测试的迁移和重构
  • 需要 Playwright Interactive 检查的 UI 视觉一致性任务
  • 模型容易提前停止的长实现任务
  • 有明确验证命令的研究或分析任务
  • 比起携带杂乱历史，更适合使用干净续跑提示的任务
不要把 Ralph Loop 当作完整任务 runtime 使用。它没有提供带暂停、恢复、清理、报告或独立 goal runtime 状态的 /goal 产品界面；它仍然运行在现有 middleware hook 形态内。

​
排障建议

  • 最终回答里看不到 <promise>DONE</promise>：这是正常现象。Ralph Loop 接受完成后会移除该标记。
  • 模型说已经完成但仍继续循环：完成标记没有配套通过的可信验证证据。
  • 验证输出失败：Ralph Loop 会带着失败上下文继续，让智能体修复根因并再次验证。
  • 没有检测到验证器：确认智能体可以访问 verifierToolNames 中列出的工具，或为你的验证工具配置对应名称。
  • 智能体带预算耗尽提示停止：提高 maxIterations，明确目标，或查看最后一次验证证据判断阻塞点。