主题
白皮书对标与落地推演：从 AI-Agent-Handbook 到开源生态企业智能体平台
一句话：这套平台的骨架与白皮书同构，但"组件齐全"不等于"按白皮书的生命周期落地"——本轮按 30 章逐条复核后，结论是 6 章已落地、12 章部分落地、6 章缺失（另 6 章为案例或按需），其中 7 处是必须纠正的理解错位（最严重的是把第 16 章 Agent Simulation 误当成"行为生成闭环"）；另有 7 个缺口已在本轮与 25/26 补到可建表、可接缝、可验收的设计级，平台实现状态仍按章级判定。
对标基准：《AI-Agent-Handbook》智能体建设白皮书 2026 版，共 30 章（架构 1–2、构建 3–6、运行 7–12、治理 13–16、调优 17–24、案例 25–29、结论 30）；被评对象：本目录 00–23、99 的"开源生态企业智能体平台"拼装方案。
本轮修订说明：上一版对标只覆盖第 1–16 章与第 30 章，且存在三处实质性误读——第 16 章、第 12 章"四通信面"、第 15 章"Asset Catalog"。本轮补读第 17–24 章，重读第 2、11、12、15、16、30 章，纠正误读并重写缺口推演；原版中成立的部分（源码验证、执行体形态、任务闭环）保留并重新编号。第 16 章的完整落地设计见 25-Agent仿真台落地设计，第 17–24 章的完整落地设计见 26-调优闭环落地设计。
为什么需要
平台文档已经写到实现级：有表结构、有接口、有状态机、有组件改造清单。但"实现级"不等于"符合白皮书"。白皮书提供的是判断这套实现该长在哪、按什么顺序长、凭什么算长成的框架。逐组件打勾会漏掉三类真实缺陷：
- 能力落在错误的平面：状态权威放进程内存、授权寄托在注册中心、评测集当真实分布——组件都在，但白皮书会判它不合格；
- 生命周期缺环：平台把"架构设计"隐含在构建里，把"调优"简化成"跑一次黄金集"；一旦形态选择或权限模型错了，后续只能靠重构补救；
- 责任悬空：多 Agent 的预算分账、通信面的选择、仿真证据、BadCase 回流，白皮书点名了，平台文档里只有"提到"没有"落地"。
所以对标要回答的不是"覆盖了哪些章"，而是四件事：哪些能力已正确落地、哪些部分落地但接缝未闭合、哪些是白皮书要求而平台没有实现、以及每个缺口如何合缝到现有组件。
对标口径
白皮书用三个视图组织判断，缺一不可：
| 视图 | 回答什么 | 平台对应 |
|---|---|---|
| 组件视图 | 一个 Agent 系统由哪些能力组成 | 00–23 的组件分篇 |
| 平台视图 | 能力由谁提供、责任如何划分 | 三平面（执行面 / 数据与资源面 / 控制面） |
| 生命周期视图 | 系统如何从架构决策走向运行并被改进 | 架构设计 → 构建 → 运行 → 治理 → 调优 |
五个责任域是：业务与场景、构建与编排、生产运行、治理控制、调优闭环。三个平面是：执行面（真实运行 Agent Loop、工具与环境操作，尽可能不持有唯一真实状态）、数据与资源面（保存可恢复事实与可访问能力，必须定义一致性、所有权、保留期与租户边界）、控制面（定义版本、身份、策略、部署、配额与改进动作，集中定义、判定点可分布）。
生命周期五阶段的顺序是 架构设计 → 构建 → 运行 → 治理 → 调优，不是"调研 → 构建 → 运行 → 调优 → 治理"（上一版写错）。治理既是阶段，也是横切约束：权限模型与数据边界在架构设计确定，工具策略与审批点在构建实现，Sandbox/Gateway 在运行执行，Observability 与安全分析在治理阶段检测，Evaluation 与 Simulation 在调优阶段验证变更。
平台侧把"什么能力值得下沉为共享平台能力"翻译为三条判据（这是本栏的翻译，不是白皮书原词）：复用面（多个 Agent/团队都要用）、强制面（不统一就会出安全或一致性问题）、可验证面（能定义契约、失败语义与验收）。三条都成立才下沉；只成立一条，留在应用侧更合适。这就是"最低充分架构"：不是把系统做大，而是对每一项被授予的自主性建立对等的执行、观测、安全与评估能力。
对标结论总览
判定统计
| 判定 | 章节 | 数量 |
|---|---|---|
| ✅ 已落地到可照做 | 1、3、7、10、13、14 | 6 |
| 🟡 部分落地，接缝未闭合 | 2、4、5、6、8、9、11、15、17、21、22、30 | 12 |
| ❌ 白皮书要求，平台缺实现 | 12（定义错位）、16、18、19、20、23 | 6 |
| ⚪ 按需/不适用/案例 | 24（边缘，默认不做）、25–29（案例，不作准入要求） | 6 |
合计 30 章。判定看的是"能否照做并验收"，不是"有没有提到"：一章里只要还有接不上缝的硬约束，就记 🟡；一章里完全没有对应实现对象，才记 ❌。
注意两种口径不要混：域级判断（下一张表）看这个责任域的能力是否够用，章级判断看每一章能否逐条照做。所以"治理控制域 ✅"与"第 13、14 章 ✅、第 15、16 章 🟡/❌"可以同时成立——域的能力框架成立，不代表每章细节都已闭合。
按责任域
| 责任域 | 平台覆盖 | 状态 | 结论 |
|---|---|---|---|
| 执行面：Model + Harness | 06 内核、11 接入、05 HiRoute、09 Jev、三类执行体 | ✅ | 06 已补 Action Request、Environment Contract 与四步提交；平台尚未收敛为单一执行点 |
| 数据与资源面 | 12 状态、19 资产、18 产物、25/26 新增仿真与调优数据 | 🟡 | 12 已补三表示与 Checkpoint；Context Manifest 仍需扩展信任层与权限依据 |
| 控制面 | 07 Service、08 Nacos、10 Scheduler、14 评测 | 🟡 | 07 已补 Release 六要素冻结与 task_run，08 已补资源中心六组件与解析锁；仍缺动态发现与 Context Compiler |
| 生产运行 | 03 网关、10 LiteTopic、21 沙箱、13 协议 | 🟡 | 13 已重写四通信面；严格预算仍待独立服务 |
| 治理控制 | 14 可观测、15 安全、04/08/19 供给 | ✅ | 纵深防御到验收级；14 已补审计与业务证据分离 |
| 调优闭环 | 14 黄金集/门禁 + 26 设计 | ❌ | 26 已给轨迹、Pipeline、归因、实验与自进化设计；平台仍无数据生产层 |
| 多 Agent 协作 | 06 子 Agent、11 委派、13 A2A、10 总线 | 🟡 | 24/22 已补 Task/TaskRun 分层、停止条件与预算；委派权限仍需落到策略 |
| Agentic OS（第 30 章） | 00–23 全篇 + 20/23/24 | 🟡 | 20 已补九个受管对象、Evidence 三态与预算接缝；实现仍缺 Budget Lease 与统一对象账本 |
七个必须纠正的错位（按严重度）
| # | 原表述 | 白皮书实际要求 | 后果 | 纠正落点 |
|---|---|---|---|---|
| 1 | 第 16 章="行为生成闭环" | 第 16 章是 Agent Simulation：Scenario→Manifest→Run→Result、用户/环境模拟器、SUT 不进仿真、三维保真度、四维状态、证据三层 | 平台没有仿真台，却以为已覆盖 | §四.4.1 + 25 篇 |
| 2 | "四通信面"=Agent 内/Agent 间/A2A/消息总线 | 四通信面是人机面（AG-UI）/能力面（MCP）/协作面（A2A）/内构面（无标准），每面再分 S1–S4 四档语义 | 选型矩阵与治理粒度全错 | §四.4.2 |
| 3 | 新建"Asset Catalog"作为统一权威目录 | Nacos Agentic Resource Registry 才是权威；目录只能是只读投影 + 对账 | 产生第二份真相，与 19 篇冲突 | §四.4.3 |
| 4 | 五阶段="调研→构建→运行→调优→治理" | 架构设计→构建→运行→治理→调优；Agent Release 是六要素最小发布单元 | 生命周期闭环顺序反了，治理与调优的职责错位 | 对标口径、§七 S0 |
| 5 | 多 Agent 只补"父预算→子预算" | 还需 Task/Subtask/TaskRun/Session 分层、六类停止条件、三级结果、入站/出站权限、Span Links | 长任务与团队协作无法收敛、无法追责 | §四.4.4 |
| 6 | "网关已覆盖" | 严格预算需 授权−已结算−在途预留 原子不变量；跨层重试预算会相乘；MCP 准入是四步链 | 预算超支、重试风暴、工具越权 | §四.4.5 |
| 7 | "已具备 Agentic OS 雏形" | 九个受管对象、Evidence 三态、强制边界 vs 观察边界、四类接入等级 | 高估成熟度，审计与强制边界缺失 | §四.4.6 |
核心机制
一、逐章对标矩阵
状态：✅=已落地到可照做；🟡=部分落地，接缝未闭合；❌=白皮书要求，平台缺实现；⚪=按需或不适用。证据列指向本目录篇目；"缺口"列指向本文 §四或 25/26 篇。
01-architecture
| 章 | 核心要求 | 平台映射 | 状态 | 说明 |
|---|---|---|---|---|
| 1 新阶段 | Agent = Model + Harness；应用形态分层；自主性与影响半径匹配 | 01、06、11 | ✅ | "内核不是调模型库，是阶段化执行引擎" |
| 2 参考架构 | 三视图、三平面、五责任域、五阶段闭环、Agent Release 六要素、最低充分架构 | 01、16 | 🟡 | 三平面与责任域对；五阶段顺序写错；Release 六要素未作为发布单元（§七 S0） |
02-build
| 章 | 核心要求 | 平台映射 | 状态 | 说明 |
|---|---|---|---|---|
| 3 Harness 范式 | Model/Harness/Runtime/Sandbox/Platform 五层责任；八个构建对象；三种路径控制；四类构建入口；平台七能力 | 06、07、11、21、01 | ✅ | 五层边界与三种接入面对齐；06 已补 Agent Contract 与 Environment Contract |
| 4 任务 | Agent Loop 五阶段；十态状态机；六类预算；三种计划模式；委派七项契约；五阶段门禁；验证五级 | 10、22 | 🟡 | 11 态可映射（queued=CREATED，planning/executing=RUNNING，waiting_tool/external≈WAITING_EVENT，expired 为平台扩展），但缺 PAUSED 与 VERIFYING 的独立语义、委派契约与 Middleware 禁止项（§四.4.4 + 23 篇） |
| 5 信息 | System Context 六层、Task Context 七层、Builder 九步、Manifest 九字段、压缩保留八项、Continuation Package 八项 | 06、12、19 | 🟡 | ContextManifest 有雏形，缺 permission_basis/trust_level/content_hash/transform/selected_reason；缺 Continuation Package |
| 6 行动 | Action Plane 八步；Action Request 字段；ALLOW/DENY/ASK；Preview-Approve-Commit-Verify；五对象边界；Environment Contract | 15、09、18、21、06 | 🟡 | 06 已补 Action Request 生命周期、Preview-Approve-Commit-Verify 与 Environment Contract；平台仍需把策略点收敛成一个可审计执行点 |
03-run
| 章 | 核心要求 | 平台映射 | 状态 | 说明 |
|---|---|---|---|---|
| 7 运行时与沙箱 | 三类负载；五种环境；四种状态策略；Template/Snapshot/Fork/Reset；执行代次与围栏；恢复六类验证 | 21、12 | ✅ | 四把钥匙、三层超时、四分支恢复已到决策级；建议补 Fork/Reset 与浅/深休眠语义 |
| 8 状态存储 | 四类状态；Event Log/Snapshot/Checkpoint 三表示；Workspace 六区；Memory 四类；Artifact 生命周期；本体与知识 | 12、18 | 🟡 | 四类存储与隔离扎实；12 已补三表示、Checkpoint 字段组、Workspace 六区与 Artifact 状态机；Memory 四类与知识证据八项仍待补（22 篇 §八 + §四.4.6 Evidence） |
| 9 AI 网关 | LLM/MCP/Agent 三层治理；模型与端点选择分离；错误分类后重试；严格预算不变量；MCP 默认拒绝准入；审批挂起重准入 | 03、05、14 | 🟡 | 网关覆盖有；严格预算、跨层重试预算、MCP 四步准入缺失（§四.4.5） |
| 10 异步任务 | Task 属性；状态机；定时任务属性与错过策略；工作流 DAG/Join；完成语义五层 | 10、22 | ✅ | 触发/投递/账本三层分工到 SQL 级；10 已补四种错过策略、计划时刻幂等与 OR Join 取消/补偿语义 |
| 11 Multi-Agent | 团队拓扑；Task/Subtask/TaskRun/Session；六类停止条件；三级结果；共享最小充分；六类身份；入站/出站权限；Span Links | 06、11、13、22 | 🟡 | 能力齐；分层、停止条件、身份与权限、跨 Trace 关联缺失（§四.4.4） |
| 12 分布式通信 | 四通信面；S1–S4 四档语义；契约六要素；手脑分离；会话通道规模化 | 06、13、10 | ❌ | 13 已按人机/能力/协作/内构重写；平台仍缺跨面统一契约与通道规模化的实现（§四.4.2） |
04-governance
| 章 | 核心要求 | 平台映射 | 状态 | 说明 |
|---|---|---|---|---|
| 13 可观测性 | 四类观测维度；三层对象；12 类执行语义；Session 与 Trace 边界；审计证据链；缺失不得补零 | 14 | ✅ | 六类信号、traceparent 续接、span 四属性到位；14 已补 12 类执行语义、Session/Trace 边界与审计/业务证据分离 |
| 14 安全 | 盾+缰绳；五类攻击面；九类护栏；双向授权；Token Exchange；出站默认拒绝；会话级隔离；S1–S4 数据分级 | 15、21 | ✅ | 四层威胁面、三层权限、默认拒绝到验收级；建议补 Token Exchange/On-Behalf-Of 与 DoW |
| 15 资产发现 | 五类资源；逻辑资源/版本/运行引用；资源中心六组件；权威与派生索引；稳定 Agent 与动态 Agent；Context Compiler/Manifest | 08、19、04 | 🟡 | 08/19 已补六组件、五态与 Resolver/Lock Manifest；仍缺 ARD/RAD 与 Context Compiler 的完整字段（§四.4.3） |
| 16 Agent Simulation | SUT 不进仿真；三种保真度；Spec→Manifest→Run→Result；用户/环境模拟器；四维状态；证据三层；置信上界 | 25 | ❌ | 25 已给到表结构、API 与接缝；平台尚无仿真对象链与执行引擎（§四.4.1 + 25 篇） |
05-optimization
| 章 | 核心要求 | 平台映射 | 状态 | 说明 |
|---|---|---|---|---|
| 17 模型调优 | 三层归因；四类能力；SFT/Agentic RL/蒸馏；五道上线门禁；灰度与回滚 | 14、05 | 🟡 | 平台不训练是合理边界；缺样本导出、可复现评估环境、Release 冻结（§四.4.7 + 26 篇） |
| 18 Agent 调优总览 | 数据飞轮六模块；两条反馈路径；Trace→Outcome→Patch 闭环 | 14 | ❌ | 只有评测，没有飞轮（26 篇） |
| 19 轨迹数据 | Trace/Session/Trajectory 三对象；ATIF；检索；样本字段；相邻事实链分析 | 14、22 | ❌ | 无轨迹对象与整理规则（26 篇） |
| 20 运行时数据处理 | Pipeline 模块目录；输出 schema；粒度决策；成本顺序；partial 语义 | 无 | ❌ | 无数据生产层（26 篇） |
| 21 黄金数据集 | 题目+判据；字段 schema；五类覆盖；版本与独立性；污染控制 | 14 | 🟡 | 有黄金集；缺 rubric/version/split/独立性（26 篇） |
| 22 BadCase | 三类评估器；判读四行；实验变量；采用三看 | 14 | 🟡 | 有归因口号；缺分类与 Patch 对应（26 篇） |
| 23 受控自进化 | 五类现象→五类资产；接入四步；四类故障；采用四确认；自动化三级 | 无 | ❌ | 无经验库/Skill 候选/受控自动化（26 篇） |
| 24 边缘运行时 | 四维边缘；Region/Edge 分工；缓存约束；L1–L4；按需 | 03/05 | ⚪ | 默认不做；多区域时按 26 篇 §十 |
06-case-study 与 07-conclusion
| 章 | 定位 | 平台映射 | 状态 | 说明 |
|---|---|---|---|---|
| 25–29 案例 | 实践参考，不是准入要求 | 00–23 可作为对照 | ⚪ | 案例只作对照，不设验收门槛 |
| 30 Agentic OS | 九个受管对象；Evidence 三态；三层边界；四类接入等级；自主性 L1–L5；六个标准接口 | 00–23 | 🟡 | 方向正确；对象与证据状态未齐（§四.4.6） |
二、合缝基线：三平面如何映射到部署单元
合缝的第一步不是画更多组件，而是给每个组件指定平面、权威与失败责任人。下面这张图是后续所有接缝的地基（编号对应 §三.2 的 22 条接缝）。
三条平面纪律，任何时候都不能破：
- 执行面只留"这一步怎么跑"：模型选择、阶段判断、循环装配、执行边界。执行面可以缓存，但不能持有唯一真实状态。
- 数据与资源面只留"这份事实归谁、权威在哪"：任务账本、会话状态、工作区、产物、轨迹、资源内容。每个事实只有一个写入口。
- 控制面只留"谁能改、何时发布、如何恢复"：目录、版本、策略、额度、发布、评测。控制面不应成为每次模型或工具调用的强同步依赖——策略集中定义，判定点分布执行。
判断是否合缝，只问一句：任意一次任务，从入口到终态，每一跳能不能说清"谁写权威、在等什么、占什么、何时释放、凭什么算完成"。答不上来的那一跳，就是接缝悬空。
三、合缝总账
3.1 接缝总账（22 条）
| # | 接缝 | 交界字段 | 权威 | 失败语义 | 已定 | 本轮补全 |
|---|---|---|---|---|---|---|
| 1 | 渠道 → Higress | external_user_id→subject、msg_id→idempotency_key、chat/group→session scope | 网关认证结果 | 验签失败拒绝；重放窗口外拒绝 | 13/17 | — |
| 2 | Higress → Service/内核 | tenant/ns/subject/session + traceparent | 网关 | 剥离原始身份头；每跳重校验 | 03/15 | 入站/出站权限分离（§四.4.4） |
| 3 | Budget Service → 网关/内核 | budget_lease_id、维度、授权额、预留额 | Budget Service | 预留失败即拒绝，不先调用后补账 | 无 | 新增（§四.4.5） |
| 4 | 内核 → 任务账本 | task_id/task_run_id/version/lease_epoch | rt.agent_task | CAS + 栅栏；旧 epoch 写回拒绝 | 22 | Task Run 分层（§四.4.4） |
| 5 | 内核 → 状态/工作区 | (tenant,userId,sessionId)、IsolationScope | 状态存储 | CAS + ConflictPolicy.FAIL | 06/12 | Checkpoint 字段组（22 篇 §八） |
| 6 | 内核 → Jev | 问题类型、候选、概率、阈值 | Jev | fail-open/closed 逐用例声明 | 09 | — |
| 7 | 内核 → 模型网关 | 模型调用、计量、能力等价结果 | 网关计量 | 降级前能力校验；重试单独占额 | 03/05 | 跨层重试预算（§四.4.5） |
| 8 | 内核 → 沙箱 | IsolationScope、快照规格、租约、代次 | 沙箱管理器 | 快照失败 fail-closed；旧代次写入拒绝 | 12/21 | Fork/Reset（21 篇） |
| 9 | 内核 → 产物服务 | artifact_id/sha256/acl/retention | 产物服务 | 扫描失败 fail-closed；入库不可变 | 18 | Artifact 状态机 |
| 10 | 产物 → 渠道适配器 | artifact_id+channel+recipient 幂等 | 适配器 | 退避重试 → 降级链接；回执写证据 | 18 | — |
| 11 | 市场 ↔ 注册中心 | product_id、nacosRefConfig/higressRefConfig | Nacos（定义） | 引用对账，差异告警不静默刷新 | 04/19 | — |
| 12 | 注册中心 → 运行时 | namespace+type+name+version、label、endpoint、schema | Nacos | Resolver 失败 → 用上一组已验证 Lock，或明确停止 | 08/19 | 重写（§四.4.3） |
| 13 | 父任务 → 子任务/子 Agent | parent_task_id、task_run_id、delegation_id、子预算 | 父任务账本 | 六类停止条件；join all/quorum；失败策略 | 22 | 扩展（§四.4.4） |
| 14 | 运行时 → OTel | traceparent、teamId/taskId/taskRunId/sessionId、span 四属性 | OTel | 采样分层；跨 Trace 用 Span Links | 14 | 扩展（§四.4.4） |
| 15 | Evaluation → 发布门禁 | 黄金集版本、评分器版本、阈值、置信区间 | 治理门禁 | 阈值先注册；证据不足不准入 | 14 | 门禁五道（26 篇） |
| 16 | Simulation → SUT | sut.agent、sut.boundary、入口、测试身份 | 控制面 | 边界被替身接管 → 拒绝启动 | 无 | 新增（25 篇） |
| 17 | Simulation → 环境/故障 | 事实模型、隔离命名空间、ChaosBlade 实验 ID | Harness（计划）/ChaosBlade（执行） | 故障四步记录缺一 → 结论不可信 | 无 | 新增（25 篇） |
| 18 | Simulation → Evaluation | Records/Observations/Evidence/Completeness | Evaluation | 证据不足 → undeterminable | 无 | 新增（25 篇） |
| 19 | 任务账本 → 轨迹层 | task_run_id/trace_id/outcome_source | 任务账本 | 采集缺失标 partial，不补零 | 14/22 | 新增（26 篇） |
| 20 | 轨迹 → Pipeline → Dataset | trajectory_id、粒度、split、rubric | Dataset | 污染/去重失败拒绝入集 | 无 | 新增（26 篇） |
| 21 | Release → 灰度/边缘 | Release ID、Manifest、区域、版本钉扎 | 控制面 | 版本未钉扎 → 不准发 | 16 | 新增（26 篇） |
| 22 | 审计 ↔ 业务证据 | audit_id、evidence_id、主体、动作、对象 | 审计（合规）/业务（Outcome） | 审计不替代证据；证据不替代审计 | 14/15 | 新增（§四.4.6） |
3.2 十条原子规则
前六条在原版已成立，后四条是本轮补的：
- 同一事实只有一个权威：状态在账本、计量在网关、定义在 Nacos、产品在市场、证据在证据服务；其它组件只做投影/引用。
- 发现不等于授权：出现在目录、注册中心、Agent Card ≠ 能调用；准入在网关、工具策略、运行时三层独立。
- 幂等覆盖所有变更：创建/提交/取消/恢复/审批回答都带
Idempotency-Key；同键不同体返回 409。 - 至少一次 + 幂等，不承诺恰好一次：先提交结果再提交位点；重投不重执行；LiteTopic 无自带重试主题，重试由租约与幂等实现。
- 等待释放计算：审批/输入/外部回调默认快照后释放沙箱；只有审批对象必须活在进程里才保留短租约，并标
resumable=false。 - 完成靠证据不靠模型：executed → verified → accepted → delivered 四层；无证据标
completed_unverified。 - 版本锁定：Agent Release、Simulation Run、Context 装配都锁定 Manifest；运行记录保存解析后的精确版本与摘要，不保存
latest或裸 label。 - 证据分层：Records（原始）→ Observations（事实）→ Evidence（按评价项）→ Verdict（结论）四层分离；结论不能改写原始材料。
- 有界停止：预算、最大委派深度、派生任务数、重试上限、返工轮次、无进展轮次，六类停止条件至少配置四类，缺一不能上长任务。
- 严格预算：
可用额度 = 已授权额度 − 已结算消耗 − 在途预留；检查与预留同一原子操作；重试单独占额；Higress 单插件不能宣称严格上限。
四、缺口落地推演
七个缺口按"定位 → 设计 → 契约/字段 → 失败语义 → 验收"展开；仿真与调优两个大块另有专篇。
4.1 缺口一：Agent 仿真台（第 16 章，最大结构性缺口）
定位：平台有生产可观测、离线黄金集、影子流量，但没有"把一个 Agent 放进可控世界跑一遍"的对象链。上一版把第 16 章理解成"从轨迹生成用例的行为生成闭环"，这是把 Simulation（生成受控执行与证据） 与 Optimization（从轨迹改进 Agent） 混为一谈；两者在第 16 章与第 18–23 章分属不同章节、不同产出。
白皮书硬约束：
- SUT 是仿真服务的对象，不是仿真的一部分；工具调用顺序一旦写成脚本，被测的就不是 Agent；
- 边界由授权与后果划定，不由"请求有没有真的发出去"划定；
- 三种保真度：全替身、混合、隔离真实依赖；不同模式的结论不可混用；
- 对象链：Scenario Spec → 不可变 Manifest → Run → Run Result（Records/Artifacts/Observations/Evidence/Completeness）；
- Run 四维状态独立：执行状态、仿真有效性、证据完整性、任务质量；
- 四种时间分离：业务日历、仿真逻辑、单调时钟、墙钟；
- 交付证据材料，不交付质量结论；零违规要附
1 − 0.05^(1/n)置信上界。
合缝设计（摘要，完整见 25 篇）：
| 组件 | 改造 | 新契约 |
|---|---|---|
| 仿真 Harness | 新增独立服务 | sim schema 核心表族：场景/资产/Manifest/Run/Task/Session/事件/记录/观测/证据/完整性/故障 |
| Nacos | 场景与资产版本化 | sim-assets 命名空间；场景/数据/工具/模拟器/评估规格独立版本 |
| Sandbox | 每 Run 独立命名空间与测试账户 | 隔离键 run_id；Run 间不共享可变状态 |
| ChaosBlade | 仅作故障执行后端 | 四步记录：planned/armed/hit/recovered |
| OTel | 关联而非采集 | run_id/manifest_id 进 span 属性 |
| Evaluation | 消费证据包 | criterion→evidence_refs→verdict；三道可用性检查 |
| 发布门禁 | 高风险变更要求仿真证据 | 缺证据 → 不准入 |
失败语义：Manifest 解析失败 → crashed，不降级到"任意可用版本"；故障未命中 → validity_status=violated；证据缺失 → evidence_status=partial 并列缺失项；快照/清理失败 → 该 Run 结论不可用。
验收：同 Manifest 重跑两次 Records 可逐条对齐；SUT 边界被替身接管时拒绝启动；故障只注入未命中时结论不被采纳；证据不足输出"不可判定"；300 次零违规报告附带 ≤1% 的置信上界。
4.2 缺口二：四通信面与交互语义（第 12 章）
定位：上一版把"四通信面"定义成 Agent 内 / Agent 间进程内 / A2A / 消息总线，这是按部署位置分类；白皮书按通信双方身份分类，决定"契约由谁定义、标准化程度、治理粒度"。两者混用会导致：该走 MCP 的工具调用被塞进消息总线，该用 A2A 任务句柄的跨组织协作被做成同步 RPC，内构面的会话通道被当成通用事件总线。
正确的四个面：
| 通信面 | 双方 | 协议层 | 常见机制 | 核心矛盾 | 平台载体 |
|---|---|---|---|---|---|
| 人机面 | 用户/前端 ↔ Agent | AG-UI | 增量 token 流、前端流式协议、待办收件箱、人在回路审批 | 需要增量可见与随时打断，前端连接最不可靠 | 13 渠道 + 17 助理 Hub + SSE |
| 能力面 | Agent ↔ 工具/数据 | MCP | 工具调用（垂直） | 工具耗时差异大，毫秒查询与分钟任务共用一套协议 | 19 供给链 + Higress MCP Gateway |
| 协作面 | Agent ↔ Agent | A2A | 任务委派（水平） | 任务天然长跑，点对点集成与信任关系随数量组合增长 | 13 A2A + 07 Endpoint + 网关准入 |
| 内构面 | Agent 服务端组件之间 | 无标准 | 消息队列、事件流、内部 RPC | 海量会话通道的元数据成本与多租户隔离 | 10 RocketMQ LiteTopic + 事件流 |
四档交互语义（决定失效模式，不是成熟度）：
| 档 | 语义 | 时间耦合 | 状态位置 | 解决 | 不解决 |
|---|---|---|---|---|---|
| S1 | 请求—响应 | 响应期内 | 临时调用状态 | 短调用与直接反馈 | 长任务查询、事件续传 |
| S2 | 请求域流式 | 当前流依赖连接 | 当前流，可关联持久任务 | 增量可见与进度 | 单凭流不能断连续补 |
| S3 | 任务句柄 | 执行与首请求解耦 | 持久任务与结果引用 | 长任务查询、离线取回 | 不自动保证事件重播或业务恢复 |
| S4 | 持久通道 | 生产与消费解耦 | 消息日志与消费位点 | 推送、削峰、重播、通道治理 | 仍需应用状态、幂等与运维 |
两轴交叉后的平台默认选择：
| 面 | 默认 | 升级触发 | 平台落点 |
|---|---|---|---|
| 人机面 | S2（token/事件流） | 长任务需离线取回 → S3；多端接同一会话 → S4 | AG-UI 事件 + SSE Last-Event-ID |
| 能力面 | S1（工具调用） | 工具耗时 > 30s 或需取消/进度 → S3（MCP Tasks） | MCP Client + Toolkit |
| 协作面 | S3（A2A Task） | 需要持续推送 → 任务查询 + 推送通知；Agent 网格 → S4 | A2A + 网关 |
| 内构面 | S4（会话通道） | 纯内部短调用 → S1 RPC；任务表认领 → S3 | LiteTopic %LMQ%$parent$session |
六个契约要素必须逐项写清，缺一项就不算可用于生产：
| 要素 | 问题 | 平台字段/做法 |
|---|---|---|
| 标识 | 会话、任务、轮次、消息的标识与从属关系 | session_id/task_id/task_run_id/turn_id/message_id 分别保留，不把任务 ID 直接当消息线程 ID |
| 顺序 | 哪个作用域内保序 | ordering_scope = session / task / none；LiteTopic 单队列保证通道内 FIFO |
| 投递保证 | 至少一次/至多一次/恰好一次 + 去重键 | 默认至少一次；idempotency_key；不承诺恰好一次 |
| 续传点 | 断连/换节点从哪里继续 | after_seq/Last-Event-ID；与任务查询能力分开声明 |
| 生命周期 | 通道与任务何时创建、过期、销毁 | LiteTopic TTL；任务 deadline_at；回收前核对活跃任务与未确认消息 |
| 背压 | 过载时如何减速 | 入口限流、通道暂停、队列水位、Worker 槽位；慢会话只慢自己 |
三条容易拼错的边界：
- 流结束 ≠ 任务结束：SSE 断开不代表执行取消；是否有独立任务句柄、是否有事件续传位置，必须分别检查；
- LiteTopic 是内构面 S4，不是通用总线：它解决会话级有序、独占消费、续传与 TTL，不解决跨组织协作与工具调用语义；
- A2A 的 Agent Card 是描述，不是授权：发现之后仍要过网关身份、配额与工具策略。
验收：每个 Agent 能回答"默认走哪个面、哪一档、六个契约要素分别是什么"；跨组织调用与内部子 Agent 的配额、审计、失败语义可分别配置；同一会话两条消息严格有序，断线重连不丢不重。
4.3 缺口三：资源中心与上下文装配（第 15 章）
定位：上一版提出新建"Asset Catalog"作为统一权威目录，这与 19 篇"Nacos 是权威、市场存引用"直接冲突。白皮书的正确形态是 Nacos Agentic Resource Registry 作为资源中心，统一的是标识、生命周期、权限、评审与运行入口，不是把五类资源改成同一种内容。任何"Catalog"只能是只读投影 + 对账，不能成为第二份真相。
边界要写清：源码与构建产物归 Git/CI，Nacos 统一的是发布态与运行态的标识、版本与状态；两者通过 provenance 关联，不能把 Nacos 变成代码仓库。
五类资源，一套治理框架：
| 资源 | 版本内容 | Pipeline 重点 | 运行时消费 |
|---|---|---|---|
| Prompt | 模板、变量、输出约束 | 渲染、Schema、评测集、安全输入 | Resolver 渲染后进 Context |
| Skill | SKILL.md、脚本、资料、依赖 | 包完整性、来源、脚本与依赖安全 | Skill Loader 按需加载 |
| MCP Server | 服务说明、Tool、Resource、协议 | Schema、协议兼容、认证、样例 | Registry/Router 发现，MCP Client 调用 |
| Agent | 版本化调用接口、协议描述、端点 | 内容校验、接口协议、安全要求 | ARD 发现、RAD 解析端点、协议客户端交互 |
| AgentSpec | 组装配置、资源引用、附属文件 | Manifest、依赖解析、版本锁定、构建验证 | 构建/部署/启动阶段解析 |
标识与版本：namespaceId + resourceType + resourceName 标识逻辑资源，加 version 标识内容；生命周期 draft → reviewing → reviewed → online → offline；在线版本不可覆盖，下线不等于删除。可见范围决定"是否出现在搜索结果"，鉴权决定"能否读取/修改/发布"，两者不能混。
资源中心六组件：
text
管理与发布 ──> 权威 Registry ──> AI 资源内容存储
│ │
├──> 发布 Pipeline │
├──> 发现索引（派生）│
│ │
Agent 请求 ──> Policy Engine ──> Resolver ──> 精确版本 + 内容摘要| 组件 | 职责 | 不是什么 |
|---|---|---|
| 权威 Registry | 逻辑资源、版本、状态、标签、权限、引用关系 | 不是内容仓库 |
| 内容存储 | Prompt 正文、Skill 包、AgentSpec 包 | 不是可用性判断依据 |
| 发布 Pipeline | 格式、安全、评测、组织条件 | 不是运行时 |
| 发现索引 | 名称、描述、分段、向量、关系 | 派生数据，可重建 |
| Policy Engine | 身份、Namespace、环境、权限、风险 | 不是鉴权唯一执行点 |
| Resolver | 引用/标签 → 不可变版本 + 摘要 + 依赖 + 状态 | 不能被检索结果替代 |
两条链路要分开：管理链路处理创建、修改、评审、发布、废弃；运行链路只做查询、解析、下载、端点发现、变更通知。运行链路必须有本地缓存，缓存项绑定精确版本与摘要；资源中心不可用时，按策略使用已验证缓存，高风险任务则停止并说明原因——不能把一次查询失败解释为"使用任意可用内容"。
稳态 Agent 与动态 Agent：
| 形态 | 绑定时机 | 机制 | 失败语义 |
|---|---|---|---|
| 稳态 Agent | 构建/部署/启动时声明依赖 | 结构化引用 {namespace,type,name,version-selector}；Resolver 解析；生成 Lock Manifest | 解析失败 → 用上一组已验证组合，或缺依赖则停止 |
| 动态 Agent | 任务开始时按需求发现 | ARD 搜索/发现/监听；RAD 解析远程调用信息；候选重新过版本/权限/风险 | 摘要与正文版本不一致 → 拒绝加载并重新发现，不用名称相近的内容替代 |
Context Compiler（第 15.9 节，平台 06 篇只有雏形）：
- 发现摘要与执行内容分离：候选比较只用名称、简述、适用场景、版本状态、风险等级、匹配原因；选定后才取正文/包/端点；
- 优先级与信任分层：系统策略与核心 Prompt > 任务 Prompt > 已批准 Skill > MCP/远程 Agent 能力说明 > Knowledge/RAG/Memory > 用户输入与工具结果；措辞强烈不改变层级；
- Token 预算与渐进装配：先给类别分预算，再在类别内按相关性与必要性选择；核心策略完整保留，Skill 先给步骤与限制，参考资料延迟到相关步骤；
- 冲突与异常：一项资源失败不能混用新旧版本；优先整体回退到上一组 Lock，或停止并说明缺依赖；
- Context Manifest：记录
agent_release/model/resources/policy_version/discovery_requests，每个资源带source_type/source_id/scope/version/trust_level/permission_basis/selected_reason/token_count/transform/content_hash。
Asset Catalog 的正确写法：只存 asset_id/type/authoritative_source/version_snapshot/owner/state/provenance 的投影，写入只由 Nacos/Service/知识库的变更事件驱动；每日对账比对 version/state/schema_sha256，差异告警而不是自动覆盖；目录故障不影响任何权威。验收标准是"目录能一处查清，但删掉目录平台仍能跑"。
最小 schema：
sql
CREATE SCHEMA IF NOT EXISTS res;
CREATE TABLE res.resource (
namespace_id text NOT NULL,
resource_type text NOT NULL CHECK (resource_type IN ('prompt','skill','mcp','agent','agentspec')),
resource_name text NOT NULL,
owner text NOT NULL,
visibility text NOT NULL CHECK (visibility IN ('public','private')),
labels jsonb NOT NULL DEFAULT '{}',
PRIMARY KEY (namespace_id, resource_type, resource_name)
);
CREATE TABLE res.resource_version (
namespace_id text NOT NULL,
resource_type text NOT NULL,
resource_name text NOT NULL,
version text NOT NULL,
status text NOT NULL CHECK (status IN ('draft','reviewing','reviewed','online','offline')),
content_ref text NOT NULL,
content_sha256 text NOT NULL,
schema_sha256 text,
endpoint_ref text,
published_at timestamptz,
PRIMARY KEY (namespace_id, resource_type, resource_name, version),
FOREIGN KEY (namespace_id, resource_type, resource_name)
REFERENCES res.resource(namespace_id, resource_type, resource_name)
);
CREATE TABLE res.resource_ref (
from_type text NOT NULL,
from_name text NOT NULL,
from_version text,
to_type text NOT NULL,
to_name text NOT NULL,
selector text NOT NULL, -- 精确版本 / stable / canary
PRIMARY KEY (from_type, from_name, from_version, to_type, to_name)
);
CREATE TABLE res.release_lock (
release_id text PRIMARY KEY,
agent_key text NOT NULL,
agent_version text NOT NULL,
resolved jsonb NOT NULL, -- 精确版本 + sha256
manifest_sha256 text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE res.context_manifest (
manifest_id text PRIMARY KEY,
task_run_id text NOT NULL,
release_id text NOT NULL,
resources jsonb NOT NULL, -- 九字段
policy_version text NOT NULL,
token_budget int NOT NULL,
token_used int NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
);验收：任一资产能查到"当前版本、权威来源、owner、状态"；上游改版本后约定周期内出现差异告警；Lock Manifest 能解释一次历史任务用了哪组精确版本；Context Manifest 能解释"为什么这段内容进了上下文、为什么那段被排除"；目录故障不影响运行时。
4.4 缺口四：多 Agent 协作、任务分层与权限（第 11 章）
定位：平台有子 Agent、委派、A2A、消息总线，但缺四样让长任务"收敛且可追责"的东西：任务分层、停止条件、结果等级、身份与权限。没有这四样，多 Agent 系统会在"谁负责、什么时候停、什么算完成"上失控。
任务分层：Task / Subtask / Task Run / Session
| 对象 | 定义 | 权威 | 平台落点 |
|---|---|---|---|
| Task | 有独立目标与交付责任的业务单元 | 父任务账本 | rt.agent_task |
| Subtask | 父任务分解出的子目标，保留父责任 | 父任务账本 | rt.agent_task.parent_task_id |
| Task Run | 一次执行尝试（可能重试、换 Worker、换模型） | 运行记录 | 新增 rt.task_run |
| Session | 交互与上下文组织，可跨 Task Run | 会话存储 | (tenant,user,session_id) |
关键边界：Session 只是执行视图，不是任务权威；一个 Session 可含多个 Task，一个 Task 可跨多个 Session；task_id 与 session_id 分别保留，不互相替代。
sql
CREATE TABLE rt.task_run (
task_run_id text PRIMARY KEY,
task_id text NOT NULL REFERENCES rt.agent_task(task_id),
attempt int NOT NULL,
worker_id text NOT NULL,
agent_release text NOT NULL,
lease_epoch bigint NOT NULL,
status text NOT NULL CHECK (status IN ('running','succeeded','failed','cancelled','lost')),
started_at timestamptz NOT NULL,
ended_at timestamptz,
terminal_reason text,
UNIQUE (task_id, attempt)
);恢复点不能只存"最后一条消息"。一次 Checkpoint 至少记录下表内容，否则换 Worker 后只能重跑，不能续跑：
| 字段 | 作用 | 缺了会怎样 |
|---|---|---|
checkpoint_seq | 同一 Task Run 内单调递增 | 不知道恢复点新旧，可能回退 |
phase / step_no | 当前阶段与步骤 | 只能从头开始 |
completed_steps / unfinished_steps | 已完成与未完成清单 | 重复执行副作用动作 |
confirmed_facts_ref | 已确认事实的引用 | 重新问用户、重复检索 |
tool_result_refs | 工具结果在对象存储的引用 | 重调外部工具 |
workspace_version / snapshot_id | 工作区版本或快照 | 文件状态与事实不一致 |
subtask_states | 子任务各自阶段 | 父子进度错位 |
wait_condition | 当前在等什么（审批/输入/事件） | 恢复后继续空转 |
budget_snapshot | 已用/预留/租约 ID | 恢复后超支或漏结算 |
state_version | 乐观锁版本 | 并发恢复互相覆盖 |
恢复时先校验 state_version + lease_epoch，再按 unfinished_steps 续跑；任何一步的外部副作用都要先查幂等键，不能默认"上次一定没执行"。
六类停止条件（长任务必须至少配四类）
| 条件 | 字段 | 默认建议 | 触发后 |
|---|---|---|---|
| 预算 | budget.* | 按任务类型 | expired，写未完成清单 |
| 最大委派深度 | max_delegation_depth | 3 | 拒绝再派发，父任务决定 |
| 派生任务数 | max_derived_tasks | 20 | 拒绝新建子任务 |
| 重试上限 | max_attempts | 3 | 转人工/死信 |
| 返工轮次 | max_rework_rounds | 2 | 升级或终止 |
| 无进展轮次 | max_no_progress_rounds | 3 | 重规划或终止 |
无进展检测不能只看"是否调用了工具"，要看"任务事实是否新增"：新确认事实、新产物、新外部状态，三者至少一项变化。
三级结果，不能互相推导
| 等级 | 含义 | 判定者 | 平台字段 |
|---|---|---|---|
| submitted | 子任务已提交结果 | 子任务执行者 | submitted_at |
| accepted | 父任务/验收方接受该结果 | 父任务或业务验收 | accepted_at/accepted_by |
| root complete | 根任务目标达成 | 根任务验收或业务系统 | root_outcome |
子任务 submitted 不等于父任务 accepted，更不等于根任务完成。把三者压成一个 completed，是"多 Agent 看起来跑完、业务其实没成"的常见原因。
委派契约七项
每次委派必须带：目标与边界、已知上下文、能力与权限、预算、输出与证据、失败语义、验收条件。缺一项，接收方就只能靠猜。Delegation 与 Handoff 要分开：Delegation 父任务保留责任，返回后整合验收；Handoff 控制权转移，接收者成为责任人并获得目标、状态、恢复位置。
子任务失败策略：FAIL_FAST、BEST_EFFORT、RETRY_OR_REASSIGN、ESCALATE，在委派时声明，不能由执行者临时决定。
预算级联：Budget Lease 是一等对象
只在父任务上记总预算不够。白皮书第 30 章要求 Budget Lease 是可管理的对象，第 9 章要求严格不变量。落地成三张表：
sql
-- 授权：组织/团队/项目/任务四级额度
CREATE TABLE gov.budget_grant (
grant_id text PRIMARY KEY,
tenant_id text NOT NULL,
scope_type text NOT NULL CHECK (scope_type IN ('org','team','project','task')),
scope_id text NOT NULL,
dimension text NOT NULL,
authorized numeric NOT NULL,
settled numeric NOT NULL DEFAULT 0,
reserved numeric NOT NULL DEFAULT 0,
valid_from timestamptz NOT NULL,
valid_until timestamptz,
CHECK (reserved >= 0 AND settled >= 0 AND settled + reserved <= authorized)
);
-- 租约：父任务给子任务的额度，可回收、可到期
CREATE TABLE gov.budget_lease (
lease_id text PRIMARY KEY,
grant_id text NOT NULL REFERENCES gov.budget_grant(grant_id),
task_id text NOT NULL,
parent_task_id text,
dimension text NOT NULL,
amount numeric NOT NULL,
used numeric NOT NULL DEFAULT 0,
reserved numeric NOT NULL DEFAULT 0,
status text NOT NULL CHECK (status IN ('active','settled','released','expired')),
expires_at timestamptz,
CHECK (reserved >= 0 AND used >= 0 AND used + reserved <= amount)
);
-- 流水：reserve/consume/release/expire，只追加
CREATE TABLE gov.budget_ledger (
entry_id bigserial PRIMARY KEY,
lease_id text NOT NULL,
kind text NOT NULL CHECK (kind IN ('reserve','consume','release','expire')),
amount numeric NOT NULL,
ref text,
created_at timestamptz NOT NULL DEFAULT now()
);gov.* 是跨任务、跨 Agent 的授权与租约权威；22 篇的 rt.agent_task_budget 是任务侧视图，两者通过 task_id / lease_id 关联，不能各记一套余额。
预留必须原子：
sql
UPDATE gov.budget_grant
SET reserved = reserved + :amount
WHERE grant_id = :grant_id
AND settled + reserved + :amount <= authorized;
-- 影响行数为 0 即额度不足，不得先调用后补账join 时先 settle 子租约，再释放未用额度，最后聚合到父任务的完成证据。父任务不能"借"子任务未花的额度继续跑，除非显式追加授权并留审计。
身份与权限：六个对象、两个方向
| 对象 | 用途 | 生命周期 |
|---|---|---|
| 人员主体 | 登录、管理、审批、发起、接管 | 随企业账号 |
| 服务主体 | API、定时触发、系统集成 | 独立于人员账号，可轮换撤销 |
| Agent/工作负载主体 | 稳定标识数字成员，绑定职责、策略、审计、成本 | 随 Agent 创建/发布/归档 |
| 执行主体 | 实际访问模型/工具/数据的运行实例 | 随 Task Run |
| 临时凭证 | 向目标系统证明执行主体与范围 | 短期、按运行/资源 |
| 委托授权 | 人员/服务允许 Agent 代办的范围 | 随 Session/Task Run，带到期 |
入站权限决定"谁可以调用这个 Agent、发起什么任务"；出站权限决定"Agent 可以代表谁、访问哪些外部资源"。两者独立校验，不能因为调用者能访问 Agent，就默认 Agent 能访问调用者的全部资源。Agent 间交接不扩大权限：接收方只获得当前任务所需、且双方都被允许的最小范围。
追踪：不要强行拼成一棵树
- W3C Trace Context 传播；业务关联标识
teamId/taskId/taskRunId/sessionId； - 能连续传播上下文的执行用父子 Span；跨 Trace、并行汇合、无法形成单一父子关系的用 Span Links；
- 任务标识与产物引用承担跨恢复关联，每段 Trace 记录实际发生的因果，不强制整段生命周期在同一条 Trace 里。
验收：父任务带两个子任务时，预算分账、证据聚合、join 策略可验证；杀死一个 Worker 后 Task Run 增加、旧 epoch 写回被拒；子任务 submitted 但父任务未 accepted 时不能标根任务完成；跨组织 A2A 调用的配额与审计独立于内部子 Agent。
4.5 缺口五：网关治理语义与严格预算（第 9 章）
定位：平台 03 篇把网关当"入口 + 路由 + 限流"，这不够。白皮书要求区分三种治理粒度：LLM Gateway（模型调用）、MCP Gateway（工具调用）、Agent Gateway（任务），并明确"哪些能承诺、哪些不能"。
三个网关，三种粒度
| 网关 | 治理对象 | 主要职责 | 不能做什么 |
|---|---|---|---|
| LLM Gateway | 一次模型调用 | 协议适配、模型/端点选择、路由、降级、限流、Token 计量 | 不能替应用判断任务难度；不能单独保证严格预算 |
| MCP Gateway | 一次工具调用 | Server Registry、协议代理、工具级 ACL、凭证托管、参数校验、审计 | 不能替代运行时工具策略；不能凭"能连到"当"有权调" |
| Agent Gateway | 一个任务 | Agent 路由、会话连续性、租户配额、任务预算、入口审计 | 不能判断执行结果；不能持有任务状态权威 |
模型选择与端点选择要分开：模型决定能力与价格，端点决定区域、版本、健康与容量。把两者合成一个 model 字段，降级时会出现"能力等价但区域不合规"或"区域合规但窗口不够"。
错误分类先于重试
重试前必须回答三件事：错误是否可重试、重试目标是否等价、重试会不会放大副作用。分类至少包括：认证/配额（不可重试）、参数/Schema（修正后新建）、限流（按 Retry-After）、上游 5xx（可重试）、超时（区分"未发送/已发送未提交/已提交响应丢失"）、内容安全（不可重试）。
跨层重试预算会相乘：网关 3 次 × 应用 3 次 = 最多 9 次上游调用。必须在任务账本或 Budget Service 里设全局 attempt 预算，各层重试共享，不能各算各的。
超时分类：排队超时、连接超时、首 Token 超时、流空闲超时、总超时、工具执行超时。只设一个"总超时"，排障时分不清是排队、模型慢还是工具卡住。
严格预算：插件不够，必须有预算服务
Higress 的 ai-token-ratelimit 是"请求前检查窗口、响应后累计"，ai-quota 是"准入查余额、响应后扣减"。两者都不能单独承诺严格并发上限：余额 100、两个最大消耗 80 的请求同时通过检查，最终可能消耗 160。
text
可用额度 = 已授权额度 − 已结算消耗 − 在途预留
准入条件 = 本次最大可计费消耗 ≤ 可用额度检查和预留必须在同一原子操作或等效事务中完成；结束后按实际消耗幂等结算，释放多余预留。预留要覆盖输入、受约束的最大输出与该接口其他计费项；重试单独占额；流式中断或结果未知不能因租约到期就无条件退款，要先确认终止或按保守规则等待对账。
平台落点：Higress 负责准入与计量上报，Budget Service 负责授权、预留、结算、对账；两者通过 budget_lease_id 关联。网关插件故障时的分支要逐项验证，不能概括为统一失败语义。
MCP 准入四步链
text
认证（谁） → 协议校验（是不是合法 MCP 请求） → 授权（这个主体能否调这个工具/参数） → 转发四条不可绕过条件：默认拒绝；注册中心/市场/Agent Card 的可见性不构成授权；协议元数据不是调用者身份证明；工具级 ACL 必须在转发前判定，不能只靠网络隔离。
审批：挂起 + 重新准入，不自动降级
高风险动作进入审批时，请求应挂起并释放资源；批准后重新走完整准入链（身份、配额、预算、策略），不能拿"审批通过"当一次永久通行证。审批不能自动降级为只读继续执行——用户批准的是"这个动作"，不是"类似动作都可以"。
审计 ≠ 业务证据：审计记录"谁在何时对什么做了什么、依据哪条策略"，业务证据记录"业务结果是否达成"。两者要关联，但不能互相替代。
验收：并发两个请求不能突破授权额度；9 次重试共享一个 attempt 预算；MCP 未订阅调用 403；审批通过后重新校验预算与权限；网关插件故障时按声明的分支处理并可对账。
4.6 缺口六：Agentic OS 的受管对象与证据状态（第 30 章）
定位：平台方向正确，但"已具备 OS 雏形"说得过早。第 30 章要求九个受管对象、Evidence 三态、三层边界与四类接入等级；平台已落实身份、Session、Workspace、Skill、Tool/MCP、Policy 六项，Run 还缺 attempt/release 字段，Evidence 仍只是任务记录里的 JSON 字段，Budget Lease 完全缺失；此外缺"强制边界 vs 观察边界"的判定方法。
九个受管对象
| 对象 | 平台落点 | 状态 |
|---|---|---|
| Agent 身份 | 02/07/15 | ✅ |
| Run | 22 + 新增 task_run | 🟡 需补 attempt/release |
| Session | 12 + 22 | ✅ |
| Workspace | 12/21 | ✅ |
| Skill | 19/Nacos | ✅ |
| Tool/MCP endpoint | 19/Higress | ✅ |
| Budget Lease | 无 | ❌ 按 §4.4 新增 |
| Policy | 15 + Nacos | ✅ |
| Evidence | 22 的 completion_evidence | 🟡 需升级为一等对象 |
Evidence 三态
| 状态 | 含义 | 谁写 | 用途 |
|---|---|---|---|
| planned | 任务开始时声明"完成需要哪些证据" | 任务创建/规划 | 防止事后挑证据 |
| issued | 证据已产生并带稳定引用 | 执行者/工具/渠道 | 可校验、可追溯 |
| confirmed | 验收方确认证据充分 | 业务/Verifier | 支撑 accepted |
sql
CREATE TABLE rt.evidence (
evidence_id text PRIMARY KEY,
task_id text NOT NULL,
criterion_key text NOT NULL,
state text NOT NULL CHECK (state IN ('planned','issued','confirmed')),
kind text NOT NULL CHECK (kind IN ('artifact','test','receipt','approval','observation')),
ref text NOT NULL,
sha256 text,
issued_by text,
confirmed_by text,
confirmed_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now()
);强制边界 vs 观察边界：只有"完整路径覆盖 + fail-closed + 负向测试"三者都成立，才是强制边界；否则只是观察边界。举例：只记录工具调用日志，是观察；工具调用必须经过 Toolkit 且未授权直接失败，才是强制。平台要逐条标注每个控制点属于哪类，不能把"有日志"写成"已管控"。
四类接入等级
| 等级 | 含义 | 平台示例 |
|---|---|---|
| 外部边界强制 | 在系统边界上强制执行，无法绕过 | Higress 认证/配额、K8s NetworkPolicy |
| 包装中介 | 通过包装层拦截，绕过包装即失效 | Toolkit 工具策略、MCP Router |
| 仅观察 | 只记录，不阻断 | OTel、审计日志 |
| 不支持 | 当前无法覆盖 | 个人助理直连本机 Shell |
三层边界与六个标准接口
| 层 | 回答什么 | 平台组件 |
|---|---|---|
| Agent 运行服务层 | 一次 Run 如何创建、调度、恢复、终止 | 07 Service + 22 任务账本 + 06 内核 |
| 系统承载层 | 身份、隔离、资源、网络、数据保留如何被执行 | 02/15 + 21 + K8s + Vault |
| 治理证据层 | 谁授权、消耗多少、结果凭什么被接受 | 03 网关 + Budget Service + 14 OTel/审计 + rt.evidence |
六个标准接口是"OS 化"的最小公约数；没有它们，每个 Agent 都会长出自己的私有控制面：
| 接口 | 作用 | 平台落点 |
|---|---|---|
| Run API | 创建、查询、取消、恢复一次执行 | 22 的 /v1/tasks |
| Session API | 会话、轮次与上下文组织 | 07 的 Session/Turn |
| Tool/MCP API | 能力发现、Schema、调用与结果 | 19 + MCP Gateway |
| Policy API | 判定谁能对什么做什么 | 15 + 策略存储 |
| Budget API | 授权、预留、结算、对账 | §4.4 的 gov.* |
| Evidence API | 计划、签发、确认证据 | §4.6 的 rt.evidence |
第 30 章仍留了七个开放问题：跨组织身份互认、长任务跨运行时迁移、证据格式标准化、跨域预算结算、沙箱逃逸检测、模型能力等价、边缘与中心一致性。平台不需要现在全解，但要在架构里留出扩展点，不能把当前实现写成"已解决"。
自主性分级 L1–L5（建议 → 需批准 → 限定范围自动 → 宽范围自动 → 自进化）要与权限、预算、审计匹配；高自主性不是目标，匹配任务风险才是。
验收：九个对象都能回答"谁创建、谁修改、何时失效、证据在哪"；Evidence 三态可追；每个控制点标明强制/包装/观察；负向测试能证明"绕过包装会失败"。
4.7 缺口七：调优闭环（第 17–24 章）
定位：平台把"评测"做扎实了，但没有数据飞轮。第 16 章是仿真，第 18–23 章才是优化：Trace → Trajectory → Pipeline → Dataset → Evaluator → Experiment → Patch → Release。上一版把两者混在一起，导致既没有仿真台，也没有轨迹与实验层。
最小闭环（完整见 26 篇）：
text
生产 Trace + 任务账本 + 产物
→ Trajectory（一次 Task Run 一行，工具请求与结果配对）
→ Pipeline（投影/过滤/组装/去重/采样）
→ Dataset（candidate → golden，题目 + rubric + split）
→ Evaluator（规则/LLM/Agent，先试评校准）
→ Experiment（四格对照、固定配置、五道门禁）
→ Patch（按归因选择：上下文/工具/状态/循环/Verifier/模型）
→ Release（六要素冻结、灰度、回滚）五条硬规则：
- 归因顺序：先环境、再 Harness、最后模型；
- 独立性：调优题与验证题分开，验证集用一次消耗一次；
- 阈值预注册：门禁阈值在看结果前确定；
- 单位成功任务成本：失败与重试成本计入分子；
- 采用四确认：改善、不退化、代价可接受、实际生效。
验收：一段真实轨迹能变成一道带 rubric 的黄金题；低分题能归到一类并给出首选 Patch；同一批题新旧两版可对照；退化能被发现；Release 可一键回滚。
五、执行体形态矩阵（源码已验证）
平台执行面不是"一个 AgentScope Java 内核"，而是三类执行体。源码验证结果：AgentSpec.Type ∈ {Declarative, BYO}，Runtime ∈ {agentscope-java, agentscope-go, custom}，这是官方扩展点。
| 形态 | 典型实现 | 信任边界 | 平台接入 | 管控重点 |
|---|---|---|---|---|
| 个人工作助理 | agentscope-paw（HarnessAgent + LocalFilesystemWithShell） | 本人身份、本机 FS+Shell、不隔离 | 13 渠道 + 17 Hub | 托管化：租户/会话/沙箱/审计；凭据进 Vault；产物进 S3 |
| 编码 Agent | OpenCode | 需出网、读写仓库、执行命令 | 15 工具策略 + 21 沙箱 + 09 Jev | diff 审批、仓库权限、出网白名单、全量审计 |
| 定制业务智能体 | AgentScope Declarative/BYO | 企业内受控 | 06 + 07 + 08 | 版本/命名空间/发布走控制面；状态权威在数据面 |
三种形态的合缝关键：
- 统一入口：都从 Higress 进，外部用户不感知执行体类型；
- 统一任务语义：一次会话/编码/业务任务都收敛到 22 的任务状态机，预算、证据、恢复一致；
- 统一资产供给：Skill/MCP/模型都走 19 与 Nacos，不各自造目录；
- 差异只留在执行边界：由
IsolationScope + SandboxSpec + 出网策略表达； - BYO 是定制通道：已有 Harness 用
BYOOverrides + HealthProbeRef挂入，获得同等发布与观测能力。
验收：三类执行体同命名空间共存；同一任务状态机跨形态一致；个人助理托管后不直连本机 Shell；OpenCode 的 diff 可审计可回滚；BYO 与声明式门禁一致。
六、源码验证结论
2026-10 对核心组件做浅克隆验证（--depth 1），原则是：字段名以所选版本源码为准；能坐实的直接写，不能坐实的标注"待确认"。
6.1 仓库与版本基线
| 组件 | 仓库 | 状态 | 文档篇目 |
|---|---|---|---|
| AgentScope Java | agentscope-ai/agentscope-java | ✅ 活跃 | 06 |
| AgentScope Service | 同仓库 agentscope-service/ | ✅ 存在 | 07 |
| AgentScope Runtime | agentscope-ai/agentscope-runtime-java | ✅ 存在 | 21 |
| HiMarket | higress-group/himarket | ✅ 存在 | 04 |
| HiRoute | higress-group/HiRoute | ✅ 存在 | 05 |
| Higress | higress-group/higress | ✅ 存在 | 03 |
| Nacos | alibaba/nacos | ✅ 存在 | 08 |
| RocketMQ | apache/rocketmq | ✅ 存在 | 10 |
关键更正：aistiod/TaskStateStore/LeaseManager 未在 agentscope-java 命中；控制面实际是 Go 实现的 CRD 风格 API（service-controlplane/api/v1alpha1），执行面是 Java，两者通过 api/v1alpha1 契约通信。07 篇的字段级细节应引用 agent_types.go。
6.2 坐实结果
| 接缝 | 文档声称 | 源码 | 结论 |
|---|---|---|---|
| 内核 builder | HarnessAgent.builder()、stateStore()、enablePlanMode()、prepareRun(msgs,ctx) | 全部命中 | ✅ |
| 沙箱隔离 | IsolationScope 四值 | IsolationScope.java 一致 | ✅ |
| 调度 SPI | AgentScheduler | 扩展模块存在 | ✅ |
| 控制面定义 | Declarative/BYO、Skills/Subagents/Tools | agent_types.go 命中 | ✅ |
| 市场↔注册 | nacosRefConfig/higressRefConfig | ProductRef.java 命中 | ✅ |
| 路由决策 | model.capabilities、revision | defaults.rs 命中 | ✅ |
| 个人助理 | agentscope-paw | README 明确"需托管用 service" | ✅ |
6.3 待确认
| 表述 | 状态 | 处置 |
|---|---|---|
aistiod、TaskStateStore、LeaseManager | ❌ 未命中 | 控制面按 Go CRD 写；商业版命名单独标注 |
| mem0 具体 API | ⚠️ 有扩展模块，未逐类验证 | 以模块源码为准 |
| Skill ZIP 10MB 上限 | ⚠️ 流程已坐实、数值待查（Nacos SkillUploadPrecheckResult 原生预检，见 §6.5.3） | 支线配置；预检码与版本动作以 Nacos 为准 |
| LiteTopic 父主题语义 | ✅ 已坐实 | toLmqName → %LMQ%$parent$liteTopic；源码注释明确 has no retry topic |
6.4 LiteTopic 关键约束
| 源码事实 | 位置 | 平台含义 |
|---|---|---|
LITE_TOPIC_PREFIX = %LMQ% | LiteUtil.java:27 | 命名前缀坐实 |
toLmqName(parent, lite) | LiteUtil.java:40-44 | 父主题=命名空间，子主题=会话/任务类型 |
| "has no retry topic" | LiteUtil.java:30 | 重试必须靠 Worker 租约 + 幂等，不能依赖 MQ |
setLiteTopicExpiration | TopicConfig.java:221 | TTL 是任务最后期限载体 |
LiteLagInfo.liteTopic | proxy DTO | 位点按子主题管理，挂掉后不回退 |
推论：重试不依赖 LiteTopic 自带 retry；父子主题归属用 belongsTo 保证消费端只认本租户本类型；TTL 与 deadline_at 配合做超时回收；位点不回退 + 租约转移实现至少一次。
验证边界：未做全量编译与运行验证；字段级结论以 2026-10 最新 commit 为准。
6.5 源码合缝复核（第二轮，2026-10-25）
范围：2026-10-25 将核心组件浅克隆至 C:\Users\Administrator\Desktop\02-项目代码（SSH 协议，--depth 1），对照 §三.1 的 22 条接缝逐条复核。原则：字段以所选 commit 源码为准；本节只记 6.1–6.4 之外的增量结论。
6.5.1 本轮拉取基线
| 组件 | 仓库 | commit（2026-10-25） | 文档篇目 |
|---|---|---|---|
| AgentScope Java | agentscope-ai/agentscope-java | 8eb91158 | 06/07 |
| AgentScope Runtime | agentscope-ai/agentscope-runtime-java | 7b9032b | 21 |
| HiMarket | higress-group/himarket | 3a63fc5 | 04 |
| HiRoute | higress-group/HiRoute | feae7f3 | 05 |
| Higress | higress-group/higress | 36f2f1a | 03 |
| Nacos | alibaba/nacos | 7f71d44 | 08 |
| RocketMQ | apache/rocketmq | 8ab8191 | 10 |
6.5.2 新增坐实证据
| 接缝 | 文档声称 | 源码证据（本轮） | 结论 |
|---|---|---|---|
| 5 内核→状态/工作区 | IsolationScope 四值 + ConflictPolicy.FAIL | IsolationScope.java（SESSION/USER/AGENT/GLOBAL；USER 默认、缺 userId 回退 SESSION）；ConflictPolicy.java（OVERWRITE 默认 / FAIL / APPEND_MERGE） | ✅ 存在；FAIL 须显式配置（见 6.5.4） |
| 7 内核→模型网关 | 能力等价结果 | HiRoute defaults.rs scoped_capability 按 model_configuration_id / upstream_model_id / upstream_protocol / connector_id+revision / endpoint_profile_id+revision 六维匹配；model.capabilities + SourceDefaultPreferencesV1 | ✅ 可直接复用，从"平台补"降级为"调用" |
| 10 任务派发 | LiteTopic 无自带重试 | LiteUtil.java 复核：LITE_TOPIC_PREFIX、toLmqName、belongsTo、"has no retry topic" | ✅ 与 6.4 一致 |
| 11 市场↔注册中心 | nacosRefConfig/higressRefConfig | ProductRef.java：另有 apigRefConfig / adpAIGatewayRefConfig / apsaraGatewayRefConfig + apiConfig / mcpConfig / agentConfig / modelConfig + apiDefinitionId / enabled / sourceType；POST /api/v1/products/{productId}/ref | ✅ 命中且字段组比文档宽（04/19 需扩表） |
| 12 注册中心→运行时 | namespace+type+name+version、label、endpoint、schema | Nacos McpServerVersionDetail："Canonical APIs identify MCP resources only by namespace, name, and exact Version"；labels / owner / scope / editingVersion / reviewingVersion / onlineCount | ✅ 原生标识规则坐实 |
| 2 Higress→内核 | traceparent 传递 | higress plugins/wasm-go/mcp：sse_proxy / proxy_outbound / proxy_integration 全链路转发 traceparent | ✅ trace 原生；身份头剥离是平台插件（6.5.4） |
| 14 运行时→OTel | OTel 集成 | agentscope agentscope-dependencies-bom/pom.xml：opentelemetry 1.66.0 + reactor instrumentation + semconv | ✅ 依赖级坐实（span 语义以扩展模块为准） |
6.5.3 Nacos 原生 AI 资源目录（对 §四.4.3 的字段级支撑）
nacos api/ai/ 已具备完整资源模型，§四.4.3 的"五类资源"几乎全部原生覆盖，平台不应自建同名目录：
| §四.4.3 资源 | Nacos 原生模型（nacos-api api/ai/） | 平台落点 |
|---|---|---|
| Prompt | PromptService、Prompt / PromptVariable / PromptVersionInfo / PromptMetaInfo | 08 篇 Resolver 直接消费 |
| Skill | SkillService、Skill / SkillMeta / SkillResource、SkillUploadPrecheckResult（READY / VERSION_ADJUSTED / DRAFT_EXISTS / REVIEWING_EXISTS / NO_PERMISSION / NOT_A_SKILL / INVALID_SKILL + CREATE_DRAFT / OVERWRITE_DRAFT / DELETE_DRAFT_AND_CREATE）、BatchUpload | Skill Loader 对接原生上传/预检 |
| MCP Server | McpService、McpServer 全套（BasicInfo / DetailInfo / Draft / Import / Labels / Version / RemoteServiceConfig / Validation）、McpServiceRef / McpTool / McpToolSpecification | Registry/Router 直接发现 |
| Agent（A2A） | AgentService / AgentDiscoveryService（搜索/订阅/Watch）、AgentCard（A2A 1.0.0，capabilities / skills / SecurityScheme）、AgentEndpoint / AgentVersion / AgentDraft / AgentPublish | ARD 发现、RAD 解析端点 |
| AgentSpec | AgentSpecService、agentspecs 全套（AgentSpec / AgentSpecResource / AgentSpecMeta） | 构建/部署/启动解析 |
另原生含：AI 资源导入（AiResourceImport*）、Pipeline（Checkpoint / PipelineExecution）、A2aService、AgentTransportMode、Agent 端点注册（AgentEndpointRegister/Deregister、RuntimeEndpointSnapshot）。
结论：§四.4.3 的"资源中心六组件"应映射为 Nacos 原生 Registry + 平台只做投影/策略/缓存；Asset Catalog 保持只读投影不变；08/19 篇补充上述原生模型名，避免自造目录与第二份真相。
6.5.4 本轮修正（影响既有结论）
- ConflictPolicy 默认 OVERWRITE：接缝 5 的
ConflictPolicy.FAIL必须显式配置，不是默认值（ConflictPolicy.java）。 - IsolationScope 沙箱是"顺序复用、非活共享"：并发同 scope 各自容器，调用结束收敛到最后快照（
IsolationScope.javaConcurrency note）。平台"会话级沙箱复用"表述应注明该语义，接缝 8 的快照/租约设计不受影响但表述要准确。 - HiRoute 能力等价可直接调用：
scoped_capability六维匹配原生提供"能力等价结果"，接缝 7 从平台补降级为直接复用。 - Higress 身份头语义是平台插件：开源仓只原生转发 traceparent；
external_user_id→subject、idempotency_key的注入/剥离/重校验全部写入平台自定义插件（接缝 1/2 的网关部分）。 - Skill ZIP 状态升级：§6.3 原"未验证"升级为——预检流程原生坐实（
SkillUploadPrecheckResult），10MB 上限数值待查 Nacos server 端。
6.5.5 修订清单增量（并入 §九）
| 篇目 | 增量 | 优先级 |
|---|---|---|
| 08/19 | Nacos 原生 api/ai 模型名对照（6.5.3）；Resolver / Loader 对接原生 API 而非自建 | P0 |
| 04 | ProductRef 五组网关 Ref + 四类产品配置扩表；接缝 11 对账字段扩展 | P1 |
| 23 | 术语表补充：MCP Server Canonical 标识（namespace+name+exact version）、Skill 预检码、A2A AgentCard | P1 |
验证边界：本轮未做全量编译与运行验证；Nacos api/ai 为 API 层证据，server 端行为（如 10MB 校验、评审流转）待运行验证。
6.5.6 agentscope-service 控制面原生能力复核（第三轮，2026-10-25）
教训（方法论修正）：6.5.1–6.5.5 的 22 条接缝核对是源码级、字段级，但当时对 agentscope-java 的 agentscope-service 模块只核了 A2A/协议相关字段，未按"完整控制面平台"深核——导致把控制面误判为"无认证透传层"，且 G9/G10/G12 等一批"平台补"实为原生已有。此后统一认知：agentscope-service = 控制面平台（自带登录/用户体系/任务模型/持久化），agentscope-runtime-java = 数据面执行引擎，两者分层核对。
控制面原生能力清单（源码坐实）：
| 模块 | 原生能力 | 关键证据 |
|---|---|---|
| service-gateway（Java） | Session API 网关：登录、Session/Turn、events 流、snapshot、actions | GatewayApp；v2 文档 service-api |
| service-common（JPA） | 用户体系 UserEntity/JpaUserStore；托管会话 ManagedSessionEntity；记忆+版本化 MemoryEntity/MemoryVersionEntity/MemoryStoreEntity；事件 outbox+幂等 fence SessionEventOutboxEntity/SessionEventFenceEntity/SessionEventEntity；HITL 动作/Turn 命令 SessionActionCommandEntity/SessionTurnCommandEntity；协调器 CoordHitlTicketEntity/CoordLeaseEntity/CoordWorkerHeartbeatEntity/CoordWorkItemEntity；Vault VaultEntity/VaultCredentialEntity；部署/环境 DeploymentEntity/EnvironmentEntity；共享/市场 ResourceShareEntity/UserMarketplaceEntity | 实体+Repository 源码 |
| service-controlplane（Go/K8s Operator） | 声明式控制面：CRD agent/mcpserver/modelconfig/sandboxclaim + webhook/RBAC + runtime-host | api/v1alpha1/*.go、config/crd |
| service-scheduler（Java） | 定时调度 CronDeploymentScheduler；渠道桥 ChannelWorkBridge（飞书回调原生）、ManagedSessionChannelBridge；出站工具 OutboundService；SchedulerSecurityConfig | 源码类清单 |
与 G 台账的映射（"平台补"→"原生已有，改为对齐+确认"）：
| 缺口 | 原生对应（源码） | 动作 |
|---|---|---|
| G9 人机契约 | CoordHitlTicketEntity + SessionActionCommandEntity（HITL 工单 + 动作命令） | 22 篇 §十八 改为对齐原生（request_id/deadline/会签语义对照） |
| G10 系统身份 | UserEntity/JpaUserStore + Application API key scopes（invoke/read/interact/cancel/webhooks:write，调用权与审批权分离） | 15 篇 §七 改为对齐原生 |
| G12 异步受理 | SessionEventOutboxEntity/SessionEventFenceEntity（outbox + 事件幂等 fence 原生） | 22 篇 §十七 改为对齐原生（表结构可直落原生实体） |
| G1 闲置回收 | CoordLeaseEntity/CoordWorkerHeartbeatEntity（协调器租约 + 心跳） | 21 篇 §十一 对照复核 |
| G3/G11 记忆/压缩 | MemoryEntity/MemoryVersionEntity/MemoryStoreEntity（记忆 + 版本化原生） | 26 篇 §十二 / 12 篇 §十一 对照复核 |
| G5 组织化 | CoordWorkItemEntity/CoordWorkerHeartbeatEntity（协调器工单/心跳，远期） | 保持延后，复核时对照 |
复核计划（证据分级升级，按序执行）：A. 控制面原生能力清单（已完成，本小节）；B. G9/G10/G12 对齐复核（字段/状态逐条对照原生实体与 v2 文档）；C. G11/G3 记忆与压缩原生语义复核（MemoryVersion 语义 vs 压缩契约）；D. G1/G5 协调器（CoordLease/Heartbeat/WorkItem）对照；E. 逐篇回写对齐结果并更新 47 台账。
证据分级标准（此后强制）：源码级（字段/类/文件可定位）＞文档级（官方 v2 文档/README 自述）＞设计级（平台自设计）。凡"平台补"必须先查原生是否有，再落设计。
6.5.7 agentscope-service 存储拓扑（数据落盘位置，源码级）
统一持久层 PostgreSQL 17，按 schema 分域（deploy/compose.yaml + service-dataplane/application.yml 坐实）：
| 数据 | 存储位置 | 证据 |
|---|---|---|
| 每轮对话消息（会话历史正文） | runtime 侧 SessionHistoryService：InMemory（默认，进程重启即丢）／Redis／TableStore(阿里云) 三选一 | runtime SessionHistoryService 接口 + 三个实现类 |
| 会话事件/动作/outbox（Session/Turn/Event/Action/Fence） | PG dp schema（ManagedSessionEntity/SessionEventEntity/SessionEventOutboxEntity/SessionEventFenceEntity/SessionActionCommandEntity） | service-common JPA 实体 + currentSchema=dp |
| 用户/记忆/Vault | PG dp schema（UserEntity/MemoryEntity/MemoryVersionEntity/VaultCredentialEntity，Vault 凭据 AES-GCM 主密钥加密） | 同上 + BUILDER_VAULT_MASTER_KEY |
执行状态（execution_attempts/hosts/pools） | PG rt schema（CONTROL_PLANE_STORAGE_DSN ... search_path=rt） | compose CONTROL_PLANE_STORAGE_DSN |
| 控制面资源（Agent/Team/Workflow CRD 状态） | PG cp schema（"Control-plane tables live in cp"） | dataplane application.yml 注释 |
| 工作区/产物 | 本地卷 /data/workspaces、/data/artifacts（E2B 云沙箱 TAR 持久化） | compose CONTROL_PLANE_WORKSPACE_ROOT/ARTIFACT_ROOT |
| 沙箱运行态 | runtime sandbox redis-extension（RedisSandboxMap，可选） | sandbox-extensions 源码 |
分域纪律（源码注释坐实）：dataplane 只碰 dp，控制面表走 ControlPlaneClient，禁止跨 schema SELECT；平面间调用用 X-Builder-Internal-Token；JWT secret 控制面/dataplane 共享（用户 token 同一套）；多副本协调默认 JDBC 表（coord.turn-lease-ttl-seconds:90，可换 Redis CoordinationStore）；SSE 通知驱动 + 30s recovery 兜底（支持 LISTEN/NOTIFY）。
与 22 篇的关系（重要）：我们 22 篇设计的 rt.agent_task/rt.execution_attempts 命名与原生 rt schema 完全吻合（rt.execution_attempts 含 lease_owner/lease_token/fencing_token/lease_expires_at/heartbeat_at/cancel_requested_at——G1/G2 依赖的租约/栅栏字段原生已在）；"每轮对话"两个视图：消息正文在 runtime 存储（默认内存，需按部署选 Redis/TableStore 才持久），控制面 PG 只存事件流（审计/恢复/跨端靠事件，不靠消息原文）——链路 1/2"会话历史权威"的落点据此修正：权威在控制面事件流，消息原文持久化是 runtime 部署配置决策。
6.5.8 mem0 API 逐类验证（G8 销号，2026-10-25 源码级）
拉取 mem0（git@github.com:mem0ai/mem0.git，SSH）对照 mem0/client/main.py 与 agentscope-runtime 适配层 Mem0MemoryService：
mem0 Client 原生 API（源码坐实）：
| 类 | 端点 | 说明 |
|---|---|---|
| 写 add | POST /v3/memories/add/ | 消息写入，messages + user_id/agent_id/app_id/run_id |
| 读 get | GET /v1/memories/{id}/ | 单条 |
| 读 get_all | POST /v3/memories/ | 批量，filters AND + 分页 |
| 检索 search | POST /v3/memories/search/ | query + filters AND + top_k + rerank |
| 改 update | PUT /v1/memories/{id}/ | 更新（适配层未封装） |
| 删 delete | DELETE /v1/memories/{id}/（支持 delete_linked 级联） | 单条 |
| 删 delete_all_memories | DELETE /v1/memories/ | 按实体批量删（适配层未封装） |
| 史 get_memory_history | GET /v1/memories/{id}/history/ | 记忆历史（适配层未封装） |
| 健 v1/ping、实体 v1/entities | GET | 连通性、用户/Agent 枚举 |
agentscope 适配层 Mem0MemoryService（agentscope-runtime 源码）：封装 add/search/get_all/delete 四类，user_id 必带 + run_id 可选 + org_id/project_id；但调用的是 v1/v2 旧端点，且缺 update/delete_all/history。
验证结论：
- 写读/检索/删除接口原生齐备，G8 销号；接入映射：
user_id→sub、agent_id→Agent、app_id→Application（G10）、run_id→session/turn； - 版本漂移风险（平台要处理）：适配层用 v1/v2 端点，mem0 最新 client 用 v3——上线前须确认 api.mem0.ai 的 v1/v2 兼容期，或将适配层升级到 v3；
- 能力缺口：update/delete_all_memories/get_memory_history 适配层未封装，画像蒸馏（G3）的冲突修正与记忆回滚可直用原生 update/history；
- 记忆归属按实体四维隔离，与 15 篇 §九 身份三态映射一致。
6.5.9 源码证据总索引（结论 ↔ 源码位置 ↔ 沉淀位置，审核链）
为什么建：源码调研结论若只存在于对话里，没有沉淀就没有人（包括后续的我们自己）能审核。本索引把每条源码级结论钉在"证据位置"与"沉淀位置"两处，任何人可顺着索引复核；新调研结论必须先入本索引再落文档。
证据分级：源码级（可定位到文件+行）＞文档级（官方 v2 文档/README 自述）＞设计级（平台自设计）。
| # | 结论（一句话） | 源码/文档证据位置 | 沉淀位置 | 状态 |
|---|---|---|---|---|
| E1 | Higress 原生 oidc 插件可指企业 IdP（授权码/refresh/logout/CSRF/cookie） | higress\plugins\wasm-go\extensions\oidc\README.md | 15 篇 §八 | ✅ 已沉淀 |
| E2 | Nacos 鉴权插件化（按 nacos.core.auth.plugin.auth.type 装载） | nacos\core\...\auth\AuthPluginTypeResolver.java | 15 篇 §八 | ✅ 已沉淀 |
| E3 | RocketMQ 5.x auth 可插拔（Provider/Strategy，Stateful/Stateless） | rocketmq\auth\...\AuthenticationProvider.java、AuthenticationStrategy.java | 15 篇 §八 | ✅ 已沉淀 |
| E4 | 控制面 agentscope-service 自带登录体系（Bearer token + Tenant/Namespace + inspect/edit/publish；Application scopes：invoke/read/interact/cancel/webhooks:write，调用权与审批权分离） | agentscope-java service-gateway/service 模块 + v2 zh 文档 service-api/api-reference/access.md | 15 篇 §九、47 §8.7、24 §6.5.6 | ✅ 已沉淀 |
| E5 | 数据面 runtime 无内置认证，metadata.userId 透传且缺省 default_user（可伪造） | agentscope-runtime\web\...\ResponseApiHandler.java 182–185；protocol\a2a\GraphAgentExecutor.java 99–100 | 15 篇 §九（安全关键点）、47 §8.7 | ✅ 已沉淀 |
| E6 | 数据面组件 ctx.user 是 stub（user_id=default），身份做实为待办 | 集成方案 docs\design\2026-09-04-integration-strategy.md 行 75/121 | 15 篇 §九 | ✅ 已沉淀 |
| E7 | 控制面 JPA 实体全家（user/session/event/outbox/fence/turn_command/coord_hitl/coord_lease/coord_worker/coord_work/memory/memory_version/memory_store/vault） | agentscope-service service-common\...\persistence\jpa（§6.5.6 实体清单） | 15 §七、21 §十/§十一、22 §十七/§十八、12 §十一、26 §十二 | ✅ 已沉淀 |
| E8 | 存储拓扑：PG17；dp/rt/cp 三 schema；Vault AES-GCM；X-Builder-Internal-Token；workspace/artifacts 卷；E2B TAR | deploy\compose.yaml、service-dataplane application.yml | 24 篇 §6.5.7 | ✅ 已沉淀 |
| E9 | rt.execution_attempts 原生租约/栅栏字段（lease_owner/fencing_token/…） | compose CONTROL_PLANE_STORAGE_DSN（§6.5.7） | 21 篇 §十/§十一 | ✅ 已沉淀 |
| E10 | 会话消息正文存储三选一（InMemory 默认/Redis/TableStore，默认不持久） | engine-core\...\SessionHistoryService.java | 24 篇 §6.5.7 | ✅ 已沉淀 |
| E11 | mem0 四类接口齐备 + v1/v2 与 v3 版本漂移 + update/history 可直用 | mem0\client\main.py（v3 add/search/get_all、v1 delete/update/history） | 24 篇 §6.5.8 | ✅ 已沉淀 |
| E12 | Team 原生模型（Leader/members role+instructions/policy、Run 快照、coordinator node、agent-tasks 协议带 expectedVersion+任务凭据、Issue 协作、用户组≠Team 编排） | agentscope-java v2 zh create-team.md/team-configuration.md + /api/v1/teams | 47 篇（原 29 篇 Team 专题并入）§二、47 台账 G5 | ✅ 已沉淀 |
| E13 | 编排原生三形态（Subagent/Team/Workflow + orchestration-runs pause/resume/cancel；Workflow 节点可调 Agent/Team） | v2 zh orchestration.md/workflows.md | 47 篇（原 29 篇）§三、47 台账 G6 | ✅ 已沉淀 |
| E14 | ConflictPolicy 需显式 FAIL（防覆盖） | agentscope-java 内核（§6.5.4-1） | 47 §8.4、21 篇 | ✅ 已沉淀 |
| E15 | SubagentSpec.WorkspaceMode ∈ {isolated, shared} | agentscope-java 内核源码 | 47 §1.2/§8.4、11/22 篇 | ✅ 已沉淀 |
| E16 | Nacos 原生 AgentCard/A2aService/SkillService 全套 AI 资源面 | §6.5.3（nacos api/ai 目录） | 47 §7.1、08/19 篇 | ✅ 已沉淀 |
| E17 | Higress mcp 代理 + external_user_id 语义 | higress\plugins\...\mcp\server | 47 §7.1 | ✅ 已沉淀 |
| E18 | coord.turn-lease-ttl-seconds:90 + SSE 通知 + 30s recovery + LISTEN/NOTIFY | service 配置（§6.5.7） | 22 篇 §八 | ✅ 已沉淀 |
审核纪律（此后强制）：①任何"源码级/原生"论断必须在 §6.5.9 有编号条目，否则按未坐实处理；②证据位置必须可定位（文件路径+行号或文档页），不给"官网有"这类无定位证据；③结论落文档时回填"沉淀位置"，一处结论多处引用时逐处标注；④逐篇审核以本索引为清单，索引没有的结论视为未审核。
七、装配顺序与实施路线
在白皮书五阶段（架构设计 → 构建 → 运行 → 治理 → 调优）与平台 16 的六切片之上，增加 S7 仿真、S8 调优两个切片。原则：每片独立验收、独立回滚，稳定一周再开下一片。
| 阶段 | 切片 | 交付 | 对应白皮书 | 验收 |
|---|---|---|---|---|
| 架构设计 | S0 | 三平面归属表、权限边界、影响半径评估、Release 六要素模板 | 第 2 章 | 每个 Agent 能回答"长在哪、谁能改、失败谁恢复" |
| 构建 | S1 | 身份与入口：Higress 路由/消费者/配额；主体映射 | 第 3、6、14 章 | 伪造租户被拒；配额生效 |
| 构建 | S2 | 内核与状态：单 Agent、Redis 状态、S3 快照 | 第 5、7、8 章 | 换节点会话续；工具结果可追 |
| 运行 | S3 | 控制面：Service 目录、Session API、Endpoint、Release 冻结 | 第 3、15 章 | Dataplane 重启后会话继续；Release 可回滚 |
| 运行 | S4 | 任务：Scheduler、Outbox、LiteTopic、Worker、Task Run | 第 4、10、11 章 | 重投只执行一次；父子任务预算可聚合 |
| 运行 | S5 | 供给与路由：HiMarket、Nacos 资源中心、HiRoute、Jev | 第 9、15 章 | 订阅/发现/准入分别可验证；严格预算可证 |
| 治理 | S6 | 证据与治理：OTel、事件日志、审计、黄金集、门禁 | 第 13、14 章 | 任一回答能还原 span 树；审计可追责 |
| 治理 | S7 | 仿真台：Scenario/Manifest/Run/Result、两个模拟器、故障注入 | 第 16 章 | SUT 边界不被替换；证据不足输出"不可判定" |
| 调优 | S8 | 调优闭环：Trajectory/Pipeline/Dataset/Evaluator/Experiment | 第 17–24 章 | 轨迹→题→实验→Release 可追；退化能发现 |
实施依赖：S0 必须先于 S1；S7 依赖 S2/S5（沙箱、模型网关）；S8 依赖 S4/S6/S7。不要先做 UI——否则界面只能展示一个假的"处理中"。
八、验收矩阵
下面 24 条能跑通，才算"代码级可落地"。前 10 条是任务闭环，后 14 条对应本轮补的缺口。
| # | 场景 | 预期 | 对应 |
|---|---|---|---|
| T1 | 同一 Idempotency-Key 创建两次 | 只产生一个任务 | 22 |
| T2 | 审批等待中杀 Worker | 仍在 waiting_approval；审批后新 Worker 恢复 | 22 |
| T3 | 工具执行中预算耗尽 | 工具取消/完成；任务 expired；未完成清单完整 | 22/§4.4 |
| T4 | 同一产物重复交付 | 渠道只收到一次，回执幂等 | 18 |
| T5 | 取消时工具仍在跑 | 不再调度；在途工具取消/标记；副作用清单完整 | 22 |
| T6 | 快照失败 | 明确 failed，不静默冷启动 | 21 |
| T7 | 租约过期后旧 Worker 写回 | 旧 epoch 被拒，新 Worker 接管 | 22/§4.4 |
| T8 | SSE 断线后 Last-Event-ID 重连 | 不丢不重，seq 连续 | 22 |
| T9 | 审批超 SLA | 任务 expired，审批单关闭，通知 owner | 22 |
| T10 | 父任务带两个子任务 | 预算分账、join 聚合、终态正确 | §4.4 |
| T11 | 子任务 submitted 但未 accepted | 根任务不能标完成 | §4.4 |
| T12 | 六类停止条件逐一触发 | 分别进入明确终态或人工队列 | §4.4 |
| T13 | 9 次重试跨两层 | 共享 attempt 预算，不产生 9 次上游调用 | §4.5 |
| T14 | 并发两请求各需 80、余额 100 | 第二个被拒，不发生超支 | §4.5 |
| T15 | MCP 未订阅调用 | 403；发现不构成授权 | §4.5 |
| T16 | 审批通过后预算已耗尽 | 重新准入失败，不执行 | §4.5 |
| T17 | 资源中心不可用 | 运行时用已验证 Lock；高风险任务停止并说明 | §4.3 |
| T18 | 上游改版本 | 目录在约定周期内差异告警，不自动覆盖 | §4.3 |
| T19 | Context Manifest 回放 | 能解释每段内容为何进入/被排除 | §4.3 |
| T20 | SUT 边界被脚本替换 | 拒绝启动 | 25 |
| T21 | 故障注入未命中 | Run 标 violated，结论不采纳 | 25 |
| T22 | 300 次零违规 | 报告附 ≤1% 置信上界 | 25 |
| T23 | 低分 BadCase | 归到一类并给出首选 Patch | 26 |
| T24 | 候选 Release 灰度 | 五道门禁通过；一键回滚到上一 Release | 26 |
九、对既有篇目的修订清单
本轮不推翻 00–23 的结构，只做"纠错 + 补字段 + 补切片"。✅ 表示本次已落地，◐ 表示已加指针但字段实现仍在 24/25/26，⬜ 表示后续动作。
| 篇目 | 修订 | 优先级 | 状态 |
|---|---|---|---|
| 00 | 路线图加入 24/25/26 与 S0–S8 | P0 | ✅ |
| 01 | 补 S0–S8 切片与手册 17–24 章映射；Release 六要素 | P0 | ✅ |
| 03 | 补严格预算不变量、跨层重试预算 | P0 | ✅ |
| 06/11 | 补 Agent Contract、Environment Contract、Action Request 对象 | P1 | ✅（06 已补三节，11 已有委派契约） |
| 07 | 控制面按 Go CRD 描述；补 task_run 与 Release 冻结 | P0 | ✅ |
| 08/19 | 补资源中心六组件、生命周期五态、Resolver、Lock Manifest；删除任何"第二权威目录"表述；Nacos 原生 api/ai 资源面字段级证据见 §6.5.3 | P0 | ✅（19 已补；08 新增六组件与解析锁；6.5.3 补原生模型映射） |
| 10 | 补 Task Run、错过策略、OR Join 取消语义 | P1 | ✅（10 已补错过策略与 join/取消） |
| 12 | 拆 Event Log / Snapshot / Checkpoint；补 Workspace 六区、Artifact 状态机 | P1 | ✅ |
| 13 | 补四通信面与六契约要素；把"消息总线"明确为内构面 S4 | P0 | ✅ |
| 14 | 补 12 类执行语义、Session/Trace 边界、审计与业务证据分离 | P1 | ✅ |
| 15 | 补 Token Exchange/On-Behalf-Of、入站/出站权限、DoW | P1 | ◐（已补双向授权） |
| 16 | 增加 S7 仿真切片与 S8 调优切片 | P1 | ✅ |
| 20 | 补九类受管对象与 Evidence 三态 | P1 | ✅（并扩到十二个接缝、十四个评审问题） |
| 22 | 补 task_run、六类停止条件、三级结果、Budget Lease、Evidence 表 | P0 | ◐（已加扩展指针，DDL 在 §四.4.4–4.6） |
| 23 | 术语表增加：Scenario/Manifest/Run/Run Result、Trajectory、Dataset、Budget Lease、Evidence 三态、四通信面、S1–S4 | P0 | ✅ |
| 99 | 增加多 Agent、资源中心、仿真、调优四组检查项 | P1 | ✅ |
| 新增 25 | Agent 仿真台落地设计 | P0 | ✅ |
| 新增 26 | 调优闭环落地设计 | P0 | ✅ |
最小上手
用一天做一次对标复核，不追求全量精读：
- 锁定版本：白皮书版本、平台 00–23 的 revision、关键组件源码 commit，一起写进复核记录；
- 建 30 行表：每章填"硬约束 / 平台实现对象 / 权威 / 失败语义 / 判定"，没有实现对象的直接记 ❌；
- 只对 🟡/❌ 做四问：落在哪个平面、谁是权威、失败怎么办、怎么验收；答不上来就保持 🟡，不因"有组件"升为 ✅；
- 给每个缺口一个最小对象：表、接口或状态枚举三选一；没有可建对象的缺口，说明还没设计到落地；
- 跑 §八 的 24 条验收：缺环境的标"未验证"，不能标"通过"；
- 输出修订清单：按 P0/P1 排期，P0 不跨迭代。
验收判据：任取一章能说出"要求什么、平台谁实现、缺什么、补了怎么验"；任取一条接缝能说出两侧组件、交界字段、权威与失败语义。
生产动作
- 版本钉扎：白皮书版本、平台 revision、组件 commit 一起记录；升级任一项就重跑矩阵。
- 定期复核：每季度一次；新组件上线、模型换代、协议大版本变更时加跑一次。
- 缺口台账：每个 🟡/❌ 有 owner、目标切片、验收用例；没有 owner 的缺口视为风险接受并留记录。
- 证据留档：复核记录、24 条用例结果、未验证项清单归档；结论引用具体版本，不引用"最新"。
- 反例优先：每次复核至少找一个"组件齐全但接缝不成立"的反例，防止打勾式对标。
边界
- 本文回答"能力该落在哪个平面、接缝是否闭合、缺口如何补"，不回答组织流程、采购与团队分工；
- 白皮书是判断框架，不是产品规格：同一能力可以有多种合缝方式，本文给的是当前组件组合下的一种可落地解；
- 组件选型会变，平面归属与判据不变；换掉 Nacos、网关或沙箱实现时，应重跑归属检查，而不是照搬字段名；
- 对标结论有时效性：以白皮书 2026 版与本目录 00–23 当前实现为准，章节或组件迭代后需重新核对；
- 第 24 章边缘优化默认不做；没有多区域与明确延迟收益时，引入边缘只会增加版本漂移与数据合规成本。
讲清楚
这套平台与白皮书是同构的：接缝契约、数据唯一权威、六步装配，就是三平面与最低充分架构的落地翻译。但同构不等于符合：本轮 30 章复核的结果是 6 章已落地、12 章部分落地、6 章缺失，另有 6 章是案例或按需。
最需要纠正的不是"少了一个组件"，而是三处理解错位：第 16 章是 Agent Simulation，不是行为生成闭环；四通信面是人机/能力/协作/内构，不是按部署位置分；Asset Catalog 只能是 Nacos 的只读投影，不能做第二权威。再加上五阶段顺序写反、多 Agent 缺任务分层与停止条件、网关缺严格预算、Agentic OS 高估成熟度，一共七处。
合缝的本质是每个接缝都有"唯一权威 + 交界字段 + 失败语义 + 验收"。22 条接缝、十条原子规则，任何一条答不上来，链路就没有闭环。
落地顺序按生命周期切片：架构设计与 Release 六要素先定，再身份、状态、控制面、任务、供给、证据，最后仿真与调优。仿真台补的是"上线前的受控世界"，调优闭环补的是"上线后的可证明改进"；两者都不是评测的替代品，而是把评测放回它该在的位置——Simulation 交证据，Evaluation 出判断，Governance 给授权。
适用：AI-Agent-Handbook 2026 版 30 章 | 被评：本目录 00–23、99 | 初稿 2026-10，修订 2026-10（补 17–24 章、纠正 7 处错位、接缝扩至 22 条）