Repository navigation
150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593
Description
Activity
裁决(PM 代决,维护者可否决):策略 (2) 按需补 ——
- 优先补两类:枚举类(
system/可观测性枚举)与 request/props 形状(ui/Element*Props/Page*Props、data/DataEngine*Request)——这些是 AI 使用者最需要可标注类型的位置; - 路径统一:加
export type别名 →gen:api-surface→gen:docs→ 删基线行;棘轮只减不增(基线现为 138 条,全部 no-type-export); - 不一次性全补:一次撑大 api-surface 约 150 个导出而无消费方验证,与 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 Stage C 不排期同理;
- 新增 spec 形状(spec: dashboard date filter 的 defaultValue 没有作者时校验 —— 拼错的预设名要到浏览器控制台才被发现 #4614 / ConnectorActionDescriptor declares nothing about whether an action reads or writes, so the platform cannot count what a connector_action did #4395 / [i18n] 为 flow 与 workflow 提供可作者化的标签和节点翻译契约 #4426 等)一律自带类型别名,不添新债——此条作为后续 spec PR 的评审项。
防 AI 轴:有可标注类型,使用侧才不会退化到
any或自己z.infer被lazySchema()拖累。已入队待派(按需分批)。
Generated by Claude Code
- 优先补两类:枚举类(
Release-board audit (maintainer-directed re-audit of non-board
domain:specitems, 2026-08-07): addingtarget:v17— metadata-protocol change, size M, low-risk: strategy 2 already ruled — batch-addexport typealiases for enums/props/request shapes so the 150 published schemas getimport typeexamples; purely additive type-export surface, the ratchet baseline only shrinks andcheck:docsgates it. Maintainer directive: protocol changes land in v17 unless large/risky. Triage seat may veto.
Generated by Claude Code
Maintainer ruling (2026-08-08): Option B — the remaining 40 non-isomorphic schemas stay on the baseline; no XParsed pairs are minted without a measured consumer.
Rationale (three-axis review):
- Business: XParsed has zero measured consumers today — minting 40 unconsumed public names is exactly the shape the startup-focus principle exists to stop.
- Long-term: every name that enters api-surface costs a major to exit. Not minting is free today; minting wrongly is a batch of future ADR-0049 retirement debt. The asymmetry decides it.
- AI-error containment: the check:spec-parsed-alias ratchet already blocks new drift, so the unused aliases would add no protection for AI authors.
The fallback (aliasing only the ElementProps / DataEngineRequest families) stays available if a real parsed-state consumer shows up — reopen or file fresh on measured demand. Standing rules unchanged: the baseline ratchet is shrink-only, and every new spec shape ships with its alias.
Bookkeeping: batch 1 shipped via PR #6606 (73 aliases + 73 ADR-0122 pins, merged 2026-08-08). Of the remaining 63 baseline entries: 17 belong to the #4570 rename track, 5 live in in-flight host files, 1 (ServiceStatus dual-source) is #6604, and the 40 are decided here. Closing as completed; with the decision made this card exits the v17 board.
Maintainer directive (verbatim, covering all 14 inbox cards): 「你的建议全部接受」. Recorded by PM session session_01JaVVMrSxt7Tgi1uwEuDtH7.
Generated by Claude Code
- added a commit that references this issue
on Aug 17, 2026 - added a commit that references this issue
on Sep 24, 2026 - added a commit that references this issue
on Sep 28, 2026
#4570 把 reference 页的 import 示例改成对照
api-surface.json真实导出面生成之后,顺带把「推导得到但导出面里查无此名」的名字全部落成了棘轮基线packages/spec/docs-import-surface.baseline.json。目前 154 条,其中 150 条是no type export:schema 常量XSchema正常导出,但对应的export type X = z.infer< typeof XSchema >不存在。为什么值得单独跟
这 150 个 schema 的文档页现在只有
import { XSchema }一行,没有import type { X }。对手写代码的人只是不方便;对 AI 写元数据应用的人是缺一半契约——他能拿到运行时校验器,却没有可以标注变量、写函数签名的类型,只能退化成any或自己z.infer<>(而z的版本和lazySchema()包装并不总是好写)。分布很集中,像是历史习惯而非有意设计:
system/的可观测性枚举(LogLevel、SpanKind、MetricType、TaskStatus…)、ui/的Element*Props/Page*Props一族、data/的若干 request 形状(DataEngine*Request)。完整清单见基线文件。需要决策的点
export type。方向上正确(声明即导出、类型可用),但一次性把api-surface.json撑大 150 个导出,是可观的公共面扩张,需要维护者点头;check:docs挡红,存量慢慢还。倾向 (2):枚举与 props 形状是元数据作者最常需要标注的,补起来收益最直接;而纯内部的中间 schema 留在基线里,比硬凑一批没人用的导出更诚实。
无论选哪条,修复方式都一样:加别名 →
gen:api-surface→gen:docs,并删掉基线里对应的行(只减不增的棘轮,陈旧条目同样会让check:docs变红)。发现于 #4570。