mirror of https://github.com/modelstudioai/cli.git synced 2026-09-14 19:49:23 +08:00

Files

T

zeyu.fz 7bc1c49cb6 feat(release): 给 publish.yml 加 bailian-kb-dsh 通道

复用同一个 Publish workflow 入口（package 下拉多一项 bailian-kb-dsh），路由到
独立的 publish-kb-dsh.mjs 处理：
- 版本读自身 package.json（不广播全套 bl 版本）
- stable 打 bailian-kb-dsh-v<version> tag（与 bl 的 v<version> 错开命名空间）
- channel 临时 bump 到 0.0.0-beta-<sha>-<stamp>（形态与 bl channel 一致），
  finally 还原 package.json
- 走自身的 tsc + tsdown build，无 binary，无 OSS CDN
- 复用 lib/git.mjs / lib/npm.mjs / lib/proc.mjs 三个薄工具
- 复用 workflow 入口 UI 与 setup 步骤（checkout / pnpm / node 24 / gitleaks
  / install），stable 走 environment: production Required Reviewers gate

不复用 publish-stable.mjs / publish-channel.mjs：它们的 loadAndValidatePackages
会广播 core 版本给全套锁步包并强校验一致性，把 kb-dsh 塞进去第一步就 throw。
故意分开是为了保住这个隔离。

本地 --dry-run 端到端跑通：build → 幂等性查重 → pack + publint + gitleaks →
pnpm publish --tag latest|<channel> --provenance --dry-run；channel 模式的
finally 还原后 git diff 干净。

文档：dsh-plugin.md 补发布小节 + 已知待办（publint 那条 web bundle CJS/ESM
warning）；publish.md 加 bailian-kb-dsh 定位；packages.mjs 与 AGENTS.md 的
注释同步指向新的 job 与 script 名。

2026-08-24 15:44:19 +08:00

11 KiB

Raw Permalink Blame History

发布（npm + GitHub Release 二进制）

触发条件

准备发布 channel（mcp/plugin 等）或正式版到 npm 与 GitHub Releases 二进制
准备打 git tag（仅 stable）

发布方式：GitHub Actions 总入口

发版必须通过 CI 完成，不要本地手动 pnpm publish。

入口：GitHub Actions → Publish workflow（.github/workflows/publish.yml）→ Run workflow。

编排关系（重要）：

publish-stable.mjs / publish-channel.mjs   ← 唯一发版入口
        ├─ npm（pnpm publish）
        └─ binary（lib/binary-release
              → binary-build
              → gh-release
              → oss-direct-upload）

tools/release/lib/binary-release.mjs 等是实现，一般不要单独当发版入口（调试可用）。

bailian-kb-dsh（独立版本、npm-only）

同一个 Publish 入口，package=bailian-kb-dsh。它走单独的 tools/release/publish-kb-dsh.mjs，不复用 publish-stable.mjs / publish-channel.mjs（版本独立、无 binary、无 OSS CDN）。详见 dsh-plugin.md。

两种模式：

模式	用途	触发方式
channel	npm dist-tag +（仅 bailian-cli）二进制 + CDN 一律覆盖 `sync-release.json`	mode=channel，channel 填 npm dist-tag 名
stable	npm latest + GitHub Release `v<ver>` + CDN `manifest.json`（及 `latest.json` 别名）	mode=stable，需 production environment 审批

可选 flag：--skip-binary（仅发 npm，紧急逃生）。

CDN 滚动指针（bailian-cli）

发布模式	CDN 指针	本机安装 / 更新
channel	始终覆盖 `sync-release.json`	`BAILIAN_CHANNEL=sync-release` / `install --channel sync-release`
stable	`manifest.json`（+ `latest.json`）	默认安装 / `bl update`（无 channel）

workflow 的 channel 输入只决定 npm dist-tag（如 mcp / plugin / sync-release），不再生成 release-test.json 这类旁路文件。

channel 发布

在 GitHub 触发 Publish workflow，mode 选 channel，channel 填 npm dist-tag 名：
- bailian-cli：npm 发到该 tag；二进制同时刷新 CDN sync-release.json（与 tag 名无关）。本机验证：BAILIAN_CHANNEL=sync-release
- knowledge-studio-cli：仅 npm（自动跳过 binary，不碰 sync-release.json）
CI 自动：生成 0.0.0-beta-<sha7>-<YYYYMMDDHHMM>（UTC 到分钟；同 commit 同分钟重跑会覆盖同号）→ 临时 bump → 自检 → npm 发到 dist-tag →（bailian-cli）Bun 编二进制 + GH prerelease + 覆盖 sync-release.json → 还原 package.json
对应脚本：tools/release/publish-channel.mjs

stable 发布

确保当前 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 自动：自检 → npm 发到 latest → 推送 git tag v<ver> → Bun 编二进制并创建/更新 GitHub Release →（bailian-cli）维护 CDN manifest.json → 完成
如果所选发布集合的当前版本已全部存在于 npm，stable 发布会失败并提示先升级版本号；如果只有部分包已发布，CI 会继续补发缺失包
对应脚本：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/<skill>/reference/`;非 channel 模式还同步各 `skills/*/SKILL.md` version（含 `bailian-protocol`）
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

CI 基础设施

认证：npm OIDC Trusted Publishing（无 token），需要 id-token: write 权限
GitHub Release：contents: write + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}（stable / channel 均需）
Node 版本：24（npm 11.5+ 才支持 OIDC token 交换）
Bun：oven-sh/setup-bun，版本钉死在 workflow 中
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 明确报错并要求先升级版本号
channel job 缺少 `contents: write`	`gh release create` 失败
stable 未先推 tag 就建 Release	`--verify-tag` 失败

11 KiB Raw Permalink Blame History Unescape Escape