用途
该技能用于设计或评审编码智能体 CLI 如何发布与演进，覆盖打包、安装渠道、自动更新策略、插件兼容性、缓存版本化、迁移策略以及本地占用管理。它关注的是运行时本身已经存在之后的产品化层。
主要能力
- 定义制品策略：决定 CLI 以什么形式发布、哪些内容内嵌、哪些内容动态加载。
- 设计安装渠道：明确 stable、beta、nightly、企业固定版本或托管分发等渠道。
- 有意识地做版本兼容：核心运行时、插件 API、缓存 schema、设置 schema 可能需要各自独立的兼容承诺。
- 将缓存视为带版本的状态：缓存失效应绑定 schema 与兼容边界，而不仅是应用版本。
- 规划安全迁移：在发布破坏性变更前定义升级、降级、回滚与部分更新行为。
- 约束本地占用：日志、缓存、会话状态、工具注册表、下载的集成都需要有界保留策略。
- 清理孤儿状态：旧插件版本与被弃用的缓存布局需要保留与垃圾回收规则。
- 发布期间保护用户信任：当插件损坏、缓存重置或会话迁移会实质影响行为时，应让用户可见。
- 测试升级路径：全新安装、原地升级、旧缓存启动、插件版本不匹配、回滚都应被演练。
使用方式
该技能提供快速参考表，按问题指向对应参考文档：
- 打包、更新与兼容性如何工作：阅读 references/packaging-updates-and-compatible-plugins.md，获得安装渠道、版本策略、插件兼容性与发布纪律。
- 缓存、迁移与本地状态如何安全演进：阅读 references/cache-migrations-and-install-channels.md，获得缓存键、迁移边界、回滚姿态与占用控制。
- OpenAI Codex 如何处理安装渠道、更新目标、app-server 包与 doctor：阅读 references/openai-codex-install-update-and-doctor.md，获得安装来源、更新目标检查、包变体与脱敏支持诊断。
默认工作流：定义制品策略；设计安装渠道；有意识地做版本兼容；将缓存视为带版本状态；规划安全迁移；约束本地占用；清理孤儿状态；发布期间保护用户信任；测试升级路径。
适用场景
- 为编码智能体 CLI 设计打包与分发。
- 添加自动更新渠道或受控发布策略。
- 审查插件兼容性与扩展版本策略。
- 建模本地缓存、迁移安全或安装占用变化。
- 决定发布工程如何处理破坏性运行时变更。
若需要插件清单与扩展架构，改用 ../ai-coding-agents-plugins/SKILL.md；若涉及设置与策略迁移，改用 ../ai-coding-agents-settings-policy/SKILL.md；若涉及会话状态兼容与恢复边界，改用 ../ai-coding-agents-sessions/SKILL.md；若需要更广泛的编码智能体架构，改用 ../ai-coding-agents/SKILL.md。
限制与注意事项
- 二进制版本、插件 API 版本与缓存 schema 版本是不同契约，不能混为一谈。
- 回滚是发布设计的一部分，不是事后修复。
- 当升级重置或使有意义的本地状态失效时，必须告知用户。
- 企业托管分发是一等操作模式，不只是不同标志。
- 安装占用增长必须有界且有人负责。
- 过时插件版本与缓存必须有明确的保留与清理规则。
- 常见失败模式包括：新二进制在旧缓存上启动导致静默损坏；插件损坏被“成功”的核心更新掩盖；回滚后迁移状态对旧版本不可读；部分更新中 helper、插件与核心协议不一致；日志、缓存或下载运行时长期增长且无保留策略；不同插件安装共享同一缓存身份并在升级中互相损坏。
- 已知陷阱：把二进制版本号当作唯一兼容信号；发布状态或缓存迁移却不规划降级；假设全新安装测试覆盖能证明升级安全；在不同安装来源、渠道或打包布局间复用同一缓存命名空间；把企业分发称为“同一构建加不同标志”；凭空编造或复制粘贴更新渠道/版本门控的键名与允许值，而不是核对当前厂商文档。
跨平台模式（Goose）
Goose 的分发模型在三个方面比 Claude Code 谱系更明确：白标自定义分发、OSS 风格安装脚本、基金会级治理。
自定义分发：Goose 支持 CUSTOM_DISTROS.md，即带有特定 provider、扩展、品牌与捆绑 recipe 的预配置构建。这不是同一二进制上的一个标志，而是具有收窄能力边界与内置策略的独立发布制品。模式：将自定义发行版视为与 stable/beta/nightly 平行的独立渠道类别。反模式：把企业或合作伙伴构建表示为“stable 渠道加一个配置文件”。Recipe：给每个自定义发行版一个 distro ID、固定的上游提交、recipe/扩展清单以及自己的更新策略。
安装脚本双重性与 OSS 安装面：Goose 提供 download_cli.sh 与 download_cli.ps1 作为规范 OSS 安装路径，与平台包管理器并存。模式：将安装脚本提交到仓库根目录，使用公开稳定 URL。反模式：依赖单一包管理器作为安装路径。Recipe：每个平台家族一个脚本（sh + ps1），各自带显式渠道标志、校验和验证以及面向企业自动化的无人值守安装模式。
治理与基金会级信任：Goose 在 Linux Foundation 下的 Agentic AI Foundation（AAIF）运作（创始贡献者 Block、Anthropic、OpenAI；2026 年 4 月 7 日转移；170+ 成员组织包括 AWS、Google、Microsoft 等；Apache-2.0 许可；有 GOVERNANCE.md、MAINTAINERS.md、SECURITY.md）。模式：将发布工程与治理分离。反模式：把“开源”当作单一复选框。Recipe：在发布渠道之外，发布 GOVERNANCE.md、MAINTAINERS.md、SECURITY.md 与 deny.toml（供应链门控）。
更新渠道、禁用自动更新与企业版本固定（Claude Code，2026-07-11 验证）
autoUpdatesChannel（用户设置，~/.claude/settings.json）只接受两个值："latest"（默认，最新发布）或 "stable"（大约落后一周，跳过有已知重大回归的发布）。没有 "disabled"、"none" 或 "off" 值。要真正停止自动更新，需设置 DISABLE_AUTOUPDATER 环境变量。渠道选择与更新终止开关是两个不同控制。
requiredMinimumVersion 与 requiredMaximumVersion 是仅限托管设置的字段（MDM 或系统 managed-settings.json，绝不在用户/项目设置中），在声明范围之外会完全阻止启动。对比更早的 minimumVersion，它是软下限，通过 claude update/自动更新阻止降级，但不阻止已在旧构建上的用户启动 Claude Code。
失效开放细节：无效或格式错误的 requiredMinimumVersion/requiredMaximumVersion 值会被剥离而非强制执行——错误策略推送不会意外锁死整个机群。设计自己的硬版本门控时也应如此：在设置点验证门控值，运行时对格式错误门控的响应是“忽略并记录”，绝不是“拒绝启动”。
模式：用 requiredMinimumVersion 强制安全补丁下限，用 requiredMaximumVersion 在合规期内冻结发布；对希望减少回归而非硬冻结版本的团队使用 autoUpdatesChannel: "stable"；仅当独立发布流程（镜像烘焙、黄金 AMI、离线安装）已拥有版本时才使用 DISABLE_AUTOUPDATER。反模式：需要硬阻止时使用 minimumVersion，或假设渠道设置也会禁用更新。Recipe：在企业设置文件中记录当前固定范围与渠道选择以及最后验证日期。
桌面运行时升级：Electron 到 Tauri（Goose 2.0，2026 年 4 月）
Goose 2.0 正将桌面应用从 Electron 迁移到 Tauri。旧（Electron）与新（Tauri）桌面客户端都与共享 ACP 守护进程通信，而不是捆绑独立运行时。该迁移是自定义分发运营者的案例研究：分发制品改变（应用包、二进制大小、操作系统信任签名），但协议契约（ACP）保持稳定。旧桌面构建上的用户仍可与新守护进程交互；表面变化是 UI，不是协议。模式：迁移桌面运行时前先稳定守护进程协议。分发渠道随后将新 UI 作为与守护进程分离的升级路径发布。