F4 · 用户如何发布、共享和复用 Agent？ - Agent Publishing & Sharing
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 交互与工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 应如何将开发完成的 Agent 安全、可追溯地发布为可用版本，向不同范围的用户共享，并支持发现、安装、复用、升级、撤销与治理？
专题导读
本篇属 Product Architecture。F1 解决创建 Agent，F2 解决配置，F3 解决开发、调试和测试；F4 解决如何让经过验证的 Agent 从个人草稿转变为被授权用户实际使用、复用和维护的产品资产。本篇从用户任务、产品对象、界面流程、发布门禁、共享权限、发现与复用、版本演进及运营治理展开。它不是 P3 · Agent Registry 的底层实现说明，也不替代 P5 · Deployment & Runtime Management 的部署机制。
本文的状态机、界面、API、数据模型、Studio 案例与验收指标属于待验证参考设计。所引用的标准和产品文档支持其中部分技术原则，但不代表存在统一的“Agent 发布标准”。
研究结论
- 发布、部署、共享、安装、运行是五种独立动作：发布冻结定义版本；部署绑定运行环境；共享授予发现或使用权；安装建立工作空间内的受管引用或副本；运行创建具体任务。
- 最小发布闭环为：选择已保存草稿 → 校验与测试证据 → 检查依赖和权限 → 预览发布影响 → 确认发布 → 生成不可变版本 → 设置可见性与使用策略 → 验证可发现和可调用。
- 发布版本不可变；“生产版”“最新版”是可变的发布渠道指针，不能充当历史执行依据。
- 可见、可使用、可复制、可编辑、可再发布必须分别授权；查看 Agent 描述不应自动允许读取 Prompt、密钥或内部知识资料。
- Agent 的共享涉及定义、工具授权、知识数据、模型成本与外部副作用；复用前必须重新检查目标工作空间的连接和治理策略。
- 平台应提供“引用/安装”与“复制/派生”两种不同复用语义，并展示上游版本、更新策略和后续维护责任。
- 发布门禁以结构化证据和风险为基础；F3 测试通过不等于 F4 审批通过，发布成功不等于 P5 部署成功。
- 下架、撤销访问、废弃版本、停止新运行、终止在途运行与删除资产具有不同的影响范围，应分别设计。
- Marketplace 是成熟期能力；早期 Studio 应优先做好工作空间内发布、项目共享、Agent 模板复用和版本回滚。
01 · 定义、范围与相邻功能
1.1 产品定义
Agent Publishing & Sharing 是平台面向构建者、使用者和管理员提供的一组产品能力：把经过确认的 Agent 配置发布为可追溯版本；为版本赋予发布渠道和使用范围；帮助目标用户发现、理解、授权、安装和复用 Agent；并持续管理更新、撤销、审计与生命周期。
1.2 五个动作的边界
| 动作 | 用户的问题 | 主要结果 | 不能推导出的结论 |
|---|---|---|---|
| Publish 发布 | 这个 Agent 的哪一版可以被正式引用？ | Agent Version、发布记录 | 已经有运行实例 |
| Deploy 部署 | 哪个环境运行这一版？ | Deployment Revision | 所有人都能使用 |
| Share 共享 | 谁能发现、查看、调用或复制？ | Grant、Visibility Policy | 对方具备资源凭证 |
| Install 安装 | 如何纳入我的工作空间？ | Installation、Binding、依赖检查 | 已获得上游源码编辑权 |
| Run 运行 | 用什么版本执行一次任务？ | Run 与执行快照 | 结果符合业务质量要求 |
F4 主要负责发布与共享的用户流程；P3 管理不可变定义版本，P7 负责资源连接，P11 负责租户隔离，P12 负责治理，F6 负责用户运行，F9 负责版本维护。
1.3 发布对象与共享对象
默认发布对象是Agent Definition 的某个不可变版本。共享对象可以是整个 Agent 的入口、某个版本、某个发布渠道、模板或可调用服务；不同共享对象必须明确权限和升级语义。发布一个 Agent 不代表公开其全部内部定义，也不意味着其外部工具自动可用。
02 · 用户角色、需求与关键场景
| 角色 | 核心目标 | 典型操作 | 主要风险 |
|---|---|---|---|
| Agent 构建者 | 将已验证成果交给他人 | 发布、写说明、设置权限 | 错发草稿、泄漏内部信息 |
| 项目负责人 | 在项目内复用可靠能力 | 审批、指定渠道、分配使用者 | 版本漂移、审核缺失 |
| 业务使用者 | 找到合适的 Agent 并执行 | 搜索、查看能力、申请使用 | 误解能力、误触发副作用 |
| 开发者 | 集成与二次开发 | 安装、引用版本、派生模板 | 依赖不兼容、上游变化 |
| 工作空间管理员 | 控制团队共享与资源 | 授权、撤销、配额 | 越权和成本失控 |
| 平台运营/安全人员 | 治理公开目录与生态 | 审核、下架、处理举报 | 恶意 Agent、滥用与供应链风险 |
2.1 核心用户故事
- 作为构建者，我希望将通过测试的“选题 Agent”发布为 v1.0，使研究团队稳定调用，同时继续编辑 v1.1 草稿。
- 作为研究负责人，我希望只允许指定项目调用“审核 Agent”，而不允许普通成员查看其内部审核提示词。
- 作为新项目成员，我希望一键安装“研究报告 Agent 模板”，并在安装时知道需要连接哪些模型和检索服务。
- 作为管理员，我希望撤销某个有风险版本的新运行权限，并能明确判断已启动任务如何处理。
- 作为开发者，我希望在工作流中锁定
agent_version_id，而不是依赖会变化的latest。
03 · 产品能力地图与信息架构
3.1 功能分组
| 功能组 | 子能力 | 初期优先级 |
|---|---|---|
| 发布中心 | 发布向导、版本说明、预检、确认、结果页 | P0 |
| 版本与渠道 | 版本列表、比较、稳定渠道、回滚 | P0/P1 |
| 共享权限 | 私有、项目、工作空间、指定成员、公开 | P0/P1 |
| 发现与详情 | Agent 目录、搜索、能力说明、依赖说明 | P1 |
| 复用与安装 | 引用、安装、复制、模板创建 | P1 |
| 维护通知 | 更新提示、废弃、迁移说明 | P1/P2 |
| Marketplace | 公开审核、评价、开发者身份、举报 | P3 |
| 运营治理 | 审核队列、滥用处置、审计、撤销 | 按共享范围逐步建设 |
3.2 页面组织
flowchart LR
A[Agent 编辑工作台] --> B[发布向导]
B --> C[发布结果与版本详情]
C --> D[共享设置]
C --> E[版本历史与渠道]
D --> F[团队 Agent 目录]
F --> G[Agent 详情]
G --> H[安装 / 引用 / 复制]
H --> I[工作空间 / Workflow]
J[管理员治理中心] --> D
J --> F建议主导航以用户对象而非底层技术命名：我的 Agent、团队 Agent、模板、版本与发布、共享设置。Marketplace 可在后续单独成区。技术对象如 Registry Entry、Release Channel 只在高级设置或开发者视图中露出。
04 · 核心产品对象与关系
4.1 对象表
| 对象 | 身份与作用 | 可变性 | 所有者/边界 |
|---|---|---|---|
| Agent Definition | Agent 的稳定逻辑身份 | 元数据可变 | 工作空间/租户 |
| Draft Revision | 可编辑草稿的修订快照 | 修订本身不可变 | 构建者/项目 |
| Agent Version | 已发布的不可变定义 | 不可变 | Agent 所有者 |
| Release Channel | stable/beta 等渠道指针 | 可变，需审计 | Agent 所有者 |
| Publication | 一次发布操作及证据 | 审计记录不可随意修改 | 发布流程 |
| Share Grant | 对主体授予具体操作权限 | 可撤销 | 资源所有者 |
| Catalog Listing | 面向目标范围的展示信息 | 可编辑且可审核 | 发布者/平台 |
| Installation | 目标工作空间对 Agent 的安装或引用 | 配置可变 | 安装方 |
| Dependency Binding | 安装后连接本地模型、工具、知识等 | 可变且受授权约束 | 安装方 |
| Derived Agent | 从模板或版本派生的独立 Agent | 自有版本生命周期 | 派生方 |
| Review Decision | 发布或上架审批结果 | 追加式记录 | 审批方 |
4.2 关系图
erDiagram
AGENT_DEFINITION ||--o{ DRAFT_REVISION : edits
AGENT_DEFINITION ||--o{ AGENT_VERSION : publishes
AGENT_VERSION ||--o{ PUBLICATION : created_by
AGENT_DEFINITION ||--o{ RELEASE_CHANNEL : exposes
RELEASE_CHANNEL }o--|| AGENT_VERSION : points_to
AGENT_DEFINITION ||--o{ SHARE_GRANT : authorizes
AGENT_DEFINITION ||--o{ CATALOG_LISTING : describes
AGENT_VERSION ||--o{ INSTALLATION : installed_from
INSTALLATION ||--o{ DEPENDENCY_BINDING : binds
AGENT_VERSION ||--o{ REVIEW_DECISION : reviewed_for设计判断： Catalog Listing 不等于 Registry Version；公开展示文案可以更新，但不得悄悄改变被引用的执行版本。安装关系应记录来源 Agent、版本、授权范围和升级策略，避免复制后丢失来源。
05 · 发布流程与交互设计
5.1 发布向导的六步
| 步骤 | 用户操作 | 系统反馈 | 阻断条件 |
|---|---|---|---|
| 1 选择草稿 | 选择 Draft Revision | 展示变更摘要、与上版差异 | 草稿已被替换、无权限 |
| 2 填写版本 | 版本号、变更说明、兼容性声明 | 版本号冲突提示 | 重复版本、非法格式 |
| 3 预检 | 查看配置、依赖、测试、安全检查 | 分级展示通过/警告/失败 | 关键校验失败 |
| 4 设置分发 | 私有/团队/指定项目、发布渠道 | 展示可见范围与使用权限 | 越权公开、资源不允许共享 |
| 5 确认发布 | 确认不可变与影响范围 | 显示提交进度、操作 ID | 审批缺失、修订变化 |
| 6 发布结果 | 获取版本 ID、访问入口 | 共享/部署/安装下一步 | 事务失败需明确可恢复状态 |
重要交互原则： 发布前再次确认草稿修订 ID，防止用户预检后继续修改草稿而将未经检查的内容发布。提交按钮需具备幂等保护，避免重复点击生成两个版本。
5.2 发布状态机
stateDiagram-v2
[*] --> Preparing
Preparing --> Validating: 提交发布
Validating --> Rejected: 校验失败
Validating --> PendingApproval: 需要审批
Validating --> Publishing: 允许直接发布
PendingApproval --> Rejected: 拒绝/超时
PendingApproval --> Publishing: 审批通过且证据有效
Publishing --> Published: 不可变版本写入成功
Publishing --> Failed: 持久化失败
Failed --> Preparing: 修复后重试
Rejected --> Preparing: 修改后重试
Published --> [*]这里描述的是发布操作状态，不等同于 Agent Version 的可用状态。已发布版本可能随后被标记为 Deprecated、Revoked 或 Archived；历史记录仍需保留。
5.3 预检清单
| 预检项 | 检查内容 | 风险分级示例 |
|---|---|---|
| 定义完整性 | Manifest Schema、必填字段、引用存在性 | 阻断 |
| 依赖可解析 | 工具、Skill、模型、知识资源是否可解析 | 阻断/警告 |
| 资源授权 | 发布者是否有权引用及分发资源 | 阻断 |
| 凭证泄漏 | Prompt、配置与文件中是否包含明文密钥 | 阻断 |
| 测试证据 | 测试集、评估器、版本与时间 | 依策略阻断 |
| 外部副作用 | 邮件、支付、写库等能力的授权与审批 | 高风险阻断 |
| 兼容性 | 输入输出 Schema、工具参数、版本差异 | 警告/阻断 |
| 分享范围 | 是否超出原始数据、许可或租户边界 | 阻断 |
| 成本提示 | 模型和工具成本估算 | 提示/策略阻断 |
F3 提供测试证据；F4 消费这些证据并向用户解释发布决策；P12 决定强制性治理规则。不得用“测试评分很高”覆盖关键安全失败。
06 · 版本、发布渠道与回滚
6.1 版本语义
版本应以稳定 agent_version_id 为权威身份。可附加人类可读 1.2.0 标签，但 SemVer 仅在平台明确约定兼容规则时才有意义；Agent 行为概率性变化不能仅由版本号保证兼容。内容摘要可验证工件完整性，但不能证明模型服务、实时网页或外部 API 的行为完全可复现。
6.2 渠道管理
| 渠道 | 典型使用 | 切换权限 | 执行约束 |
|---|---|---|---|
| development | 开发验证 | 构建者 | 仅开发环境 |
| beta | 小范围试用 | 项目负责人 | 限定用户/预算 |
| stable | 正式使用 | 发布负责人 | 必要审批与回归证据 |
| archived | 归档展示 | 管理员 | 默认禁止新运行 |
渠道是指针，切换需要原子更新、权限检查和审计。Run 创建时必须把渠道解析成具体版本并固化。回滚是把渠道指针重新指向已知版本，不是修改历史版本，也不能自动撤销已发生的外部操作。
6.3 版本比较界面
差异比较应分为：基本信息、Prompt、模型配置、工具、知识、输入输出 Schema、权限、依赖锁、测试结果、成本与风险。对密钥只展示“凭证引用已变更”，不展示密钥值。对大型 Prompt 提供结构化 diff 与风险提示，避免用户只看到一串不可读 JSON。
07 · 共享范围与授权语义
7.1 可见范围
| 范围 | 可发现者 | 默认策略 | 适用场景 |
|---|---|---|---|
| Private | 所有者和被授权管理员 | 默认 | 个人草稿/敏感 Agent |
| Project | 指定项目成员 | 最小权限 | 研究团队 |
| Workspace | 工作空间成员 | 可配置 | 内部复用 |
| Organization | 组织内指定成员/团队 | 需组织策略 | 多工作空间共享 |
| Link-limited | 持有链接且满足身份授权者 | 不建议仅靠链接授予敏感权限 | 定向试用 |
| Public | 符合公开目录政策的用户 | 审核后开放 | 模板/Marketplace |
公开可见不意味着可查看源 Prompt、知识文档或私有配置。不同租户的资源绑定不可自动继承。
7.2 权限矩阵
| 权限 | 描述 | 应与哪些权限区分 |
|---|---|---|
| discover | 搜索结果中可见 | 查看详情 |
| view_metadata | 查看描述、版本、要求 | 查看内部配置 |
| invoke | 发起 Agent Run | 查看 Prompt/复制 |
| install | 安装到工作空间 | 访问外部连接 |
| inspect_definition | 查看允许公开的定义字段 | 读取密钥 |
| fork | 派生独立 Agent | 修改原 Agent |
| manage_grants | 管理共享授权 | 发布新版本 |
| publish | 发布新版本 | 设置公开可见 |
| promote | 调整 stable 等渠道 | 直接修改历史版本 |
| revoke | 撤销授权/版本使用 | 物理删除历史 |
授权检查应以主体 + 操作 + 资源 + 租户上下文 + 条件为输入。前端隐藏按钮只是体验层，后端每次敏感操作仍需验证。
7.3 共享时的资源边界
共享 Agent 可能包含第三方模型、知识库、私有工具、连接器和插件。目标用户是否能运行，取决于目标环境是否具备独立合法的资源连接与授权。平台应展示“可安装但需要配置资源”“可直接调用受管服务”“因政策不可用”等明确状态，而不是一律显示“已共享即可使用”。
08 · Agent 目录、详情与发现
8.1 目录信息架构
建议卡片包含：名称、目标任务、适用场景、发布者、当前稳定版本、支持的输入输出、关键资源要求、使用范围和维护状态。能力声明应与已验证范围区分，不应将营销描述伪装成性能保证。
8.2 详情页
详情页至少回答：它能做什么、不能做什么、需要什么权限和成本、如何开始、版本是谁维护的、最近发生了什么变化。推荐信息区：概述、输入输出示例、所需资源、使用限制、版本历史、更新日志、测试与风险说明、安装/调用按钮。
8.3 搜索与排序
初期可按名称、标签、所有者、项目、更新时间过滤；后续加入全文和语义检索。排序算法不得默认将高调用量解释为高质量；若提供“推荐”，应披露主要排序维度，并提供举报和质量纠错入口。
09 · 复用方式、安装与依赖适配
9.1 三种复用方式
| 方式 | 对象关系 | 上游更新 | 适用场景 |
|---|---|---|---|
| 引用（Reference） | 保留上游 Agent 身份，运行时按约定版本解析 | 依锁定/渠道策略 | 统一维护的团队能力 |
| 安装（Install） | 建立目标工作空间安装记录和本地资源绑定 | 可手动/审核升级 | 跨项目复用 |
| 复制/派生（Fork） | 创建新 Agent Definition，保留来源信息 | 不自动继承 | 深度定制、模板开发 |
9.2 安装向导
安装向导应依次展示：来源和可信度 → 版本选择 → 目标工作空间 → 所需模型与工具 → 权限与预算 → 本地凭证绑定 → 测试连接 → 安装确认。安装完成后提供“运行示例”和“打开配置”两个入口。
9.3 依赖处理
不能把发布者的凭证复制到安装方。依赖可按“平台共享能力”“工作空间需绑定”“用户需单独授权”“目标环境不支持”分类。对可升级依赖记录版本范围与锁定版本；对不可用依赖给出可操作的替代或阻断说明。
9.4 更新策略
默认建议生产环境显式批准更新。自动跟随 stable 可用于低风险试验环境，但应展示潜在行为变化、回归结果和回滚路径。更新通知需要说明影响：配置变化、依赖变化、权限新增、接口兼容性与成本变化。
10 · 审核、上架与 Marketplace
10.1 三层审核
- 技术校验：定义、依赖、签名/摘要、恶意内容与安全扫描。
- 使用治理：权限、数据许可、外部副作用、配额和审计要求。
- 目录治理：发布者身份、说明准确性、内容政策、举报与下架流程。
内部发布可以按风险简化审批；面向公众的 Marketplace 应采用更严格的治理流程。自动化扫描不能完全证明 Agent 安全，也不能替代必要的人类复核。
10.2 Marketplace 的产品边界
Marketplace 增加目录运营、开发者身份、审核、评分、发现、安装、举报、下架和支持责任；不应与底层 Registry 混为一谈。收费、分成和商业结算属于后续商业系统，不能仅凭 Agent 下载量判断价值。
10.3 评价体系
建议将“使用评价”“可验证的测试证据”“安全与治理状态”“维护活跃度”分开呈现。用户评价可能受样本偏差、刷评与不同任务难度影响，不应视为客观质量证明。
11 · 撤销、废弃、下架与生命周期
| 操作 | 影响对象 | 对新运行的影响 | 对历史记录的影响 |
|---|---|---|---|
| 取消共享 | Share Grant | 不再允许无权主体访问 | 保留审计记录 |
| 废弃版本 | Agent Version 状态 | 可警告或按政策阻断 | 版本仍可追溯 |
| 撤销版本 | Version 可执行资格 | 应阻止新运行 | 已在途 Run 需单独决策 |
| 渠道回滚 | Release Channel | 新运行解析到旧版 | 不修改历史 Run |
| 目录下架 | Catalog Listing | 不再公开发现 | 不必立即删除版本 |
| 停止部署 | Deployment | 阻止相应环境新运行 | 需处理在途任务 |
| 删除/归档 | 定义及关联数据 | 按保留策略执行 | 受审计、法律保留与引用约束 |
关键区别： 下架不是删除；撤销未来使用权限也不能保证已下载副本消失。发生高风险事件时应提供紧急禁用机制，并由运行管理系统决定是否中断在途任务及处理外部副作用。
12 · 产品与技术架构映射
sequenceDiagram
actor Builder as 构建者
participant UI as 发布工作台
participant Dev as P4 Development Services
participant Gov as P12 Governance
participant Reg as P3 Agent Registry
participant Cat as Catalog/Sharing
participant CP as P1 Control Plane
Builder->>UI: 选择草稿与发布范围
UI->>Dev: 校验草稿与测试证据
Dev-->>UI: 校验结果
UI->>Gov: 发布与共享策略检查
Gov-->>UI: 允许/审批/拒绝
UI->>Reg: 幂等提交不可变版本
Reg-->>UI: agent_version_id
UI->>Cat: 更新目录与授权
Builder->>UI: 设置 stable 渠道
UI->>Reg: 原子更新渠道指针
Note over CP,Reg: Run 启动时解析并固定版本
CP->>Reg: 解析 stable
Reg-->>CP: 不可变版本 ID| 产品能力 | 主要技术服务 | 必要依赖 |
|---|---|---|
| 发布预检 | P4 Development Services | F3 测试证据、P7 依赖 |
| 版本冻结 | P3 Registry | P10 资产存储 |
| 渠道切换 | P3 Registry / P1 Control Plane | P12 策略与审计 |
| 共享授权 | P11 Isolation / P12 Governance | 身份与组织关系 |
| 目录与发现 | Catalog 服务 / P10 索引 | 授权过滤 |
| 安装与资源绑定 | P7 Resource & Integration | 凭证与连接 |
| Agent 运行 | P1/P2/P5 | F6 运行界面 |
| 插件和市场生态 | P9 Extensibility | 安全审核与版本管理 |
13 · 参考接口与数据契约
13.1 发布请求示例
{
"agent_id": "agt_topic_research",
"draft_revision_id": "dr_00042",
"version_label": "1.0.0",
"release_notes": "首次稳定发布：支持结构化选题候选和审核输入",
"channel": "stable",
"visibility": "project",
"project_ids": ["prj_research_studio"],
"evaluation_report_ids": ["eval_0081"],
"idempotency_key": "pub_20261101_topic_1"
}以上为设计示例，不是现有平台的正式 API。真实实现建议把 Idempotency-Key 放在 HTTP 请求头，并用服务端授权上下文确定租户身份，而不是信任客户端传入的租户 ID。
13.2 参考 API
| 方法与路径 | 目的 | 重要约束 |
|---|---|---|
POST /v1/agents/{id}/publications/validate | 发布预检 | 绑定草稿修订、返回检查 ID |
POST /v1/agents/{id}/publications | 提交发布 | 幂等、审批、不可变写入 |
GET /v1/agents/{id}/versions | 查询版本 | 权限过滤、分页 |
POST /v1/agents/{id}/channels/{name}:promote | 切换渠道 | 乐观锁、审批、审计 |
POST /v1/agents/{id}/grants | 创建共享授权 | 对象级授权 |
DELETE /v1/agents/{id}/grants/{grant_id} | 撤销授权 | 传播延迟与审计 |
GET /v1/catalog/agents | 搜索目录 | 可见性过滤 |
POST /v1/installations | 安装 Agent | 目标工作空间授权、依赖预检 |
POST /v1/agents/{id}:fork | 派生 Agent | 许可与来源记录 |
POST /v1/agents/{id}/versions/{version}:revoke | 紧急撤销版本 | 高权限、影响评估 |
13.3 错误契约示例
{
"error": {
"code": "PUBLICATION_PRECHECK_FAILED",
"message": "发布前检查未通过",
"request_id": "req_8b21",
"details": [
{"field": "tool_bindings.search", "reason": "MISSING_TARGET_AUTHORIZATION"},
{"field": "evaluation_report_ids", "reason": "STALE_DRAFT_REVISION"}
]
}
}常见错误包括 VERSION_ALREADY_EXISTS、DRAFT_REVISION_CONFLICT、POLICY_DENIED、APPROVAL_REQUIRED、DEPENDENCY_UNAVAILABLE、INSTALLATION_INCOMPATIBLE、CHANNEL_ETAG_MISMATCH 和 REVOKED_VERSION。前端应提供可修复指引，不直接暴露内部密钥或敏感审计内容。
14 · 数据模型与一致性参考
14.1 关系表草案
CREATE TABLE agent_publications (
publication_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
agent_id UUID NOT NULL,
draft_revision_id UUID NOT NULL,
agent_version_id UUID,
status TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
initiated_by UUID NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (tenant_id, idempotency_key)
);
CREATE TABLE agent_release_channels (
tenant_id UUID NOT NULL,
agent_id UUID NOT NULL,
channel_name TEXT NOT NULL,
agent_version_id UUID NOT NULL,
revision BIGINT NOT NULL DEFAULT 1,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, agent_id, channel_name)
);
CREATE TABLE agent_share_grants (
grant_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
agent_id UUID NOT NULL,
principal_type TEXT NOT NULL,
principal_id UUID NOT NULL,
permission TEXT NOT NULL,
expires_at TIMESTAMPTZ,
revoked_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE agent_installations (
installation_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
workspace_id UUID NOT NULL,
source_agent_id UUID NOT NULL,
pinned_version_id UUID NOT NULL,
update_policy TEXT NOT NULL,
installed_by UUID NOT NULL,
installed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);此 DDL 仅展示关键关系，不是可直接投产的完整 Schema。实际实现还需外键、复合租户约束、RLS、审计表、索引、软删除与保留策略、并发控制和权限边界；不得依赖客户端的 tenant_id 实现隔离。
14.2 一致性与事件
发布写入 Registry、渠道切换、目录索引与通知属于多个存储边界。建议采用事务内写版本与 Outbox 事件、事务外幂等消费的方式传播索引和通知。不能在数据库事务失败后仍向用户显示“发布成功”。对搜索目录的短暂最终一致性应明确展示“发布成功，目录索引更新中”。
14.3 事件示例
{
"event_id": "evt_20261101_001",
"event_type": "agent.version.published",
"occurred_at": "2026-11-01T05:00:00Z",
"tenant_id": "tenant_example",
"agent_id": "agt_topic_research",
"agent_version_id": "av_100",
"publication_id": "pub_100",
"actor_id": "user_example"
}事件消费者需要去重；审计与事件通知不等同，审计记录应遵循独立的完整性和保留要求。
15 · Studio 贯穿案例：发布并复用选题 Agent
15.1 业务背景
研究报告 Studio 的工作流包括选题、审核、深度调研、分析、写作和交付。构建者已经通过 F3 对“选题 Agent”完成结构化输出、重复候选、无引用主张和异常输入等测试，现在希望把该 Agent 提供给多个研究项目。
15.2 从发布到复用的用户旅程
| 阶段 | 用户行为 | 系统响应 | 验收要点 |
|---|---|---|---|
| 创建版本 | 选择选题 Agent 的已测草稿 | 展示测试与依赖摘要 | 测试证据绑定修订 |
| 发布审核 | 项目负责人检查风险 | 同意发布 stable | 记录审批人和版本 |
| 配置共享 | 选择研究工作空间 | 创建 invoke/install 授权 | 不公开内部密钥 |
| 目录发现 | 其他项目成员搜索“选题” | 展示能力、示例和限制 | 仅显示有权目录项 |
| 安装引用 | 新项目安装 Agent | 检查搜索服务连接与预算 | 不复制原项目凭证 |
| 工作流绑定 | 将 Agent 加入选题节点 | 固定 agent_version_id | Run 可追溯 |
| 运行观察 | 发起研究任务 | 进入 F6/F8 | 输出与成本可追踪 |
| 升级维护 | 发布 v1.1 | 显示差异与回归结果 | 旧项目不被强制升级 |
| 发现问题 | 管理员撤销 v1.1 新运行 | 阻断新 Run、提示回滚 | 在途任务单独处置 |
15.3 用户界面建议
Studio 的 Agent 详情页可采用四个标签：概览、配置与测试、版本与发布、共享与安装。构建者看到完整编辑能力；普通成员只看到授权范围内的能力描述、调用入口和必要资源说明。版本历史中的每条记录展示发布时间、发布人、变更摘要、测试报告、当前渠道及使用情况。
15.4 最小闭环与后续扩展
初期优先完成：不可变发布版本、项目内共享、稳定渠道、安装引用、依赖提示、版本差异、审计日志。公开市场、评价系统、商业分成、复杂跨租户许可证和自动升级可后置。对于用户数量较少的 Studio，过早建设 Marketplace 会增加安全与运营成本，而不一定改善核心研究交付体验。
16 · 失败场景、风险与可恢复性
| 失败场景 | 用户可见表现 | 平台处理原则 |
|---|---|---|
| 发布时草稿变化 | 提示重新预检 | 草稿修订乐观锁 |
| 版本标签冲突 | 显示已存在版本 | 不覆盖不可变版本 |
| 测试报告过期 | 说明测试对应旧草稿 | 要求重跑必要测试 |
| 发布者权限被撤销 | 发布被拒绝 | 提交时重新鉴权 |
| 资源依赖失效 | 显示不可安装/不可运行 | 不把凭证打包到版本 |
| 目录索引延迟 | 发布成功但搜索暂不可见 | 显示索引进度、重试 |
| 共享链接外泄 | 未授权访问被拒绝 | 链接不替代身份验证 |
| 跨租户安装 | 提示重新绑定资源 | 强制租户边界与许可检查 |
| 渠道并发切换 | 冲突提示与重试 | ETag/版本号比较更新 |
| 已发布版本发现恶意工具 | 禁止新运行并通知管理员 | 版本撤销与依赖封禁 |
| 安装后上游下架 | 显示维护状态 | 区分目录下架与执行撤销 |
| 回滚后仍有旧任务 | 提示在途运行 | 不擅自改变 Run 快照 |
| 复制模板含敏感配置 | 阻止复制/清理引用 | 敏感字段分级与脱敏 |
| 大量公开 Agent 刷榜 | 降低异常推荐权重 | 反滥用与人工复核 |
17 · 产品指标、可用性与分阶段开发
17.1 指标体系
| 维度 | 参考指标 | 解释限制 |
|---|---|---|
| 发布效率 | 首次发布完成率、发布耗时 | 不应牺牲安全门禁 |
| 共享效率 | 被授权用户成功发现率 | 需区分权限过滤 |
| 安装体验 | 安装完成率、依赖配置耗时 | 受第三方服务影响 |
| 复用价值 | 被不同项目实际调用的 Agent 比例 | 调用多不等于质量高 |
| 版本质量 | 发布后回滚率、关键回归失败率 | 需按风险与发布规模分组 |
| 治理安全 | 越权拦截、错误公开、撤销生效时延 | 不能只看拦截数量 |
| 维护健康 | 废弃版本使用量、未处理风险通知 | 需区分历史 Run |
不应设定未经实验支持的统一目标值。产品验证需要按用户类型和发布范围分层，结合任务观察、日志与定性访谈。
17.2 五阶段建设路线
| 阶段 | 建设范围 | 交付门槛 |
|---|---|---|
| M0 内部发布 | 草稿预检、不可变版本、版本历史 | 发布不改变在途任务 |
| M1 项目共享 | 共享权限、团队目录、调用入口 | 未授权主体不可发现/调用 |
| M2 安装复用 | 安装、资源绑定、模板派生 | 不复制凭证、可追溯来源 |
| M3 组织协作 | 审批、渠道管理、通知、审计 | 可回滚、可撤销、可追责 |
| M4 开放生态 | 公开目录、开发者审核、举报下架 | 完成威胁建模和运营流程 |
17.3 用户研究任务
让首次使用者完成“发布一个测试通过的 Agent”；让项目负责人完成“仅向指定项目共享”；让业务成员完成“发现、安装并运行”；让管理员完成“撤销一个高风险版本并解释影响”。观察错误理解、重复点击、权限误判、依赖配置失败和回滚决策，不只记录按钮点击次数。
18 · 工程验证与验收测试矩阵
以下均为建议测试，未执行。
| ID | 测试情境 | 预期结果 |
|---|---|---|
| T01 | 发布已保存且通过校验的草稿 | 生成不可变版本 |
| T02 | 发布过程中草稿被修改 | 阻断或要求重新预检 |
| T03 | 重复提交同一幂等键 | 返回同一发布结果 |
| T04 | 同 Agent 重复版本标签 | 明确冲突，不覆盖 |
| T05 | 无发布权限主体提交 | 拒绝并审计 |
| T06 | 测试报告对应旧草稿 | 不允许复用过期证据 |
| T07 | 关键安全测试失败 | 按策略阻断发布 |
| T08 | 未获审批尝试发布 stable | 要求审批 |
| T09 | 已发布版本被编辑 | 拒绝直接修改 |
| T10 | stable 指针并发更新 | 仅一个 CAS 更新成功 |
| T11 | 渠道回滚 | 新 Run 解析旧版，历史 Run 不变 |
| T12 | 无 discover 权限搜索 | 不返回目录项 |
| T13 | 有 discover 无 invoke 权限 | 可见但不可运行 |
| T14 | 有 invoke 无 inspect 权限 | 可调用但看不到内部 Prompt |
| T15 | 分享设置为 project | 其他项目被拒绝 |
| T16 | 跨租户安装 | 重新验证身份与许可 |
| T17 | 安装 Agent 需要外部搜索连接 | 明确提示并完成本地绑定 |
| T18 | 安装时缺失凭证 | 不继承发布者凭证 |
| T19 | 从模板 Fork | 产生新 Agent ID，保留来源 |
| T20 | 上游发布新版 | 固定版本安装不被静默升级 |
| T21 | 自动升级触发不兼容 Schema | 阻断并提示迁移 |
| T22 | 撤销共享授权 | 新访问被拒绝 |
| T23 | 下架目录项 | 搜索消失，历史版本保留 |
| T24 | 撤销高风险版本 | 新 Run 被阻断 |
| T25 | 已运行任务遇到版本撤销 | 按明确策略处理并审计 |
| T26 | 发布后索引更新失败 | 通过 Outbox 重试，状态透明 |
| T27 | Manifest 包含明文密钥 | 预检拒绝 |
| T28 | 插件依赖被撤销 | 安装或运行时被阻断 |
| T29 | 公开详情页访问私有知识 | 不暴露知识内容或地址 |
| T30 | 导出/复制权限不足 | 拒绝 Fork/Export |
| T31 | 发布审计日志查询 | 能关联主体、版本、时间和结果 |
| T32 | 目录搜索分页与权限变化 | 不出现跨租户泄漏 |
| T33 | 使用者收到废弃通知 | 明确影响版本和升级路径 |
| T34 | 用户取消发布操作 | 明确区分未提交和已提交事务 |
| T35 | 渠道切换后新 Run 创建 | Run 记录解析后的具体版本 ID |
| T36 | 用户报告恶意公开 Agent | 进入审核、下架与通知流程 |
19 · 局限、取舍与开放问题
- 行为兼容性难以完全自动判断。 即使输入输出 Schema 未变，Prompt、模型或检索资源变化也可能影响语义质量；需要 F3 回归证据和真实使用反馈。
- 不可变版本不等于完全可复现。 外部模型、实时检索和第三方工具的行为可能变化，应固定可控依赖并记录运行环境。
- 共享与保密存在张力。 可调用 Agent 的用户不一定有权读取内部 Prompt；若 Agent 行为暴露敏感信息，还需运行时防护与测试。
- 撤销有传播时延。 缓存、离线副本和在途任务可能继续存在，需定义一致性与应急策略。
- 跨租户共享涉及法律与许可问题。 数据、插件、模型使用条款和知识资产的许可不能仅靠技术授权替代。
- Marketplace 的质量排名容易被误用。 下载量、评分、调用量不是可靠的任务质量证据。
- 发布流程复杂度需要与风险匹配。 对内部低风险 Agent 不必套用公开市场级审核；对外部写操作或敏感数据 Agent 则不能只用简单“确认发布”代替治理。
附录 A：参考文献与原始资料
以下资料用于核对通用版本、接口、安全与供应链原则；并不存在由这些资料共同规定的统一 Agent Publishing & Sharing 标准。具体 Agent 产品的功能和术语可能随版本变化，实施前应重新核验。
- OpenAPI Initiative. OpenAPI Specification 3.1. spec.openapis.org/oas/v3.1.0.html - API 契约与描述原则。
- JSON Schema. JSON Schema Core / Validation. json-schema.org/specification - Agent Manifest 的结构校验基础。
- Semantic Versioning. Semantic Versioning 2.0.0. semver.org - 可选版本标签规则及适用前提。
- OCI. OCI Image Specification. github.com/opencontainers/image-spec - 不可变工件、描述符与内容摘要的类比参考；不直接规定 Agent 发布。
- OCI. Distribution Specification. github.com/opencontainers/distribution-spec - 工件分发与注册机制参考。
- SLSA. Supply-chain Levels for Software Artifacts. slsa.dev/spec/v1.0 - 构建来源与供应链完整性参考。
- Sigstore. Documentation. docs.sigstore.dev - 签名和验证参考。
- NIST. Secure Software Development Framework (SP 800-218). csrc.nist.gov/pubs/sp/800/218/final - 安全开发与发布过程。
- OWASP. Top 10 for Large Language Model Applications. genai.owasp.org/llm-top-10 - 提示词注入、供应链、敏感信息等风险。
- PostgreSQL. Documentation: Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html - 多租户数据隔离参考。
- Kubernetes. Deployments. kubernetes.io/docs/concepts/workloads/controllers/deployment - 部署和滚动更新机制的技术类比；不等于 Agent 发布。
- OpenAI. Agents SDK Documentation. openai.github.io/openai-agents-python - Agent 定义与运行工具链的产品案例。
- LangChain. LangGraph Documentation. docs.langchain.com/oss/python/langgraph/overview - Agent/工作流运行与持久化的产品案例。
- Dify. Documentation. docs.dify.ai - 可视化 AI 应用发布和使用体验的产品案例，功能以具体版本为准。
- OAuth Working Group. OAuth 2.0 Authorization Framework (RFC 6749). www.rfc-editor.org/rfc/rfc6749 - 委托授权的基础参考；实际实施还需遵循后续安全最佳实践。
附录 B：研究证据、验证声明与适用边界
B.1 证据分级
| 类型 | 本文内容 | 可信边界 |
|---|---|---|
| 标准/规范可核对 | JSON Schema、OpenAPI、OAuth、SemVer 的基本规则 | 只支持对应技术机制 |
| 官方技术文档可核对 | OCI、PostgreSQL、Kubernetes 等技术组件的能力 | 不意味着 Agent Platform 必须使用它们 |
| 工程推论 | 发布不可变、渠道指针、运行版本固定、授权分离 | 需要结合系统需求验证 |
| 参考设计 | 页面、状态机、API、SQL、Studio 工作流 | 尚未实现和测试 |
| 开放问题 | Marketplace 治理、行为兼容性、撤销传播 | 需进一步研究与实测 |
B.2 验证声明
本篇未执行代码部署、数据库迁移、自动化测试、渗透测试、用户访谈或 Marketplace 运营实验。文中 T01 - T36 为待实施的验证方案；JSON、SQL 与 Mermaid 为参考表达，不能视为已验证的生产实现。文中引用的外部资料仅用于说明技术原则和可研究案例，未逐项完成当前版本在线核验。
B.3 适用范围
适用于需要管理多个 Agent、多个项目或多用户复用的 Agent Platform，尤其适合从内部 Studio 逐步演进到团队协作平台的产品设计。对单用户、单 Agent、无需版本与共享的实验性工具，可以只保留最小发布与版本机制。公开 Marketplace、商业化分发和跨租户资产交易需要独立的安全、法律、运营和财务研究。