文章目录
- Pre
- 一、整体架构：从执行原语到自主模式
- 1. 基础执行原语
- 2. 自主模式在层级中的位置
- 二、Autopilot：从 2 行想法到可验证交付物
- 1. 典型使用场景
- 2. 六阶段完整生命周期
- 3. 利用上游成果进行“短路”
- 4. 配置与恢复能力
- 三、Ralph：PRD 驱动的保证完成引擎
- 1. 适用场景与定位
- 2. 以 PRD 为中心的九步循环
- 3. Ralph 的 flags 与可调行为
- 四、Ralphthon：从“任务执行”到“自主黑客马拉松”
- 1. 角色与定位
- 2. 编排机制与“波次”加固
- 五、如何选择：Autopilot、Ralph 还是直接执行？
- 1. 典型场景与模式选择
- 2. 预执行拦截门：ralplan 的守门人角色
- 六、状态持久化、统一取消与安全机制
- 1. 持久化：跨上下文的连续执行
- 2. cancel：统一的退出机制
- 3. 安全限制与断路保护
- 七、实战建议与常见排错思路
- 1. 常见症状与处理建议
- 2. 在团队里的落地建议
- 结语：从“辅助开发”走向“自治团队”的中间态
Pre
OMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”：oh-my-claudecode 深度解析与实战指南
OMC - 02 五分钟起步，走向多智能体协作：深入解析 oh-my-claudecode 快速开始与架构设计
OMC - 03 从 0 到高效：Oh My ClaudeCode 安装与实践全指南
OMC - 04 用好 Oh-My-ClaudeCode 的 30 个会话技能：从“帮我写点代码”到端到端自动交付
OMC - 05 从单人到多 Agent：Oh-my-claudecode 的插件架构解析
OMC - 06 从“大模型管家”到“十九人专家团队”：oh-my-claudecode 的多 Agent 工程实践
OMC - 07 把「选模型」当成一门工程学：oh-my-claudecode 的三层模型路由实践
OMC - 08 在多 Agent 时代，如何优雅地「分工协作」：oh-my-claudecode 委托分类体系深度解读
OMC - 09 oh-my-claudecode 的多 Agent 编排实战
大模型编码工具已经从“写几行辅助代码”进化到可以端到端承担完整开发流水线。Oh-My-ClaudeCode（下文简称 OMC）在这个方向上给出了一个相当激进的答案：通过Autopilot和Ralph两种自主执行模式，把自然语言需求可靠地转化为可运行、可验证的代码。
本文面向有一定工程经验的开发者、架构师和研究者，围绕以下几个问题展开：
- Autopilot 和 Ralph 分别解决什么问题？
- 它们在整体自主执行架构中的位置是什么？
- 具体是如何“免看管”地完成从规划到交付的？
- 对真实团队实践意味着什么，应该如何选择和落地？
一、整体架构：从执行原语到自主模式
在 OMC 中，自主能力不是从零开始堆出来的，而是建立在一套可组合的执行原语之上。 这些原语大致可分为两层：基础能力与编排模式。
1. 基础执行原语
核心原语包括：
- Deep Interview：面向需求方的“苏格拉底式访谈”，通过不断追问澄清模糊需求，形成结构化规范。
- Ralplan：共识规划器，在已有需求基础上产出多轮审校过的实现计划。
- Executor Agents：专职执行单个编码/改动任务的 agent，负责真正写代码、改文件。
- Ultrawork：并行执行引擎，在多个 executor 之间分发任务，并按任务复杂度路由到 Haiku、Sonnet、Opus 不同模型层级。
- UltraQA：面向构建、测试、lint 的 QA 循环模块。
这些原语提供了“如何干活”的底层能力，但还缺少一个“长程目标 + 状态机”式的外壳来承接完整需求。
2. 自主模式在层级中的位置
在基础原语之上，OMC 进一步叠加出两种更高层的自主模式：
- Ralph：在 Ultrawork 外层封装会话持久化、按 story 追踪、强制审查者验证，专注于“确保 PRD 中每一条验收标准都确实完成”的问题。
- Autopilot：再包裹在 Ralph 之外，承担“从模糊产品创意出发，一路走到可验证交付物”的完整六阶段生命周期。
可以把它们想象成一个自底向上的栈：
- 最底层：粗粒度的“并行执行引擎 + 单任务 agent”。
- 中间层：Ralph 把这些执行能力变成“可追踪的 PRD 完成循环”。
- 顶层：Autopilot 把 PRD 循环前后的需求扩展、架构规划、QA 和多重验证全部编排起来，形成完整流水线。
二、Autopilot：从 2 行想法到可验证交付物
Autopilot 是 OMC 中自主性最高的模式，设计目标很直接：给它一段 2–3 行的产品创意，剩下的全部交给系统完成。
1. 典型使用场景
典型使用方式类似：
“请用 TypeScript 为书店库存构建一个 REST API，支持库存查询与入库。”
在这样的场景里，人类只给出目标与约束的大方向，不介入“接口怎么设计”“文件怎么拆分”“测试怎么写”等工程细节。
Autopilot 尤其适合：
- 新功能从 0 到 1：一个明确的业务目标，但没有现成的技术方案。
- 跨文件、多模块改造：涉及架构调整、测试补齐、安全校验等。
- 你愿意让系统自行“规划 +执行 + 验证”，只在关键节点审阅。
2. 六阶段完整生命周期
Autopilot 把整个交付过程切成 6 个阶段，每个阶段都是下一个阶段的门槛，阶段内可以高度并行，但阶段之间严格顺序执行。
六个阶段如下：
Phase 0 — 扩展（Expansion）
- 角色：Analyst（分析师） + Architect（架构师），均使用 Opus 级模型。
- 目标：把用户的几行想法转成详细的规格说明。
- 输出：
.omc/autopilot/spec.md。 - 额外机制：如果输入过于模糊（没有具体文件、函数或上下文锚点），会建议先走
deep-interview做需求澄清，再回到扩展阶段。
Phase 1 — 规划（Planning）
- 角色：Architect 直接写实现计划，然后交由 Critic 校验。
- 目标：确定要改哪些文件、做哪些步骤、执行顺序是什么。
- 输出：
.omc/plans/autopilot-impl.md。
Phase 2 — 执行（Execution）
- 角色：Ralph + Ultrawork。
- 目标：正式编码和改造，任务拆解为多个子任务并发执行。
- 路由策略：简单事务走 Haiku，常规开发走 Sonnet，复杂分析走 Opus。
Phase 3 — QA 循环（QA Cycling）
- 模块：UltraQA。
- 目标：构建、lint、测试循环执行，直到全部通过或达到上限。
- 限制：最多 5 个循环。
- 安全机制：“同一错误 3 次出局”（连续 3 个 QA 循环出现同一错误会提前断路，避免在根本性问题上无效重试）。
Phase 4 — 验证（Validation）
- 角色：三个并行审查者。
- Architect：关注功能完整性。
- Security Reviewer：关注安全漏洞。
- Code Reviewer：关注代码质量和可维护性。
- 规则：三者必须全部通过，否则拉回去修复后再次验证，最多可配置多轮。
- 角色：三个并行审查者。
Phase 5 — 清理（Cleanup）
- 行为：删除所有相关状态文件（例如
autopilot-state.json、ralph-state.json、ultrawork-state.json、ultraqa-state.json），并调用统一的cancel技能干净退出。
- 行为：删除所有相关状态文件（例如
这种流水线带来的好处是：任何出错点都尽可能被局部隔离和显式暴露，而不是在一个巨大的“黑盒对话”中消失不见。
3. 利用上游成果进行“短路”
Autopilot 并不强制每次都从 Phase 0 开始。只要上游已经产出可信的中间成果，就会自动跳过对应阶段：
| 上游产物 | 文件模式 | Autopilot 行为 |
|---|---|---|
| Deep Interview 规范 | .omc/specs/deep-interview-*.md | 跳过 Phase 0，直接从规范进入规划阶段。 |
| Ralplan 共识计划 | .omc/plans/ralplan-*.md或consensus | 跳过 Phase 0 和 Phase 1，直接进入执行阶段。 |
因此，完整推荐链路往往是：
/deep-interview→/ralplan --direct→/autopilot。
这样，Autopilot 承接的是“已经过多重校验的规范与计划”，极大降低了后续阶段的反复修改和返工概率。
4. 配置与恢复能力
Autopilot 的行为可以通过.claude/settings.json中的omc.autopilot配置项进行调整：
| 参数 | 类型 | 默认值 | 作用 |
|---|---|---|---|
maxIterations | number | 10 | 所有阶段的最大总迭代次数 |
maxQaCycles | number | 5 | Phase 3 QA 循环的最大轮次 |
maxValidationRounds | number | 3 | Phase 4 验证可重试轮次 |
pauseAfterExpansion | boolean | false | Phase 0 后暂停，允许人工审阅规范 |
pauseAfterPlanning | boolean | false | Phase 1 后暂停，允许人工审阅计划 |
skipQa | boolean | false | 跳过 QA 阶段 |
skipValidation | boolean | false | 跳过验证阶段 |
同时，Autopilot 的状态是持久化的：如果中途取消或失败，再次调用/oh-my-claudecode:autopilot时，可以从状态文件恢复，从上次停下的位置继续执行。
在实践中，一个常见用法是：开启pauseAfterExpansion和pauseAfterPlanning，把需求和计划阶段当成“AI 辅助的文档/设计评审工具”，等认同之后再放行后续自动执行。
三、Ralph：PRD 驱动的保证完成引擎
如果说 Autopilot 管的是“从需求到交付”的整个旅程，Ralph 管的则是“交付阶段内部的每一个验收标准都确实完成”。它更接近一种PRD 驱动的严格执行控制环。
1. 适用场景与定位
Ralph 围绕一个结构化的prd.json文件运转，这个文件被视为“唯一的事实来源”（single source of truth）：里面包含了按优先级排序的 stories 和每个 story 的验收标准。
典型适用场景包括：
- 有明确拆分好的用户故事，需要逐条完成并验证。
- 希望把“验收标准”从口头约定变成真正的执行契约。
- 需要对每条 story 的完成情况留存“可审核的证据”。
一个简单例子是：
“实现这 5 个用户故事并进行验证。”
在这种情况下，用 Autopilot 反而会显得“太重太宽”，Ralph 则正好聚焦在 story 粒度的执行与验证上。
2. 以 PRD 为中心的九步循环
Ralph 的执行过程可以概括为一个九步循环，完全围绕prd.json展开：
Step 1：PRD 设置（PRD Setup）
- 如果已有
prd.json，则读取并校验。 - 否则自动生成脚手架，然后由 LLM 对其进行细化。
- 把诸如“实现完成”这类模糊描述，拆成具体且可验证的标准，例如“函数
processKeywordDetector接收字符串并返回布尔值”。 - stories 会按优先级排序（关键 → 高 → 中 → 低）。
- 如果已有
Step 2：选择下一条 story（Pick Next Story）
- 从未完成的 story 中按优先级选择下一条。
- 保证“最关键的事情先做完”。
Step 3：实现（Implement）
- 委派给不同层级的 executor agent。
- Ralph 借助 Ultrawork 并行触发独立任务，并把“修改了什么、改了哪些文件、踩坑经验”等记录在
progress.txt中，方便后续追踪和复盘。
Step 4：验证 story（Verify）
- 每条验收标准都必须有“新鲜证据”：运行对应测试、检查输出、验证行为。
- 只有当所有标准都有证据支撑时，这条 story 才能被视为“完成”。
Step 5：标记完成（Mark Complete）
- 在 PRD 中将 story 的
passes标记为true，并记录进度。 - 形成可机读的“完成轨迹”。
- 在 PRD 中将 story 的
Step 6：是否全部完成？（All stories complete?）
- 如果还有未完成 story，则返回 Step 2。
- 否则进入审查阶段。
Step 7：审查者验证（Reviewer Verification）
根据更改范围选择不同层级的审查者和模型：
更改范围 审查级别 模型 少于 5 个文件，少于 100 行，且具备完整测试 标准 Sonnet 一般更改 标准 Sonnet 超过 20 个文件，或涉及安全/架构等敏感部分 严格 Opus 审查是严格对照 PRD 中的验收标准，而不是“感觉上差不多就算完了”。
可通过命令行标志覆盖审查者：
--critic=architect：用 Architect 进行完成度验证（默认）。--critic=critic：用 Critic 进行更挑剔的完成度检查。--critic=codex：调用外部 Codex CLI，把“最优性”也纳入验证范围。
Step 7.5：AI 垃圾内容清理（AI-Slop Cleanup）
- 审查者通过后，会调用
ai-slop-cleaner技能对在本次会话中修改的文件进行“AI 垃圾内容”清理，比如多余注释、啰嗦代码路径等。 - 可以通过
--no-deslop标志跳过这一环节。 - 需要注意的是：
ai-slop-cleaner是一个 skill，必须通过Skill("ai-slop-cleaner")调用；如果误用为 agent，例如Task(subagent_type="oh-my-claudecode:ai-slop-cleaner")，会报 “Agent type not found”。
- 审查者通过后，会调用
Step 7.6：回归验证 & Step 8/9
- 清理后重新跑测试、构建、lint，确保没有引入新的问题。
- 如果一切正常，通过
cancel干净退出（Step 8）。若发现新的问题，则进入 “Fix & Re-verify”（Step 9），继续循环直至满足所有标准。
这套流程非常强调“可验证证据 + 结构化进度记录”，将“你觉得做完了”和“系统能证明做完了”明确分开。
3. Ralph 的 flags 与可调行为
Ralph 提供了一些常见标志用于自定义行为：
| 标志 | 含义 |
|---|---|
--no-deslop | 跳过审查后强制执行的 AI 垃圾内容清理环节 |
--critic=architect | 使用 Architect 作为完成度审查者（默认） |
--critic=critic | 使用 Critic 作为完成度审查者 |
--critic=codex | 使用外部 Codex CLI，包含“是否最优”的评估逻辑 |
在实际使用中，如果你特别在意“代码风格与一致性”，可以保留ai-slop-cleaner流程；如果你已经有自己的严格 code style 工具链，则可以通过--no-deslop关掉这一步，把控制权交回给现有工具链。
四、Ralphthon：从“任务执行”到“自主黑客马拉松”
在 Autopilot 和 Ralph 之上，OMC 又推了一层更“有野心”的东西：Ralphthon，一个面向黑客马拉松式长周期任务的自主生命周期。
1. 角色与定位
Ralphthon 不是一个 “skill”，而是src/ralphthon/下的 TypeScript 模块，通过 tmux 和状态机在基础设施层面编排整个流程。
它串联了以下阶段：
- deep-interview：与人类进行需求访谈，生成初始 PRD。
- PRD 生成与细化。
- Ralph 执行：按 story 推进、循环验证。
- 自动加固（hardening）：不断添加边界用例、性能/安全/质量加固任务。
- 干净终止：达到某个“加固充分”的阈值才结束整个黑客马拉松。
可以把 Ralphthon 看成是“把一个长时间、多人参与的黑客马拉松，移植到 AI 自治世界里”的尝试。
2. 编排机制与“波次”加固
Ralphthon 的 orchestrator 采用“双触发机制”：
- 监控 leader tmux 窗格的空闲情况，30 秒无活动视为 idle。
- 每 2 分钟做一次轮询，检查 Ralph 的 PRD 状态。
一旦检测到合适的状态，就通过tmux send-keys把任务注入 Claude Code 窗格，驱动下一个阶段的执行或加固任务生成。
加固阶段的核心概念是wave（波次）：
- 每一波会自动生成一组边界情况、测试、安全和性能加固任务。
- 完成这一波任务后，如果又暴露了新的问题，则增加 wave 计数继续下一波。
- 只有当连续 N 个“干净波次”（默认 3）没有发现新问题，或达到最大波次（默认 10）时，Ralphthon 才认为“足够稳固，可以结束”。
与之对应，Ralphthon 的 PRD 类型在标准 PRD 基础上扩展了：
- 加固任务（hardening tasks）。
- 规划上下文：例如棕地检测（现有系统情况）、假设模式、代码库映射等。
- 生命周期配置：波次上限、终止阈值等。
换句话说，它试图自动化过去常见的“赛后加固阶段”，而不是停在“功能看上去能跑就算完”。
五、如何选择：Autopilot、Ralph 还是直接执行？
实际使用中，开发者需要面对的是：这次任务应该用哪个模式？OMC 给出了一套比较明确的建议和一个“预执行拦截门”。
1. 典型场景与模式选择
官方给出的一些典型映射如下：
| 场景描述 | 推荐模式 | 理由 |
|---|---|---|
| “用 TypeScript 为书店库存构建一个 REST API” | Autopilot | 多阶段、从创意到可运行代码的大项目 |
“修复src/hooks/bridge.ts:326的空值检查” | 直接交给 executor | 改动范围单一且明确，不需要流水线 |
| “实现这 5 个用户故事并进行验证” | Ralph | 已有结构化 PRD，关键是保证每条故事都确实完成 |
| “改进这个应用” | 先 Ralplan → 再选模式 | 请求过于模糊，需要先规划与边界界定 |
| “修复这个”（缺乏任何锚点） | 自动拦截 → Ralplan | 有“执行意图”但没有上下文，先强制走共识规划 |
| “force: ralph 重构认证模块” | Ralph（绕过拦截门） | 用户使用force:前缀显式覆盖预执行拦截 |
这背后的原则很简单：
- 粒度小、上下文明确，直接交给 executor，避免重型流水线的开销。
- 有完整 PRD 但不需要从“创意”开始，用 Ralph 去保证“按故事彻底做完”。
- 需要系统帮你从模糊目标一路走到交付物，且接受 AI 自己做设计，选 Autopilot。
- 需求太模糊，系统会自动引导你先走 Ralplan 规划一遍，再去选 Autopilot 或 Ralph。
2. 预执行拦截门：ralplan 的守门人角色
系统内置了一个ralplan 预执行门，当检测到“想执行但规格不足”时，会拦截请求并重定向到共识规划流程。
它会自动放行带有这些“具体信号”的请求：
- 具体文件路径、issue/PR 编号。
- camelCase/PascalCase/snake_case 符号（常见函数名/变量名模式）。
- 测试运行器命令、编号步骤、明确验收标准。
- 错误引用、代码块。
- 显式的转义前缀
force:或!（表示你清楚风险，仍要继续）。
这套机制从工具层面避免了“来回空谈、无目标乱改”的情况，让自主执行更多发生在“信息充足”的区域。
六、状态持久化、统一取消与安全机制
要让自主模式真正能长时间跑下去，可靠的状态管理和安全控制同样关键。
1. 持久化：跨上下文的连续执行
所有自主模式（包括 ralph、autopilot、ultrapilot、swarm、ultrawork、ultraqa、pipeline、team 等）共享一套通用的状态层。
persistent-mode.mjs提供了一个持久模式钩子，解决了一个实际问题：大型对话在上下文窗口满了之后会被压缩甚至丢失关键状态。
这个钩子的做法是：
- 在上下文压缩前，把当前模式的核心状态记录到外部。
- 在后续轮次中把状态重新注入，让 LLM 知道“自己正在执行哪个模式、处在哪个阶段”。
这样，自主模式就能在长时间运行时保持“自我连续性”，而不是半路“失忆”。
2. cancel：统一的退出机制
cancel技能是所有 OMC 模式的标准退出入口：
- 检测当前有哪些活跃模式。
- 执行相应的清理逻辑：停止工作流、删除状态文件、释放任务占用等。
- 同时保留必要的进度信息，以便后续恢复或者做事后分析。
开发者的体验是：不需要记住每个模式的专属“退出指令”，统一用 cancel 即可。
3. 安全限制与断路保护
在安全方面，系统提供了多重限制措施：
- 全局迭代限制：
OMC_SECURITY=strict时，默认为最多 200 次迭代。- 也可以在
.claude/omc.jsonc的安全配置中自定义更细致的限制。
- Autopilot 的“同一错误三振出局”机制：
- 如果在 QA 阶段连续三个循环看到同一个错误，认为这是“根本性阻塞”而不是暂时性不稳定，主动停止并上报。
这些设计的目标很明确：在追求“免看管”的同时，避免系统在某个死胡同里反复消耗算力和时间，给人类一个清晰的“需要介入”的信号。
七、实战建议与常见排错思路
落地层面，Autopilot 与 Ralph 并不是“按下按钮就永远顺滑”的魔法工具，出现问题时，官方也给出了一些典型诊断与解决建议。
1. 常见症状与处理建议
部分典型问题及建议处理方式如下：
| 症状 | 可能原因 | 建议做法 |
|---|---|---|
| 卡在某个阶段没有进展 | 依赖阻塞或缺少/损坏状态文件 | 检查.omc/autopilot-state.json、ralph-state.json等，必要时 cancel 后重启 |
| QA 循环耗尽（达到 5 次） | 持续测试失败，且错误模式并非同一个 | 检查每轮失败是否由于不同问题导致，必要时人工重新审视实现方案 |
| 验证在 3 轮后仍然失败 | 原始需求/PRD 过于模糊或内部冲突 | 停止当前执行，回到需求或 PRD，细化和统一口径后再重跑 |
| 出现 “Agent type not found” 错误 | skill 被当成 agent 调用，或反之 | 确认 skill 用Skill("name")，agent 用Task(subagent_type="...") |
| Autopilot 一启动就跳到执行阶段 | .omc/plans/中存在 Ralplan 共识计划文件 | 这是预期行为，如需重新规划，删除对应计划文件 |
这些排查路径本质上仍然遵循一个原则：先搞清楚“系统以为自己在干什么”，再决定是补全信息还是清空状态重来。
2. 在团队里的落地建议
结合上面的机制，可以给出一些在团队环境中实践的建议示例：
- 把 Deep Interview 和 Ralplan 视作“AI 辅助的产品&架构评审”工具，尽量在 Autopilot 之前把需求&计划打磨到比较稳定的程度。
- 对长期项目，引入 Ralphthon 作为“持续加固管线”，把边界用例、安全与性能加固任务也结构化地交给系统排查。
- 在安全和合规要求高的团队，保持 QA 与 Validation 阶段开启，并把
maxValidationRounds调大一些，同时为 Security Reviewer 制定额外的审查规范。 - 在一开始，可以保守地多使用
pauseAfterExpansion/pauseAfterPlanning，逐步建立对系统行为的信任，再考虑放开更多阶段自动运行。
结语：从“辅助开发”走向“自治团队”的中间态
Autopilot 和 Ralph 并没有宣称要完全取代人类开发者，而是在实践中扮演了一个相当务实的角色：试图把“从需求到交付”的大量机械性、重复性的决策和操作自动化掉，把人类解放到更高层的产品思考和系统设计上。
- Autopilot 给了你一个从创意到交付的完整“自动驾驶”模式。
- Ralph 则守在交付阶段，确保每条验收标准都是真正被满足，而不是凭感觉打勾。
- Ralphthon 把这套能力延伸到更长周期和更高强度的“自主黑客马拉松”场景。
- 持久化、取消与安全机制为长时间运行、多人协作提供了必要的护栏。
对开发者而言，更现实的问题不是“要不要上 AI 自主模式”，而是：在哪些环节让它接管、在哪些环节保留人工决策，以及如何为你的团队设计一条合适的迁移路径。OMC 提供了一套相对完整的“模式库”，接下来要做的，就是把它拼装到你自己的工程实践里去。
