一致性不是“Schema 能对上就行”，而是三层一起对齐：协议对象语义、入口请求形态、以及对外边界口径。

推荐阅读

发布前看三层

对象语义

Demand、Grant、Event 等对象与标准保持一致。

请求形态

请求字段、鉴权和同步/异步响应遵循 OpenAPI。

外部边界

只依赖公开入口，不把本地实现当成对外契约。

提示你要对齐的不是实现细节，而是对外口径

这页用于帮助你在发布前做自检：哪些对象语义要和标准保持一致、哪些字段以 OpenAPI 为准、哪些行为不应被集成方依赖。

1) 协议层：对象语义一致

当你在 structured_input 中携带协议层对象时，应保持和协议仓的语义一致（例如 Demand、AuthorizationGrant、ProtocolError、ProtocolEvent）。

2) 入口层：请求形态一致

POST /api/execute 的请求结构以公开 OpenAPI 为准，最小可执行子集通常包含：

• domain
• required_scopes
• execution_mode
• text or structured_input
• key_id（仅在特定 Bearer 模式下需要，以 OpenAPI 为准）

并且：

• 鉴权与权限校验必须通过（否则直接拒绝）
• 声明了 required_scopes 就必须真的满足（不要把它当“注释”）
• 同步集成要能处理 output / usage_applications / 可选 exact_bridge
• 异步集成要只沿响应返回的 follow-up URL 继续（不要猜 URL）

3) 边界层：对外行为一致

以下行为不符合当前对外口径（也不应成为集成方依赖）：

• 依赖未公开的内部 URL 或接口名
• 以某个垂直站点的本地实现“推导出”对外契约
• 把本地状态当作 entitlement/quota 的最终解释并绕过平台校验

4) 发布前自检清单

• 请求包含并稳定保存：request_id、trace_id、idempotency_key（若使用）
• 能发送 text 或 structured_input，并在日志里记录请求摘要
• 携带协议层对象时放在 structured_input，不要“扩展”顶层请求结构
• 能正确处理 200（同步）与 202（异步，若开放）
• 能把返回的关键字段落库/落日志，保证排障与对账不断链

推荐阅读

配套页面

信任边界

避免把规范对象、示例字段误当成对外入口。

API Reference

字段与响应结构对照（OpenAPI 优先）。

上线检查

幂等、重试、告警与安全检查。

部署手册

文档站发布流程与校验脚本。