modelstudioai__cli/docs/agents/publish.md

发布（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，mode 选 channel，channel 填 dist-tag 名（如 mcp）
2. CI 自动：生成 0.0.0-beta-<sha7>-<date> 版本号 → 自检 → 构建 → 发布到指定 dist-tag
3. 对应脚本：tools/release/publish-channel.mjs

stable 发布

1. 确保当前 release tooling 覆盖的包(tools/release/lib/packages.mjs,现为 packages/core / packages/cli)已升到目标版本且一致;同时人工检查源码包版本(runtime / commands / rag)是否需要跟随
2. 在 GitHub 触发 Publish workflow，mode 选 stable
3. 需要 production environment 审批人批准
4. CI 自动：自检 → 构建 → 发布到 latest → 打 git tag
5. 对应脚本：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 相同（当前为 core + cli）
workspace:* 替换	发布包间 workspace 依赖解析为真实版本号
构建	当前 check 会构建 core + cli
pnpm pack	打 tarball
publint	包元数据校验
gitleaks	敏感信息扫描

本地可以 dry-run 验证：

node tools/release/publish-channel.mjs --channel test --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 发布的包(core + cli)的 Trusted Publisher 指向 modelstudioai/cli 的 publish.yml，environment 留空;新增发布包时同步 npm Trusted Publisher

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

版本号目标（仅 stable）

• tools/release/lib/packages.mjs 覆盖的包已升到目标版本且一致
• 源码包 packages/runtime/package.json、packages/commands/package.json、packages/rag/package.json 是否需要同步升版已人工确认;当前仓库通常保持五包版本一致
• tools/release/lib/packages.mjs 的 PACKAGES 覆盖所有本次实际要发布的包;如果新增发布包,同步 publish-stable.mjs / publish-channel.mjs 的 bump、publish、idempotency 逻辑
• 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 都真的注册
• LICENSE 文件存在（根 + 当前实际发布包;新增发布包时补该包 LICENSE）

完成后

• 验证 npm 上能装：npm view bailian-cli@<tag> version
• 试装一次：npm i -g bailian-cli@<tag> && bl --version

常见漏点（基于历史踩坑）

漏点	后果
只升 cli/core,漏升 runtime/commands/rag	当前 check.mjs 不一定拦下,但 workspace 发布会出现版本漂移
新增发布包但没加 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