Ralph 编排器

一个基于“帽子”系统的编排框架，能够让 AI 代理持续循环工作，直到任务完成。

“我英语会不及格？这不可能！”——拉尔夫·维格姆

文档 | 快速入门 | 预设配置

安装

通过 npm（推荐）

npm install -g @ralph-orchestrator/ralph-cli

通过 GitHub 发布版安装脚本

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh

通过 Cargo

cargo install ralph-cli

目前 Homebrew 尚未从本仓库的自动化发布流程中发布。建议优先使用 npm、Cargo 或 GitHub 发布版安装脚本。

快速入门

# 1. 使用您偏好的后端初始化 Ralph
ralph init --backend claude

# 2. 规划您的功能（交互式 PDD 会话）
ralph plan "添加基于 JWT 的用户认证"
# 创建：specs/user-authentication/requirements.md、design.md、implementation-plan.md

# 3. 实现该功能
ralph run -p "在 specs/user-authentication/ 中实现该功能"

Ralph 会不断迭代，直到输出 LOOP_COMPLETE 或达到迭代上限。

对于更简单的任务，可以直接跳过规划并运行：

ralph run -p "为 /users 端点添加输入校验"

Web 控制台（Alpha 版）

Alpha 版： Web 控制台目前仍在积极开发中，可能存在一些不完善之处和破坏性变更。

Ralph 内置了一个 Web 控制台，用于监控和管理编排循环。

ralph web                              # 启动 Rust RPC API + 前端，并打开浏览器
ralph web --no-open                    # 跳过自动打开浏览器
ralph web --backend-port 4000          # 自定义 RPC API 端口
ralph web --frontend-port 8080         # 自定义前端端口
ralph web --legacy-node-api            # 选择使用已弃用的 Node tRPC 后端

MCP 服务器的工作区范围

ralph mcp serve 仅限于每个服务器实例对应一个工作区根目录。

ralph mcp serve --workspace-root /path/to/repo

优先级如下：

1. --workspace-root
2. RALPH_API_WORKSPACE_ROOT
3. 当前工作目录

对于多仓库使用场景，建议为每个仓库或工作区运行一个 MCP 服务器实例。Ralph 当前的控制平面 API 会在单个工作区根目录下持久化配置、任务、循环、规划会话和集合，因此按工作区划分服务器是确定性的模型。

要求：

• Rust 工具链（用于 ralph-api）
• Node.js >= 18 + npm（用于前端）

首次运行时，ralph web 会自动检测缺失的 node_modules 并执行 npm install。

设置 Node.js 的方法如下：

# 方法一：nvm（推荐）
nvm install    # 读取 .nvmrc 文件

# 方法二：直接安装
# https://nodejs.org/

开发环境：

npm install              # 安装前端和旧版后端依赖
npm run dev:api          # Rust RPC API（端口 3000）
npm run dev:web          # 前端（端口 5173）
npm run dev              # 仅启动前端（默认）
npm run dev:legacy-server  # 已弃用的 Node 后端（可选）
npm run test             # 运行所有前端和后端的工作区测试

MCP 服务器模式

Ralph 可以作为 MCP 服务器通过标准输入输出运行，供兼容 MCP 的客户端使用：

ralph mcp serve

此模式应从 MCP 客户端配置中调用，而非交互式终端工作流。

Ralph 是什么？

Ralph 实现了 拉尔夫·维格姆技术 —— 通过持续迭代实现自主任务完成。它支持以下功能：

• 多后端支持 — Claude Code、Kiro、Gemini CLI、Codex、Amp、Copilot CLI、OpenCode
• 帽子系统 — 通过事件协调的专用角色
• 背压机制 — 拒绝未完成工作的门控机制（如测试、代码检查、类型检查）
• 记忆与任务 — 持久化学习和运行时工作跟踪
• 5 种内置功能 — code-assist、debug、research、review 和 pdd-to-code-assist，更多模式已在示例中记录

RObot（人机协作）

Ralph 支持通过 Telegram 在编排过程中进行人工干预。代理可以提出问题并阻塞等待回复；人类也可以随时发送主动指导。

Telegram 快速接入：

ralph bot onboard --telegram   # 引导式设置（令牌 + 聊天 ID）
ralph bot status               # 验证配置
ralph bot test                 # 发送一条测试消息
ralph run -c ralph.bot.yml -p  "帮助人类"

# ralph.yml
RObot:
  enabled: true
  telegram:
    bot_token: "your-token"  # 或者设置 RALPH_TELEGRAM_BOT_TOKEN 环境变量

• 代理提问 — 代理会发出 human.interact 事件；循环将阻塞，直到收到回复或超时
• 主动指导 — 随时发送消息以在循环中引导代理
• 并行循环路由 — 消息可通过回复、@loop-id 前缀路由，或默认发送到主循环
• Telegram 命令 — /status、/tasks、/restart 可实时查看循环状态

请参阅 Telegram 指南 获取设置说明。

文档

完整文档可在 mikeyobrien.github.io/ralph-orchestrator 查看：

• 安装
• 快速入门
• 配置
• CLI 参考
• 预设
• 概念：帽子与事件
• 架构

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南，以及 CODE_OF_CONDUCT.md 了解社区规范。

许可证

MIT 许可证 — 详情请参阅 LICENSE。

💬 社区与支持

加入 ralph-orchestrator 社区，讨论 AI 代理模式、获取实施帮助或参与路线图建设。

• Discord：加入我们的服务器，与维护者及其他用户实时交流。
• GitHub Issues：如需报告 bug 或提出正式的功能请求，请使用 问题追踪器。

致谢

• Geoffrey Huntley — Ralph Wiggum 技术的创造者
• Strands Agents SOP — 代理 SOP 框架
• ratatui — 终端 UI 框架

---

“我在学习呢！”——Ralph Wiggum

Ralph Orchestrator 快速上手指南

Ralph Orchestrator 是一个基于“帽子（Hat）”系统的 AI 代理编排框架，通过持续迭代循环直到任务完成。它支持多种后端（如 Claude Code、Gemini CLI 等），并具备人类介入（Human-in-the-Loop）功能。

环境准备

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

• 操作系统：Linux, macOS 或 Windows (WSL)
• Rust 工具链：版本 1.75+（用于核心二进制文件）
  • 安装命令：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• Node.js：版本 18+ 及 npm（仅在使用 Web Dashboard 时需要）
  • 推荐使用 nvm 管理：nvm install
• AI 后端凭证：确保已配置好所选后端（如 Claude Code）的 API Key 或登录状态。

注意：目前官方未提供 Homebrew 源，推荐优先使用 npm、Cargo 或官方安装脚本。国内用户若访问 GitHub 释放源较慢，建议配置代理或使用 Cargo/npm 镜像加速。

安装步骤

您可以选择以下任意一种方式进行安装：

方式一：通过 npm 安装（推荐）

npm install -g @ralph-orchestrator/ralph-cli

方式二：通过 Cargo 安装

cargo install ralph-cli

方式三：通过官方安装脚本

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh

安装完成后，运行 ralph --version 验证安装是否成功。

基本使用

1. 初始化项目

首先选择您偏好的 AI 后端进行初始化（例如使用 Claude）：

ralph init --backend claude

2. 规划任务（可选但推荐）

对于复杂功能，可以使用交互式 PDD（Problem Driven Development）会话生成需求、设计和实施计划：

ralph plan "Add user authentication with JWT"

执行后将自动生成 specs/ 目录下的 requirements.md, design.md, implementation-plan.md 等文件。

3. 执行任务

让 Ralph 自动迭代执行任务，直到输出 LOOP_COMPLETE 或达到迭代上限：

ralph run -p "Implement the feature in specs/user-authentication/"

对于简单任务，可以直接跳过规划步骤运行：

ralph run -p "Add input validation to the /users endpoint"

4. 启动 Web 监控面板（Alpha 阶段）

如需可视化监控编排循环和任务状态，可启动本地 Web 服务：

ralph web

该命令会自动启动 Rust RPC API 和前端服务，并在浏览器中打开仪表盘。

---

更多高级功能（如 Telegram 机器人介入、MCP 服务器模式）及详细配置，请参阅官方文档：mikeyobrien.github.io/ralph-orchestrator