feat: harden public OpenAI API contracts

docs-developer/responses-api.mdx

@@ -5,10 +5,19 @@ description: 使用 OpenAI Responses 风格的 HTTP 与 SSE 接口调用平台
 
 # Stateful Responses 文本接口
 
-`POST /v1/responses` 为 Pipeline 助手提供文本调用。服务端保存每轮输入和输出，后续请求通过 `previous_response_id` 恢复上下文。语音、视频和长连接交互继续使用 `/v1/realtime`。
+`POST /v1/responses` 是 **OpenAI-compatible subset v1** 的有状态文本接口。服务端保存每轮输入和输出，后续请求通过 `previous_response_id` 恢复上下文。语音、视频和长连接交互继续使用 `/v1/realtime`。字段和事件边界见 [OpenAI 兼容范围](/openai-compatibility)。
 
 接口使用后台创建的长期 `sk-rt-...` API Key。短期 `ek-rt-...` Client Secret 不能调用文本接口。
 
+## 发现可用助手
+
+```bash
+curl "https://api.example.com/v1/models" \
+  -H "Authorization: Bearer $REALTIME_API_KEY"
+```
+
+返回对象中的 `id` 可直接作为 Responses 或 Realtime 的 `model`。`capabilities` 表明该助手支持 `responses`、`realtime` 或两者。
+
 ## 首轮请求
 
 ```bash
@@ -65,6 +74,54 @@ curl "https://api.example.com/v1/responses/resp_xxx" \
   -H "Authorization: Bearer $REALTIME_API_KEY"
 ```
 
+## 官方 SDK
+
+Python：
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="sk-rt-...",
+    base_url="https://api.example.com/v1",
+)
+
+first = client.responses.create(
+    model="assistant:asst_xxx",
+    input="第一轮",
+)
+second = client.responses.create(
+    previous_response_id=first.id,
+    input="第二轮",
+)
+third = client.responses.create(
+    previous_response_id=second.id,
+    input="第三轮",
+)
+print(third.output_text)
+```
+
+JavaScript：
+
+```js
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: "sk-rt-...",
+  baseURL: "https://api.example.com/v1",
+});
+
+const first = await client.responses.create({
+  model: "assistant:asst_xxx",
+  input: "第一轮",
+});
+const second = await client.responses.create({
+  previous_response_id: first.id,
+  input: "第二轮",
+});
+console.log(second.output_text);
+```
+
 ## SSE 流式输出
 
 设置 `stream: true` 后返回 `text/event-stream`：
@@ -77,7 +134,37 @@ curl "https://api.example.com/v1/responses/resp_xxx" \
 }
 ```
 
-主要事件依次为 `response.created`、`response.in_progress`、`response.output_text.delta`、`response.output_text.done` 和 `response.completed`。连接中断会取消运行，并把 Response 标记为 `cancelled`。
+文本输出的主要事件依次为 `response.created`、`response.in_progress`、`response.output_text.delta`、`response.output_text.done` 和 `response.completed`。Client Tool 参数通过 `response.function_call_arguments.delta` 与 `response.function_call_arguments.done` 返回。连接中断会取消运行，并把 Response 标记为 `cancelled`。
+
+每个 SSE 事件都有连续的 `sequence_number`。Python SDK 可直接迭代：
+
+```python
+stream = client.responses.create(
+    model="assistant:asst_xxx",
+    input="流式介绍",
+    stream=True,
+)
+for event in stream:
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="")
+```
+
+## 幂等重试
+
+创建请求可以携带 `Idempotency-Key`：
+
+```bash
+curl -X POST "https://api.example.com/v1/responses" \
+  -H "Authorization: Bearer $REALTIME_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: order-A123-turn-1" \
+  -d '{"model":"assistant:asst_xxx","input":"查询订单 A123"}'
+```
+
+- 同一 API Key、同一幂等键、相同请求会返回原 Response，并带 `X-Idempotent-Replayed: true`。
+- 相同幂等键对应不同请求时返回 `409 idempotency_key_conflict`。
+- 原请求仍在生成时返回 `409 idempotency_key_in_use`。
+- 幂等键最长 255 个字符；建议调用方使用业务请求 ID 或 UUID。
 
 ## 动态变量
 
@@ -126,10 +213,50 @@ curl "https://api.example.com/v1/responses/resp_xxx" \
 
 如果父链存在多个尚未完成的 Client Tool，本轮必须一次提交全部对应结果。
 
+## 输入项与删除
+
+输入项接口支持稳定游标分页，默认按倒序返回 20 项：
+
+```bash
+curl "https://api.example.com/v1/responses/resp_xxx/input_items?order=asc&limit=20" \
+  -H "Authorization: Bearer $REALTIME_API_KEY"
+```
+
+继续翻页时把上一页 `last_id` 传给 `after`。`limit` 范围为 1 到 100。
+
+删除 Response：
+
+```bash
+curl -X DELETE "https://api.example.com/v1/responses/resp_xxx" \
+  -H "Authorization: Bearer $REALTIME_API_KEY"
+```
+
+删除使用内部 tombstone。该 ID 随后查询或作为新父响应时返回 404；已经存在的子 Response 仍可沿内部祖先链恢复上下文。正在生成的 Response 返回 409，不能通过删除来取消。
+
+subset v1 不支持 background，因此 `POST /v1/responses/{id}/cancel` 明确返回 `400 unsupported_operation`。
+
+## 请求关联与错误
+
+所有 HTTP 响应都返回 `X-Request-ID`。可以在请求中传入自己的安全标识并由服务端透传，便于关联调用方日志；没有提供时服务端生成 `req_...`。
+
+错误统一使用 OpenAI 风格 envelope：
+
+```json
+{
+  "error": {
+    "type": "invalid_request_error",
+    "code": "response_not_found",
+    "message": "Response not found",
+    "param": null
+  }
+}
+```
+
 ## 首版边界
 
 - 仅支持 `runtimeMode=pipeline` 的 Prompt、Workflow、Dify 和 FastGPT 助手。
 - 只支持文本 `message` 和 `function_call_output` 输入。
 - `store` 必须为 `true` 或省略。
 - 不支持 `conversation`、`background`、图片、文件以及调用方覆盖 instructions 或 tools。
+- `usage` 只在 Provider 提供可靠 token 统计时返回；否则为 `null`，不会估算。
 - 不提供 `/v1/chat/completions` 兼容接口。