拉尔夫

拉尔夫是一个极简的、基于文件的自主编码代理循环。每次迭代都会从头开始，读取相同的磁盘状态，并一次只处理一个故事的工作。

工作原理

拉尔夫将文件和 Git视为内存，而不是模型上下文：

• PRD（JSON） 定义了故事、关卡和状态
• 循环 每次迭代执行一个故事
• 状态 持久化在 .ralph/ 中

全局 CLI（推荐）

从任何地方安装并运行拉尔夫：

npm i -g @iannuttall/ralph
ralph prd # 启动交互式提示符
ralph build 1 # 运行一次拉尔夫

模板层级

拉尔夫会按以下顺序查找模板：

1. 当前项目的 .agents/ralph/ 目录（如果存在）
2. 随本仓库一起提供的默认模板

状态和日志始终保存在项目的 .ralph/ 目录中。

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

ralph install

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

安装所需技能（可选）

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 安装）。

示例提示文本：

一个轻量级的 uptime 监控器（Hono 应用），部署在 Cloudflare 上，通过 AWS SES 发送邮件告警

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

.agents/tasks/prd-<short>.json

2. 运行一次构建迭代：

ralph build 1 # 运行一次拉尔夫

不提交的试运行：

ralph build 1 --no-commit # 运行一次拉尔夫

覆盖 ralph prd 的 PRD 输出：

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

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

ralph overview

这会在 PRD 文件旁边生成一个简短的概览文件：prd-<slug>.overview.md。

PRD 故事的状态字段会由循环自动更新：

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

如果循环崩溃且故事仍处于 in_progress 状态，你可以在 .agents/ralph/config.sh 中设置 STALE_SECONDS，以允许拉尔夫自动重新打开卡住的故事。

覆盖 PRD 路径

你可以通过 CLI 标志指定拉尔夫使用不同的 PRD JSON 文件：

ralph build 1 --prd .agents/tasks/prd-api.json # 运行一次拉尔夫

可选的进度覆盖：

ralph build 1 --progress .ralph/progress-api.md # 运行一次拉尔夫

如果 .agents/tasks/ 目录中存在多个 PRD JSON 文件，而你未指定 --prd，拉尔夫会提示你选择其中一个。

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

.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 build 1 --agent=claude # 运行一次拉尔夫
ralph build 1 --agent=droid # 运行一次拉尔夫
ralph build 1 --agent=opencode # 运行一次拉尔夫

如果未安装 CLI，拉尔夫会打印安装提示：

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

Ralph 快速上手指南

Ralph 是一个极简的、基于文件的自主编码代理循环工具。它将文件和 Git视为记忆，而非依赖模型上下文，每次迭代都会读取磁盘状态并逐个完成开发故事（Story）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 需安装 Node.js (推荐 LTS 版本)，因为 Ralph 通过 npm 分发。
• Git: 项目必须初始化为 Git 仓库，Ralph 依赖 Git 进行状态管理。
• AI 代理客户端: 根据您选择的模型，需预先安装对应的 CLI 工具（任选其一）：
  • 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

注意：国内用户若遇到 npm 或 curl 下载缓慢，建议配置淘宝镜像源 (npm config set registry https://registry.npmmirror.com) 或使用代理加速。

安装步骤

推荐全局安装 Ralph，以便在任何项目目录中直接使用。

1. 全局安装 Ralph：

   npm i -g @iannuttall/ralph
   

2. （可选）初始化项目模板与技能： 进入您的项目根目录，运行以下命令将默认模板复制到本地 .agents/ralph/ 目录，并安装必要的技能（如 commit, dev-browser, prd）。

   ralph install --skills
   

   运行后按提示选择您使用的 Agent（如 codex/claude 等）以及安装范围（本地或全局）。

基本使用

以下是从零开始运行一次完整开发循环的最简流程：

1. 生成需求文档 (PRD)

首先定义您的开发任务。Ralph 会通过交互式提示引导您输入需求，并生成 JSON 格式的产品需求文档（PRD）。

ralph prd

示例输入：A lightweight uptime monitor (Hono app), deployed on Cloudflare, with email alerts via AWS SES 输出：自动生成 .agents/tasks/prd-<short>.json 文件。

2. 执行开发迭代

运行一次构建循环，Ralph 将读取 PRD 中的第一个待办故事（Story），调用 AI 代理编写代码并提交。

ralph build 1

• 干跑模式（不提交代码）：如果您想先查看 AI 的计划而不实际写入 Git：

  ralph build 1 --no-commit
  

3. 查看进度与概览

您可以随时查看生成的自然语言概览，了解当前进度：

ralph overview

该命令会在 PRD 同级目录生成 prd-<slug>.overview.md 文件。

---

进阶提示：

• 若需切换 AI 代理，可在命令中指定：ralph build 1 --agent=claude。
• 所有运行状态和日志均保存在项目内的 .ralph/ 目录中。