P3 · 如何注册、存储和管理 Agent 定义与版本？ - Agent Registry
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：平台如何为 Agent 建立可识别、可校验、可版本化、可追溯、可授权访问的定义注册中心，并将发布后的 Agent 版本安全地交付控制面与执行面？
专题导读
本篇属 Technical Architecture。Agent Registry（Agent 注册中心）是 Agent Platform 管理Agent 定义、不可变版本、引用关系、发布状态和可发现性的核心服务。它使“一个 Agent 是什么”与“它此刻在哪里执行”解耦，使平台能够复用 Agent、审查变更、固定运行配置、回滚发布，并追踪某次 Run 使用的具体版本。
本篇研究的是平台级注册、元数据、版本与分发机制，不是 02 · Agent 中的单体 Agent 设计方法，也不是 03 · Agent System 中的运行状态管理。P4 负责开发和构建体验，P5 负责部署及运行生命周期，P10 负责更广泛的平台数据资产；P3 则提供 Agent 定义与版本的可信记录和解析契约。
研究结论
- Agent Definition 与 Agent Version 必须分离。 Definition 表示长期稳定的逻辑身份；Version 表示一次经过校验、可被执行引用的不可变定义快照。
- Registry 是控制面可依赖的事实来源之一，而不是执行引擎。 Registry 负责“是什么、哪个版本、是否允许使用”；控制面负责“谁可执行、是否准入”，执行面负责“实际怎样执行”。
- 可复现性依赖完整依赖锁定。 只记录提示词或模型别名不足以重建执行；应记录模型策略、工具契约、Skill/Workflow 引用、运行镜像或适配器版本，以及可校验的摘要。即便如此，外部模型与动态数据也可能导致结果不可完全复现。
- 发布是受控状态转换，不等于写入数据库。 Draft、Validated、Published、Deprecated、Revoked 等状态须有明确准入条件和审计记录。
- 别名可变，版本不可变。
production、latest等指针可以切换；运行开始时必须解析为确定的 Version ID 与快照摘要。 - Registry 的访问控制与供应链完整性同等重要。 应区分读取、编辑、验证、发布、撤销和跨组织共享权限，并对依赖和工件进行完整性检查。
- 初期优先采用关系数据库 + 对象存储 + 后端注册模块。 只有在跨团队共享、分发规模和扩展需求明确后，才需要独立注册服务或市场化目录。
一、定义与系统边界
1.1 Agent Registry 是什么
Agent Registry 是一组持久化存储、查询、校验、版本管理、发布和引用解析能力。其管理的主要对象包括 Agent Definition、Agent Version、Release/Channel、依赖清单、校验报告和审计事件。它可以是独立服务，也可以是模块化单体中的一个模块。
一个平台即使有“创建 Agent”按钮，也不一定具备成熟 Registry。判断依据是：是否能够给 Agent 稳定身份、保存历史版本、执行结构化校验、固定运行引用、实施访问控制，并追溯发布与撤销。
1.2 与相邻专题的职责划分
| 专题 | 主要职责 | P3 的交界面 |
|---|---|---|
| P1 Control Plane | 身份、准入、执行意图与状态控制 | 解析指定 Agent Version、校验可用性 |
| P2 Execution Plane | Worker、沙箱、任务执行 | 获取已授权的不可变执行快照 |
| P4 Agent Development Services | 编辑、构建、测试与验证流程 | 写入草稿、提交验证结果、发起发布 |
| P5 Deployment & Runtime Management | 环境部署、运行实例、流量切换 | 将版本绑定到 Deployment |
| P6 Workflow Management | 工作流定义、编排与调度 | 管理 Agent 引用与工作流依赖锁定 |
| P7 Resource & Integration | 模型、工具、连接器资源管理 | 校验引用是否存在及访问范围 |
| P9 Extensibility & Ecosystem | 插件与扩展生命周期 | 记录插件依赖及兼容性 |
| P10 Platform Data & Assets | 全平台资产存储、共享与治理 | Agent 版本属于其特定资产子域 |
| P11/P12 | 租户隔离、权限与治理 | 作用域、发布审批、审计、撤销 |
1.3 Registry 不是什么
Registry 不负责运行 Agent 推理循环，不替代队列或 Worker；不负责保管所有运行中的会话状态；不应把明文 API Key 直接嵌入版本快照；也不意味着平台必须提供公开 Agent Marketplace。注册中心可完全私有。
二、对象模型与身份体系
2.1 核心对象
| 对象 | 身份与含义 | 可变性 |
|---|---|---|
| Agent Definition | Agent 的稳定逻辑实体，含所有权、名称、描述、标签 | 元数据可变 |
| Agent Draft | 可编辑工作副本，含未发布配置 | 可变 |
| Agent Version | 一次冻结的可执行定义及依赖清单 | 发布后不可变 |
| Validation Report | 针对某草稿/版本的规则与测试结果 | 结果不可覆盖，允许追加 |
| Release Channel | dev、staging、production 等版本指针 | 可变，受审批 |
| Dependency Lock | 版本所引用模型策略、工具、技能与工件的解析结果 | 与版本一起冻结 |
| Publication Event | 发布、弃用、撤销与渠道切换记录 | 仅追加 |
| Sharing Grant | 对其他用户、工作空间或组织的访问授权 | 可撤销 |
设计要点：Agent Version 与 Deployment 是不同对象。Version 描述可执行内容，Deployment 描述某版本在某环境中的提供方式。一个版本可以部署到多个环境；同一环境也可能通过渠道或流量策略指向多个版本。
2.2 身份与命名
建议使用内部不可变 ID 作为主键，例如 agt_...、agv_...；可读 slug 用于展示与 URL，但不应作为唯一外键。资源定位至少包含 tenant_id 与 agent_id，跨租户读取需独立授权。
示例路径：/v1/workspaces/{workspace_id}/agents/{agent_id}/versions/{version_id}。这只是参考 API，不代表现有标准。
2.3 关系图
flowchart LR
T[Tenant] --> W[Workspace]
W --> A[Agent Definition]
A --> D[Editable Draft]
A --> V1[Agent Version v1]
A --> V2[Agent Version v2]
V1 --> L1[Dependency Lock]
V2 --> L2[Dependency Lock]
A --> C[Release Channel]
C -->|resolves to| V2
V2 --> DEP[Deployment / P5]
DEP --> RUN[Run / P1-P2]注意：Run 应同时保存 version_id、snapshot_digest 与 deployment_id（如有），而不能只保存可变的 production 渠道名。
三、Agent 定义的结构与契约
3.1 推荐字段分层
- 身份层：
agent_id、tenant_id、workspace_id、name、owner、visibility。 - 行为层：角色、指令、目标、输出契约、行为限制、终止条件。
- 模型层：模型选择策略、参数范围、回退策略、能力需求；避免把会轮换的凭据写入定义。
- 能力层：工具引用、Skill 引用、知识源引用、工作流入口及版本约束。
- 运行需求层：超时、最大步骤、预算、沙箱等级、并发约束；由控制面最终裁决。
- 治理层：权限声明、敏感操作要求、审批策略引用、数据分类。
- 追溯层：schema 版本、创建者、更新时间、依赖锁摘要、内容摘要。
3.2 参考定义示例
{
"schema_version": "agent.definition/v1",
"agent_id": "agt_research_01",
"name": "Research Agent",
"instructions": {
"system_ref": "asset://prompts/researcher@sha256:EXAMPLE"
},
"model": {
"policy_ref": "model-policy://research-balanced@v2"
},
"tools": [
{"ref": "tool://web-search@2.1.0", "permission": "read"}
],
"skills": ["skill://citation-check@1.3.0"],
"output_schema_ref": "schema://research-result@v1",
"limits": {"max_steps": 30, "max_runtime_seconds": 1800},
"security": {"sandbox_profile": "network-restricted"}
}以上为示意契约，URI 和摘要均非真实资源。实际实现须定义 JSON Schema、资源解析规则和兼容性策略。system_ref 应指向受访问控制的资产，不应允许通过任意外部 URL 绕过授权。
3.3 定义与运行时注入的分界
定义中保存“需要哪类凭据/连接器”的声明；运行时由受控 Secret Manager 注入具体凭据。版本快照可以固定连接器接口版本，但不应冻结令牌明文。运行时上下文（用户消息、会话记忆、实时检索结果）也不属于静态 Agent Version 本体。
四、注册、校验与发布流程
4.1 参考生命周期
stateDiagram-v2
[*] --> Draft
Draft --> Validating: submit
Validating --> Draft: validation failed
Validating --> Validated: passed
Validated --> Published: approved publish
Published --> Deprecated: deprecate
Published --> Revoked: security revoke
Deprecated --> Revoked: revoke
Deprecated --> [*]: retention completed
Revoked --> [*]: retention completed状态设计说明：上述状态是逻辑示例，不要求所有平台采用同一枚举。撤销不应删除历史审计或使已存在的 Run 引用失效；如何停止正在运行的任务属于 P1/P5 的策略决策。
4.2 发布流水线
- 创建/修改 Draft，使用乐观并发控制防止覆盖他人编辑。
- 对定义执行 schema 校验、字段语义校验、引用可达性与权限检查。
- 锁定依赖版本并计算规范化内容摘要；校验工具/Skill/模型策略兼容性。
- 执行必要的静态安全检查、模拟测试或评估，生成不可覆盖的报告。
- 按工作空间策略发起发布审批；关键环境可要求职责分离。
- 原子性写入 Agent Version、Dependency Lock 与 Publication Event。
- 按权限更新 Release Channel；写入审计事件并发送变更通知。
- 控制面在创建 Run 时解析渠道为具体版本并保存快照引用。
发布与渠道切换应区分：发布新版本不意味着立即将其投入生产流量。
4.3 校验矩阵
| 检查类别 | 示例 | 失败处理 |
|---|---|---|
| 结构 | 必填字段、schema 版本、字段类型 | 拒绝发布 |
| 引用 | 工具/技能/知识资产存在且可访问 | 拒绝发布 |
| 兼容性 | 工具参数、输出 schema、运行适配器 | 拒绝或阻断指定环境 |
| 安全 | 高风险工具、权限越界、疑似密钥 | 拒绝或人工审批 |
| 资源 | 步数、超时、预算是否超出平台上限 | 拒绝或收紧配置 |
| 质量 | 回归样例、基本功能测试、评估阈值 | 按发布策略阻断 |
| 供应链 | 依赖摘要、签名或可信来源 | 依安全级别阻断 |
质量阈值不是所有场景的统一数值，应按任务风险、数据敏感性和发布环境定义。
五、版本策略与兼容性
5.1 不可变版本与可变渠道
推荐 agent_id + version_id 唯一确定定义；production 等渠道是指针。不要将“更新 production 指针”实现为原地修改旧版本内容。版本可以使用单调递增编号、时间序列 ID 或内容摘要；SemVer 可作为用户可读标签，但不保证语义兼容。
5.2 兼容性分类
- 配置兼容：指令、参数调整是否影响既有调用。
- 接口兼容：输入输出 schema、工具参数是否破坏调用方。
- 运行兼容：Worker 适配器、运行镜像、沙箱能力是否满足依赖。
- 数据兼容：历史记忆、检查点和产物能否由新版本读取。
- 策略兼容：新版本是否需要更高权限或不同审批流程。
不能简单以“版本号加一”判断兼容；应将接口与运行要求显式表达，并通过测试验证。
5.3 回滚语义
回滚通常是将渠道或 Deployment 指针切回旧版本，而不是修改旧版本。旧版本若依赖已撤销的工具或密钥，也可能无法重新部署。因此回滚前需要执行依赖可用性、安全与兼容性检查。
六、依赖解析与可复现性
6.1 依赖图
Agent 可能依赖模型策略、提示词、工具、Skill、知识资产、Workflow、运行镜像和策略包。发布时至少记录每项依赖的身份、版本约束、实际解析版本、摘要与访问作用域。
flowchart TD
AV[Agent Version] --> MP[Model Policy]
AV --> PR[Prompt Asset]
AV --> TL[Tool Contract]
AV --> SK[Skill Package]
AV --> KB[Knowledge Source]
AV --> RT[Runtime Adapter]
TL --> CON[Connector Version]
SK --> PKG[Package Digest]6.2 锁定策略
- 严格锁定：工具接口、技能包、提示词、镜像等可以固定的依赖使用精确版本/摘要。
- 策略锁定：模型路由可固定为策略版本，但策略背后的第三方模型可能更新，需保留实际调用模型标识。
- 动态资源：知识库和外部网页持续变化；运行时记录检索索引版本、文档快照或查询证据（受保留策略约束）。
- 执行快照：Run 记录
version_id、snapshot_digest、resolved_dependencies、effective_policy_id。
限制：固定依赖能改善可审计性，不保证 LLM 输出逐字一致。模型服务升级、非确定性采样和外部环境变化均可能影响结果。
七、存储架构与一致性
7.1 推荐存储分工
| 数据 | 推荐存储 | 原因 |
|---|---|---|
| Agent 元数据、所有权、状态 | 关系数据库 | 事务、唯一性、查询 |
| Version 清单与依赖索引 | 关系数据库 | 引用完整性与版本解析 |
| 大型配置工件、技能包、测试附件 | 对象存储 | 体积、内容摘要、低成本保留 |
| 搜索索引、标签检索 | 搜索引擎或数据库索引 | 可发现性 |
| 发布与审批事件 | 追加型审计表/事件流 | 追溯与通知 |
| 凭据 | 专用密钥服务 | 轮换与最小暴露 |
7.2 最小关系模型
CREATE TABLE agents (
id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
workspace_id TEXT NOT NULL,
name TEXT NOT NULL,
slug TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (workspace_id, slug)
);
CREATE TABLE agent_versions (
id TEXT PRIMARY KEY,
agent_id TEXT NOT NULL REFERENCES agents(id),
version_label TEXT NOT NULL,
schema_version TEXT NOT NULL,
manifest JSONB NOT NULL,
content_digest TEXT NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (agent_id, version_label)
);
CREATE TABLE agent_channels (
agent_id TEXT NOT NULL REFERENCES agents(id),
channel TEXT NOT NULL,
version_id TEXT NOT NULL REFERENCES agent_versions(id),
revision BIGINT NOT NULL DEFAULT 1,
PRIMARY KEY (agent_id, channel)
);这是教学用最小 SQL 草案，尚未包含 tenant 复合外键、RLS、审计、草稿表、状态约束和不可变性触发器，不可直接视为生产数据库设计。
7.3 原子发布与事件通知
发布时在同一事务内写入 Version、状态、审批引用及 outbox 事件；事务提交后由 outbox worker 异步发送通知。这样可减少“数据库已发布但消息未发送”的不一致窗口。消费者仍须幂等处理重复通知。
7.4 并发与缓存
Draft 编辑使用 etag/revision 乐观锁。渠道切换使用 compare-and-swap，避免并发覆盖。Registry 查询可缓存不可变 Version，但渠道指针需要短 TTL 或事件失效；关键运行创建应在可信服务端解析版本，不应依赖浏览器缓存。
八、接口设计与控制面协作
8.1 参考 API
| 方法 | 路径 | 作用 |
|---|---|---|
| POST | /agents | 创建 Agent Definition |
| GET | /agents/{id} | 查询元数据与权限范围 |
| PUT | /agents/{id}/draft | 更新草稿（要求版本条件） |
| POST | /agents/{id}/validate | 校验草稿 |
| POST | /agents/{id}/versions | 创建不可变版本 |
| GET | /agents/{id}/versions/{vid} | 查询版本及摘要 |
| POST | /agents/{id}/channels/{channel} | 审批后切换渠道指针 |
| POST | /agents/{id}/versions/{vid}/deprecate | 标记弃用 |
| POST | /agents/{id}/versions/{vid}/revoke | 安全撤销 |
实际 API 需定义鉴权、幂等键、错误码、分页、审计字段及租户作用域。
8.2 Run 创建时的解析流程
sequenceDiagram
participant U as User / Studio
participant CP as Control Plane
participant R as Agent Registry
participant Q as Queue
participant W as Worker
U->>CP: Start Run(agent, channel)
CP->>CP: Authenticate + authorize
CP->>R: Resolve channel to immutable version
R-->>CP: version_id + digest + manifest
CP->>CP: Validate policy, quotas, deployment
CP->>CP: Persist Run snapshot + outbox
CP-->>U: run_id (accepted)
CP->>Q: Dispatch run_id
Q->>W: Claim task
W->>CP: Fetch authorized execution snapshot
CP-->>W: pinned version + scoped credentials
W->>W: Execute Agent System
W-->>CP: events + artifacts + result关键不变量：控制面在创建 Run 后，渠道即使切换，既有 Run 也不应悄悄改用新版本。需要“升级正在运行任务”时，应有独立的显式迁移流程与兼容性验证。
8.3 Registry 服务内部授权
控制面与 Registry 之间应使用服务身份、明确作用域和审计。Worker 通常不应拥有枚举所有 Agent 的权限，而应通过 Run 授权获取特定版本及必要依赖。跨租户缓存键必须包含租户或授权上下文。
九、安全、权限与供应链
9.1 权限矩阵
| 动作 | Creator | Reviewer | Operator | Viewer |
|---|---|---|---|---|
| 创建/编辑草稿 | ✓ | 按策略 | - | - |
| 查看允许的版本 | ✓ | ✓ | ✓ | ✓ |
| 执行验证 | ✓ | ✓ | 按策略 | - |
| 审批生产发布 | - | ✓ | 按策略 | - |
| 切换部署渠道 | - | 按策略 | ✓ | - |
| 撤销危险版本 | 按策略 | ✓ | ✓ | - |
此表仅是角色权限示例。生产实现应以组织策略和最小权限为准，不能仅依赖固定角色名称。
9.2 常见风险
- 越权引用：一个租户引用另一个租户的私有 Agent/工具。
- 依赖投毒：恶意技能包、工具定义或外部模板被纳入发布版本。
- 渠道劫持：攻击者将
production指向未经批准的版本。 - 密钥泄漏：凭据被写入 manifest、日志或版本历史。
- 审计断裂：发布者、审批者、依赖摘要与运行版本无法对应。
- 撤销失效：被撤销版本仍可通过缓存或旧部署继续启动。
应实施对象级授权、签名/摘要验证、双人审批（按风险）、密钥扫描、不可覆盖审计、缓存失效和撤销传播。撤销后的既有 Run 是否终止，须由风险分级策略明确。
9.3 供应链完整性
可参考 OCI Artifact、SBOM、SLSA provenance 等成熟实践管理构建产物与来源，但它们不直接定义 Agent Registry 的行业统一格式。对于 Agent 的工具/技能依赖，至少保存来源、版本、摘要和审核状态。
十、可发现性、共享与资产治理
Registry 可以提供名称、标签、能力、作者、更新时间、兼容运行时、发布状态等索引；搜索结果必须按访问权限过滤。公开共享、组织共享和私有 Agent 的授权模型应明确区分。
Agent Marketplace 是 Registry 的可选产品层。Marketplace 往往还涉及评分、计费、审核、许可证、安装和升级流程；这些属于 F4 Publishing & Sharing、P9 Extensibility & Ecosystem 和 P10 Platform Data & Assets 的扩展研究范围。
删除策略应区分隐藏、归档、弃用、撤销和物理删除。存在 Run、Deployment、审计或合规保留依赖时，直接级联删除版本通常不可接受。
十一、研究报告 Studio 贯穿案例
11.1 场景
Studio 有选题 Agent、深度调研 Agent、分析 Agent、审核 Agent。一个 Studio 项目可引用多个 Agent；每个 Agent 可拥有不同版本。某次报告生成必须能追溯当时使用的版本组合。
11.2 示例版本清单
| Agent | 版本 | 主要变化 | 发布渠道 |
|---|---|---|---|
| Topic Agent | v1 | 基础选题流程 | production |
| Research Agent | v3 | 新检索工具与引用规则 | production |
| Analysis Agent | v2 | 新结构化输出 schema | staging |
| Review Agent | v2 | 新审稿策略 | production |
这些均为虚构示例，不是用户当前项目的真实部署状态。
11.3 Studio 推荐实现步骤
- 创建
agents、agent_drafts、agent_versions、agent_channels等最小表。 - 定义 Agent Manifest JSON Schema，并实现服务端校验。
- 实现草稿编辑、校验、创建不可变版本、渠道切换四条主链路。
- 在
studio_workflows中引用明确的 Agent Version，或在启动 Run 时解析并固定渠道。 - 在
runs保存每个 Agent 节点的version_id和依赖摘要。 - 为生产渠道切换建立权限检查与审计记录。
- 引入回归测试，验证新版本与现有 Studio Workflow 的接口兼容性。
- 在有实际需求后增加跨工作空间共享、市场目录、签名分发与复杂审批。
11.4 失败场景演练
场景 A：研究任务进行中，管理员发布新版本。 已启动的 Run 继续使用固定旧版本；新 Run 根据渠道指针使用新版本。
场景 B：某工具被安全撤销。 Registry 标记依赖受影响的版本；控制面禁止新建不符合策略的 Run，并按风险策略处理运行中任务。
场景 C：编辑者同时修改同一 Draft。 后提交者遇到 revision 冲突，不应静默覆盖先提交者。
场景 D：版本已入库，发布通知发送失败。 Outbox 机制重发通知，消费者按事件 ID 去重。
十二、架构取舍与演进路线
| 阶段 | 推荐 Registry 形态 | 重点能力 |
|---|---|---|
| 原型 | 后端模块 + 单数据库 | Agent 身份、草稿、版本、Run 引用 |
| 单租户 MVP | 增加发布状态、校验、渠道 | 稳定发布、可追溯与回滚 |
| 团队化 | 权限、审批、共享、审计 | 多人协作与变更控制 |
| 多租户 | 严格隔离、配额、缓存作用域 | 跨组织安全与资源治理 |
| 生态化 | 签名工件、兼容性、发现与分发 | 插件/Agent 市场和外部开发者 |
不要仅因为 Registry 概念独立就立即拆成微服务。优先定义清晰的模块 API、数据不变量和测试边界，再根据部署、吞吐与团队职责决定拆分。
十三、工程验证与验收设计
以下均为待实施测试计划，不是已执行测试结果。
| 编号 | 测试 | 预期结果 |
|---|---|---|
| T01 | 同一 Agent 创建多个版本 | Version ID 唯一，历史可查询 |
| T02 | 修改已发布版本 manifest | 被拒绝或生成新版本 |
| T03 | 无效 schema 提交发布 | 返回明确校验错误 |
| T04 | 引用不存在的工具版本 | 发布被阻断 |
| T05 | 越权读取跨租户 Agent | 访问被拒绝且留痕 |
| T06 | 并发编辑同一草稿 | 触发乐观锁冲突 |
| T07 | 并发切换同一渠道 | 仅符合 revision 的更新成功 |
| T08 | 发布后切换 production | 新 Run 使用新版本 |
| T09 | 运行中切换 production | 旧 Run 仍使用原版本 |
| T10 | 版本撤销后启动新 Run | 按策略拒绝 |
| T11 | Outbox 通知重复投递 | 消费者幂等处理 |
| T12 | Outbox 通知延迟 | 状态最终收敛，可告警 |
| T13 | 回滚到兼容旧版本 | 渠道切换成功，记录审计 |
| T14 | 回滚到依赖已失效版本 | 被阻断并说明原因 |
| T15 | 提交含密钥的配置 | 扫描阻断，日志脱敏 |
| T16 | 删除被 Run 引用的版本 | 受保留规则约束 |
| T17 | 使用缓存中的旧渠道指针 | 服务端运行解析得到正确版本 |
| T18 | 导出版本与依赖清单 | 能验证摘要与来源 |
| T19 | Agent 接口发生破坏性变更 | 兼容性检查识别风险 |
| T20 | 共享 Agent 被撤销授权 | 新访问被拒绝，缓存失效 |
建议验收指标：发布流程具备可审计记录；所有新建 Run 均持久化确定的版本 ID；生产版本内容不可原地修改；跨租户授权测试无越权；渠道切换与撤销传播有明确 SLO。具体数值应由项目实际需求决定。
十四、常见误区与自检
- 将 Agent 名称当成版本身份：重命名和并发编辑会破坏引用。
- 只存最后一次配置：无法解释历史 Run 的行为。
- 把
latest当成运行记录：渠道改变后历史不可追溯。 - 将 Registry 与 Runtime 合并为同一个对象：定义状态与执行状态互相污染。
- 在版本快照中存储明文密钥：导致长期泄漏风险。
- 把 SemVer 当作自动兼容保证：模型、工具和输出契约仍需测试。
- 发布时未锁定依赖：同一版本在不同时间运行可能依赖不同代码。
- 将发布与部署混同：无法区分“可用版本”和“生产环境使用版本”。
- 只做界面权限控制：API 和 Worker 仍可能越权访问。
- 用物理删除替代撤销：破坏审计和历史运行引用。
自检问题：能否回答“2026 年某次报告由哪个 Agent 版本、哪些工具与模型策略生成”？能否在不修改旧版本的前提下回滚？能否拒绝未经授权的跨租户引用？能否在 Worker 失联后重新取得可信的执行快照？如果不能，Registry 的核心不变量尚未建立。
十五、与后续专题的衔接
- P4 Agent Development Services：研究 Builder、编辑器、调试器如何生成和验证 Draft，并调用 Registry 发布版本。
- P5 Deployment & Runtime Management：研究 Version 如何被绑定到环境、形成 Deployment，并管理运行实例与发布策略。
- P6 Workflow Management：研究工作流如何固定 Agent 依赖，以及多个 Agent 版本的兼容性。
- P8 Platform API & SDK：研究对外注册、查询、发布 API 的稳定契约和开发者体验。
- P10 Platform Data & Assets：研究更广泛的 Prompt、Workflow、Knowledge、Artifact 的资产治理。
- F4 Agent Publishing & Sharing：研究终端用户视角的发布、共享、模板与复用流程。
- F9 Agent Management：研究用户如何查看版本历史、弃用、回滚和管理生命周期。
附录 A：参考文献与原始资料
以下资料主要用于核对架构思想、版本化工件、接口规范和供应链完整性。它们不构成统一的 Agent Registry 标准。
- Kubernetes Documentation - Controllers：kubernetes.io/docs/concepts/architecture/controller （期望状态与观测状态的控制模式）。
- Kubernetes Documentation - Deployments：kubernetes.io/docs/concepts/workloads/controllers/deployment （版本、发布与回滚的工程类比）。
- Open Container Initiative - Image Specification：github.com/opencontainers/image-spec （不可变清单、摘要与分发思想）。
- Open Container Initiative - Distribution Specification：github.com/opencontainers/distribution-spec （注册表分发协议的类比，不等于 Agent Registry API）。
- JSON Schema - Official Documentation：json-schema.org/learn （定义结构校验）。
- OpenAPI Initiative - Specification：spec.openapis.org/oas/latest.html （平台 API 契约）。
- SLSA - Supply-chain Levels for Software Artifacts：slsa.dev/spec/v1.1 （工件来源与完整性）。
- PostgreSQL Documentation - Transactions：www.postgresql.org/docs/current/tutorial-transactions.html （事务一致性）。
- PostgreSQL Documentation - Row Security Policies：www.postgresql.org/docs/current/ddl-rowsecurity.html （租户隔离的数据库控制选项）。
- NIST AI Risk Management Framework：www.nist.gov/itl/ai-risk-management-framework （AI 风险管理的总体参考）。
文献说明：上述链接为官方文档入口及通用技术规范，本文未进行实时联网逐页核验。实际落地前应检查具体版本、许可证和安全要求。
附录 B：研究证据、验证声明与适用边界
研究方法：基于既定 v1.3 目录及 P1/P2 研究边界，综合注册表、不可变工件、版本发布、关系数据库事务、供应链完整性与多租户授权等通用工程方法，提出 Agent Registry 的参考架构。
证据分类：
- 既有工程实践：不可变版本、内容摘要、事务、乐观锁、权限控制、审计、依赖清单等可从相关软件工程规范中找到依据。
- 研究性综合：Agent Definition / Draft / Version / Channel / Dependency Lock 的具体对象组合与发布状态机，是本文建议的参考模型，并非行业统一规定。
- 示意性材料：JSON Manifest、SQL DDL、API 路径、Studio 版本表和 Mermaid 图用于说明设计，不代表现有系统实现。
验证状态：未进行真实数据库迁移、API 联调、负载测试、安全测试或发布回滚演练。第十三节 T01 - T20 均为待实施测试。本文未声称对任何第三方 Agent 平台完成实际功能验证。
适用边界：适用于需要管理多个 Agent 定义及版本、支持持续发布和可追溯运行的 Agent Platform。对于一次性脚本或单 Agent 原型，可以采用更简单的文件版本控制方案；对于受监管、高安全或跨组织生态场景，需要进一步增加签名、审计保留、供应链证明、跨域授权和合规评估。