- 准备发布 channel（beta/mcp/plugin 等）或正式版到 npm
- 准备打 git tag
发版必须通过 CI 完成，不要本地手动 pnpm publish。
入口：GitHub Actions → Publish workflow（.github/workflows/publish.yml）→ Run workflow。
两种模式：
| 模式 | 用途 | 触发方式 |
|---|---|---|
| channel | 发 channel 版本到指定 dist-tag | 选 mode=channel，填 dist-tag 名称（如 mcp/plugin） |
| stable | 正式发版到 latest | 选 mode=stable，需 production environment 审批 |
- 在 GitHub 触发 Publish workflow，package 选
bailian-cli或knowledge-studio-cli，mode 选channel，channel 填 dist-tag 名（如mcp） - CI 自动：生成
0.0.0-beta-<sha7>-<date>版本号 → 临时 bump 对应包集合 → 自检 → 构建 → 发布到指定 dist-tag - 对应脚本：
tools/release/publish-channel.mjs
- 确保当前 release tooling 覆盖的包(
tools/release/lib/packages.mjs)已升到目标版本且一致;当前基础集合为packages/core/packages/runtime/packages/commands/packages/cli，knowledge-studio-cli发布会额外包含packages/kscli - 在 GitHub 触发 Publish workflow，package 选目标包集合，mode 选
stable - 需要 production environment 审批人批准
- CI 自动：自检 → 构建 → 发布到 latest → 打 git tag
- 对应脚本：
tools/release/publish-stable.mjs
两种模式都会先跑 check.mjs，覆盖以下检查：
| 检查项 | 说明 |
|---|---|
pnpm install --frozen-lockfile |
lockfile 一致性 |
| README 同步 | packages/cli/README.md 与根 README 一致 |
| 版本号一致 | tools/release/lib/packages.mjs 中待发布包集合 version 相同 |
workspace:* 替换 |
发布包间 workspace 依赖解析为真实版本号 |
| 构建 | 基础发布构建 core/runtime/commands 依赖和 cli;--knowledge 额外构建 knowledge-studio-cli |
| 生成资产 | 重建 skills/bailian-cli/reference/;非 channel 模式还同步 skills/bailian-cli/SKILL.md version |
| pnpm pack | 打 tarball |
| publint | 包元数据校验 |
| gitleaks | 敏感信息扫描 |
本地可以 dry-run 验证：
node tools/release/publish-channel.mjs --channel test --dry-run
node tools/release/publish-channel.mjs --channel test --knowledge --dry-run- 认证：npm OIDC Trusted Publishing（无 token），需要
id-token: write权限 - Node 版本：24（npm 11.5+ 才支持 OIDC token 交换）
- Actions 版本：checkout/setup-node/pnpm-action 均为 v6（Node 24 兼容）
- npm 配置：当前 release tooling 发布的包(
bailian-cli-core/bailian-cli-runtime/bailian-cli-commands/bailian-cli/knowledge-studio-cli)的 Trusted Publisher 指向modelstudioai/cli的publish.yml;新增发布包时同步 npm Trusted Publisher
-
tools/release/lib/packages.mjs覆盖的目标包集合已升到目标版本且一致 - 源码包
packages/core/package.json、packages/runtime/package.json、packages/commands/package.json、packages/cli/package.json、packages/kscli/package.json是否需要同步升版已人工确认;当前仓库通常保持五包版本一致 -
tools/release/lib/packages.mjs的PACKAGES覆盖基础发布包;KSCLI_PACKAGE/ALL_PACKAGES覆盖knowledge-studio-cli发布路径;如果新增发布包,同步publish-stable.mjs/publish-channel.mjs的 bump、publish、idempotency 逻辑和.github/workflows/publish.yml的 package 选项 - pre-release 格式正确（
1.0.0-beta.0/1.0.0-rc.1，不要直接用1.0.0当 beta）
-
CHANGELOG.md和CHANGELOG.zh.md都已新增目标版本条目，中英文一一对应 - 分类标题用 Keep a Changelog 规范的
Added/Changed/Deprecated/Removed/Fixed/Security（中文版对应新增/变更/已弃用/已移除/修复/安全），不要自创Improved/优化等规范外分类 - 条目日期与发版日期一致
-
README.md/README.zh.md的 Quick Start 命令仍能跑通 - README 的 Node.js 徽章版本与
cli/package.json.engines.node一致 - README 宣传的 bin 名称在
cli/package.json.bin都真的注册 -
packages/kscli/README.md/README.zh.md与knowledge-studio-cli的 bin、控制台 URL、认证方式一致 -
LICENSE文件存在（根 + 当前实际发布包;新增发布包时补该包 LICENSE）
- 验证 npm 上能装：
npm view bailian-cli@<tag> version;如发布knowledge-studio-cli，同时npm view knowledge-studio-cli@<tag> version - 试装一次：
npm i -g bailian-cli@<tag> && bl --version;如发布knowledge-studio-cli，同时npm i -g knowledge-studio-cli@<tag> && kscli --version
| 漏点 | 后果 |
|---|---|
| 只升部分包,漏升 runtime/commands/kscli | 当前 check.mjs 按所选发布集合校验,但未选择 knowledge-studio-cli 时不会覆盖 kscli |
新增发布包但没加 tools/release/lib/packages.mjs |
CI 不会 bump/publish/校验该包 |
| cli 升版号但 core 没升 | check.mjs 会拦下 |
发版漏更 CHANGELOG，或分类写成规范外的 优化/Improved |
用户看不到本次变更，分类与历史不一致 |
1.0.0 当 beta 直接发 |
占了 latest tag，所有用户被强升，撤回成本极高 |
README 写的 bin 名实际 package.json.bin 没注册 |
用户复制命令报 command not found |
Node 徽章 >=18、engines >=22.12 不一致 |
用户在 Node 18 上 npm i 被 engine 警告或直接失败 |
| npm Trusted Publisher 的 workflow filename 改了没同步 | OIDC 匹配不上，publish 报 404 |
| CI 用 Node 22（npm 10）跑 publish | npm 10 不支持 OIDC token 交换，publish 报 404 |