Ralph Orchestrator

这是一个基于“帽子系统”（Hat-based）的编排框架，它能让 AI Agent 持续循环运行，直到任务完成。

“我英语不及格？那是不可能的！”—— Ralph Wiggum

安装

通过 npm 安装（推荐）

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

通过 Homebrew 安装（macOS/Linux）

brew install ralph-orchestrator

通过 Cargo 安装

cargo install ralph-cli

快速入门

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

# 2. 规划你的功能（交互式 PDD 会话）
ralph plan "Add user authentication with JWT"
# 创建：specs/user-authentication/requirements.md, design.md, implementation-plan.md

# 3. 实现功能
ralph run -p "Implement the feature in specs/user-authentication/"

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

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

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

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 Server 工作区范围

ralph mcp serve 的作用范围限定为每个 server 实例对应一个工作区根目录。

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

优先级顺序为：

--workspace-root
RALPH_API_WORKSPACE_ROOT
当前工作目录

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

要求：

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

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

设置 Node.js：

# 选项 1: nvm (推荐)
nvm install    # 读取 .nvmrc

# 选项 2: 直接安装
# 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 Server 模式

Ralph 可以作为通过 stdio 通信的 MCP server 运行，供支持 MCP 的客户端使用：

ralph mcp serve

请在 MCP 客户端配置中使用此模式，而不是在交互式终端工作流中使用。

什么是 Ralph？

Ralph 实现了 Ralph Wiggum 技术 —— 通过持续迭代实现自主任务完成。它支持：

多后端支持 — Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, OpenCode
帽子系统 (Hat System) — 通过事件进行协作的专业化角色扮演系统
背压机制 (Backpressure) — 拒绝不合格工作的“门控”（测试、lint、类型检查）
记忆与任务 — 持久化学习与运行时任务追踪
5 个内置功能 — code-assist, debug, research, review, 和 pdd-to-code-assist，更多模式示例请查阅文档

RObot（人机协同）

Ralph 通过 Telegram 支持编排过程中的人工交互。Agent 可以发起提问并等待回复；人类也可以随时发送主动指导。

快速上手 (Telegram)：

ralph bot onboard

mikeyobrien/ralph-orchestrator