fable-release

Fable 发布

证明用户将收到的确切提交和制品已准备就绪，然后区分就绪状态与实际分发。

使命

发布是一次外部状态转换。即使源码测试全部通过，软件包仍可能遗漏文件、标签可能指向另一个提交、注册表可能仍提供旧版本，或者已发布的制品可能无法在干净环境中启动。

此 Skill 将发布声明与确切的版本、提交、制品、工作流、标签和注册表证据关联起来，以弥合这一差距。

适用时机

• 准备将分支合并，或准备发布某个版本；
• 创建／推送版本标签；
• 发布 npm／软件包／插件制品；
• 完成 GitHub Release；
• 验证分发渠道是否确实提供目标版本；
• 评估最后一刻的更改后，发布证据是否仍然有效。

不适用时机

• 实现仍在变更（fable-execute／fable-tdd）；
• 功能验证尚未完成（fable-verify）；
• 仍有阻塞性的审查／安全问题；
• 用户尚未授权不可逆的发布操作。可以执行就绪检查；实际发布必须获得相应授权。

发布分类

发布类型	额外关注事项
仅合并	分支／基线是否为最新、必要的 CI、审查
软件包注册表	软件包内容、干净安装、注册表验证
Git 标签／GitHub Release	标签→SHA 绑定、说明／资源、草稿／预发布状态
插件／市场	清单／版本一致性、提交／审批状态
带迁移的发布	推出顺序、向后兼容性、回滚
安全敏感型发布	公告／密钥／依赖项门禁、披露限制

协议

阶段 1 — 冻结候选版本

确定确切的候选版本：

• 版本；
• 提交 SHA；
• 目标分支／标签；
• 分发渠道；
• 必要的 CI／审查／安全证据。

此后任何源码／配置／软件包变更都会使相关发布证据失效，并产生新的候选版本。

阶段 2 — 验证版本语义

检查：

• 目标注册表／标签命名空间中尚不存在该版本；
• SemVer 与实际兼容性影响相符；
• 所有规范版本位置／清单保持一致；
• 更新日志／发布说明准确描述用户可见的更改；
• 预发布状态符合预期。

不要仅仅为了方便选择补丁／次要／主要版本号。

阶段 3 — 重新确认最新质量门禁

验证必要的功能／构建／审查／安全证据对应候选 SHA／变更代次。如果证据是在候选版本变更之前生成的，请重新运行。

• 如可用，通过 no-mistakes 代理路由分支推送（git push no-mistakes 或 no-mistakes axi run），确保在远程合并前通过 rebase、自动审查、测试、lint 和文档检查。

阶段 4 — 检查制品边界

构建／试运行确切的制品，并检查其清单／内容。

检查：

• 必需的入口点／资源／清单均已包含且非空；
• 除非有意公开，否则应排除密钥、临时文件、测试／夹具／内部保留文件；
• 生成的文件为最新版本；
• 可执行权限／导出项／bin 路径正确；
• 依赖项／运行时约束准确。

阶段 5 — 在干净环境中进行冒烟测试

在源码检出目录之外安装／使用生成的制品（条件允许时）。

至少验证：

• 安装成功；
• 主可执行文件／导入项可正常解析；
• 版本／帮助／基本冒烟测试正常；
• 文档中的快速入门路径不会意外依赖仓库本地文件。

阶段 6 — 验证仓库发布状态

发布前：

• 候选提交已推送；
• 候选版本的必要 CI 检查已通过；
• 标签不存在，或已准确指向目标 SHA；
• 发布说明／资源对应同一标签／SHA；
• 相对于基线，分支没有已知问题。

阶段 7 — 仅通过获授权的安全路径发布

优先使用已配置的可信发布／OIDC／自动化主机，而不是引入长期有效令牌。

不要打印或存储凭据，也不要为了让发布通过而削弱安全性。

如果缺少授权或身份验证，请停在 READY_NOT_PUBLISHED，并准确说明剩余操作。

阶段 8 — 独立验证分发

发布后，查询外部目标，而不是盲目信任发布命令。

验证示例：

• 注册表报告预期的版本／分发元数据；
• 从注册表全新安装成功；
• Git 标签解析到候选 SHA；
• GitHub Release 确实公开，而非草稿；
• 市场状态显示已提交／已发布。

阶段 9 — 发布后冒烟测试与交接

通过公开分发渠道运行面向用户的安装／调用流程。记录发现的回滚／弃用／后续问题。

发布结论

• NOT_READY：必需的确定性／审查／安全／制品关卡未通过。
• READY_NOT_PUBLISHED：候选版本可靠，但未获授权／无法发布／未请求发布。
• PUBLISHED_UNVERIFIED：发布命令／工作流声称成功，但尚未通过独立验证确认外部分发。
• RELEASED：确切的候选版本已通过预期渠道公开发布，并经独立验证。

不要把这些状态一概称为“完成”。

决策规则

• 如果明确说明工作区中的未提交改动无关，且发布制品来自干净的候选 SHA，则工作区不干净不会自动导致失败；但未提交的发布改动会导致就绪检查失败。
• 标签存在但指向不同的 SHA → 立即停止；切勿轻率移动／强制更新发布标签。
• 软件包版本已存在于不可变注册表中 → 选择新的有效版本，不要覆盖。
• 试运行内容与预期公开内容不同 → 在打标签／发布前修正软件包配置。
• 从仓库链接进行本地全局安装有效，但干净的 tarball／注册表安装失败 → NOT_READY。
• 较旧提交上的 CI 通过 → 发布证据已过时。
• GitHub Release 是草稿 → 不能作为公开发布的证据。
• 发布工作流通过，但注册表尚未更新 → 在独立确认或已知的传播策略问题解决前，保持 PUBLISHED_UNVERIFIED。
• 市场要求人工审批 → 如实报告提交状态；绝不声称已发布。

不变量

• 发布版本、提交、标签、制品和公开元数据均指向同一个候选版本。
• 不得将凭据提交或记录为发布证据。
• 不可逆的外部写入需要适用的授权。
• 公开发布声明须经外部验证。
• 最后时刻的变更会使过时的候选版本证据失效。
• 发布说明不得声称未经最新证据支持的成熟度／功能。

故障分类

制品缺失／污染

软件包缺少运行时文件或包含机密／内部材料。修正边界，重新构建并重新执行冒烟测试。

版本不一致

清单／变更日志／CLI／标签不一致。发布前协调一致。

候选版本变更

发布提交变更后，CI／证据仍指向较旧的 SHA。重新运行关卡。

标签不匹配

现有标签指向其他位置。停止；先调查，不要强制移动标签。

发布／身份验证失败

候选版本可能保持 READY_NOT_PUBLISHED。诊断安全身份验证／工作流问题，不要嵌入凭据。

注册表／发布不匹配

发布报告成功，但公开渠道提供的是错误／旧制品。保持 PUBLISHED_UNVERIFIED 并调查。

干净安装失败

制品依赖仓库本地文件／开发环境状态。无论源代码测试结果如何，均为 NOT_READY。

反模式

• “测试通过，就发布”；
• 未检查制品内容就创建标签；
• 仅将源代码检出作为安装测试；
• 强行移动标签；
• 在配置或文档中添加令牌以绕过可信发布；
• 将草稿发布等同于公开发布；
• 未查询注册表或发布页面就相信工作流成功；
• 未经公开验证就更新文档，声称内容已可用；
• 行为证据已过时，却声称成熟度达到 100%。

发布证明

Version:
Candidate SHA:
Target channels:
Fresh quality gates:
Artifact manifest check:
Clean-install smoke:
Tag → SHA:
GitHub Release state:
Registry/marketplace state:
External verification:
Verdict: NOT_READY | READY_NOT_PUBLISHED | PUBLISHED_UNVERIFIED | RELEASED
Rollback/follow-up:

完成标准

当请求的发布阶段得到准确证明时，Skill 的工作即告完成：

• 就绪声明与确切的候选版本证据相关联；
• 在适用情况下，已证明制品边界和全新安装；
• 标签、发布状态和注册表状态一致；
• 在标记为 RELEASED 之前，已独立验证公开分发；
• 缺失的授权或外部关卡明确表示为状态，绝不凭猜测补全。

渐进式资源

• 深入指南：references/artifact-and-distribution-verification.md
• 现有发布关卡：references/release-gates.md
• 示例：examples/release-readiness-audit.md