HTTP 与 SSE 契约参考

HTTP、SSE 与错误契约

下表使用默认 /ai。修改 base-path 后，除 /ai-admin 外都替换前缀。

端点总表

方法和路径	成功状态	说明
`GET /ai/tools`	200	当前用户可发现 Tool
`POST /ai/tools/call`	200	每次重新授权；业务 isError 仍可为 200
`POST /ai/model/stream`	200 SSE	结构化模型流
`GET /ai/conversations`	200	当前 owner 会话列表
`POST /ai/conversations`	200	无 body 合法；不是 201
`GET /ai/conversations/{id}`	200	会话元数据与完整 Context
`PUT /ai/conversations/{id}`	200	revision + 完整 Context 原子替换
`DELETE /ai/conversations/{id}`	204	幂等删除；不存在也返回 204
`GET /ai/admin/stats`	200	Admin + AuditQueryRepository
`GET /ai/admin/traces`	200	page 默认 0，pageSize 默认 20、范围 1..100
`GET /ai/admin/traces/{traceId}`	200	Trace 详情
`GET /ai/admin/mcp/servers`	200	Admin 和 MCP 同时开启
`GET /ai/admin/mcp/servers/{name}/tools`	200	当前 Server Tool 快照
`POST /ai/admin/mcp/servers`	201	JDBC 模式创建
`PUT /ai/admin/mcp/servers/{name}`	200	revision 乐观锁更新
`POST /ai/admin/mcp/servers/{name}/enabled`	200	enabled + revision
`DELETE /ai/admin/mcp/servers/{name}?revision=n`	204	revision 必填
`POST /ai/admin/mcp/servers/{name}/refresh`	200	刷新真实 Tool 列表
`POST /ai/admin/mcp/servers/{name}/test`	200	连通失败也返回 200、body ok=false
`GET /ai-admin` 或尾斜杠	302	固定路径，跳转 index
`GET /ai-admin/config`	200	返回实际 basePath

Admin Trace 日期格式为 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss，解析严格且 from 不得晚于 to。

Tool call 请求

{
  "name": "local.device_get",
  "arguments": {"serial": "device-placeholder"},
  "requestId": "request-placeholder",
  "traceId": "trace-placeholder",
  "toolCallId": "tool-call-placeholder",
  "conversationId": "conversation-placeholder"
}

name 和 arguments 必填；即使无参数也必须显式发送 {}。其他字段只用于关联，不是可信身份字段。未知顶层字段拒绝。

Conversation 请求

创建请求只允许可选 title，最大 256 字符。保存请求必须包含：

{
  "title": "可选标题",
  "revision": 0,
  "context": {
    "messages": [],
    "modelState": null
  }
}

revision 必须为非负整数。冲突返回 409 CONVERSATION_CONFLICT，错误对象包含 currentRevision；客户端应重新加载并由用户决定，不能静默覆盖。

Model stream 请求

request 必须显式包含 responseMessageId、非空 messages、tools 和 modelState。tools 可以是空数组，modelState 可以是显式 null，但两个字段都不能缺失。maxTokens 如提供必须大于 0。

SSE 事件

响应为 text/event-stream; charset=UTF-8，设置 Cache-Control: no-cache 和 X-Accel-Buffering: no。每帧只使用 SSE data JSON，不设置命名 event。

type	主要字段	语义
`block-start`	index, block	开始 text/reasoning/tool-call 等 Block
`block-delta`	index, delta	text/reasoning 文本或 Tool argumentsDelta
`block-stop`	index	当前 Block 完整结束
`message-stop`	stopReason, usage, modelState	唯一完整消息结束边界
`error`	error.code/message/retryable	流建立后的模型失败

message-stop 到达前，所有已开始 Block 必须先 stop；到达后不允许再有模型事件。流结束但没有 message-stop、存在未关闭 Block、非法 Tool 参数或后续多余事件都属于 MODEL_PROTOCOL_ERROR。只有完整流成功组装后，Runtime 才发布模型调用完成事实；取消、网络失败、协议失败或未完成的消息一律不报告为完成。

stopReason 为 end-turn、tool-use、max-tokens、stop-sequence 或 other，并必须与稳定 Tool Call 数严格一致：

stopReason	Tool Call 数	Browser Runtime 处理
`tool-use`	至少 1	整批预检后按模型顺序串行执行
`tool-use`	0	`MODEL_PROTOCOL_ERROR`
`max-tokens`	0	保留并保存已封闭消息和 ModelState，返回 `max-tokens` Outcome，Widget 提示内容可能不完整
`max-tokens`	至少 1	`MODEL_PROTOCOL_ERROR`，不执行可能被截断的 Tool Call
`end-turn` / `stop-sequence` / `other`	0	返回 `completed` Outcome
`end-turn` / `stop-sequence` / `other`	至少 1	`MODEL_PROTOCOL_ERROR`

Browser 不解析任何厂商 choices、tool_calls、reasoning_content 或结束标记。一条 Assistant 消息的所有 Tool Call 在任何 Tool 开始前整批检查 Call ID 唯一性、快照成员、JSON 对象参数与次数预算；任一预检失败时当前批次零 Tool 执行。

FilesExpand file tree

http-api.md

Latest commit

History