docs(skills): guide 里反引号包裹的仓内路径无任何门禁校验 —— #3713/#3730 两轮 13+ 处死路径都是靠人肉发现的

[yinlianghui]

越界发现，记录于 #3730（订正 skills/objectui/guides/console-development.md 三处表/节的 13 个符号路径）期间。按纪律只报不改，单独立单，未认领。

打 finding：这是一条缺失的门禁，不是今天有人踩到的缺陷。用户面零影响，严重度留给分诊裁。

事实

skills/objectui/guides/*.md 是本仓 agent 写代码时的直接输入，正文里大量以反引号给出仓内路径当坐标（packages/app-shell/src/layout/UnifiedSidebar.tsx 这类）。没有任何门禁校验这些路径在磁盘上存在。

• scripts/check-doc-links.mjs 的 SCAN_ROOTS（该文件第 392 行起）为
  content/docs / examples / README.md / CONTRIBUTING.md / ROADMAP.md / docs / packages/*/README.md
  —— 不含 skills/。且它校验的是 markdown 链接（[x](y)），本来也不看反引号里的裸路径。
• 全仓搜 skills/ 的其他消费者：只有 scripts/__tests__/check-control-bytes.test.ts 命中，且那是它自己的 fixture 路径（.claude/skills/demo/SKILL.md），与本仓 skills/ 无关。
• 结论：skills/** 正文里的仓内路径当前完全无人校验。

代价已经付了两轮，两轮都是靠人在阅读时肉眼发现：

• docs(skills): console-development.md 指路的 7 个 console 页面里 5 个不存在,并整节教用已删除的 MetadataManagerPage #3713 / PR docs(skills): console-development.md 按 pages/system 现状重写,并同步 eval 的幽灵组件期望 (#3713) #3729 —— 同一文件的目录树与 metadata registry 章节。
• docs(skills): console-development.md 的 Key contexts / Key hooks / UnifiedSidebar 三处把 13 个真实符号指到 apps/console 下已不存在的目录 #3730 / PR docs(skills): 把 console-development.md 三处表/节里 13 个符号的路径钉回真实位置 (#3730) #3734 —— 同一文件的 Key contexts（5 行）/ Key hooks（7 行）/ UnifiedSidebar 小节，共 13 个真实符号指向不存在的目录，另有 NavigationContext 小节第二处同类。

这类错误的成本形态很特殊：符号都真实存在，只是坐标错了，所以 agent 照着去 Read/Edit 得到「文件不存在」，浪费一整圈定位，而不是立刻拿到一个编译错误。它也天然会复发 —— 代码搬家（c1e105793 / 28ffe4033 / b279d80d6 / cccdf84d7 这批 app-shell 抽取）不会有任何东西提醒 guide 跟着改。

一个可行的最小形状（仅供分诊参考，不预设结论）

抽出 skills/**/*.md 正文里所有反引号 token，取形如 ^(apps|packages|examples|scripts|content)/ 且不含空格的，逐个 existsSync。PR #3734 里我用一个 8 行 node 脚本跑过全文，34 条候选命中 33 条存在，唯一「不存在」的是一句故意的否定句（「apps/console/src/context/ 这个目录并不存在」）—— 说明：

• 信噪比够高，可直接当门禁；
• 但必须有豁免机制，因为「指出某路径不存在」是 guide 的合法写法（packages/spec/src/ 下带占位段的路径同理）。豁免可以是 baseline JSON（仿 scripts/i18n-call-site-key-baseline.json）或行内注释标记，哪种更合仓内习惯由维护者定。

要不要连 content/docs/** 一起纳入（那里同样有反引号裸路径，且已在 SCAN_ROOTS 里但只查链接）也是分诊可以一并裁的范围问题。

关联

• docs(skills): console-development.md 指路的 7 个 console 页面里 5 个不存在,并整节教用已删除的 MetadataManagerPage #3713 / PR docs(skills): console-development.md 按 pages/system 现状重写,并同步 eval 的幽灵组件期望 (#3713) #3729、docs(skills): console-development.md 的 Key contexts / Key hooks / UnifiedSidebar 三处把 13 个真实符号指到 apps/console 下已不存在的目录 #3730 / PR docs(skills): 把 console-development.md 三处表/节里 13 个符号的路径钉回真实位置 (#3730) #3734 —— 本 finding 想防的两轮复发，同一文件。
• scripts/check-doc-links.mjs —— 最近的同类门禁；其 docblock 记录的历史（content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479 / content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490 / CONTRIBUTING.md / ROADMAP.md 共 3 条死链:处在 check-doc-links 与 lychee 的双重扫描盲区 #3545 一次扩面就要连带清红）说明扩面要先量红再落地。

已就关键词（skills guides path、console-development.md、check-doc-links SCAN_ROOTS、docs path gate）搜过本仓开放 issue，无同源单。

---

Generated by Claude Code

[os-zhuang]

Findings round: promoted — finding removed, pm:queue applied (documentation kept).

• Premise re-checked on objectui origin/main @ a4f837c: scripts/check-doc-links.mjs still scans only its documented SCAN_ROOTS surfaces (no skills/), and it checks markdown links, not backtick path tokens — the gap is live. The cost side is not hypothetical: two rounds (docs(skills): console-development.md 指路的 7 个 console 页面里 5 个不存在,并整节教用已删除的 MetadataManagerPage #3713/PR docs(skills): console-development.md 按 pages/system 现状重写,并同步 eval 的幽灵组件期望 (#3713) #3729, docs(skills): console-development.md 的 Key contexts / Key hooks / UnifiedSidebar 三处把 13 个真实符号指到 apps/console 下已不存在的目录 #3730/PR docs(skills): 把 console-development.md 三处表/节里 13 个符号的路径钉回真实位置 (#3730) #3734) of 13+ dead paths in the same guide, all found by eye.
• Grade rationale: scoped gate addition with a pre-measured signal-to-noise reading (33/34 candidates resolve; the one miss is a deliberate negative sentence), a sketched 8-line extractor, and an in-repo exemption precedent to follow (baseline JSON, mirroring i18n-call-site-key-baseline.json) — acceptance statable in one sentence, so it queues. Default: new standalone script + baseline exemption file, skills/**/*.md only; widening to content/docs/** is explicitly out of default scope (the check-doc-links docblock's own history says expansion must measure the red first — content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479/content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490/CONTRIBUTING.md / ROADMAP.md 共 3 条死链:处在 check-doc-links 与 lychee 的双重扫描盲区 #3545).
• Dedup: the body's four keyword searches plus this round's scan — no open twin; check-i18n-en-drift 的显式 --base / OS_I18N_DRIFT_BASE 解析不出时会静默跌落到别的提交,拿错基准比对并报绿 #3766 (this round) is a different gate, different file. Clean.

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

---

Generated by Claude Code

[yinlianghui]

🔒 认领(objectui shard PM,session session_01GTRjn8xBqp75dk7kFupVRt)

• 分支:claude/issue-3735-skills-path-gate
• 文件面:新增门禁脚本(scripts/ 下)+ baseline 豁免 JSON + scripts/__tests__/ 测试 + CI 接线(按仓内既有门禁的挂法);不改任何 skills/**/*.md 正文(唯一已知反例是故意的否定句,进豁免)。
• 形状按分诊缺省裁定执行:独立脚本 + baseline JSON 豁免(仿 i18n-call-site-key-baseline.json),扫描面仅 skills/**/*.md;content/docs/** 扩面明确不在本单(check-doc-links 自家历史 content/docs 有 16 个失效的相对链接,且 check-doc-links.mjs 对相对链接一律放行 #3479/content/docs 有 18 条链接在站上是 404,但 check-doc-links 按设计放行(1 条相对链接跑出 docs collection + 17 条 /spec /protocol /api /examples 绝对链接) #3490/CONTRIBUTING.md / ROADMAP.md 共 3 条死链:处在 check-doc-links 与 lychee 的双重扫描盲区 #3545 说扩面须先量红)。
• 前序关联:docs(skills): console-development.md 顶部注记把 shell/navigation 搬家的成因全记在 cccdf84d7 —— 实测 13 个符号没有一个是在该 commit 里搬走的 #3737 → PR docs(skills): console-development.md 顶部注记的搬家归因改成 04-21→04-23 的 commit 链,cccdf84d7 降为其中一步 (#3737) #3856 刚验收(同 guide 的归因订正,只动散文),本单不碰该文件正文,零冲突。
• 与在飞 disabled 的「已声明」判定还有五处停在 != null(action-icon / action-group ×2 / action-menu / record-quick-actions),#3842 只修了两处 #3849、258 个 t() 调用点引用的 key 在任何语言包里都不存在(#3530 守卫首跑实测),其中 8 处直接把 raw key 渲染给用户 #3546 切片六、docs(app-shell): 两个 AppContent 路由测试的头注释仍把 sys-datasources / sys-objects 枚举为「在发 legacy 别名」的生产端 —— #3660 / #3739 之后已陈旧 #3749、docs(ROADMAP): P1.12.3 / P1.16 还有 9 条同源漂移在 #3712 围栏之外(metadataTypeRegistry、注册表生成卡片、listMode、MetadataGrid) #3738 文件面零相交。

---

Generated by Claude Code