Ralph

Ralph 是一个极简的、基于文件的自主编程代理循环系统。每次迭代都会重新开始，读取相同的磁盘状态，并一次提交一个任务（Story）。

工作原理

Ralph 将文件和 Git 视为内存，而非模型上下文：

• PRD (JSON)：定义任务、门控（gates）和状态。
• 循环 (Loop)：每次迭代执行一个任务。
• 状态 (State)：持久化存储在 .ralph/ 目录中。

全局 CLI（推荐）

在任意位置安装并运行 Ralph：

npm i -g @iannuttall/ralph
ralph prd # 启动交互式提示
ralph build 1 # 执行一次 Ralph 运行

模板层级

Ralph 会按以下顺序查找模板：

1. 当前项目中的 .agents/ralph/（如果存在）。
2. 本仓库内置的默认模板。

状态和日志文件始终存放在项目中的 .ralph/ 目录下。

将模板安装到项目中（可选覆盖）

ralph install

这会在当前代码库中创建 .agents/ralph/，以便你自定义提示词和循环行为。在安装过程中，系统会询问你是否要添加所需的技能（skills）。

安装所需技能（可选）

ralph install --skills

系统会提示你选择代理程序（codex/claude/droid/opencode）以及选择局部还是全局安装。安装的技能包括：commit、dev-browser、prd。 如果你在执行 ralph install 时跳过了技能安装，可以随时通过 ralph install --skills 进行补充。

快速入门（项目）

1. 创建你的 PRD (JSON) 或生成一个：

ralph prd

需要 prd 技能（通过 ralph install --skills 安装）。

提示词示例：

A lightweight uptime monitor (Hono app), deployed on Cloudflare, with email alerts via AWS SES

默认输出（代理会在 .agents/tasks/ 中选择一个简短的文件名）：

.agents/tasks/prd-.json

2. 运行一次构建迭代：

ralph build 1 # 执行一次 Ralph 运行

不提交更改的空运行（dry run）：

ralph build 1 --no-commit # 执行一次 Ralph 运行

为 ralph prd 覆盖 PRD 输出路径：

ralph prd --out .agents/tasks/prd-api.json

可选的人类概览（从 JSON 生成）：

ralph overview

这会在 PRD 旁边写入一份简短的概览：prd-.overview.md。

PRD 的任务状态字段由循环自动更新：

• open → 可选择
• in_progress → 被正在运行的循环锁定（带有 startedAt）
• done → 已完成（带有 completedAt）

如果循环崩溃导致任务卡在 in_progress，你可以在 .agents/ralph/config.sh 中设置 STALE_SECONDS，允许 Ralph 自动重新开启卡住的任务。

覆盖 PRD 路径

你可以通过 CLI 参数指定不同的 PRD JSON 文件：

ralph build 1 --prd .agents/tasks/prd-api.json # 执行一次 Ralph 运行

可选的进度文件覆盖：

ralph build 1 --progress .ralph/progress-api.md # 执行一次 Ralph 运行

如果 .agents/tasks/ 中存在多个 PRD JSON 文件且你省略了 --prd 参数，Ralph 会提示你进行选择。

可选配置文件（如果你已安装模板）：

.agents/ralph/config.sh

选择代理运行器

在 .agents/ralph/config.sh 中设置 AGENT_CMD 以切换代理：

AGENT_CMD="codex exec --yolo -"
AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
AGENT_CMD="opencode run \"$(cat {prompt})\""

或者在每次运行时覆盖：

ralph prd --agent=codex
ralph build 1 --agent=codex # 执行一次 Ralph 运行
ralph build 1 --agent=claude # 执行一次 Ralph 运行
ralph build 1 --agent=droid # 执行一次 Ralph 运行
ralph build 1 --agent=opencode # 执行一次 Ralph 运行

如果未安装 CLI，Ralph 会打印安装提示：

codex    -> npm i -g @openai/codex
claude   -> curl -fsSL https://claude.ai/install.sh | bash
droid    -> curl -fsSL https://app.factory.ai/cli | sh
opencode -> curl -fsSL https://opencode.ai/install.sh | bash

状态文件 (.ralph/)

• progress.md — 仅追加的进度日志
• guardrails.md — “路标”（经验教训）
• activity.log — 活动及时间日志
• errors.log — 重复出现的失败及笔记
• runs/ — 原始运行日志及摘要

注意事项

• .agents/ralph 是可移植的，可以在不同仓库间复制。
• .ralph 是项目级别的状态存储。
• 当代理需要文件路径而不是标准输入时，请在 AGENT_CMD 中使用 {prompt}。
• 示例：请参考 examples/commands.md。
• OpenCode 服务器模式：为了获得更好的 OpenCode 性能，可以在另一个终端运行 opencode serve，并取消 .agents/ralph/agents.sh 中 AGENT_OPENCODE_CMD 行的注释以使用 --attach http://localhost:4096。这可以避免每次运行时的冷启动。

测试

空运行冒烟测试（无需代理）：

npm test

快速代理健康检查（真实代理调用，最少输出）：

npm run test:ping

可选集成测试（需要安装代理）：

RALPH_INTEGRATION=1 npm test

完整的真实代理循环测试：

npm run test:real