Ralph

Ralph 是一个极简的、基于文件的自治编程 Agent 循环。每一次迭代都会从零开始，读取相同的磁盘状态，并一次完成一个需求（story）。

工作原理

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

• PRD (JSON)：定义需求（stories）、门禁（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/，以便你自定义提示词（prompts）和循环行为。安装过程中，系统会询问你是否需要添加必要的技能（skills）。

安装所需技能 (可选)

ralph install --skills

系统会提示你选择 Agent（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

默认输出（Agent 会在 .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 标志将 Ralph 指向不同的 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

选择 Agent 运行器

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

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 需要文件路径而非标准输入（stdin）时，请在 AGENT_CMD 中使用 {prompt}。
• 示例：参见 examples/commands.md。
• OpenCode 服务器模式：为了提高 OpenCode 的性能，可在单独的终端运行 opencode serve，并取消 .agents/ralph/agents.sh 中 AGENT_OPENCODE_CMD 行的注释，以使用 --attach http://localhost:4096。这样可以避免每次运行时进行冷启动。

测试

试运行冒烟测试（无需 Agent）：

npm test

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

npm run test:ping

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

RALPH_INTEGRATION=1 npm test

完整真实 Agent 循环测试：

npm run test:real