CONTRIBUTING.md 的 Documentation 一节有两处与仓库现状不符:门禁描述指错工具/触发条件,"✅ 正确链接示例" 里 3 条路由是死的

[yinlianghui]

修 #3545(PR 见该单)时在同一节的相邻散文里读到的,按 Prime Directive #10 未在那个 PR 里改(越界),另立本单。两处都不是死链(#3545 的那一类),所以 #3545 的修复不覆盖它们。

1. CONTRIBUTING.md:467 — 门禁描述把工具和触发条件都说反了

现文:

Link validation runs automatically via GitHub Actions on all PRs using lychee-action. This checks for broken internal and external links.

与现状对不上:

• .github/workflows/check-links.yml(lychee)的触发器只有 workflow_dispatch + 每周 cron 17 4 * * 0,不在 PR 上跑。该文件自己的头注释还明确写了 "⛔ Do NOT enable the two triggers below — pnpm docs:check-links 在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213's ruling B still stands",即 PR 触发是被有意排除的;
• 真正 gate PR 的是 scripts/check-doc-links.mjs,由 .github/workflows/docs-links.yml 在 pull_request: [main, develop] 上跑。check-links.yml 的头注释也是这么写的:"Site-internal routes (/docs/...) are a different problem with a different tool — scripts/check-doc-links.mjs, run by docs-links.yml, which ... is therefore the one that gates pull requests."

也就是说这一句把周扫的外链检查说成了PR 门禁,又把真正的 PR 门禁完全略去了。贡献者据此会以为外链坏了会拦住自己的 PR(不会),也不知道 pnpm docs:check-links 才是本地要跑的那个。

2. CONTRIBUTING.md:441-445 — 标着 "✅ Correct Link Patterns" 的示例里有 3 条路由不存在

那个代码块里 5 条示例,用仓库自己的判定器(scripts/check-doc-links.mjs 的 routeExists() + collectSiteRoutes())跑一遍:

OK   /docs/guide/quick-start
OK   /docs/components
DEAD /docs/reference/api/core
DEAD /docs/reference/protocol/overview
DEAD /docs/architecture/component

content/docs/ 下没有 reference/、也没有 architecture/ 目录(实有:api、blocks、components、core、fields、guide、layout、plugins、rfcs、utilities)。更尴尬的是紧接着的 "❌ Incorrect Link Patterns" 块里,把 /spec/component 的"正确写法"注成 /docs/architecture/component、把 /api/core 注成 /docs/reference/api/core —— 教的是同样不存在的路由。

为什么门禁抓不到: 这些示例在 ```markdown 围栏里,而 check-doc-links.mjs 在扫描前会 `stripCode()` 掉围栏块(这是必需的,见该文件 "Code spans are stripped before scanning" 一节)。所以即便第 2 步把 `CONTRIBUTING.md` 纳入 `SCAN_ROOTS`(#3545 提的),这 3 条也仍然扫不到 —— 它们落在围栏这个结构性盲区里。这一点值得记一笔:文档里"举例说明正确写法"的链接天然免疫链接门禁,而它们恰恰是最容易被照抄的。

复现(只读,离线)

node -e '
import("./scripts/check-doc-links.mjs").then(async (m) => {
  const path = await import("node:path");
  const site = m.collectSiteRoutes(path.join(process.cwd(), "apps", "site"));
  const ctx = { fromFile: path.join(process.cwd(), "CONTRIBUTING.md"), docsRoot: path.join(process.cwd(), "content", "docs"), site };
  for (const h of ["/docs/guide/quick-start","/docs/components","/docs/reference/api/core","/docs/reference/protocol/overview","/docs/architecture/component"])
    console.log(m.routeExists(h, ctx) ? "OK  " : "DEAD", h);
});'

建议

1. 第 1 处:把这句改成如实描述 —— PR 上跑的是 docs/check-doc-links(docs-links.yml),lychee 是周扫的外链检查、不 gate PR;顺带给出本地命令 pnpm docs:check-links。
2. 第 2 处:把 3 条死路由换成真实存在的等价页面,或直接换成两条已验证 OK 的示例。改之前建议先确认 /docs/reference/*、/docs/architecture/* 是曾经存在后来搬走还是从来就是虚构的 —— 如果是前者,别处可能还有同样的引用。

关联

#3545(同一节相邻的 3 条死链,已修)、#3536 / PR #3542(扫描面扩展)、#3213(lychee 不 gate PR 的裁定)、#3543(另一份文档的过期陈述,不同文件)。

⚠️ 本单未认领,留给 PM 分诊。

[yinlianghui]

认领(PM 分诊晋级;串行条件已满足 —— 同文件的 PR #3571 已落 main)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3570-contrib-stale-claims。

分诊裁定:两处都修 —— (1) :467 的 lychee 假声明改写为真实门禁分工(PR 门禁 = check-doc-links.mjs 经 docs-links.yml;lychee = 周 cron + 手动、continue-on-error,#3213 有意取舍);(2) "✅ Correct Link Patterns" 围栏里三条被 routeExists() 判死的示例路由,换成真实存在的路由(以检查器当前路由表为准逐条验证)。⚠️ 这三条在代码围栏内、stripCode 盲区,修完也没有门禁看得见 —— 在该节加一句"示例路由如有变动请手动核对"的诚实提示,不为它造新门禁。

文件面:CONTRIBUTING.md(仅 Documentation 节那两处)。与同批在飞的 #3572(改检查器脚本)零文件相交。越界即停。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3585。

核过 GitHub 实物(恰 1 文件,+22/-10)。裁定要点:

1. 纠正了派单的机制错述:lychee 并非 continue-on-error,而是 fail: true(周跑会红,但从不上 PR)—— 结论相同、机制不同,dev 按实测改写而非照抄派单,记为好运行。改写后的门禁分工每句带 workflow 行号锚点,且按机制而非枚举描述扫描面(check-doc-links 扫描面第三扩:CONTRIBUTING.md + ROADMAP.md + docs/**(实测 70 链接、今日零死链、纯配置三行) #3572 扩面后此段免改)。
2. ✅/❌ 双块一并修的超裁定偏离背书:❌ 块把"正确写法"注成同样的死路由,只修一块必然自相矛盾;正反两向都逐条用检查器 oracle 验证("错误示范"也必须真的死 —— 否则误导反向)。
3. 考古闭环:三条死路由确曾存在(旧 commit 的 git ls-tree 列出实体文件),全仓仅剩的 6 处引用恰是本 PR 改掉的 6 行 —— 无残留跟进。
4. 前瞻模拟不给并行单埋雷:内存中预演 check-doc-links 扫描面第三扩:CONTRIBUTING.md + ROADMAP.md + docs/**(实测 70 链接、今日零死链、纯配置三行) #3572 的扩面,CONTRIBUTING 零 broken —— 两单并行协调闭环。
5. stripCode 盲区实测确认(15 条存活链接里无示例块路由),诚实提示句已加,未造新门禁。
6. 第三处过期陈述("All docs are in docs/")→ CONTRIBUTING.md:414 「All docs are in docs/」与现状不符 —— 站点文档实际在 content/docs/,docs/ 是内部树 #3584,已核存在;⚠️ 同文件,docs(contributing): 按现状改写链接门禁分工,换掉三条死的"正确示例"路由 (#3570) #3585 合并前不派。

PR 转 ready + auto-merge。

---

Generated by Claude Code