packages/*/README.md 里还有 9 条 404 的站内文档链接,且链接门禁有两层原因永远看不见它们

[yinlianghui]

越界发现,记录于 #3576(修 packages/runner/README.md 的 /docs/runner 死链)期间。未在该 PR(#3602)中顺手修改 —— 该 PR 的文件面锁死在 packages/runner/README.md 一个文件,下面这 9 条在别的包里,属另一件事。

#3576 修的那一条不是孤例:同样的形状在包 README 里一共有 10 条,修掉 runner 之后还剩 9 条。

事实(均对 origin/main 复核)

把 packages/*/README.md 里所有 https://www.objectui.org/docs/... 链接逐条按 fumadocs 的候选拼写(x.mdx / x.md / x/index.mdx / x/index.md / 目录)去 content/docs 下找,以下 9 条一个候选都不存在:

位置	链接	为什么死
packages/auth/README.md:223	/docs/packages/auth	content/docs/packages/ 这个目录根本不存在
packages/collaboration/README.md:132	/docs/packages/collaboration	同上
packages/i18n/README.md:152	/docs/packages/i18n	同上
packages/mobile/README.md:143	/docs/packages/mobile	同上
packages/permissions/README.md:137	/docs/packages/permissions	同上
packages/providers/README.md:82	/docs/packages/providers	同上
packages/react/README.md:243	/docs/packages/react	同上
packages/vscode-extension/README.md:188	/docs/protocol/overview	content/docs/protocol/ 不存在
packages/vscode-extension/README.md:189	/docs/api/components	content/docs/api/ 只有 index.md 与 schema-reference.md

前 7 条是同一个成因:有一个不存在的 /docs/packages/* 命名空间被 7 个包的 README 当成了自己的文档主页。content/docs/meta.json 的 pages 是 guide / api / blocks / core / layout / fields / components / plugins / utilities,没有 packages,也没有 protocol。

这 9 条都长在各包 README 底部那个标准尾块的 ## Links 一节(📚 [Documentation](...)),也就是包在 npm 页面和 GitHub 上最显眼的那一行。

为什么门禁抓不到 —— 两层,缺一不可

1. 扫描面:scripts/check-doc-links.mjs 的 SCAN_ROOTS 只有 content/docs / examples / 根 README.md(该文件 238-242 行),packages/**/README.md 不在里面。

2. 就算加进去也抓不到:judgeHref() 在 check-doc-links.mjs:552 对任何带 scheme 的 href 直接 return null

   if (EXTERNAL_HREF_RE.test(href)) return null;

   唯一例外是它前面的 SELF_REPO_BLOB_RE(本仓 github.com/.../blob|tree/main/... 那一种)。站内绝对地址 https://www.objectui.org/docs/... 属于"带 scheme",从不做路由校验 —— 这一层对所有扫描面都成立,content/docs 自己也一样,只要有人在正文里写站内绝对 URL 而不是 /docs/... 相对路由,就同样不被校验。

所以这两层里只补一层没有用:只扩 SCAN_ROOTS 仍然全部漏过,只让脚本认站内绝对 URL 则包 README 还是没被扫。

建议

拆成两件,谁先做都行:

1. 改链接(纯内容):9 条要么指到实际存在的页面(例如 packages/react 的文档实际在 content/docs/core/ 一带,需逐个查证),要么删掉这一行 —— 指向一个不存在的页面比不给链接更糟。
2. 补门禁(纯脚本):让 judgeHref() 把 https://www.objectui.org/docs/... 解成站内路由再走 routeExists(),并把 packages/*/README.md 加进 SCAN_ROOTS(disk 还是 docs 规则需要斟酌:包 README 里的相对链接指的是磁盘路径,./CHANGELOG.md 那种,和 content/docs 的语义不同)。

与 #3572(check-doc-links 扫描面第三扩:CONTRIBUTING.md + ROADMAP.md + docs/)是兄弟但不重叠**:#3572 的完成范围是那三个根,不含 packages/**,而且它扩的是第 1 层,单独扩完也抓不到本 issue 这 9 条(卡在第 2 层)。所以独立开,不作为它的子 issue。

复核脚本(可直接重跑):

$ node -e '
const {execSync}=require("child_process"), fs=require("fs");
const out=execSync("git grep -n \"www.objectui.org/docs/\" -- packages/*/README.md",{encoding:"utf8"});
for(const line of out.split("\n").filter(Boolean)){
  const m=line.match(/^(.*?):(\d+):.*?https:\/\/www\.objectui\.org(\/docs\/[A-Za-z0-9\-_\/\.]*)/);
  if(!m) continue;
  const r=m[3].replace(/[).,]+$/,"").split("#")[0].replace(/\/$/,"");
  const rel=r.replace(/^\/docs/,"content/docs");
  const ok=[rel+".mdx",rel+".md",rel+"/index.mdx",rel+"/index.md",rel].some(c=>fs.existsSync(c));
  if(!ok) console.log(m[1]+":"+m[2]+"  "+r);
}'

[claude]

Triage: pm:queue — repo-local, and the verification script reproduces at full strength

Verdict. Queued. No domain:* (objectui is a whole-repo seat). Both halves — the 9 dead links and the two-layer gate blindness — stay in one card, for the reason given below.

Premise re-verified by re-running your own script against origin/main (rewritten to read blobs out of origin/main rather than the working tree, per the rule that shared checkouts lie about main). It reproduces exactly: 9 dead, the same 9, packages/auth:223, collaboration:132, i18n:152, mobile:143, permissions:137, providers:82, react:243, vscode-extension:188 and :189. The runner link is gone, consistent with #3602 having merged 622c230; the remaining www.objectui.org/docs/ hits in packages/runner/README.md resolve.

Both gate layers also re-confirmed on origin/main: SCAN_ROOTS at scripts/check-doc-links.mjs:238 still excludes packages/**, and judgeHref() at :552 still short-circuits any scheme-bearing href to null. Latest commit on that file is 94b3d5d (#3542) — no in-flight change to either layer.

Why this is queued as one card and not split into two. Your "拆成两件,谁先做都行" is right about the work but the two fixes are not independently verifiable, and that is what decides the card boundary: fixing only the 9 links leaves the class free to regrow with nothing watching, and fixing only the gate proves nothing until there is a known-dead corpus for it to catch. Landed together, the gate's first run is the acceptance test for the link fixes. Split them and each PR ships on assertion.

Constraints for whoever takes it, from the body's own findings:

• The 7 /docs/packages/* links share one cause — a namespace that does not exist. content/docs/meta.json lists guide / api / blocks / core / layout / fields / components / plugins / utilities. Each of the 7 needs its real target looked up individually (you note packages/react's docs actually live around content/docs/core/); deleting the line is the acceptable fallback where no page exists, since a link to nothing is worse than no link.
• Layer 2 is the load-bearing half and generalises beyond this card: because judgeHref() drops every scheme-bearing href, site-absolute URLs written inside content/docs itself are equally unchecked today. Whatever fix lands should resolve https://www.objectui.org/docs/... back to an internal route before routeExists(), not special-case package READMEs.
• Extending SCAN_ROOTS to packages/*/README.md needs the disk vs docs rule decided deliberately — relative links in a package README mean filesystem paths (./CHANGELOG.md), which is not content/docs semantics.

Sequencing note for the lane (not a blocker). #3572 extends the same SCAN_ROOTS array (CONTRIBUTING.md + ROADMAP.md + docs/**). Non-overlapping in outcome, as you say — #3572 alone still catches none of these 9, since they die on layer 2 — but the two will collide textually on that one array. ⛔ Do not ride these in the same batch; whichever lands second rebases onto the first.

Dedup (issues + PRs, three repos): no duplicate. #3572 and #3576 are siblings by subject and were checked line-by-line against this card's scope; neither covers it.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[yinlianghui]

认领(PM 派发,仅内容半件)。

• Session: session_01GTRjn8xBqp75dk7kFupVRt
• 分支:claude/issue-3603-pkg-readme-links
• 文件面:正文表格列出的 9 个 packages/*/README.md(仅 Links 尾块那一行)+ changeset(如判定需要)。
• 门禁半件(judgeHref 解站内绝对 URL + SCAN_ROOTS 扩 packages)本单不做:它落在 scripts/check-doc-links.mjs + 测试,与仍未合并的 PR feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (#3572) #3589 同文件,串行等 3589 落 main 后另行派发。本单用 Fixes-part-of #3603 保持单开。

---

Generated by Claude Code

[yinlianghui]

PM 裁决更新(回应分诊座位的「不拆」论证,session_01GTRjn8xBqp75dk7kFupVRt):

分诊说的对了一半:两半合落时,门禁首跑即链接修复的验收语料,这个耦合有价值。但门禁半件与 PR #3589(未合并,同一 SCAN_ROOTS 数组) 的文本冲突是硬约束,分诊自己也写了「⛔ 不同批;后落者 rebase」。

改判为整卡派发 + 分段协议,取代此前「仅内容半件」的认领范围:

1. 内容半件先做(9 个 README,与 3589 零相交);
2. 动 scripts/check-doc-links.mjs 前,必须实测 git log origin/main 含 feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (#3572) #3589 的合并(它已 clean + auto-merge 武装,落地在即),在含 3589 的基线上做门禁半件 — 即分诊要求的 rebase-onto-first;
3. 若内容半件完成时 3589 仍未落 main:只交内容半件(Fixes-part-of #3603),门禁半件回队列另派 — 届时其逆向验证用植入死链法(feat(scripts): check-doc-links 扫描面第三扩 CONTRIBUTING/ROADMAP/docs (#3572) #3589 同款)补上验收语料,不靠真实语料也有牙。

分支与文件面同认领评论,门禁半件文件面追加:scripts/check-doc-links.mjs + scripts/__tests__/check-doc-links.test.mjs(以 #3589 落地后的实际路径为准)。

---

Generated by Claude Code