`ApiEndpointSchema.path` 的 `.describe()` 举的例子会被 ADR-0121 D1 当场拒绝 —— 而这段文案正是 Studio 端点表单显示给作者的提示

[os-zhuang]

越范围发现,记录于 #5271 实现期,不在该 PR 内修(该 PR 的文件面是注册表与 schema 绑定,改 .describe() 会动生成基线,而同批有四个 PR 正在动生成物)。

事实

packages/spec/src/api/endpoint.zod.ts:

path: z.string().regex(/^\//).describe('URL Path (e.g. /api/v1/customers)'),

举的例子是 /api/v1/customers。而 ADR-0121 D1 把声明路径收紧成了 运行前缀 + /apps/ + 命名空间 + 子路径,publish 门(namespaceGate)对任何落在 carve-out 之外的路径直接拒绝。也就是说:这个 schema 自己举的例子,publish 会拒。

为什么现在才要紧

#5271 之前 api 没有注册 schema,/meta/types 不为它出 JSON Schema,Studio 只能给一个 raw-JSON 文本框 —— 这段 .describe() 没有渲染面。#5271 之后它成为 metadata-admin 表单里那个字段的说明文字,也进入 objectstack.json 生成的 JSON Schema。于是一段会被拒绝的示例,变成了作者(很常是 AI 作者,ADR-0033)照抄的第一手提示。

ApiMappingSchema 那几个 .describe() 同理值得一并复核。

建议(不预判)

把示例换成 carve-out 形状,并说明命名空间段派生自 manifest.namespace(ADR-0121 D2)而非作者自由字段 —— 门函数的拒绝文案里已经有一份措辞可以复用,不需要新发明判据。

改动会移动 authorable-surface.json / json-schema.manifest.json,按 os-regen 四步整体重生成。

关联

#5271(出处)、ADR-0121 D1/D2、#5040 E7。

[os-zhuang]

分诊结论:pm:queue + domain:spec

复核结果:

1. 前提未过时:git show origin/main:packages/spec/src/api/endpoint.zod.ts(HEAD cdfbee2,含 feat(spec): api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS (#5271) #5312/[spec] api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS(#5206 第 1 步,拆单) #5271)第 55 行仍是 path: z.string().regex(/^\//).describe('URL Path (e.g. /api/v1/customers)'),一字未改。同一提交树下 packages/spec/src/api/endpoint-publish-gate.ts 的 appEndpointMountPrefix() 证实 ADR-0121 D1 的挂载前缀是 `${DEFAULT_RUNTIME_PREFIX}/apps/${namespace}/`(即 /api/v1/apps/<namespace>/...),示例给出的 /api/v1/customers 落在 apps/<namespace>/ carve-out 之外,namespaceGate 会拒绝——问题描述的事实成立,不是过时前提。
2. 查重:搜索 objectstack/objectui/cloud 三仓开放 issue 与 PR,未见任何在修 endpoint.zod.ts 的 .describe() 或 namespaceGate 示例文案的进行中工作;#5311/#5384/#5227/#5309/#5488 都是 ApiEndpointSchema 附近其他角度的独立发现(未知键收紧、allowRuntimeCreate 未接线等),与本单的示例文案问题不重叠,不构成同影或阻塞。
3. 归类:定位到具体文件与具体行(packages/spec/src/api/endpoint.zod.ts 的 path/ApiMappingSchema 字段 .describe()),且 [spec] api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS(#5206 第 1 步,拆单) #5271 落地后这段文案已经是 metadata-admin 端点表单对作者(含 AI 作者)展示的第一手提示,属于当下就在误导作者的具体缺陷,而非无用户可见影响的观察类记录;修复方向也不涉及产品语义裁决——carve-out 形状与措辞可直接复用 endpoint-publish-gate.ts 拒绝文案里已有的表述——因此归类为 pm:queue 而非 finding 或 needs-user-decision。
4. 域:改动落点是 packages/spec/src/api/endpoint.zod.ts(以及连带的 authorable-surface.json / json-schema.manifest.json 生成物),按域表归 domain:spec,单一域,不需要跨域拆分。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code