2026/10/22

WorkFlowX：AI 多智能体开发工作流的设计与分析

知识库

WorkFlowX：AI 多智能体开发工作流的设计与分析

本文由旧稿《Harness Design X_x》重维护，并入 llmWikiX 条目（原为空占位，主题「让 AI 维护 Note」在第四节展开）。分析对象：TreeX-xx/WorkFlowX —— 一个更强调可控、可追踪和 Token 效率的 AI 多智能体开发工作流。

一、它是什么

WorkFlowX 是一套放进 AI 编程工具（Claude Code / OpenAI Codex）里的工程化工作流：你仍然只和一个主代理对话，但它不再「边聊边写」，而是有规划、有验收、可追踪。

三个关键词：

纯文件驱动——所有状态落在仓库文件里（skill、agent 定义、.agents/notes/ 文档），没有服务、没有数据库，可 git 追踪、跨工具迁移；
质量门独立——实现者自述完成不算数，独立评估者按固定验收标准建测试实跑，给出 PASS / NEEDS_FIX / UNEVALUABLE；
Token 效率——单文件归位、链接代替内联、最小上下文派发，多轮迭代不把全部历史塞进每次请求。

二、设计源起：从 Harness Design 角色流说起

WorkFlowX 的思想起点是面向长运行应用的 Harness 设计（参考 StaticFlow 的 Harness Design）。早期形态是四个角色构成的全栈工作流：

角色	职责要点
Planner	倾听与扩展（模糊提示 → 完整规格）、选项驱动（2-3 个方案交用户选）、如实记录（不脑补需求）、高维视角、严禁过早深入实现细节
Generator	KISS 原则（如无必要勿增实体）、即时自省（对照评分标准自评）、状态归档与前瞻
Evaluator	一票否决的硬性阈值、动静结合多维审查（动态测试 + 静态审查）、闭环反馈驱动（结构化反馈报告逼着重做，直到通关）
Abstracter	由面到点结构化降维（全局→主线→细节）、高信噪比标准化交付、基于事实的严谨考证（有一分代码说一分话）、质量风险洞察、面向决策的闭环建议

其中一条关键约定：Planner 与 Evaluator 必须持有同一份评分标准——规划时定义的验收，就是评审时的判据，不允许两套口径。示例评分维度（设计质量 / 原创性 / 工艺 / 功能性）沿用至今，演化为 task note 里的固定 AC。

现行 WorkFlowX 保留了这套理念，但把「角色流水线」重构为「Main Agent 直接编排 + 按需委派」：不再有独立的 orchestratorX 子代理，planner 的规划职责由 Main Agent 承担，Abstracter 的沉淀职责交给 noteX / proseX 文档维护。

三、核心架构

3.1 三种模式

按改动影响范围选模式，拿不准时 Main Agent 摆出三选一，不悄悄代选：

模式	适用场景	规划方式	验收循环
xdo	清晰的日常工作	主 Agent 直接工作；普通工作不创建 Task，原位维护相关文档	主 Agent 自审验证
xdel	单 task 可追溯委托	基于已接受范围的 Task，单次派发 coderX	不触发评估链，带回 Note 草稿
xflow	新功能、跨模块重构、高影响任务	仓库发现 → socratesX 澄清 → Ready Summary → task notes，按依赖派发	每个 task 后 evaluatorX 独立评估，局部缺陷默认最多一次最小修复重派发

3.2 角色分工

用户 ── xdo / xdel / xflow / xstatus
        │
        ▼
Main Agent（编排 + 文档维护）
   ├─ orchestrateX 路由（显式命令优先；模式模糊就问）
   ├─ xdo：直接工作，engineeringX 自审
   ├─ xdel：单次委托 coderX（engineeringX + specX），不触发 evaluatorX
   └─ xflow：发现 → 澄清 → Task → 派发 → 独立评估
          ├─ coderX：单 task 实现，输出 Change Summary + Note 草稿
          └─ evaluatorX：按固定 AC 建最小测试集并实跑（只读不改）

配套 skill：orchestrateX（路由编排）、socratesX（xflow 前置澄清）、engineeringX（实现原则与自审）、specX（coderX 契约阅读）、auditX（评估）、noteX + proseX（文档资产与写作标准）。

3.3 一次 xflow 的生命周期

仓库事实探索——先读代码再问人，避免凭空澄清；
socratesX 分批澄清——只问未决问题，经 Ready Summary 确认后才建 note；
Task note 承载契约——范围 / 固定 AC 引用 / 验证入口 / 进展 / 证据 / 交接同处一文件；
最小派发——派发包只带相关契约、文件、失败与风险，不回传完整历史；
独立评估——evaluatorX 不信任 coderX 自述，建最小有用测试集实跑，逐条 AC 标记；
分级修复——失败用例 + 观察结果 + 修复范围 + 回归风险打成 Repair Packet，最多一次自动重派发；
文档落地——按实际变化维护模块与 Note，无事实变化不制造更新。

四、知识沉淀：让 AI 维护 Note（harness-note 体系）

这是 WorkFlowX 区别于同类框架最深的一层——工程记忆是第一等公民。

4.1 .agents/notes：六类文档

.agents/notes/
├─ module.md              module：项目入口
└─ <模块>/
   ├─ module.md           module：模块入口（每模块恰好一份）
   ├─ <主题>.md           note / idea / requirement / decision / task
   └─ tasks/              交付中的任务

类型	拥有什么	正文契约
module	整体设计	解释全貌并链接细节，不逐条复制子文档事实
note	独立可用的细节	标题自由，一个 H1
idea	探索	Intent（意图）
requirement	预期行为	Acceptance criteria，稳定 `AC-n` 编号（编号永不重排）
decision	决策理由	Problem / Decision / Alternatives / Consequences
task	有界交付	Scope / AC / Verification / Progress / Evidence / Handoff

4.2 维护纪律

身份稳定：UUID 标识文档，文件名只描述主题（不带日期前缀）；改路径、转类型不丢身份——一篇持续演进的 Idea 可以原地转成 Requirement 或 Decision；
原位维护：同一主题就地更新，不为每轮讨论另开新 Note；独立职责出现才新增文档或子模块；
时间纪律：created 是真实日历日，updated 每次维护写刷新（UTC RFC3339）；只读访问和无事实变化的 no-op 不刷新；
合并/拆分/删除有账：合并保留一个延续身份并修复引用；删除要把吸收的事实、引用、证据结清，不立永久墓碑；
主 Agent 负责：文档整理、合并、清理与引用修复是 Main Agent 的职责，子智能体只读 Task、返回 Note 草稿。

4.3 Wiki 与蓝图共用 Note

工程 wiki 直读 Note 原文，正式关系与正文引用分开，反链由索引可重建地派生；知识 wiki 记录实际读取的 Note 来源及哈希——引用不悬空、来源可考证。

五、关键设计决策分析

1. 纯文件驱动，而不是服务/数据库。 状态即仓库文件，带来三个连锁收益：git 历史天然成为审计日志；换宿主工具只需拷贝配置目录；「下一位 Agent 从仓库资产接续，不依赖原聊天历史」——连续性来自文档，不是会话窗口。代价是文件格式必须严格（harness-note/2 的 schema 与校验脚本就是为此存在）。

2. 评估员不信任程序员。 这是把「AI 说完成了」变成「独立质量门确认完成了」的核心机制。三个细节值得称道：固定 AC 引用（验收标准不许临场改）；最小有用测试集（不为覆盖率跑全量）；UNEVALUABLE 显式态（无可运行测试路径时如实报「评不了」，绝不谎称通过）。

3. Token 三层优化。 L1 单文件归位（一处事实只读一处）；L2 链接代替内联（URI + 一行摘要，不贴长文）；L3 最小派发（修复包只带失败测试、相关文件、接口约束与风险摘要）。多轮迭代的成本主要烧在重复携带历史上，三层分别砍向「翻文档」「贴文档」「传历史」。

4. 需求澄清前置。 xflow 先做仓库事实探索、按阶段批量澄清、Ready Summary 确认后才建 note——把「编码后才发现需求误解」这个最贵的返工挡在写代码之前。而 xdo 明确不调用 socratesX：小事不逼问，「能不能/我想/帮我」就是执行令。

5. 并发不靠锁。 无全局锁；派发前做同目标冲突检查，支持时用 worktree 隔离，加上 task 责任边界。并行永远不隐式触发——由用户明确要求，调度与集成收口归 Main Agent。

六、评价与思考

优势：同类框架（Superpowers、OMC 等）多在「让 AI 更会写代码」上竞争，WorkFlowX 押注的是「让 AI 的产出可被验证、过程可被追溯」——模块文档 + Task 追踪 + 测试驱动独立验收是它独有的两块；对长周期、多会话、多人/多代理接续的工程尤其有感。

代价：文档纪律有学习曲线——六类文档、稳定 AC、时间戳规则，初用会觉得重；它的回报在第三次会话之后（记忆还在）而不是第一次。另外整套机制依赖模型的指令遵循能力，弱模型下规范容易流于形式。

适用判断：一次性脚本、探索性 spike 不必上它；需求会持续演化、要跨会话续作、要让另一个代理/另一个人接手的工程，它的价值最大。

七、上手

# Claude Code
/plugin marketplace add https://github.com/TreeX-xx/WorkFlowX
/plugin install workflowx

# 第一条需求
xdo 给 Config 加超时配置

OpenAI Codex 用自然语言前缀触发（xflow 实现订单中心）。Node.js 18+ 即可，无其他运行时依赖。

参考：TreeX-xx/WorkFlowX（MIT）· 公众号 TreeX-AI