Ralph Flow——下一代自定义工作流编排引擎，探索无界AI编程的极致潜力

Ralph Flow：从一段 Bash 循环到可编排的 AI 工作流引擎

2025年底，澳大利亚开发者 Geoffrey Huntley 在铲羊粪时琢磨出一个简单的 Bash 脚本——Ralph Loop。逻辑其实挺粗暴：每次用全新上下文启动 Agent，跑完一轮就停，然后重启再跑，直到任务完成或者 Token 烧光。没想到这玩意儿在社区里火得很快，连 Claude Code 的负责人 Boris Cherny 都用它跑了 30 天、提交了 259 个 PR。

但热闹过后，实际用起来的问题也慢慢浮出水面。成本不好控、中间产物没地方放、状态全靠外部脚本维护……社区里那句“抛弃 Workflow，拥抱 Ralph Loop”的口号，很快就被更务实的声音取代了：我们缺的不是循环本身，而是一个真正能灵活编排、可追溯的工作流引擎。

于是有了 ralph-flow。它不是要推翻 Ralph Loop，而是把那种“死磕到底”的思路，做成了一个插件化的多步骤工作流工具，专门给 OpenCode 用户用的。

一、Ralph Loop 的局限与 ralph-flow 的出发点

Ralph Loop 的核心就一句话：Stop Hook 拦截 AI 的结束指令，把原始 Prompt 重新塞回去，强制它继续跑。简单直接，适合单点任务死磕。但一旦任务稍微复杂点，问题就来了：

只能做“执行→检查→重试”的单循环，拆不了“分析-设计-实现-测试”的流水线。
中间产物无处安放，比如审查报告、设计文档，全靠 PRD JSON 和 progress.txt 硬扛。
状态管理散落在各个文件里，跑一半卡住了都不知道停在哪，回滚也麻烦。

ralph-flow 的思路很明确：保留“迭代直到完成”的内核，但把执行过程结构化。每个步骤拆成 DO（执行）和 CHECK（验证），用 YAML 定义流转逻辑，中间产物统一归档，状态实时可查。

二、核心设计：DO→CHECK 引擎与“工作流即配置”

1. 独立审计的 DO→CHECK 机制

每个步骤不再让 AI “自己考自己”。DO 阶段负责干活，输出 <done>；CHECK 阶段用独立的上下文去验证结果，返回 <true> 或 <false>。通过就往下走，不通过就把失败原因喂回去重试。

这样既避免了上下文膨胀导致的注意力分散，也解决了“全新失忆”带来的无效循环。每次失败后重新注入失败上下文，AI 是带着“上次为什么没跑通”的记忆继续的，而不是从头再来。

2. YAML 定义工作流

不用写代码，在 .opencode/ralph-flow/workflows/ 下放个 YAML 就能跑。比如一个标准的“审查→重构→测试”流程：

steps:
  - id: review
    desc: 代码审查
    do: 审查当前代码库，找出代码异味、潜在bug和优化机会，生成审查报告
    input: 项目源码
    output: review-report.md
    check: 审查报告是否覆盖了所有关键模块？是否给出了可操作的建议？
    on_pass: refactor
    on_fail: review
    max_fail_count: 3

  - id: refactor
    desc: 代码重构
    do: 基于审查报告执行重构，修复问题并优化代码结构
    input: review-report.md
    output: 重构后的代码
    check: 重构后代码是否通过了测试？是否解决了审查报告中的所有问题？
    on_pass: test
    on_fail: refactor
    max_fail_count: 5

  - id: test
    desc: 最终验证
    do: 运行完整测试套件，验证重构后的功能完整性
    input: 重构后的代码
    output: test-results.md
    check: 所有测试是否通过？是否有回归问题？
    on_pass: done
    on_fail: refactor
    max_fail_count: 3

每一步的输入、输出、验证条件、失败重试次数都写得很清楚。团队可以把这套逻辑沉淀成模板，新人直接 /ralphflow-start tdd 就能按规范走。

3. 关键节点的人工介入

AI 跑飞了最头疼的是 Token 烧完才发现方向错了。ralph-flow 支持 manual_phase，比如：

manual_phase: review.do, execute.check

会在审查完成和验证前暂停，等你确认后再继续。效率和安全之间，留了一道手动开关。

三、状态管理与底层逻辑

1. 一切皆文件，Git 可追溯

所有中间产物和运行状态都放在 .opencode/ralph-flow/ 下：

.opencode/ralph-flow/
├── ralph-flow.local.md      # 工作流状态（Markdown frontmatter）
├── workflows/               # 自定义工作流 YAML 定义
├── artifacts/               # 中间产物（proposal/design/verification 等）
└── logs/                    # JSON Lines 格式执行日志

跑一半断了？直接看文件就知道停在哪，甚至能回滚。logs/ 里记录了 step_start、check_result、fail_count_increment 等事件，完全可审计、可回放。

2. 事件驱动与钩子

插件主要监听 session.idle 和 session.deleted。AI 输出 <done> 后进入 idle，插件自动注入 CHECK Prompt；验证结果出来后，根据 YAML 配置决定下一步。整个过程不依赖外部调度器，纯靠 OpenCode 的会话生命周期驱动。

四、ralph-loop vs ralph-flow：核心差异

维度	Ralph Loop	Ralph Flow
流程模型	单步死循环	YAML 定义的多步骤流水线
验证方式	PRD 里的 `passes` 标记	独立 CHECK 阶段，不同上下文审计
失败处理	全局 stuck 阈值	每步独立 `max_fail_count` + 失败上下文重试
人工介入	CLI 手动干预	`manual_phase` 精确控制暂停点
状态管理	`progress.txt`	Markdown 状态文件 + JSON Lines 日志
安装方式	npm 全局 CLI	OpenCode 插件，一行配置自动注册命令

五、快速上手

在 OpenCode 配置里加一行：

{ "plugin": ["@yibener/ralph-flow"] }

首次加载会自动初始化目录结构。常用命令就几个：

/ralphflow-start （自动引导选工作流）
/ralphflow-status （看当前进度、失败计数）
/ralphflow-continue / /ralphflow-cancel （恢复或终止）

六、能跑什么？不止是代码生成

ralph-flow 不预设固定模式，YAML 就是边界。除了刚才的 TDD 流程，实际社区里已经有人在用：

API 开发：接口设计 → 参数校验 → 业务逻辑 → 单测 → 集成测试
依赖升级：影响分析 → 兼容性检查 → 渐进迁移 → 回归验证
安全审计：代码扫描 → 漏洞分析 → 修复建议 → 审计报告

每个 YAML 都可以版本控制、团队共享。它更像是一个“工作流脚手架”，把重复的 AI 交互固化成可复用的标准动作。你不需要重新发明轮子，只需要把团队的 best practice 写成配置。

七、写在最后

ralph-flow 还在早期，目前只支持基础 DAG 流转和单 Agent 执行。后续可能会加可视化编辑器、条件分支、多 Agent 协作，甚至搞个社区模板市场。但现阶段，它已经能解决“AI 跑偏了不知道”、“中间产物找不到”、“流程无法复用”这几个最头疼的问题。

项目是开源的：https://github.com/534529531/ralph-flow
如果你也在用 OpenCode 做 AI 辅助开发，或者对可编排的工作流感兴趣，欢迎 clone 下来试试。有 bug 直接提 Issue，有更好的工作流模板也欢迎 PR。顺手点个 Star 就行，开源项目靠大家养着。

posted @ 2026-05-27 01:00 易奔二阅读(80) 评论(0) 收藏举报

刷新页面返回顶部

易奔二