finding(docs/types): `content/docs/blocks/block-schema.mdx` 教的整族 block 词汇表(含节点位置的 `slot`)没有任何 renderer

[yinlianghui]

观察类 finding —— 记录一个已声明但无渲染面的词汇表,不是今天有用户正在踩的具体缺陷(这一族目前没有已知的运行时使用者)。发现于 #4823 的实施(PR 见其分支),是那道门第一次全扫时被豁免表挡下的一处,豁免理由里指向本单。

事实

packages/types/src/blocks.ts + packages/types/src/zod/blocks.zod.ts 声明了一整族带 type 判别式的 schema,并有 Zod 校验:

判别式	声明处
block	blocks.ts(BlockSchema)
block-library	blocks.ts:263 / blocks.zod.ts:100
block-editor	blocks.ts:315 / blocks.zod.ts:116
block-instance	blocks.ts:357 / blocks.zod.ts:130

content/docs/blocks/block-schema.mdx 把这四个都当作可写的 schema 文档来教。但仓内没有任何 ComponentRegistry.register() 认领其中任何一个键 —— 按 #4823 那道门的派生口径(661 个注册键)全部落空。

这本身未必是缺陷:BlockSchema 是一份定义(像 FormSection 那样),不是一个被渲染的节点,不需要注册。但 BlockLibrarySchema / BlockEditorSchema 读起来是组件 schema(它们各自带 type 判别式,形状与被渲染的节点一致),这两者到底该不该有 renderer,是需要维护者定的方向,不是我这边能替它选的。

更硬的一处:slot 在真节点位置上

BlockSchema.template 声明为 SchemaNode | SchemaNode[](blocks.ts:190 附近),也就是真的会走 SchemaRenderer。而 block-schema.mdx:254 在 template.children 里教:

{
 type: 'slot',
 name: 'content'
}

slot 在仓内任何地方都不存在 —— 不是注册键,blocks.ts 里也没有 type: 'slot' 的声明(只有 BlockSlot 接口和 slots?: BlockSlot[] / slotContent 两个键)。所以这一处比上面四个更接近 #4823 的原形:一个处在渲染路径上的节点,类型名不存在,照抄得 OBJUI-001。

之所以没在 #4823 的 PR 里顺手改掉:正确写法不唯一。要么给 block 系统的插槽占位符定一个真的节点类型并注册它,要么这一段该改成 slotContent 那条已声明的路子 —— 两种读法通向不同的架构,#4823 明确是「最小静态门 + 同形改名」,不预决这个。因此该处目前带理由指向本单留在 scripts/check-doc-component-types.mjs 的 DOC_TYPE_EXEMPTIONS 里,本单一旦有结论,那条豁免应当随之删掉(门会把失效的豁免报成 stale-exemption,所以它不会被忘掉)。

为什么标 finding 而不是 pm:queue

这是一个方向问题(这族 schema 到底要不要渲染面),不是一个待修的 bug;而且它今天不会打到任何人 —— 没有已知的运行时使用者,那页文档教的是类型层的形状。要不要做、做成哪一种,交给分诊轮定级。

参考

• finding: 教学面 prose(content/docs/**.mdx 代码块)没有 catalog 侧 #4616 那样的「不许出现 OBJUI-001」棘轮,同一缺陷已复发三次 #4823 / scripts/check-doc-component-types.mjs(发现来源,豁免表里 content/docs/blocks/block-schema.mdx 一节)
• packages/types/src/blocks.ts、packages/types/src/zod/blocks.zod.ts
• content/docs/blocks/block-schema.mdx

[os-support-ai]

Triage (concentrated finding round): finding → needs-user-decision. The question is direction, and it gates a recorded exemption (DOC_TYPE_EXEMPTIONS stale-exemption cleanup waits on this card).

Question: should the block schema family (block-library / block-editor / block-instance, plus the doc-taught slot node) get renderers, or be re-scoped as type-level definitions with the docs corrected?

Options: A build renderers for the family (feature work, needs appetite); B re-scope as type-level: correct block-schema.mdx (teach slotContent, delete the phantom slot node example), keep BlockSchema as a definition, drop the component-schema framing of block-library/block-editor; C retire the family (ADR-0049 enforce-or-remove).

Four-axis block:

• Platform long-term coherence: a schema family shaped like renderable nodes with no renderer is a standing dialect trap; either wiring it or renaming its intent shrinks the ambiguity — leaving it (status quo) grows it.
• Measured business pull: zero registered keys, zero runtime consumers, zero known users; the docs page is the only consumer-facing surface. No pull for A today.
• AI-agent error-resistance: the slot example is copy-bait that yields OBJUI-001 at render; B removes the bait with the smallest surface; A would make the docs true at the price of new surface nobody asked for.
• Startup scope discipline: A is declare-and-maintain with no pull — disfavored; B is a docs-truth fix; C is maximal but touches published types whose external usage is unmeasured.

Recommendation: B (docs corrected to the declared slotContent path, family stays type-level), with C revisited only if a later liveness pass shows the whole family inert externally. On ruling, the stale exemption in scripts/check-doc-component-types.mjs gets dropped in the implementing PR.

本评论来自分诊座位 Routine (session session_018euHiF12oV8iSfYdjVioUF).

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Option B — docs-truth fix, re-scoped as type-level

• Correct content/docs/blocks/block-schema.mdx: teach the declared slotContent path and delete the phantom type: 'slot' example (copy-bait that yields OBJUI-001 — slot exists nowhere in the repo). Keep BlockSchema framed as a definition (like FormSection), dropping the component-schema framing for the family.
• Option A (build renderers for the family) is rejected on zero pull — declare-and-maintain with no measured demand; Option C (retire the family) is deferred, to be revisited only if a later liveness pass shows the published types inert externally.
• The implementing PR must drop the DOC_TYPE_EXEMPTIONS entry in scripts/check-doc-component-types.mjs that points at this card (the gate reports stale exemptions).

State: needs-user-decision → pm:queue.

---

Generated by Claude Code