1. 引言
ruvnet/ruflo是一个用 TypeScript 实现的元 harness（meta-harness），目标是解决一个越来越普遍的问题：当单个编码 Agent（如 Codex、Claude Code）能力有限时，如何把多个 Agent 组织成一支有记忆、会学习、能协同的 swarm，去完成更复杂的自主工作流和对话系统。
它并不重新发明底层模型，而是把 Codex、Claude Code 这类编码智能体包裹在一层统一的调度与协作框架之下，向上提供自适应记忆、自学习策略与联邦通信原语三块能力。换句话说，ruflo 关注的不是“一个 Agent 能写多少代码”，而是“一群 Agent 如何像团队一样持续地、可靠地协同工作”。
2. 为什么需要“元 harness”
单个 coding agent 在实际生产中会遇到三类明显瓶颈：
- 上下文边界：一个长任务往往需要多轮修改、多文件协作，单一会话的上下文很容易被淹没，导致“越改越偏”。
- 策略固化：大多数 agent 使用固定 prompt 和固定流程，缺少对不同任务类型、不同失败模式的自我适配。
- 通信缺失：多个 agent 并行工作时，如果没有统一的通信协议，就会各自为战，产生冲突、重复劳动或状态不一致。
ruflo 的思路是把这些问题从业务逻辑中剥离出来，下沉到一个可复用的 harness 层。开发者只关注“要完成什么任务”，而“如何记忆、如何调度、如何通信、如何从失败中学习”交给 ruflo 统一处理。
3. 架构总览
从整体上看，ruflo 处于“用户任务”与“底层 Agent 执行器”之间，形成一条完整的编排链路：
这里的核心设计是：Agent 不再是“应用”，而是“可被编排的资源”。ruflo 通过策略层决定何时启动、暂停、拆分或合并 Agent 任务，通过记忆层维护跨会话的上下文，通过通信层保证并行 Agent 之间可以交换信息和达成一致。
4. 三大核心能力
4.1 自适应记忆
自适应记忆解决“跨会话遗忘”问题。它不会把所有历史无条件塞进上下文，而是根据当前任务的相关度，动态检索和注入最有价值的记忆片段。
典型工作方式包括：
- 记录每个 Agent 的历史行为、成功经验与失败原因；
- 根据新任务的语义相似度检索相关记忆；
- 按重要性与时效性对记忆做衰减或淘汰，避免上下文过载。
这样，后续任务可以站在前序任务的“经验”上继续，而不是每次从零开始。
4.2 自学习策略
自学习策略让 orchestration 本身具备进化能力。ruflo 会把一次任务的执行过程视为可观测、可评估的样本：
- 观察不同策略下的成功率、耗时、Token 消耗；
- 对策略进行评分与调优，例如调整并行度、拆分粒度、重试上限；
- 在遇到反复出现的失败模式时，自动插入修正步骤或切换备用 Agent。
它不是在模型权重层面做训练，而是在编排策略层面做经验积累，成本更低、反馈更快，也更容易被人审阅和调整。
4.3 联邦通信原语
多 Agent 协作最容易出问题的地方在通信。ruflo 提供一套统一的联邦通信原语，让不同 Agent 之间可以：
- 发布与订阅：某个 Agent 产出中间结果后，通知依赖该结果的其它 Agent；
- 请求与应答：Agent 间按需查询上下文或确认状态；
- 协商与共识：对冲突的修改结果进行合并、裁决或回滚。
这些原语屏蔽了底层 Agent 的差异，使得 Codex、Claude Code 乃至未来接入的新执行器，都能使用同一套协作语义。
5. 包在 Codex / Claude Code 外层意味着什么
ruflo 的一个重要定位是“套在 Codex / Claude Code 外层”，这带来两个好处：
- 保持底层 Agent 的独立性：Codex、Claude Code 仍然负责它们擅长的编码、执行与工具调用，ruflo 不侵入它们的内部实现。
- 统一编排与治理：任务的拆解、调度、记忆、通信和策略学习都发生在 harness 层，底层 Agent 可以随时替换或混合使用。
这种分层让系统具备了良好的可演进性：底层 agent 能力持续升级，上层编排策略可以独立迭代，业务方无需重写工作流。
6. 场景一：自主工作流
在自主工作流场景中，ruflo 接收一个高层目标，例如“为仓库实现某个 feature 并补齐测试”，然后内部完成：
- 意图解析与任务拆分；
- 将子任务分配给合适的 Agent；
- 多 Agent 并行处理不同模块；
- 通过通信原语同步依赖与冲突；
- 通过记忆与策略学习优化后续执行。
整个过程不需要人工逐步下达指令，只需在关键节点做确认或审阅，即可让 swarm 持续向前推进。
7. 场景二：对话系统
在对话系统场景中，ruflo 的价值体现在“对话”与“执行”的统一：
- 用自适应记忆维护长期用户画像与上下文，而不是只依赖单轮输入；
- 用策略层决定何时直接回答、何时调用工具、何时派发 coding agent 执行真实任务；
- 用通信原语协调对话意图识别、任务执行与结果汇总等多个 Agent。
这样构建出的系统，不仅能聊天，还能在聊天过程中真正把任务落地，形成“对话即编排、编排即执行”的体验。
8. 快速上手示例
下面的示例展示一个概念性的最小用法：创建一个ruflo编排环境，注册 Codex 与 Claude Code 两个执行器，然后下发一个高层任务。
import{createHarness}from"ruflo";constharness=createHarness({memory:{mode:"adaptive",relevanceThreshold:0.75,},strategy:{selfLearning:true,scoreKeepers:["successRate","latencyMs","tokenUsage"],},});// 注册底层编码 Agent 执行器harness.registerExecutor({id:"codex",kind:"codex",capabilities:["coding","refactor","test"],});harness.registerExecutor({id:"claude-code",kind:"claude-code",capabilities:["coding","review","terminal"],});// 通过联邦通信原语订阅中间结果harness.subscribe("artifact:ready",(message)=>{console.log("有新的中间产物就绪：",message.subject);});// 下发一个高层自主任务constsession=awaitharness.run({goal:"为 utils/retry.ts 补充单元测试，并修复发现的边界问题",mode:"autonomous",});forawait(constupdateofsession.updates){console.log(`[${update.agent}]${update.status}:${update.summary}`);}说明：以上 API 为概念性示意，实际字段与调用方式请以
ruvnet/ruflo仓库文档为准。
8.1 实战：多Agent协作示例
下面这个示例展示 ruflo 如何协调 Codex 与 Claude Code，让前者负责生成函数实现，后者负责审查优化并补充测试。代码仍以概念性 API 示意，实际字段请以仓库文档为准。
import{createHarness}from"ruflo";// 1. 定义任务：Codex 负责生成 normalizePrice 函数，// Claude Code 负责审查、优化并补充测试。consttask={id:"build-normalize-price",title:"实现并优化 normalizePrice 函数",spec:["接收可能为 string、number、null 或 undefined 的原始价格；","将输入统一转换为以元为单位、保留两位小数的 number；","无法解析的输入应返回 null。",].join("\n"),acceptance:["支持处理 '1,234.56'、'￥199.00'、'199.0' 等字符串","正确处理负数、大数，避免浮点精度问题","空值和非数字输入返回 null",],steps:[{id:"generate",agent:"codex",instruction:"根据 spec 生成 normalizePrice 函数实现",publish:"artifact:ready",// Codex 完成后发布事件},{id:"review",agent:"claude-code",subscribe:"artifact:ready",// Claude Code 监听 Codex 的产出instruction:"审查并优化函数实现，补充边界测试与注释",publish:"review:complete",// 审查完成后发布最终结果事件},],};// 2. 创建 harness，开启自适应记忆与自学习策略constharness=createHarness({memory:{mode:"adaptive",// 根据任务语义动态注入相关记忆relevanceThreshold:0.7,},strategy:{selfLearning:true,// 允许编排策略根据执行结果自我调优scoreKeepers:["successRate","latencyMs","tokenUsage"],},});// 3. 注册两个底层 Agent 执行器harness.registerExecutor({id:"codex",kind:"codex",capabilities:["generate-code","implement-function","write-tests"],});harness.registerExecutor({id:"claude-code",kind:"claude-code",capabilities:["review","optimize","refactor","test"],});// 4. 通过联邦通信原语订阅关键事件，观察协作进度harness.subscribe("artifact:ready",(message)=>{// Codex 生成代码后触发，harness 会把消息转发给订阅者console.log(`[协作进度] Codex 已生成代码：${message.artifact.path}`);console.log(`[协作进度] 下一步：Claude Code 将根据该产物进行审查`);});harness.subscribe("review:complete",(message)=>{// Claude Code 完成审查时触发console.log(`[协作进度] Claude Code 已完成审查：${message.review.summary}`);console.log(`[协作进度] 发现${message.review.issues.length}个需要关注的问题`);});// 5. 下发任务并处理最终结果constsession=awaitharness.run({goal:task.title,mode:"collaborative",// 以多 Agent 协作模式运行task,});// 轮询或迭代 session 更新，直到任务结束forawait(constupdateofsession.updates){console.log(`[${update.stepId}]${update.agent}->${update.status}:${update.summary}`);}// 6. 从结果中取回最终函数与审查报告constresult=awaitsession.result;console.log("最终生成的 normalizePrice 函数：");console.log(result.artifacts.normalizePrice.code);console.log("Claude Code 的审查意见：");for(constnoteofresult.review.notes){console.log(`- [${note.severity}]${note.detail}`);}9. 总结
ruflo 的价值可以概括为一句话：把“多个编码 Agent”从一堆孤立工具，升级为一支有记忆、会学习、可通信的自主团队。
它通过 TS 元 harness 这一轻量又不失表达力的抽象，把自适应记忆、自学习策略和联邦通信原语组合起来，套在 Codex、Claude Code 等成熟执行器外层。无论你要构建的是长时间运行的自主工作流，还是需要边聊边干的对话系统，都能借助这套编排层获得更稳定、更可复用、更容易演进的实现基础。
如果你正在被多 Agent 的上下文、协调和策略管理困扰，ruflo 提供了一条值得关注的工程路径。
