03 · 如何设计 Agent Platform 的系统架构？ - System Design

所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：04 · 如何开发、部署和维护 Agent Platform？ - Engineering & Practice
文档类型：专题研究 / 系统架构 / 工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：如何将 Agent Platform 的产品能力、控制面、工作流、Agent Runtime、数据和运维体系组织为边界清晰、状态可靠、安全可控、可演进的完整系统，并为 Studio 建立可实施的架构蓝图？

专题导读

本篇属 Engineering & Practice。本篇承接 04/04/01 Platform Case Studies 与 04/04/02 Technology Selection，研究的是系统设计方法与可实施参考架构，而非某一个框架的使用教程。前文技术选型提出 Next.js、PostgreSQL、独立 Worker、对象存储及若干工作流/Agent Runtime 候选，本篇把它们放入统一系统边界，明确对象归属、状态转移、事务一致性、执行恢复、权限检查、接口契约和部署拓扑。

研究对象是同时支持 Agent 创建、运行、协作、审批、产物管理、API 集成与管理治理的 Agent Platform。本文以多 Agent 研究报告 Studio 为贯穿案例：选题 Agent → 审核 Agent → 深度调研 Agent → 分析 Agent → 人工确认 → 成果交付。本文不是对 Studio 现有代码的审计，任何具体技术实现均标记为建议或待验证。

证据分级：[规范/官方] 表示规范或官方文档中明确描述的机制；[架构推论] 表示基于需求和成熟工程原则提出的设计；[待验证] 表示需要通过 PoC、代码审计或压力测试确认。下文 SQL、JSON、API、指标与时序是参考契约，不宣称已在生产环境执行。

研究结论

1. 业务数据库是平台状态真相源，Agent Runtime 不是平台真相源。 Run、审批、产物、版本、租户、权限与审计应由平台拥有；Trace 负责诊断，不替代业务状态。[架构推论]
2. 采用 Control Plane / Execution Plane / Data Plane / Observability Plane 分离的逻辑架构；初期可以部署为模块化单体 API + 独立 Worker，不必立即拆分微服务。[架构推论]
3. 工作流编排器必须显式支持持久化检查点、等待、超时、取消、重试、恢复、版本固定；不能以长连接或内存变量承载长任务的唯一状态。[架构推论]
4. 使用事务 Outbox + 至少一次投递 + 幂等消费衔接业务状态和异步队列；“Exactly once”不能被简单等同于外部工具副作用恰好执行一次。[架构推论]
5. 将 Run 的执行成功、评估通过、人工审核通过、成果交付成功视为不同维度，避免错误的产品状态和自动发布。[架构推论]
6. 权限、租户隔离、预算、凭证、数据保留和审计应贯穿所有入口与执行链路，而非后台管理的补丁。[架构推论]
7. Studio 首期建议优先验证一条可恢复的研究任务完整闭环，再逐步引入复杂协作、分布式扩容与多租户。[待验证]

01 · 系统设计的目标与边界

1.1 设计输入

输入类别	需要明确的事实或决策	Studio 参考约束
用户与产品	用户类型、关键旅程、权限边界	作者、审核者、管理员、外部集成方
工作流	阶段、依赖、返工、人工介入	选题 - 审核 - 调研 - 分析 - 审批 - 交付
数据	真相源、保留、删除、可追溯	Run、AgentVersion、ArtifactVersion、Review
非功能需求	可用性、延迟、并发、恢复目标	需通过实际业务负载确定，不预设 SLA
安全	租户隔离、密钥、工具授权	工具调用必须受项目/租户授权约束
预算	模型调用、队列、存储、日志成本	每 Run 预算和组织级配额
团队	人力、语言能力、运维能力	候选为 Next.js + 独立 Worker

1.2 系统边界

平台内部负责：身份与权限、Agent 定义与版本、Workflow 定义、Run 生命周期、调度策略、审批、产物元数据、审计、预算、集成 API。外部依赖包括模型供应商、搜索/检索服务、第三方工具、邮件/通知、对象存储和可观测性后端。任何外部依赖都应通过明确的适配器和错误模型接入。[架构推论]

1.3 质量属性与取舍

质量属性	设计目标	常见冲突	证明方式
正确性	状态转移合法、结果关联准确	开发速度	状态机/契约测试
可恢复性	Worker 崩溃后任务可继续	执行开销	故障注入
安全性	最小权限与隔离	操作便利	越权/租户穿透测试
可观测性	任务与工具调用可追踪	隐私/成本	Trace 与脱敏测试
可扩展性	API 和 Worker 独立扩容	系统复杂度	负载测试
可演进性	替换模型/运行时成本可控	抽象层开销	适配器替换 PoC
可运营性	故障定位、回滚、备份	初期投入	演练与恢复测量

02 · 总体逻辑架构

flowchart TB
  U[Web / External Client] --> EDGE[API Gateway / BFF]
  EDGE --> AUTH[Identity / Policy Enforcement]
  AUTH --> CTRL[Platform Control Plane]
  CTRL --> REG[Agent & Workflow Registry]
  CTRL --> RUN[Run Service / State Machine]
  CTRL --> REV[Review & Approval Service]
  CTRL --> ART[Artifact & Delivery Service]
  RUN --> DB[(PostgreSQL: Business State)]
  RUN --> OUT[(Transactional Outbox)]
  OUT --> DISPATCH[Dispatcher / Queue]
  DISPATCH --> W[Execution Workers]
  W --> ORCH[Workflow Orchestrator]
  ORCH --> AR[Agent Runtime]
  AR --> MODEL[Model Gateway]
  AR --> TOOLS[Tool / Integration Gateway]
  W --> OBJ[(Object Storage)]
  W --> DB
  CTRL --> DB
  W -. telemetry .-> OTEL[Telemetry Collector]
  CTRL -. telemetry .-> OTEL
  OTEL --> OBS[Traces / Metrics / Logs]
  MODEL --> EXT[External Model Providers]
  TOOLS --> SYS[External Systems]

2.1 四个逻辑平面

Control Plane 管理定义、权限、策略、版本、Run 意图和操作审计；Execution Plane 负责队列、Worker、工作流、Agent Runtime、模型与工具调用；Data Plane 承载业务数据、文件对象、检索索引和缓存；Observability Plane 汇聚追踪、日志、指标、告警与成本分析。四平面是职责划分，初期不要求四套独立集群。[架构推论]

2.2 模块化单体与服务拆分

初期把 Auth、Registry、Run、Review、Artifact、Admin 作为同一 API 进程中的独立业务模块，统一 PostgreSQL 事务边界；将耗时执行放入 Worker。只有当伸缩、故障隔离、组织边界或部署周期形成可量化压力时，再将某模块独立成服务。拆分前应先稳定模块 API、事件契约和数据所有权。[架构推论]

2.3 与 v1.3 技术层的对应

技术层	主要实现组件	责任边界
P1 Control Plane	API、策略、Registry、Run 控制	意图与授权
P2 Execution Plane	Worker、Runtime、执行隔离	实际执行
P3 Agent Registry	AgentDefinition、AgentVersion	不可变版本
P4 Development Services	测试沙箱、配置校验	开发验证
P5 Deployment & Runtime	Deployment、Worker Pool	实例与环境
P6 Workflow Management	状态机、检查点、队列	协作与恢复
P7 Resource & Integration	Model/Tool Gateway	外部资源
P8 Platform API & SDK	HTTP/SSE/Webhook/SDK	开放接口
P9 Extensibility	插件与扩展点	可控扩展
P10 Platform Data & Assets	DB、对象存储、索引	资产管理
P11 Multi-tenancy	tenant_id、策略、隔离	组织边界
P12 Platform Governance	配额、预算、审计	治理执行

03 · 领域模型与聚合边界

3.1 核心实体

实体	标识	关键字段	所有者
Tenant	tenant_id	name, status, policy	Identity/Governance
Workspace	workspace_id	tenant_id, members	Workspace
AgentDefinition	agent_id	workspace_id, owner	Registry
AgentVersion	agent_version_id	immutable_spec, checksum	Registry
WorkflowDefinition	workflow_id	workspace_id	Workflow
WorkflowVersion	workflow_version_id	immutable_graph	Workflow
Run	run_id	workflow_version_id, status, budget	Run Service
StepRun	step_run_id	run_id, node_key, status	Orchestrator
Attempt	attempt_id	step_run_id, attempt_no, lease	Worker
Approval	approval_id	run_id, step_run_id, decision	Review
Artifact	artifact_id	run_id, kind	Artifact
ArtifactVersion	artifact_version_id	checksum, object_key	Artifact
Delivery	delivery_id	artifact_version_ids, recipient	Delivery
AuditEvent	audit_id	actor, action, target	Governance

3.2 不可变与可变对象

AgentVersion 和 WorkflowVersion 发布后不可原地修改；修改应创建新版本。Run 创建时固定所引用的 WorkflowVersion 及其 AgentVersion 解析结果，避免执行过程中配置漂移。ArtifactVersion 固定内容哈希与存储键；审批绑定特定版本。Run 状态、任务租约、预算剩余量、审批等待状态属于可变业务状态，须有并发控制。[架构推论]

3.3 关键不变量

1. 任一 Run 必须属于且仅属于一个 Tenant 和 Workspace；跨租户引用默认拒绝。
2. 任一 StepRun 必须属于同一 Run 的固定 WorkflowVersion 中可识别的节点。
3. 已终结 Run 不得重新变为 running；重新执行应创建新 Run 或显式的派生关系。
4. 同一 StepRun 可以有多个 Attempt，但只有一个合法完成结果可提交。
5. 审批决定必须关联审批请求、版本、操作者与时间。
6. ArtifactVersion 一经确认不可覆盖；交付引用确定版本。
7. 外部工具调用的授权范围不得超过发起用户和执行身份的有效交集。
8. 审计事件应不可由普通业务角色修改或删除；保留策略独立控制。

04 · Run 与工作流状态机

4.1 Run 状态建议

stateDiagram-v2
  [*] --> queued
  queued --> running
  running --> waiting_approval
  waiting_approval --> queued: approved / resumed
  waiting_approval --> cancelled: cancel
  running --> succeeded
  running --> failed
  running --> cancelling
  queued --> cancelled
  cancelling --> cancelled
  cancelling --> failed: cancellation error
  failed --> [*]
  succeeded --> [*]
  cancelled --> [*]

这是一种参考状态机；实际系统还可能需要 timed_out、expired、blocked 等状态。应统一定义合法转移、状态原因和时间戳，并保证 UI、API、数据库及事件流语义一致。等待人工审批不应占用一个长期挂起的 Worker 进程。[架构推论]

4.2 状态与结果分离

维度	典型状态	含义
execution_status	queued/running/succeeded/failed	执行是否完成
evaluation_status	pending/passed/failed/not_evaluated	质量门禁是否通过
review_status	pending/approved/rejected/not_required	审核是否通过
delivery_status	not_ready/ready/delivered/failed	是否已交付

执行成功但审核失败时，不能在产品界面显示为“已完成交付”。对外 API 应返回这些独立字段。[架构推论]

4.3 节点状态与依赖

每个节点有明确输入映射、输出契约、依赖、重试策略、超时、失败分支、审批门禁和补偿策略。动态生成节点时必须记录拓扑变更及其版本。条件分支应保存实际决策输入的安全摘要，保证复盘时能解释为何走某一路径；不得暴露模型内部私有推理。[架构推论]

05 · 异步执行、队列与事务一致性

5.1 为什么需要 Outbox

如果 API 在数据库写入 Run 后、消息发布前崩溃，Run 可能永久停留 queued；如果先发消息再提交数据库，Worker 可能查不到 Run。建议在同一数据库事务内写入 Run 与 outbox_event，再由独立 Dispatcher 发布到队列。Dispatcher 可能重复发布，因此 Worker 必须幂等。[架构推论]

sequenceDiagram
  participant C as Client
  participant A as Platform API
  participant D as PostgreSQL
  participant O as Outbox Dispatcher
  participant Q as Queue
  participant W as Worker
  C->>A: POST /runs (Idempotency-Key)
  A->>D: BEGIN; INSERT run + outbox; COMMIT
  A-->>C: 202 + run_id
  O->>D: Read pending outbox
  O->>Q: Publish run.requested
  Q->>W: Deliver (at least once)
  W->>D: Acquire lease / check state
  W->>W: Execute step
  W->>D: Commit step result + next outbox
  W-->>Q: Ack

5.2 消费幂等与租约

Worker 领取任务时使用条件更新、版本号或数据库锁保证同一时刻只有一个有效租约。租约过期后允许其他 Worker 接管，但原 Worker 可能仍在运行，因此提交结果时还需核验 lease_token / fencing_token。去重键可以是 (run_id, step_run_id, attempt_no, event_type)；事件 ID 不应替代业务级幂等键。[架构推论]

5.3 外部副作用的限制

向邮件、支付、发布系统发送请求时，数据库事务无法与外部系统形成普通的单一原子事务。若对方支持幂等键，传入稳定键；否则设计先查询、人工确认、补偿或“可能已执行”的不确定状态。禁止宣传“任务重试绝不会重复产生副作用”，除非在具体工具契约下得到验证。[架构推论]

5.4 重试策略

故障类型	默认建议	说明
网络瞬断/429	指数退避+抖动	遵守 Retry-After
模型上下文超限	不盲目重试	缩短上下文或调整任务
权限不足	直接失败/等待授权	重试无意义
审批拒绝	业务返工分支	不是基础设施故障
Worker 崩溃	检查点恢复	防止重复副作用
输出契约不符	有界修复重试	记录次数与成本
外部服务未知结果	标记不确定并核对	防止重复执行

06 · 工作流恢复、人工审批与返工

6.1 检查点设计

每个稳定检查点至少保存 run_id、workflow_version_id、当前可执行节点、已完成节点输出引用、等待条件、审批令牌引用、预算消耗、重试次数、版本号及更新时间。大型中间数据存对象存储，数据库只保留引用和校验摘要。检查点提交与下一任务派发应通过事务性事件衔接。[架构推论]

6.2 人工审批

审批请求包括目标产物版本、待决定事项、可选操作、授权角色、截止时间与失效策略。审批 API 必须防止重复提交、过期提交、非授权提交及版本漂移。审批完成后写入不可变决策记录并发出恢复事件；不能仅依赖前端页面仍然打开。[架构推论]

6.3 审核返工

Studio 的审核 Agent 对选题或研究报告给出 approved | revise | rejected 的结构化结果；revise 进入指定返工节点，携带审核意见与已冻结的上下文引用。设置最大返工次数、预算上限和人工接管条件，避免无限循环。返工应创建新的 StepRun/Attempt 或明确的迭代编号，保留历史结果，不覆盖前次版本。[架构推论]

6.4 工作流版本升级

新 Run 使用新 WorkflowVersion；已有 Run 原则上继续旧版本。若必须迁移，需设计状态映射、数据结构转换、兼容性检查、回滚与审计，不应默认支持无损热迁移。[架构推论]

07 · Agent Runtime 与模型/工具网关

7.1 Runtime Adapter

平台应通过稳定接口接入 LangGraph、Agents SDK 或自研运行时，至少定义 start_step、cancel_step、stream_events、get_usage、serialize_checkpoint（若支持）和 normalize_error。不是每个 SDK 都原生支持全部能力；不支持的能力必须由编排层补足或在选型中视为约束。[架构推论]

7.2 Model Gateway

模型网关负责供应商凭证、模型映射、路由策略、请求超时、速率限制、重试、Token/成本计量和审计摘要。质量要求高的步骤应固定模型配置或记录实际模型标识。供应商返回的 usage 与最终账单可能不一致，应区分估算、供应商报告和结算数据。[架构推论]

7.3 Tool Gateway

工具声明应包含名称、版本、输入/输出 Schema、权限范围、网络目标、超时、幂等能力、风险等级与审计要求。敏感工具默认需要独立授权；高风险写操作可引入人工确认。对于搜索网页、读取文件和外部文档，必须将返回内容视为不可信输入，防范提示注入与越权指令。[架构推论]

7.4 沙箱与隔离

不可信代码执行与任意工具脚本应放在受限容器/沙箱，限制网络出口、文件系统、CPU、内存、执行时长与凭证可见范围。简单多租户数据库行过滤不能替代执行环境隔离；具体隔离等级取决于风险评估。[架构推论]

08 · 数据架构与一致性边界

8.1 存储职责

存储	推荐承载	不宜承载
PostgreSQL	身份、定义、Run、审批、元数据、审计索引、Outbox	大型二进制文件
Object Storage	报告、附件、原始资料、导出包、检查点大对象	高频事务锁
Redis（可选）	缓存、短时速率计数、队列实现依赖	唯一业务真相源
Vector/FTS Index	资料检索、语义索引	审批/权限权威记录
Telemetry Backend	Trace、Metrics、Logs	唯一 Run 状态真相源

8.2 一致性原则

业务关键操作（Run 创建、审批决定、ArtifactVersion 登记、交付冻结）应尽量在单个事务边界内完成。跨服务采用事件驱动最终一致性，明确“已提交/待同步/同步失败”状态。读取 UI 可以使用物化视图，但应显示数据新鲜度，不能让缓存状态覆盖权威状态。[架构推论]

8.3 产物一致性

上传产物时先写临时对象，再计算校验和、完成病毒/格式检查、登记 ArtifactVersion；若数据库事务失败，应清理孤儿对象。下载时校验租户与版本权限，使用短期受控 URL。审核与交付必须绑定不可变版本及校验摘要。[架构推论]

09 · API、事件与契约设计

9.1 API 设计原则

API 以资源为中心：/agents、/agent-versions、/workflows、/runs、/approvals、/artifacts、/deliveries。异步创建 Run 返回 202 Accepted 和可查询的 run_id；请求幂等由客户端提供稳定键。所有资源查询必须执行租户/工作空间权限校验，不能只依赖前端隐藏入口。[架构推论]

POST /v1/workflows/wf_123/runs
Authorization: Bearer <token>
Idempotency-Key: research-request-20261101-001
Content-Type: application/json

{"input":{"topic":"非遗数字化创新"},"budget":{"max_usd":8},"workspace_id":"ws_01"}

{
  "run_id": "run_01",
  "workflow_version_id": "wfv_12",
  "execution_status": "queued",
  "evaluation_status": "pending",
  "review_status": "not_required",
  "delivery_status": "not_ready",
  "links": {"self": "/v1/runs/run_01", "events": "/v1/runs/run_01/events"}
}

9.2 事件 Envelope

{
  "event_id": "evt_01",
  "event_type": "step.completed",
  "schema_version": "1.0",
  "tenant_id": "tenant_01",
  "workspace_id": "ws_01",
  "run_id": "run_01",
  "step_run_id": "step_04",
  "attempt_id": "attempt_02",
  "occurred_at": "2026-11-01T08:00:00Z",
  "correlation_id": "corr_01",
  "payload": {"artifact_version_id": "av_07"}
}

该示例是平台自定义事件契约，不是声称 CloudEvents 强制要求这些字段。若采用 CloudEvents，应按其标准 envelope 映射业务字段到扩展属性或 data。[规范/官方 + 架构推论]

9.3 SSE 与 Webhook

SSE 面向在线前端实时查看进度；断线重连需支持事件游标或从权威状态重建。Webhook 面向外部系统，要求签名、时间戳、重放防护、重试、死信和订阅权限。两者都是状态通知渠道，不是状态权威存储。[架构推论]

9.4 错误契约

统一返回 code、message、request_id、retryable 和必要的 details。典型错误包括 RUN_STATE_CONFLICT、APPROVAL_EXPIRED、TENANT_ACCESS_DENIED、BUDGET_EXCEEDED、ARTIFACT_VERSION_MISMATCH。不向用户泄露供应商密钥、内部路径或跨租户对象存在性。[架构推论]

10 · 权限、多租户与安全架构

10.1 身份链

区分登录用户身份、平台服务身份、Worker 执行身份和外部工具凭证。Run 创建时保存发起主体、所属租户、工作空间、授权上下文和策略版本；Worker 执行时再次检查仍然有效的关键权限。不能将用户的全权限访问令牌原样长期存入队列。[架构推论]

10.2 租户隔离

数据库查询始终携带租户上下文；可以在适用场景下叠加 PostgreSQL Row-Level Security，但不能只依赖 ORM 开发习惯。对象存储路径与签名 URL、队列任务、缓存键、Trace 属性和日志也必须包含隔离边界。对外错误信息避免泄露其他租户对象的存在。[架构推论]

10.3 密钥与敏感数据

凭证使用专门的 Secret Manager 或受控加密存储，提供轮换与撤销；日志和 Trace 默认脱敏，Prompt、文档、用户上传内容不应无限期全文记录。建立数据分类、保留期限、删除策略、导出审批和访问审计。[架构推论]

10.4 Prompt Injection 与工具风险

来自网页、检索结果、附件和其他 Agent 的内容都可能包含恶意指令。模型输出不得直接变成高权限操作的授权依据；工具网关执行白名单、Schema 验证、权限检查和必要的人审。敏感外发、批量删除、付费操作须有独立业务策略。[架构推论]

11 · 可观测性、评估与成本治理

11.1 三类事实

业务事件回答“Run 的合法状态是什么”；Telemetry 回答“系统执行时发生了什么”；Evaluation 回答“输出质量是否达到标准”。三者通过 run_id、step_run_id、attempt_id、trace_id 关联，但不能混为一谈。[架构推论]

11.2 核心指标

指标	建议定义	风险提示
Run 完成率	succeeded Run / 终结 Run	不等于合格交付率
合格交付率	满足评估和审核的交付 / 应交付任务	需定义分母与时间窗
端到端耗时	完成时间－创建时间	区分审批等待
队列等待	首次开始执行－入队时间	需报告 P50/P95/P99
重试率	发生额外 Attempt 的 StepRun 占比	区分业务返工
工具失败率	失败工具调用 / 有效工具调用	供应商与工具分类
单份合格报告成本	相关总成本 / 合格报告数	不能只统计 Token
审批积压	超过目标等待时长的 Approval 数	需要明确责任人

11.3 Trace 与成本

采用 OpenTelemetry 传播上下文和收集遥测；生成式 AI 语义约定随规范版本演进，应在具体实现时固定版本并验证字段。成本账本区分模型估算、供应商 usage、基础设施分摊与最终账单；每次调用归因到 Run、AgentVersion、Workspace 与 Tenant。[规范/官方 + 架构推论]

11.4 告警与 SLO

优先监测无法恢复的 Run、队列堆积、审批超时、异常成本增长、外部供应商错误、存储失败和租户隔离异常。告警需去重、分级、归属、抑制与升级；SLO 目标应根据实际使用者期望和历史数据确定，本文不虚构目标值。[架构推论]

12 · 部署拓扑与容量规划

12.1 MVP 拓扑

flowchart LR
  B[Browser] --> WEB[Next.js Web + API]
  WEB --> PG[(Managed PostgreSQL)]
  WEB --> Q[Queue / Dispatcher]
  Q --> WK[Worker Pool]
  WK --> PG
  WK --> OS[(Object Storage)]
  WK --> M[Model & Tool Providers]
  WEB -. logs .-> MON[Monitoring]
  WK -. traces .-> MON

Web/API 与 Worker 应独立部署，以便短请求与长任务分别伸缩。生产部署需要考虑网络出口、秘密管理、备份、监控与运行环境隔离。单实例数据库可作为初期选择，但必须明确备份、恢复和容量风险。[架构推论]

12.2 扩容触发条件

症状	首先检查	可能的扩容动作
API 延迟升高	DB 查询、连接池、缓存命中	API 水平扩容/查询优化
Run 排队过久	Worker 并发、模型限流	Worker 扩容/分队列
数据库锁冲突	事务范围、热点行	缩短事务/分区/读模型
外部模型 429	配额、供应商限制	限流、退避、模型路由
Trace 成本过高	采样、基数、保留	分级采样与保留策略
大量审批等待	人员流程、通知机制	批量审批/超时升级

12.3 容量估算

在设计阶段记录 每日 Run 数 × 平均 Step 数 × 每 Step 平均调用数 的量级估算；对 Token、对象存储、Trace、数据库写入、峰值并发分别建模。由于实际数据未知，不能据此宣称某技术栈可支持固定 QPS 或固定用户规模。[待验证]

13 · 参考数据库设计

以下是用于讨论聚合关系的 PostgreSQL 示意 DDL，并非完整生产迁移脚本。实际实现需补充外键、索引、RLS、分区、审计保留和迁移策略。

CREATE TABLE agent_versions (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  agent_id UUID NOT NULL,
  version TEXT NOT NULL,
  spec JSONB NOT NULL,
  checksum TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (agent_id, version)
);

CREATE TABLE workflow_versions (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  workflow_id UUID NOT NULL,
  version TEXT NOT NULL,
  graph JSONB NOT NULL,
  checksum TEXT NOT NULL,
  UNIQUE (workflow_id, version)
);

CREATE TABLE runs (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  workspace_id UUID NOT NULL,
  workflow_version_id UUID NOT NULL REFERENCES workflow_versions(id),
  execution_status TEXT NOT NULL,
  evaluation_status TEXT NOT NULL DEFAULT 'pending',
  review_status TEXT NOT NULL DEFAULT 'not_required',
  delivery_status TEXT NOT NULL DEFAULT 'not_ready',
  state_version BIGINT NOT NULL DEFAULT 0,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE step_runs (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  run_id UUID NOT NULL REFERENCES runs(id),
  node_key TEXT NOT NULL,
  iteration_no INT NOT NULL DEFAULT 0,
  status TEXT NOT NULL,
  lease_token UUID,
  lease_expires_at TIMESTAMPTZ,
  UNIQUE (run_id, node_key, iteration_no)
);

CREATE TABLE outbox_events (
  id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  aggregate_id UUID NOT NULL,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  published_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_runs_tenant_status ON runs (tenant_id, execution_status, created_at DESC);
CREATE INDEX idx_outbox_pending ON outbox_events (created_at) WHERE published_at IS NULL;

约束提醒：UNIQUE (run_id, node_key, iteration_no) 只适用于每次迭代同名节点唯一的工作流模型；并行分支或动态节点需要增加 branch_id / invocation_id。tenant_id 跨表一致性需要复合外键、RLS 或应用层校验共同保障；示意 DDL 未实现这些安全约束。[架构推论]

14 · Studio 端到端案例

14.1 业务场景

用户在 Studio 新建“非遗数字化创新研究”项目，选择研究模板和 Agent 团队，提交研究任务。系统依次完成选题、自动审核、深度调研、分析、人工审批与成果导出；若审核失败，返回指定节点返工。所有阶段保留运行事件、Agent 版本、输入资料、产物版本和成本记录。[架构推论]

14.2 执行时序

sequenceDiagram
  participant U as User
  participant P as Platform API
  participant D as Database
  participant W as Workflow Worker
  participant A as Agent Runtime
  participant H as Human Reviewer
  participant S as Artifact Storage
  U->>P: Create research run
  P->>D: Persist Run + Outbox
  P-->>U: run_id
  W->>D: Claim task
  W->>A: Topic Agent (pinned version)
  A-->>W: Candidate topics
  W->>S: Save ArtifactVersion
  W->>A: Review Agent
  A-->>W: revise / approved
  alt revise
    W->>D: Record feedback + new iteration
    W->>A: Topic Agent revision
  else approved
    W->>A: Research + Analysis
    A-->>W: Draft report
    W->>S: Save draft version
    W->>D: Create Approval + wait
    H->>P: Approve specific version
    P->>D: Decision + Resume Outbox
    W->>S: Export delivery package
    W->>D: Mark delivery result
  end
  U->>P: Get run + artifacts
  P-->>U: Status / links / audit summary

14.3 五个关键失败场景

场景	风险	设计响应
选题 Agent 调用超时	重试导致重复费用	有界重试、usage 记录
审核持续拒绝	无限循环	最大迭代次数、预算门禁
人工审批期间服务重启	审批状态丢失	数据库持久化等待条件
报告导出中 Worker 崩溃	重复导出/孤儿文件	幂等导出任务、对象清理
交付后 Agent 版本升级	历史无法复现	Run 固定版本与配置快照

14.4 建议的用户界面

Studio 左侧显示 Workflow 节点状态，中间显示 Agent 协作事件与人工审批，右侧显示产物和版本；顶部展示 Run 状态、耗时、预算和风险提示。产品界面应允许从某次审核意见定位对应的 ArtifactVersion 和 StepRun。原始 Trace 进入开发者诊断视图，不直接暴露敏感工具入参或模型私有推理。[架构推论]

15 · 设计决策与 ADR

15.1 建议记录的 ADR

ADR	决策问题	候选与验证
ADR-001	模块化单体还是微服务	部署/团队成本对比
ADR-002	PostgreSQL 是否作为 Run 真相源	事务与恢复测试
ADR-003	Workflow Engine	LangGraph / Temporal / 轻量状态机 PoC
ADR-004	Agent Runtime	Python/TypeScript SDK 对照
ADR-005	队列与 Outbox	故障注入和重复投递
ADR-006	Artifact 存储与版本	一致性与恢复测试
ADR-007	多租户隔离	越权与数据穿透测试
ADR-008	监控与成本	Trace 完整性、预算归因

15.2 ADR 模板

# ADR-XXX · 决策标题
状态：Proposed / Accepted / Superseded
背景与约束：
候选方案：
评估标准：
实验与证据：
决定及理由：
被拒绝方案：
已知风险：
迁移与退出策略：
复审触发条件：

16 · 分阶段工程落地路线

阶段	交付重点	退出标准
S0 · 基线	代码审计、领域模型、ADR、环境	现状可复现、约束明确
S1 · 单 Run	AgentVersion、Run、Worker、Artifact	崩溃后恢复且状态一致
S2 · 多节点	Workflow、审核返工、人工审批	跨重启审批与返工正确
S3 · 可运营	权限、审计、监控、预算、备份	关键故障演练通过
S4 · 平台化	多工作空间、API/SDK、版本治理	跨项目复用与隔离通过
S5 · 扩展	性能优化、插件、组织治理	有实测瓶颈与收益证据

阶段顺序允许根据现有代码和业务优先级调整；不应把上述表格当成 Studio 已完成进度。[待验证]

17 · 故障模式与恢复策略

故障模式	观测信号	恢复机制	验证方法
API 在提交后超时	客户端未知结果	幂等键查询已有 Run	重复请求
Outbox Dispatcher 宕机	待发布事件积压	重启后继续扫描	故障注入
消息重复投递	相同业务键重复出现	消费幂等与租约	重放消息
Worker 执行中被杀	心跳消失/租约过期	接管与检查点恢复	kill -9 演练
模型供应商不可用	错误率上升	退避/熔断/可选路由	模拟 5xx
工具副作用结果不明	超时但外部可能成功	对账/人工确认	超时注入
数据库连接耗尽	连接池报警	限流、池配置、降载	并发测试
对象存储写入失败	导出任务失败	有界重试/孤儿清理	故障注入
审批链接过期	审批 API 拒绝	重新签发受控链接	过期测试
租户访问穿透	异常跨租户请求	服务端策略拒绝	安全测试
Token 成本异常	预算告警	停止新调用/人工确认	预算模拟
部署版本不兼容	Worker 无法反序列化	版本固定/滚动回退	兼容性测试

18 · 工程验收与测试矩阵

下表是待执行的参考测试，不是测试报告。验收时应记录环境、提交版本、输入、预期、实际结果、日志与责任人。

ID	测试场景	预期结果
T01	创建 Run	返回唯一 run_id 与可查询状态
T02	请求幂等	重复 Idempotency-Key 不创建第二 Run
T03	跨租户创建	拒绝非法 workspace_id
T04	版本固定	运行时保持原 AgentVersion
T05	工作流版本固定	新发布不改变已启动 Run
T06	合法状态转移	按状态机成功迁移
T07	非法状态转移	返回冲突且不改数据
T08	并发状态更新	版本冲突得到明确反馈
T09	Outbox 原子性	Run 与待发布事件同时提交
T10	Dispatcher 崩溃	恢复后事件仍可投递
T11	重复队列消息	仅一个有效业务结果
T12	Worker 租约超时	任务可被接管
T13	旧 Worker 回写	fencing token 拒绝陈旧提交
T14	Worker 强制终止	检查点恢复
T15	步骤超时	进入定义的重试/失败分支
T16	429 限流	遵守退避与 Retry-After
T17	权限失败	不进行无意义自动重试
T18	工具未知结果	标记不确定并阻止盲目重试
T19	工具幂等键	支持的外部工具不重复执行
T20	审核返工	迭代号与意见完整保存
T21	返工上限	达到上限后进入人工接管
T22	人工审批暂停	Worker 不长期占用
T23	审批跨重启	恢复审批等待与执行
T24	重复审批	只有一次有效决策
T25	越权审批	拒绝并审计
T26	过期审批	拒绝并提示更新
T27	产物不可变	旧版本哈希与内容不变
T28	审核版本绑定	新版本不继承旧审核
T29	导出重复执行	不产生重复交付记录
T30	对象存储失败	记录失败并清理孤儿对象
T31	SSE 断线重连	补齐事件或重建权威状态
T32	Webhook 重放	签名/时间窗/去重有效
T33	预算耗尽	阻止后续计费调用
T34	模型 usage 缺失	标记估算不伪装实账
T35	Trace 关联	run_id 与 trace_id 可关联
T36	敏感日志脱敏	不暴露凭证和受限内容
T37	跨租户产物下载	拒绝并不泄露对象存在
T38	队列积压告警	达到条件后触发告警
T39	数据库备份恢复	恢复后状态与产物引用一致
T40	Schema 向前兼容	旧 Worker 按策略运行或拒绝
T41	部署回滚	API/Worker 兼容恢复
T42	高并发 Run	无丢失/重复终结状态
T43	取消执行	取消请求与实际结果可区分
T44	外部副作用取消	明确已执行副作用不可自动撤销
T45	质量门禁	执行成功但评估失败不交付
T46	交付追溯	从交付定位 Run/版本/审核
T47	审计完整性	高风险管理操作有可追溯记录
T48	恢复演练	记录 RTO/RPO 实测值而非预设
T49	数据删除	满足保留策略且无跨租户影响
T50	供应商故障	故障范围隔离并有用户提示

19 · 常见设计误区与修正

误区	后果	修正
把 Agent SDK 当成完整平台	缺少权限、版本、审批、审计	独立 Control Plane
只用内存保存工作流	重启丢失执行状态	持久化检查点
把队列当真相源	业务状态不可查询或回放	数据库权威状态 + Outbox
假设消息只投递一次	重复执行、重复计费	幂等、租约、fencing
所有失败统一重试	权限错误、预算爆炸	分类错误与重试策略
审批绑定“最新版”	审核结论漂移	绑定 ArtifactVersion
把执行成功视为质量通过	低质报告自动交付	独立评估与审核状态
全量记录 Prompt/文档	隐私与存储风险	脱敏、最小化、保留策略
一开始全面微服务化	开发与运维复杂度高	模块化单体渐进拆分
先定框架再写需求	架构被工具牵引	从质量属性与 PoC 出发
只做 happy path Demo	无法处理崩溃和返工	故障注入与恢复验收
把 Trace 当作业务审计	状态不完整、保留不一致	独立审计事件

20 · 研究局限与后续问题

本文没有获得 Studio 当前仓库、部署配置、实际负载、预算、人员分工和用户使用数据，因此不能证明某一候选方案最优。尤其需要验证：① LangGraph/Temporal/轻量状态机在同一审核返工流程上的恢复成本；② TypeScript 与 Python Worker 的实际维护成本；③ 供应商工具的幂等与超时行为；④ 数据库租户隔离；⑤ Trace 与产物的存储成本；⑥ 备份恢复时间。架构应随真实证据更新 ADR，而不是将本文参考图直接当作生产部署说明。[待验证]

跨章节契约修订说明（v1.3-r1，2026-11-01）

本节是第五轮审核后的规范对齐补充，不代表前文所有局部示例已经被自动改写为统一 schema，也不代表完成工程测试。统一契约详见 04-Agent-Platform-Canonical-Contracts-v1.3-r1.md；当本文的参考状态、字段或接口示例与统一契约不一致时，应以统一契约作为后续实现候选基线，并在真正部署前完成迁移与验证。

统一核心状态： [平台设计决策] canonical execution_status 为 queued/running/waiting/paused/cancelling/succeeded/failed/cancelled/timed_out；waiting_approval 等产品状态由 status_reason 映射，cancel_requested 归入 desired_action。本文先前的简化状态图是架构示意，不是冻结后的数据库枚举。状态转换须以 status_version 原子更新；终态不可原地恢复。

统一业务对象与接口： Run 固定 AgentVersion/WorkflowVersion；Attempt 追加不可覆盖；审核绑定 ArtifactVersion；交付固定不可变 Manifest。POST /runs 的 202 仅表示受理，幂等键作用域、摘要、TTL 和冲突处理属于平台自定义契约。

可靠执行： [架构推论/待测试] Outbox 至少一次投递、消费去重、租约 fencing 只约束平台内部提交，不能保证外部工具 exactly-once。业务状态事件独立于 OpenTelemetry 遥测；上线前需进行故障注入、API 契约和数据迁移测试。

附录 A：参考文献与原始资料

以下以官方规范、项目文档和工程实践资料为主。链接用于核验概念和具体机制；不代表本文示例架构已由这些项目联合验证。技术文档可能更新，正式开发时应核对版本。

1. PostgreSQL Documentation, Transactions. www.postgresql.org/docs/current/tutorial-transactions.html
2. PostgreSQL Documentation, Explicit Locking. www.postgresql.org/docs/current/explicit-locking.html
3. PostgreSQL Documentation, Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html
4. PostgreSQL Documentation, JSON Types. www.postgresql.org/docs/current/datatype-json.html
5. OpenTelemetry, Documentation. opentelemetry.io/docs
6. OpenTelemetry, Context Propagation. opentelemetry.io/docs/concepts/context-propagation
7. OpenTelemetry, Semantic Conventions for Generative AI. opentelemetry.io/docs/specs/semconv/gen-ai
8. W3C, Trace Context. www.w3.org/TR/trace-context
9. CloudEvents, Specification. github.com/cloudevents/spec
10. CNCF, Cloud Native Glossary: Idempotent. glossary.cncf.io/idempotent
11. AWS Prescriptive Guidance, Transactional Outbox Pattern. docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
12. AWS Prescriptive Guidance, Saga Orchestration Pattern. docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/saga-orchestration.html
13. Temporal, Documentation. docs.temporal.io
14. LangGraph, Documentation. docs.langchain.com/oss/python/langgraph/overview
15. OpenAI, Agents SDK Documentation. openai.github.io/openai-agents-python
16. OWASP, Top 10 for LLM Applications. genai.owasp.org/llm-top-10
17. NIST, AI Risk Management Framework. www.nist.gov/itl/ai-risk-management-framework
18. Google, Site Reliability Engineering Book. sre.google/sre-book/table-of-contents
19. Google, The Site Reliability Workbook. sre.google/workbook/table-of-contents
20. OpenAPI Initiative, Specification. spec.openapis.org/oas/latest.html
21. IETF, HTTP Semantics (RFC 9110). www.rfc-editor.org/rfc/rfc9110
22. Redis, Documentation. redis.io/docs/latest
23. Prometheus, Documentation. prometheus.io/docs/introduction/overview
24. Kubernetes, Documentation. kubernetes.io/docs/home

附录 B：研究证据、验证声明与适用边界

规范支持的事实：PostgreSQL 提供事务、锁与 RLS 机制；OpenTelemetry 提供分布式追踪/指标/日志相关规范与实现生态；W3C Trace Context 规定跨服务 Trace 上下文传播；CloudEvents 定义事件封装格式；HTTP 与 OpenAPI 提供 API 语义和描述基础。具体细节以所采用版本的官方规范为准。

架构推论：模块化单体 + Worker、数据库权威状态、Outbox、版本固定、独立审批、可追溯产物、租户策略及逐步扩容，是针对 Studio 目标场景形成的建议，不属于任何单一标准强制的系统架构。

尚未验证：本文未读取 Studio 源代码，未实际部署候选框架，未运行 T01 - T50 测试，未完成压力、成本、灾备、安全或可用性基准。示例 JSON/SQL/Mermaid 为参考设计，不应不经校验直接用于生产。引用材料并不构成对特定平台商业条款、当前版本兼容性或性能的保证。

后续衔接：下一篇为 04/04/04 · 如何分阶段开发 Agent Platform？ - Development Roadmap，应将本文模块边界、不变量、风险和测试矩阵转化为可执行的里程碑、依赖、交付物及验收标准。