Appearance
发布、版本与插件治理
插件版本不是一条普通操作日志，而是一次发布时生成的稳定配置快照。工作流、智能体和正式运行链路会记录或使用具体版本号，因此发布前要同时检查工具契约、运行状态、版本说明和已有引用。
图 1：插件详情页提供发布、历史和版本快照入口。历史列表按发布时间倒序排列，单击版本记录可查看该次发布保存的插件与工具快照。
当前版本机制
| 项目 | 当前规则 |
|---|---|
| 版本生成 | 每次普通发布生成一条发布版本和一份快照，不再区分旧文档中的“发布版本”和“提交版本” |
| 最新版本 | 按版本记录的创建时间倒序取最近一次发布，不按版本号数值大小比较 |
| 版本号 | 必填；同一插件内不可重复；普通详情页最多 40 个字符 |
| 版本描述 | 必填；普通详情页最多 800 个字符 |
| 个人信息声明 | 必填，只能选择“收集、传输个人信息”或“不收集、传输个人信息” |
| 历史详情 | 支持查看版本号、描述、发布时间、发布人、个人信息声明，以及插件和工具快照 |
| 历史版本运行 | 正式运行使用具体版本号读取对应快照，不接受 latest、published 等模糊版本标识 |
| 回滚 | 当前没有插件版本回滚接口，也没有从历史版本一键恢复为草稿的入口 |
版本号怎么填写
平台目前只校验版本号非空、长度和同插件内唯一性，没有强制校验语义化版本格式。为了便于排序和沟通，建议统一使用 v主版本.次版本.修订号，例如 v1.2.0：
- 仅修复实现且不改变契约：递增修订号，如
v1.2.0 → v1.2.1。 - 新增向后兼容的工具或可选字段：递增次版本号，如
v1.2.1 → v1.3.0。 - 删除字段、修改类型或产生其他不兼容变更：递增主版本号，如
v1.3.0 → v2.0.0。
普通插件详情页首次发布默认填写 v0.0.1；如果最近一次发布记录使用标准 vX.Y.Z 格式，页面会自动递增修订号。自动填写只是建议值，最终仍需确认是否与变更级别匹配。
Cloud IDE 的版本号预填
Cloud IDE 发布页当前每次进入版本步骤都会预填 v0.0.1，不会根据历史记录自动递增。首次发布后再次发布时，请手工改成未使用的版本号，否则会因版本号重复而失败。为兼容普通发布入口，版本号和版本描述仍建议分别控制在 40 和 800 个字符内。
四种插件的发布差异
四种插件都会形成插件版本记录，但发布前置条件和完成时点不同。
| 插件形态 | 发布方式 | 版本完成条件 | 快照重点 |
|---|---|---|---|
| 云侧插件：已有服务 | 同步发布 | 发布请求成功 | 插件连接配置、鉴权配置、工具定义、输入输出参数、示例和状态 |
| 云侧插件：Cloud IDE | 异步构建发布包 | 构建任务成功后才写入发布版本并上线 | 插件和工具快照，以及与该版本绑定的生产发布包和构建结果 |
| 端插件 | 同步发布 | 发布请求成功 | 端插件元数据、工具和参数契约；客户端安装包与设备部署不在快照恢复范围内 |
| MCP 插件 | 同步发布 | 当前页面要求先有工具；启用工具还必须通过定义校验 | 当前已保存的 MCP 工具、Schema 和参数，不会在发布动作中重新连接服务端同步工具 |
Cloud IDE 发布前还必须满足：至少有一个启用工具、每个启用工具都有入口文件且调试通过、依赖全部安装完成。单击发布后先进入“发布中”，只有生产包构建成功才形成可用版本；任务失败或取消时不能把它当作已发布版本使用。
MCP 插件发布的是页面中已经保存的工具集合。需要获取服务端最新工具时，应先执行工具同步、核对新增和下线项，再发布新版本。启用工具只要有一个未完成定义校验，普通发布就会被拒绝。后端发布能力允许生成空工具版本，但当前详情页在工具为空时会禁用发布按钮，因此正常操作应先完成工具同步。
发布前检查
- 插件名称、说明、头像和插件形态正确。
- 服务地址、Header、Service Token 或 OAuth 配置在目标环境可用。
- 用户授权 Schema 已使用真实账号验证；版本的个人信息收集声明与实际行为一致。
- 计划开放的工具已经启用并完成最小参数试运行。
- 输入输出契约与真实响应一致，字段类型、必填项、枚举和示例没有过期。
- MCP 工具已先同步并核对；Cloud IDE 代码已保存、依赖安装完成、启用工具全部调试通过。
- 版本号没有使用过，版本描述写清新增工具、契约变化、修复内容、迁移方式和已知影响。
- 已确认工作流、智能体、快捷指令和市场分发中的既有版本引用不会被误判为已经升级。
版本快照包含什么
普通发布会把发布时的插件配置和工具列表写入版本快照，包括插件类型、连接方式、工具状态、工具定义、输入输出参数和示例等信息。鉴权快照只保存鉴权结构和脱敏状态，不保存可直接读取的明文 Token 或 Client Secret。工具的卡片绑定属于独立配置，不在当前插件版本快照中。
Cloud IDE 的内部版本数据还会关联生产发布包和构建结果；当前详情页的“版本快照”抽屉主要展示插件名称、描述、工具和参数数量，不等同于完整的包管理界面。
发布后继续编辑当前插件，不会修改已经生成的历史快照。当前实现中，不是所有编辑动作都会立即把顶部状态改成“未发布”，因此不能只根据状态标签判断当前配置是否与最新快照完全一致。重要修改完成后应重新试运行，并使用新版本号再次发布。
查看发布历史
- 进入插件详情页。
- 单击右侧“历史”入口。
- 在按时间倒序排列的版本列表中选择一条发布记录。
- 在“版本快照”中核对版本号、描述、发布时间、发布人、个人信息声明和工具配置摘要。
这与旧平台文档存在明显差异：旧文档写明“暂不支持查看某个历史版本的插件工具配置详情”，当前后端已经能够读取完整版本快照，详情页也会展示插件名称、说明、工具名称、工具说明和输入参数数量；但页面暂未展开全部参数 Schema、示例和 Cloud IDE 包信息。旧文档中的“同时生成发布版本和提交版本”也不适用于当前实现。
工作流和智能体如何引用版本
当前资源选择器添加插件工具时，读取插件最近一次发布的具体版本号，并把该版本号写入节点或智能体草稿。正式运行再按这个具体版本读取快照，而不是临时解析“最新版本”。
因此需要注意：
- 插件发布新版本后，已有工作流节点和智能体草稿不会被自动改写。
- 当前选择器默认提供最近一次发布版本，没有从插件历史中任选版本的选择器。
- 当前没有统一的“一键升级全部引用”入口；需要升级时，应在调用方重新选择插件工具，并重新检查输入映射、输出引用和异常处理。
- 同一工作流中多个节点可能保存不同时间绑定的版本，升级时要逐个核对，不能只检查其中一个节点。
- 市场或企业分发准备阶段未指定版本时可以解析最近一次发布版本，但进入正式运行配置后仍应保存具体版本号。
旧平台文档中“智能体始终自动使用最新版本”的规则不适用于当前代码：当前智能体工具草稿也要求保存具体插件版本，并拒绝使用 latest、published、latest_published 作为正式绑定版本。
兼容变更
| 变更 | 风险 | 推荐处理 |
|---|---|---|
| 新增可选字段 | 较低 | 更新描述和示例，发布次版本并重新试运行 |
| 新增必填字段 | 高 | 先提供默认值或新工具，再迁移调用方 |
| 字段改名、删字段、改类型 | 高 | 保留兼容字段或发布主版本，逐个迁移现有引用 |
| 收紧枚举、改变单位 | 高 | 新增明确字段，保留过渡期并更新变量映射 |
| 修改工具名称或描述 | 中 | 重新验证模型选工具效果；不要只做文本检查 |
| 修改外部服务行为但不改 Schema | 高 | 仍应发布新版本，并在版本描述中说明行为变化 |
没有回滚按钮时如何处理
当前版本历史可用于查看和运行已绑定快照，但不能直接把某个历史版本恢复为当前草稿，也不能覆盖普通用户已经发布的同名版本。需要恢复旧行为时：
- 打开目标历史版本，核对插件和工具快照。
- 手工把当前插件配置、工具契约和外部服务调整到目标行为。
- 完成连接验证和试运行。
- 使用一个全新的版本号发布，例如将恢复版本发布为
v1.4.1，不要再次使用旧版本号。 - 在需要恢复的工作流和智能体中重新绑定这个新版本，并验证变量映射。
即使已有调用方继续绑定旧版本，版本快照也不能回滚外部服务、MCP Server、OAuth 应用、Cloud IDE 之外的部署产物、端插件客户端或设备权限。旧版本能否继续正确运行，仍取决于这些外部依赖是否保持兼容。
启用、停用、删除与分发
- 停用工具适合阻止新调用，但仍要关注运行中的任务和已保存版本引用。
- MCP 工具由服务同步时，先核对远端删除、重命名和 Schema 变化，再发布。
- 删除工具前查看智能体、工作流和快捷指令中的具体版本依赖。
- 删除插件会影响其中全部工具；插件已发布到商店时，必须先下架才能删除。
- 复制到其他工作空间会形成独立资源，目标空间需要重新检查鉴权、网络、Cloud IDE 构建包、端插件部署和最小参数试运行。
- 市场或企业渠道分发应明确资源版本；安装后仍需在目标空间检查授权和工具可用性。
推荐的下线顺序是：新增替代工具 → 发布新版本 → 迁移调用方 → 停用旧工具 → 观察运行记录 → 删除旧工具。
更多定位方法参见插件常见问题。