# 发布（npm publish）

## 触发条件

- 准备发布 channel（beta/mcp/plugin 等）或正式版到 npm
- 准备打 git tag

## 发布方式：GitHub Actions + npm OIDC

发版**必须**通过 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 审批     |

### channel 发布

1. 在 GitHub 触发 Publish workflow，package 选 `bailian-cli` 或 `knowledge-studio-cli`，mode 选 `channel`，channel 填 dist-tag 名（如 `mcp`）
2. CI 自动：生成 `0.0.0-beta-<sha7>-<date>` 版本号 → 临时 bump 对应包集合 → 自检 → 构建 → 发布到指定 dist-tag
3. 对应脚本：`tools/release/publish-channel.mjs`

### stable 发布

1. 确保当前 release tooling 覆盖的包(`tools/release/lib/packages.mjs`)已升到目标版本且一致;当前基础集合为 `packages/core` / `packages/runtime` / `packages/commands` / `packages/cli`，`knowledge-studio-cli` 发布会额外包含 `packages/kscli`
2. 在 GitHub 触发 Publish workflow，package 选目标包集合，mode 选 `stable`
3. 需要 production environment 审批人批准
4. CI 自动：自检 → 构建 → 检查 npm 已发布版本 → 发布到 latest → 打 git tag
5. 如果所选发布集合的当前版本已全部存在于 npm，stable 发布会失败并提示先升级版本号；如果只有部分包已发布，CI 会继续补发缺失包
6. 对应脚本：`tools/release/publish-stable.mjs`

## 自检（`tools/release/check.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 验证：

```sh
node tools/release/publish-channel.mjs --channel test --dry-run
node tools/release/publish-channel.mjs --channel test --knowledge --dry-run
```

## CI 基础设施

- **认证**：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

## `check.mjs` 不覆盖的（手动确认）

### 版本号目标（仅 stable）

- [ ] `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（仅 stable）

- [ ] `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 徽章与 `cli/package.json.engines` 不一致（当前应为 `>=18.17`） | 用户在声明外的 Node 上 `npm i` 被 engine 警告或直接失败                            |
| npm Trusted Publisher 的 workflow filename 改了没同步               | OIDC 匹配不上，publish 报 404                                                      |
| CI 用 Node 22（npm 10）跑 publish                                   | npm 10 不支持 OIDC token 交换，publish 报 404                                      |
| stable 发布前没有升级版本号                                         | 所选发布集合的版本已全部存在于 npm，CI 明确报错并要求先升级版本号                  |