Ralph Orchestrator

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

"Me fail English? That's unpossible!" - Ralph Wiggum

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

安装

通过 npm 安装（推荐）

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

通过 GitHub Releases 安装脚本

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 Releases 安装脚本。

快速入门

# 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 在每个服务器实例中仅限于单个工作区根目录。

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：

# 选项 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 服务器，供 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（PDD 转代码辅助），更多模式详见文档示例。