content/docs/guide/building-crud-app.md 有 2 条 GitHub 绝对 URL 指向不存在的 examples/ 目录(examples/todo、examples/crm),两个门禁按设计都看不见

[yinlianghui]

在实施 #3490(PR #3506,非 /docs 绝对链接按站点路由校验)时顺手发现,不在 #3490 的完成范围内:#3490 的口径是「站点路由不存在」的 18 条站内链接,这 2 条是站外 https:// 绝对 URL,两回事。记在这里由 PM 定级。

现象

content/docs/guide/building-crud-app.md:

行	链接
328	[Todo example](https://github.com/objectstack-ai/objectui/tree/main/examples/todo)
330	[CRM example](https://github.com/objectstack-ai/objectui/tree/main/examples/crm)

examples/ 在 origin/main(f995a45)下实际只有:

README.md  byo-backend-console  console-starter  hello-world  schema-catalog

examples/todo 与 examples/crm 都不存在,两条都是 GitHub 404。

为什么两个门禁都不报

• scripts/check-doc-links.mjs(含 PR fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 扩展后)按设计跳过一切带 scheme 的 href(EXTERNAL_HREF_RE)——外链归 lychee。
• lychee(check-links.yml)能发现,但它是周 cron + 手动,且 continue-on-error,从不 gate PR(这是 pnpm docs:check-links 在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 的有意取舍:外链走网络,第三方 502 不该把 PR 弄红)。

所以这一类「指向本仓库自己、但路径已不存在的 GitHub 绝对 URL」处在两个门禁之间:它其实是仓库内部的引用完整性问题(可离线判定),却因为写成了 https:// 而被当成外链。

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

1. 只修内容:两条改指真实存在的 example(console-starter / byo-backend-console / hello-world),或改指对应的 /docs/... 页面。
2. 顺带补门禁:让 check-doc-links.mjs 对「指向本仓库自身 blob/tree 的 GitHub 绝对 URL」做离线路径校验(https://github.com/objectstack-ai/objectui/(blob|tree)/main/<path> → 断言 <path> 在工作树里存在)。这条能离线、能 gate,且正好覆盖 PR fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 大量新引入的这种写法——fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 把 8 条链接改成了这个形式,目前没有任何 gate 校验它们,同样会悄悄烂掉。

方向 2 与 #3490 评论区已锚的「扫描面扩到 examples/** + 根 README.md」是不同的两件事(那条是扩扫描面,这条是扩可判定的 href 形态),但很可能适合放在同一单里做。

[yinlianghui]

认领(PM 分诊)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3507-dead-example-links。

分诊裁定:本单只做方向 1(内容修复,两条链接改指真实存在的 example,标签如实改写)。方向 2 单独持有:它改 scripts/check-doc-links.mjs,而 PR #3506 正在重写同一脚本 —— 等 #3506 合并后,方向 2 与已锚的「扫描面扩到 examples/** + 根 README.md」并成一张 gate 扩展单(一个改扫描面、一个改可判定 href 形态,同一脚本同一趟做),届时另立 issue 引回本单。

文件面:content/docs/guide/building-crud-app.md 第 328/330 行。越界即停。

---

Generated by Claude Code

[yinlianghui]

方向 1 已实现:PR #3509(draft)。顺带把方向 2 的规模测了一下,附在这里给 PM 定级用 —— 是本单已记录方向的补充数据,不另开 issue。

方向 1 的落点

行	原目标(404)	新目标
328	examples/todo	/docs/plugins/plugin-kanban
330	examples/crm	/docs/fields/lookup

按各自 bullet 的承诺挑的("Add a Kanban board view using @object-ui/plugin-kanban" / "Build multi-object apps with relationships"),标签如实改写,理由见 PR 正文。补一条本单原文没提到的事实:这两个目录是在 12b287d8b(2026-05-02,一次删掉 80 个文件)随 Todo/CRM 示例移除的,链接烂了约三个月;#3486/#3495 修的 examples/hello-world/README.md 里的 ../crm/、../todo/ 是同一次删除的另一侧,docs 站这侧当时漏了。

方向 2 的规模:当前 backlog 为 0,它是纯预防性的

把 content/docs 下所有指向本仓库自身的 tree|blob/main/ 绝对 URL 全部拿 git cat-file -e 对 origin/main(f995a45)判了一遍,25 个不同目标,只有 2 个是死的 —— 正是本单这两条:

DEAD   examples/crm
DEAD   examples/todo
OK     CHANGELOG.md, CONTRIBUTING.md, examples, examples/schema-catalog, packages,
       packages/plugin-{ai,calendar,charts,chatbot,designer,detail,editor,gantt,
       kanban,list,map,markdown,report,timeline}, packages/plugin-dashboard/README.md,
       packages/plugin-gantt/README.md, skills/objectui, skills/objectui/README.md

对 PM 定级的含义:

1. PR docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509 合并后,这一类在 content/docs 里的存量清零。 方向 2 上线时会是绿的,不会附带一张待修清单(和 content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479 上线时要顺手修 16 个目标的情形不同)。
2. 所以方向 2 不紧急,可以安心等 fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 合并后再和「扫描面扩到 examples/** + 根 README.md」并成一张单 —— 与本单分诊裁定一致。它买的是"以后别再烂三个月没人发现",不是"现在有东西要修"。
3. 一个后续动作:上面这一遍是对 origin/main 跑的,不含 fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 新引入的 8 条同形态链接。fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 合并后建议重跑一次同样的判定确认那 8 条都活着 —— 那正是本单提到"目前没有任何 gate 校验它们"的部分。

复现命令(只读,离线):

git grep -hoP 'https://github\.com/objectstack-ai/objectui/(?:tree|blob)/main/[^)\s#]+' origin/main -- content/docs \
 | sed 's#.*/main/##' | sort -u \
 | while read -r p; do git cat-file -e "origin/main:$p" 2>/dev/null && echo "OK   $p" || echo "DEAD $p"; done

未触碰 scripts/check-doc-links.mjs。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3509。

核过 GitHub 实物:恰 1 file / +2/-2。两点裁定随验收记录:

1. 改指站内路由而非另一条 GitHub URL 背书 —— 这让两条链接从"无 gate 的盲区形态"迁进了 check-doc-links 的覆盖面(Probe A 已实证新链接真的被检查:改错一个字符立刻红),比"修成另一种没人看的链接"强一档。
2. 330 行与 PR fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 的目标分歧背书 —— dev 读了 console-starter/src/App.tsx 才做决定:它是路由+鉴权脚手架,不演示关系建模;硬指过去就是"标签夸大目标"的原缺陷复刻。跟随的是 fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 的原则(如实改题)而非其具体目标,对。
3. PR body 自我更正(Type Check 按路径过滤根本不在 docs-only diff 上跑,"pre-existing red"表述撤回)记为证据纪律加分。

方向 2 的量化数据收到:25 个自仓 tree|blob 目标中恰 2 死(即本单所修),#3509 合并后此类存量归零 → 方向 2 纯预防、不紧急,维持"等 #3506 落地后并单"的持有;并单后按 dev 留的 one-liner 复扫 #3506 新引入的 8 条。

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

---

Generated by Claude Code

[claude]

Triage: pm:dispatched (pm-state only — per the seat protocol, issues living in objectui / cloud carry no domain:*; those repos are whole-repo seats and routing is expressed by the repo itself).

Why pm:dispatched and not pm:queue. This issue was already claimed at 01:36:38Z (session session_01GTRjn8xBqp75dk7kFupVRt, branch claude/issue-3507-dead-example-links) and PR #3509 is open against it. pm:queue would advertise it as ready-to-dispatch to every sweep; the honest state is in-flight. ⛔ This comment applies a label only — the assignee is untouched and the existing claim stands.

Why this stays in the objectui seat (no cross-seat transfer). Checked against the three transfer triggers: direction 1 is content/docs/** inside this repo; direction 2 lands in this repo's own scripts/check-doc-links.mjs. Not feature-level, not cross-repo, and nothing touches packages/spec ⇒ no objectstack mirror issue and no domain:spec transfer is owed.

Dedup (full paginated enumeration of open issues and PRs in all three repos + local matching — the GitHub search API is blocked for repository-scoped sessions, so this was done by enumeration, not by search):

• content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490 / PR fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 — not a duplicate, and the body's own reasoning holds: content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490 is 18 in-site route links; this is 2 off-site https:// absolute URLs that the offline checker skips by design (EXTERNAL_HREF_RE). Different href class, different gate.
• PR docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页 #3509 — this issue's own fix. One dispatch entry, as required.
• objectstack#6028 — cross-linked, not converged: it records that the Check Links workflow triggers are commented out on the objectstack side. Same failure family (lychee is the only thing that would catch a dead absolute URL, and it never gates a PR), different repo and different landing site. Neither should be closed into the other.

Recorded so a later sweep does not re-triage it. The claiming PM parked direction 2 (offline validation of https://github.com/objectstack-ai/objectui/(blob|tree)/main/<path> URLs) until PR #3506 stops rewriting check-doc-links.mjs, to be merged with the already-anchored "extend the scan surface to examples/** + root README.md" into one gate-extension issue. That issue does not exist yet, so it is currently held only by a comment. Filing it now would create a second dispatch entry for work already promised, so this round does not — but the note matters: PR #3506 also introduced ~8 links in exactly the unvalidated form, so if #3506 merges and no gate-extension issue appears, the next findings round should file one rather than let the promise decay in a thread.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code