Skip to content

Commit 225388e

Browse files
authored
发布改走 npm trusted publishing(OIDC),新增发版 skill (#89)
* 发布改走 npm trusted publishing(OIDC),新增发版 skill npm 将于 2027-01 取消 bypass-2FA token 的直接发布能力。发布 job 去掉 NODE_AUTH_TOKEN 与 setup-node 的 registry-url,改用 OIDC 身份;首发由维护者本机交互式发布,之后登记 trusted publisher。完整发版步骤与失败处理落到 .telov/skills/release。 * 按复审修 #89:首发必须 bump 新版本才轮到 OIDC,并补两道门禁 - publish.yml 钉 [email protected](与 actions 钉 SHA 同一条理由,浮动 tag 会在发布前引入未审阅代码) - 首发流程改为「本机发 0.1.0 → 登记 trusted publisher → bump 0.1.1 打 tag」:推 v0.1.0 会被版本已存在的幂等守卫跳过,OIDC 一次不跑、配置 2 天后静默过期 - doc-tool-names 扫描面改为 PROMPT_SKILLS_DIRS,纳入 .telov/skills(运维 skill 同样进提示词) - pack-manifest 黑名单补 .telov/,白名单被放宽时的第二道防线 - Note 补 actions/setup-node#1551(删 registry-url 的理由)与门禁读数 * 抬 development 文档天花板到 2550(2379 只剩 4.84%,低于 5% 规矩)并改准用例数
1 parent e4b99d0 commit 225388e

13 files changed

Lines changed: 226 additions & 30 deletions

‎.agents/notes/2026-11-02-npm-publish-pipeline.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@
7575

7676
## 边界
7777

78-
- **`NPM_TOKEN` 必须手工配**:仓库 secret,Automation 或 Granular access token,需要 publish 权限。首次发布时包在 npm 上还不存在、无法配 trusted publishing,只能用 token;发过一次后可以改成 OIDC 发布并删掉 secret。
78+
- **`NPM_TOKEN` 路线已废弃**:npm 已宣布 bypass-2FA token 从 2027-01 起不能直接发布;本仓改为首发本机交互式发布、之后走 OIDC,见 [2026-11-03-npm-oidc-publishing.md](2026-11-03-npm-oidc-publishing.md)。
7979
- **provenance 只在 CI 里生成,且要求仓库公开**:本地 `npm publish` 没有 OIDC 身份,不会带来源证明。发布走 tag 才有;仓库已验证是 public(`gh repo view --json visibility` → `PUBLIC`)。
8080
- **只从 `npm publish`(不带路径参数)发布**:`prepublishOnly` 只在无参发布时执行,`npm publish xxx.tgz` 不跑生命周期脚本,`release:check` 整段被跳过。这一条写在[发布与打包](../development.md#发布与打包)。
8181
- **不自动改版本号**:版本仍在 `package.json` 里手工改,tag 由人打。自动 bump 需要与 release notes 生成策略一起定,这次不引入。
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# npm 发布迁移到 trusted publishing(OIDC)
2+
3+
## 背景
4+
5+
npm 2026-07-08 宣布弃用 bypass-2FA 的 granular access token,分两步落地:2026-07-31 起这类 token 不能再做账户与包管理操作(建 token、改 maintainer、改 trusted publisher 配置);2027-01(目标)起连直接发布也取消,只剩读私有包与 stage publish。2026-09-18 上线 stage-only token(`npm stage publish` + 维护者 2FA 批准),2026-10-02 起 staged publish 可以创建全新包(先注册 `0.0.0-stage` 占位)。
6+
7+
本仓此前的发布链路(见 [2026-11-02-npm-publish-pipeline.md](2026-11-02-npm-publish-pipeline.md))用 `NPM_TOKEN` secret 直发。包还没发布过(`npm view` 返回 E404),secret 也没配。按旧方案走,首个版本发出后要立刻换 OIDC,而换配置那一步(在 npmjs.com 改 trusted publisher)本身已不能用 bypass token 完成,只能人工补。
8+
9+
## 决策
10+
11+
### 首发在维护者本机交互式发布
12+
13+
trusted publishing 要求包在 registry 上已存在才能登记(npm/cli#8544 仍开放)。首发因此只能二选一:本机 `npm login` 后 `npm publish`(真实 2FA OTP),或建 stage-only token 走 `npm stage publish` 再人工 `npm stage approve`。
14+
15+
选前者:一次性操作,不需要在仓库或 CI 里留任何 token,也不给自己加一道 stage 审批;代价是首个版本没有 provenance(npm 只在 OIDC/CI 下生成),从第二个版本起由 CI 补上。stage 路线写进发版 skill 作为备选,给不想在维护者机器上 `npm login` 的场合。
16+
17+
**登记 trusted publisher 之后必须再发一个未发布的版本**(如 0.1.1),不能把首发版本本身推成 tag。`publish.yml` 的发布步骤带「版本已存在就跳过」守卫,推 `v0.1.0` 会在打印「已发布,跳过 npm publish」后 exit 0:workflow 绿色,OIDC 一次都没跑,trusted publisher 配置 2 天后静默过期,而 CI 读数与成功发布完全一样。首发版本天然已存在,所以首发之后必须有一个新版本真走一遍 OIDC。
18+
19+
### 之后全部走 OIDC,仓库不留发布 secret
20+
21+
`publish.yml` 删掉 `NODE_AUTH_TOKEN` 与 setup-node 的 `registry-url`:后者会往 `.npmrc` 写 `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`,token 删掉后展开为空串,npm 把这个空值读成「认证已配置」而从不发起 OIDC exchange,最终报 ENEEDAUTH(actions/setup-node#1551)。保留 `id-token: write`,并显式装 `[email protected]`:OIDC 发布要求 CLI ≥ 11.5.1,OIDC 下切 dist-tag 要求 ≥ 11.21 / 12.2,不依赖 setup-node 附带的那一版;钉具体版本而不是 `@latest`,理由与 actions 钉 SHA 相同——发布前不该从浮动 tag 拉到没人审阅过的代码,且 npm 版本不可回收。
22+
23+
包侧配置:npmjs.com → 包 → Settings → Trusted Publisher 登记 `fengshenx` / `dsh-leader-kit` / `publish.yml`,Allowed actions 勾 `npm publish`(预发布用 `--tag next`,再勾 `Allow npm dist-tag`)。首次 OIDC 发布成功后,把 Publishing access 改成「Require two-factor authentication and disallow tokens」。
24+
25+
### 发版操作固化为工作区 skill
26+
27+
版本号怎么定、bump 在哪做、tag 何时打、失败怎么处理,写成 [.telov/skills/release](../../.telov/skills/release/SKILL.md)。它放在 `.telov/skills/` 而不是 `.agents/skills/`:后者是随包发布的协议层 skill(`tests/skills.test.js` 固定名单),发版手册只服务本仓维护者。
28+
29+
手册不进包,但要进两道门禁。`pack-manifest.mjs` 的 `FORBIDDEN_PATTERNS` 显式拦 `.telov/`(今天靠 `files` 白名单兜住,那是白名单被放宽时的第二道防线);`doc-tool-names.mjs` 的扫描面从单目录常量改成 `PROMPT_SKILLS_DIRS = ['.agents/skills', '.telov/skills']`——手册同样进会话提示词、同样会让模型去调工具,**只扫 `.agents/skills` 时新 skill 里写错工具名没有任何门禁会红**。
30+
31+
## 边界
32+
33+
- **顺序不能反**:先用本地发布让包在 registry 上存在,再登记 trusted publisher;登记后(2 天窗口内)要 bump 一个未发布版本并推它的 tag,不能推首发版本,否则守卫跳过、OIDC 一次不跑,配置过期只能删掉重配。
34+
- **首发版本没有 provenance**:0.1.0 由本机发布,包页面从下一个版本起才有「Built and signed on GitHub Actions」。
35+
- **tag 不能在分支上打**:`publish.yml` 仍校验 tag 提交在 `origin/main` 上;在 worktree 里 bump 要用 `npm version --no-git-tag-version`,否则会留下一个指向分支提交的本地 tag。
36+
- **OIDC 仍要求仓库公开**:provenance 与 trusted publishing 的可用性都依赖这个前提,`package.json` 的 `repository` 也必须与 GitHub 仓库一致。
37+
- **本地发布同样跑门禁**:`prepublishOnly` = `release:check`;`npm publish <tarball>` 不跑生命周期脚本,会整段跳过。
38+
- **`AGENTS.md` 天花板 4200 → 4280,`docs/development.md` 2500 → 2550**:详细步骤搬进 skill,development 只留链路契约(补首发顺序后 2379,2500 只剩 4.84% 余量、低于本仓 5% 规矩,且门禁只判超限不判贴线,所以按 6.7% 重算到 2550);AGENTS.md 新增两处发版入口(改后 3846),按 10% 余量重算到 4280。
39+
40+
## 验证
41+
42+
- `npm run check` 全绿:65 篇笔记格式合规、**12 篇**文档工具名全部存在(新增的一篇是 `.telov/skills/release/SKILL.md`)、13 篇 standing docs 都在天花板内(AGENTS.md 3846/4280、`docs/development.md` 2379/2550)、语法 96 个文件、977 用例通过(16 skip)、覆盖率门禁通过。
43+
- 两处新门禁都做了双向验证:`PROMPT_SKILLS_DIRS` 回退成只含 `.agents/skills`,新增的扫描面用例变红;撤掉 `/^\.telov\//`,打包黑名单用例变红;各自还原后全绿(两个文件 22 例)。
44+
- `npm run verify:pack`:86 个文件(未压缩 994 kB),必需项齐全、无开发残留、装机 smoke 通过。加 `.telov/` 不改变包内容——它本来就不在 `files` 白名单里。
45+
- **OIDC 发布路径未在本仓验证**:需要包已在 npm 上存在并登记 trusted publisher,只能由首次真实 tag 发布证明。本地能验的是 workflow 语法与 tag 前置校验;首次发布后把 CI 读数回填到本文件。

‎.github/workflows/publish.yml‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,15 @@ name: Publish
22

33
# 发版入口:改 package.json 的 version → 提交 → 打 tag `v<version>` → push tag。
44
# 门禁挂在本包的 `prepublishOnly`(= npm run release:check),手动发布与 CI 走同一条链路。
5+
# 认证走 npm trusted publishing(OIDC):仓库不存发布 token,身份由本次 workflow 换取短期凭证。
56
on:
67
push:
78
tags: ['v*']
89

910
permissions:
1011
# 建 GitHub Release 用 GITHUB_TOKEN
1112
contents: write
12-
# npm provenance 用 OIDC 换签名,不需要额外 secret
13+
# 向 npm 换 OIDC 短期发布凭证,并生成 provenance
1314
id-token: write
1415

1516
concurrency:
@@ -20,8 +21,8 @@ jobs:
2021
publish:
2122
runs-on: ubuntu-latest
2223
steps:
23-
# pin 到完整 commit SHA:浮动 tag 被上游 retag 后,新代码在 `npm publish`
24-
# 之前就能读到 NODE_AUTH_TOKEN,而 npm 版本不可回收。注释里的版本号供人读。
24+
# pin 到完整 commit SHA:浮动 tag 被上游 retag 后,新代码在发布前就能拿到发布权限
25+
#(OIDC 身份 + contents: write),而 npm 版本不可回收。注释里的版本号供人读。
2526
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
2627
with:
2728
fetch-depth: 0
@@ -48,21 +49,24 @@ jobs:
4849
exit 1
4950
fi
5051
52+
# 不写 registry-url:它会往 .npmrc 写 _authToken=${NODE_AUTH_TOKEN},
53+
# 空值会先于 OIDC 身份被 npm 读到。
5154
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
5255
with:
5356
node-version: 24
5457
cache: npm
55-
registry-url: https://registry.npmjs.org
58+
59+
# OIDC 发布要求 npm CLI ≥ 11.5.1;OIDC 下切 dist-tag 要求 ≥ 11.21 / 12.2。
60+
# 钉具体版本而不是 @latest:与 actions 钉 SHA 同一条理由——发布前不该从浮动
61+
# tag 拉到一份没人审阅过的代码,而 npm 版本不可回收。11.21.0 同时满足两个门槛。
62+
- run: npm install -g [email protected] --no-fund --no-audit
5663

5764
- run: npm ci
5865

59-
# NPM_TOKEN 是仓库 secret(Automation 或 Granular access token,需要 publish 权限)。
60-
# --provenance 让 npm 用本次 workflow 的 OIDC 身份生成来源证明,包页面显示
61-
# 「Built and signed on GitHub Actions」;它的前提是仓库公开,且 package.json 的
62-
# repository 与这里一致。
63-
#
64-
# 两步都不能省:版本已存在时跳过发布(发布成功但后面建 Release 失败时,重跑
65-
# 不会卡在 E403),预发布版走 next dist-tag(不带 --tag 会把 rc 顶到 latest)。
66+
# 认证来自 trusted publishing:npmjs.com 上该包已登记本仓库与 workflow 文件名
67+
#(publish.yml),并勾选允许 npm publish;仓库里没有 NPM_TOKEN。
68+
# 版本已存在时跳过发布,保证「发布成功但建 Release 失败」后能直接重跑;
69+
# 预发布版走 next dist-tag(不带 --tag 会把 rc 顶到 latest)。
6670
- name: 发布到 npm
6771
run: |
6872
set -euo pipefail
@@ -75,8 +79,6 @@ jobs:
7579
tag=latest
7680
case "$version" in *-*) tag=next ;; esac
7781
npm publish --provenance --access public --tag "$tag"
78-
env:
79-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
8082
8183
- name: 建 GitHub Release
8284
env:

‎.telov/skills/release/SKILL.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
name: release
3+
description: 本仓发版手册:定版本号、bump、跑 release:check、开 PR、合并后打 tag 触发 CI 发布;含首次发布与失败处理。当用户要求「发版」「发布 npm 包」「bump 版本」「打个 tag」时使用。
4+
whenToUse: 需要把 dsh-leader-kit 的新版本发布到 npm,或排查发版失败时。
5+
---
6+
7+
# 发版
8+
9+
目标:让 `npm publish` 只由 tag 触发,版本号、门禁、tag 三者严格对齐。发布不可回收,任何一步没把握就停下来问用户。
10+
11+
## 前提
12+
13+
- 改动在 worktree 里(`npm run worktree:spawn <任务名>`),主 checkout 保持干净。
14+
- `gh` 已登录、对 `fengshenx/dsh-leader-kit` 有推 tag 权限;`main` 上的 CI 是绿的。
15+
- 仅首次发布需要本机发布:`npm login` 完成、账号已开 2FA。
16+
17+
## 一、定版本号
18+
19+
`package.json` 的 `version` 是唯一来源,tag 必须是 `v<version>`。
20+
21+
| 变化 | 用法 | 例子 |
22+
|---|---|---|
23+
| 修复 | patch | 0.1.0 → 0.1.1 |
24+
| 0.x 期间的新能力或破坏性变化 | minor | 0.1.0 → 0.2.0 |
25+
| 预发布 | 显式写版本 | 0.2.0-rc.1 |
26+
27+
预发布版本带 `-`:CI 用 `next` dist-tag,GitHub Release 标 prerelease,不会顶掉 `latest`。
28+
29+
## 二、bump
30+
31+
```bash
32+
npm version patch|minor|major|x.y.z --no-git-tag-version
33+
git diff -- package.json package-lock.json
34+
```
35+
36+
diff 只能出现在这两个文件的版本行。默认的 `npm version` 会提交并打 tag,而那个 tag 指向 worktree 分支的提交,CI 会因「不在 origin/main 上」拒绝。
37+
38+
## 三、门禁
39+
40+
```bash
41+
npm run release:check
42+
```
43+
44+
它就是 `prepublishOnly`,也是 CI 的发布门禁:`check` + `build:client` + `verify:pack`。顺序不能倒,`verify:pack` 依赖已构建的 `lib/client.js`。红了先修,不要绕过。
45+
46+
## 四、提交与 PR
47+
48+
```bash
49+
git add -A
50+
git commit -m "chore(release): <version>"
51+
git push -u origin feature/<任务名>
52+
gh pr create --fill
53+
```
54+
55+
等 CI 绿、PR 合并。合并与 approve 需用户明确指令。
56+
57+
## 五、合并后打 tag
58+
59+
```bash
60+
git checkout main && git pull
61+
git tag -a v<version> -m "v<version>"
62+
git push origin v<version>
63+
```
64+
65+
tag 必须指向 `main` 上的提交。`publish.yml` 会校验 tag 与 `package.json` 版本一致、且提交在 `origin/main` 上。
66+
67+
## 六、观察
68+
69+
```bash
70+
gh run watch
71+
gh release view v<version>
72+
npm view dsh-leader-kit@<version> version
73+
```
74+
75+
CI 依次:校验 → `npm ci` → OIDC 发布 → 建 Release。发布步骤幂等:版本已存在就跳过,所以 Release 失败可以直接重跑 workflow。
76+
77+
## 首次发布(包在 npm 上还不存在)
78+
79+
trusted publisher 要求包已存在,所以首个版本必须绕开 CI;但**登记完必须再发一个未发布过的版本**,否则 OIDC 一次都不会跑:
80+
81+
1. 本机确认 `npm run release:check` 通过。
82+
2. `npm login`,然后 `npm publish`(不要带路径参数,否则跳过 `prepublishOnly`)。这一步发出 `package.json` 里的当前版本(如 0.1.0),没有 provenance。
83+
3. `npm view dsh-leader-kit version` 确认版本上线。
84+
4. npmjs.com → 包 → Settings → Trusted Publisher → GitHub Actions:
85+
- Organization or user: `fengshenx`
86+
- Repository: `dsh-leader-kit`
87+
- Workflow filename: `publish.yml`
88+
- Allowed actions: `npm publish`(预发布再勾 `npm dist-tag`)
89+
5. **bump 到一个未发布的版本**(如 0.1.1),按第一到五节走完整流程:PR 合并后从 `main` 打 `v0.1.1` tag。这一步才是首次 OIDC 发布。
90+
6. 看 `gh run view` 的发布步骤:必须是 `npm notice Publishing ...`,不能是「已发布,跳过 npm publish」。
91+
7. 包设置 → Publishing access → 「Require two-factor authentication and disallow tokens」。
92+
93+
**为什么不能直接推 `v0.1.0`**:第 2 步已经把它发到 registry,`publish.yml` 的「版本已存在就跳过」守卫会打印「已发布,跳过 npm publish」并 exit 0——workflow 整体绿色,但 OIDC 一次都没跑,trusted publisher 配置 2 天后静默过期,而 CI 读数看不出区别。首发版本天然「已存在」,所以首发之后必须有一个新版本真走一遍 OIDC。
94+
95+
备选(不想在维护者机器上登录):建 `Read and write (stage only)` granular token,`npm stage publish` 后由维护者 `npm stage approve`(要 OTP);它先注册 `0.0.0-stage` 占位包。同样要在登记 trusted publisher 后发一个新版本验证 OIDC。
96+
97+
## 失败处理
98+
99+
- **`tag ... 与 package.json 的 ... 不一致`**:版本没提交或 tag 打错。删本地 tag(`git tag -d`)并从 `main` 重打。
100+
- **`tag 指向的提交不在 origin/main 上`**:tag 打在了 worktree 分支上。删除远端 tag(`git push origin :refs/tags/<tag>`)后从 `main` 重打。
101+
- **版本已存在**:npm 不允许重发同一版本。确认内容后 `npm deprecate`,再发下一个版本。
102+
- **`ENEEDAUTH` / 403**:检查 trusted publisher 的仓库、workflow 文件名、Allowed actions 是否与 `publish.yml` 一致;配置是否已过期。
103+
- **Release 建失败**:直接重跑 workflow,发布步骤会跳过已存在版本。
104+
105+
## 禁止
106+
107+
- 在主 checkout 改版本或跑发布。
108+
- 从分支推 tag、对 `main` force push、删除已发布版本所在的 tag。
109+
- `npm publish <tarball>`:不跑 `prepublishOnly`,门禁整段跳过。
110+
- 未经用户明确指令合并 PR、改包设置或发版。

‎AGENTS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ dsh-leader-kit —— dsh(DeepSeek Harness)的**仓外插件 bundle**:lead
2727
| 项目级提示词(`LEADER.md` / `SLOTS.md`;旧名 `COORDINATOR.md` 只是兼容入口) | [2026-10-29-coordinator-manual-injection.md](.agents/notes/2026-10-29-coordinator-manual-injection.md)、`src/host/leader-context.js`、`src/host/slots/` |
2828
| 写浏览器 e2e 场景、跑 `npm run e2e`、截图取证 | [docs/e2e-testing.md](docs/e2e-testing.md)(车道命令、场景模板、mock 标记约定、截图落点、断言纪律;脚本化不了的才走人工取证) |
2929
| 审查 PR、以 bot 身份发评论 | [用 bot 身份发评论](#用-bot-身份发评论)、`scripts/github-app-token.mjs` |
30-
| 发版、发布包内容与 CI | [development 的发布与打包一节](docs/development.md#发布与打包)、[2026-11-02-npm-publish-pipeline.md](.agents/notes/2026-11-02-npm-publish-pipeline.md) |
30+
| 发版、发布包内容与 CI | [.telov/skills/release](.telov/skills/release/SKILL.md)(发版手册)、[development 的发布与打包一节](docs/development.md#发布与打包)、[2026-11-03-npm-oidc-publishing.md](.agents/notes/2026-11-03-npm-oidc-publishing.md) |
3131
| 协议层文案(`.agents/skills/`) | 现有 `.agents/skills/leader-mode/` 的行文与结构,保持同一口吻 |
3232

3333
## 目录与职责
@@ -38,6 +38,7 @@ src/host/ 宿主侧:工具、派工器、存储、项目服务、wor
3838
src/client/ 浏览器侧:项目树、看板、会话行(React.createElement,无 JSX)
3939
src/shared/ 两端共用的纯函数与消息来源约定
4040
.agents/skills/ 协议层 skill(leader-mode 派工协议、init-project 初始化方法)
41+
.telov/skills/ 工作区运维 skill(release 发版手册,不进发布包)
4142
tests/ node:test 单测(纯函数与假件,不引 jsdom)
4243
tests/e2e/ 浏览器 e2e:实例夹具、mock provider、场景(`npm run e2e` 单独跑)
4344
build/ esbuild 客户端构建:client.mjs 入口 + client-bundle.mjs(配置与原子写)

0 commit comments

Comments
 (0)