教程概述
$ralph 是 oh-my-codex 的持久执行技能，通过自引用循环机制确保任务持续执行直到完成。
你将学到
- ✅ $ralph 的工作原理
- ✅ 自引用循环机制
- ✅ 与 $autopilot 的区别
- ✅ sparkshell 验证工具
- ✅ 复杂任务执行实战
触发方式标识
trigger_mode: "显式命令（$ralph）"
codex_native_alternative: "手动持续跟进"
superpowers_equivalent: "verification-completion 技能"
when_to_use_omx: "复杂、多步骤、易失败的任务"
when_to_skip_omx: "简单、一次性成功的任务"
为什么需要 $ralph？
普通执行的问题
flowchart TD
A[开始任务] --> B[执行步骤 1]
B --> C{成功?}
C -->|否| D[失败停止]
C -->|是| E[执行步骤 2]
E --> F{成功?}
F -->|否| D
F -->|是| G[完成]
style D fill:#ffcccc
持久执行的优势
flowchart TD
A[开始任务] --> B[$ralph 循环]
B --> C[执行步骤]
C --> D{成功?}
D -->|否| E[分析失败]
E --> F[修复问题]
F --> B
D -->|是| G[sparkshell 验证]
G --> H{验证通过?}
H -->|否| E
H -->|是| I[完成]
style B fill:#e1f5ff
style E fill:#fff3e0
$ralph 是什么？
$ralph 是 oh-my-codex 提供的持久执行工作流，核心特性：
- 自引用循环 - 失败后自动重试
- 错误分析 - 诊断失败原因
- 自动修复 - 尝试修复已知问题
- 验证集成 - 完成后自动验证
- 直到完成 - 不会中途放弃
与 $autopilot 的区别
| 特性 | $autopilot | $ralph |
|---|---|---|
| 目标 | 自动化常规任务 | 完成复杂任务 |
| 失败处理 | 停止并报告 | 自动重试 |
| 验证 | 可选 | 强制 |
| 使用场景 | 简单、确定性任务 | 复杂、探索性任务 |
| 人工介入 | 很少需要 | 关键决策点 |
工作循环
while not complete:
1. 分析当前状态
2. 规划下一步
3. 执行操作
4. 检查成功/失败
5. if 失败:
分析原因
修复问题
continue
6. if 成功:
sparkshell 验证
if 验证通过:
complete = true
else:
修复问题
continue
sparkshell 验证工具
sparkshell 是 $ralph 集成的验证工具，用于验证任务完成情况。
验证维度
| 维度 | 检查内容 | 工具/方法 |
|---|---|---|
| 功能 | 功能是否正常工作 | 自动化测试 |
| 质量 | 代码是否符合规范 | Linter |
| 安全 | 是否存在漏洞 | 安全扫描 |
| 性能 | 是否满足性能要求 | 性能测试 |
| 集成 | 是否破坏现有功能 | 回归测试 |
sparkshell 工作流程
flowchart TD
A[代码完成] --> B[sparkshell]
B --> C[运行测试套件]
C --> D{全部通过?}
D -->|否| E[生成错误报告]
E --> F[返回修复]
D -->|是| G[验证完成]
style B fill:#e3f2fd
style G fill:#e8f5e9
完整实战案例
场景：重构大型代码库
任务：将 10000+ 行的单体应用重构为模块化架构
步骤 1：启动 $ralph
$ralph "重构 monolith 应用为模块化架构"
$ralph 执行过程：
=== 迭代 1 ===
操作：识别模块边界
结果：成功
识别出 5 个核心模块
=== 迭代 2 ===
操作：提取用户模块
结果：失败 - 循环依赖
分析：User 和 Order 模块相互引用
修复：引入 UserRepository 接口
=== 迭代 3 ===
操作：重新提取用户模块
结果：成功
用户模块独立
=== 迭代 4 ===
操作：提取订单模块
结果：成功
...（持续迭代）...
=== 迭代 15 ===
操作：运行 sparkshell 验证
结果：验证失败
问题：3 个测试未通过
修复：更新测试用例
=== 迭代 16 ===
操作：重新验证
结果：全部通过
状态：完成
最终结果：
- 重构完成：5 个独立模块
- 测试通过：98/98
- 代码质量：A 级
- 耗时：自动完成，无需人工干预
使用模式
模式 1：简单持久执行
$ralph "实现一个功能"
适用：中等复杂度，可能遇到预料外问题
模式 2：带验证的执行
$ralph "重构代码并确保测试通过"
# sparkshell 自动运行测试
适用：需要质量保证的任务
模式 3：多阶段执行
# 阶段 1：规划
$plan "重构方案"
# 阶段 2：持久执行
$ralph "按 PRD 重构代码"
适用：大型、复杂任务
核心原则
DO（推荐做法）
✅ 给 $ralph 明确的任务目标
✅ 设定合理的完成标准
✅ 在关键节点检查进展
✅ 信任 sparkshell 验证
DON’T（避免做法）
❌ 任务目标过于模糊
❌ 频繁中断 $ralph 执行
❌ 忽视 sparkshell 的错误报告
❌ 对简单任务使用 $ralph
反模式与常见错误
反模式 1：目标不明确
❌ 错误：
$ralph "改进代码"
✅ 正确：
$ralph "将代码覆盖率提升到 80%"
反模式 2：忽视验证失败
❌ 错误：
sparkshell 报告问题后忽略
✅ 正确：
认真分析 sparkshell 报告
修复所有问题
反模式 3：无限循环
❌ 问题：
任务目标不可能完成
$ralph 无限重试
✅ 解决：
设定最大迭代次数
达到限制后人工介入
vs 原生 Codex
| 特性 | 原生 Codex | $ralph |
|---|---|---|
| 失败处理 | 停止 | 自动重试 |
| 错误分析 | 手动 | 自动 |
| 验证 | 可选 | 集成 sparkshell |
| 任务持续性 | 会话限制 | 持久直到完成 |
| 人工干预 | 频繁需要 | 关键节点 |
vs Superpowers
| 特性 | Superpowers | $ralph |
|---|---|---|
| 触发方式 | 自动触发 | 显式命令 |
| 失败处理 | 自动重试 | 自动重试+修复 |
| 验证 | verification 技能 | sparkshell |
| 使用场景 | 自动模式 | 显式控制 |
| 成本 | 自动管理 | 用户控制 |
快速参考
命令速查
# 基础持久执行
$ralph "任务描述"
# 带自定义验证
$ralph "任务描述 - 验证：测试通过率 100%"
# 限制迭代次数
$ralph "任务描述 --max-iterations 10"
# 与 $plan 组合
$plan "任务方案"
$ralph "执行上述方案"
使用场景速查表
| 场景 | 推荐命令 |
|---|---|
| 修复复杂 Bug | $ralph |
| 重构代码 | $ralph |
| 提高测试覆盖 | $ralph |
| 添加功能 | $plan 后 /prompts:executor |
| 简单修改 | /prompts:executor |
小结
$ralph 确保任务持续执行直到完成，是 oh-my-codex 的执行保障机制。
核心要点：
- 复杂任务用 $ralph
- 相信自引用循环机制
- 认真对待 sparkshell 验证
- 与 $plan 配合使用效果最佳
下一篇：教程 6：$team 多代理协调