ai-delivery-workflow 0.2.2 → 0.4.0

package/docs/NPM-RELEASE-MANAGEMENT.zh-CN.md

@@ -0,0 +1,106 @@
+# npm 版本与发布管理规范
+
+本文约束 `ai-delivery-workflow` 维护仓库的 npm 版本和发行，不描述安装后业务项目的研发版本或生产发布状态机。npm 包、Git 提交和 Git Tag 必须能够相互追踪；已经公开的版本和 Tag 不得改写。
+
+## 1. 权威身份
+
+- `package.json` 的 `version` 是待发布或最近发布的 npm 版本，`package-lock.json` 必须同步。
+- Git Tag 固定使用 `v<version>`，例如 `v0.2.2`，并指向包含该版本号的唯一发行提交。
+- npm 官方仓库 `ai-delivery-workflow@<version>` 是公开制品身份；版本一经发布即不可复用。
+- `latest` 只指向稳定版本。预发布版本使用 `x.y.z-beta.n`、`x.y.z-rc.n` 和 `next` 等非 `latest` dist-tag。
+- `main` 可以在发布后继续包含未发布变更；只有完成本文门槛后才能声称某个提交已经发行。
+
+## 2. 版本选择
+
+采用 SemVer，并对 `0.x` 阶段使用更严格的兼容约束：
+
+| 变更 | 版本规则 | 示例 |
+| --- | --- | --- |
+| 修复缺陷、补充验证或文档，且不改变公开契约 | PATCH | `0.2.2` -> `0.2.3` |
+| 新增向后兼容能力、命令或 Skill | MINOR | `0.2.x` -> `0.3.0` |
+| CLI、状态 schema、Hook 协议、安装结构或 Skill 上下游契约发生不兼容变化 | `0.x` 阶段至少 MINOR，并提供迁移说明；`1.0.0` 后使用 MAJOR | `0.3.x` -> `0.4.0` |
+
+自动迁移能够完整保留既有物料时可视为兼容；需要用户手工改文件、丢弃状态或改变已有命令语义时属于不兼容变更。安装清单 schema、正式状态 schema 和 npm 版本是不同身份，不得互相替代。
+
+## 3. 发布前门槛
+
+发布必须从干净、已同步的 `main` 开始。不得从临时工作区、审计远程或业务项目发布。依次完成：
+
+```powershell
+npm run release:check -- prepare --version <version>
+git diff --check
+```
+
+`release:check prepare` 以结构化 JSON 一次执行并汇总版本、Git、全量测试、Skill、审计、打包、官方 registry、版本占用、npm 身份和 2FA 门槛。正式发布必须使用默认 `full` scope；`--scope local` 只用于离线回归测试，不能替代发布门槛。完整字段见[维护仓库验证工具](MAINTENANCE-VERIFICATION.zh-CN.md)。
+
+该命令内部必须实际执行 `npm test`、`npm run skills:validate`、`npm run audit:verify` 和 `npm publish --dry-run`；结构化汇总不能用静态声明替代这些命令。
+
+发布预检必须使用 `npm publish --dry-run`，不能只依赖 `npm pack --dry-run`；前者还会执行 npm 的发布规范化检查。输出不得包含 `auto-corrected`、`invalid and removed`，并必须确认：
+
+- 包名、版本、文件数量和制品摘要符合预期；
+- `bin.ai-delivery` 为 `bin/ai-delivery.mjs`，文件以 Node shebang 开头；
+- `bin/`、`lib/`、`skills/` 和 `docs/` 均进入制品；
+- `.tmp/`、`verification/`、`audit/`、凭据和本地日志不进入 npm 包。
+
+版本号使用以下命令同步到两个清单文件：
+
+```powershell
+npm version <version> --no-git-tag-version
+```
+
+修改后必须重新执行全部门槛。禁止先发布、后补测试或文档。
+
+## 4. Git 与 npm 发布顺序
+
+1. 提交通过验证的发行内容，并把发行提交推送到 `origin/main`。
+2. 确认远程不存在同名 Tag，在发行提交上创建本地签注 Tag `v<version>`。
+3. 使用官方仓库登录身份和发布级 2FA 执行 `npm publish --access public`。
+4. 从官方仓库回读版本、dist-tag、CLI、repository 和完整性摘要。
+5. 安装精确版本并执行 `ai-delivery --version` 冒烟验证。
+6. npm 验证通过后推送 Git Tag。若团队要求先公开 Git Tag，则 npm 发布失败后不得改写该 Tag，修复必须使用新的 PATCH 版本。
+
+Git Tag 和 npm 版本必须指向同一发行内容。不得删除远程 Tag 后复用版本，也不得把可移动 branch head 当作发行身份。
+
+## 5. 认证与凭据
+
+- 发布前执行 `npm whoami --registry=https://registry.npmjs.org/`，确认账号正确。
+- 交互发布必须启用 `auth-and-writes` 2FA，并使用 npm 的一次性网页认证或 OTP。
+- 密码、OTP、恢复码和 npm token 不得写入仓库、`.tmp/` 审计物料、命令日志或对话文档。
+- CI 只能使用最小权限、限定包、可过期的 granular access token；只有发布任务需要时才允许 bypass 2FA，并存入 CI secret store。
+- `publishConfig.registry` 必须固定为 `https://registry.npmjs.org/`，避免把正式包发布到本地镜像。
+
+## 6. 失败处理
+
+| 场景 | 处理 |
+| --- | --- |
+| npm 在创建版本前拒绝发布 | 修复原因并重新执行全部门槛；若远程 Tag 已存在，递增 PATCH，不改写 Tag。 |
+| npm 已发布但 Tag 推送失败 | 保留 npm 版本，重试把同一发行提交的 Tag 推送到远程；不得重新发布。 |
+| 发布后发现普通缺陷 | 发布新的 PATCH；不得覆盖或复用旧版本。 |
+| 发布后发现严重安全或安装问题 | 经人工确认后使用 `npm deprecate` 标注并立即发布修复版；只有满足 npm 官方撤回政策时才考虑 unpublish。 |
+| `latest` 指向错误版本 | 核对制品后显式修正 dist-tag，不重新打包同一版本。 |
+| 2FA 或权限失败 | 保持源码和 npm 状态不变，完成账号授权后重试；不得把令牌写入项目配置。 |
+
+任何失败都要先用 `npm view ai-delivery-workflow@<version>` 确认版本是否真正创建，再决定重试或递增版本。
+
+## 7. 发布后验证
+
+```powershell
+npm run release:check -- verify --version <version> --commit <40位发行提交ID>
+npm view ai-delivery-workflow@<version> version dist-tags bin repository homepage --json --registry=https://registry.npmjs.org/
+npm install --prefix .tmp/npm-smoke-<version> --no-save --package-lock=false ai-delivery-workflow@<version> --registry=https://registry.npmjs.org/
+.\.tmp\npm-smoke-<version>\node_modules\.bin\ai-delivery.cmd --version
+```
+
+POSIX 环境使用对应的 `.bin/ai-delivery`。验证结果必须满足：精确版本可安装、`latest` 符合发布意图、CLI 返回相同版本、Git Tag 指向发行提交、维护仓库工作区干净。
+
+公开 `npx` 入口还必须从维护仓库及其子目录之外执行一次：
+
+```powershell
+Push-Location C:\tmp
+npx --yes --registry=https://registry.npmjs.org/ ai-delivery-workflow@<version> --version
+Pop-Location
+```
+
+npm 会向父目录查找 `package.json`；如果在本维护仓库或 `.tmp/` 子目录执行同名包，可能把当前源码误认为已经安装并跳过临时安装，产生假的“命令不存在”。仓库外消费目录才代表用户的真实 `npx` 路径。
+
+本规范属于维护仓库发行规则，不写入[安装目标模板](../skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md)。维护入口和其他仓库边界见[完整项目手册](PROJECT-MANUAL.zh-CN.md)。