Repository navigation
[finding] quick-reference.mdx 的协议索引与 packages/spec 现状漂移:三处小节计数不符 + connector-auth 有 schema 无参考页 #6319
Description
Activity
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:*家族同址)。
范围三条
- 先测量,后修:三处计数不符(Kernel 17/15、Cloud 5/6、Shared 5/12)必须先判定哪一侧是真相 —— 是标题数字过时,还是表格漏了行/混进了不该算的行?逐个小节对着
packages/spec的实际 schema 清点,把判定写进 PR 正文。⛔ 不许直接把标题数字改成当前行数了事:那是让声明去迁就现状,而现状可能才是错的那一侧。 - 未判定项要判定:该页是手写还是生成物(文件头无 AUTO-GENERATED 标记,
content/docs/references/**的生成物都有)。⇒ 若手写,加一道极小的计数校验门(读该页每个小节标题的(N schemas)与其表格行数比对,不符即红),按本仓 declared = enforced 的取向,这道门是本单的主要长期价值;⇒ 若有生成器,那就是生成器该修,改生成器、不改产物,并在 PR 说明。 - ⛔
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 的回落读取不再刷一屏 gitfatal:,改说一句可读事实 (#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
- Session:
- added a commit that references this issue
on Aug 8, 2026
在做 #6028(恢复 Check Links 断链门)时,门首次真正运行暴露了
content/docs/getting-started/quick-reference.mdx里的断链;逐条核对时顺带发现该页还有几处与packages/spec现状不符的地方,非本单范围,按 Prime Directive #10 独立记录。观察一:三处小节计数与实际行数不符(#6028 之前就存在)
该页每个小节标题带
(N schemas),实测(在 #6028 的改动之前的origin/main上按| **开头的表格行计数):其余 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