会话服务 API 迁到统一面后：202／SSE 断了算不算完成？

现有软件把智能体会话接到自建会话服务后，最容易踩的坑不是「换哪家模型」，而是：HTTP 202、SSE 连接断开，能不能当成这一轮已经完成？旧前缀还能不能静默回退？ 迁调用面时如果仍按「状态码／断流＝成功」或「合同头丢了就改走 /v2」写客户端，界面会提前亮绿灯，工具副作用也可能被换键重放放大。

2026 年 10 月前后，多家智能体／流式 API 公开材料把同一纪律推到开发者面前。BeeOS OpenAPI 变更日志（端点变更标注 2026-10-21，本机 2026-11-09 再核 HTTP 200）写明：阻塞式 POST .../invoke 已从契约移除，迁移路径改为会话消息＋/events SSE，或异步任务＋轮询／事件流；没有旧 invoke 的替代同名路由。BeeOS《调用智能体》（文档页现行，HTTP 200）进一步说明：发消息接口非阻塞，常以 202 受理，回复经会话事件流返回——受理不等于终态。兔子 API《SSE 流式响应与 WebSocket 实时连接》（文档核验日期写明 2026-08-12，HTTP 200）直接写：只有收到协议定义的完成事件，才能把业务状态记为成功；HTTP 200 之后仍可能出现流内错误；断线后若无可恢复游标，应标「未知」而不是静默重试。OceanBase Agent Runtime API（HTTP 200）把 POST /runs 写成异步受理并返回 202 Accepted，完成以 SSE 的 RUN_FINISHED／RUN_ERROR 等终止事件判定；TEXT_MESSAGE_END 只表示段落结束，不等于整次 Run 结束。Qwen Code #4585（HTTP 200）把 POST /prompt 改成非阻塞 202，完成交给 turn_complete／turn_error。sub2api #2245（HTTP 200）则记录了「上游 SSE 在 response.completed 前 EOF、下游仍按 HTTP 200 当成功」的真实事故面。上述材料共同回答的行业问题是：流式／异步智能体 API 里，受理码与连接生命周期 ≠ 业务终态；迁契约时禁止静默降级到旧入口。

对会话服务／客户端开发者，完整行业答案可以收成六句话：

1. 202 Accepted 只表示受理：请求已进入服务端队列或异步路径，不证明模型轮次、工具链或任务已成功结束。
2. SSE 断开不等于完成：连接关闭、代理超时、EOF 都可能发生在终止事件之前；必须以协议定义的终态字段／事件为准。
3. 段落结束 ≠ 整轮结束：文本块 end、delta 停更，通常只覆盖展示层；整轮／Run 另有 terminal／FINISHED／completed 事件。
4. 合同不可用要上报，不要静默回退旧前缀：缺统一合同头、或协商头未回响时，应判失败／不可用，而不是猜「大概是旧服务」改走 /v2。
5. 重试看 retry 语义，不看心情：只有明示可同键重放时才重放；结果未知类错误只能查询状态，禁止换幂等键赌一把。
6. 迁移是换路径／头／错误判定，不是重写成功体：成功响应体往往与旧前缀同形；失败分支与完成判定必须按新合同改。

本文把上述行业问题映射到已核实的 Tansr 机制：@tansr/serve 自 0.13.0（2026-10-02） 起对外唯一 HTTP 调用面为 /api（合同名 unified-v1）；每个响应（含 2xx 与 SSE 打开）必带 tansr-contract／tansr-manifest-revision／tansr-domain／tansr-schema-hash；统一错误信封含 19 个统一码与 6 种 retryAction；事件包络用 terminalStatus 判定轮次／操作终态——文档原文写明 「SSE 结束与 202 都不等于完成」。迁移与旧前缀窗口见 统一 API 总览、迁移与退役时间表、统一请求头、响应头与错误信封、错误处理与重试（本机 2026-11-09 再核均为 HTTP 200；资料站页 last-modified 约 2026-11-07）。它不是 S06 的 401／429／余额／能力关闭分码排障全文，也不是 S08 Electron appkey、S09 鸿蒙运行位置、S01 提示词或 R01 费用；这里只回答：会话服务迁到统一调用面后，客户端怎样判断完成，以及怎样按 retryAction 行动。

直接答案

1. 把完成判定钉在 terminalStatus（或领域约定的终止事件）上：不要用 HTTP 202、SSE 连接结束、首段文本出现或代理返回 200 推断「本轮成功」。
2. 每个 /api 响应都核对四合同头：缺 tansr-contract: unified-v1（或同名重复／词表外头）→ 合同不可用，上报；禁止因此改走 /v2／/v3。
3. 错误按 code＋retryAction 决策：code／status／retryAction 是公开决策面；不要从 HTTP 状态码或 message 文案猜下一步。族内旧码只在 detail.domainCode。
4. 六种 retryAction 对照执行：none 修正请求；same-request 等待后同键重放一次；query-status 只查不重放；rebind 重建绑定；refresh 重读 revision／ETag；rediscover 重新拉能力围栏。result_unknown／commit_unknown 永不换键重放。
5. 迁移时换入口与错误分支，不指望成功体重写：/api 不改写领域成功响应体；旧 error.code === 'session_ended' 一类分支要改为统一码（例如 gone）再按需看 detail.domainCode。
6. 同一会话族不要新旧前缀混用：0.15.0 起混用会记 api.legacy_prefix_mixed；源码不要手写 /v2、/v3/sdk2、/v3/terminal 字面量；路径由 manifest／@tansr/api-client/api 的操作名实例化。
7. 旧前缀退役以当日发行说明为准：@tansr/serve 0.15.1（2026-10-10） 仍是当前文档核对的 npm latest 基线之一；旧前缀窗口缺省仍为 readwrite，显式 readonly／off 才收紧；0.16.0 尚未发布，不得写成「旧前缀已默认只读／已关闭」。
8. 本批未做线上对照实测：标题收窄为机制与客户端纪律说明，不承诺「照抄一段代码即可迁完生产」。

行业问题：为什么「看见 202／流断了」不够

BeeOS 去掉 invoke、Agent Runtime／Qwen 的 202＋终止事件、流式文档「200≠成功」、以及「完成事件前 EOF」事故，共同指向同一产品缺口：异步／流式会话 API 的完成与重试纪律，必须写进客户端，而不是留给运维猜。

你原来要自己做的事 → Tansr 接手什么 → 应用仍要负责什么

原来常要自行完成的：

• 为 /v2、/v3/sdk2、/v3/terminal* 维护多套路径与错误词表。
• 用 HTTP 状态、连接关闭或首包文本推断轮次完成。
• 在合同头缺失或网关异常时静默降级到旧前缀。
• 对「结果未知」类失败换键重放，放大工具副作用。

Tansr 公开机制可接手的部分（以 2026-11-09 抓取的 docs.tansr.com 为准；0.20.0 候发内容不得写成已上线）：

• /api＝unified-v1 唯一对外调用面（serve ≥0.13.0）；成功体与旧前缀同形，改变的是头、错误形与（显式协商后的）事件帧外形。
• 四合同响应头；官方客户端零回退门闸（缺头即 contract_unavailable／等价错误）。
• 统一错误信封：19 统一码＋6 retryAction；retryAdvice／retrySameRequest（@tansr/api-client/api）编码同键重放纪律。
• 事件包络与 terminalStatus；文档明确「SSE 结束与 202 都不等于完成」。
• 迁移表、旧前缀 Deprecation／可选 Sunset、混用告警 api.legacy_prefix_mixed；manifest revision 7（文档当日）。
• 多语言客户端路径模块由 manifest 生成，避免手写旧前缀。

应用仍要负责：

• 把 UI「成功」绑定到 terminalStatus／领域终止语义，而不是 202／断流。
• 改造错误分支与幂等键策略；对 query-status 接好领域查询操作。
• 反代亲和：/api/sessions/:id/ 及其子路径 与旧会话路径同片；SSE 长连接纪律在切流前后一致。
• 显式管理旧前缀窗口环境变量；不把未发布的缺省 readonly 写成已生效。
• 本批未在生产／预发环境做迁移动态对照；不承诺零停机配方。

推荐迁移动作（机制说明，非「一键完成」承诺）

1. 升级 @tansr/serve 到文档核对基线（≥0.13.0 提供 /api；当前页讨论的 latest 核对点含 0.15.1），确认四合同头出现在 2xx 与 SSE 打开响应。
2. 新代码只用 import { createApiClient } from '@tansr/api-client/api'（或各语言等价入口），按操作名调用，不拼 /v2 字面量。
3. 错误处理改为 switch (error.code)＋error.retryAction；需要族内细分时读 detail.domainCode。
4. 事件消费循环以 terminalStatus !== null（或文档规定的终止条件）退出，再更新 UI 终态。
5. 同一进程、同一会话族不要新旧入口并存；切流后打开混用日志核对是否还有交叉访问。
6. 自托管多副本先改会话亲和与 SSE 超时，再切客户端；否则会出现跨副本 404／半截流。
7. 联调把「合同不可用」「result_unknown」「same-request 等待重放」分开展示，避免统一「网络繁忙」。

迁移窗口（以公开页为准，不写成已关闭）

开发者七条纪律（合同原文要点，官方客户端按此实现）：①不静默降级；②不从响应取 URL；③不重放未知副作用；④身份不进体；⑤SSE 结束与 202 都不等于完成；⑥五个游标互不替代；⑦不手写旧前缀。

什么时候采用，什么时候不采用

值得按此推进：已有或新建基于 @tansr/serve 的会话客户端；需要防止「202／断流当成功」与「合同失败静默回退」；正在从 /v2／/v3/* 迁到 /api；安全／稳定性评审要求可审计的完成与重试语义。

先不要：在缺合同头时自动改走旧前缀「保活」；把 result_unknown 当成可换键重试；把 0.15.1 仍为 readwrite 的旧前缀窗口写成「已经只读退役」；或在本批未做对照实测时对外承诺「迁完零事故」。纯本地、永不暴露 HTTP 会话面的进程内 SDK 演示可以另议——一旦经会话服务对外提供异步／SSE 面，就应按统一合同纪律。

与已有稿的差异

• 相对 S06：S06 讲调用失败时 401／429／余额／能力关闭的分码排障；本文讲 统一调用面迁移后的完成判定与 retryAction 客户端纪律（含 202／SSE≠完成、禁止静默降级）。
• 相对 Q01：Q01 侧重「稍后重试」产品话术与 429 阅读；本文侧重 合同头、terminalStatus、六动作重试表与旧前缀退役窗口。
• 相对 S08／S09／S01／R01／M01／G01／S04／S05／S07：凭据换发、鸿蒙运行位置、提示词、费用、换模、媒体、MCP 通告、Skills 完整性、能力位治理均非本篇主线。
• 相对规划 Q11：本篇取开发者向「统一面＋终态＋retryAction」合题，覆盖现有软件接入 AI 的会话服务客户端；品牌向「只讲 Tansr 退役日程」的纯迁移公告不做主标题。

限制（紧邻结论）

• 产品事实以 2026-11-09 抓取的 docs.tansr.com 公开页为准；未做迁移动态联调实测。
• 旧前缀缺省窗口、Sunset 日期以当日发行说明为准；不把未发布的 0.16.0 行为写成已上线。
• BeeOS／兔子 API／OceanBase／GitHub issue 用作行业完成判定纪律旁证，不表示实现兼容或商业关系。
• 不写具体价格；不写「免费试用」；无 AI／身份页脚。
• AI 效果基线本批缺测，按指导单独记录，不阻塞内容交付。