name: ralph-mode
description: 通过迭代、背压门和完成标准实现自主开发循环。适用于需要多次迭代、测试验证和结构化进度跟踪的持续编码会话。支持 Next.js、Python、FastAPI 和 GPU 工作负载，采用适配 OpenClaw 的 Ralph Wiggum 方法。
Ralph 模式实现了适配 OpenClaw 的 Ralph Wiggum 技术：通过带有背压门、完成标准和结构化规划的持续迭代，实现自主任务完成。
在以下情况使用 Ralph 模式：
- 构建需要多次迭代和优化的功能
- 处理具有验收标准的复杂项目
- 需要自动化测试、代码检查或类型检查门控
- 希望系统性地跟踪多次迭代的进度
- 偏好自主循环而非手动逐条指导
阶段 1：需求定义
- 在 specs/ 中记录规范（每个关注点一个文件）
- 定义验收标准（可观察、可验证的结果）
- 创建包含优先级任务的实施计划
阶段 2：规划
- 差距分析：将规范与现有代码进行比较
- 生成包含优先级任务的 IMPLEMENTATION_PLAN.md
- 此阶段不进行实施
阶段 3：构建（迭代）
- 每次迭代从计划中选取一个任务
- 实施、验证、更新计划、提交
- 持续进行，直到所有任务完成或标准满足
通过验证自动拒绝不完整的工作：
程序化门控（始终使用）：
- 测试：[test command] - 提交前必须通过
- 类型检查：[typecheck command] - 及早捕获类型错误
- 代码检查：[lint command] - 强制执行代码质量
- 构建：[build command] - 验证集成
主观门控（用于用户体验、设计、质量）：
- LLM 作为评审员，审查语调、美观性、可用性
- 二进制通过/失败 - 通过迭代收敛
- 仅在程序化门控可靠工作后添加
为每个 Ralph 模式项目创建以下结构：
项目根目录/
├── IMPLEMENTATION_PLAN.md # 共享状态，每次迭代更新
├── AGENTS.md # 构建/测试/检查命令（约60行）
├── specs/ # 需求（每个主题一个文件）
│ ├── topic-a.md
│ └── topic-b.md
├── src/ # 应用程序代码
└── src/lib/ # 共享工具
优先级任务列表 - 单一事实来源。格式：
# 实施计划
## 进行中
- [ ] 任务名称（迭代 N）
- 备注：发现、错误、阻塞项
## 已完成
- [x] 任务名称（迭代 N）
## 待办事项
- [ ] 未来任务
能否在不使用“和”的情况下用一句话描述主题？
- ✅ “使用 JWT 和会话管理的用户认证”
- ❌ “认证、配置文件和计费” → 3 个主题
运行项目的简明指南。保持在 60 行以内：
# 项目操作
## 构建命令
npm run dev # 开发服务器
npm run build # 生产构建
## 验证
npm run test # 所有测试
npm run lint # ESLint
npm run typecheck # TypeScript
npm run e2e # 端到端测试
## 操作备注
- 提交前测试必须通过
- 类型检查失败会阻止提交
- 优先使用 src/lib 中的现有工具，而非临时复制
为不同任务设置的专业角色：
角色：架构师 (@architect)
- 高层设计、数据建模、API 契约
- 关注点：模式、可扩展性、可维护性
角色：实施者 (@implementer)
- 编写代码、实施功能、修复错误
- 关注点：正确性、性能、测试覆盖率
角色：测试员 (@tester)
- 测试编写、验证、边界情况
- 关注点：覆盖率、可靠性、可复现性
角色：评审员 (@reviewer)
- 代码审查、PR 反馈、质量评估
- 关注点：风格、可读性、规范遵循
用法：
“生成一个带有 @architect 角色的子代理来设计数据模型”
您作为主代理的工作：工程设置、观察、纠正方向。
每个子代理迭代：
1. 研究 - 阅读计划、规范、相关代码
2. 选择 - 选择最重要的未完成任务
3. 实施 - 编写代码，仅一个任务
4. 验证 - 运行测试、代码检查、类型检查（背压）
5. 更新 - 标记任务完成、记录发现、提交
6. 退出 - 下一次迭代重新开始
循环在以下情况结束：
- ✅ IMPLEMENTATION_PLAN.md 中的所有任务完成
- ✅ 所有验收标准满足
- ✅ 测试通过，无阻塞问题
- ⚠️ 达到最大迭代次数（配置限制）
- 🛑 手动停止（Ctrl+C）
预先定义成功 - 避免“似乎完成”的模糊性。
[test_command] 返回 0针对难以自动化的质量标准：
## 完成检查 - 用户体验质量
标准：导航直观，主要操作易于发现
测试：用户能够完成核心流程而不感到困惑
## 完成检查 - 设计质量
标准：视觉层次清晰，品牌一致性保持
测试：布局遵循既定模式
运行 LLM 作为评审员的子代理进行二进制通过/失败检查。
specs/
├── authentication.md
├── database.md
└── api-routes.md
src/
├── app/ # App Router
├── components/ # React 组件
├── lib/ # 工具（数据库、认证、助手）
└── types/ # TypeScript 类型
AGENTS.md:
构建: npm run dev
测试: npm run test
类型检查: npx tsc --noEmit
代码检查: npm run lint
specs/
├── data-pipeline.md
├── model-training.md
└── api-endpoints.md
src/
├── pipeline.py
├── models/
├── api/
└── tests/
AGENTS.md:
构建: python -m src.main
测试: pytest
类型检查: mypy src/
代码检查: ruff check src/
specs/
├── model-architecture.md
├── training-data.md
└── inference-pipeline.md
src/
├── models/
├── training/
├── inference/
└── utils/
AGENTS.md:
训练: python train.py
测试: pytest tests/
代码检查: ruff check src/
GPU 检查: nvidia-smi
启动 Ralph 模式会话：
“为我在 ~/projects/my-app 的项目启动 Ralph 模式。我想实施使用 JWT 的用户认证。”
我将：
1. 创建包含优先级任务的 IMPLEMENTATION_PLAN.md
2. 生成子代理进行迭代实施
3. 应用背压门（测试、代码检查、类型检查）
4. 跟踪进度并宣布完成
当出现 Ralph 模式时，更新 AGENTS.md：
## 发现的模式
- 添加 API 路由时，同时添加到 OpenAPI 规范
- 优先使用 src/lib/db 中的现有数据库工具，而非直接调用
- 测试文件必须与实现文件位于同一位置
当轨迹出错时：
- Ctrl+C - 立即停止循环
- 重新生成计划 - “丢弃 IMPLEMENTATION_PLAN.md 并重新规划”
- 重置 - “Git 重置到最后已知的良好状态”
- 缩小范围 - 为特定工作创建更小范围的计划
针对主观标准（语调、美观性、用户体验）：
创建 src/lib/llm-review.ts：
interface ReviewResult {
pass: boolean;
feedback?: string;
}
async function createReview(config: {
criteria: string;
artifact: string; // 文本或截图路径
}): Promise<ReviewResult>;
子代理发现并使用此模式进行二进制通过/失败检查。
根据经验使用情况，强制执行以下实践以避免静默失败：
Ralph 必须在每次迭代后写入 PROGRESS.md。 这是不可协商的。
在项目根目录开始时创建 PROGRESS.md：
# Ralph: [任务名称]
## 迭代 [N] - [时间戳]
### 状态
- [ ] 进行中 | [ ] 阻塞 | [ ] 完成
### 已完成的工作
- [项目 1]
- [项目 2]
### 阻塞项
- 无 | [描述]
### 下一步
[来自 IMPLEMENTATION_PLAN.md 的具体下一个任务]
### 更改的文件
- `path/to/file.ts` - [简要描述]
原因： 外部观察者（父代理、定时任务、人类）可以跟踪一个文件，而不是扫描目录或从会话日志推断状态。
在生成新的 Ralph 会话之前：
- 通过 sessions_list 检查现有的 Ralph 子代理
- 终止或验证先前会话的完成情况
- 不要在同一代码库上生成重叠的 Ralph 会话
反模式： 在 v1 仍在运行时生成 Ralph v2 = 文件冲突、竞态条件、工作丢失。
切勿假设目录结构。每次迭代开始时：
// 验证当前工作目录
const cwd = process.cwd();
console.log(`工作目录: ${cwd}`);
// 验证预期路径是否存在
if (!fs.existsSync('./src/app')) {
console.error('预期 ./src/app，找到:', fs.readdirSync('.'));
// 调整或显式失败
}
原因： Ralph 可能从具有不同工作目录的不同上下文生成。
完成后，Ralph 必须：
PROGRESS.md，包含“## 状态: 完成”示例完成的 PROGRESS.md：
# Ralph: 影响者详情页面
## 状态: 完成 ✅
**完成时间:** [ISO 时间戳]
### 最终验证
- [x] TypeScript: 通过
- [x] 测试: 通过
- [x] 构建: 通过
### 创建的文件
- `src/app/feature/page.tsx`
- `src/app/api/feature/route.ts`
### 测试说明
1. 运行: `npm run dev`
2. 访问: `http://localhost:3000/feature`
3. 验证: [具体检查]
如果 Ralph 遇到不可恢复的错误：
不要静默失败。 一个停止迭代但没有进度日志的 Ralph 与仍在工作的 Ralph 无法区分。
设置显式迭代超时：
## 操作参数
- 最大迭代时间: 10 分钟
- 总会话超时: 60 分钟
- 如果迭代超限: 记录阻塞项，退出
原因： 防止在卡住的任务上无限循环，允许父代理干预。
每次 Ralph 模式会话后，记录：
## [日期] Ralph 模式会话
**项目:** [项目名称]
**持续时间:** [迭代次数]
**结果:** 成功 / 部分 / 阻塞
**学习:**
- 哪些工作良好
- 需要调整什么
- 添加到 AGENTS.md 的模式
常见的反模式：
| 反模式 | 后果 | 预防措施 |
|---|---|---|
| 无进度日志记录 | 父代理无法确定状态 | 强制 PROGRESS.md |
| 静默失败 | 工作丢失，时间浪费 | 显式错误日志记录 |
| 重叠会话 | 文件冲突，状态损坏 | 生成前检查/清理 |
| 路径假设 | 错误目录，错误文件 | 显式验证 |
| 无完成信号 | 父代理无限等待 | 清晰的完成状态 |
| 无限迭代 | 资源浪费，无进展 | 时间限制 + 阻塞项 |
| 复杂的初始提示 | 子代理从未启动（空会话日志） | 简化指令 |
证据： 空会话日志（2 字节），无工具调用，0 令牌使用
## 任务: [一个具体事项]
**文件:** 确切的/路径/to/file.ts
**内容:** 更改的精确描述
**验证:** 要运行的精确命令
**然后:** 更新 PROGRESS.md 并退出
## 规则
1. 不要查看其他文件
2. 不要“先检查”
3. 进行更改，验证，退出
修复所有这些文件中的 TypeScript 错误：
- lib/db.ts 有 2 个错误
- lib/proposal-service.ts 有 5 个错误
- route.ts 有错误
检查先修复哪些，然后...
修复 lib/db.ts 第 27 行：
更改: PoolClient 为 pg.PoolClient
验证: npm run typecheck
完成后立即退出
每个 Ralph 迭代处理一个文件。不是“所有错误”，不是“检查然后决定”。一个文件，一个更改，验证，退出。
强制： 每次迭代后，更新 PROGRESS.md，包含：
## 迭代 [N] - [时间戳]
### 状态: 完成 ✅ | 阻塞 ⛔ | 失败 ❌
### 已完成的工作
- [所做的具体更改]
### 验证
- [测试/代码检查/类型检查结果]
### 下一步
- [接下来应该发生什么]
原因： 定时任务读取 PROGRESS.md 以获取状态更新。如果未更新，状态显示为陈旧/重复。
如果 Ralph 停滞：
1. 检查会话日志（应在 60 秒内显示工具调用）
2. 如果生成后为空 → 指令太复杂
3. 简化：一个文件，一个行号，一个更改
4. 更短的超时强制更小的任务（300 秒而非 600 秒）
如果定时任务重复报告相同状态：
1. 检查子代理是否更新了 PROGRESS.md
2. 如果未更新 → 子代理跳过了文档步骤
3. 更新技能：在提示中添加“强制 PROGRESS.md 更新”
4. 手动修复：更新 PROGRESS.md 以反映实际状态
Ralph 在以下情况工作：单一文件焦点 + 显式更改 + 验证 + 退出
Ralph 在以下情况停滞：复杂决策 + 多个文件 + 条件逻辑