ralph-loop

name	ralph-loop
description	双 Agent 全面审查修复框架。Antigravity + Codex MCP 独立审查 → 交叉验证 → 协作修复。内置 Codex session 监控、权限管控、双向状态追踪、清理策略。触发词："Ralph Loop"、"raphaloop"、"全面审查"、"零容错审查"、"/ralph-loop"。适用场景：代码审查、数据质量检查、发布前终验、跨 Agent 协作修复。

Ralph Loop — 双 Agent 全面审查修复框架

三阶段、双 Agent 协作的代码/数据全面审查修复流程。核心思路来自 claude-review-loop，为 Antigravity + Codex MCP 环境深度定制。

执行流程

1. 用户触发 → Antigravity 创建 task.md + implementation_plan.md
2. 确认权限配置（sandbox / MCP / 联网 / Skills）
3. Phase A: Antigravity 独立审查（只读）
4. Phase B: Codex 独立审查（只读，codex-monitor 监控）
5. Phase C: 合并 → 辩论 → 按优先级修复 → 交叉验证
6. 汇报：向用户提交完整报告 + 清理建议
7. 用户决策 → 执行清理 → 推送 → 更新 walkthrough.md

---

权限规范

[!CAUTION] 每个 Phase 启动前必须确认权限配置。不得擅自提升权限等级。

配置项	Phase A（Antigravity）	Phase B（Codex）	Phase C（协作修复）
sandbox	N/A（Antigravity 自身）	read-only	workspace-write（仅修复阶段）
approval-policy	N/A	never	never
文件写入	❌ 只读	❌ 只读	✅ 仅修复文件
联网搜索	按需（查文档/API）	按需（查文档/API）	按需
MCP 白名单	sequential-thinking、context7	不限（Codex 内部管理）	sequential-thinking、context7、codex
Skills 访问	仅 ralph-loop 自身	无（独立审查）	ralph-loop + codex-monitor
commit/push	❌ 禁止	❌ 禁止	✅ 需逐次确认

Codex 子 Agent 权限：继承父 session 的 sandbox 级别。Phase B 子 Agent 也必须是 read-only。

---

Phase A：Antigravity 独立审查

• 只读审查，不改代码
• 按审查模块 M1-M7 逐项检查（见 review-modules.md）
• 每步严格遵循五步思维标准（不得省略）
• 输出问题清单到 /tmp/ralph_loop_antigravity_issues.json
• 审查完毕后记录：耗时、审查模块数、发现问题数

Phase B：Codex 独立审查

通过 Codex MCP 启动独立审查 session，只读不改：

mcp_codex_codex({
  model: "gpt-5.3-codex",
  config: { "model_reasoning_effort": "xhigh" },
  sandbox: "read-only",
  approval-policy: "never",
  cwd: "<项目路径>",
  prompt: "<审查任务描述，包含 M1-M7 模块要求，明确禁止修改任何文件>"
})

输出问题清单到 /tmp/ralph_loop_codex_issues.json。

启动后立即进入双向监控（见下方「双向监控机制」）。

Phase C：协作辩论 + 统一修复

1. 合并两份问题清单
2. 差异项辩论（一方发现、另一方没发现的问题需仲裁）
3. 按优先级修复：Critical → Warning → Info
4. 分工明确：Antigravity 负责修改代码 → commit → Codex 负责验证修复结果（Codex 不改代码）
5. 交叉验证修复结果
6. 进入汇报流程（见「汇报机制」）

---

五步思维标准

[!IMPORTANT] 每个审查步骤必须严格遵循以下五步，不得省略任何一步。

1. Sequential Thinking — 分步骤推理（优先使用 sequential-thinking MCP；若不可用，手工输出 1..N 步推理结构）
2. Critical Thinking — 质疑假设，寻找反例
3. First Principles — 从根本原理出发，不盲从惯例
4. Ultra Thinking — 考虑边界条件和长尾场景
5. Reflection — 反问"是否遗漏了什么"

---

监控与验证机制

[!NOTE] 架构限制：Codex 作为 MCP server 被 Antigravity 调用，是单向关系。Codex 无法主动回调或监控 Antigravity 的状态。因此监控职责由 Antigravity 全权承担，Codex 仅在被调用时执行被动验证。

Antigravity 主导监控（贯穿全流程）

Antigravity 是整个 Ralph Loop 的调度中心，负责：

1. Phase B 监控 Codex：运行 codex-monitor 脚本

   python3 <codex-monitor-skill-dir>/scripts/codex-monitor.py --watch
   

   <codex-monitor-skill-dir> 的定位方法：查找 .agent/skills/codex-monitor/ 目录

2. 状态速查：

   图标	含义	Antigravity 操作
   ✅	完成	读取输出 → 继续 Phase C
   🔄	运行中	等待，每 2-5 分钟检查一次
   ⏱️	超时（>10min）	记录失败原因 → 修正 prompt → 手动重新启动 Codex session
   ⚠️	可能停滞	再等 2 分钟，仍无进展则按超时处理
   ❌	出错	读取错误信息 → 修正 prompt → 手动重试
   📭	空/未启动	检查 MCP 连接 → 重新调用

3. 追踪内容：

   • Session 数量（主 session + 子 Agent）
   • 每个 session 的完成状态
   • 工具调用情况和 MCP/Skills 访问记录
   • 输出物位置（/tmp/ralph_loop_codex_issues.json）
   • Rate Limit 百分比

4. 异常恢复（全部由 Antigravity 手动执行）：

   • 超时 → 修正 prompt 后重新调用 mcp_codex_codex()
   • 错误 → 读取错误信息，判断原因后重试
   • Rate Limit → 等待冷却后重试或切换模型
   • 子 Agent 部分失败 → 针对未完成部分重新启动

Codex 被动验证（仅在 Phase C 被调用时执行）

Codex 无法主动监控 Antigravity，但在 Phase C 被调用进行验证时，Antigravity 会通过 prompt 指示 Codex 检查：

1. Antigravity 的修复是否引入新问题
2. git diff 是否只含预期变更
3. 构建/测试是否通过
4. 将验证结果输出到 /tmp/ralph_loop_codex_verify.json，由 Antigravity 读取并处理

Codex 不具备主动轮询或回调 Antigravity 的能力。所有信息流方向为：Antigravity → 调用 Codex → 读取 Codex 输出。

定时检查规则

• Phase B 期间：Antigravity 每 2-5 分钟 运行一次 codex-monitor.py --last 3
• Phase C 期间：每次 commit 后 Antigravity 主动调用 Codex 执行验证
• 任何异常立即记录到问题清单

---

Session 追踪

Codex Session 文件位置

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl

追踪清单

每次启动 Codex session 后记录：

追踪项	说明
Session ID	前 8 位即可标识
启动时间	从 codex-monitor 输出获取
子 Agent 数量	检查 parent-child 关系树
完成状态	✅/🔄/❌/⏱️
输出物位置	/tmp/ralph_loop_codex_issues.json 或其他指定路径
Token 使用量	从 codex-monitor 输出获取
Rate Limit	百分比

使用 codex-monitor 的正确方式

# 定位脚本（首次使用时确认路径）
ls -la <codex-monitor-skill-dir>/scripts/codex-monitor.py

# 查看今天所有 session
python3 <codex-monitor-skill-dir>/scripts/codex-monitor.py today

# 实时监控（每 10s 刷新）
python3 <codex-monitor-skill-dir>/scripts/codex-monitor.py --watch

# 只看最近 N 个 session
python3 <codex-monitor-skill-dir>/scripts/codex-monitor.py --last 3

<codex-monitor-skill-dir> 查找方法：find ~/.agent -path "*/codex-monitor/scripts/codex-monitor.py" -o -path "*/.agent/skills/codex-monitor/scripts/codex-monitor.py" 2>/dev/null | head -1

---

协调机制（防冲突）

1. Phase A 和 B 只读，不修改文件
2. Phase C 修复时 Antigravity 修改 → commit → Codex 验证（Codex 不改代码）
3. 每次改代码前先 git pull --rebase
4. 如果有 Lovable/其他平台的并发修改，每个 Phase 开始前 git pull
5. Codex 子 Agent 之间不得同时修改同一文件

---

汇报机制

[!IMPORTANT] 任务完成后必须向用户提交完整汇报，等待用户确认后才执行后续操作。

汇报内容

1. 修复总结

   • Phase A 发现数 / Phase B 发现数 / 合并后总数
   • Critical / Warning / Info 各几项
   • 已修复数 / 跳过数（附理由）

2. 变更文件清单

   • 每个被修改的文件 + 变更摘要
   • git diff --stat 输出

3. 中间产物清单（见「清理策略」）

4. Session 追踪报告

   • Codex session 总数、各状态、Token 消耗

5. 建议后续动作

   • 推荐的推送策略
   • 需用户确认的事项

---

清理策略

[!CAUTION] 硬性规则（不可违反）：

1. 禁止自动删除 — 在用户明确逐项批准之前，不得删除任何文件、session、对话或临时数据
2. 禁止静默清理 — 不得在汇报中省略任何中间产物，不得以"已自动清理"的方式跳过用户决策
3. 禁止批量删除 — 即使用户说"全部删除"，也必须先列出完整清单让用户确认

违反以上任何一条都是不可接受的严重错误。宁可多问一次，不可擅自删除。

清理流程（严格按顺序执行）

Step 1: 扫描 → 生成中间产物清单（不删除任何东西）
Step 2: 分类标注 → 给每个产物标注建议（🟢/🟡/🔴）
Step 3: 提交给用户 → 使用 notify_user 展示完整清单
Step 4: 等待用户逐项批准 → 用户未回复则不操作
Step 5: 仅删除用户明确批准的项目 → 每删一个确认一个

分类标签

标签	含义	说明
🟢 可安全删除	Ralph Loop 过程中产生的临时中间文件，删除不影响任何功能	例：/tmp 下的问题清单 JSON
🟡 建议保留	有追溯/参考价值，删除后无法恢复	例：Codex session 日志、审查记录
🔴 需用户确认	无法判断是否有价值，必须由用户决定	例：来源不明的相关文件

中间产物详解

以下是 Ralph Loop 执行过程中会产生的所有中间产物：

1. Antigravity 问题清单

属性	说明
文件	/tmp/ralph_loop_antigravity_issues.json
来源	Phase A 中 Antigravity 独立审查后输出
内容	JSON 数组，每项包含 module、severity、file、line、description、suggestion
用途	Phase C 中与 Codex 问题清单合并、辩论、修复
删除后果	无法追溯 Phase A 的审查细节；如果 Phase C 已完成则无影响
默认建议	🟢 Phase C 完成后可安全删除

2. Codex 问题清单

属性	说明
文件	/tmp/ralph_loop_codex_issues.json
来源	Phase B 中 Codex 通过 MCP 独立审查后输出
内容	同上格式，由 Codex 生成
用途	Phase C 中与 Antigravity 清单合并
删除后果	同上
默认建议	🟢 Phase C 完成后可安全删除

3. Codex 验证报告

属性	说明
文件	/tmp/ralph_loop_codex_verify.json
来源	Phase C 中 Codex 被调用执行验证时输出
内容	修复验证结果：通过/失败 + 具体问题
用途	确认修复是否正确
删除后果	无法追溯验证细节
默认建议	🟢 Phase C 完成后可安全删除

4. Codex Session 日志

属性	说明
文件	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
来源	每次调用 Codex MCP 时自动生成
内容	完整的 Codex 对话记录：工具调用、Token 用量、Agent 消息、错误信息
用途	事后追溯 Codex 做了什么、为什么失败、消耗了多少资源
删除后果	不可恢复 — 丢失 Codex 的完整工作记录，无法事后排查问题
默认建议	🟡 建议保留至少 7 天

5. Antigravity Brain 文件

属性	说明
文件	brain/<conversation-id>/task.md、implementation_plan.md、walkthrough.md
来源	Antigravity 在执行 Ralph Loop 时创建
内容	任务清单、实施计划、最终汇报
用途	记录整个审查过程的规划和结果
删除后果	丢失审查过程的完整记录
默认建议	🟡 建议保留

---

详细参考

以下参考资料按需加载，无需全部阅读：

• Codex 配置策略（模型选择、模式、调用模板、权限详解）：见 codex-integration.md
• 审查模块 M1-M7（详细说明 + 自定义 + 验收标准）：见 review-modules.md