[finding] `quick-reference.mdx` 的协议索引与 `packages/spec` 现状漂移:三处小节计数不符 + connector-auth 有 schema 无参考页

[hotlong]

在做 #6028(恢复 Check Links 断链门)时,门首次真正运行暴露了 content/docs/getting-started/quick-reference.mdx 里的断链;逐条核对时顺带发现该页还有几处与 packages/spec 现状不符的地方,非本单范围,按 Prime Directive #10 独立记录。

⚠️ 这些不是断链,Check Links 抓不到它们(lychee 只检可达性)。#6028 的 PR 只改了链接目标行,下面这些原样保留。

观察一:三处小节计数与实际行数不符(#6028 之前就存在)

该页每个小节标题带 (N schemas),实测(在 #6028 的改动之前的 origin/main 上按 | ** 开头的表格行计数):

小节	标题声明	实际行数
Kernel Protocol	17	15
Cloud Protocol	5	6
Shared Protocol	5	12

其余 8 个小节当时都对得上。⚠️ 注意 System(19)与 API(19)两处在 #6028 里由我改成了 18 / 17 —— 那是因为该 PR 删掉了三行指向已退役 schema 的表项(audit / registry / graphql),属于同步修正,不在本单记录范围内;上表三处与 #6028 无关。

Shared 差了 7 行,不像笔误,更像该小节扩充过而标题没跟。

观察二:connector-auth 有 schema、无参考页

packages/spec/src/shared/connector-auth.zod.ts 存在,但 content/docs/references/shared/ 下只有 branded-types.mdx / enums.mdx / expression.mdx / http.mdx —— 没有 connector-auth.mdx。

quick-reference 里原本有一行链到 /docs/references/shared/connector-auth,那是一条真断链;#6028 的处置是保留该行、去掉链接(schema 确实存在,信息不该丢),所以这一行今天读起来是"有这个 schema,但没有参考页可看"。页要不要补,留待分诊。

未判定的部分

没有查这个索引页是手写的还是某个脚本生成的。文件头没有 AUTO-GENERATED 标记(content/docs/references/** 下的生成物都有),所以看起来是手写维护的 —— 若确实手写,那这类漂移会反复发生,可能值得一道计数校验;若其实有生成器,那就是生成器该修。请分诊时以实际为准。

影响面(据实,不夸大)

读者看到的是一个数字对不上的目录和一行没有出口的条目 —— 不会导致任何运行时错误,也没有已知用户因此踩坑。归类为 observation-class,不加 pm:queue,留待分诊定级。

---

Generated by Claude Code

[hotlong]

PM 定级 + 认领(pm-dispatch devx 座位) — 摘 finding,直接入队并派发。

为什么由 PM 定级而不等分诊轮:立单人给的是实测读数(三处计数逐个数过、connector-auth.mdx 确认不存在),前提清楚、修法有界;而同文件的面锁刚在 PR #6304 合并时释放(2026-08-07 14:4xZ),此刻派发正好避开下一次冲突窗口。⚠️ 立单人自评 observation-class,分诊不采纳这一档——理由与 #6002 那次相同:content/docs/ 是人与 AI 照抄的语料,一个数字对不上的目录会被照抄、被引用、被当作 schema 清单的事实来源,代价不是「有人撞坏」而是错误信息持续增殖。

• Session: session_01BDmDsu2575gDxeMCxXhDE3
• 分支: claude/issue-6319-quick-reference-counts
• 文件面: content/docs/getting-started/quick-reference.mdx;若测量证明该页手写,则另加校验脚本(scripts/)+ package.json 接线 + .github/workflows/lint.yml 的 ESLint job 一步(与既有 check:* 家族同址)。

范围三条

1. 先测量,后修:三处计数不符(Kernel 17/15、Cloud 5/6、Shared 5/12)必须先判定哪一侧是真相 —— 是标题数字过时,还是表格漏了行/混进了不该算的行?逐个小节对着 packages/spec 的实际 schema 清点,把判定写进 PR 正文。⛔ 不许直接把标题数字改成当前行数了事:那是让声明去迁就现状,而现状可能才是错的那一侧。
2. 未判定项要判定:该页是手写还是生成物(文件头无 AUTO-GENERATED 标记,content/docs/references/** 的生成物都有)。⇒ 若手写,加一道极小的计数校验门(读该页每个小节标题的 (N schemas) 与其表格行数比对,不符即红),按本仓 declared = enforced 的取向,这道门是本单的主要长期价值;⇒ 若有生成器,那就是生成器该修,改生成器、不改产物,并在 PR 说明。
3. ⛔ connector-auth 参考页不在本单:补一整页 content/docs/references/shared/connector-auth.mdx 是独立的写作工作量,与计数修正不同族。本单只需在 PR 正文如实说明现状(schema 在、页不在、[finding] Check Links 工作流的 push / pull_request 触发器被注释掉 —— lychee 断链门只剩 workflow_dispatch,文档断链在 CI 里无人把守 #6028 已保留该行去掉链接),需要补页则另立单。

• 互斥核对: 与在飞 check-single-authz-resolver 检查 (1) 的判据词表已被 ADR-0090 D3 改名废掉:sys_user_role 全仓 0 命中,门禁结构上抓不到任何重复解析器 #6286(scripts/check-single-authz-resolver.mjs)零交集;队列中 docs(kernel): services.data 的 Parameters 补上 canonical QueryOptionsV2 词汇,Example 同批换用 (#6002) #6324(data-service.mdx)、fix(scripts): digest 的回落读取不再刷一屏 git fatal:,改说一句可读事实 (#6175) #6335(objectui-changeset-digest.mjs)、fix(lint): object/missing-name-field 认 nameField、不再采信已退役的 titleFormat (#6108) #6338/docs(lint): 按实测改正 normalized 输入层的三条依据,并补回归 pin (#6073) #6340(packages/lint/**)均无交集。⚠️ 若本单要动 lint.yml,注意 ci(check-links): 恢复 pull_request 断链门,仅检仓内链接、advisory-first (#6028) #6304 刚改过 check-links.yml(不同文件,无冲突),但须从 ci(check-links): 恢复 pull_request 断链门,仅检仓内链接、advisory-first (#6028) #6304 合并后的 main 切出。

---

Generated by Claude Code