以下清单用于“上线前自检”：帮助你把幂等、标识保存、错误处理与安全边界做完整，避免上线后靠临时排障硬撑。

尚在选择路径时，请先看 选择接入路径、API 规范与接入评估 与 快速开始。

提示上线的最低标准

• 至少打通一条真实请求，并能稳定复现与排障。
• 能明确处理鉴权/权限失败与请求体失败（不是“失败就重试”）。
• 把关键标识保存下来：request_id / trace_id / idempotency_key。

推荐阅读

上线前的四个检查面

请求链路

真实请求可稳定发送，并保留完整关联标识。

权限边界

凭证、scope、entitlement 与 quota 失败可区分。

结果处理

同步、异步、重试与 follow-up URL 有明确策略。

排障运营

日志、告警、审计和回退路径能够被团队执行。

1. 01

   真实请求已复现

   至少一条真实请求可端到端执行、复现并定位。

   不满足时：先回到最小请求，稳定复现链路。查看检查项 →
2. 02

   关联标识已保存

   request_id、trace_id 与 idempotency_key 可持续关联。

   不满足时：先统一保存标识，不把排障留给临时日志。查看检查项 →
3. 03

   失败路径可区分

   鉴权、请求体与后续跟进失败有不同处理策略。

   不满足时：先建立分流与回退规则，不统一重试。查看检查项 →
4. 04

   后续处理有边界

   同步/异步、返回 URL、日志、告警与回退责任已明确。

   不满足时：先固化处理边界与团队责任。查看检查项 →

上线前应已完成

• 已打通至少一条真实请求。
• 已能处理 Bearer、权限与返回结构。
• 已能区分同步 200 和异步 202。

基础链路

• 稳定生成或保存 request_id、trace_id、idempotency_key。
• 所有请求统一走公开入口与白名单路由。
• 前台、插件或中间层不要依赖未公开的 URL。

请求构造

• 能稳定发送 text；复杂上下文使用 structured_input。
• 清楚 admin bearer 何时需要 key_id。
• 如携带中性协议对象用于审计或翻译，仍放在 structured_input，不将其当作默认顶层请求结构。

返回与失败处理

• 能处理同步 200 与异步 202。
• 保存同步 output、usage_applications、可选 exact_bridge，以及异步 workflow 标识与 URLs。
• 对 admission failure 有明确重试与回退规则。
• 只使用响应返回的 workflow URL 继续处理，不自行拼接 URL。

运维与排障

• 本地日志能按 request_id 或 trace_id 追踪。
• 异步 workflow 引用不会丢失。
• 团队知道多数早期错误来自鉴权、scope、请求体校验与幂等策略，而不是业务逻辑本身。

推荐阅读

配套页面

快速开始

从最小请求升级到稳定集成骨架。

执行生命周期

同步/异步差异与 follow-up URL 处理。

Error Model

三段式错误分类，写出可维护的重试与告警。

网络成熟度与证据

将上线前自检连接到可复核的网络证据与撤回边界。

一致性要求

发布前核对标准层与入口层口径一致。