《互联网产品的 AI 架构·多能力编排与任务闭环》前言

这一卷解决什么问题

卷一回答「一个能力的边界在哪」，卷二回答「同样边界下怎样更便宜更快」。卷三面对的是另一个问题：多个能力怎样协同完成一个任务。

这个问题不是把前两卷的结论相加就能解决。单能力优化的是节点，多能力优化的是边。边的成本、状态与失败，在节点视角下不可见。

卷三的十三章围绕三条边展开：能力之间传什么，上下文复用到什么程度，失败如何沿链路传播。每一章至少给出一个可运行模块、一组确定性数据、一份带取舍的 ADR，或者一条可判定的编排判据。

全书结构如下。

前三章建立结构与契约，第 3–6 章处理执行、状态、失败与并发，第 7–8 章做验收与成本，第 9–12 章补安全、观测、平台与演进，第 13 章收口。

十三章的一条主线

十三章不是十三个孤立话题，而是一条从「连接」到「治理」的线。

结构   1 编排问题与结构
        │
契约   2 编排契约与数据流
        │
执行   3 执行图与调度 ── 4 上下文与状态
        │                    │
失败   5 失败传播与部分结果 ── 6 并发、人工与异步
        │
验收   7 编排的质量验收 ── 8 编排的成本与预算
        │
安全   9 编排的权限与安全
        │
观测  10 编排的观测与运维
        │
平台  11 编排平台化 ── 12 演进与边界
        │
收口  13 卷三收口

读图的方式：

• 第 1、2 章是地基。结构没定，契约没定，后面的成本与失败分析没有对象。
• 第 3、4 章把编排从文字变成图与状态，是所有可运行模块的核心。
• 第 5、6 章处理「不顺利」的情况，决定编排能不能上线。
• 第 7、8 章回答「怎么证明它值得」，把质量与成本放在同一张验收表上。
• 第 9–12 章把单条编排扩展成多团队可用的平台。
• 第 13 章不再引入新概念，只把前面的判据收成基线。

箭头不是严格的前置依赖。第 5 章可以单独读，第 9 章也可以先看。但跳过第 1、2 章直接做平台化，通常会得到一套无法验收的抽象。

每章的四段式

每一节保持相同结构，便于对照，也便于团队分工。

1. 问题与判据：这一节回答什么问题，什么算达标，判据能不能被测试。
2. 机制与取舍：为什么这样设计，代价是什么，备选方案为什么不选。
3. 可运行片段：ai-lab 中的模块与测试，展示判据如何落成代码。
4. 边界与错误：什么时候不适用，常见误用是什么。

每章第三节固定是实验章：把前两节的判据合成一个可运行的检查、报告或基线。

四段式不是形式主义。它强迫每一节都回答三个问题：判据是什么，代价是什么，怎么验证。缺任何一项，这一节就退化成了概念介绍。

实验工程：src/orch 模块地图

卷三沿用卷一、卷二的 ai-lab 工程，新增 src/orch/。

模块之间可以互相引用，也可以引用卷一、卷二的 src/core/、src/gateway/、src/perf/，但不修改它们。

所有新增代码只用 node: 内置模块，零第三方依赖。本地导入带 .ts 后缀，测试放在 test/orch/ 下。

三级可运行性

沿用前两卷的分级。

卷三以 L1、L2 为主，并明确不承诺 L3。

不承诺 L3 有三层含义。第一，书里的模型调用由 mock 提供方模拟，延迟与失败率是可配置参数，不是真实供应商的表现。第二，下单、退款、发券等外部动作全部是模拟器，不连接任何真实业务系统。第三，权限、幂等、审计与回滚只做到进程内可验证，不覆盖真实组织的账号体系与审批流程。

这不是回避工程复杂度，而是把可复现的部分写死，把与具体环境强绑定的部分留给读者。L1、L2 能验证判据是否成立；L3 才能验证你的系统是否真的适合这套判据。

代码块的三行头

每个 TypeScript 代码块以三行注释开头。

// file: src/orch/workflow-shape.ts
// tier: L1
// verify: node --test test/orch/workflow-shape.test.ts

三行的含义：

• file 是相对 ai-lab 的路径，正文代码块与该文件逐字节一致。
• tier 标明该文件的最低验证级别，L1 或 L2。
• verify 给出可复现的验证命令。

这样做的好处是：书里的每个片段都能在工程里找到原文，改一处必须同时改两处，避免「书上能跑、仓库里跑不了」。

卷三的大部分代码是 text 或 sh 块，用来说明结构、命令与输出。需要展示实现时才会出现 ts 块，且必定带三行头。没有三行头的 ts 块视为错误。

案例「回声」的三条链路

「回声」是内容社区 + 私信 + 轻交易的组合产品。卷三用它的一条客服任务贯穿全书。

这条任务有三种典型链路。

单跳问答最短，也最容易被当成「已经会了」。它仍然有编排问题：检索与重排是两个能力，交接时传的是完整文档还是摘要，直接决定回复质量与成本。

多跳任务把上下文衰减暴露出来。第一跳检索到的政策原文，经过摘要、判断、回复三次转手，条件可能被逐层简化。第 4 章会用共享上下文与节点预算处理这个问题。

动作闭环最难。答复说「可以退」之后，退款动作可能因为权限、库存、风控失败。此时用户已经看到承诺，系统却无法兑现。第 5 章的部分结果与第 9 章的动作授权，都是为这一类失败准备的。

三条链路共用同一个成本模型、同一套失败分类与同一份追踪字段。这也是卷三的组织方式：案例不变，链路逐步变复杂。

数字口径

书里的数字遵循统一口径。

• 成本单位是整数微元；延迟单位是毫秒；成功率与复用率必须写明分母。
• 平均延迟必须与 p95 一起出现；只给平均值视为不完整。
• 成本对比必须写明对照基线与统计窗口。
• 模拟数据必须标注「示例样本上的运行结果」。
• 没有测量就写「需要实测」，不用「约」「大概」掩盖。

贯穿全书的基准数字如下。

这些数字来自三能力示例样本，不是生产实测。换一套 token 结构或单价，绝对金额会变；回本线与失败预算的算法不变。

阅读节奏建议

十三章、三十九节，不必一次读完。一个务实的节奏是每周一章。

八周是参考，不是承诺。只有一条链路时，可以压缩到三周；跨团队、多租户时，可能更久。节奏可以调，顺序尽量别跳：结构与契约是所有后续动作的地基。

三条阅读路径

按问题选路径。

1. 建设路径：1.1 → 2.1 → 2.2 → 3.1 → 3.2 → 4.1 → 4.2 → 5.1 → 7.1 → 8.1 → 13.1。适合第一次把多个能力串起来。
2. 排障路径：5.1 → 5.2 → 5.3 → 7.2 → 7.3 → 10.1 → 10.3。适合线上已经出现「整条链路失败但不知道是哪个节点」。
3. 平台路径：3.1 → 9.1 → 10.2 → 11.1 → 11.3 → 12.1 → 12.2 → 13.1。适合把一条编排复制给多个团队。

三条路径可以交叉。排障时如果发现契约缺失，回到第 2 章；平台化时如果发现失败语义不清，回到第 5 章。路径是入口，不是轨道。

如果只读一章，读第 2 章。交接契约决定了后面所有成本、状态与失败分析有没有对象。

怎么验证书里的代码

每个代码块都能在 ai-lab 中找到同名文件。验证分三步。

1. 按代码块头部的 // verify: 命令运行单模块测试。
2. 用 node --test 跑 test/orch/ 全量，确认改动没有破坏其他章节的假设。
3. 对照正文数字，确认它们来自测试输出而不是手工填写。

三步有任何一步对不上，以脚本输出为准。书是静态的，脚本是活的。

书中不提供「复制到生产就能用」的完整服务。实验工程刻意省略了持久化、鉴权、真实供应商连接、订单系统对接与部署配置。这些部分与具体环境强绑定，写进书里会很快过期，也会让读者误以为照抄即可上线。

如果你的运行结果与书中不同，先检查三件事：Node 版本是否一致，单价参数是否一致，统计分母是否一致。三者都一致仍然不同，那可能是一个值得记录的差异，欢迎写进勘误。

三个本卷不做的事

不做通用 Agent 框架的安装与配置教程。 框架版本迭代快，配置项与具体版本强绑定。卷三给的是编排判据：什么时候该固定流程，什么时候该并行，失败怎么传播。判据可以迁移到任何框架，配置不能。

不做真实外部动作。 下单、退款、发券、发消息全部由模拟器执行。书里会讨论权限、幂等、审计与回滚，但不会连接任何真实账号、支付或订单系统。真实动作的后果不可逆，不适合用书本示例直接试。

不做生产级容量与压测结论。 卷三的实验是单进程、确定性负载，用来建立口径与对照方法。它能告诉你一条链路的成本结构与失败预算，不能告诉你双十一能不能扛住。

三件事有共同点：它们都依赖具体环境，换个公司、换个版本就失效。卷三只写不随环境变化的部分：结构、契约、判据与取舍。

团队怎么用

建议按「一次只改一个连接」的节奏使用本书。

1. 用第 1 章统一「什么算一条链路」的口径。
2. 用第 2 章给每次交接写契约，标出传递的是完整对象、摘要还是引用。
3. 用第 3、4 章把链路画成图，给每个节点分上下文预算。
4. 用第 5、6 章补失败策略、人工节点与异步交付。
5. 用第 7、8 章建评测集与预算表，确认质量与成本都能验收。
6. 用第 9–12 章补权限、观测、平台与灰度。
7. 用第 13 章做一次方案评审，形成可执行的基线。

不要一次改四个连接。四个变量同时变，失败无法归因，成本也无法解释，团队会陷入「好像快了一点」的争论。

自检清单

读完卷三后，你应该能回答：

• 一个请求需要几个能力，怎么判断该串行、并行还是条件分支？
• 什么任务适合固定编排，什么任务才需要自主规划？
• 每次交接应该传完整上下文、摘要、引用还是游标？
• 交接 token 为 820、共享上下文为 3,200、缓存折扣 90% 时，回本复用率是多少？
• 共享上下文的三种形态分别适合什么任务？
• 上游失败后，下游跳过、重试与部分结果各自的代价是什么？
• 三步链路、每步 1 次重试、目标成功率 95% 时，单步失败率上限是多少？
• 端到端成功率为什么不能只看最后一个节点？
• 编排级重试预算与单能力重试预算有什么区别？
• 外部动作的授权边界应该卡在编排层还是能力层？
• 一条编排的最低追踪字段有哪些？
• 从固定编排迁移到自主 Agent，应该先满足哪些条件？

答不上来的条目，对应章节需要重读。

勘误与反馈

书中的代码与数字都可以复现。如果发现代码无法运行、数字与脚本不符，以仓库中的脚本输出为准，并在勘误中记录命令、环境与输出。

欢迎指出判据不成立的反例，这比指出错别字更有价值。尤其是那些「在示例里成立、在真实任务里不成立」的编排假设，它们是卷三最需要修正的部分。

小结

卷三不是「多调用几个模型」的教程，而是一套把多能力任务变成可设计、可验收、可治理的方法。

方法的核心只有一句：先让每一次交接的 token、状态与失败都能被解释，再谈编排的复杂度。连接处解释不清，能力越多，系统越脆弱。

下一章从「回声」的三条链路开始，把这句话落到具体请求上。