ralph — Lightweight Harness Framework
来源：@wayne_zhang0 + @hylarucoder (社区实践), 2026-04-12；Addy Osmani 系统梳理, 2026-04-28
核心观点
ralph loop（又称 Ralph Wiggum technique）是长时间运行 agent 的最小可用实现。 核心洞察：agent 本身是 amnesiac 的，但 filesystem 不是。状态存在磁盘上，每次迭代从磁盘读取足够上下文继续工作。
ralph loop 机制
Addy Osmani 总结的七步循环（参考实现为 bash 脚本）：
- 从任务列表（
prd.json或等效文件）中选取下一个未完成任务 - 构建 prompt：任务 + 相关上下文 + 持久化笔记
- 调用 agent
- 运行测试或其他检查
- 将执行结果追加到
progress.txt - 更新任务列表（完成 / 失败 / 阻塞）
- 回到步骤 1
文件系统的三种角色
| 文件 | 角色 | 类比 |
|---|---|---|
prd.json |
计划 | 产品需求文档 |
progress.txt |
实验笔记 | 实验室记录本 |
AGENTS.md |
滚动规则手册 | 操作手册 |
"The agent itself is amnesiac, but the filesystem isn't."
Compound Product 扩展
Ryan Carson 的 Compound Product 将单循环扩展为多循环链：
- 分析循环 — 读取日报，提取洞察
- 规划循环 — 输出 PRD
- 执行循环 — 编写代码
这大致是 Anthropic planner-generator-evaluator 三角色架构的开源等价物。
为什么有效
ralph loop 有效的原因与所有 production harness 相同：
- 状态活在 agent 上下文之外
- 每次迭代都是冷启动 + 状态注入
- 测试/检查作为硬 gate
Google 和 Anthropic 产品化的正是同一模式——只是增加了 recoverability、security 和 observability。
社区实践
AGENTS/CLAUDE.md 原则章节
海拉鲁编程客 (@hylarucoder) 分享在 AGENTS/CLAUDE.md 中添加"原则章节"指挥 coding agent 的经验：
## 原则
1. **代码仓库是唯一的记录系统**
- 不在 repo 里的知识对智能体不存在
- 讨论、脑中决策、外部文档——如果影响开发，必须落地为 repo 内的 versioned 文件
与 CLAUDE.md 配合使用
ralph 的设计理念与 Karpathy 的 AGENTS/CLAUDE.md 模式高度契合：
- 简单明确的规则优于复杂配置
- 代码即文档
- 版本控制即记忆
适用场景
- 快速原型开发
- 个人/小团队项目
- 多小时或隔夜任务（在 worktree 中运行，笔记本合盖不中断）
- 需要精细控制 agent 行为的场景
Addy Osmani 的判断："This is the path most people should take, and it's where the most leverage is right now."
Codex /goal：进程内的目标导向循环（2026-05-03）
OpenAI 在 Codex CLI 0.128.0 中加入 /goal 命令，提供了一种与 ralph loop 不同的目标维持机制。
核心差异：
| 维度 | ralph loop（社区实现） | Codex /goal |
|---|---|---|
| 状态维持 | 每轮冷启动，靠 git + 进度文件交接 | 进程内持续循环，目标跨轮次保持活跃 |
| 类比 | 接力赛，每一棒换新人 | 马拉松，累了暂停但不换人 |
| 持久化 | 文件系统（progress.txt） |
SQLite 数据库（进程重启不丢失） |
| 完成判定 | 测试通过或人工检查 | 内置完成审计协议 + 预算控制 |
Codex /goal 的防护机制：
- 零工具调用抑制：一轮中 Agent 未调用任何工具，系统自动停止循环
- 预算控制：token 预算 + 时间上限，超限时注入提示要求总结进展
- 完成审计协议：每次续跑要求模型将目标拆解为可交付物、建检查清单、检查真实文件/输出/测试结果
- 模型只能标记完成，不能暂停：防止模型"偷懒"自行暂停
关系：ralph loop 是社区最小实现，Codex /goal 是产品化版本。两者共享同一核心洞察——状态活在 agent 上下文之外——但 Codex 增加了恢复能力、预算约束和完成审计。
与 Managed Agents 的对比
| 维度 | ralph loop | Claude Managed Agents / Google Agent Platform |
|---|---|---|
| 基础设施 | 本地 bash + JSON | 托管运行时 + 持久化 session + SLA |
| 恢复能力 | 手动 checkpoint | 自动 wake(sessionId) 恢复 |
| 安全性 | 依赖本地隔离 | 沙箱 + 凭证隔离 |
| 可观测性 | progress.txt | 结构化事件日志 + 监控 |
| 适用阶段 | 个人/小团队 | 生产级托管产品 |
关联
- claude-code/llm-wiki-pattern — Karpathy LLM Wiki 模式
- harness-engineering/overview — Harness Engineering 综述
- harness-engineering/what-is-agent-harness — 什么是 Agent Harness
- harness-engineering/yoyo-harness-engineering-practice — Yoyo Harness 实践
- harness-engineering/anthropic-long-running — Anthropic 双 agent 架构