Repository navigation
content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490
Description
在 #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 不预设)
- 只修内容:把这 18 条改指真实存在的目标(
/docs/...页面、或 GitHub 上的packages/**/README.md绝对 URL ——plugins/*.mdx里的 "Package README" 已经是这个写法),门禁不动。 - 顺带补门禁:让
check-doc-links.mjs也能判非/docs绝对 href。需要一份站点路由的真值来源(枚举apps/site/app的路由段 +public/静态资源),这会让脚本从「只读content/docs」变成「也读apps/site」,是个设计取舍;同时可考虑拒绝跑出 collection 的相对链接(A 类)。 - 两者都做。
方向 2 是防止再次积攒的唯一办法(#3479 的教训正是「没门禁就会攒」),但它把脚本的职责扩大了一圈,值得单独定。
Activity
yinlianghui commentedon Aug 6, 2026
补充相邻观察(来自 #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 commentedon Aug 7, 2026
认领:objectui 分片 PM 并行批第 62 单(前置解除:PR #3489 已 MERGED@449227d71,checker 同文件串行满足)
会话:
session_01GTRjn8xBqp75dk7kFupVRt分支:
claude/issue-3490-site-route-linksWorktree:
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 commentedon Aug 7, 2026
验收:ACCEPT — PR #3506。
核过 GitHub 实物(非报告转述),要点:
apps/site/app+public/)、测试(22→34,含 6 条拒绝类钉扎)、7 个 content 文件共 18 处链接修复、ci-cd-pipeline.md事实性修正。/img链接被新检查正确放行(真实 public 资产)。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 先例处理。后续: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
feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (obje…
feat(scripts): check-doc-links 扫描面第四扩 packages/*/README.md,并付清入场价的 11…
ci(skills): skills 指南正文反引号里的仓内路径上门禁,豁免走双向陈旧检测的 baseline (objectstack-…