P9 · 如何支持插件、扩展与第三方集成？ - Extensibility & Ecosystem
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何设计稳定的扩展点、插件契约与开发者工具，并安全管理插件的发布、安装、授权、隔离执行、升级、撤销及第三方生态？
专题导读
本篇属 Technical Architecture。P9 研究 Agent Platform 如何在不修改平台核心代码的前提下，允许受信任或经审核的第三方提供能力扩展，并将其转化为可安装、可配置、可授权、可运行、可升级和可撤销的平台资产。它研究的是扩展机制与生态治理，而非单纯的工具调用。P7 负责资源和连接管理，P8 负责对外 API/SDK，P9 负责扩展契约、运行隔离、分发和生态规则。
本篇以可实现的参考架构为主，明确区分成熟技术规范、工程推论和待测试设计。示例代码、数据表、指标阈值及测试计划均不代表 Studio 已实现。
研究结论
- 插件是有独立身份、版本、权限、生命周期的可部署扩展包；工具、连接器、Skill 和插件存在交集，但不能互相等同。
- 扩展点必须先于插件市场设计：定义事件、输入输出、失败语义、权限和兼容性，才能稳定接纳第三方。
- 默认采用进程外隔离与能力最小化：第三方插件不应获得平台数据库、宿主进程或所有租户密钥的直接访问权。
- 安装不等于授权，授权不等于执行许可：发布者、安装者、管理员和运行时主体具有不同职责。
- 插件版本应不可变且可验证来源；安装实例固定具体版本，升级通过显式变更、兼容性检查和回滚实现。
- 外部副作用是风险分界线：发送邮件、支付、写库等插件需要独立审批、幂等和审计。
- Studio 初期只建设内部插件体系：优先为检索、文档处理和报告导出提供少量稳定扩展点，暂不建设公开市场。
一、概念定义与系统边界
1.1 五个容易混淆的对象
| 对象 | 核心含义 | 是否必然是插件 | 管理主体 |
|---|---|---|---|
| Tool | Agent 可调用的具体操作契约 | 否 | P7 Resource/Tool Registry |
| Connector | 对某一外部系统的连接和认证适配 | 否 | P7 Connection Management |
| Skill | 对任务方法、指令和可选资源的封装 | 否 | Agent/Skill 管理模块 |
| Plugin | 通过平台扩展契约安装的独立扩展单元 | 是 | P9 Plugin Manager |
| Extension Point | 平台允许扩展介入的受控接口/事件位置 | 否 | 平台核心维护者 |
插件可能贡献一个或多个工具、连接器、界面组件或工作流节点；但一个 REST API 工具即使被 Agent 调用，也不必然具有插件的安装、版本和生命周期。
1.2 P9 与其他章节的职责分界
- P1 Control Plane：决策是否允许安装、启用和调用；P9 提供插件身份、契约与生命周期机制。
- P2 Execution Plane：提供实际执行和隔离能力；P9 规定插件如何交付、接入和声明所需权限。
- P3 Agent Registry：保存 Agent 定义与版本；P9 的 Plugin Registry 保存插件包与版本。
- P4 Development Services：提供开发调试工具；P9 定义插件开发工具包、验证和打包规范。
- P5 Deployment：管理实例与运行；P9 管理插件实例的安装和启用，调用运行服务部署。
- P6 Workflow：调度流程；P9 允许插件贡献新的受控节点类型。
- P7 Resource & Integration：连接模型/工具/外部系统；P9 负责第三方扩展如何向 P7 注册资源能力。
- P8 Platform API & SDK：公开通用平台能力；P9 的 Plugin SDK 是其中面向扩展开发者的专用契约。
- P10 Data & Assets：保存插件产物和共享资产，不替代插件的安全审查。
- P11/P12：租户隔离、权限、配额、治理策略的最终执行边界。
二、扩展能力分类与扩展点设计
2.1 扩展点分类
| 扩展点 | 插件贡献 | 典型场景 | 关键风险 |
|---|---|---|---|
| Tool Provider | 工具定义及调用实现 | 网页检索、文档解析 | 越权调用、数据外传 |
| Model Adapter | 模型提供商适配 | 自定义推理服务 | 凭证、费用、数据边界 |
| Connector Provider | 外部服务连接方式 | 邮件、知识库、CRM | OAuth 范围与令牌管理 |
| Workflow Node | 节点定义和执行处理器 | 审核、格式转换 | 状态恢复、重试语义 |
| Event Subscriber | 订阅平台事件 | 通知、审计镜像 | 重复投递、循环触发 |
| Artifact Processor | 输入输出产物转换 | Markdown→PDF | 文件解析漏洞 |
| UI Extension | 受控界面组件 | 配置面板 | XSS、宿主页面权限 |
| Policy Extension | 扩展决策辅助 | 内容规则 | 绕过平台强制策略 |
原则：第三方策略插件可以建议或增加约束，但不能取消平台内置的强制安全控制。对事件型扩展明确区分同步阻断型与异步通知型；异步插件失败不得暗中阻塞主业务。
2.2 扩展点契约的最小字段
extension_point_id、contract_version、input_schema、output_schema、invocation_mode、timeout_policy、retry_policy、side_effect_class、required_capabilities、error_codes、observability_fields。这些字段是本文提出的参考设计，并非业界统一标准。
2.3 契约演进
扩展点版本独立于平台版本和插件版本。对可选字段新增、枚举扩展、错误码新增、行为语义变化分别制定兼容性规则。破坏性变更必须引入新契约版本，保留迁移期和兼容测试。
三、插件系统逻辑架构
flowchart TB
Dev[第三方/内部开发者] --> Package[构建与签名]
Package --> Registry[Plugin Registry]
Registry --> Review[静态校验/审核/策略]
Review --> Install[安装与授权管理]
Install --> Bind[Workspace/Agent/Workflow Binding]
Bind --> Gateway[Plugin Invocation Gateway]
Gateway --> AuthZ[运行时授权/配额/审计]
AuthZ --> Runner[隔离插件运行器]
Runner --> External[外部 API / 数据]
Runner --> Assets[平台产物服务]
Gateway --> Obs[Trace / Metrics / Logs]平台分为分发面（包、版本、审核、签名）、管理面（安装、配置、授权、绑定、升级）和执行面（隔离调用、凭证代理、日志与配额）。三者可以在 MVP 中由同一个后端项目实现，但逻辑上必须分开。
3.1 核心服务
Plugin Registry、Extension Contract Catalog、Package Validator、Installation Manager、Permission Broker、Invocation Gateway、Sandbox Runner、Event Dispatcher、Marketplace Catalog（可选）、Usage Metering。
3.2 信任边界
插件包和插件提供的文本、工具响应、UI 内容均应视为不可信输入。平台自身持有租户身份和资源授权；插件只能获得经范围限定的调用令牌或代理能力，不能自行声明“我是管理员”即被信任。
四、对象模型与数据关系
erDiagram
PLUGIN ||--o{ PLUGIN_VERSION : publishes
PLUGIN_VERSION ||--o{ PLUGIN_INSTALLATION : installed_as
WORKSPACE ||--o{ PLUGIN_INSTALLATION : owns
PLUGIN_INSTALLATION ||--o{ PLUGIN_BINDING : exposes_to
PLUGIN_INSTALLATION ||--o{ PLUGIN_GRANT : authorized_by
PLUGIN_BINDING ||--o{ PLUGIN_INVOCATION : invokes
PLUGIN_INVOCATION ||--o{ PLUGIN_ATTEMPT : retries
PLUGIN_VERSION ||--o{ PLUGIN_EXTENSION : contributes
EXTENSION_CONTRACT ||--o{ PLUGIN_EXTENSION : validates| 对象 | 稳定身份与主要字段 | 不可变性要求 |
|---|---|---|
| Plugin | plugin_id、publisher、slug、owner | 身份稳定 |
| PluginVersion | version_id、digest、manifest、artifact_ref | 发布后不可变 |
| PluginExtension | extension_point_id、contract_version、entrypoint | 随版本冻结 |
| PluginInstallation | installation_id、workspace、version、state | 状态可变，版本更换留历史 |
| PluginGrant | principal、scope、resource、expiry | 可撤销、留审计 |
| PluginBinding | agent/workflow、installation、config | 变更有版本或修订记录 |
| PluginInvocation | request/run/trace、principal、result | 追加记录 |
插件包版本和工作空间安装版本是不同对象；一个插件版本可安装到多个工作空间，但不能跨工作空间复用其密钥与授权。
五、插件 Manifest 与发布包规范
以下 YAML 是建议的 Studio 内部格式，不是 MCP、OCI 或其他标准直接定义的通用插件清单。
schema_version: "studio.plugin/v1"
plugin_id: "com.example.document-export"
version: "1.2.0"
publisher: "example"
display_name: "Document Export"
compatibility:
platform_api: ">=1.3 <2.0"
extension_contracts:
artifact_processor: "1.x"
package:
kind: "oci-image"
digest: "sha256:<actual-content-digest>"
entrypoint: "plugin-server"
extensions:
- id: "export_pdf"
type: "artifact_processor"
contract_version: "1.0"
input_schema: "schemas/export-input.json"
output_schema: "schemas/export-output.json"
permissions:
requested:
- "artifact:read:bound"
- "artifact:write:workspace"
network:
allowed_hosts: []
limits:
timeout_seconds: 60
memory_mb: 256
configuration:
schema: "schemas/config.json"
secrets:
references: []
provenance:
attestation_ref: "attestations/build.intoto.jsonl"清单还应支持许可证、隐私声明、支持联系方式、可用区域、数据处理说明和升级迁移要求。包摘要应由构建系统实际计算，不可使用示例占位值投入生产。
5.1 包格式选择
进程外服务插件可采用容器镜像或受限远程服务；轻量脚本插件可采用受控 WASM 或隔离子进程。OCI 镜像是分发容器工件的一种成熟机制，但OCI 本身不定义 Agent 插件权限语义。
5.2 版本规则
SemVer 可以表达发布者对兼容性的承诺，但不能替代实际契约测试。安装记录必须固定不可变 digest；latest 只能作为安装时解析的渠道指针，不可作为审计中的唯一版本标识。
六、插件生命周期与状态机
stateDiagram-v2
[*] --> Draft
Draft --> Validating: submit
Validating --> Rejected: failed
Rejected --> Draft: revise
Validating --> Reviewed: pass
Reviewed --> Published: approve
Published --> Deprecated: deprecate
Published --> Revoked: security revoke
Deprecated --> Revoked: critical issue
Revoked --> [*]包生命周期：开发、构建、校验、审核、发布、弃用、撤销。安装生命周期：请求安装、等待授权、启用、暂停、升级、卸载。调用生命周期：准入、分配、执行、完成/失败、审计。三个状态机应分别建模。
升级采用“新版本预安装→契约检查→配置迁移（必要时）→预生产验证→绑定切换→观察→清理旧版本”。回滚恢复旧版本绑定，不应覆盖或删除旧版运行记录。若插件执行了不可逆外部操作，回滚代码不等于撤销业务副作用。
七、权限模型、身份与凭证
7.1 权限四阶段
- 发布审核：平台确认包和发布者是否符合入库规则。
- 安装授权：工作空间管理员确认允许安装及请求的权限范围。
- 绑定授权：Agent/Workflow 负责人确认具体业务对象能使用哪些插件能力。
- 调用时授权：网关依据实际调用者、租户、资源、环境和策略再次决策。
安装记录不应被视为永久授权。对外部账户，OAuth token 保存在密钥服务或凭证代理中，插件获得短期、最小权限的访问方式；不得把长期 refresh token 写入 Manifest、日志或 Agent Prompt。
7.2 典型授权元组
(tenant_id, workspace_id, principal_id, plugin_installation_id, extension_id, resource_scope, action, environment, expires_at)。任何跨租户资源引用都必须拒绝，除非有明确的跨租户共享模型和独立授权。
7.3 高风险操作
邮件发送、数据库写入、文件删除、资金交易和外部发布应支持二次确认、限额、审批或细粒度白名单。用户自然语言要求不能覆盖平台权限策略。
八、插件执行与隔离策略
8.1 执行模式比较
| 模式 | 优点 | 局限 | 建议使用条件 |
|---|---|---|---|
| 宿主进程内动态模块 | 延迟低、集成简单 | 崩溃域共享、权限难隔离 | 仅内部可信代码 |
| 独立子进程 | 可隔离故障与依赖 | OS 级边界需加固 | 内部或受审查插件 |
| 容器化 Worker | 资源限制、部署成熟 | 冷启动与运维成本 | 默认服务器端插件 |
| WASM 沙箱 | 能力受限、可移植 | 运行时/系统接口限制 | 适合受限计算插件 |
| 远程 HTTPS 插件 | 第三方独立运维 | 数据出境、供应商依赖 | 严格审批的外部服务 |
“容器化”本身不构成绝对安全沙箱。需叠加非特权运行、文件系统限制、网络出口策略、资源限额、短期凭证和运行时审计。
8.2 调用流程
sequenceDiagram
participant A as Agent/Workflow
participant G as Plugin Gateway
participant Z as Policy Engine
participant C as Credential Broker
participant R as Sandbox Runner
participant E as External Service
A->>G: invoke(extension, input, run_context)
G->>Z: authorize(principal, resource, action)
Z-->>G: allow + constraints
G->>C: request scoped capability
C-->>G: ephemeral reference/token
G->>R: execute(pinned_digest, input, capability)
R->>E: approved outbound request
E-->>R: result
R-->>G: structured output + usage
G-->>A: result + trace_id8.3 失败语义
将错误至少分为 VALIDATION_ERROR、PERMISSION_DENIED、PLUGIN_UNAVAILABLE、TIMEOUT、RATE_LIMITED、UPSTREAM_ERROR、CONTRACT_VIOLATION、SECURITY_REVOKED。重试必须依据操作是否幂等；“超时”不能被解释为“外部操作未发生”。
九、事件订阅与工作流扩展
事件扩展必须定义事件 ID、schema version、来源、租户、发生时间、投递时间、重放策略与去重键。默认按至少一次投递设计消费端去重；除非底层具备明确证明，不承诺端到端 exactly-once。
工作流节点插件需声明：输入/输出 schema、执行超时、重试安全性、是否可暂停、是否可恢复、是否产生外部副作用，以及是否支持取消。Workflow Version 应固定插件安装或版本引用；否则同一工作流在不同时间可能解析到不同实现。
UI 插件应运行在明确的受限边界（例如 sandboxed iframe 与受控 postMessage 协议），不得通过浏览器共享存储直接读取平台身份凭证。
十、插件开发者工具与发布流水线
建议提供 Plugin SDK、CLI、示例项目、Manifest Schema、Mock Host、契约测试套件、测试工作空间和本地调试器。
plugin init
-> 编写 Manifest / 扩展实现
-> plugin validate
-> plugin test --contract
-> plugin build
-> 生成 SBOM / provenance / digest
-> plugin publish --channel=staging
-> 平台审核与审批
-> 发布到内部目录上述命令为建议命令设计，不是现有 CLI 的真实命令。
10.1 验证分层
静态 schema 校验、入口点存在性、扩展点版本兼容、依赖与许可证扫描、恶意行为与密钥泄露扫描、签名和来源验证、隔离环境动态测试、人工风险审核。自动扫描不能证明插件完全安全。
10.2 开发者体验
应提供稳定的错误码、沙箱日志、模拟授权上下文、事件回放、版本兼容矩阵、清晰的弃用周期和可复现的示例。SDK 与宿主版本兼容关系应机器可读并纳入 CI。
十一、Plugin Registry 与生态分发
Plugin Registry 负责版本工件与可信元数据；Marketplace Catalog 负责搜索、分类、评价、定价和展示。注册仓库与插件市场是两个独立概念，内部平台可只建设 Registry。
发布者身份验证、组织归属、软件供应链来源、包签名、漏洞披露、下架、撤销和申诉流程应构成生态治理闭环。推荐把以下信号用于风险评分：发布者可信级别、权限广度、网络出口、数据敏感性、外部副作用、依赖风险和历史安全事件。风险评分只能辅助审核，不能代替确定性授权策略。
若未来支持付费插件，还需研究计费归因、结算、税务、退款、服务等级和用户数据处理协议；这些属于商业生态层，不是 MVP 的前置条件。
十二、数据架构与参考 SQL
以下为简化 PostgreSQL 参考模型，生产设计还需补充迁移、索引、审计、RLS 策略及并发测试。
CREATE TABLE plugins (
plugin_id UUID PRIMARY KEY,
publisher_id UUID NOT NULL,
slug TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (publisher_id, slug)
);
CREATE TABLE plugin_versions (
version_id UUID PRIMARY KEY,
plugin_id UUID NOT NULL REFERENCES plugins(plugin_id),
version TEXT NOT NULL,
digest TEXT NOT NULL,
manifest JSONB NOT NULL,
state TEXT NOT NULL CHECK (state IN ('reviewed','published','deprecated','revoked')),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (plugin_id, version),
UNIQUE (plugin_id, digest)
);
CREATE TABLE plugin_installations (
installation_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
workspace_id UUID NOT NULL,
version_id UUID NOT NULL REFERENCES plugin_versions(version_id),
state TEXT NOT NULL CHECK (state IN ('pending','enabled','disabled','revoked','uninstalled')),
revision BIGINT NOT NULL DEFAULT 1,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE plugin_grants (
grant_id UUID PRIMARY KEY,
installation_id UUID NOT NULL REFERENCES plugin_installations(installation_id),
principal_id UUID NOT NULL,
scope JSONB NOT NULL,
expires_at TIMESTAMPTZ,
revoked_at TIMESTAMPTZ
);
CREATE TABLE plugin_invocations (
invocation_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
installation_id UUID NOT NULL REFERENCES plugin_installations(installation_id),
run_id UUID,
trace_id TEXT,
status TEXT NOT NULL,
started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
finished_at TIMESTAMPTZ
);
CREATE INDEX idx_plugin_installations_workspace
ON plugin_installations (tenant_id, workspace_id, state);
CREATE INDEX idx_plugin_invocations_run
ON plugin_invocations (tenant_id, run_id, started_at DESC);实现注意：数据库唯一约束不能单独确保已发布版本的 manifest 和 digest 不被 UPDATE；必须在应用授权、数据库角色、触发器或追加式存储中实现不可变性。安装升级应使用乐观锁（revision）防止覆盖并发修改。审计日志应独立追加存储。
十三、参考 API 与事件契约
| 方法 | 路径 | 语义 |
|---|---|---|
GET | /v1/extension-points | 查询受支持扩展点及契约 |
POST | /v1/plugins | 注册插件身份 |
POST | /v1/plugins/{id}/versions | 提交不可变版本候选 |
POST | /v1/plugin-versions/{id}:validate | 发起验证 |
POST | /v1/plugin-versions/{id}:publish | 经审批发布 |
POST | /v1/workspaces/{id}/plugin-installations | 安装指定版本 |
POST | /v1/plugin-installations/{id}/grants | 授予范围限定权限 |
POST | /v1/plugin-installations/{id}:disable | 停用安装 |
POST | /v1/plugin-invocations | 经网关调用扩展 |
GET | /v1/plugin-invocations/{id} | 查询调用结果与审计 |
{
"installation_id": "inst_123",
"extension_id": "export_pdf",
"run_id": "run_456",
"idempotency_key": "export-report-456-v1",
"input": {"artifact_id": "art_789"}
}Idempotency-Key 应由平台持久化校验请求指纹；相同键不同载荷返回冲突。权限错误应避免泄漏跨租户资源存在性。API 仅为参考设计，具体路径和字段需在 P8 的统一 API 契约下协调。
十四、Studio 贯穿案例：研究报告插件体系
14.1 业务场景
Studio 研究工作流：选题 → 审核 → 深度调研 → 分析 → 写作 → 人工确认 → 交付。适合扩展的环节包括搜索服务、来源解析、文献去重、引文格式化、Markdown/PDF 导出和消息通知。
14.2 三个内部插件
| 插件 | 扩展点 | 输入 | 输出 | 权限边界 |
|---|---|---|---|---|
| Search Provider | Tool Provider | 检索词、时间范围 | 来源链接、摘要、来源元数据 | 网络白名单、配额 |
| Citation Formatter | Artifact Processor | 引文结构化数据 | 参考文献段落 | 仅读取绑定资料 |
| Report Exporter | Artifact Processor | 已审核 Markdown Artifact | PDF/HTML Artifact | 指定产物读写 |
邮件通知插件暂缓启用；如果引入，默认需要用户确认发送对象与内容，且记录外部发送 ID。
14.3 一次运行的版本固定
Workflow Version 绑定 Search Provider v1.1.0 和 Report Exporter v1.2.0 的安装 ID 与版本摘要。Run 启动时 Control Plane 解析并冻结有效配置；Execution Plane 调用时再次核对租户、权限、版本和撤销状态。若中途发现安全撤销，平台可以阻止后续调用并将 Run 标记为需要人工处置；不能为了“可复现”而继续执行已确认恶意的插件。
14.4 推荐 MVP 顺序
第一阶段：内部扩展点契约 + 受控工具适配 + 调用日志。第二阶段：Manifest、版本冻结、工作空间安装、最小权限。第三阶段：隔离 Worker、发布验证、升级回滚。第四阶段：第三方开发者 SDK、审核与内部目录。公开 Marketplace、计费和多组织分发应在真实需求出现后再建设。
十五、威胁模型、故障与治理
| 风险/故障 | 典型表现 | 预防/处置 |
|---|---|---|
| 恶意插件供应链 | 发布包替换、依赖投毒 | digest 固定、签名、来源证明、审核 |
| 插件越权 | 读取其他工作空间资料 | 调用时对象级授权、隔离凭证 |
| Prompt Injection | 外部内容诱导 Agent 发送秘密 | 将插件输出视为不可信数据、独立权限检查 |
| 凭证泄漏 | token 出现在日志 | 凭证代理、脱敏、轮换、短期令牌 |
| 网络外传 | 未授权域名出站 | 网络出口白名单、审计 |
| 资源耗尽 | 无限循环、内存膨胀 | CPU/内存/时间配额、熔断 |
| 版本漂移 | 插件升级改变历史 Run 行为 | 版本锁、运行快照、显式升级 |
| 重复副作用 | 超时后重试再次发邮件 | 幂等键、外部操作记录、人工补偿 |
| 事件风暴 | 插件订阅自身事件反复触发 | 事件链深度限制、去重、速率限制 |
| 签名密钥失窃 | 恶意包伪装可信发布者 | 密钥轮换、撤销、来源复核 |
| 不兼容升级 | Workflow 节点 schema 改变 | 契约测试、灰度、快速回滚 |
| 远程插件中断 | 服务不可达 | 超时、熔断、降级与业务告警 |
15.1 可观测性与成本
记录 tenant_id、workspace_id、plugin_id、version_id、installation_id、extension_id、invocation_id、run_id、trace_id、延迟、错误、重试、资源消耗和外部调用成本。日志中不记录明文密钥和未经授权的敏感正文。
15.2 运营指标（待定阈值）
插件调用成功率、P95 延迟、超时率、隔离违规次数、升级回滚率、发布审核耗时、依赖漏洞暴露时间、每租户成本、插件弃用覆盖率。目标阈值应在基线压测和风险分级后确定，不宜凭空设定统一 SLA。
十六、技术选型与取舍
MVP 方案 A：受控内部扩展。平台内置少量扩展点，插件作为独立 Worker/适配器，统一经 P7 Gateway 调用。优点是实现成本低、可验证边界清晰；缺点是生态开放程度有限。
方案 B：可安装插件平台。增加 Manifest、Plugin Registry、安装/授权、包验证和升级。适合多个团队频繁贡献新能力时。
方案 C：公开插件生态。增加开发者门户、签名与审核、市场、版本政策、撤销通知、计费与合规流程。成本最高，且不应以“插件市场页面”替代真实的隔离和权限能力。
对于 Studio 当前阶段，优先 A，再以可量化需求决定是否进入 B；C 属于后期产品战略选择。
十七、工程验证与验收矩阵
以下 28 项为测试设计，未实际执行。测试前应明确平台版本、插件样本、隔离模式、数据规模、故障注入方法及判定证据。
| ID | 测试场景 | 预期结果 | 当前状态 |
|---|---|---|---|
| T01 | Manifest 缺少必填字段 | 拒绝发布并返回字段路径 | 待执行 |
| T02 | Manifest schema_version 不支持 | 返回明确兼容性错误 | 待执行 |
| T03 | 扩展点契约不兼容 | 阻止启用并保留旧版 | 待执行 |
| T04 | 包摘要不匹配 | 拒绝安装与执行 | 待执行 |
| T05 | 发布者签名无效 | 阻止发布并记录安全事件 | 待执行 |
| T06 | 插件请求未声明权限 | 拒绝调用 | 待执行 |
| T07 | 安装授权已撤销 | 立即阻止新调用 | 待执行 |
| T08 | 跨租户 installation_id | 不可访问且不泄露资源信息 | 待执行 |
| T09 | 插件超时 | 终止/隔离并记录状态 | 待执行 |
| T10 | 插件输出不符合 schema | 返回 CONTRACT_VIOLATION | 待执行 |
| T11 | 并发升级同一安装 | 乐观锁冲突而非静默覆盖 | 待执行 |
| T12 | 升级失败 | 旧版继续服务或可回滚 | 待执行 |
| T13 | Run 中途插件版本切换 | 已启动 Run 仍固定原版本 | 待执行 |
| T14 | 安全紧急撤销 | 阻止后续调用并触发处置 | 待执行 |
| T15 | 重复事件投递 | 消费者去重 | 待执行 |
| T16 | 事件循环触发 | 深度限制/熔断生效 | 待执行 |
| T17 | 重复外部写操作 | 幂等策略避免重复副作用 | 待执行 |
| T18 | 外部服务断连 | 超时/熔断/重试按策略 | 待执行 |
| T19 | 凭证出现在错误日志 | 脱敏测试阻止泄漏 | 待执行 |
| T20 | 非法网络出口 | 被网络策略拒绝 | 待执行 |
| T21 | 插件资源耗尽 | 隔离与资源限制生效 | 待执行 |
| T22 | UI 插件脚本越权 | 浏览器隔离与消息校验 | 待执行 |
| T23 | 权限过期 | 过期后拒绝访问 | 待执行 |
| T24 | 插件禁用后重放旧请求 | 重新授权并拒绝 | 待执行 |
| T25 | 插件依赖存在已知高危问题 | 按风险策略阻止或人工批准 | 待执行 |
| T26 | 大量插件并发调用 | 验证队列公平性与配额 | 待执行 |
| T27 | 卸载插件仍有历史 Run | 保留历史审计与版本引用 | 待执行 |
| T28 | 插件报告成本异常 | 计量告警与限额生效 | 待执行 |
建议补充端到端链路测试：插件发布→安装→授权→绑定→Workflow Run→调用审计→升级→撤销。对关键安全场景采用自动化回归测试，并保留证据记录。
十八、实施路线图与章节衔接
M0 契约阶段：定义 Tool Provider、Artifact Processor 两个扩展点；统一 schema、错误码、追踪字段和权限模型。
M1 内部插件阶段：实现受控注册、工作空间绑定、隔离调用、日志和基本限额。
M2 版本治理阶段：实现不可变包、digest 固定、兼容校验、灰度升级、回滚和撤销。
M3 开发生态阶段：提供 Plugin SDK、CLI、测试工作空间、发布流水线和内部目录。
M4 外部生态阶段（可选）：发布者验证、公开审核、市场、支持协议、计费和合规。
与下一篇 P10 的关系：P9 负责扩展如何产生或消费资产；P10 研究平台如何统一存储、组织、授权、索引、版本化和交付数据与产物。
附录 A：参考文献与原始资料
- OpenAPI Specification - spec.openapis.org/oas/latest.html。用途：接口描述与兼容契约
- JSON Schema - json-schema.org/specification。用途：Manifest 与输入输出校验。
- OCI Image Specification - github.com/opencontainers/image-spec。用途：容器工件与摘要分发
- OCI Distribution Specification - github.com/opencontainers/distribution-spec。用途：工件分发接口
- Sigstore Documentation - docs.sigstore.dev/。用途：软件工件签名与验证
- SLSA Specification - slsa.dev/spec/。用途：构建来源与供应链安全
- NIST SP 800-218 SSDF - csrc.nist.gov/pubs/sp/800/218/final。用途：安全软件开发框架
- OWASP Top 10 for LLM Applications - genai.owasp.org/llm-top-10/。用途：LLM 应用风险分类。
- OAuth 2.0 Security Best Current Practice RFC 9700 - www.rfc-editor.org/rfc/rfc9700。用途：OAuth 安全实践。
- OAuth 2.0 Authorization Framework RFC 6749 - www.rfc-editor.org/rfc/rfc6749。用途：授权协议基础
- CloudEvents Specification - github.com/cloudevents/spec。用途：事件元数据契约参考
- Kubernetes Extensibility - kubernetes.io/docs/concepts/extend-kubernetes/。用途：平台扩展机制实例
- Kubernetes Admission Controllers - kubernetes.io/docs/reference/access-authn-authz/admission-controllers/。用途：受控扩展与准入实例
- Model Context Protocol Specification - modelcontextprotocol.io/specification。用途：工具与上下文互操作协议；不等同通用插件平台
- PostgreSQL Documentation - www.postgresql.org/docs/current/。用途：数据模型与事务能力
- OpenTelemetry Specification - opentelemetry.io/docs/specs/otel/。用途：插件调用可观测性
- WebAssembly Security - webassembly.org/docs/security/。用途：WASM 沙箱边界基础。
- CNCF TAG Security Software Supply Chain - tag-security.cncf.io/。用途：云原生供应链安全参考
文献使用说明：上述为规范和官方文档入口，供实施阶段逐项核对版本与具体条款。本文不将 OCI、MCP、CloudEvents 等标准误称为“Agent Platform 插件标准”；跨规范整合部分属于本研究的架构推论。
附录 B：研究证据、验证声明与适用边界
B.1 证据分级
- 规范支持：JSON Schema 可描述结构化数据验证；OpenAPI 可描述 HTTP API；OCI 可描述工件；OAuth 提供授权框架；OpenTelemetry 提供可观测性语义。
- 工程推论：插件分发/管理/执行三面分离、插件与安装分离、运行时二次授权、版本固定与撤销优先等，为跨规范组合的参考架构。
- 待验证设计：Manifest 字段、SQL、API 路径、M0 - M4 路线、具体沙箱和性能目标、全部测试矩阵。
B.2 尚未完成的验证
未执行代码运行、依赖漏洞扫描、签名验真、租户穿透测试、网络隔离测试、压力测试或外部系统联调。所有参考代码均需根据实际部署环境复核，不能直接视为生产安全方案。
B.3 适用范围
适用于支持多 Agent、Workflow、工具调用和工作空间管理的 Agent Platform；不要求所有平台均建立公开 Marketplace。对于仅有少量可信内部工具的产品，完整插件市场和第三方分发机制可能是过度设计。