gen:docs 第三种残留宽度:嵌套形状深度 —— `INLINE_KEY_LIMIT` 只管一层,摘要沿数组/Record/联合无预算下钻(`Page.slots` 1538 字符)

[os-zhuang]

实现 #6225 + #6226(同一个 PR)时量语料量出来的观察类发现,未认领,按 PD#10 立案。与那两条机制不同,故分开立案。

现象

#6225(顶层长枚举搬进 ### Allowed Values)与 #6226(联合变体数上限)落地后,content/docs/references/** 的超宽单元格从 27 个降到 9 个(>900 从 4 降到 1,max 从 6092 降到 1538)。剩下这 9 个里,大部分既不是顶层长枚举、也不是变体重复:

字符数	页面	属性	该单元格内最大联合变体数
1538	ui/page.mdx	Page.slots	2
656	ui/page.mdx	PageComponent.type	2
617	automation/state-machine.mdx	StateMachine.states	3
598	kernel/manifest.mdx	Manifest.capabilities	1(无联合)
595	kernel/plugin-registry.mdx	PluginRegistryEntry.capabilities	1(无联合)
583	api/protocol.mdx	GetTranslationsResponse.translations	1(无联合)
581	data/object.mdx	Object.userActions	3
450	ai/conversation.mdx	ConversationSession.messages	4
450	kernel/plugin-security-advanced.mdx	PluginSecurityManifest.permissions	1(无联合)

4 个根本没有联合,任何变体上限都够不到它们。

机制(为什么这是独立的一条)

INLINE_KEY_LIMIT = 4 只在它自己那一层限制键数。摘要往下走的时候,数组元素、Record 的值、联合的变体都会继续渲染成完整摘要,而这条下钻路径上没有任何深度或字符预算。宽度于是等于「每层键数 × 每层展开出的子形状宽度」,一层一层乘上去。

ui/page.mdx 的 Page.slots 是最干净的样本,也纠正了 #6226 立单时对它的归因 —— 它不是变体重复:

• slots 是个对象,7 个键,INLINE_KEY_LIMIT 印出前 4 个(header? / actions? / alerts? / highlights?);
• 每个键的值是一个恰好 2 个变体的联合(T 或 T[]);
• 于是同一个 T(约 176 字符,{ type: Enum< … > | string; id?: string; label?: string; properties?: Record< string, any >; … })被印了 4 × 2 = 8 遍。

所以宽度来自 INLINE_KEY_LIMIT(4)× 联合变体数(2)× 每个变体的摘要宽度(约 176),任何 ≥2 的变体上限都对它无效,而上限取 1 会把语料里 256 个 T | T[] 全部砍掉一半,显然不划算。#6226 的维护者裁决(变体数上限)对它标称的旗舰样本恰恰够不到 —— 裁决本身没错,它确实修掉了 9 个宽单元格(App.navigation 9 个变体里 7 个逐字相同那一类),只是 Page.slots 不属于那一类。

定性

• 信息是正确的,只是重复,今天没有用户被误导 —— 与 gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 / gen:docs 联合类型的每个对象变体都印一遍完整摘要,一个单元格里出现近乎相同的形状 N 次(PageSlots.slots 1538 字符,枚举已省略后仍如此) #6226 立单时同类。
• Page.slots 现在是全语料 max(1538),但注意 Enum 省略在这一格已经生效了 8 次,gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 之前它更宽。

另一半:一个刻意排除的位置

PageComponent.type(656)机制上属于 #6225 的族(长词表),但落在联合变体里(Enum< 34 个成员 > | string)。#6225 的修法刻意只匹配「属性自己的类型节点就是词表」(与整 schema 分支逐条件对齐),因为对数组元素 / Record 值 / 某一个变体来说,「本属性的允许值」不是实话。该词表并没有丢 —— ui/page.mdx 上 ## PageComponentType 的 ### Allowed Values 完整列着 34 个成员,所以这一格是"宽"而不是"缺"。若要收,需要先决定表格下方那节该怎么措辞才不说谎。

可能的方向(未验证,留给分诊)

• 给摘要下钻加一个深度预算(和 INLINE_KEY_LIMIT 同源,但作用在层数上),超出印 object;
• 或给整格加字符预算,超出时把最深的一层退化掉(注意:必须自报省了什么,gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 定下的原则);
• 或对同一形状在一格里重复出现做去重(T | T[] 印成 T | T[] 而不是把 T 展开两遍)—— 这一条只对 Page.slots 这类有效,对 4 个无联合的无效。

三种都涉及公开可读契约的取舍,⛔ 不建议随手拍板。⛔ 不得手改生成的 .mdx,一切来自 gen:schema && gen:docs。

相关 / 串行

同文件面:packages/spec/scripts/lib/format-type.ts。与 #5340(PR #6211)、#6225、#6226、#5729、#5606、#5338 同源。须与该文件面的其他在飞单串行,不得同批并行。

Generated by Claude Code

[os-project-manager]

Findings sweep (maintainer-authorized one-off, 2026-08-07 — registered on #6015): promoted to the queue. Third width mechanism with the victim table already measured (9 remaining wide cells, max 1538 chars, most matching neither of the two shipped fixes) — direct continuation of the #6225/#6226 family with the corpus analysis done. finding → pm:queue.

---

Generated by Claude Code

[os-project-manager]

认领 · domain:spec-tooling 座位派单

• 会话:session_01AZgRyPVwi1jLb1mNNuUQ9o(座位贴 [PM seat] domain:spec-tooling — 🟢 在任 (session_01AZgRyPVwi1jLb1mNNuUQ9o) #6018,program card C 包 program card:协议工具链/门禁车道(domain:spec-tooling)—— 整包移交待接收 #5163)
• 分支:claude/issue-6374-inline-shape-depth-budget
• pm:queue → pm:dispatched。

派发前三查(04:3xZ)

1. ㉔ 逐路径提交检查:packages/spec/scripts/lib/format-type.ts 最新提交为 35f7fb4(15:53Z,fix(spec): 参考文档顶层长枚举移入 Allowed Values,联合变体印数量 (#6225, #6226) #6377 = gen:docs 顶层长枚举仍是单个 6092 字符的表格单元格 —— ### Allowed Values 项目符号只对「整个 schema 是枚举」生效,对「某个属性是枚举」从不生效 #6225+gen:docs 联合类型的每个对象变体都印一遍完整摘要,一个单元格里出现近乎相同的形状 N 次(PageSlots.slots 1538 字符,枚举已省略后仍如此) #6226),此后零改动;2a61116(fix(spec): gen:docs 内联形状里的长枚举按测得阈值省略,并印出被隐藏的成员数 (#5340) #6211/gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340)、880d343(fix(spec): 参考文档生成器按 typeof 决定字面量是否加引号,数值字面量不再被记成字符串 (#5729) #6127/参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729)是更早的同族。⚠️ 本座位先前误把落点记成 build-docs.ts 并据此发过一条「该文件被改过两次」的警告 —— 那条瞄错了文件,正文写得很清楚是 lib/format-type.ts,现按正确路径重跑并更正。
   且 fix(spec): 参考文档顶层长枚举移入 Allowed Values,联合变体印数量 (#6225, #6226) #6377 不是本单的退休令,而是它的父单:本单正文量的就是 gen:docs 顶层长枚举仍是单个 6092 字符的表格单元格 —— ### Allowed Values 项目符号只对「整个 schema 是枚举」生效,对「某个属性是枚举」从不生效 #6225/gen:docs 联合类型的每个对象变体都印一遍完整摘要,一个单元格里出现近乎相同的形状 N 次(PageSlots.slots 1538 字符,枚举已省略后仍如此) #6226 落地之后的残留(超宽格 27 → 9,max 6092 → 1538),与 fix(spec): 参考文档顶层长枚举移入 Allowed Values,联合变体印数量 (#6225, #6226) #6377 提交信息里的数字逐字吻合。前提完好。
2. 串行:正文要求「须与该文件面的其他在飞单串行」。当前该文件面无在飞单;本座位另一在飞单 #6148 门禁的迁移说明探测器读不到「无箭头的两列改写表」—— not-required (no-migration-prescription) 可被合法豁免绕过,存量已见 4 条同形 #6497 的面是 scripts/check-adr-0087-registration.mjs,不同文件。且全语料重生成面已随 fix(spec): 同目录裸源码路径通过 fromCategory 解析 —— 9 处纯文本变成链接或代码段 #6534(02:1xZ 起在队列,已合)释放,本单接手该面。
3. 竞态:线程仅本座位 00:48Z 的晋级评论,无任何会话认领,assignee 此前为空。

座位裁决:先量后裁,不是先裁后量(否决窗口照例开在本线程)

正文列了三条方向并写明「都涉及公开可读契约的取舍,⛔ 不建议随手拍板」——同意,但这不等于本单要先送维护者。理由:三条方向的取舍在拿到语料数字之前无人能理性裁定,包括维护者;而本仓两次同族修法(#5340 的枚举预算 80、#6377 的枚举预算 160 / 变体上限 4)都是先把分布测出来、阈值由数据给出,再落裁决。#6350 的 dev 也刚示范过这条路的正确形态:量完、发现判据本身欠定,带着数字回来问,而不是空手问、也不是拍脑袋写。

因此派单要求:三条方向各自测出全语料效果,然后二选一 ——

• 若有一条在证据上明显占优 ⇒ 实施它,阈值必须实测得出而非选定;
• 若几条各有胜负、取舍确实落在公开契约上 ⇒ 带着数字回报 needs_decision,由维护者裁定。

⛔ 无论哪条,不得在没有数字的情况下改契约。

三条不可让的约束(均有先例,不是本单新造)

1. 省略必须自报省了什么(gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 定下):静默前缀让页面看起来完整而实际不完整,对「AI 作者的权威输入」(ADR-0033)而言比宽单元格更糟。
2. 标记必须挣回自己的位置(fix(spec): 参考文档顶层长枚举移入 Allowed Values,联合变体印数量 (#6225, #6226) #6377 实测拒绝了 248 个候选省略中的 54 个):省不下自身标记宽度的省略不做。
3. 4 个无联合的单元格是试金石 —— Manifest.capabilities / PluginRegistryEntry.capabilities / GetTranslationsResponse.translations / PluginSecurityManifest.permissions。方向三(同形去重)对它们完全无效,任何提案都必须说明它对全部 9 格各做了什么,不能只报旗舰样本。

刻意不碰:PageComponent.type(656)属 #6225 族但落在联合变体里,#6225 是有意只匹配「属性自己的类型节点就是词表」——因为对数组元素 / Record 值 / 某个变体而言,「本属性的允许值」不是实话。要收它得先决定表格下方那节怎么措辞才不说谎,⛔ 不在本单顺手改。

⛔ 不得手改生成的 .mdx,一切来自 gen:schema && gen:docs。

---

Generated by Claude Code