名称: ralph-supervisor
描述: |
Ralph 循环模式 - Claude 监督，而 Codex (gpt-5.3-codex) 执行
实现工作。用于自治编码循环，每次迭代都有新上下文，
验证门，和 Git 支持的持久化。工具: ralph_init,
ralph_story, ralph_iterate, ralph_loop, ralph_status, ralph_cancel, ralph_review.
Ralph Supervisor 模式
Ralph 实现了一个自治编码循环，其中 Claude 充当监督者，Codex 执行实现工作。名称来自模式 openclaw-codex-ralph。
核心哲学
传统 AI 会话积累上下文和漂移。Ralph 使用：
- 每次迭代的新上下文 - 每个 Codex 会话从干净开始
- Git 支持的持久化 - 完成的工作保存在提交中
- 验证门 - 测试必须在进展前通过
- 进度传递 - 学习向前流动（最后 2000 字符）
架构
┌──────────────────────────────────────────────────────────┐
│ RALPH 架构 │
├──────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Claude │ 产生 │ Codex │ │
│ │ (监督者) │ ──────► │ (执行者) │ │
│ └─────────────┘ └─────────────┘ │
│ │ │ │
│ │ 计划/审查 │ 实现 │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ prd.json │ │ 代码 + │ │
│ │ (故事) │ │ 测试 │ │
│ └─────────────┘ └─────────────┘ │
│ │ │ │
│ │ │ 验证 │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │progress.txt │◄────────│ npm test │ │
│ │ (学习) │ 日志 │ 类型检查 │ │
│ └─────────────┘ └─────────────┘ │
│ │ │ │
│ │ │ 成功时 │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 群体智慧 │ │ Git 提交 │ │
│ │ (语义) │ │ (持久化) │ │
│ └─────────────┘ └─────────────┘ │
│ │
└──────────────────────────────────────────────────────────┘
迭代生命周期
1. 读取 PRD → 查找下一个待处理故事（按优先级）
2. 加载 progress.txt + AGENTS.md 作为上下文
3. 为 Codex 构建迭代提示
4. 生成 Codex (codex exec --full-auto)
5. 运行验证命令
6. 如果成功：
- 标记 story.status = "passed"
- 附加到 progress.txt
- Git 提交
7. 如果失败：
- 记录失败详情
- 保留故事重试
8. 重复直到所有故事通过或达到限制
故事结构
{
"id": "story-1234567890",
"title": "添加用户认证",
"description": "实现使用 JWT 的登录/注销...",
"priority": 1,
"status": "pending",
"validation_command": "npm test && npm run typecheck",
"acceptance_criteria": [
"JWT 令牌生成有效",
"刷新令牌流程已实现"
],
"attempts": 0,
"files_touched": [],
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
}
PRD 结构
{
"version": "1.0",
"project_name": "我的功能",
"description": "添加 OAuth 支持...",
"stories": [...],
"metadata": {
"created_at": "...",
"last_iteration": "...",
"total_iterations": 5,
"total_stories_completed": 3
}
}
监督者最佳实践
故事设计
- 粒度范围 - 每个故事应适合一个 Codex 上下文
- 清晰的验收标准 - 具体、可测试的要求
- 适当的验证 - 实际验证工作的测试
- 优先级排序 - 依赖项优先（数字越低优先级越高）
审查过程
┌─────────────────────────────────────────────────────────────┐
│ 审查清单 │
├─────────────────────────────────────────────────────────────┤
│ │
│ □ 测试通过 (validation_command 成功) │
│ □ 验收标准满足 │
│ □ 代码质量可接受 │
│ □ 未引入安全问题 │
│ □ 与现有代码集成正确 │
│ │
│ 如果全部为是 → ralph_review({ approve: true }) │
│ 如果任何为否 → ralph_review({ approve: false, │
│ feedback: "具体问题"}) │
│ │
└─────────────────────────────────────────────────────────────┘
知识持久化
完成项目后，存储学习内容：
hivemind_store({
information: "OAuth 实现：使用刷新令牌轮换模式，有效期为 7 天。关键点：必须在使用时使旧刷新令牌失效。",
tags: "oauth,auth,令牌,模式",
confidence: 0.9
})
配置
| 参数 |
默认值 |
描述 |
model |
gpt-5.3-codex |
使用的 Codex 模型 |
sandbox |
workspace-write |
沙箱模式 |
max_iterations |
20 |
循环限制 |
auto_commit |
true |
成功时提交 |
progress_context_limit |
2000 |
提示中的进度字符数 |
default_validation |
npm run typecheck; npm test |
后备验证 |
发出的事件
| 事件 |
时机 |
ralph:init |
项目初始化 |
ralph:story:added |
故事添加到 PRD |
ralph:iteration:start |
迭代开始 |
ralph:iteration:complete |
迭代结束 |
ralph:loop:start |
循环开始 |
ralph:loop:iteration |
每个循环迭代 |
ralph:loop:complete |
循环完成 |
ralph:loop:error |
循环错误 |
ralph:review:approved |
工作批准 |
ralph:review:rejected |
工作拒绝 |
错误处理
| 错误 |
恢复 |
| Codex 超时 |
使用更长超时重试 |
| 验证失败 |
在下一次迭代中修复 |
| 无故事剩余 |
全部完成，退出 |
| 最大迭代 |
报告剩余工作 |
比较：Ralph vs Swarm
| 方面 |
Ralph |
Swarm |
| 执行者 |
Codex |
Claude 工作者 |
| 并行性 |
顺序 |
并行 |
| 上下文 |
每次迭代新上下文 |
通过群体智慧共享 |
| 审查 |
监督者审查每个 |
协调者审查所有 |
| 最适合 |
复杂顺序任务 |
独立并行任务 |