Skip to content

Commit fddab1a

Browse files
XXPermanentXXXXPermanentXX
committed
docs: rewrite publish docs and rename release.md to publish.md
1 parent cdf2116 commit fddab1a

6 files changed

Lines changed: 101 additions & 104 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Skill / 命令手册不再随 npm 包发布,改由独立的 `npx add skills` 机
2929

3030
非代码资产:
3131

32-
- `tools/release.mjs` — 发版自动化
32+
- `tools/release/` — 发版自动化（CI 驱动，见 `.github/workflows/publish.yml`）
3333
- `tools/generate-reference.ts` — 从 `catalog.ts` 生成命令手册(临时输出到 `tools/generated/reference/`)
3434
- `README.md` / `README_CN.md` — npm 和 GitHub 主页
3535

@@ -55,7 +55,7 @@ Skill / 命令手册不再随 npm 包发布,改由独立的 `npx add skills` 机
5555
| URL / 渠道变更 | 控制台域名 / 文档站 / 追踪参数 | [docs/agents/url-change.md](docs/agents/url-change.md) |
5656
| 鉴权扩展 | 加 OAuth / SSO / 换 token 来源 | [docs/agents/auth-change.md](docs/agents/auth-change.md) |
5757
| 配置项扩展 | 新 env var 或 `~/.bailian/config.json` 字段 | [docs/agents/config-add.md](docs/agents/config-add.md) |
58-
| 发版前自检 | beta / rc / 正式发布到 npm | [docs/agents/release.md](docs/agents/release.md) |
58+
| 发布 | channel / stable 发布到 npm（CI 驱动） | [docs/agents/publish.md](docs/agents/publish.md) |
5959
| 工具链调整 | lint 规则 / 构建配置 / 依赖升级 | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md) |
6060

6161
如果当前任务无法对应任何场景,先按经验完成,然后**回来评估这是不是一类新场景** —— 是就新增一份 `docs/agents/<scenario>.md`,把清单沉淀下来。

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ bailian-cli/
1818
│ ├── cli/ # `bailian-cli` — CLI entry, commands, UI
1919
│ └── core/ # `bailian-cli-core` — auth, HTTP, types
2020
├── docs/agents/ # Scenario-based maintenance guides
21-
├── tools/ # Release & reference generation
21+
├── tools/ # Release automation & reference generation
2222
├── AGENTS.md # Contract for AI agents
2323
└── README.md
2424
```

‎CONTRIBUTING_CN.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ bailian-cli/
1818
│ ├── cli/ # `bailian-cli` —— CLI 入口、命令、UI
1919
│ └── core/ # `bailian-cli-core` —— 鉴权、HTTP、类型
2020
├── docs/agents/ # 场景化维护文档
21-
├── tools/ # 发版与命令手册生成
21+
├── tools/ # 发版自动化与命令手册生成
2222
├── AGENTS.md # AI agent 维护契约
2323
└── README.md
2424
```

‎docs/agents/changelog-write.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -176,11 +176,11 @@ git show <commit> --stat
176176
| 版本号 bump commit 自身的 README 改动算进上个版本 | 重复 / 错位 |
177177
| 中英两份不同步 | 文档可信度直接崩,等同于撒谎 |
178178

179-
## 与 release.md 的边界
179+
## 与 publish.md 的边界
180180

181-
| 文档 | 管什么 |
182-
| ------------------------ | ---------------------------------------------------- |
183-
| [release.md](release.md) | 发版前自检:版本号 / 包内容 / 安全扫描 / publish 流程 |
184-
| 本文档 | 发版后写说明:面向用户的 release notes |
181+
| 文档 | 管什么 |
182+
| -------------------------- | ---------------------------------------------------- |
183+
| [publish.md](publish.md) | 发布流程:自检 / 构建 / npm publish（CI 驱动） |
184+
| 本文档 | 发版后写说明:面向用户的 release notes |
185185

186-
两者顺序:`release.md` → npm publish → 本文档(更新 `CHANGELOG.md` + `CHANGELOG_CN.md`)→ 推到 GitHub。
186+
两者顺序:`publish.md` → npm publish → 本文档(更新 `CHANGELOG.md` + `CHANGELOG_CN.md`)→ 推到 GitHub。

‎docs/agents/publish.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# 发布（npm publish）
2+
3+
## 触发条件
4+
5+
- 准备发布 channel（beta/mcp/plugin 等）或正式版到 npm
6+
- 准备打 git tag
7+
8+
## 发布方式：GitHub Actions + npm OIDC
9+
10+
发版**必须**通过 CI 完成，不要本地手动 `pnpm publish`。
11+
12+
入口：GitHub Actions → **Publish** workflow（`.github/workflows/publish.yml`）→ Run workflow。
13+
14+
两种模式：
15+
16+
| 模式 | 用途 | 触发方式 |
17+
| ------- | ----------------------------- | ------------------------------------------------- |
18+
| channel | 发 channel 版本到指定 dist-tag | 选 mode=channel，填 dist-tag 名称（如 mcp/plugin） |
19+
| stable | 正式发版到 latest | 选 mode=stable，需 production environment 审批 |
20+
21+
### channel 发布
22+
23+
1. 在 GitHub 触发 Publish workflow，mode 选 `channel`，channel 填 dist-tag 名（如 `mcp`）
24+
2. CI 自动：生成 `0.0.0-beta-<sha7>-<date>` 版本号 → 自检 → 构建 → 发布到指定 dist-tag
25+
3. 对应脚本：`tools/release/publish-channel.mjs`
26+
27+
### stable 发布
28+
29+
1. 确保 `packages/cli/package.json` 和 `packages/core/package.json` 已升到目标版本且一致
30+
2. 在 GitHub 触发 Publish workflow，mode 选 `stable`
31+
3. 需要 production environment 审批人批准
32+
4. CI 自动：自检 → 构建 → 发布到 latest → 打 git tag
33+
5. 对应脚本：`tools/release/publish-stable.mjs`
34+
35+
## 自检（`tools/release/check.mjs`）
36+
37+
两种模式都会先跑 `check.mjs`，覆盖以下检查：
38+
39+
| 检查项 | 说明 |
40+
| ---------------------------- | ------------------------------------------- |
41+
| `pnpm install --frozen-lockfile` | lockfile 一致性 |
42+
| README 同步 | `packages/cli/README.md` 与根 README 一致 |
43+
| 版本号一致 | cli 与 core 的 version 字段相同 |
44+
| `workspace:*` 替换 | cli 对 core 的依赖解析为真实版本号 |
45+
| 构建 core + cli | `pnpm build` |
46+
| pnpm pack | 打 tarball |
47+
| publint | 包元数据校验 |
48+
| gitleaks | 敏感信息扫描 |
49+
50+
本地可以 dry-run 验证：
51+
52+
```sh
53+
node tools/release/publish-channel.mjs --channel test --dry-run
54+
```
55+
56+
## CI 基础设施
57+
58+
- **认证**：npm OIDC Trusted Publishing（无 token），需要 `id-token: write` 权限
59+
- **Node 版本**：24（npm 11.5+ 才支持 OIDC token 交换）
60+
- **Actions 版本**：checkout/setup-node/pnpm-action 均为 v6（Node 24 兼容）
61+
- **npm 配置**：两个包的 Trusted Publisher 都指向 `modelstudioai/cli` 的 `publish.yml`，environment 留空
62+
63+
## `check.mjs` 不覆盖的（手动确认）
64+
65+
### 版本号目标（仅 stable）
66+
67+
- [ ] `packages/cli/package.json` 和 `packages/core/package.json` 已升到目标版本
68+
- [ ] pre-release 格式正确（`1.0.0-beta.0` / `1.0.0-rc.1`，**不要直接用 `1.0.0` 当 beta**）
69+
70+
### 用户面文档
71+
72+
- [ ] `README.md` / `README_CN.md` 的 Quick Start 命令仍能跑通
73+
- [ ] README 的 Node.js 徽章版本与 `cli/package.json.engines.node` 一致
74+
- [ ] README 宣传的 bin 名称在 `cli/package.json.bin` 都真的注册
75+
- [ ] `LICENSE` 文件存在（根 + cli + core 各一份）
76+
77+
## 完成后
78+
79+
- [ ] 验证 npm 上能装：`npm view bailian-cli@<tag> version`
80+
- [ ] 试装一次：`npm i -g bailian-cli@<tag> && bl --version`
81+
82+
## 常见漏点（基于历史踩坑）
83+
84+
| 漏点 | 后果 |
85+
| ------------------------------------------------ | ---------------------------------------------------- |
86+
| cli 升版号但 core 没升 | check.mjs 会拦下 |
87+
| `1.0.0` 当 beta 直接发 | 占了 `latest` tag，所有用户被强升，撤回成本极高 |
88+
| README 写的 bin 名实际 `package.json.bin` 没注册 | 用户复制命令报 `command not found` |
89+
| Node 徽章 `>=18`、engines `>=22.12` 不一致 | 用户在 Node 18 上 `npm i` 被 engine 警告或直接失败 |
90+
| npm Trusted Publisher 的 workflow filename 改了没同步 | OIDC 匹配不上，publish 报 404 |
91+
| CI 用 Node 22（npm 10）跑 publish | npm 10 不支持 OIDC token 交换，publish 报 404 |

‎docs/agents/release.md‎

Lines changed: 0 additions & 94 deletions
This file was deleted.

0 commit comments

Comments
 (0)