用途:把 @shadscan/cli 的一个新版本发布到 npm,包含版本号提升、CHANGELOG.md 与站点 changelog 条目、完整发布门禁、发布与发布后验证。预发布版本(形如 0.1.0-rc.N)发布到 npm 的 next 标签,稳定版经分阶段的 GitHub 工作流发布到 latest 标签。执行前须完整阅读 docs/releasing.md,它是所有者前置条件、门禁、可信发布与恢复流程的唯一依据;不得弱化或跳过其中门禁。
完成契约:一次发布对应一个严格更高、此前未发布过的版本,先用 npm view @shadscan/cli versions --json 确认不存在;已发布的名称/版本对不可变,修正只能向前发新版本,不能重发。发布完成需同时满足:目标版本以预期 dist-tag 上线、在干净目录用精确版本运行 --version 并执行真实审计、检查 dist-tag 映射正确、两处 changelog(根 CHANGELOG.md 与 changelog/<version>.md)均已提交推送。只从 packages/cli 发布,仓库根为私有 Next.js 应用不可发布。npm 2FA 属于所有者,可代为准备并运行发布命令,但不得绕过、脚本化或等待 2FA 提示,需把终端交给所有者完成。任一门禁失败即停止并报告确切失败项。
主要步骤:1)准备版本与 changelog:提升 packages/cli/package.json 版本;把根 CHANGELOG.md 的 Unreleased 内容移入 ## <version> - <YYYY-MM-DD> 小节(含 Added/Changed/Fixed/Security 分组)并保留空的 Unreleased;在 changelog/<version>.md 写带 frontmatter(version、date、channel、title、summary、highlights 3–5 条)的叙事条目;确认三处版本一致;检查 README 中声明的规则数量、BUNDLED_RULESET_VERSION 及测试中的硬编码计数。2)运行门禁:pnpm install --frozen-lockfile、pnpm check、pnpm docs:check、pnpm --filter ./packages/cli typecheck、pnpm cli:test、pnpm test:api、pnpm test:web、pnpm exec playwright install chromium、pnpm test:e2e、pnpm typecheck、pnpm audit:dependencies、pnpm audit:self、pnpm build、pnpm cli:smoke,以及 pnpm cli:release:check -- --tag next --git-tag "v${CLI_VERSION}"(稳定版改为 --tag latest 与对应稳定 Git 标签)。3)发布:预发布由所有者 npm login 确认身份后运行 (cd packages/cli && npm publish --tag next --access public) 并完成 2FA;稳定版按 docs/releasing.md 的分阶段流程(签名 Git 标签、GitHub release、工作流暂存产物、所有者检查后批准)。4)验证:npm view @shadscan/cli dist-tags --json 检查标签映射;用 npx --yes @shadscan/cli@<version> --version 验证精确版本,并在干净的 Next.js、Vite React、通用 React 项目做代表性审计,同一项目跑两次确认结果一致;确认站点 /changelog、/stats、/rules 反映发布。5)收尾:验证通过后才可宣布;稳定版将公开文档与 UI 中 @next 固定示例改为不带限定的命令。若发布损坏:把 dist-tag 回退到上一个可用版本,用 npm deprecate 标注坏版本并说明替代版本,向前修复;仅在安全或意外泄露时按策略 unpublish。限制:技能未说明具体价格或收费信息,暂未提供;其余平台与效果信息以仓库文档为准。