Skip to content

Commit 2fc06a3

Browse files
committed
按复审修 #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 的理由)与门禁读数
1 parent c335f13 commit 2fc06a3

9 files changed

Lines changed: 69 additions & 22 deletions

File tree

‎.agents/notes/2026-11-03-npm-oidc-publishing.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,23 @@ trusted publishing 要求包在 registry 上已存在才能登记(npm/cli#8544
1414

1515
选前者:一次性操作,不需要在仓库或 CI 里留任何 token,也不给自己加一道 stage 审批;代价是首个版本没有 provenance(npm 只在 OIDC/CI 下生成),从第二个版本起由 CI 补上。stage 路线写进发版 skill 作为备选,给不想在维护者机器上 `npm login` 的场合。
1616

17+
**登记 trusted publisher 之后必须再发一个未发布的版本**(如 0.1.1),不能把首发版本本身推成 tag。`publish.yml` 的发布步骤带「版本已存在就跳过」守卫,推 `v0.1.0` 会在打印「已发布,跳过 npm publish」后 exit 0:workflow 绿色,OIDC 一次都没跑,trusted publisher 配置 2 天后静默过期,而 CI 读数与成功发布完全一样。首发版本天然已存在,所以首发之后必须有一个新版本真走一遍 OIDC。
18+
1719
### 之后全部走 OIDC,仓库不留发布 secret
1820

19-
`publish.yml` 删掉 `NODE_AUTH_TOKEN` 与 setup-node 的 `registry-url`(它会往 `.npmrc` 写 `_authToken=${NODE_AUTH_TOKEN}`,空值会先于 OIDC 身份被读到)。保留 `id-token: write`,并显式 `npm install -g npm@latest`:OIDC 发布要求 CLI ≥ 11.5.1,OIDC 下切 dist-tag 要求 ≥ 11.21 / 12.2,不依赖 setup-node 附带的那一版。
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`,并显式装 `npm@11.21.0`:OIDC 发布要求 CLI ≥ 11.5.1,OIDC 下切 dist-tag 要求 ≥ 11.21 / 12.2,不依赖 setup-node 附带的那一版;钉具体版本而不是 `@latest`,理由与 actions 钉 SHA 相同——发布前不该从浮动 tag 拉到没人审阅过的代码,且 npm 版本不可回收。
2022

2123
包侧配置: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」。
2224

2325
### 发版操作固化为工作区 skill
2426

2527
版本号怎么定、bump 在哪做、tag 何时打、失败怎么处理,写成 [.telov/skills/release](../../.telov/skills/release/SKILL.md)。它放在 `.telov/skills/` 而不是 `.agents/skills/`:后者是随包发布的协议层 skill(`tests/skills.test.js` 固定名单),发版手册只服务本仓维护者。
2628

29+
手册不进包,但要进两道门禁。`pack-manifest.mjs` 的 `FORBIDDEN_PATTERNS` 显式拦 `.telov/`(今天靠 `files` 白名单兜住,那是白名单被放宽时的第二道防线);`doc-tool-names.mjs` 的扫描面从单目录常量改成 `PROMPT_SKILLS_DIRS = ['.agents/skills', '.telov/skills']`——手册同样进会话提示词、同样会让模型去调工具,**只扫 `.agents/skills` 时新 skill 里写错工具名没有任何门禁会红**。
30+
2731
## 边界
2832

29-
- **顺序不能反**:先用本地发布让包在 registry 上存在,再登记 trusted publisher;登记后 2 天内要完成首次 OIDC 发布,否则配置过期,只能删掉重配。
33+
- **顺序不能反**:先用本地发布让包在 registry 上存在,再登记 trusted publisher;登记后(2 天窗口内)要 bump 一个未发布版本并推它的 tag,不能推首发版本,否则守卫跳过、OIDC 一次不跑,配置过期只能删掉重配。
3034
- **首发版本没有 provenance**:0.1.0 由本机发布,包页面从下一个版本起才有「Built and signed on GitHub Actions」。
3135
- **tag 不能在分支上打**:`publish.yml` 仍校验 tag 提交在 `origin/main` 上;在 worktree 里 bump 要用 `npm version --no-git-tag-version`,否则会留下一个指向分支提交的本地 tag。
3236
- **OIDC 仍要求仓库公开**:provenance 与 trusted publishing 的可用性都依赖这个前提,`package.json` 的 `repository` 也必须与 GitHub 仓库一致。
@@ -35,6 +39,7 @@ trusted publishing 要求包在 registry 上已存在才能登记(npm/cli#8544
3539

3640
## 验证
3741

38-
- `npm run check` 全绿(Agent Note 格式、文档工具名、文档预算、语法、覆盖率),`docs/development.md` 与 `AGENTS.md` 都在各自天花板内。
39-
- `verify-pack` 不涉及 workflow 与 skill 内容之外的文件,包内容不受这次改动影响。
42+
- `npm run check` 全绿:65 篇笔记格式合规、**12 篇**文档工具名全部存在(新增的一篇是 `.telov/skills/release/SKILL.md`)、13 篇 standing docs 都在天花板内(AGENTS.md 3846/4280、`docs/development.md` 2372/2500)、语法 96 个文件、976 用例通过(16 skip)、覆盖率门禁通过。
43+
- 两处新门禁都做了双向验证:`PROMPT_SKILLS_DIRS` 回退成只含 `.agents/skills`,新增的扫描面用例变红;撤掉 `/^\.telov\//`,打包黑名单用例变红;各自还原后全绿(两个文件 22 例)。
44+
- `npm run verify:pack`:86 个文件(未压缩 994 kB),必需项齐全、无开发残留、装机 smoke 通过。加 `.telov/` 不改变包内容——它本来就不在 `files` 白名单里。
4045
- **OIDC 发布路径未在本仓验证**:需要包已在 npm 上存在并登记 trusted publisher,只能由首次真实 tag 发布证明。本地能验的是 workflow 语法与 tag 前置校验;首次发布后把 CI 读数回填到本文件。

‎.github/workflows/publish.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,9 @@ jobs:
5757
cache: npm
5858

5959
# OIDC 发布要求 npm CLI ≥ 11.5.1;OIDC 下切 dist-tag 要求 ≥ 11.21 / 12.2。
60-
# 不依赖 setup-node 附带的那一版。
61-
- run: npm install -g npm@latest --no-fund --no-audit
60+
# 钉具体版本而不是 @latest:与 actions 钉 SHA 同一条理由——发布前不该从浮动
61+
# tag 拉到一份没人审阅过的代码,而 npm 版本不可回收。11.21.0 同时满足两个门槛。
62+
- run: npm install -g [email protected] --no-fund --no-audit
6263

6364
- run: npm ci
6465

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

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -76,20 +76,23 @@ CI 依次:校验 → `npm ci` → OIDC 发布 → 建 Release。发布步骤
7676

7777
## 首次发布(包在 npm 上还不存在)
7878

79-
trusted publisher 要求包已存在,所以首个版本必须绕开 CI:
79+
trusted publisher 要求包已存在,所以首个版本必须绕开 CI;但**登记完必须再发一个未发布过的版本**,否则 OIDC 一次都不会跑:
8080

8181
1. 本机确认 `npm run release:check` 通过。
82-
2. `npm login`,然后 `npm publish`(不要带路径参数,否则跳过 `prepublishOnly`)。
82+
2. `npm login`,然后 `npm publish`(不要带路径参数,否则跳过 `prepublishOnly`)。这一步发出 `package.json` 里的当前版本(如 0.1.0),没有 provenance。
8383
3. `npm view dsh-leader-kit version` 确认版本上线。
8484
4. npmjs.com → 包 → Settings → Trusted Publisher → GitHub Actions:
8585
- Organization or user: `fengshenx`
8686
- Repository: `dsh-leader-kit`
8787
- Workflow filename: `publish.yml`
8888
- Allowed actions: `npm publish`(预发布再勾 `npm dist-tag`)
89-
5. **2 天内**推一个 `v*` tag 完成首次 OIDC 发布,否则配置过期要删掉重配。
90-
6. 包设置 → Publishing access → 「Require two-factor authentication and disallow tokens」。
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」。
9192

92-
备选(不想在维护者机器上登录):建 `Read and write (stage only)` granular token,`npm stage publish` 后由维护者 `npm stage approve`(要 OTP);它先注册 `0.0.0-stage` 占位包。
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。
9396

9497
## 失败处理
9598

‎docs/development.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,4 +50,4 @@ npm run worktree:prune -- --apply --delete-remote # 连远端分支一起删
5050

5151
发版走 tag:改 `package.json` 的 `version` → 提交 → 打 `v<version>` 并 push。`.github/workflows/publish.yml` 校验 tag 与 version 一致、提交在 `origin/main` 上(`git merge-base --is-ancestor`),再以 trusted publishing(OIDC)发布并建 GitHub Release;`ci.yml` 跑同一条 `release:check`(node 取 `24.9.0` 与最新 `24` 两档),发布 job 握着 OIDC 身份与 `contents: write`,所以 `actions/*` 都 pin 到 commit SHA。预发布走 `next` dist-tag,Release 标 prerelease。步骤与失败处理见 [release skill](../.telov/skills/release/SKILL.md)。
5252

53-
认证不落 secret:npmjs.com 的 Trusted Publisher 登记 `fengshenx/dsh-leader-kit` 与 workflow 文件名 `publish.yml`,勾选允许 `npm publish`(预发布再勾 `npm dist-tag`),2 天内必须完成首次发布,否则过期。**首次发布是例外**:包不存在时无法登记,须本机 `npm login` 后交互式 `npm publish`(带 2FA OTP,没有 provenance),之后登记配置并在包设置里禁掉 token 发布。
53+
认证不落 secret:Trusted Publisher 登记本仓与 `publish.yml`,勾选允许 `npm publish`(预发布再勾 `npm dist-tag`),登记后 2 天内要有新版本真走 OIDC,否则过期。**首次发布是例外**:包不存在时无法登记,须本机交互式 `npm publish`(2FA OTP,无 provenance),随后 bump 新版本打 tag——首发版本已在 registry,推它的 tag 会被幂等守卫跳过。步骤见 [release skill](../.telov/skills/release/SKILL.md)。

‎scripts/doc-tool-names.mjs‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,17 @@
1111

1212
const INLINE_CODE = /`([^`\n]+)`/g
1313

14-
/** 会进会话提示词的文档:根目录两篇,加上 `PROMPT_SKILLS_DIR` 下全部 Markdown。 */
14+
/** 会进会话提示词的文档:根目录两篇,加上 `PROMPT_SKILLS_DIRS` 下全部 Markdown。 */
1515
export const PROMPT_DOCS = Object.freeze(['SLOTS.md', 'LEADER.md'])
16-
export const PROMPT_SKILLS_DIR = '.agents/skills'
16+
17+
/**
18+
* 会进会话提示词的 skill 目录。
19+
*
20+
* `.agents/skills/` 是随包发布的协议层 skill,`.telov/skills/` 是工作区运维 skill
21+
* (发版手册之类)。两者都会被会话加载、都会让模型去调工具,所以工具名都要校验:
22+
* 只扫前者时,新 skill 里写错工具名没有任何门禁会红。
23+
*/
24+
export const PROMPT_SKILLS_DIRS = Object.freeze(['.agents/skills', '.telov/skills'])
1725

1826
/** 至少一个下划线,才可能是工具名;文件名、命令与 camelCase 字段都不命中。 */
1927
const SNAKE_CASE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/

‎scripts/pack-manifest.mjs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,9 @@ export const AGENTS_SKILLS_PREFIX = '.agents/skills/'
2121
* 不该出现在发布包里的路径。
2222
*
2323
* 每条都对应一个具体的漂移风险:测试把仓内上下文带进用户的 node_modules;`scripts/`
24-
* 与 `build/` 是开发工具,装了也用不上;`.dev/`、`.worktrees/` 是本地运行态;`.tgz` 与
25-
* `.DS_Store` 是打包过程与 macOS 的残留。
24+
* 与 `build/` 是开发工具,装了也用不上;`.dev/`、`.worktrees/`、`.telov/` 是本地运行态
25+
* 与工作区运维资产(发版 skill 之类,只服务本仓维护者);`.tgz` 与 `.DS_Store` 是打包
26+
* 过程与 macOS 的残留。
2627
*
2728
* 这份名单是 `files` 白名单的补集,不是它的复述:白名单一旦放宽(比如有人写
2829
* `"docs/**"`、`"*.md"`),这里负责把不该发的东西拦下来。`.agents/` 例外,走
@@ -33,6 +34,7 @@ export const FORBIDDEN_PATTERNS = Object.freeze([
3334
/(^|\/)tests\//,
3435
/^\.dev\//,
3536
/^\.worktrees\//,
37+
/^\.telov\//,
3638
/^\.github\//,
3739
/^AGENTS\.md$/,
3840
/^CLAUDE\.md$/,

‎scripts/verify-doc-tool-names.mjs‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22
* 注入给会话的文档里,工具名必须真实注册。判定逻辑在 doc-tool-names.mjs,这里
33
* 只读盘、取真实工具名与报数。
44
*
5-
* 扫描面只覆盖会进会话提示词的三处:SLOTS.md、LEADER.md、.agents/skills/**\/*.md。
6-
* README 与 docs/ 是给人读的,`.agents/notes/` 里还记着已删工具的历史,都不扫。
5+
* 扫描面只覆盖会进会话提示词的三处:SLOTS.md、LEADER.md、以及两个 skill 目录
6+
* (`.agents/skills/**`、`.telov/skills/**`)下的 Markdown。README 与 docs/ 是给人
7+
* 读的,`.agents/notes/` 里还记着已删工具的历史,都不扫。
78
*
89
* 规则与理由见 AGENTS.md 的「提交与 PR」一节。
910
*/
@@ -12,7 +13,7 @@ import { readdirSync, readFileSync } from 'node:fs'
1213
import { join, relative } from 'node:path'
1314
import { fileURLToPath } from 'node:url'
1415
import { documentedToolNames } from '../src/host/index.js'
15-
import { PROMPT_DOCS, PROMPT_SKILLS_DIR, scanToolNames } from './doc-tool-names.mjs'
16+
import { PROMPT_DOCS, PROMPT_SKILLS_DIRS, scanToolNames } from './doc-tool-names.mjs'
1617

1718
const root = fileURLToPath(new URL('../', import.meta.url))
1819

@@ -31,7 +32,7 @@ function markdownFiles(dir) {
3132

3233
const docs = [
3334
...PROMPT_DOCS.map((name) => join(root, name)),
34-
...markdownFiles(join(root, PROMPT_SKILLS_DIR)).sort(),
35+
...PROMPT_SKILLS_DIRS.flatMap((dir) => markdownFiles(join(root, dir))).sort(),
3536
]
3637

3738
const known = new Set(documentedToolNames())

‎tests/doc-tool-names.test.js‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { test } from 'node:test'
33
import { readdirSync, readFileSync } from 'node:fs'
44
import { join } from 'node:path'
55
import { fileURLToPath } from 'node:url'
6-
import { PROMPT_DOCS, PROMPT_SKILLS_DIR, scanToolNames } from '../scripts/doc-tool-names.mjs'
6+
import { PROMPT_DOCS, PROMPT_SKILLS_DIRS, scanToolNames } from '../scripts/doc-tool-names.mjs'
77
import { documentedToolNames } from '../src/host/index.js'
88

99
const root = fileURLToPath(new URL('../', import.meta.url))
@@ -94,11 +94,22 @@ test('仓库里注入会话的文档零误报', () => {
9494
const known = new Set(documentedToolNames())
9595
const docs = [
9696
...PROMPT_DOCS.map((name) => join(root, name)),
97-
...markdownFiles(join(root, PROMPT_SKILLS_DIR)),
97+
...PROMPT_SKILLS_DIRS.flatMap((dir) => markdownFiles(join(root, dir))),
9898
]
9999
for (const file of docs) {
100100
const { violations, unclosedFence } = scanToolNames(readFileSync(file, 'utf8'), known)
101101
assert.deepEqual(violations, [], `${file} 引用了不存在的工具名`)
102102
assert.equal(unclosedFence, undefined, `${file} 的代码围栏没闭合`)
103103
}
104104
})
105+
106+
test('.telov/skills 也在扫描面内:运维 skill 写错工具名同样会红', () => {
107+
const docs = PROMPT_SKILLS_DIRS.flatMap((dir) => markdownFiles(join(root, dir)))
108+
assert.ok(
109+
docs.some((file) => file.endsWith('.telov/skills/release/SKILL.md')),
110+
'发版手册应进入工具名门禁的扫描面',
111+
)
112+
// 门禁脚本必须复用同一常量:另写一套目录列表时,扫描面会与这里悄悄分叉
113+
const source = readFileSync(join(root, 'scripts/verify-doc-tool-names.mjs'), 'utf8')
114+
assert.match(source, /PROMPT_SKILLS_DIRS\.flatMap/)
115+
})

‎tests/pack-manifest.test.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,22 @@ test('files 放宽到 .agents/** 时,notes 与新增目录仍被拦', () => {
145145
assert.deepEqual(missing, [])
146146
})
147147

148+
test('.telov 是工作区运维目录,整棵子树都不该进包', () => {
149+
// 今天靠 files 白名单兜住(.telov/ 不在名单里);白名单哪天放宽,这里是第二道
150+
// 防线。发版 skill 只服务本仓维护者,装到用户 node_modules 里没有用处。
151+
const forbidden = [
152+
'.telov/skills/release/SKILL.md',
153+
'.telov/mcp.json',
154+
]
155+
for (const path of forbidden) assert.equal(isForbiddenPath(path), true, `${path} 应被拦下`)
156+
157+
const { forbidden: caught } = checkPackEntries({
158+
entries: ['index.js', '.telov/skills/release/SKILL.md'],
159+
required: [],
160+
})
161+
assert.deepEqual(caught, ['.telov/skills/release/SKILL.md'])
162+
})
163+
148164
test('发布包要用的路径不被误判', () => {
149165
const legit = [
150166
'src/host/index.js',

0 commit comments

Comments
 (0)