ci(docs): check-doc-links 提升为无路径过滤的独立 workflow，纯 docs PR 也拦得住断链 (#3448)

[yinlianghui]

Fixes #3448

按 PM 裁定采方案 A：把 node scripts/check-doc-links.mjs 提升为独立 workflow，无任何路径过滤，镜像 control-bytes.yml 的形状（触发集、最小 checkout、头注解释为什么不能加过滤）。裁定与「形式上偏离维护者 08-03 对 #3213 的『加进 ci.yml 的 docs 任务』原话」的理由已在单上论证：#3448 (comment) —— 那个裁决作出时结构洞尚未被发现，其意图（内链断裂 = 硬门禁）在字面落法下对纯 docs PR 恰好失效。

问题（已在 origin/main 上复核）

ci.yml 的 paths-ignore 两处都列着 '**/*.md'、content/**、docs/**、apps/site/**；站点文档全在 content/docs/**。GitHub 的语义是「改动文件全部命中即整个 workflow 不启动」，且没有 per-job path filter —— 所以只改文档的 PR 根本不启动 ci.yml，#3450 加的那一步自然也不跑。它此前只覆盖「文档+代码」混合 PR 与 push 到 main。

改动

• 新增 .github/workflows/docs-links.yml：push / pull_request to main+develop 加 workflow_dispatch，既无 paths 也无 paths-ignore；checkout + setup-node + 一行 node scripts/check-doc-links.mjs。无 install、无网络、几秒钟。头注写清为什么路径过滤在这里是错的（paths: content/** 看着更紧，实则只是脚本扫描面的第二份副本，会各自漂移）。
• 从 ci.yml 的 docs job 删掉重复步骤 —— 这一处按最小重复原则由实现者定，我选删：新 workflow 的触发集是该 job 的严格超集（同样的 main/develop，且无过滤），保留只会为同一条坏链多出一个红勾、多一处会忘记同步的副本。原地留注释说明它去哪了、为什么别加回来；那段已失效的 KNOWN GAP 注释一并删除（留着就是假话）。
• 新增 scripts/__tests__/docs-links-workflow.test.ts：workflow 必须存在、必须门禁 PR、必须既无 paths 也无 paths-ignore、必须是唯一跑该脚本的 workflow。最后一条钉的是去重决策本身——把副本加回某个带路径过滤的 workflow，正是会重新制造「看着有覆盖、实则纯 docs PR 照样溜过去」的那个具体错误。扫描前先剥掉整行注释：ci.yml 的说明注释里仍提到脚本名，不剥会误报重复门禁。

⚠️ 越界说明：content/docs/guide/ci-cd-pipeline.md

派单文件面把 content/docs/** 列为禁止面。这一条我越了界，因为它不是顺手改文档，而是既有门禁的机械要求：scripts/__tests__/ci-cd-pipeline-doc.test.ts 读 .github/workflows/ 目录，任一 workflow 在该页没有点名标题就红。先加 workflow、不改文档，实测：

AssertionError: These workflows exist in .github/workflows/ but no heading in
content/docs/guide/ci-cd-pipeline.md names them:
  - docs-links.yml

该页自己的「Adding a New Workflow」也写着「Give it a section on this page in the same PR. Not a convention — a test.」。改动限于四处必要更正：清单表一行、新章节、ci.yml 任务表里 docs 行的更正（它不再跑链接检查）、Link Checking 章节里 #3448 那个「已知缺口」的收口（#3449 那个仍在）。如维护者认为该越界不可接受，我可以拆出去，但那样本 PR 必然是红的。

与在飞 PR #3456 的交叉：#3456（#3451）同样在改这个文件与 ci-cd-pipeline-doc.test.ts。两边不冲突的部分：它改 ci.yml 行与 dev-server 幽灵行，我加 docs-links.yml 行与新章节；可能冲突的一处是任务表里 docs 行——我改了它的内容，而它紧邻 #3456 删掉的 dev-server 行。两处修改都是有意的，谁后合谁 rebase 时按此说明取并集即可。#3456 不动 ci.yml，故 workflow 侧零交叉。

验证

• python yaml.safe_load 两个 workflow 均解析通过；docs-links.yml 的触发集实测为 {'pull_request': {'branches': ['main','develop']}, 'push': {'branches': ['main','develop']}, 'workflow_dispatch': None} —— 没有任何 paths 键。
• node scripts/check-doc-links.mjs → Docs links are valid. (exit 0)
• pnpm exec vitest run scripts/（仓库根，规范调用）→ 9 files / 127 tests passed
• node scripts/check-control-bytes.mjs → OK（3648 文件）；另对本 PR 四个文件做了越出门禁的自扫 grep -naP，无命中。
• 反向验证（方向先判后跑，两次均如期）：把删掉的步骤加回 ci.yml → 新测试两处红（is the only workflow that runs the link checker 实得 ['ci.yml','docs-links.yml']；every workflow that runs it is one a docs-only PR can start 点名 ci.yml 的 paths-ignore）。给 docs-links.yml 加 paths: content/** → carries NO path filter of any kind 红。

诚实的覆盖面说明：本 PR 改的是 .github/**，所以它自己既会启动 ci.yml、也会启动新 workflow —— 绿灯只证明「workflow 能在 PR 上跑通」，证明不了「纯 docs PR 会启动它」，后者只能由将来某个只改 markdown 的 PR 实证。能在此刻担保它的，是配置本身：on.pull_request 只有 branches，没有 paths/paths-ignore 两个键中的任何一个（YAML 解析结果如上），而 GitHub 只在存在过滤键时才做路径判断。这一条同时由上面那条测试机械看守。

未做的事

• 无 changeset：纯 CI 配置，不影响任何包的产物（先例 fix(test): 拒绝两种静默假绿的 vitest 调用,并把正确跑法写进 AGENTS.md #3437 / ci(docs): 把 check-doc-links 接进 CI,并修好它一直在报的那条坏链 (#3213, #3292) #3450）。
• scripts/ 的 type-check 覆盖（单上相邻观察）→ 建议拆单，不顺路。理由不是错误多（实测 tsc --noEmit --strict 跑 scripts/**/*.ts 只有 3 个报错，且全是 .mjs/.js 无声明文件的 TS7016 与一处随之失效的 TS2578），而是落点全在本 PR 之外：(1) 它需要 install（typescript + @types/node + vitest 类型），而新 workflow 的全部设计前提是「无 install、无网络、几秒」，还被我的测试钉住了——把 tsc 塞进去等于让纯 docs PR 去等一次完整安装，与 paths-ignore 想省的正是同一笔开销；正确的家是 ci.yml 的 type-check job（那里已有 install 与 turbo 缓存）。(2) 需要为 scripts/ 决定一个 tsconfig（并入根 include？独立 tsconfig？）并与 check-type-check-coverage.mjs（按 包 判定覆盖，而 scripts/ 不是包）对齐。(3) 选定的 allowJs/checkJs 会机械地改变现有测试里 @ts-expect-error 的成立与否，从而必须改动既有测试文件——其中 ci-cd-pipeline-doc.test.ts 正被 docs(ci): 删掉 ci.yml 任务表里的幽灵 dev-server 行，并给任务表加双向 pin (#3451) #3456 占用。三处都在本单文件面之外，硬塞进来就是替维护者做架构决定。查重未能完成：GitHub 搜索/列表 API 对本账号已限流（API rate limit already exceeded），与 ci-cd-pipeline.md 的 ci.yml job 表格漂移:写「Seven jobs」并列了一个不存在的 dev-server job(实际 6 个) #3451 的 dev 撞的是同一堵墙，故按 #4949 纪律不盲目立单，留给 PM 立（该观察已记在 check-doc-links 挂在 ci.yml 的 docs job 上,对「纯 docs PR」永远不会触发(paths-ignore 含 content/**) #3448 评论里，不会丢）。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 6, 2026 6:52am