Ruflo驱动上禾体检一体机接入：过程报告
版本：V1.0
汇报日期：2026-08-26
汇报对象：管理团队、产品与研发负责人
一、管理结论
上禾SH-V20体检一体机接入，是康比特首次将开源Agent Meta-Harness用于真实硬件研发任务的完整试点。
本次使用Ruflo管理角色、任务、依赖和过程证据，由Codex工作单元真正执行代码分析、开发、测试和评审。最终验证：Ruflo适合复杂、多角色、高风险研发任务的过程治理，但不能替代Codex执行、Git状态、自动化测试、数据库回读和人工发布审批。
试点最重要的价值不是“启动更多Agent”，而是把原本容易串行、遗漏或口头化的研发过程，固化为：
需求冻结 → 多角色并行取证 → 单Writer实现 → TDD验证
→ 独立Review Gate → Git/云效关联 → 开发库回读 → 全面兼容回归
二、为什么选择这个任务试点
上禾接入同时涉及：
- 厂家V3.06协议与双鉴权模式；
- 手机号会员匹配；
- 测量报告补传、幂等和数据库唯一性；
- 体重档案、员工身高体重、积分、推荐能量等既有业务；
- 阿里云/本地附件存储；
- 小程序体重档案展示；
- 沃莱、云康宝、宅客、BC300、跳绳、英吉多等旧设备兼容；
- store PHP7.3、ai_api PHP7.4双运行时；
- SQL、接口、设备和现场验收多重门禁。
它具备复杂任务试点所需的典型特征：跨系统、跨角色、规则多、错误成本高、需要保留完整证据。
三、Ruflo与Codex的分工
官方Codex Agent指南明确：Ruflo是协调账本，Codex是执行者。
| 组件 | 本次职责 | 不承担的职责 |
|---|---|---|
| Ruflo | 登记角色、任务、分配、状态和memory实验 | 不自动写代码、不自动跑测试 |
| Codex | 读协议和源码、实现代码、运行测试、审查和修复 | 不拥有业务规则最终解释权 |
| Git/数据库/测试 | 提供真实状态和验收证据 | 不替代业务确认 |
| 人 | 决定业务规则、授权提交、合并、部署和现场验收 | 不把Agent状态当作完成证明 |
四、五角色协作模型
本次建立5个岗位、5项任务和5个分配关系：
| 角色 | 核心职责 | 权限 |
|---|---|---|
| Coordinator | 维护依赖、进度、停止条件和交付门禁 | 不写业务代码 |
| Evidence | 读取协议、源码、数据库和旧设备证据 | 只读 |
| Writer | 负责唯一业务实现 | 单一worktree唯一写入者 |
| Tester | 设计正常、异常、补传、幂等和兼容矩阵 | 只读设计/独立测试范围 |
| Reviewer | 审查正确性、架构、安全、兼容和发布条件 | 只读 |
“一个worktree一个Writer”是本次最关键的冲突控制规则。研究、测试设计和审查并行，业务代码只由一个明确责任人写入，避免多Agent同时修改同一代码。
五、全过程
阶段1：任务冻结
先形成对接方案、问题清单和实施计划，确认：
- 会员按手机号
userID匹配； - Token和无Token两种模式兼容；
datas[]兼容单条和多条；recordNo标识报告；- 补传需要合并整份报告；
- 同日跨来源体重只加一次积分；
- 历史补传不刷新当天推荐能量；
- 最新实际测量更新员工身高体重；
- 第一期不建设人工待匹配页面。
阶段2：隔离初始化
Ruflo运行时、缓存、memory和业务实验克隆均放在正式仓库之外。初始化时关闭Codex自动检测、全局注册和云服务，避免污染用户级配置。
试点中真实发现：默认初始化可能写入用户主目录、增加Codex MCP配置，并自动启动daemon。团队随后增加了目录前后态检查、精准回退和daemon退出清理。
阶段3：并行取证
Evidence、Tester和Reviewer并行完成：
- V3.06相对V3.04协议变化；
- 网络恢复后整份报告补传语义；
- 现有宅客、BC300、沃莱、云康宝业务链路；
- 体重、员工、积分和推荐能量逻辑；
- 数据表容量、唯一键、门店上下文和无效会话风险；
- 小程序体重档案现有查询和字段映射。
阶段4：TDD实现
开发按小切片推进：
RED失败基线 → 最小实现 → GREEN → 回归 → 证据 → Review Gate
先实现纯协议映射，再实现数据库迁移、设备鉴权、手机号匹配、报告合并、附件存储和体重业务。每次新增行为都有对应契约测试或数据库烟测。
阶段5：独立评审
Reviewer没有直接接受首版，而是连续发现并关闭：
- 设备回调缺少门店上下文；
- 已匹配报告可能被错误降级或改绑；
- 完全重复报文仍可能重复触发副作用；
- 历史补传可能覆盖最新员工档案；
- 小程序
body_type/obesityDegree字段不一致； - 正式SQL放错仓库；
- store测试误用PHP7.4语法；
- 数据库触发器带来的隐蔽运维风险。
阶段6：全面回归
软件回归覆盖：
- Token、无Token和错误码；
- 手机号匹配、未匹配隔离；
- 单/多
datas[]； - 部分报告、整份补传和完全重复；
- 体重、员工、积分和推荐能量；
- 阿里云附件上传、复用和清理；
- 小程序日期、体重和体成分字段；
- 沃莱、云康宝、宅客、BC300、跳绳、英吉多；
- Activity和Meal统一健康数据读取；
- store PHP7.3与ai_api PHP7.4。
阶段7：触发器改为代码维护
试点过程中，管理者提出“数据库触发器一旦失效，问题难排查”。团队没有坚持原方案，而是：
- 让7个健康指标写入入口显式维护
segment_key； - 从开发库删除两个触发器；
- 在无触发器状态下重跑上禾和全部旧设备；
- 保留数据库唯一索引作为并发重复保护；
- 让逻辑回到代码，可测试、可审查、可定位。
这体现了Harness的核心价值：不仅生成代码，还能把人工审查意见快速转换为受验证的系统改进。
阶段8：正式协同
需求和开发任务写入云效，分支、提交、MR、测试和工时形成关联。上禾代码已从开发评审进入develop_haerbin，并继续合入release。
六、关键门禁
| 门禁 | 规则 |
|---|---|
| 业务 | P0规则不清楚时停止，不由AI猜测 |
| 目录 | Ruflo Runtime不得位于正式仓库或用户主目录 |
| 写权限 | 一个worktree只有一个Writer |
| 数据库 | 先预检结构与重复数据，再执行DDL |
| 安全 | 密钥、密码、真实手机号和原始敏感报文不进Git/memory |
| 兼容 | 上禾通过不等于完成，必须回归旧设备和小程序 |
| Git | commit、push、MR、merge和deploy分别授权 |
| 发布 | 本地/开发库通过不等于真实设备或生产验收 |
七、过程收益
1. 风险更早暴露
数据库容量、报告补传、门店上下文、历史体重、小程序映射和旧设备兼容，均在正式发布前被发现并关闭。
2. 并行但不乱写
证据、测试和评审可以并行；代码只有一个Writer，兼顾速度和责任边界。
3. 质量可证明
完成状态由代码、测试、数据库和MR证明，而不是由Agent“自报完成”。
4. 人工意见能进入闭环
SQL归属、PHP版本、触发器等人工反馈均转成代码、测试和回归证据，没有停留在口头要求。
5. 可复制资产形成
已沉淀隔离bootstrap、角色登记、Workflow、Skill、测试门禁和试点证据，后续复杂任务可复用。
八、过程中的不足
- Ruflo CLI的任务列表曾与JSON状态不一致；
- Agent登记后不会自动执行，必须映射真实Codex工作单元；
- 初始化与状态命令可能自动启动daemon；
- memory首轮有效性较低，尚未证明能稳定降低重复劳动；
- 当前没有“不使用Ruflo”的同任务平行基线，不能宣称节省了固定百分比工时；
- 多角色组织对小任务可能得不偿失。
九、建议
- Ruflo继续保持“复杂任务试行”，不设为全部研发默认。
- 再选一个跨仓库中型任务复用，量化准备时间、总周期、返工、缺陷发现和Token成本。
- 角色控制在3—7个，只为真正可并行的职责增加Agent。
- 保留单Writer、独立Reviewer、TDD和人工发布门禁。
- memory只保存已验证模式，第二次试点后再决定是否升级为团队推荐能力。
新增强制规则：每个Ruflo任务从启动起维护task-metrics.csv，统一统计准备时长、总周期、返工、缺陷前置、Token和memory命中；Review Gate前必须通过校验，观察期结束后补齐最终缺陷前置率。
十、一句话总结
Ruflo没有替代开发人员，也没有自动完成上禾接入；它把Codex多角色研发变成了一套有职责、有门禁、有证据、可复盘的工程流程，使复杂硬件对接更早发现风险、更少依赖口头协作，并形成可复用的团队能力。
证据边界
- Ruflo官方定位来自开源仓库、官方Codex Agent指南和npm包信息，属于外部方法证据。
- 上禾过程、代码、测试、数据库和MR来自康比特本地与Codeup真实执行证据。
- 效率收益已体现为并行协作和返工前置，但尚未形成对照实验，不写虚构百分比。