Ralph Wiggum 入门第 1 部分：介绍与基础

你正盯着一个枯燥的迁移任务——200 个测试文件需要从 Jest 转换成 Vitest。模式很清晰，工作纯粹是机械性的，但得花你一整天。

或者你可以输入一条命令，去吃个午饭，回来发现活干完了。

这就是 Ralph Wiggum。一旦你用过，你会纳闷之前是怎么过来的。

什么是 Claude Code？

Claude Code 是 Anthropic 官方的 Claude CLI（命令行界面）——一个基于终端的 AI 编程助手，可以读取、编写和编辑你代码库中的文件。不同于聊天界面，Claude Code 直接操作你的本地文件，运行命令，并融入你的开发工作流。完整介绍请参阅 Claude Code 精通第 1 部分：入门指南。

什么是 Ralph Wiggum？

Ralph 是一个 Claude Code 插件，它把你的 AI 助手变成了一个自主编程代理（Agent）。不再是通常的来回交互——提示、审查、提示、审查——你给 Ralph 一个任务，然后走开。它会一直工作到任务真正完成。

核心理念很简单：迭代 > 完美。不要试图在第一个提示就搞定。让循环去处理。

正如 Geoffrey Huntley，这项技术的创造者所说：「Ralph 就是一个 Bash 循环。」这就是它的本质——一个 while true，不断给 Claude 喂入同一个提示，直到满足完成条件。

具体机制如下：

1. 你给 Claude 一个带有明确完成条件的任务
2. Claude 开始工作，并在认为「完成」时尝试退出
3. 一个 Stop Hook（钩子）拦截并检查：它真的完成了吗？（Hook 是在 Claude 生命周期特定节点运行的自动化操作——详见 精通第 3 部分）
4. 如果没完成，同样的提示再次被喂入
5. Claude 在文件中看到自己之前的工作
6. 循环继续，直到真正完成

关键洞察？ 提示从不改变——但代码库在变。每次迭代都建立在上一次的基础上。Claude 读取自己之前的工作并加以改进。

为什么这很重要

这不是纸上谈兵。开发者们正在运行 14 小时的自主会话来迁移整个代码库。Geoffrey Huntley 运行了一个 3 个月的循环，构建了一门编程语言。VentureBeat 称 Ralph 为「当下 AI 领域最响亮的名字」。

这个插件由 Boris Cherny，Anthropic 的 Claude Code 负责人正式化。它是官方的。它已经可以用于生产。它正在改变严肃开发者的工作方式。

开始使用（5 分钟）

第 1 步：安装依赖

Ralph 需要 jq 来处理 JSON。先安装：

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows: 使用 WSL 或从 https://stedolan.github.io/jq/ 获取

第 2 步：安装插件

在 Claude Code 内，运行 /plugin 打开插件发现界面。搜索 "ralph" 并从官方插件中选择 ralph-loop。

或者直接安装：

/plugin install ralph-loop@claude-plugins-official

第 3 步：配置权限

这是大多数人踩坑的地方：Ralph 自主运行，意味着它不能每次编辑文件都停下来问你「这样可以吗？」。如果你不配置权限，循环在 Claude 遇到第一个权限提示时就会中断。

选项 A：在设置中预先批准（推荐）

在你的 .claude/settings.local.json 中添加 Ralph 需要的工具：

{
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "Bash(npm:test *)",
      "Bash(npm:run build *)",
      "Bash(git:add *)",
      "Bash(git:commit *)"
    ]
  }
}

理解权限语法： Bash(npm:test *) 模式的意思是「允许任何以 npm test 开头的 Bash 命令」。* 作为通配符。这让 Ralph 有权限运行测试而不用每次都提示你。详见 精通第 3 部分：项目配置 了解完整的权限模式。

选项 B：使用权限标志

对于沙箱环境中的长时间运行任务，你可以完全绕过权限提示：

claude --dangerously-skip-permissions
# 或
claude --permission-mode acceptEdits

警告： 只在沙箱环境（容器、虚拟机、一次性云实例）中使用 --dangerously-skip-permissions。它会给 Claude 完全的文件系统访问权限。

正如 Boris Cherny 所说，对于非常长的运行任务，你需要 --permission-mode=acceptEdits 或在沙箱中使用 --dangerously-skip-permissions，这样 Claude 就不会被阻塞等待你的确认。

选项 C：完全沙箱化（长时间运行任务推荐）

对于严肃的自主工作，Claude Code 的内置沙箱在隔离 Ralph 的同时仍然允许必要的操作。在 Claude Code 中运行 /sandbox 来启用它，这提供了操作系统级别的文件系统和网络隔离。

你还可以在 .claude/settings.json 中配置权限规则来控制 Ralph 可以访问什么：

{
  "permissions": {
    "allow": [
      "WebFetch(domain:registry.npmjs.org)",
      "WebFetch(domain:github.com)"
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(docker:*)",
      "Read(./.env)",
      "Read(~/.ssh/**)"
    ]
  }
}

根据你项目的需要自定义 allow/deny 列表。更多配置示例请参阅 JeredBlu 的指南。

第 4 步：运行你的第一个循环

从小处开始。这里有一个安全的初次实验：

/ralph-loop "Add JSDoc comments to all exported functions in src/utils.ts. Output <promise>DONE</promise> when complete." --completion-promise "DONE" --max-iterations 10

看着它工作。审查提交。感受这个节奏。

最重要的两个参数

--max-iterations 是你的安全网。一定要设置它。默认值是无限制，这意味着如果完成承诺（Completion Promise）永远不触发，Ralph 会一直运行下去。

从小处开始。 最初的几次实验用 10-20 次迭代。在大型代码库上跑 50 次迭代可能花费 50-100+ 美元的 API 额度。

--completion-promise（完成承诺）告诉 Ralph 什么时候停下来。它是精确的字符串匹配——Claude 必须输出这个精确的文本来表示完成。

/ralph-loop "<your task>" --max-iterations 30 --completion-promise "TASK COMPLETE"

插件 vs Bash 循环 vs TUI：该用哪个

运行 Ralph 有三种方式：

插件方式（/ralph-loop）

• 在单个上下文窗口中运行
• 最容易设置——零配置
• 适合 20-30 次迭代以下的任务

Bash 循环方式

• 每次迭代启动新的上下文窗口
• 防止上下文膨胀和幻觉（Hallucination）
• 需要手动设置提示和文件

Ralph TUI（详见 第 3 部分）

• 每次迭代使用新的上下文（类似 Bash 循环）
• 内置 PRD（产品需求文档）创建、任务跟踪和监控面板
• 帮你处理所有的提示管理和文件管理
• 最适合严肃的长时间运行构建

什么是上下文窗口（Context Window）？ 上下文窗口是 Claude 的工作记忆——Claude 关于你的对话所知的一切都必须在这里装得下（约 200K tokens）。随着你的工作，这里会被你的提示、代码和 Claude 的回复填满。当它满了，Claude 就会开始遗忘早期的细节。详见 精通第 2 部分：心智模型 了解更深入的解释。

这里是一个最简 Bash 循环示例：

#!/bin/bash
# loop.sh - 长任务用这个来替代插件
for ((i=1; i<=30; i++)); do
  echo "=== Iteration $i ==="
  result=$(claude -p "$(cat PROMPT.md)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"ALL TASKS COMPLETE"* ]]; then
    echo "Done after $i iterations"
    exit 0
  fi
done

正如 JeredBlu 指出的，Bash 循环方式「从根本上更适合长时间运行任务」，因为每次迭代都从全新状态开始。插件在单个上下文中运行所有内容，在 30-40 次迭代后可能导致性能下降。

查看实际实现： 浏览社区的完整 Ralph 配置：

• snarktank/ralph — 完整的 ralph.sh、prompt.md 和 AGENTS.md
• ClaytonFarr/ralph-playbook — PROMPT_plan.md 和 PROMPT_build.md 模板
• frankbria/ralph-claude-code — 带智能退出检测的实现

没用 Claude Code？ Ralph 也能和其他工具一起用：

• ralph-wiggum-cursor — Cursor IDE 集成，带 Token 跟踪
• aymenfurter/ralph — VS Code 扩展，带可视化控制面板
• opencode-ralph-wiggum — OpenCode 集成，带卡顿检测

建议： 从插件开始学习概念。对于生产级的长时间运行任务，使用 Ralph TUI——它让你获得 Bash 循环方式的好处而不需要手动设置。详见 第 3 部分 获取完整的 TUI 指南。

写出有效的提示

这就是一个一直转圈的提示和一个能干净利落完成的提示之间的区别：

糟糕的提示（模糊的完成条件）：

Make the code better.

好的提示（具体且可测试）：

Add comprehensive error handling to src/api/users.ts.

Requirements:
- Wrap all async operations in try/catch
- Return proper HTTP status codes
- Log errors with context
- Add input validation for all endpoints

Run tests after each change. Fix any failures before moving on.

When ALL tests pass, output: <promise>COMPLETE</promise>

好的提示具备：

• 明确的范围 — 具体的文件，具体的修改
• 可测试的标准 — 「测试通过」是二元的，不是主观的
• 内置的质量门禁 — 「继续之前先修复失败」
• 明确的完成信号 — 完成时输出的精确文本

什么时候用 Ralph（什么时候不用）

Ralph 擅长：

• 机械性重构 — Jest → Vitest、CommonJS → ESM
• 添加测试 — 「让这个模块的覆盖率达到 80%」
• CRUD 操作 — 「添加带验证的用户管理接口」
• 文档 — 「给所有公共函数添加 JSDoc」
• 迁移 — 「更新所有导入以使用路径别名」

不要用 Ralph 来：

• 审美决策 — 「让 UI 更好看」不可测试
• 一次性编辑 — 如果手动只要 30 秒，直接做吧
• 生产环境调试 — 你需要上下文和判断力，而不是迭代
• 目标不明确 — 「让它变更好」会无限循环

经验法则： 如果你能为「完成」写一个自动化测试，Ralph 就能搞定。如果完成需要人类判断，那就自己来。

Ralph 哲学

The Ralph Playbook 记录了让这一切运作的四个核心原则：

1. 迭代 > 完美 — 不要试图在第一个提示就完美搞定。让循环来打磨。
2. 失败即数据 — 当 Ralph 失败时，你学会了怎么写更好的提示。
3. 操作者的技能很重要 — 你的提示质量决定了 Ralph 的成功率。
4. 坚持就是胜利 — 循环自动处理重试。你只需定义「完成」。

社区的格言：「可预测地失败，好过不可预测地成功。」

监控长时间运行的循环

当 Ralph 长时间运行时，你需要可视化。Ralph TUI 给你一个实时面板：迭代次数、当前任务、Token 使用量，以及暂停或停止的键盘控制。

我们在 第 3 部分：Ralph TUI 监控 中详细介绍监控。

接下来

你已经安装了 Ralph。你理解了循环。你知道什么时候用它，什么时候手动操作。

但我们只是揭开了冰山一角。

在 第 2 部分：三阶段方法论 中，我们将介绍专业工作流——分别用于规划和构建的提示、指导多天项目的规格文件，以及让长时间自主构建真正可行的技巧。这就是 Ralph 从「好用的工具」变成「力量倍增器」的地方。

术语表

刚接触 Claude Code？以下是你在整个系列中会遇到的关键术语：

上下文窗口（Context Window） — Claude 的工作记忆。Claude 关于你的对话所知的一切都必须在这里装得下（约 200K tokens）。了解更多

反压（Backpressure） — 自动化验证（测试、Lint、类型检查），拒绝不合格的工作，迫使 Claude 迭代直到正确

完成承诺（Completion Promise） — Claude 必须输出的精确文本，用来表示任务完成。Ralph 使用字符串匹配来检测

迭代（Iteration） — 一个完整的思考-行动-观察-纠正周期。一个任务可能需要多次迭代

子代理（Subagent） — 具有独立上下文的专业 AI 工作者，可以并行运行。了解更多

MCP — Model Context Protocol（模型上下文协议）。将 Claude 连接到外部服务，如数据库、API 和浏览器自动化。了解更多

Ultrathink — 分配最大思考预算（约 32K tokens）用于复杂推理的关键词。了解更多