Skip to content

发布改走 npm trusted publishing(OIDC),新增发版 skill - #89

Merged
fengshenx merged 3 commits into
mainfrom
feature/release-oidc
Nov 3, 2026
Merged

fengshenx merged 3 commits into
mainfrom
feature/release-oidc

Conversation

@fengshenx

@fengshenx fengshenx commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner

背景

npm 已宣布 bypass-2FA 的 granular token 从 2027-01 起不能直接发布;2026-07-31 起这类 token 也不能再做 trusted publisher 配置等账户操作。本仓发布 job 仍用 NODE_AUTH_TOKEN,而包尚未发布、secret 也还没配——沿旧方案会在首个版本发出后立刻返工,且换配置那一步只能人工做。

改动

  • .github/workflows/publish.yml:删掉 NODE_AUTH_TOKEN 与 setup-node 的 registry-url(避免空 _authToken 抢先于 OIDC),改由 id-token: write 的 OIDC 身份发布;显式升级 npm(OIDC ≥ 11.5.1,OIDC dist-tag ≥ 11.21 / 12.2)。
  • docs/development.md / docs/limitations.md:发布节改为 OIDC 契约与「首次发布例外」,删掉 NPM_TOKEN 的过时说法。
  • .agents/notes/2026-11-03-npm-oidc-publishing.md:记录决策与边界;旧 note 的过时段落改为指向新 note。
  • .telov/skills/release/SKILL.md:发版手册(定版本号 → bump → release:check → PR → 合并后打 tag),含首发流程与失败处理。放在 .telov/skills/ 而不是 .agents/skills/,因为它不随包发布。
  • AGENTS.md:发版入口指向 skill;scripts/doc-budgets.json 的 AGENTS.md 天花板 4200 → 4280(按 10% 余量重算)。

验证

  • npm run check:65 篇笔记格式合规;12 篇文档工具名全部存在(含新增的 .telov/skills/release/SKILL.md);13 篇 standing docs 在天花板内(AGENTS.md 3846/4280、docs/development.md 2379/2500);语法 96 个文件;977 用例通过(16 skip),覆盖率门禁通过。
  • npm run verify:pack:86 个文件(未压缩 994 kB),必需项齐全、无开发残留、装机 smoke 通过。
  • 两道新门禁做了双向验证:PROMPT_SKILLS_DIRS 回退成只含 .agents/skills 时扫描面用例变红;撤掉 .telov/ 黑名单条目时打包用例变红;还原后均全绿。
  • workflow YAML 用 yaml.safe_load 解析通过,setup-node 仍是 node-version: 24 + cache: npm。
  • OIDC 发布路径未在本仓验证:需要包已在 npm 上存在并登记 trusted publisher,只能由首次真实 tag 发布证明。

合并后需要你本机执行

  1. npm login → npm publish(首发 0.1.0,真实 2FA OTP;这一步没有 provenance)。
  2. npmjs.com → 包 → Settings → Trusted Publisher:fengshenx / dsh-leader-kit / publish.yml,Allowed actions 勾 npm publish(预发布再勾 npm dist-tag)。
  3. bump 到 0.1.1 并走完整发版流程:bump → release:check → PR 合并 → 从 main 打 v0.1.1 tag。这一步才是首次 OIDC 发布。
    不要直接推 v0.1.0:0.1.0 已在第 1 步发布,publish.yml 的「版本已存在就跳过」守卫会打印「已发布,跳过 npm publish」并 exit 0——workflow 绿色,但 OIDC 一次都没跑,trusted publisher 配置 2 天后静默过期,CI 读数看不出区别。
  4. 看 gh run view 的发布步骤:必须是 npm notice Publishing ...,不能是「已发布,跳过 npm publish」。
  5. 包设置 → Publishing access → 「Require two-factor authentication and disallow tokens」。

合并后不要立刻推 tag:先完成第 1、2 步,否则 CI 会 ENEEDAUTH。

npm 将于 2027-01 取消 bypass-2FA token 的直接发布能力。发布 job 去掉 NODE_AUTH_TOKEN 与 setup-node 的 registry-url,改用 OIDC 身份;首发由维护者本机交互式发布,之后登记 trusted publisher。完整发版步骤与失败处理落到 .telov/skills/release。
@telov-review-bot

Copy link
Copy Markdown
Contributor

审查结论(head c335f13)

1 条阻断:首发流程第 3 步会走空,「2 天内完成首次 OIDC 发布」这一步实际不发布任何东西,trusted publisher 配置 2 天后静默过期。
4 条建议(npm@latest 未 pin、工具名门禁不扫 .telov/skills、发布包黑名单没有 .telov/、registry-url 的理由缺来源),3 条可忽略。

workflow 代码本身没查出问题;PR 里关于 npm 的版本号、权限位置、Allowed actions、包必须已存在等断言,逐条对 npm 官方文档核过,全部成立。唯一实质问题是文档与幂等守卫的交互。


阻断

B1 首发流程第 3 步不会触发任何 OIDC 发布,配置会过期

  • PR 正文「合并后需要你本机执行」第 3 步:2 天内推 v0.1.0 tag 完成首次 OIDC 发布。
  • .telov/skills/release/SKILL.md:89 同一条:5. **2 天内**推一个 v* tag 完成首次 OIDC 发布。
  • 但第 1 步已经在本机 npm publish 发了 0.1.0(SKILL.md:82),而 .github/workflows/publish.yml:74-77 的守卫是「版本已存在就跳过」:
if npm view "${name}@${version}" version >/dev/null 2>&1; then
  echo "${name}@${version} 已发布,跳过 npm publish"
  exit 0
fi

所以推 v0.1.0 时实际发生的是:tag/版本校验过 → npm view 命中 → 打印「已发布,跳过 npm publish」→ exit 0 → 只建了个 GitHub Release。OIDC 发布一次都没跑,trusted publisher 没被验证,2 天后过期(SKILL.md:99 自己就把「配置是否已过期」列成了失败态)。

实测(/tmp,同一段 if 结构 + 一个确实已发布的版本):输出 已发布,跳过 npm publish,退出码 0。分支可静态追踪,结果确定。

影响:首次迁移此坑必然踩到,且没有任何提示;唯一症状是 2 天后第一次真实发布报 ENEEDAUTH/403,届时只能删掉配置重配(配置本身有 2 天窗口,删了又要重新开始一轮)。

修法(改文档即可,不用动 workflow):把「验证发布」明确落到一个未发布的版本上,例如

  1. 本机发 0.1.0;
  2. npmjs.com 登记 trusted publisher;
  3. npm version patch --no-git-tag-version 得 0.1.1,走 PR 合并;
  4. 从 main 推 v0.1.1 —— 这一版 registry 上还不存在,CI 会真发,配置得到验证,provenance 也从这版开始。

对应把 SKILL.md:89 与 PR 正文第 3 步改成「推 v0.1.1(首发之后的下一版)」,并说明为什么不能推 v0.1.0。publish.yml:68-69 的注释其实已经把幂等语义写清楚了,问题只在文档没跟它对齐。


建议

S1 npm install -g npm@latest 未 pin(publish.yml:61)

发布链路的工具链由上游决定:@latest 指向哪版、哪版改了 OIDC/--tag 行为,都不由本仓控制。这与同一份 workflow 把 actions/* pin 到 SHA 的规矩(:26、:54)不一致。建议 pin 到具体版本(如 [email protected] 或 12.2.x),并在注释里写「选它是为了 OIDC 下 dist-tag 的下限」。本机 npm 是 11.19.1,正好低于 11.21 —— 说明这条下限是实存的,不是纸面数字。

S2 工具名门禁扫不到 .telov/skills/**(scripts/doc-tool-names.mjs:14-16)

该门禁的注释说「只覆盖会进会话提示词的三处」,但实际扫描面是 PROMPT_DOCS = ['SLOTS.md','LEADER.md'] + PROMPT_SKILLS_DIR = '.agents/skills'。.telov/skills 同样是会被注入会话的 skill 目录——本次会话的可用 skill 列表里就有 release。因此 .telov/skills/release/SKILL.md 里写错 bundle 工具名,npm run check 不会报,verify-doc-tool-names: 11 篇 也照旧全绿。

今天这篇只写了 npm/gh/git,没有实际违规;建议把 .telov/skills/** 并进 markdownFiles() 的扫描面,否则这条门禁的自述前提已经不成立了。

S3 发布包黑名单里没有 .telov/(scripts/pack-manifest.mjs:32-47)

.agents/ 走的是正向允许面(只放行 .agents/skills/),而 .telov/ 在 FORBIDDEN_PATTERNS 里没有任何条目。今天靠 package.json 的 files 白名单兜住——我实测 npm pack 解包,86 个文件里 .telov/、docs/、tests/ 都是 0 条。但 files 一旦放宽(.agents/ 当初就是这么漏的),发版手册会静默进用户的 node_modules,verify:pack 也不会报。建议加一条 forbidden 规则或做成允许面。

S4 删 registry-url 的理由缺来源(publish.yml:52-53、Note「决策」第 2 段)

理由本身站得住,我核了 setup-node pin 的那个 SHA(949feb2)的 src/authutil.ts:registry-url 会让它往 RUNNER_TEMP/.npmrc 写 //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN},并 exportVariable('NPM_CONFIG_USERCONFIG', …);只有 process.env 里本来就有 NODE_AUTH_TOKEN 时才 export 变量。变量没设时该值是空串,npm 把它当成「认证已配置」,OIDC 交换不发生(actions/setup-node#1551、npm/cli#9088 有多份 2026 年的实测同一结论)。删掉也安全——registry 默认就是 npmjs。

但 npm 官方 trusted publishing 文档的示例仍然带 registry-url: 'https://registry.npmjs.org'(配 package-manager-cache: false)。读者对着官方文档看,会觉得本仓的理由与官方示例矛盾。建议在 Note 里补一句来源,说明「官方示例仍保留,但 setup-node 写的 .npmrc 会先于 OIDC 被读到」,别让这个正确结论看起来像是拍脑袋。


可忽略

  • contents: write 是 workflow 级(publish.yml:13),实际只有最后一个 gh release create 用得上。拆 job 才能收紧权限面,当前不影响正确性。
  • --provenance(:80)在 trusted publishing 下是自动的——npm 文档明说会自己生成并上传;显式传冗余但无害,留着当自述也可以。
  • 预发布 --tag next 是否需要在 npm 里额外勾 Allow npm dist-tag:文档只写「dist-tag 操作」需要(默认关闭),publish --tag 属于 publish 负载还是独立的 dist-tag 操作,我未能在文档里确证。PR 已让预发布场景勾上,方向是安全的。待确认。

已核实成立的断言

PR 中的断言 核对结果
OIDC 发布需 npm CLI ≥ 11.5.1、Node ≥ 22.14.0 成立;workflow node-version: 24 满足
OIDC 下切 dist-tag 需 11.21 / 12.2 成立,数字与官方一致
需要 id-token: write,可放 workflow 级 成立;官方示例就是 workflow 级,publish.yml:14 同形
Allowed actions:npm stage publish 恒允许、npm publish 需勾、npm dist-tag 默认关闭 成立;SKILL.md:88 的指引正确
新建配置 2 天内必须完成首次成功发布 成立(问题在于「成功发布」被幂等守卫跳过,见 B1)
包必须在 registry 上已存在才能登记 trusted publisher 成立;SKILL.md:79 的前提正确
provenance 在 OIDC + 公开仓库 + 公开包下自动生成 成立

未验证

  • OIDC 发布路径本身:包还没上 npm、没有 trusted publisher 配置,跑不起来。Note 与 PR 正文都明写了这一点,没有把未验证说成已验证。
  • npm install -g npm@latest 在 GitHub runner toolcache 上的写权限:本机模拟不了。
  • 预发布 --tag 的权限边界(同上「待确认」)。

复跑读数(worktree head c335f13)

  • npm run check 全绿:verify-agent-note-format: 65 篇、verify-doc-tool-names: 11 篇、verify-doc-budgets: 13 篇、check-syntax: 96 个文件、verify-coverage: 975 用例通过(16 跳过)。
  • npm run build:client + npm run verify:pack:86 个文件(未压缩 994 kB),必需项齐全、无开发残留,装机 smoke 通过。
  • 文档预算:AGENTS.md 3846 / 4280(余 434,10.14%,满足 10% 规则)、docs/limitations.md 6312 / 6750(6.5%)、docs/development.md 2372 / 2500(5.1%,满足 5%)。
  • 全仓 workflow 已无 NODE_AUTH_TOKEN / NPM_TOKEN / 生效的 registry-url,只剩两处解释性注释(:52、:66)。
  • npm pack 解包:.telov/ 未进包。
  • tests/skills.test.js:17 断言 .agents/skills 名单恰为 ['init-project','leader-mode'] —— 印证「发版手册放 .telov/skills,不随包发布」这个取舍是对的。

结论:B1 改掉文档后可以合并(B1 是文档不一致,不是代码缺陷)。不 approve、不 merge,等你的指令。

- 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 的理由)与门禁读数
@telov-review-bot

Copy link
Copy Markdown
Contributor

增量复审(head 2fc06a3)

五处逐条:B1 与四条建议的修复全部成立,探针双向验证都真红。新查出 2 条读数问题(1 条建议-中、1 条建议-低),都不影响修法本身。


1. B1 首发流程:成立

SKILL.md:77-93 改成 7 步,核心是第 5 步「bump 到一个未发布的版本(如 0.1.1),PR 合并后从 main 打 v0.1.1 tag」。

  • 守卫不会命中 0.1.1:publish.yml:74 的 npm view "${name}@${version}" 对未发布版本返回非 0,if 走 else 分支继续发布。实测(同一段 if 结构,name=dsh-leader-kit、version=0.1.1):输出 PROCEED 会执行 npm publish。(当前 registry 上整个包都还是 E404,首发 0.1.0 之后 0.1.1 同样 E404 —— 单版本 404 与包 404 对 npm view 都是非 0,分支行为一致。)
  • SKILL.md:93 与代码逐句对得上:文档说「守卫会打印『已发布,跳过 npm publish』并 exit 0」→ publish.yml:75-76 正是 echo "${name}@${version} 已发布,跳过 npm publish" + exit 0;说「workflow 整体绿色」→ 该分支退出码 0,job 继续走建 Release;说「CI 读数看不出区别」→ 唯一区别是那行 echo,与 npm notice Publishing 不同。文档没夸大也没漏。
  • SKILL.md:90 的判据可用:实测 npm publish --dry-run 输出 npm notice Publishing to https://registry.npmjs.org with tag latest and public access,成功路径确实有这一行,可以用来区分「真发了」和「被跳过」。
  • dist-tag 两条路径都成立:publish.yml:79-80 用 case "$version" in *-*) tag=next ;; esac,正式版 → --tag latest,预发布(0.2.0-rc.1)→ --tag next,不会把 rc 顶到 latest;SKILL.md:27 与 docs/development.md 的说法一致。

2. npm pin:成立

  • [email protected] 在 registry 上真实存在,engines = { node: '^20.17.0 || >=22.9.0' } —— workflow 的 node-version: 24 满足,没有引入 Node 24 不兼容。
  • 两个门槛同时满足:OIDC publish 要 ≥ 11.5.1 ✓;OIDC dist-tag 要 ≥ 11.21 / 12.2 ✓(11.21.0 恰好压在 11.x 的下限上,正好覆盖两条路径)。
  • 注释(publish.yml:60-62)的理由成立且与 actions/* pin SHA 同源:发布前不从浮动 tag 拉代码、npm 版本不可回收。

3. 工具名扫描面:成立

  • doc-tool-names.mjs:24 改 PROMPT_SKILLS_DIRS = ['.agents/skills', '.telov/skills'],verify-doc-tool-names.mjs:35 用 flatMap 展开后排序;读数 12 篇(原 11 + .telov/skills/release/SKILL.md),与实测一致。
  • 探针 A1:把常量回退成 ['.agents/skills'] → tests/doc-tool-names.test.js:107 的 assert.ok(docs.some(...)) 变红(actual false / expected true)。
  • 探针 A2:常量保留、把脚本里改成字面量 ['.agents/skills', '.telov/skills'].flatMap(...) → :114 的 assert.match(source, /PROMPT_SKILLS_DIRS\.flatMap/) 变红。两条断言各管一件事,都能真红。
  • 还原后两文件 22 例全绿。

4. 打包黑名单:成立

  • pack-manifest.mjs:37 加 /^\.telov\//;verify:pack 86 文件 994 kB + smoke 通过,npm pack 解包后 tarball 内 .telov 条数 0。
  • 探针 B1:撤掉该规则 → tests/pack-manifest.test.js:155 报 AssertionError: .telov/skills/release/SKILL.md 应被拦下。
  • 探针 B2(端到端):保留规则、把 package.json 的 files 放宽成含 ".telov/**" → npm run verify:pack 退出 1,报 不该进包:.telov/skills/release/SKILL.md。这证明它真的是白名单之外的第二道防线,不是摆设。

5. 复跑读数

  • npm run check 全绿:note-format 65 篇、doc-tool-names 12 篇、doc-budgets 13 篇、check-syntax 96 个文件、coverage 977 用例通过(16 跳过)、68 源文件 / 53 加载 / 45 行覆盖 100% / 15 登记不可加载。
  • 预算:AGENTS.md 3846 / 4280(余 434,10.14%);docs/limitations.md 6312 / 6750(6.5%);docs/development.md 2379 / 2500。
  • npm run verify:pack:86 文件 994 kB,装机 smoke 通过。

本轮新发现

建议-中:docs/development.md 余量掉到 4.84%,低于本仓的 5% 规矩

改后实测 2379 / 2500,余量 121 字 = 4.84%。AGENTS.md 的文档分层规则要求天花板「按当前值留至少 5% 余量……不贴线」,改前是 2372 / 2500(5.1%),这一轮又涨了 7 字就压线了。verify-doc-budgets 只判「不超限」,所以门禁照旧绿——靠规则而不是门禁守。

同时 Note「验证」段与「边界」段仍写 2372 / 2500(余量 5.1%),是改动前的读数,没回填。

修法二选一:压缩 ≥7 字回到 5% 以上(2373 及以下),或把天花板抬到 2510(2379 × 1.05 ≈ 2498,抬 10 字即 5.2%),并按规矩在 PR 里写清抬的理由;两种都要同步 Note 里的读数。

建议-低:Note 验证段用例数写 976,实测 977

.agents/notes/2026-11-03-npm-oidc-publishing.md 验证段第 1 条写「976 用例通过(16 skip)」,实测 977(两个新测试文件 +19 例,作者算少了 1 例)。顺手改正即可。

可忽略

  • markdownFiles() 遇到不存在的目录会抛 ENOENT:若将来 .telov/skills/ 被删,npm run check 会以 ENOENT 崩而不是友好提示。Fail Loud 的方向没错,只是报错信息不指向「扫描面少了一个目录」。
  • 「脚本必须复用该常量」这条 meta 断言用正则匹配源码写法:改成 PROMPT_SKILLS_DIRS.map(...) 之类的等价写法仍能绕开。目的(防止扫描面分叉)达到即可。
  • npm view 若因网络抖动失败,守卫会误判成「未发布」继续 publish,撞上「版本已存在」报 403/EPUBLISHCONFLICT。失败是响的,不影响正确性。
  • 预发布 --tag next 是否需要在 npm 里额外勾 Allow npm dist-tag:与上一轮相同,文档没把 publish --tag 与独立 dist-tag 操作区分清楚,我未能确证。PR 已让预发布场景勾上,方向安全。待确认(唯一遗留项)。

结论:B1 与四条建议的修复全部成立,两条新发现的读数问题都是文档层面的小修(development 预算余量、Note 用例数),改完可合并。不 approve、不 merge。

@fengshenx
fengshenx merged commit 225388e into main Nov 3, 2026
2 checks passed
@fengshenx
fengshenx deleted the feature/release-oidc branch November 3, 2026 08:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant