实现 #5340 (PR #6211 )时量语料量出来的观察类发现,未认领 ,按 PD#10 立案。不是该 PR 造成的,也不是 它的返工项 —— #5340 的范围明确只收「内联形状里的第二份拷贝」,而这一条恰恰是那份唯一的完整拷贝 ,故意不动才是对的。
现象
#5340 落地后,content/docs/references/** 里仍有 27 个超过 400 字符的类型单元格 ,其中 9 个是「整格就是一个 Enum< ... >」的顶层枚举 :
字符数
页面
属性
6092 api/contract.mdxApiError.code(261 个成员)
1159
api/errors.mdxcode
1083
api/events.mdxtype
561
data/field.mdx / ui/action.mdx / ui/view.mdx / ui/bulk-action.mdx / ai/solution-blueprint.mdxtype(49 个字段类型)
6092 字符挤在一个 GFM 表格单元格里,和 #5340 修掉的那个是同一种阅读体验。
机制(为什么它没被 #5340 的省略碰到,也不该被碰到)
两件事叠在一起:
formatType 的省略只在 ctx.inShapeSummary 置位时生效,而该标志只在内联摘要的 { ... } 之下设置。顶层位置永不省略 ,这是 gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 api/contract.mdx 上没有 ErrorCode 小节、没有 任何项目符号列表,这 6092 字符是该页上这份词表的唯一 完整拷贝,省略它等于把信息删掉。build-docs.ts 确实有一条更适合长词表的渲染路径 —— ### Allowed Values + 每个成员一行项目符号 —— 但它只在整个 schema 是 type: 'string' + enum 时才走(build-docs.ts 里 mainDef.type === 'string' && mainDef.enum 那一支)。一个属性 的类型是枚举时永远走不到,只能得到一个表格单元格。
所以 261 个成员的词表落在哪种渲染上,取决于它在 zod 里是被提升成了具名 schema 还是内联在属性上 —— 而这跟「读者需要怎样读它」无关。
可能的修法(未验证,留给分诊)
顶层枚举超过 N 个成员/字符时,单元格印一个短摘要,完整词表移到该属性下方的 ### Allowed Values 项目符号列表(复用已有渲染路径,且信息不丢 );
或让具名枚举 schema 的 $ref 保持链接而不是被内联展开,把词表留在它自己的页/小节里。
两种都要逐页确认重生成 diff。⛔ 不得手改生成的 .mdx。
相关 / 串行
同文件面:packages/spec/scripts/lib/format-type.ts + build-docs.ts。与 #5340 (PR #6211 ,内联枚举省略)、#5729 、#5606 、#5338 同源;另有一条同批量出的、机制不同 的残留宽度观察已另立(union/shape 变体重复)。须与该文件面的其他在飞单串行 ,不得同批并行。
实现 #5340(PR #6211)时量语料量出来的观察类发现,未认领,按 PD#10 立案。不是该 PR 造成的,也不是它的返工项 —— #5340 的范围明确只收「内联形状里的第二份拷贝」,而这一条恰恰是那份唯一的完整拷贝,故意不动才是对的。
现象
#5340 落地后,
content/docs/references/**里仍有 27 个超过 400 字符的类型单元格,其中 9 个是「整格就是一个Enum< ... >」的顶层枚举:api/contract.mdxApiError.code(261 个成员)api/errors.mdxcodeapi/events.mdxtypedata/field.mdx/ui/action.mdx/ui/view.mdx/ui/bulk-action.mdx/ai/solution-blueprint.mdxtype(49 个字段类型)6092 字符挤在一个 GFM 表格单元格里,和 #5340 修掉的那个是同一种阅读体验。
机制(为什么它没被 #5340 的省略碰到,也不该被碰到)
两件事叠在一起:
formatType的省略只在ctx.inShapeSummary置位时生效,而该标志只在内联摘要的{ ... }之下设置。顶层位置永不省略,这是 gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例) #5340 刻意的设计 —— 已核实api/contract.mdx上没有ErrorCode小节、没有任何项目符号列表,这 6092 字符是该页上这份词表的唯一完整拷贝,省略它等于把信息删掉。build-docs.ts确实有一条更适合长词表的渲染路径 ——### Allowed Values+ 每个成员一行项目符号 —— 但它只在整个 schema 是type: 'string'+enum时才走(build-docs.ts里mainDef.type === 'string' && mainDef.enum那一支)。一个属性的类型是枚举时永远走不到,只能得到一个表格单元格。所以 261 个成员的词表落在哪种渲染上,取决于它在 zod 里是被提升成了具名 schema 还是内联在属性上 —— 而这跟「读者需要怎样读它」无关。
可能的修法(未验证,留给分诊)
### Allowed Values项目符号列表(复用已有渲染路径,且信息不丢);$ref保持链接而不是被内联展开,把词表留在它自己的页/小节里。两种都要逐页确认重生成 diff。⛔ 不得手改生成的
.mdx。相关 / 串行
同文件面:
packages/spec/scripts/lib/format-type.ts+build-docs.ts。与 #5340(PR #6211,内联枚举省略)、#5729、#5606、#5338 同源;另有一条同批量出的、机制不同的残留宽度观察已另立(union/shape 变体重复)。须与该文件面的其他在飞单串行,不得同批并行。