P1 · 平台如何统一管理和控制 Agent？ - Control Plane
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何以统一的控制面管理 Agent 定义、部署、执行准入、生命周期、策略与资源，并与执行面保持安全、可追踪、可恢复的协作？
专题导读
本篇属 Technical Architecture。Control Plane（控制面）是 Agent Platform 的管理与决策职责集合：它将用户意图和平台策略转化为可验证、可审计的执行安排，并持续维护 Agent 及相关对象的期望状态。它并不等同于后台管理页面，也不意味着所有请求都必须经过单个“控制面微服务”。
本篇承接 Fundamentals 的对象模型及本章 Technical Architecture 总纲，回答五个问题：控制面管理什么；对哪些动作做决策；如何把决策交给执行面；怎样处理异步任务与故障；如何把权限、配额、版本和审计嵌入控制流程。本文以多 Agent 研究报告 Studio 为贯穿案例，给出参考对象模型、接口契约、状态机、时序图、故障矩阵与验证清单。
研究边界：P1 研究平台级控制职责和协作契约。P2 深入研究实际执行与资源隔离；P3 研究 Agent Registry；P5 研究部署和运行生命周期；P6 研究工作流调度；P11、P12 研究租户隔离及治理策略。本文只说明它们与控制面的接口，不代替这些专题。
研究结论
- 控制面负责决定“允许什么、执行什么版本、由谁承载、如何跟踪”，执行面负责“实际运行并报告事实”。 控制面可以委派调度和部分执行期决策，但不能把授权和资源边界仅寄托于模型提示词。
- 控制面的核心是对象状态与契约，不是界面或某个框架。 Agent Definition、Version、Deployment、Run、Attempt、Approval、Policy Decision 等对象必须具有稳定标识和明确关系。
- 一次运行必须固定可追溯的执行快照。 至少记录 Agent/Workflow 版本、配置引用、租户、调用主体、权限范围及资源预算；敏感凭据使用安全引用，不复制明文。
- 执行请求需要“鉴权 → 策略/配额准入 → 版本解析 → 持久化 → 可靠派发 → 结果归并”闭环。 仅在 HTTP 处理器内直接启动长任务会使故障恢复与审计变得困难。
- 控制面与执行面之间宜采用可重试的异步契约，并按至少一次交付的现实设计幂等。 不应默认消息恰好一次送达，也不能把“请求已受理”误写成“任务已成功”。
- 期望状态与观测状态应区分。 控制面声明部署目标和运行意图，执行面报告实际执行、健康和结果；对账机制负责处理差异。
- 从模块化单体控制服务 + 独立 Worker 起步通常更符合 Studio 的 MVP 阶段。 是否拆分服务取决于隔离、负载、团队和可靠性要求，而非平台名称。
一、概念与边界
1.1 什么是控制面
控制面是一组负责平台资源声明、管理决策、执行准入、协调与治理的能力。它面向用户、开发者、管理员及自动化调用方，接收创建、配置、发布、启动、暂停、取消、审批等意图，检查是否允许，记录其结果，并驱动执行面采取行动。
可将平台简化为三个协作视角：
| 视角 | 核心职责 | 典型输入 | 典型输出 |
|---|---|---|---|
| Control Plane | 管理对象、策略判断、准入、调度意图、生命周期协调 | API 命令、版本变更、审批决定 | 状态变更、执行指令、审计事件 |
| Execution Plane | 执行 Agent System、工具调用、隔离与运行报告 | 运行快照、租约/令牌、任务消息 | 运行事件、结果、指标、产物 |
| Shared Services | 身份、数据库、队列、密钥、存储、观测等基础能力 | 两侧的服务调用 | 身份与策略数据、持久化及遥测 |
“控制面 / 数据面”在基础设施领域具有广泛用法；在 Agent Platform 中，Execution Plane 更准确地强调长时间运行、模型调用与工具操作。二者是逻辑划分，不保证网络隔离，也不天然意味着微服务。
1.2 控制面不是什么
- 不是单纯的 Admin Console。前端管理页只是控制面的一个入口。
- 不是 Agent 的推理循环。模型如何规划和调用工具属于 Agent/Agent System 的执行机制。
- 不是 Workflow Engine 的同义词。工作流引擎可能处于执行面或独立编排服务；控制面负责其定义、启动、权限与生命周期契约。
- 不是“万能中枢”。模型推理、文件解析、长任务执行和工具沙箱不应因控制方便而全部挤入同步 API 进程。
- 不是安全的唯一执行点。工具访问、网络隔离、凭据作用域等需要在实际执行路径再次强制校验。
1.3 控制面研究的抽象层级
- 产品操作：用户点击“运行报告”，或调用
POST /runs。 - 领域命令：
CreateRun、ApproveRun、CancelRun。 - 决策与状态：鉴权、策略判断、版本固定、预算预留、状态迁移。
- 执行契约：向 Worker 发布
RunRequested、RunCancellationRequested等消息。 - 部署形态：同一进程、模块化单体、独立控制服务或分布式控制集群。
以上五层不能互相替代；例如增加一个“运行”按钮并不等于已经实现可靠的控制面。
二、控制面管理的对象与关系
2.1 核心对象清单
| 对象 | 作用 | 关键关系 | 控制面职责 |
|---|---|---|---|
| Tenant / Organization | 资源与治理边界 | 拥有 Workspace、策略、配额 | 身份与归属、隔离上下文 |
| Workspace / Project | 协作与业务组织 | 容纳 Agent、任务、产物 | 成员权限、资源可见性 |
| Agent Definition | Agent 的逻辑身份 | 对应多个 Version | 创建、编辑、归档 |
| Agent Version | 固定配置与依赖 | 被 Deployment/Run 引用 | 校验、发布、撤销 |
| Workflow Version | 固定编排定义 | 被 Run 引用 | 版本解析与准入 |
| Deployment | 版本在环境中的可用配置 | 指向版本和环境 | 期望状态、发布、回滚 |
| Runtime Instance | 实际运行承载体 | 承载 Attempt | 发现、健康、分配策略 |
| Run | 一次业务执行 | 固定快照、含多个 Attempt | 准入、状态、取消、审计 |
| Attempt | 一次执行尝试 | 属于 Run | 重试条件、次数与去重 |
| Approval | 人工决策记录 | 关联 Run/步骤 | 审批权限、有效期与结果 |
| Artifact | 输出成果 | 属于 Run/Project | 元数据、访问授权、保留 |
| Policy / Quota | 规则与预算 | 作用于租户、资源、动作 | 决策、计量、审计 |
关键约束：Run 是业务执行的稳定身份，Attempt 是一次尝试；Worker 重启或重试不应自动创建一个全新的业务 Run。Deployment 是期望可用状态，不等于一个具体进程；Agent Version 是不可变定义，不等于运行中的实例。
2.2 对象关系示意
flowchart TD
T[Tenant / Organization] --> W[Workspace / Project]
W --> D[Agent Definition]
D --> V[Agent Version]
V --> DEP[Deployment]
W --> R[Run]
V -.固定引用.-> R
DEP -.可作为运行入口.-> R
R --> A[Attempt]
A --> RI[Runtime Instance]
R --> AP[Approval]
R --> ART[Artifact]
T --> POL[Policy / Quota]
POL -.准入与约束.-> R这是一张概念图，不代表数据库外键必须逐一按图建立。一个 Run 还可能引用多个 Agent Version、Workflow Version 和资源版本，尤其是在多 Agent 场景中。
2.3 运行快照的最小内容
每次获准启动的 Run 应固定：run_id、tenant_id、project_id、initiator、agent_version_id 或 workflow_version_id、input_ref、policy_version、budget_limit、created_at、trace_id。如果运行依赖多 Agent，应固定各节点版本和依赖引用。
资源密钥应保存为 secret_ref，由运行时按授权领取短期凭据；不要把密钥明文放入 Run 快照、队列消息、日志或审计记录。是否固定模型精确版本取决于供应商支持，若无法固定，应记录可观测的模型标识和调用时间，并明确复现限制。
三、控制面的核心职责
3.1 统一入口与身份上下文
入口可以是 Web UI、REST/GraphQL API、CLI、SDK 或自动化事件。所有入口应进入一致的领域授权流程，避免“UI 禁止但 API 可绕过”的缺陷。请求上下文至少包含调用主体、租户、目标资源、动作、请求关联标识和必要的风险属性。
认证回答“你是谁”，授权回答“你能否对这个对象执行这个动作”。角色（RBAC）、属性（ABAC）或关系（ReBAC）可按需要组合。不能把来自前端的 tenant_id 当作可信权限证明；服务端必须验证调用者与目标租户的关系。
3.2 定义、版本与发布控制
控制面管理 Agent/Workflow 的创建、修改、校验、发布、撤销与引用；具体定义存储与查询由 P3 Agent Registry 深入研究。重要规则包括：草稿可修改、发布版本不可变、部署指向明确版本、运行绑定快照、撤销新启动权限不应无条件破坏已运行任务。
发布流程可包括 schema 校验、工具权限检查、依赖可用性检查、测试门槛、审批和签名/哈希记录。发布与执行是不同权限动作。
3.3 运行准入与资源决策
一次运行请求至少需要通过以下检查：
- 主体是否对该 Project/Agent 拥有
run:create权限。 - 目标版本是否可运行，是否被禁用或撤销。
- 输入是否满足 schema、大小、内容与引用访问约束。
- 所需模型、工具、知识源是否可用且允许访问。
- 租户并发数、速率、令牌预算、货币预算和资源上限是否允许。
- 高风险操作是否需要预先审批，或执行到关键步骤时再次审批。
- 是否能分配到满足隔离和能力要求的执行资源。
配额检查应与预留/扣减策略一致，避免并发请求同时通过检查造成超额。预算估算可能不准确，执行期还需持续计量并设置硬限制或明确的超限处置策略。
3.4 调度意图与执行分配
控制面可以把获准的 Run 放入持久化队列，或交给独立调度器分配 Worker。常见分配条件包括租户隔离、模型/工具可用性、执行环境、地理/数据驻留限制、资源需求、优先级与并发限制。
控制面通常不负责逐 token 调度。执行面可在获授权范围内自行决定具体模型调用、工具执行顺序和局部重试；超出权限、预算或审批边界时需要返回控制面或策略执行点。
3.5 生命周期控制与期望状态
控制面接收 pause、resume、cancel、retry、approve 等命令，校验状态迁移是否允许，并通过事件通知执行面。应区分：
- 命令已接受：控制面持久化意图；不代表执行面已完成。
- 执行已确认：Worker 已观察并处理控制意图。
- 最终状态：Run 已完成、失败、取消或超时，并持久化结果。
暂停、取消通常不是瞬时操作。若 Worker 正在执行不可中断的外部工具调用，控制面只能保证尽力取消，并通过超时、租约失效和后续对账处理残留执行。外部副作用的补偿需要独立设计。
3.6 审计、观测与治理
每个重要控制动作应形成可关联的审计事实：谁、在何时、对哪个对象、请求什么动作、采用哪个策略版本、得到什么决策、最终产生什么结果。审计记录不应直接包含敏感提示词、令牌或凭据。操作日志、分布式追踪、指标和审计日志有不同用途，不能互相替代。
四、控制面与执行面的协作协议
4.1 端到端时序
sequenceDiagram
autonumber
participant U as User / API Client
participant C as Control API
participant DB as Database + Outbox
participant Q as Queue
participant W as Worker / Execution Plane
participant S as Artifact Storage
U->>C: POST /runs + Idempotency-Key
C->>C: Authenticate / Authorize / Policy / Quota
C->>DB: Transaction: Run(QUEUED) + Outbox event
C-->>U: 202 Accepted + run_id
DB-->>Q: Outbox publisher: RunRequested
Q->>W: Deliver run_id + snapshot_ref
W->>DB: Acquire lease / register Attempt
W->>W: Execute pinned Agent/Workflow version
W->>S: Persist artifact (if any)
W->>DB: Report events + terminal outcome
W-->>Q: Acknowledge message
U->>C: GET /runs/{run_id}
C->>DB: Read authorized Run state
C-->>U: State + artifact references示意采用事务性 Outbox：先在同一数据库事务中写入 Run 与待发布事件，再异步投递到队列，避免“Run 已创建但消息丢失”或“消息已发送但 Run 未落库”的双写不一致。Outbox 不会自动解决重复投递；消费者必须幂等。
4.2 参考接口契约
以下接口为教学性参考设计，不是现成平台的官方 API：
| 接口 | 语义 | 关键约束 |
|---|---|---|
POST /v1/runs | 创建并请求运行 | Idempotency-Key、鉴权、版本快照 |
GET /v1/runs/{id} | 查询状态与结果引用 | 资源级授权、租户隔离 |
POST /v1/runs/{id}:cancel | 请求取消 | 状态迁移校验、异步生效 |
POST /v1/runs/{id}:resume | 恢复可恢复任务 | checkpoint 有效性、审批状态 |
POST /v1/approvals/{id}:decide | 审批决策 | 审批主体、一次性决定、过期校验 |
POST /v1/deployments | 创建部署意图 | 版本不可变引用、发布权限 |
GET /v1/events?run_id=... | 查询运行事件 | 过滤、分页、授权与保留期 |
创建运行的参考请求：
{
"project_id": "proj_123",
"workflow_version_id": "wfv_2026_10_31_01",
"input_ref": "obj://tenant-a/inputs/request-42.json",
"execution_profile": "standard",
"budget": { "max_cost_usd": 3.0, "max_duration_seconds": 1800 }
}参考响应：
{
"run_id": "run_8f2c",
"status": "QUEUED",
"accepted_at": "2026-10-31T12:00:00Z",
"status_url": "/v1/runs/run_8f2c"
}服务端不得直接信任请求中任何自称拥有高权限的字段；执行快照必须由服务端解析、验证和固定。预算金额仅用于展示示例字段，并非推荐定价。
4.3 参考事件契约
{
"event_id": "evt_001",
"event_type": "RunRequested",
"schema_version": 1,
"run_id": "run_8f2c",
"tenant_id": "tenant_a",
"snapshot_ref": "db://run_snapshots/run_8f2c",
"occurred_at": "2026-10-31T12:00:00Z",
"trace_id": "trace_abc"
}事件仅包含必要的标识与受控引用。Worker 获取快照时再次验证租户、租约与运行权限。对于敏感操作，不能仅凭可伪造的队列字段完成授权。
4.4 幂等、去重与顺序
- API 幂等：同一调用主体、作用域、Idempotency-Key 和请求摘要应返回同一业务结果；同键不同内容应拒绝或显式冲突。
- 消息去重：以
event_id、run_id、attempt_id和状态版本控制重复消费。 - 状态并发：使用版本号/CAS 或数据库事务，防止旧事件覆盖终态。
- 事件乱序：按 Run 内单调序号或状态版本归并，不依赖跨队列全局顺序。
- 外部副作用：发送邮件、支付、写第三方系统等需要业务幂等键、审批和补偿策略；平台无法凭队列去重保证外部世界“恰好一次”。
五、控制面的状态机与一致性
5.1 Run 状态机（参考）
stateDiagram-v2
[*] --> QUEUED
QUEUED --> RUNNING: Worker lease acquired
QUEUED --> CANCELLING: cancel requested
RUNNING --> WAITING_APPROVAL: approval gate
WAITING_APPROVAL --> QUEUED: approved and resumed
WAITING_APPROVAL --> CANCELLING: rejected / cancelled
RUNNING --> PAUSING: pause requested
PAUSING --> PAUSED: checkpoint confirmed
PAUSED --> QUEUED: resume accepted
RUNNING --> SUCCEEDED: committed outcome
RUNNING --> FAILED: terminal failure
RUNNING --> CANCELLING: cancel requested
CANCELLING --> CANCELLED: stop confirmed
CANCELLING --> FAILED: cancellation failure policy
QUEUED --> FAILED: admission expiry
SUCCEEDED --> [*]
FAILED --> [*]
CANCELLED --> [*]这是教学性状态机，具体实现可增加 TIMED_OUT、RETRY_SCHEDULED、EXPIRED 等状态。审批拒绝是否取消整个 Run、暂停是否可恢复、失败后重试是新 Attempt 还是新 Run，均应由产品语义和执行契约明确规定。
5.2 期望状态与观测状态
对于 Deployment：期望状态可能是“版本 v3、并发 4、环境 production”，观测状态可能是“当前仅 3 个健康 Worker”。控制面对账器定期比较二者并触发修复、告警或回滚。
对于 Run：期望状态可能是 CANCEL_REQUESTED，观测状态可能仍是 RUNNING。若控制面在取消请求时立即写入 CANCELLED，将掩盖仍在运行的外部副作用。因此建议分别保存控制意图与执行事实，或采用能表达中间状态的状态机。
5.3 租约、心跳与失联
Worker 可通过带过期时间的租约声明对 Attempt 的执行权；租约超时后，调度器按策略回收或重新分配。对于可能发生长时间停顿的任务，必须考虑：
- 心跳延迟不等于进程必然死亡；可能出现网络分区。
- 旧 Worker 恢复后可能与新 Worker 并行执行，需要 fencing token 或等价机制阻止过期持有者写入受保护状态。
- 对外部系统的副作用未必受平台 fencing 保护，仍需外部幂等与人工核查。
- checkpoint 必须记录兼容的执行版本、状态 schema 和资源引用，否则恢复可能失败。
六、平台安全与治理的控制点
6.1 策略决策与执行位置
可以借用 Policy Administration Point、Policy Decision Point、Policy Enforcement Point 等概念组织策略，但具体实现未必需要独立策略引擎。常见控制点如下：
| 控制点 | 控制面责任 | 执行面/资源侧责任 |
|---|---|---|
| 创建 Agent | 验证创建者与 Workspace 权限 | 不适用 |
| 发布版本 | 校验依赖、风险、审批 | 加载已批准版本 |
| 启动 Run | 认证、授权、配额、预算预留 | 验证租约与运行快照 |
| 调用工具 | 颁发最小权限范围与策略 | 在工具网关/沙箱强制执行 |
| 访问文件 | 生成受控资源引用 | 校验租户、路径、有效期 |
| 人工审批 | 确认审批者、决定和过期时间 | 审批前阻止对应副作用 |
| 取消与回滚 | 记录意图、授权、对账 | 停止执行、报告补偿结果 |
关键原则：控制面准入通过，不代表执行过程中所有操作都被永久授权。执行期权限可因令牌过期、策略变更或风险升级而被拒绝。
6.2 多租户与资源隔离
租户边界必须贯穿 API、数据库查询、缓存键、队列消息、对象存储路径、Worker 调度、工具凭据和审计日志。共享 Worker 是否足够安全取决于代码执行风险、凭据隔离和数据敏感度；高风险任务可使用容器/沙箱或专用执行池。控制面要保存隔离策略，实际隔离由执行环境与数据访问控制落实。
6.3 配额、预算与公平性
平台应区分：请求速率、并发 Run、排队深度、模型令牌、工具调用、CPU/内存、存储与货币成本。配额是准入边界，计量是实际消耗记录，预算是支出控制目标。预估费用可能与真实消耗不同，需明确预留、结算、超额与退款策略。对不同租户的公平调度应考虑饥饿、优先级和资源争用。
七、三种实现模式及取舍
| 模式 | 适用条件 | 优点 | 风险 |
|---|---|---|---|
| 模块化单体控制服务 + Worker | 单团队、早期 MVP | 事务边界简单、开发快 | 后期模块耦合与容量边界 |
| 独立控制服务 + 队列 + Worker 池 | 多团队、异步任务增长 | 扩容和隔离较灵活 | 事件一致性、调试复杂度 |
| 多租户控制集群 + 分层执行池 | 高并发、多组织、强隔离 | 独立治理、分级资源调度 | 运维成本、复杂度、策略一致性 |
不要把“控制面和执行面分责”误认为“必须部署成两个微服务”。即使采用单体，也应将控制 API、领域服务、持久化和执行 Worker 的契约隔离出来。
7.1 Studio 的建议起步架构
flowchart LR
UI[Studio Web UI] --> API[Platform API / Control Modules]
API --> DB[(PostgreSQL)]
API --> OUT[Outbox Publisher]
OUT --> Q[(Task Queue)]
Q --> WK[Agent System Worker]
WK --> MODELS[Models / Tools / Knowledge]
WK --> STORE[(Artifact Storage)]
WK --> DB
API --> AUTH[Identity / Policy / Quota]
API --> OBS[Audit / Telemetry]
WK --> OBS这是逻辑参考图。早期可以让 Outbox Publisher 与 API 共享部署；执行 Worker 独立进程，避免长任务占用 Web 请求。PostgreSQL 可作为状态主存储，任务队列可按技术选型采用受支持的消息/作业系统。是否采用 Redis、消息代理或专用工作流引擎，应由负载和恢复要求决定。
7.2 Studio 的控制面动作实例
用户在 Project 中启动“城市文化研究报告”工作流：
- 控制面验证用户在该 Project 的运行权限，并解析工作流的已发布版本。
- 固定选题、调研、分析、审核等 Agent 的版本和允许工具，创建 Run 快照。
- 检查研究预算、并发限制与可访问的数据源；将 Run 持久化为
QUEUED。 - Worker 执行选题 Agent 和审核 Agent 的循环；每个关键步骤记录事件与检查点。
- 到达“用户确认选题”节点，执行面报告
WAITING_APPROVAL，控制面创建 Approval 对象。 - 用户确认后，控制面校验审批权限与版本，发出恢复命令；Worker 继续深度调研。
- 报告产物写入对象存储，控制面登记 Artifact 元数据、权限和归属，Run 进入终态。
这个案例说明：控制面管理“能否做、做哪个版本、如何受控推进”；Agent System 管理“具体怎样研究、分析和生成报告”。
八、常见失败模式与防护
| 失败模式 | 根因 | 防护或恢复策略 |
|---|---|---|
| Run 入库成功但任务未派发 | 数据库与队列双写 | 事务性 Outbox、重投递与告警 |
| 消息重复导致任务重复 | 至少一次交付 | 幂等消费、租约、Attempt 去重 |
| 用户重复点击创建多个 Run | 无 API 幂等 | Idempotency-Key + 请求摘要 |
| 旧 Worker 覆盖新状态 | 租约过期后继续写 | 状态版本、fencing token |
| 用户跨租户读取产物 | 仅 UI 做隔离 | 服务端资源级鉴权与存储授权 |
| 发布版本被原地修改 | 缺少不可变版本 | 版本快照、内容哈希、发布权限 |
| 取消请求后仍有外部操作 | 把取消视为同步完成 | 中间状态、执行确认、补偿流程 |
| 配额并发超卖 | 只做读后检查 | 原子预留、执行期计量与结算 |
| 审批后运行了另一版本 | 审批对象未绑定快照 | 审批绑定 Run、步骤与版本摘要 |
| 控制面宕机导致状态丢失 | 内存状态与临时队列 | 持久化状态、Outbox、对账器 |
| 任务长时间卡住 | 无超时、心跳、告警 | 租约、超时策略、死信队列 |
| 日志泄漏凭据或输入数据 | 无数据分级与脱敏 | 最小日志、敏感字段脱敏、访问审计 |
九、可观测性与运行指标
控制面至少需要以下观测维度：
| 指标/证据 | 说明 | 用途 |
|---|---|---|
| API 受理延迟、错误率 | 请求到持久化受理 | 控制面可用性 |
| 准入拒绝原因分布 | 权限、配额、版本、策略 | 产品诊断与安全审计 |
| 队列等待时长 | Run 入队到 Worker 领取 | 容量规划 |
| 派发失败与 Outbox 积压 | 控制事件投递状态 | 检测双写/队列故障 |
| 租约超时与重试次数 | Worker 不稳定性 | 可靠性分析 |
| Run 状态滞留时长 | RUNNING、WAITING_APPROVAL 等 | 卡死与审批瓶颈 |
| 预算预留与实际消耗差额 | 估算与计量差异 | 成本治理 |
| 取消完成时延 | 取消意图到执行确认 | 用户体验与风险 |
| 审计事件完整率 | 控制动作是否可追溯 | 合规与事故调查 |
关键关联标识包括 request_id、trace_id、tenant_id、run_id、attempt_id、deployment_id 和 event_id。对高基数标识应谨慎设计指标标签，避免监控系统成本失控；完整标识更适合日志或追踪。
十、工程验证计划与验收标准
下表为建议实施的测试，不是已完成的测试结果。
| 编号 | 测试场景 | 预期结果 |
|---|---|---|
| CP-01 | 未授权用户创建 Run | 403/等价拒绝；无 Run、无派发 |
| CP-02 | 跨租户读取 Run/Artifact | 服务端拒绝；不泄露对象存在性或内容 |
| CP-03 | 相同幂等键重复创建 | 同一作用域返回同一 Run；不重复执行 |
| CP-04 | 相同幂等键不同请求体 | 明确冲突，不静默复用 |
| CP-05 | Run 入库后 Outbox 发布进程崩溃 | 恢复后最终派发，不丢 Run |
| CP-06 | 队列重复投递 | 不产生未经授权的并行副作用 |
| CP-07 | Worker 租约过期后恢复 | 旧持有者不能覆盖新状态 |
| CP-08 | 已发布版本被修改 | 拒绝原地修改，必须产生新版本 |
| CP-09 | Run 执行中修改 Agent 草稿 | 已启动 Run 的快照不变 |
| CP-10 | 并发超额请求 | 原子配额控制；按策略排队/拒绝 |
| CP-11 | 等待审批时尝试执行高风险工具 | 未获批准不得产生副作用 |
| CP-12 | 非审批人提交批准 | 拒绝并记录审计 |
| CP-13 | 取消正在执行的任务 | 明确中间状态；最终确认或超时告警 |
| CP-14 | 控制面重启 | 持久化 Run、审批和派发意图仍可恢复 |
| CP-15 | 队列长时间不可用 | Outbox 积压可观测、可重试、可告警 |
| CP-16 | Worker 重复提交终态 | 终态不可被旧事件覆盖 |
| CP-17 | 任务完成后登记产物 | Artifact 与 Run 归属一致、访问受控 |
| CP-18 | 凭据/敏感信息检查 | API 响应、队列、日志和审计中无明文泄漏 |
建议在验收前明确服务等级目标（例如受理延迟、派发时延、可恢复时间），再根据真实负载测试结果设置阈值；本文不凭空指定生产级 SLO 数字。
10.1 最小可用控制面的完成定义
一个可投入内部试用的最小控制面至少应具备：资源级身份授权；Agent/Workflow 不可变版本引用；Run 持久化与幂等创建；可靠派发；执行状态查询；基础取消/超时；租户或项目级资源边界；审计与故障告警。人工审批、分层租户隔离和复杂策略引擎是否属于第一阶段必需项，应由 Studio 的实际风险和用户范围决定。
10.2 推荐开发顺序
- 先定义对象 ID、状态机、版本与权限模型。
- 实现控制 API、事务写入与运行快照。
- 实现可靠派发、Worker 租约与状态回报。
- 实现取消、超时、失败重试和对账。
- 接入审批、配额、成本计量和产物授权。
- 在故障注入与负载测试中验证边界，再按需要拆分服务。
十一、与 P2 - P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 及 F1 - F2 - F3 - F4 - F5 - F6 - F7 - F8 - F9 - F10 - F11 - F12 的关系
| 关联专题 | P1 提供的接口/约束 | 对方专题深入研究的内容 |
|---|---|---|
| P2 Execution Plane | 运行快照、准入结果、租约与控制命令 | 执行隔离、资源调度、工具与模型调用 |
| P3 Agent Registry | 版本发布、查询与固定引用契约 | 定义存储、索引、版本及依赖 |
| P4 Agent Development Services | 开发操作授权、发布准入 | 构建、校验、调试与开发工具服务 |
| P5 Deployment & Runtime Management | 期望状态、部署命令、Run 状态契约 | 实例、部署、健康、滚动更新与回滚 |
| P6 Workflow Management | 工作流版本引用、启动与审批契约 | DAG/状态机、调度、协作、补偿 |
| P7 Resource & Integration | 资源授权、预算与策略约束 | 模型、工具、知识及连接器接入 |
| P8 Platform API & SDK | 领域命令与错误语义 | 外部接口、SDK、版本与开发者契约 |
| P9 Extensibility & Ecosystem | 扩展权限与注册准入 | 插件生命周期、扩展点、兼容性 |
| P10 Platform Data & Assets | 资产引用、归属与访问控制 | 存储、共享、保留、产物治理 |
| P11 Multi-tenancy & Isolation | 请求租户上下文与资源边界 | 数据、执行、网络、组织隔离 |
| P12 Platform Governance | 决策执行点、审计与配额接口 | 策略、权限、预算、合规治理 |
产品架构中，F1 - F2 - F3 - F4 的创建/配置/调试/发布操作通过控制 API 形成可审计命令；F5 的 Workspace/Project 通过租户和资源模型获得权限边界；F6 - F7 - F8 的执行/协作/监控通过 Run、事件和审批契约实现；F9 - F10 - F11 - F12 的管理、交付、开发者接口和平台管理则依赖控制面的统一授权与状态查询。产品界面不是控制面本身，而是控制能力的一种使用方式。
十二、常见认知误区与自检问题
12.1 常见误区
- “有管理后台就有控制面。” 后台界面可能只做配置 CRUD，缺少版本、准入、生命周期和执行契约。
- “控制面必须是单独微服务。” 逻辑分责与物理拆分是两回事。
- “队列保证任务只执行一次。” 重试和网络故障意味着必须设计幂等与副作用控制。
- “Run 创建成功等于任务执行成功。”
202 Accepted只表示请求已受理。 - “权限校验一次就够。” 执行期工具、文件和外部资源仍需强制执行权限。
- “取消按钮可以立即停止任何外部操作。” 取消是协议，需要执行确认与补偿机制。
- “所有状态都放在 Agent 内存里。” 长任务、审批和恢复需要持久化与可重建状态。
- “多租户只要数据库加 tenant_id。” 队列、缓存、文件、Worker、密钥和审计同样需要隔离。
12.2 自检问题
- 能否说明 Agent Version、Deployment、Runtime Instance、Run、Attempt 各自的身份与生命周期？
- 控制面是否能在不启动任务的情况下验证权限、版本和预算？
- 控制面进程在“写入 Run 后、派发消息前”崩溃会发生什么？
- 同一任务被投递两次、旧 Worker 恢复、审批消息乱序时，系统如何处理？
- 用户点击取消后，哪些状态表示“请求已受理”，哪些表示“执行已停止”？
- 如何证明某份报告由哪个工作流版本、哪些 Agent 版本及哪次 Run 生成？
- 哪些安全约束在控制面判断，哪些必须在 Worker/工具网关再次强制执行？
- 当 Studio 从单团队扩展到多租户时，哪些对象和接口无需重新设计？
第六轮跨章节契约核对（v1.3-r1；2026-11-01）
[平台设计决策 / 待测试] 本节是领域级一致性修订说明，优先于本篇不一致的历史局部示例；不表示已执行数据库迁移、API 合约或运行测试。统一参考：
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md。
本篇 Mermaid 中 WAITING_APPROVAL 为产品可读状态而非统一数据库枚举；映射为 waiting + status_reason=approval。CANCEL_REQUESTED 属于控制意图 desired_action=cancel，不代表已取消；202 Accepted 仅表示受理，不代表 Run 完成。既有图、指标标签和示例需在实施时统一转换。
上述映射不应机械替换其他对象（如 ManagementOperation、Deployment）的同名状态；正式实施应更新 OpenAPI/JSON Schema、SQL 约束、事件消费者、UI 映射及测试。
附录 A：参考文献与原始资料
以下资料用于进一步核对通用架构原则。它们支持特定工程概念，但不代表存在唯一的 Agent Platform 标准架构。具体产品能力和版本应以各项目最新官方文档为准。
- Kubernetes Documentation, Kubernetes Components：控制平面、节点组件与控制循环的通用架构参考。kubernetes.io/docs/concepts/overview/components
- Kubernetes Documentation, Controllers：期望状态与观测状态的协调/对账机制。kubernetes.io/docs/concepts/architecture/controller
- Kubernetes Documentation, Leases：租约、心跳及协调的工程参考。kubernetes.io/docs/concepts/architecture/leases
- AWS Prescriptive Guidance, Transactional Outbox Pattern：数据库状态与事件发布的一致性。docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
- Microsoft Azure Architecture Center, Competing Consumers Pattern：多消费者处理消息及并发控制的通用模式。learn.microsoft.com/en-us/azure/architecture/patterns/competing-consumers
- Microsoft Azure Architecture Center, Idempotent Message Processing（相关可靠消息设计参考，可在其消息模式与架构指南中查阅）。learn.microsoft.com/en-us/azure/architecture
- OpenTelemetry Documentation, Concepts：Trace、Metric、Log 等可观测性概念。opentelemetry.io/docs/concepts
- NIST, AI Risk Management Framework：AI 风险管理与治理的参考框架。www.nist.gov/itl/ai-risk-management-framework
- Open Policy Agent Documentation：策略决策与执行集成的参考。www.openpolicyagent.org/docs
- OWASP, Top 10 for LLM Applications：LLM 应用安全风险与防护参考。genai.owasp.org/llm-top-10
来源适用性说明：Kubernetes 的控制面概念、Outbox 和消息处理模式是跨领域可迁移的工程原则；本篇对 Agent Platform 的对象、API、状态机和 Studio 案例均为研究性综合设计，不应误认为上述文献提供了相同的 Agent Platform 实现。
附录 B：研究证据、验证声明与适用边界
B.1 证据分级
| 内容 | 证据属性 | 适用边界 |
|---|---|---|
| 控制面/执行面职责分离 | 通用架构原则 + 本文定义 | 各平台的具体边界可能不同 |
| 期望状态/观测状态及对账 | 借鉴成熟控制器模式 | 需结合 Agent 执行语义调整 |
| 事务性 Outbox、幂等消费 | 通用分布式系统模式 | 不能保证外部副作用恰好一次 |
| Agent Version/Run/Attempt 对象关系 | 本研究参考领域模型 | 非行业强制统一命名 |
| 示例 API、事件、状态机 | 教学性设计方案 | 需经接口评审、测试和演进 |
| Studio 起步架构 | 面向案例的工程建议 | 未测量真实负载和成本 |
| CP-01 - CP-18 测试 | 待执行的验证计划 | 不构成已通过测试的证据 |
B.2 本次验证情况
本篇完成概念边界、对象关系、职责划分、事件契约、状态机、故障模式与测试计划的文档级自检。未执行平台部署、负载测试、故障注入、安全渗透测试或真实第三方 API 调用。因此，性能、恢复时间、可用性及成本不作实测结论。
B.3 后续专题衔接
下一篇为 P2 · 平台如何执行和承载 Agent 任务？ - Execution Plane。它将接续本文定义的运行快照、队列、租约、状态与治理契约，重点研究执行环境、Worker/Runtime、隔离、调度、工具调用、资源管理、长任务与故障恢复。