CPT · AI Engineering

Technical Sharing · Agent Harness

Ruflo：把Codex多角色研发变成可治理的工程流程

不是再增加一个“写代码的AI”，而是在复杂任务中建立岗位、依赖、质量门禁、业务闭环和可回读证据。

文档版本V1.0

分享日期2026-08-28

建议时长40—50分钟

试点案例上禾SH-V20

常规Codex负责快速完成明确任务；Ruflo负责让跨系统、高风险、强业务闭环的AI研发协作不失控。

01｜Ruflo到底是什么

Ruflo是Codex之上的协调与治理层。它登记角色、任务、依赖、状态和memory；真实编码、测试与修复仍由Codex完成，最终结果仍由工程证据和人证明。

Ruflo角色、任务、依赖、状态、memory账本

→

Codex工作单元取证、编码、测试、修复、评审

→

工程证据Git、测试、数据库、HTTP、页面回读

→

人业务决策、授权、合并、部署和验收

1Ledger不是执行者

Agent active或task complete不代表代码已经运行。

2Agent数量不是产能

只有边界清楚、可独立验收的工作才值得并行。

3状态不是完成证据

完成必须有diff、测试、数据或环境回读。

02｜它解决的是复杂任务失控

上下文混杂

协议、数据库、页面和历史规则挤在一个任务中。

并行踩代码

多个Agent同时修改共享契约，责任边界消失。

只验成功路径

补传、幂等、异常、历史和旧功能没有覆盖。

中断难恢复

过程只在聊天中，换人后需要重新取证。

完成口径虚化

自报完成，却没有测试和数据库证据。

业务链断裂

接口写完了，副作用和用户展示没有闭环。

03｜5个角色，1个Writer

上禾试点证明，5个角色已经足够。角色分工的目标是减少盲区，不是制造组织规模感。

Coordinator依赖、进度、停止条件

Evidence协议、源码、数据证据

Writer唯一业务代码写入者

Tester异常、恢复、兼容矩阵

Reviewer正确性、安全、推广门禁

关键规则：一个worktree只有一个Writer。Evidence、Tester和Reviewer可以并行；未冻结的共享API、数据库、权限和配置契约不能并行修改。

04｜标准执行流程

PHASE A任务冻结目标、边界、验收

PHASE B隔离初始化外部Runtime

PHASE C角色与任务映射真实Codex

PHASE DTDD执行RED → GREEN

PHASE EReview Gate独立审查

PHASE F工程证据Git、DB、HTTP、页面

PHASE G人工决策合并、部署、验收

PHASE H量化复盘周期、缺陷、Token

05｜上禾SH-V20：从设备协议到小程序展示

这个任务同时涉及外部协议、身份、数据、历史业务、附件、小程序和旧设备兼容，是Ruflo适用场景的典型样本。

设备手机号 → 门店与会员匹配 → 报告幂等/补传合并 → 会话/raw/指标/附件
→ 体重/员工/积分/推荐能量 → 小程序体重档案 → 旧设备与统一查询回归

前置发现	如果遗漏	闭环处理
raw容量不足	最大波形报文截断	升级容量并外置大附件
回调缺门店上下文	业务数据落错租户	设备绑定store_id
补传被当普通重复	完整报告指标丢失	按recordNo合并
重复报文仍触发副作用	重复体重、积分和能量刷新	相同payload提前短路
历史补传覆盖最新	员工档案回退	按实际测量时间门控
小程序指标码不一致	体成分不显示	对齐统一健康指标
触发器依赖隐蔽	失效后排查困难	代码显式维护并回归旧设备

06｜收益不只体现在效率

效率

取证、测试设计和评审并行；中断后可从任务包恢复。

代码质量

独立Reviewer、TDD、异常恢复和兼容回归进入固定门禁。

安全

外部Runtime、单Writer、凭据隔离和分级授权降低风险。

业务闭环

从需求、接口和数据库一直验证到业务副作用和用户展示。

可追溯

完成结论绑定代码、测试、数据库、MR或页面证据。

可复制

角色、脚本、指标和Gotcha沉淀为下一任务资产。

07｜Ruflo还是常规Codex

常规 Codex

最短执行路径

单文件或小范围修改
接口契约明确
低数据和兼容风险
一个上下文可完整验证

Ruflo + Codex

可控的复杂协作

跨仓库或共享契约
硬件、身份、权限、支付、同步
旧功能兼容和数据迁移
多角色门禁和完整业务闭环

项目已启用自动路由：Codex按复杂度、代码质量风险、兼容性、业务闭环和角色价值自动选择，不再要求人员先决定工具。

08｜团队成员最小使用路径

拉取最新zhctprompt/master并安装项目Skills。
从zhct工作区提交任务，Codex先给出执行模式和依据。
命中Ruflo后创建任务包和task-metrics.csv。
指定正式仓库之外的Runtime，登记3—7个角色。
映射真实Codex工作单元，保持单Writer并执行TDD。
通过独立Review Gate，停止daemon并检查环境残留。
由人决定是否提交、合并、部署和现场验收。

入口	项目路径
自动路由	`task-execution-mode-router/SKILL.md`
Ruflo执行	`ruflo-isolated-task-harness/SKILL.md`
治理流程	`RUFLO_ISOLATED_TASK_HARNESS_WORKFLOW.md`
任务初始化	`bootstrap_isolated_ruflo.sh`
角色登记	`register_ruflo_ledger.sh`

09｜用数据回答“值不值”

准备与周期

准备时长、Review Gate总周期。

返工与缺陷

返工轮次、合并前后缺陷、缺陷前置率。

AI成本

输入、输出、缓存和总Token；不可回读写n/a。

Memory价值

搜索、命中、采用、有效和命中率。

兼容与覆盖

正常、异常、恢复、历史和旧系统回归。

环境残留

daemon、临时目录和用户级配置污染。

10｜成本和边界也必须讲清楚

Node/npm、Runtime、缓存和实验克隆增加环境成本。
多角色会增加Token、重复阅读和交接成本。
CLI状态可能与JSON账本不一致，角色登记也不会自动执行代码。
初始化和状态命令可能启动daemon，退出必须清理。
小任务套完整Harness可能比直接开发更慢。
没有对照数据时，不宣称固定百分比提效。

11｜建议的40—50分钟分享节奏

5分钟

定位与三条核心认知

8分钟

四层架构、五角色和单Writer

12分钟

上禾业务链和关键缺陷案例

8分钟

隔离Runtime、任务与证据演示

7分钟

自动选型、指标和团队使用

5—10分钟

问答

12｜常见问题

Ruflo能替代Codex吗？

不能。Ruflo负责协调，Codex负责真实执行。

Agent越多是不是越快？

不是。只有边界清晰、可独立验收的工作才适合并行。

Ruflo显示完成，能直接合并吗？

不能。必须有工程证据，并保留人工提交、合并和发布门禁。

每个任务都必须用Ruflo吗？

不用。小任务走常规Codex，复杂高风险和强闭环任务才走Ruflo。

最后一句

常规Codex解决“快速完成一个明确任务”；Ruflo解决“如何让复杂AI研发协作不失控，并且结果可验证、可追溯、可复用”。