维护者 2026-08-04 已裁决三项(经执行器车道 PM 的对比分析,含主流平台调研;本 issue 正文即裁决的持久记录),需起草 ADR 落档。docs-only PR,不改任何代码或 schema —— 执行体(publish 门、describe 文案)由 #5040 的 E 系列与 E7 翻转 PR 按本 ADR 实施。
三项裁决
① 命名空间制(否决「任意路由」)
声明式端点(apis: / ApiEndpointSchema.path)不得认领任意路由 。路径收紧为:
apps 为平台保留的唯一切出段;<应用名> 派生自声明方 stack/app 的规范身份(起草时从 stack.zod.ts 实核可用的身份键),作者只自由命名子路径。publish 期强制。
依据 :主流平台零例外 —— Salesforce Apex REST(/services/apexrest/<ns>/…)、ServiceNow Scripted REST(/api/<scope>/<api_id>/…)、MS Dataverse Custom API(纯名字派生)、Shopify App Proxy(/apps/<子路径>)、K8s CRD(group/version/kind 派生),没有一家让应用元数据认领任意路由。收益:#5040 设计 §1 的保留前缀 pin 清单、spec/runtime 双端一致性测试、跨应用撞路径整类问题在构造上消失;URL 自带应用名可反查;AI 需要掌握的平台内部知识归零。时机红利:v17 硬拒(#4936 )已清场,17.x 收紧零迁移成本。
② 通道分工:actions = 平台内命令,apis = 平台外集成面
一句话判据(写进 ADR 与两侧 schema describe 的执行项):调用方在平台内(有会话、懂平台方言:UI 按钮、AI/MCP、SDK)→ actions;调用方在平台外(第三方 webhook、合作方系统)→ apis(资源读写 + webhook 接收)。
依据:actions(/actions/:object/:action,POST-only)已具备参数契约(ADR-0104)、权限门(ADR-0066 D4)、HTTP 语义化错误(#3962 )、AI/MCP 暴露(ActionAiSchema),是成熟的命令通道;而平台外调用方的三个硬特征(报文形状对方定 → 需 inputMapping 防腐、无平台会话 → 需 authRequired: false + 端点级 rateLimit、URL 是写进对方系统的对外契约 → 需稳定 + OpenAPI)actions 结构上均不满足。行业同构:Salesforce 内部 Invocable Actions / 对外 Apex REST;ServiceNow 内部 UI Action / 对外 Scripted REST。
③ type: flow 保留在 ApiEndpoint,配三条纪律
「URL 触发 flow」是入站集成的第一原语(Zapier/Make/n8n 的 webhook trigger 即此;showcase 自证案例 POST …/inquiries/purge 本身就是 flow 端点),摘除它 = 第三方 webhook 接收没有元数据故事,只剩代码逃生舱,逆北极星。保留,重叠带用三条纪律约束:
分工判据 (②的一句话)写进 ADR 与 ApiEndpointSchema/ActionType 两侧 describe(describe 修改属 spec 车道执行项,ADR 只立规则);同管线红线 :flow 端点纯委派 automation 服务(与 action 触发同一条 execute + 身份转发管线,17.x 立项:建设声明式 ApiEndpoint 执行器(挂载 + matchEndpoint + authRequired/cacheTtl/inputMapping/outputMapping 逐键接线) #5040 匿名端点防呆门 (E7 publish 门执行项):authRequired: false 的端点必须同时声明 rateLimit,否则 publish 拒绝并附处方;签名验证(webhook 真实需要)明示为将来词表候选 ,不在本 ADR 承诺。
ADR 关系与范围
验收
关联:#4936 (裁决与实测)、#4939 、#5040 (设计全文)、#4910 (四问依据)、ADR-0076、ADR-0049。
维护者 2026-08-04 已裁决三项(经执行器车道 PM 的对比分析,含主流平台调研;本 issue 正文即裁决的持久记录),需起草 ADR 落档。docs-only PR,不改任何代码或 schema —— 执行体(publish 门、describe 文案)由 #5040 的 E 系列与 E7 翻转 PR 按本 ADR 实施。
三项裁决
① 命名空间制(否决「任意路由」)
声明式端点(
apis:/ApiEndpointSchema.path)不得认领任意路由。路径收紧为:apps为平台保留的唯一切出段;<应用名>派生自声明方 stack/app 的规范身份(起草时从stack.zod.ts实核可用的身份键),作者只自由命名子路径。publish 期强制。依据:主流平台零例外 —— Salesforce Apex REST(
/services/apexrest/<ns>/…)、ServiceNow Scripted REST(/api/<scope>/<api_id>/…)、MS Dataverse Custom API(纯名字派生)、Shopify App Proxy(/apps/<子路径>)、K8s CRD(group/version/kind 派生),没有一家让应用元数据认领任意路由。收益:#5040 设计 §1 的保留前缀 pin 清单、spec/runtime 双端一致性测试、跨应用撞路径整类问题在构造上消失;URL 自带应用名可反查;AI 需要掌握的平台内部知识归零。时机红利:v17 硬拒(#4936)已清场,17.x 收紧零迁移成本。② 通道分工:actions = 平台内命令,apis = 平台外集成面
一句话判据(写进 ADR 与两侧 schema describe 的执行项):调用方在平台内(有会话、懂平台方言:UI 按钮、AI/MCP、SDK)→ actions;调用方在平台外(第三方 webhook、合作方系统)→ apis(资源读写 + webhook 接收)。
依据:actions(
/actions/:object/:action,POST-only)已具备参数契约(ADR-0104)、权限门(ADR-0066 D4)、HTTP 语义化错误(#3962)、AI/MCP 暴露(ActionAiSchema),是成熟的命令通道;而平台外调用方的三个硬特征(报文形状对方定 → 需inputMapping防腐、无平台会话 → 需authRequired: false+ 端点级rateLimit、URL 是写进对方系统的对外契约 → 需稳定 + OpenAPI)actions 结构上均不满足。行业同构:Salesforce 内部 Invocable Actions / 对外 Apex REST;ServiceNow 内部 UI Action / 对外 Scripted REST。③
type: flow保留在 ApiEndpoint,配三条纪律「URL 触发 flow」是入站集成的第一原语(Zapier/Make/n8n 的 webhook trigger 即此;showcase 自证案例
POST …/inquiries/purge本身就是 flow 端点),摘除它 = 第三方 webhook 接收没有元数据故事,只剩代码逃生舱,逆北极星。保留,重叠带用三条纪律约束:ApiEndpointSchema/ActionType两侧 describe(describe 修改属 spec 车道执行项,ADR 只立规则);execute+ 身份转发管线,17.x 立项:建设声明式 ApiEndpoint 执行器(挂载 + matchEndpoint + authRequired/cacheTtl/inputMapping/outputMapping 逐键接线) #5040 设计 §4 已立),零语义分叉 —— 保证选错通道只是风格问题,不是行为问题;authRequired: false的端点必须同时声明rateLimit,否则 publish 拒绝并附处方;签名验证(webhook 真实需要)明示为将来词表候选,不在本 ADR 承诺。ADR 关系与范围
apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint全仓无实现 #4936 裁决)→ 17.x 执行器(17.x 立项:建设声明式 ApiEndpoint 执行器(挂载 + matchEndpoint + authRequired/cacheTtl/inputMapping/outputMapping 逐键接线) #5040)→ 翻转 PR(E7)实施本 ADR 的 publish 门;matchEndpoint签名、cacheTtl 键形状、兜底 seam 等留在 17.x 立项:建设声明式 ApiEndpoint 执行器(挂载 + matchEndpoint + authRequired/cacheTtl/inputMapping/outputMapping 逐键接线) #5040 设计文档;验收
docs/adr/<下一空位编号>-*.md(起草时以 origin/main + 开放 PR 双查确认编号未被占用,预计 0120),头部格式对齐 ADR-0118(状态/日期/关联/执行项/动因);apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint全仓无实现 #4936/ApiRegistry/api-registryplugin 只在packages/core/examples/里被装配,无任何真实 composition 挂载 ——ApiEndpointRegistrationSchema因此整面零执行 #4939/17.x 立项:建设声明式 ApiEndpoint 执行器(挂载 + matchEndpoint + authRequired/cacheTtl/inputMapping/outputMapping 逐键接线) #5040(+ E7 届时补);.changeset/adr-XXXX-*.md有先例);content/docs/releases/,不改任何.zod.ts/ runtime 代码。关联:#4936(裁决与实测)、#4939、#5040(设计全文)、#4910(四问依据)、ADR-0076、ADR-0049。