content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接)

[yinlianghui]

在 #3479 / PR #3489(把 scripts/check-doc-links.mjs 扩到相对链接)过程中顺手发现,记在这里由 PM 定级。不在 #3479 的完成范围内:#3479 的口径是 lychee 实测的 16 个目标 / 33 处引用,那批已在 PR #3489 修完并且门禁绿了;下面这 18 条 lychee 与扩展后的 checker 都判绿,因为两者都只做「文件系统能否解析」,而这 18 条的问题是「站点路由不存在」。

根:门禁只在 docs collection 内解析

check-doc-links.mjs 现在校验两类 href —— 相对 href(按源文件目录解析)与绝对 /docs/...(按路由解析)。其余绝对 href 一律放行,因为从 content/docs 无从判断 apps/site 的路由表。这是当时的有意取舍,不是疏漏;但代价是下面两类实际 404 无人拦。

A. 1 条相对链接跑出了 collection

content/docs/guide/data-source.md:202

[adapter README](../../../packages/data-objectstack/README.md#cross-object-atomic-batch-batchtransaction)

文件在磁盘上真实存在,所以 lychee --offline 和扩展后的 checker 都判绿。但站点侧解析不了:fumadocs 的 source.resolveHref 只能在 docs collection 的页面索引里查,packages/** 不在其中,于是 href 原样落到浏览器。

构建产物实证(apps/site/.next/server/app/docs/guide/data-source.html):

href="../../../packages/data-objectstack/README.md#cross-object-atomic-batch-batchtransaction"

页面 URL 是 /docs/guide/data-source,浏览器相对解析后落到 /packages/data-objectstack/README.md —— 站上无此路由,404。

B. 17 条非 /docs 绝对链接指向不存在的路由

apps/site/app/ 下的路由段只有:(home)、docs、playground、og、llms.mdx、api/search(route handler)。没有 spec、protocol、examples;next.config.mjs 只有一条 /docs/:path*.mdx 重写,仓库里也没有 vercel.json。所以下列全部 404:

文件	href
guide/component-registry.md	/spec/component-package.md、/spec/component.md、/api/core、/api/react
guide/schema-rendering.md	/spec/schema-rendering、/spec/architecture、/protocol/overview、/api/core、/api/react
guide/expressions.md	/protocol/overview、/protocol/form、/protocol/view、/api/core
guide/fields.md	/protocol
guide/plugins.md	/spec/component-package.md
guide/objectos-integration.mdx	/examples/crm、/examples/kitchen-sink

构建产物实证:.next/server/app/docs/guide/plugins.html 里是 href="/spec/component-package.md",.../expressions.html 里是 href="/protocol/overview" 等 —— 原样输出。

(同一批里的 3 条 /img/guide/dashboard-filters/*.png 是好的:apps/site/public/img/guide/dashboard-filters/ 下三个文件都在。)

顺带一提,/spec/component-package.md 还带着 .md 后缀 —— 即便将来真有 /spec 路由,这个写法也仍是错的。

可能的处理方向(由 PM/维护者定,本 issue 不预设)

1. 只修内容:把这 18 条改指真实存在的目标(/docs/... 页面、或 GitHub 上的 packages/**/README.md 绝对 URL —— plugins/*.mdx 里的 "Package README" 已经是这个写法),门禁不动。
2. 顺带补门禁:让 check-doc-links.mjs 也能判非 /docs 绝对 href。需要一份站点路由的真值来源(枚举 apps/site/app 的路由段 + public/ 静态资源),这会让脚本从「只读 content/docs」变成「也读 apps/site」,是个设计取舍;同时可考虑拒绝跑出 collection 的相对链接(A 类)。
3. 两者都做。

方向 2 是防止再次积攒的唯一办法(#3479 的教训正是「没门禁就会攒」),但它把脚本的职责扩大了一圈,值得单独定。

[yinlianghui]

补充相邻观察(来自 #3486/PR #3495 的 dev,限流未能查重,由 PM 代记于此——实施本单时须知):

scripts/check-doc-links.mjs 的扫描面只有 content/docs(DOCS_ROOT)——examples/**/README.md 与根 README.md 完全在外;PR #3489 扩展的相对链接校验同样只覆盖该树。这是 #3480/#3486 家族的死链在绿色 CI 下存活 ~3 个月的系统性成因。本单(路由级校验)实施时应一并考虑扫描面是否扩到 examples/** 与根 README,或明确记录为后续单——否则门禁对这一家族继续报「Docs links are valid」。另:console-starter 缺 README 的观察待 PM 查重后另立。

---

Generated by Claude Code

[yinlianghui]

认领:objectui 分片 PM 并行批第 62 单(前置解除:PR #3489 已 MERGED@449227d71,checker 同文件串行满足)
会话:session_01GTRjn8xBqp75dk7kFupVRt
分支:claude/issue-3490-site-route-links
Worktree:objectui-issue-3490
文件面:scripts/check-doc-links.mjs + 其测试、content/docs/** 的 18 处修链。⛔ 不动 apps/site 路由本身。

PM 裁定(issue 三方向):采方向 3 但收敛范围——① 内容侧 18 条按「改指真实目标」修(/docs 页面或 GitHub 绝对 URL,plugins/*.mdx 的 Package README 已有先例写法);② 门禁侧两项:非 /docs 绝对 href 以 apps/site/app 路由段枚举 + public/ 静态资源为真值来源做存在性判定、拒绝跑出 collection 的相对链接(A 类)——这是 #3479 教训(无门禁必再积攒)的直接延伸,职责扩大在 PR 里写明取舍。本单评论区已锚的「扫描面扩到 examples/**+根 README」不做,留后续单(避免一单三扩)。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3506。

核过 GitHub 实物(非报告转述),要点:

• 10 个文件与披露清单一一对应:检查器(+215/-18,路由真源改为枚举 apps/site/app + public/)、测试(22→34,含 6 条拒绝类钉扎)、7 个 content 文件共 18 处链接修复、ci-cd-pipeline.md 事实性修正。
• 逆向验证是实跑的:恢复两处豁免 → 恰好 6 条新钉扎变红(3 种 site-route 形状、缺失 public 资产、无表即抛、escapes-collection 分类),单元测试按预告保持绿。方向全部先预告后运行。
• 18 处修复逐条给了 disposition,引入的每个 GitHub 绝对路径都核过磁盘存在;3 条 /img 链接被新检查正确放行(真实 public 资产)。
• 两处披露的边界处理均背书:(1) ci-cd-pipeline.md 的 gate 描述被本 PR 改动证伪,最小事实修正符合 AGENTS.md Add automated testing infrastructure and CI/CD workflows #2,比让文档撒谎好;(2) 测试文件第 7 行 @ts-expect-error 删除与 main 的 Type Check job 全红:#3489 与 #3498 的语义冲突,check-doc-links.test.ts 的 @ts-expect-error 在 allowJs 下变成 TS2578 #3504 热修同形,两侧同删同一行,合并次序无关 —— 若入队时仍报 dirty,按 ci(docs): check-doc-links 提升为无路径过滤的独立 workflow，纯 docs PR 也拦得住断链 (#3448) #3458 先例处理。
• routeExists 对无路由表的绝对 href 抛错而非放行,把"静默 waive"这条积累了 18 个 404 的路堵死了 —— 与 declared=enforced 的仓库取向一致。

后续:dev 顺手立的 #3507(building-crud-app.md 两条指向不存在的 examples/{todo,crm} 的 GitHub 链接,两道 gate 按设计都不覆盖)进 PM 分诊池;"PR 自引入 8 条 GitHub 绝对 URL 无 gate 校验"的观察并入既有的扫描面扩展跟进项,不另立单。

PR 转 ready + auto-merge(配额恢复后执行)。

---

Generated by Claude Code