@jsbot-tellus/core 2.0.2 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- package/docs/release.md +81 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -142,6 +142,10 @@ npm run check:local # 检查 plugins（需要先安装本地依赖）
|
|
|
142
142
|
npm run build:local # 构建 plugins
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
+
## 发布
|
|
146
|
+
|
|
147
|
+
发布由 [`.github/workflows/cd.yaml`](.github/workflows/cd.yaml) 驱动：`main` 的 CI 成功后自动通过 npm Trusted Publisher 发布；已存在的版本会跳过。不需要版本标签。检查、构建和首次配置见[发布流程](docs/release.md)。
|
|
148
|
+
|
|
145
149
|
## 文档
|
|
146
150
|
|
|
147
151
|
- [架构](docs/architecture.md)
|
|
@@ -149,6 +153,7 @@ npm run build:local # 构建 plugins
|
|
|
149
153
|
- [配置](docs/configuration.md)
|
|
150
154
|
- [迁移与回滚](docs/migration.md)
|
|
151
155
|
- [功能对照](docs/feature-parity.md)
|
|
156
|
+
- [发布流程](docs/release.md)
|
|
152
157
|
|
|
153
158
|
## 许可证
|
|
154
159
|
|
package/docs/release.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# 发布流程
|
|
2
|
+
|
|
3
|
+
`@jsbot-tellus/core` 通过 GitHub Actions 自动发布：
|
|
4
|
+
|
|
5
|
+
- CI 工作流：[`.github/workflows/ci.yaml`](../.github/workflows/ci.yaml)，负责类型检查、格式检查、依赖审计、测试、构建和 smoke
|
|
6
|
+
- CD 工作流：[`.github/workflows/cd.yaml`](../.github/workflows/cd.yaml)，在 `main` 的 CI 成功后发布到 npm
|
|
7
|
+
- 触发方式：推送到 `main`，或在 `main` 上手动运行 `CI`；不需要创建或推送版本标签
|
|
8
|
+
- 发布方式：npm Trusted Publisher（GitHub OIDC），不需要长期 `NPM_TOKEN`
|
|
9
|
+
- 幂等处理：如果 `package.json` 中的版本已经存在于 npm，发布步骤会跳过
|
|
10
|
+
- 发布产物带 npm provenance
|
|
11
|
+
|
|
12
|
+
CD 只会在 CI 结论为成功、且 CI 运行来自 `main` 的 `push` 或 `workflow_dispatch` 时执行。`pull_request` 运行和其他分支不会触发发布。
|
|
13
|
+
|
|
14
|
+
## 一次性配置
|
|
15
|
+
|
|
16
|
+
在 npm 上打开 `@jsbot-tellus/core` 的包设置，配置 Trusted Publisher：
|
|
17
|
+
|
|
18
|
+
| 字段 | 值 |
|
|
19
|
+
| -------------------- | -------------- |
|
|
20
|
+
| Provider | GitHub Actions |
|
|
21
|
+
| Organization or user | `JsBot-Dev` |
|
|
22
|
+
| Repository | `JsBot-Tellus` |
|
|
23
|
+
| Workflow filename | `cd.yaml` |
|
|
24
|
+
| Environment | 留空 |
|
|
25
|
+
|
|
26
|
+
工作流文件名必须与实际文件一致。如果以后重命名 `cd.yaml`，需要同步修改 npm 的 Trusted Publisher 配置。
|
|
27
|
+
|
|
28
|
+
CD 工作流已经声明：
|
|
29
|
+
|
|
30
|
+
```yaml
|
|
31
|
+
permissions:
|
|
32
|
+
contents: read
|
|
33
|
+
id-token: write
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`id-token: write` 用于 OIDC 和 provenance，不能删除。
|
|
37
|
+
|
|
38
|
+
## 发布新版本
|
|
39
|
+
|
|
40
|
+
发布前先在功能分支提升版本并更新 lockfile：
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm version patch --no-git-tag-version
|
|
44
|
+
git add package.json package-lock.json
|
|
45
|
+
git commit -m "Release v$(node -p "require('./package.json').version")"
|
|
46
|
+
git push
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
将 `patch` 换成 `minor` 或 `major` 可以发布对应版本。合并到 `main`（或直接推送到 `main`）后，CI 会先运行；CI 成功后 CD 自动发布该版本。
|
|
50
|
+
|
|
51
|
+
如果 `main` 上的版本已经在 npm 存在，CD 只会输出提示并跳过，不会失败。因此重复推送 `main` 是安全的。
|
|
52
|
+
|
|
53
|
+
## 手动运行
|
|
54
|
+
|
|
55
|
+
在 GitHub Actions 中打开 `CI`，选择 `Run workflow`，并选择 `main` 分支。CI 成功后，CD 会像普通推送一样自动发布。
|
|
56
|
+
|
|
57
|
+
如果 CD 因临时故障失败，可以在 Actions 中打开对应的 `CD` 运行并选择 `Re-run failed jobs`，不需要重新推送代码。
|
|
58
|
+
|
|
59
|
+
## 验证
|
|
60
|
+
|
|
61
|
+
发布完成后检查：
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm view @jsbot-tellus/core version
|
|
65
|
+
npm view @jsbot-tellus/core dist-tags
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
正式安装验证：
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
npm install -g @jsbot-tellus/core@latest
|
|
72
|
+
jsbot --help
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## 常见失败
|
|
76
|
+
|
|
77
|
+
- **`ENEEDAUTH` / `E403`**：检查 npm Trusted Publisher 的组织、仓库和工作流文件名是否完全匹配（文件名必须是 `cd.yaml`）。
|
|
78
|
+
- **`npm publish` 提示版本已存在**：说明该版本此前已经发布；提升 `package.json` 版本后重新推送到 `main`。正常情况下 CD 会自动跳过已发布版本。
|
|
79
|
+
- **provenance 失败**：确认 CD 工作流仍有 `id-token: write` 权限，并且仓库是公开的。
|
|
80
|
+
- **CD 没有触发**：确认 `CI` 已在 `main` 上成功完成；`pull_request` 运行和其他分支不会触发发布。
|
|
81
|
+
- **CD 找不到要发布的提交**：确认 `ci.yaml` 和 `cd.yaml` 都已经在默认分支上。
|