Repository navigation
gen:docs 联合类型的每个对象变体都印一遍完整摘要,一个单元格里出现近乎相同的形状 N 次(PageSlots.slots 1538 字符,枚举已省略后仍如此) #6226
Description
实现 #5340(PR #6211)时量语料量出来的观察类发现,未认领,按 PD#10 立案。与 #6225 同批量出但机制不同,故分开立案。
现象
#5340 落地后仍有 27 个超过 400 字符的类型单元格。上一条(#6225)解释了其中 9 个「顶层长枚举」。剩下 18 个的宽度与枚举无关 —— 是联合类型把每个对象变体的完整摘要各印了一遍。
最清楚的实例是 content/docs/references/ui/page.mdx 的 slots,枚举省略已经生效了 8 次(该行带 8 个 ... +N more 标记),单元格仍有 1538 字符:
{ header?: { type: Enum< 'page:header' | ... | … +29 more > | string; id?: string;
label?: string; properties?: Record< string, any >; … } | { type: Enum< 'page:header'
| ... | … +29 more > | string; ... } | ... }
同一个 { type; id?; label?; properties?; … } 形状被重复了 8 次,彼此只差极少。其余 17 个在 400–656 字符之间(kernel/manifest.mdx 的 navigationContributions / capabilities、automation/state-machine.mdx 的 states、ui/app.mdx 的 navigation、api/protocol.mdx 的 translations 等)。
定性(为什么这是独立的一条,也不是 #5340 的返工项)
- 宽度来源是
anyOf变体数 × 每个变体的摘要长度,不是单个类型的宽度。gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 的字符预算作用在Enum< ... >的 body 上,天然管不到这里 —— 而且在本实例上它已经生效了 8 次,把该行从更宽压到了 1538。 - 信息是正确的,只是重复:
formatType的anyOf分支是variants.map(v => formatType(v, ctx)).join(' | '),对变体之间的相似度一无所知。 - 今天没有用户被误导 —— 与 gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 立单时的定性同类(正确但冗长)。
可能的修法(未验证,留给分诊)
- 对变体数量设上限,与
INLINE_KEY_LIMIT同源地印| …(但要带上被省略的变体数,遵循 gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 定下的「省略必须自报数量」原则); - 或对整个单元格设字符预算,超出时整体退化为
object/ 变体数摘要(gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 原始 issue body 里列过的第二种方案,当时没选); - 或在变体全是同一具名 schema 的情况下恢复
$ref链接而不是逐个内联展开(与 gen:docs 顶层长枚举仍是单个 6092 字符的表格单元格 ——### Allowed Values项目符号只对「整个 schema 是枚举」生效,对「某个属性是枚举」从不生效 #6225 的第二种修法同源)。
三种都涉及公开可读契约的取舍(读者看到的是变体的完整枚举还是数量),⛔ 不建议随手拍板;需要分诊给出方向。逐页确认重生成 diff,不得手改生成的 .mdx。
相关 / 串行
同文件面:packages/spec/scripts/lib/format-type.ts。与 #5340(PR #6211)、#6225、#5729、#5606、#5338 同源。须与该文件面的其他在飞单串行,不得同批并行。
Activity
os-zhuang commentedon Aug 7, 2026
维护者裁决(2026-08-07,经
domain:spec-tooling座位 PM 呈报):变体数上限 + 自报被省略的变体数。即:对
anyOf变体数量设上限,超出时印| …,并带上被省略的变体数。裁决理由(呈报时给出,维护者采纳)
选它不是因为这个阈值更科学,而是因为一致性:#5340(PR #6211,今天已合入)刚刚为同一张表里的长枚举确立了「省略必须自报数量」的原则 —— 理由是纯前缀截断会让页面看起来完整而实际不是,读者无法区分「一共 7 项」和「49 项里的前 7 项」。这些页面是 AI 作者的权威输入(ADR-0033),一个靠省略说谎的页面比一个过宽的单元格更糟。
同一张表里出现两种省略风格,才是比宽度更严重的问题。 另外两个方向(整格字符预算退化为
object、具名 schema 恢复$ref)信息损失更大或改动面更宽,在「今天没有用户被误导、只是冗长」这个定性下不划算。派发时的硬要求:阈值必须实测(像 #5340 那样在真实语料上跑候选值、给出命中数与 p99 单元格宽),⛔ 不得拍脑袋定;并且要有一条「标记必须挣回自己的位置」的守卫 —— 只省略一两个变体时,
… +N more占的字符可能比省下的还多,#5340 实测有 29 处是净亏。⏸ 暂不派发的原因(纯文件面串行)
本单落点
packages/spec/scripts/lib/format-type.ts且会重生成content/docs/references/**,而 PR #6308(#5853,模块标题改为声明式)此刻正在重生成同一棵树。同一时刻只能有一张重生成该树的单在飞 —— 今天已实测过代价:两棵独立重生成的树会零冲突合并却落地陈旧组合(#6224 实测 merge 零冲突,而os-regen钩子独立标出 33 页交集)。排队顺序:#6308 落地 → #6225(顶层长枚举仍是单个 6092 字符单元格,同文件面)→ 本单。两者可考虑合并派发以省一次重生成,派发时定。
Generated by Claude Code
os-zhuang commentedon Aug 7, 2026
🔒 认领 (claim) — os-dev agent
session_014wsZeReNTqiceBfLb5Pyf5claude/issue-6225-reference-cell-widthdomain:spec-tooling本单与 #6225 打包派发,同一个 PR 同时
Fixes两单(同文件面 + 同一次content/docs/references/**重生成)。已读到本单 2026-08-07 的维护者裁决并按其执行:变体数上限 + 自报被省略的变体数,阈值实测、并带「标记必须挣回自己的位置」守卫。裁决不重开。
串行前置已满足:#6308(#5853)已合入 main(
2c26040a4)。Generated by Claude Code
Generated by Claude Code
fix(spec): 参考文档顶层长枚举移入 Allowed Values,联合变体印数量 (objectstack-ai#6225, o…