SpecKit 发布器

解决什么问题

在基于 spec 的原型开发流程里，speckit-prototype 负责创建原型、体验评审和普通上传，但当原型通过门禁、需要以正式版本对外发布时，最常见的做法是手工拼一条 git push。这时典型的事故包括：manifest 中的产品名、版本号和 artifact_key 互相不一致就推上远端；凭据被写进 URL、日志或临时文件；为了「省事」顺手 --force，覆盖了同名但内容不同的已发布版本。

speckit-publish 就是为这一步设计的执行型技能。它不做诊断，不做性能分析，只做一件事：把一个已验证有效的 Frozen 快照安全地发布出去。

它如何工作

发布前必须完整读取四份契约文档：

• command.md：发布命令入口与参数约定
• references/release-package-contract.md：发布包结构与产物契约
• references/product-target-contract.md：产品目标契约
• references/ux-release-contract.md：体验发布契约

核心执行链路：

1. 本地校验优先：验证 Frozen 快照、源 manifest、产品路径、原型门禁和入口配置；任一不通过都不得触碰远端。
2. 发布路径锁定：路径必须是 ///，并保留外层 prototype/ 目录。
3. 凭据安全：通过 --credential-helper wincred 或 SPECKIT_GIT_CREDENTIAL_HELPER=wincred 走 Windows Credential Manager；发布器在同一进程内执行 git credential fill 预检，凭据不出现在 URL、参数、日志或 JSON 中。
4. 一次性前台执行：前台运行一次发布器，不并行启动第二次；stdout 为结构化 JSON，stderr 为阶段进度，退出码原样保留。
5. 退出码即语义：0 返回结构化结果；非零返回机器错误并停止，不在同轮内自行改参数重试。

结果中两种易混淆的状态：credential_status=Verified 表示凭据预检在同一上下文通过；url_status=Pending 仅表示静态托管地址暂不可验证，不代表 Git 发布失败。ALREADY_PUBLISHED_IDENTICAL 是成功结果，不重试；VERSION_CONFLICT 必须停下交给人决策——远端已存在同名但内容不同的版本。

适用边界与注意点

• 只管发布：原型创建、体验评审和普通上传归 speckit-prototype。
• 只认有效快照：校验失败即阻断远端访问，不会替你「顺手修一下」manifest。
• 凭据上下文敏感：CREDENTIAL_ACCESS_BLOCKED 意味着当前上下文拿不到 Windows Credential Manager，需换有权限的上下文重跑完整发布；只有 CREDENTIAL_NOT_FOUND 才是真的没有凭据。
• 大仓库与内网：可用 --partial-fetch 减少传输；用 SPECKIT_GIT_BIN 指定真实 Git 二进制而非 shim。
• 默认有界时间：Git 探针/凭据 60 秒、远端读取 60 秒、fetch/push 600 秒、URL 校验 30 秒，由 SPECKIT_PUBLISH_* 环境变量调整。
• 远端操作前需确认：仓库、分支、项目 ID、快照和静态站点配置；不 force push、不覆盖同名不同内容版本、不使用浏览器提交、不递归删除。