主题
落地方法论与总体架构
一句话：开源把零件商品化了，平台之间的差距不在”选了哪些组件”，而在每条接缝有没有显式的接口、字段与唯一权威——拼装不是把服务连起来，是把契约对齐。
定位：以 AI Agent Handbook 为设计判据、以阿里百炼为能力对标，用阿里开源全家桶（AgentScope Java/Service、Higress、HiMarket、Nacos、RocketMQ LiteTopic）拼装企业级智能体平台。策略是最小成本缝合引擎、最大定制 HiMarket 产品壳——能力引擎保持原版，所有”百炼感”由 HiMarket + 统一体验层包装出来。不含模型微调，聚焦运行时、治理与交付闭环。
为什么需要
同一套开源组件，两个人能搭出完全不同的东西：一个人得到“演示很顺、上线就乱”的拼盘，另一个人得到能按租户计费、能回滚、能追责的平台。差别不在组件能力，而在七个接缝：
- 身份接缝：网关认得 API Key，运行时不认得这个 Key 属于哪个租户，计费、隔离、审计各说各话；
- 供给接缝：能力上架了，但注册中心、市场、网关三处各有一份定义，发现即授权、下线后仍能调用；
- 版本接缝：Agent 定义改了，正在跑的会话跟着变，复现时已经找不到当时的配置；
- 状态接缝：会话状态放在进程内存，Pod 一回收上下文就断，任务重试只能从头再来；
- 任务接缝：请求发出去了，但不知道执行到哪一步、是否重复执行、失败该重投还是人工接管；
- 交付接缝：产物生成了却送不到 IM；或者收件人由模型决定、链接永久公开，发错群无法撤回；
- 证据接缝：有日志没有轨迹，有轨迹没有归因，有归因没有回归用例，发布门禁只能拍脑袋。
这些接缝不属于任何单个组件。拼错的典型症状是：网关被当成状态机，市场被当成授权系统，消息队列被当成数据库，Trace 被当成账单。
核心机制
一、全量拼装图
这张图按“请求从哪来、谁做决定、在哪执行、状态放哪、怎么送达、证据留哪”分六层。读图只看三件事：谁持有权威状态、谁做准入、谁留下证据。PostgreSQL 是控制与运行状态的权威，Redis 是会话热状态的权威，对象存储是产物与快照的权威，Nacos 是资产元数据的权威，审计存储是审计的权威；其他位置都只能是投影或缓存。
图里最容易漏掉的不是网关和内核，而是三类“边上组件”：
- 交付类：产出物服务、下载网关、DLP、渠道适配器——没有它们，Agent 只能生成，不能安全送达；
- 身份类：企业 IdP、Hub Router、Provisioner——没有它们，单域名、多设备、离职回收都落不了地；
- 供给类：Git/CI、Skill Registry、MCP Registry——没有它们，能力只能手工拷贝，无法版本化与回滚。
下面按六组把组件逐个映射到职责、契约、权威与篇目。Nacos 同时承担控制面的注册配置和供给链的 Skill/MCP Registry，表中按主要职责放在控制面，Registry 单列两行。
接入与交付
| 组件 | 在拼装中的职责 | 对外契约 | 权威 / 不承担 | 篇目 |
|---|---|---|---|---|
| 企业 IdP / SSO | OIDC 登录、组与角色、入职转岗离职事件 | issuer + sub → subject_id；OIDC | 人员与组是权威；不决定业务授权 | 02 |
| 渠道适配器 | 验签、外部 ID 映射、消息规范化、回执 | X-Signature、external_user_id、msg_id；IM/Webhook 回调 | 外部消息与回执；不决定收件人、不跑 Agent | 13、18 |
| Higress | 认证、消费者、配额、模型与 MCP 代理、内容安全 | Authorization、X-AgentScope-*、OpenAI 兼容 /v1/chat/completions、MCP Streamable HTTP | 调用计量与访问日志；不管任务状态 | 03 |
| Hub Router | 单域名同源代理、Cookie 会话、subject → instance 路由 | __Host-sid、X-Auth-Subject、HMAC、mTLS | 路由表与会话表；不跑 Agent | 17 |
| Provisioner | 懒创建个人实例、工作区、Vault 路径 | 内部 REST；幂等键 | 创建请求；不做路由决策 | 17 |
| 下载网关 | ticket 校验、二次鉴权、流式回源 | 一次性 ticket，TTL 5–15 分钟；HTTPS | ticket 记录；不存文件 | 18 |
| DLP / 水印 | 发送前扫描、命中转审批、文档水印 | 扫描 API；同步或异步结果 | 策略结果；不决定收件人 | 18 |
控制面
| 组件 | 在拼装中的职责 | 对外契约 | 权威 / 不承担 | 篇目 |
|---|---|---|---|---|
| Service Gateway | 统一入口、认证、路由、公共 API | REST/SSE；Authorization、X-AgentScope-Tenant/Namespace | 请求路由；不做模型循环与任务状态 | 07 |
| aistiod（Control） | Agent 目录、Team、Workflow、命名空间、版本、控制台后端 | 内部 REST；agent_id + version 乐观锁 | Agent/Endpoint 定义（落 PG）；不执行 Turn | 07 |
| Service Scheduler | Channel、Cron、出站任务、Hosted Worker 协调 | REST；session_id、turn_id、deadline、budget | 触发配置（PG）；不保证消息投递 | 07、10 |
| PostgreSQL | cp / rt / dp 三 schema：定义、会话与事件、任务账本 | JDBC 事务 + outbox；task_id + attempt | 控制与运行状态；不存大对象 | 07、10 |
| Nacos | 服务发现、动态配置、Agent/Worker 元数据 | namespace/group/service；配置 dataId | 注册与配置；不做授权、密钥、任务状态 | 08 |
| Environment | Managed / External / Hosted 三种执行位置 | Service API；environment_id | 执行位置绑定；不做模型循环 | 07、11 |
| Vault | 凭据存储、按会话短时注入、轮换与吊销 | 路径 tenant/subject/tool；短时令牌 | 凭据；不分发配置 | 07、15 |
| K8s API | 工作负载、沙箱、WarmPool、NetworkPolicy、HPA | K8s API；SandboxTemplate/WarmPool/Claim | 期望状态；不做业务调度 | 11、21 |
运行面
| 组件 | 在拼装中的职责 | 对外契约 | 权威 / 不承担 | 篇目 |
|---|---|---|---|---|
| RocketMQ + LiteTopic | 会话级保序、至少一次、续传、TTL 自动删除 | t/{tenant}/s/{session}、task_id、idempotency_key、位点 | 在途消息；不是状态账本 | 10 |
| Dataplane | Managed Agent 推理循环、Session Brain、Turn 执行 | REST/事件流；SSE as_of、Last-Event-ID、410 | Turn 执行结果；不做跨租户治理 | 07 |
| HarnessAgent | 循环、上下文装配、工具调用、子 Agent、计划模式 | 进程内 API；RuntimeContext | 单次 Agent 执行；不做多租户与计费 | 06 |
| Toolkit | 工具注册、MCP 客户端、权限策略 | mcp__{server}__{tool}；always_allow/always_ask/deny | 单次调用策略；不发布版本 | 06、19 |
| Memory / Workspace | 内置记忆、工作区文件、Skill 加载 | load_skill_through_path、<available_skills>；文件系统 | 会话工作区；长期事实可外置 mem0 | 06、12 |
| DistributedStore | AgentStateStore、BaseStore、SandboxSnapshotSpec、SandboxExecutionGuard、CAS | getVersioned/saveIfVersion；IsolationScope | 按 scope 的状态；不做业务语义 | 12 |
| Runtime Scheduler SPI | AgentScheduler（Quartz/XXL-Job）、ScheduleConfig、ScheduleAgentTask | 每次触发创建新 Agent 实例；XXL-Job 默认 9999 | 调度配置；不保证投递 | 10 |
| Sandbox Manager | 生命周期、快照、热池、四分支恢复、清理 | SandboxTemplate/WarmPool/Claim、/execute、/download；Docker/K8s/Daytona/E2B/AgentRun | 沙箱实例与快照；不做网络策略与凭据 | 12、21 |
| Runtime Host | 准备目录、启动 Harness、回报事件与产物 | Hosted 注册 API；mTLS | 主机执行状态；不做多租户隔离 | 11 |
| Coding Harness | OpenCode / Claude Code / Codex，执行编码任务 | CLI/进程协议；能力协商 | 任务执行；不承担平台治理 | 11 |
| HiRoute | 本地模型分流、任务委派、成本证据 | Harness → HiRoute；路由回执与评分 | 路由回执；不做中心配额 | 05 |
| Jev | 类型化判断、校准概率、阶段路由 | POST /v1/systemone；JevExecution.Options | 判断结果；不做授权与执行 | 09 |
| 模型服务 | OpenAI 兼容推理、embedding/rerank | /v1/chat/completions；公有云或私有化 | 推理结果；不做路由与配额 | 03 |
| MCP Servers | 工具实现与参数 Schema | Streamable HTTP/SSE；JSON Schema | 工具行为；不做 Agent 循环 | 06、19 |
数据与存储
| 组件 | 在拼装中的职责 | 对外契约 | 权威 / 不承担 | 篇目 |
|---|---|---|---|---|
| Redis / MySQL / Mongo | 会话热状态、缓存、锁、配额计数、Hub 会话表 | {tenant}:{ns}:{user}:{session}；CAS 能力因后端而异 | 热状态与计数；不存大对象 | 12、17 |
| NAS / CephFS | 工作区共享文件系统 | POSIX；/{tenant}/{ns}/{user}/{session}/ | 工作区文件；不做快照 | 12、21 |
| OSS / Ceph RGW / MinIO | 产物、快照、大工具结果 | S3 API；s3://{bucket}/{tenant}/{ns}/{session}/ | 二进制与快照；不做锁与计数 | 12、18 |
| mem0 | 跨会话长期事实 | add/search/update/delete；user_id/agent_id/run_id | 长期记忆；不做组织知识与权限 | 12 |
| 向量库（pgvector/Qdrant） | 语义索引 | vector API | 索引可重建；不是权威事实 | 12 |
| 产出物服务 | 产物元数据、ACL、保留期、ArtifactCreated outbox | artifact_id、storage_uri、checksum、acl | 产物元数据；不存二进制 | 18 |
| 对象生命周期 | 过期、归档、真删除 | S3 lifecycle 或定时任务 | 保留策略执行；不是业务状态 | 14、18 |
供给链
| 组件 | 在拼装中的职责 | 对外契约 | 权威 / 不承担 | 篇目 |
|---|---|---|---|---|
| Git / CI | Skill 源码、镜像构建、扫描、签名、provenance | Git + CI pipeline；SHA-256、commit | 源码与构建产物；不是运行时分发 | 19 |
| HiMarket | 产品目录、订阅、审批、计量、门户 | POST /api/v1/products/{id}/ref；产品类型 Model/MCP/Agent/Skill/Worker | 产品与订阅记录；不存资产定义、不做运行时鉴权 | 04、19 |
| Console | 目录、Chat、Issue、运行观察 | Service API | 只读投影；不是权威 | 07 |
| Skill Registry（Nacos） | Skill 包、SemVer、label、审核状态、可见性 | ZIP + SKILL.md；draft/reviewing/online/offline | Skill 版本权威；不做订阅与计费 | 19 |
| MCP Registry（Nacos） | MCP 端点、协议、工具清单、健康检查 | nacosRefConfig；namespace/group/service | MCP 元数据权威；不做调用放行 | 19 |
证据面
| 组件 | 在拼装中的职责 | 对外契约 | 权威 / 不承担 | 篇目 |
|---|---|---|---|---|
| OTel Collector + Trace 后端 | 接收 OTLP、采样、存储、查询 | OTLP 4317/4318；Trace/metric API | 轨迹与指标；不是计费权威 | 14 |
| 评测与门禁 | 黄金集、评分器、回归、四级门禁 | eval API + CI hook | 质量结论与放行；不做业务执行 | 14 |
| 审计存储 | append-only 审计、保留期、不可篡改 | 独立存储；event_id | 审计；与 Trace 分开 | 14、15 |
二、进程与端口：先能部署，才谈拼装
| 进程 / 组件 | 默认端口 | 协议 | 上游 | 下游 |
|---|---|---|---|---|
| 企业 IdP / SSO | 443 | OIDC / HTTPS | 浏览器、网关 | — |
| 渠道适配器 | 自建，按部署 | HTTPS 回调 | IM / Git | Higress |
| Higress | 80 / 443 | HTTP(S)、SSE、WebSocket | 渠道、应用、外部 Agent | Service Gateway、Hub Router、模型端点、MCP |
| Hub Router | 443 | HTTPS、SSE、WebSocket | Higress | 个人实例、Service Gateway |
| Provisioner | 自建，按部署 | REST | Hub Router | K8s、PostgreSQL |
| HiMarket | 80 / 443 | HTTP(S) | 浏览器、运营 | Nacos、Higress |
| service-gateway | 8080 | REST、SSE | Higress、Hub Router、Console | aistiod、dataplane、scheduler |
| aistiod | 8081 | REST | gateway、控制台 | PostgreSQL、K8s |
| service-dataplane | 8082 | REST、事件流 | gateway / scheduler / Hub Router | 内核、Redis、对象存储、产出物服务 |
| service-scheduler | 8083 | REST | gateway | PostgreSQL、RocketMQ、Runtime Host |
| XXL-Job Executor | 9999 | HTTP | Runtime Scheduler SPI | — |
| Jev | 自建，按部署 | HTTP | 内核 | — |
| Nacos | 8848 / 9848 | HTTP / gRPC | 网关、运行时、市场 | — |
| RocketMQ | 9876 / 10911 | gRPC / TCP | Scheduler / Relay | Dataplane |
| PostgreSQL | 5432 | JDBC | 控制面、数据面 | — |
| Redis / MySQL / Mongo | 6379 / 3306 / 27017 | RESP / JDBC / Mongo | 内核、Hub Router | — |
| Vault | 8200 | HTTP API | 内核、Dataplane | — |
| K8s API | 6443 | HTTPS | aistiod、Sandbox Manager | — |
| 对象存储 | 443 | S3 API | 内核、产出物服务、下载网关、快照服务 | — |
| 产出物服务 | 自建，按部署 | REST、事件 | 内核 | 对象存储、PostgreSQL、渠道适配器 |
| 下载网关 | 443 | HTTPS | 用户 | 对象存储 |
| Runtime Host | 自建，按部署 | HTTPS / mTLS | Scheduler、HiRoute | Coding Harness |
| mem0 | 自建，按部署 | HTTP / SDK | 内核 | 向量库 / KV |
| DLP | 自建，按部署 | 扫描 API | 产出物服务 | — |
| OTLP Collector | 4317 / 4318 | gRPC / HTTP | 网关、内核、Dataplane、产出物服务 | Trace 后端 |
端口是默认值，以实际部署清单为准；但每个端口对应哪条契约必须固定下来，否则联调时只能靠猜。部署顺序也是依赖顺序：数据库与对象存储 → 注册中心 → 控制面 → 数据面 → 网关 → 渠道。
三、一次请求的完整链路
个人助理的单域名模式在这条链路之上多一跳 Hub Router；产出物不回到模型，而是由产出物服务登记后经渠道适配器交付，再由下载网关做二次鉴权，详见 17-个人助理 Hub 与 18-产出物与 IM 交付。
四、接缝级接口契约
先看七条契约，再看接口细节：
| 接缝 | 契约 | 拼错的后果 |
|---|---|---|
| 身份 | 请求携带 tenant / namespace / subject / session，四者不可缺 | 计费串租户、审计无法归属 |
| 供给 | 注册中心是权威、市场是引用、网关是执行点 | 目录漂移、发现即授权 |
| 版本 | 会话创建时冻结 Agent、Workspace、Workflow、路由版本 | 复现时配置已变 |
| 状态 | 会话与任务状态在进程之外，事件日志权威 | Pod 回收丢上下文 |
| 任务 | 至少一次投递 + 幂等键 + 租约/栅栏 | 重复执行、扣费翻倍 |
| 交付 | 产物先登记、再交付；收件人来自会话主体 | 发错人、永久链接泄漏 |
| 证据 | 每次调用有 trace，结论能追到版本与来源 | 门禁失效、事故无法复盘 |
只画箭头不够，每条箭头都要能说清“用什么协议、带什么字段、失败怎么办”。
| # | 接缝 | 接口形态 | 必带字段 | 失败语义 |
|---|---|---|---|---|
| 1 | 渠道 → Higress | HTTPS 回调 | X-Signature、external_user_id、msg_id | 验签失败 401；重放窗口外的消息丢弃 |
| 2 | Higress → Service | REST + SSE | Authorization、X-AgentScope-Tenant、X-AgentScope-Namespace | 401/403 不重试；429 按 Retry-After |
| 3 | Service → aistiod | 内部 REST | tenant、namespace、agent_id、version | 版本冲突 409，不回退到最新版 |
| 4 | aistiod → PostgreSQL | JDBC 事务 | 主键、version（乐观锁） | 冲突重读后重试，最多 N 次 |
| 5 | Service → Scheduler | REST | session_id、turn_id、deadline、budget | 超时先查状态，换幂等键重试视为新任务 |
| 6 | Scheduler → PostgreSQL | 同库事务 | task_id、status、attempt、outbox 记录 | 事务失败则任务不成立 |
| 7 | Relay → LiteTopic | gRPC 发送 | liteTopic=t/{tenant}/s/{session}、task_id、idempotency_key、traceparent | 发送失败留在 outbox，退避重投 |
| 8 | LiteTopic → Dataplane | gRPC 推送 | ClientID、位点、消息体 | 先提交结果再提交位点；重复投递靠幂等键 |
| 9 | Dataplane → 内核 | 进程内调用 | userId、sessionId、冻结版本 | 状态加载失败不执行，直接失败 |
| 10 | 内核 → Higress | OpenAI 兼容 /v1/chat/completions | 租户、会话、预算、traceparent | 5xx 按候选回退；预算耗尽拒绝 |
| 11 | 内核 → MCP | Streamable HTTP | mcp__{server}__{tool}、参数 Schema | 工具错误回填给模型，不静默吞掉 |
| 12 | 内核 → Jev | POST /v1/systemone | 问题类型、候选、有限上下文 | 超时/失败按用例 fail-open 或 fail-closed |
| 13 | 内核 → 存储 | Redis / S3 / JDBC | {tenant}:{ns}:{user}:{session} 前缀 | 状态写失败则本轮不提交 |
| 14 | 运行时 → OTel | OTLP | traceparent、span 名、模型与工具属性 | 采集失败不阻断执行，但必须告警 |
| 15 | HiMarket → Nacos / Higress | POST /api/v1/products/{id}/ref | sourceType、nacosRefConfig 或 higressRefConfig | 引用失效则产品不可用；需定时对账，不假设自动同步 |
| 16 | Hub Router → 个人实例 | HTTPS / WSS + mTLS | X-Auth-Subject、X-Auth-Tenant、X-Auth-Ts、X-Auth-Nonce、X-Auth-Sig | 验签失败 401；owner 不匹配 403；不因内网来源放行 |
| 17 | 内核 → 产出物服务 | REST / 流式上传 | artifact_id、owner_subject、session_id、mime、size、checksum、acl、retention | 写入失败则本轮不声明完成；同 artifact_id 重试幂等 |
| 18 | 产出物服务 → 渠道适配器 | 事件 / Outbox | ArtifactCreated、artifact_id、recipient、channel、traceparent | 至少一次；用 artifact_id + channel + recipient 幂等；失败退避 |
| 19 | 用户 → 下载网关 | HTTPS | 一次性 ticket；服务端记录 artifact、subject、过期时间 | 过期或已用 410；主体不匹配 403 |
| 20 | 内核 → Nacos Skill Registry | HTTP / gRPC + 变更订阅 | skillId、version、label、SHA-256 | 拉取失败用缓存并告警；close() 释放订阅 |
这张表是联调清单：两边对不上，不要靠“应该能通”推进。
五、数据所有权：每份数据只有一个写者
| 数据 | 唯一权威 | 键 / 命名 | 其他系统 |
|---|---|---|---|
| Agent 定义与 Endpoint | PostgreSQL cp | (namespace, agent_id, version) | 控制台只读投影 |
| Session / Turn / 事件 | PostgreSQL rt / dp | (tenant, namespace, session_id, seq) | SSE 只是投影 |
| 会话状态 | Redis / MySQL / Mongo | {tenant}:{ns}:{user}:{session} | 对象存储只做冷备 |
| 工作区文件 | NAS / CephFS | /{tenant}/{ns}/{user}/{session}/ | 沙箱挂载读写 |
| 产物与快照 | S3 兼容存储 | s3://{bucket}/{tenant}/{ns}/{session}/ | 数据库只存引用 |
| 产物元数据 | 产出物服务 / PostgreSQL | artifact_id | 对象存储只存二进制 |
| 下载 ticket | Redis / 数据库 | ticket_id + subject | 一次性、短 TTL |
| 长期记忆 | 内置 memory 或 mem0 | user_id / agent_id / run_id | 知识库不共享索引 |
| 任务账本 | PostgreSQL | task_id + attempt | 队列消息不是状态 |
| 消息在途 | LiteTopic | t/{tenant}/s/{session} | 非权威，TTL 可删 |
| 注册与配置 | Nacos | namespace / group / dataId | 网关只做缓存 |
| Skill / MCP 元数据 | Nacos | namespace / group / service + SemVer | HiMarket 只存引用 |
| 凭据 | Vault | namespace/path | 配置里只放引用 |
| 模型调用计量 | Higress | consumer + tenant + model | OTel 成本只是估算 |
| 轨迹 | OTel 后端 | trace_id | 计费另有权威 |
| 审计事件 | 审计存储 | event_id | Trace 不是审计 |
六、最容易拼错的组件
| 组件 | 承担 | 明确不承担 | 缺口由谁补 |
|---|---|---|---|
| Higress | 认证、限流、模型/MCP 转发、内容安全、访问日志 | 任务状态、检查点、结果验收 | Service 会话日志 + 业务验收器 |
| HiMarket | 从 Nacos/Higress 引用能力、上架、订阅审批、计量与门户 | 运行时授权、参数级 ACL、持续同步 | 网关消费者策略 + 工具策略 + 定时对账 |
| Nacos | 服务发现、动态配置、资产元数据与版本 | 授权、密钥、任务状态 | 网关 + Vault + 事件日志 |
| Hub Router | 单域名代理、Cookie 会话、subject 路由 | 身份认证、Agent 执行 | IdP + Higress + Service |
| LiteTopic | 会话级保序投递、续传、生命周期 | 系统账本、任务状态机 | PostgreSQL + 业务状态机 |
| Sandbox | 文件系统与进程隔离、快照 | 网络策略、凭据管理 | NetworkPolicy + Vault |
| 产出物服务 | 产物元数据、ACL、交付事件 | 二进制存储、IM 协议差异 | 对象存储 + 渠道适配器 |
| Runtime Host | 准备目录、启动 Harness、回报事件与产物 | 多租户隔离、模型治理 | 容器/VM + 企业网关 |
| mem0 | 跨会话可检索的长期事实 | 组织知识、权限裁决 | 知识库 + 工具策略 |
| OTel / 审计 | 轨迹、指标、成本归因、审计 | 计费权威、质量结论 | 网关计量 + 评测集 |
读法是“从右往左”：先看组件不承担什么，再决定这个责任落在哪。一个组件被要求做它不负责的事，就是拼错的开始。
七、装配顺序：六步，每步都有验收
| 阶段 | 装什么 | 连到哪 | 验收 |
|---|---|---|---|
| 1 身份与入口 | 账号体系 → Higress consumer → Service 命名空间 | 渠道 → 网关 | 请求能归属到唯一租户与主体 |
| 2 内核与状态 | HarnessAgent + DistributedStore + 一个只读工具 | Redis / 对象存储 | 换节点会话能续，工具结果可追 |
| 3 控制面与版本 | Service 的目录、会话、端点 | PostgreSQL | 改定义不影响运行中会话 |
| 4 任务与触发 | Scheduler + Outbox + LiteTopic + Worker | 账本 ↔ 通道 | 定时任务独立会话，重投只执行一次 |
| 5 供给与路由 | HiMarket + Nacos + HiRoute + Jev | 市场 ↔ 注册中心 ↔ 网关 | 订阅、发现、准入三件事分别可验证 |
| 6 交付与证据 | 产出物服务 + 渠道适配器 + 下载网关 + OTel + 评测 | 内核 ↔ 对象存储 ↔ IM ↔ 全链路 | 产物能送到、能撤回；任取一条回答能追到模型、提示词、工具与版本 |
前四步没跑通就上市场，会得到“能上架、调不通、查不到”的三件套；第五步没跑通就接渠道，会把渠道问题误判成内核问题；第六步没跑通就上线，会得到“生成得出来、送不出去、出了事说不清”的三件套。
六步之上还有一条贯穿的运行态闭环：任务状态、等待释放、预算终态与完成证据。它不属于某一个阶段，而是每一层的验收前置；字段、表结构、API 与组件改造清单见 22-架构评审与任务闭环，术语口径见 23-术语与写作约定。
按白皮书生命周期补齐后，六步扩展为 S0–S8：S0 架构设计与 Release 六要素，S1–S6 对应上表六步，S7 仿真台，S8 调优闭环；切片划分、依赖与验收见 24-白皮书对标与落地推演 §七。
八、手册章节怎么落到这一栏
手册原文的逐章精读在 08-AI-Agent-Handbook 精读；这里只判断 07 栏目把哪些能力真正落了地。
| 手册章节组 | 主题 | 对应篇目与缺口 |
|---|---|---|
| 第 1–2 章 | 应用形态与参考架构 | 01 |
| 第 3–6 章 | Harness、任务、信息、行动 | 06、11；上下文装配与 Action Plane 的字段级契约部分覆盖 |
| 第 7–12 章 | 运行时、状态、网关、异步、多 Agent、通信 | 03、07、08、09、10、12、13、21 |
| 第 13–16 章 | 可观测、安全、资产、Agent 仿真 | 04、14、15、19、24、25 |
| 第 17–18 章 | 模型调优与 Agent 调优总览 | 05、14、24、26；模型训练不作为平台职责 |
| 第 19–24 章 | 轨迹、数据流水线、黄金集、BadCase、自进化、边缘 | 14、20、26；实现见 26 |
| 第 25–30 章 | 企业案例与 Agentic OS | 16、20、24；案例不作准入要求 |
真正的落地判断是——这一章要求的能力，在矩阵里有没有明确的责任人。
最小上手
先不接市场、不接渠道、不接编码 Harness，只跑一条五段链路：
text
用户 → Higress（认证 + 限流）→ Service Gateway → Dataplane（单 Agent）
→ 一个只读 MCP 工具 → 事件日志 + OTel Trace验收只问六个问题：请求能否归属到唯一租户；会话创建后配置版本是否冻结；Pod 重启后会话能否继续；同一任务重投两次是否只产生一个结果；任取一条回答能否追到模型、提示词版本和工具调用；产物能否先登记再交付、收件人是否由会话主体决定。六问都过，再往上加组件。
生产动作
- 先定组件清单与责任矩阵，再选版本：每个组件写清“接在哪、带什么字段、谁是权威、不承担什么”，评审时按矩阵吵架，而不是按功能清单吵架。
- 接缝处只留一种权威：状态以事件日志为准，计量以网关为准，质量以评测集为准，资产以 Nacos 为准；其他系统只做投影。
- 按装配顺序上线：每加一层就跑一次全链路回归，避免新组件打破旧链路的隐式假设。
- 跨组件调用带四个标识：租户、会话、任务、trace，缺一个就不许上线。
- 按失败域演练：分别杀掉网关、Dataplane、消息队列、沙箱、决策服务、产出物服务，观察哪一层先报警、哪一层能自愈。
- 把任务闭环当上线门禁：任务状态、等待原因、预算终态、完成证据四项缺一项，不进入生产；具体验收用例见 22 的 T1–T10。
边界
- 矩阵不是组织架构：一个组件可以由多个团队运维，但责任边界必须唯一。
- 清单不是越多越好：同一能力有多个实现时，只保留一个权威，其余标成可替换实现；清单的目的是找接缝，不是比谁列得长。
- 开源覆盖机制，不覆盖制度：租户模型、审批流、计费规则、数据保留期最终要按企业制度实现。
- 接缝越多，延迟与运维成本越高：小团队可以先把网关、内核、队列合并在一个进程里，等出现独立扩缩容需求再拆。
- 端口与路径会变：表里的端口是默认值，接口路径随版本变化；契约看字段与语义，不要硬编码别人的默认值。
讲清楚
拼装平台的核心不是选组件，而是给每条接缝指定唯一权威：入口层管准入，控制面管目录与版本，运行面管执行，数据层分别管状态、文件与产物，证据面管归因。
组件清单按六组展开：接入与交付、控制面、运行面、数据与存储、供给链、证据面。最容易漏的是交付、身份、供给三类“边上组件”——它们不在主请求链上，却决定平台能不能安全送达、能不能按人回收、能不能版本化回滚。
一次请求要穿过渠道、网关、控制面、调度、队列、内核、工具、存储八个位置；每个箭头都要有协议、必带字段与失败语义，靠约定俗成的部分会在换组件时断掉。
判断一套拼装是否成立，不看组件数量，而看六件事：请求能否归属、配置能否复现、Pod 死后能否续跑、重投是否只执行一次、产物能否安全送达、结论能否追到来源。
适用：2026 年开源 Agent 平台组件 | 初稿 2026-10