docs(contributing): 按现状改写链接门禁分工,换掉三条死的"正确示例"路由 (#3570)

[yinlianghui]

Fixes #3570

只动 CONTRIBUTING.md 的 Documentation 一节。与同批在飞的 #3572(改 scripts/check-doc-links.mjs)零文件相交。

1. Validating Links —— 门禁描述与现状对不上

原文一句话把周扫的外链检查说成了 PR 门禁,又把真正的门禁完全略去。改写为如实的分工,每条都对着当前 workflow 文件核过:

断言	出处(本 PR 基线 632c07c5b)
PR 门禁 = scripts/check-doc-links.mjs,由 docs-links.yml 跑	.github/workflows/docs-links.yml:26-27(pull_request: branches: [main, develop])、:61-62(run: node scripts/check-doc-links.mjs)
离线、只读 checkout	docs-links.yml:54-56 头注释 "Reads the checkout and nothing else, so no install is required"
无 paths 过滤 → 纯文档 PR 也被检查	docs-links.yml:18-19,并由 scripts/__tests__/docs-links-workflow.test.ts 钉住
lychee 只有 cron + 手动,从不上 pull_request	.github/workflows/check-links.yml:21-36(workflow_dispatch + schedule: '17 4 * * 0')、:38-48(两个触发器被注释掉并标 "⛔ Do NOT enable … #3213's ruling B still stands")
本地命令 pnpm docs:check-links	package.json:45

一处与派单描述的偏差,已按实测写: 派单说 lychee 是 continue-on-error。它不是 —— check-links.yml 全文没有 continue-on-error,只有 fail: true(:76-77)。所以我写的是「它确实会让自己那次定时运行变红,只是从不让你的 PR 变红」,而不是「continue-on-error」。这两种说法的门禁结论相同,但机制不同,照抄会成为下一个过期陈述。

按派单要求按机制描述、不枚举扫描面:结尾一句把「哪些文件被扫」指回 SCAN_ROOTS 表和 check-links.yml 的 args,所以 #3572 把扫描面从 3 根扩到 6 根之后,这段散文不需要跟着改。

2. ✅ Correct Link Patterns —— 三条死路由

用检查器自己的 routeExists() + collectSiteRoutes() 逐条验证(#3571 的探针法,离线只读):

--- 教作"正确"的路由(必须全 OK)---
OK   /docs/guide/quick-start        (保留)
OK   /docs/components               (保留)
OK   /docs/api/schema-reference     (换掉 DEAD /docs/reference/api/core)
OK   /docs/core/app-schema          (换掉 DEAD /docs/reference/protocol/overview)
OK   /docs/guide/architecture       (换掉 DEAD /docs/architecture/component)
--- 教作"错误"的路由(必须全 DEAD)---
DEAD /guide/quick-start
DEAD /components
DEAD /reference/api/core
DEAD /architecture/component
DEAD /spec/app

两个方向都验了:正例真的能解析,反例真的死 —— 否则「反面教材」会意外指向一个能用的路由。

顺带改了紧邻的 ❌ Incorrect 块(派单文件面之内,但比 PM 裁定多一处,故显式说明):它原先把 /api/core 的"正确写法"注成 /docs/reference/api/core、把 /spec/component 注成 /docs/architecture/component —— 教的是同样不存在的路由(issue 正文已点名)。不改它,新的 ✅ 块会和紧挨着的 ❌ 块自相矛盾。现在那三条死路由改作反面例子本身:/reference/、/architecture/、/spec/ 这三个顶层段确实不存在于 content/docs/,正好是这次错误的历史来源。

issue 问的「曾经存在还是从来虚构」:曾经存在。 git ls-tree ce779c7ea -- docs/reference docs/architecture 列出 docs/reference/api/core.md、docs/reference/protocol/overview.md、docs/architecture/component.md 等 20 个文件 —— 是历次文档重构搬走的。但全仓已无第二处引用:grep -rn '/docs/reference/\|/docs/architecture/'(排除 node_modules)命中 6 行,全部在 CONTRIBUTING.md 本文件内,即本 PR 改掉的这 6 行。没有"别处还有同样引用"要跟进。

3. 一句诚实提示,不造门禁

这些示例写在 markdown 代码围栏里,而 stripCode() 在扫描前把围栏块和行内代码抹成空格(这是必需的,见该文件 "Code spans are stripped before scanning" 一节),所以即便 #3572 把 CONTRIBUTING.md 纳入 SCAN_ROOTS,这些示例路由仍然没有任何门禁看得见。实测确认:对本文件跑 stripCode() 后只剩 15 条链接,示例块里的路由一条都不在其中。

按 PM 裁定加了一句提示要求改动时手工核对,未为它造新门禁。

验证

$ node scripts/check-doc-links.mjs
Links are valid across 3 scan roots.                      # exit 0

$ node scripts/check-control-bytes.mjs
check-control-bytes: OK (scanned 3631 tracked text file(s); skipped 85 binary).

$ pnpm exec vitest run scripts/ --maxWorkers=2
Test Files  16 passed (16) / Tests  275 passed (275)

SCAN_ROOTS 在本 PR 基线上仍是 3 根(content/docs、examples、README.md)—— #3572 尚未合并,所以本文件此刻还不在扫描面内,上面的 exit 0 并不代表它被验过。为此额外做了前瞻模拟:在内存里往 SCAN_ROOTS 追加 { path: 'CONTRIBUTING.md', rule: 'disk' } 再跑 collectBrokenLinks(),结果 0 broken —— 即本 PR 不会给 #3572 埋雷。#3572 若先落地,重跑真实门禁即可。

无 changeset(根目录文档,非 packages/ 用户可见变更)。未触碰 content/docs/releases/。

越界记录

同一节 CONTRIBUTING.md:414「All docs are in docs/」也已过期(站点源是 content/docs/,见 apps/site/source.config.ts:6;根 docs/ 是 ADR/审计内部树)。不在本单文件面内(PM 裁定只授权那两处 + 一句提示),按 Prime Directive #10 未在本 PR 修,查重后另立 #3584(未认领,留给 PM 分诊)。

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 2:41pm