Ralph MCP

拉尔夫MCP

](https://www.npmjs.com/package/ralph-mcp) 

平行拉尔夫环：PRD→ ralph_start → 继续聊天 → 合并。在具有自动质量门和合并的隔离工作树中同时运行多个PRD。

基于 杰弗里·亨特利的拉尔夫模式.

配套项目：使用 Ralph CLI 当你想要一个独立的终端管理器时，启动重启、租赁/修订恢复和一个专用的集成工作树。需要时使用Ralph MCP ralph_start, ralph_status，以及可从MCP原生Claude Code工作流中获得的Ralph Runner。

中文文档

拉尔夫循环（2步）

Step 1: Generate PRD
User: "Create a PRD for user authentication"
Claude: [Generates tasks/prd-auth.md]

Step 2: Execute
User: "Start" or "Execute this PRD"
Claude: ralph_start → Task Agent handles everything automatically

就这样 Ralph MCP自动处理：分支创建、工作树隔离、代码实现、质量检查、提交、合并和文档同步。

为什么选择Ralph MCP？

对原版Ralph的改进

拉尔夫MCP扩展 snarktank/ralph 在保持其核心优势的同时，实现生产级自动化。

新增功能

保存了什么

Ralph MCP保持了久经考验的基础：

• 珠三角驱动发展 -带有用户故事和验收标准的结构化需求
• 迭代执行 -一次一个用户故事，有质量关卡
• Git工作树隔离 -并行特征之间无冲突
• 质量门 -每次提交前进行类型检查、lint、build
• 自动合并 -当所有故事都通过时，实现免提集成

关键架构更改

1. 长寿特工：一个代理完成PRD中的所有用户故事（不为每个故事生成新流程）
2. 跑步者自动化：后台进程管理执行生命周期，不运行手动脚本
3. MCP本地：通过MCP协议与Claude Code直接集成
4. 状态持久性：基于JSON的状态在重启后仍然有效，并支持并行执行跟踪

特性

• 两步工作流程 -只需创建PRD并运行 ralph_start，其他一切都是自动的
• 并行执行 -与长期使用的Ralph代理同时运行5+个PRD
• CLI第一代理运行时 -默认为CLI执行，SDK回退仍然可用
• Git工作树隔离 -每个PRD都在自己的工作树中运行，零冲突
• 依赖管理 -PRD可以依赖于其他PRD；依赖项只有在依赖项PRD集成到同一项目中后才会启动
• 停滞检测 -自动检测卡住的代理（无进度、重复错误）并标记为失败
• 代理内存 -持久的“进度日志”从用户故事中的错误中学习

代理支持

Ralph MCP将代理执行分为两个维度：

• agent.backend: cli （默认）或 sdk
• agent.provider: codex （默认）或 claude

默认情况下，运行者现在更喜欢CLI启动器，当CLI启动失败时，可以回退到SDK后端。

Codex CLI（默认）

通过Codex CLI使用GPT-5.3 Codex执行代理。

要求：

• 已安装Codex CLI
• LiteLLM代理正在运行 localhost:4000
• 环境变量：

  export OPENAI_BASE_URL=http://localhost:4000/v1
  export OPENAI_API_KEY=

配置：

# .ralph.yaml
agent:
  backend: cli
  provider: codex
  coAuthor: "GPT-5.3 Codex "
  
  codex:
    # Path to Codex CLI (default: "codex")
    codexPath: "codex"
    
    # Approval policy for command execution
    # Options: never, on-request, on-failure, untrusted
    approvalPolicy: on-request
    
    # Sandbox mode for filesystem access
    # Options: read-only, workspace-write, danger-full-access
    sandboxMode: workspace-write
    
    # Execution level (L1=Executor, L2=Builder, L3=Autonomous, L4=Specialist)
    level: L2
    
    # Max auto-recovery attempts when stalled
    maxRecoveryAttempts: 2
    
    # Minutes of inactivity before detecting stall
    stallTimeoutMinutes: 5

Claude 命令行界面

当您需要CLI后端但更喜欢Claude作为提供者时，可以直接使用Claude Code CLI。

要求：

• 已安装Claude Code CLI
• LiteLLM代理正在运行 localhost:4000 （可选，适用于自定义型号）

配置：

# .ralph.yaml
agent:
  backend: cli
  provider: claude
  coAuthor: "Claude Opus 4.6 "

  claude:
    claudePath: claude
    additionalFlags: []

SDK后端（回退/覆盖）

如果您更喜欢进程内SDK路径，或者希望在CLI启动器不可用时有一个稳定的回退，请切换 agent.backend 到 sdk.

agent:
  backend: sdk
  provider: claude # or codex

比较

切换代理

要切换提供商或后端，请更新您的 .ralph.yaml:

# Use Claude CLI
agent:
  backend: cli
  provider: claude

# Use Codex CLI (default)
agent:
  backend: cli
  provider: codex

# Use Claude SDK instead
agent:
  backend: sdk
  provider: claude

然后重新启动Ralph MCP服务器或运行 ralph_doctor 以验证配置。

为什么是长寿特工？

Ralph MCP的长寿命代理设计不同于原始的Ralph模式。本节解释了这两种方法背后的推理。

拉尔夫哲学

Geoffrey Huntley在设计Ralph时考虑到了一个明确的约束： 上下文窗口限制 （当时约17万个代币）。他的哲学：

• 每个代理进程一个用户故事 -每个故事都有一个新的主体，具有集中的背景
• 避免多代理复杂性 -无代理间通信或协调开销
• 快速反馈回路 -无上下文膨胀的快速迭代
• 简单的编排 -基于脚本的执行，易于理解和调试

这种设计对于2024年的限制是最优的：有限的上下文窗口意味着做好一件事比试图一次完成所有事情要好。

为什么Ralph MCP改变了这一点

Ralph MCP采用长期代理（每个PRD一个代理），因为约束已经演变：

1.更大的上下文窗口（20万+令牌）

• 现代Claude模型可以处理具有多个用户故事的整个PRD
• 上下文窗口不再是多层执行的瓶颈

2.学习积累

• 进度日志记录了同一PRD内用户故事的学习情况
• 后来的故事受益于早期故事中的发现
• 示例：“US-001发现 pnpm db:migrate:dev 必须在模式更改后运行”→US-003预先知道这一点

3.降低启动开销

• 为每个故事生成一个新的代理进程会增加延迟（模型加载、上下文注入）
• 长期代理在PRD的所有故事中摊销这一成本

4.上下文连续性

• Agent记住以前故事中的架构决策
• 无需为每个故事重新解释项目结构或惯例
• 自然对话流程：“继续使用US-002中的相同方法”

权衡比较

何时使用每种方法

原始拉尔夫 在以下情况下更好：

• 上下文窗口有限（\ !s.passes) 在代理提示生成中。与需要手动操作的ralph-cli不同 completedUS.includes()` 经检查，ralphmcp的设计本质上防止了已完成故事的重新执行。
• 修复了进度检测误报问题
• 添加了提交计数跟踪，以区分实际进度和停滞
• 防止代理在成功提交代码后被标记为停滞

学分

• G0d2i11a -维护人员
• 杰弗里·亨特利 -原始拉尔夫图案
• 拉尔夫cli -配套命令行Ralph控制器
• 人类 -克劳德代码和MCP协议

许可证

麻省理工学院