聊天：启动流式轮次

POST /v1/chat/stream

启动 Agent 轮次并立即返回 session id。轮次在后台运行；LLM 增量、工具调用、工具结果和最终助手消息通过 /v1/stream 的多路复用 WebSocket 推送，使用 chat channel 和返回的 session_id 作为 key。重新连接可从每个会话的序列缓冲区续传。

请求体

{ "message": "analyze BTC momentum", "session_id": "chat_...", "attachments": [ { "key": "file_ab12", "filename": "chart.png", "media_type": "image/png", "size": 48213, "kind": "image" } ], "model": "claude-sonnet-4-5", "reasoning_effort": "high" }

响应体

{ "session_id": "chat_...", "kind": "chat", "is_new": true }

说明

除 message 外，所有字段均为可选字段。使用 resume: true 继续已结束的服务商连接故障轮次，或使用 capability_continuation 在能力配置完成后继续任务时，可省略 message。session_id 用于继续现有会话；省略它会创建新会话（此时 session_kind 选择界面类型，默认为 "chat"）。retry: true 会替换会话的最新轮次，而不是叠加重复轮次。resume: true 必须提供现有 session_id；它会保留已完成的工具结果，从最近的持久化边界继续执行，并且不会新增可见的用户消息行。

消息标识与一次性技能：client_message_id 是由客户端生成的非空字符串（最长 200 个字符），会随用户消息保存。使用 retry: true 时，传入原消息的 client_message_id 作为 retry_target，旧消息也可使用 u-<row id>。只有与目标匹配的最新持久化用户轮次会被撤回；未保存或已被后续消息取代的目标不会删除已有历史。省略 retry_target 时保留旧版替换最新轮次的行为。turn_skill_overrides: { include: string[], exclude: string[] } 只影响本条消息，并以 skill_overrides 保存到消息元数据，不改变会话默认设置。重试时应重新发送原消息的技能设置；后续普通消息不会继承这些技能。

capability_continuation: { "tool_call_id": "..." } 需要现有 session_id，以及最新已结束轮次的工具结果中可恢复的能力配置要求。能力必须已安装，且具备本次请求所需的服务权限。续接保留聊天历史和工具结果，不新增可见的用户消息行。重复或已被新任务取代的回调、未完成的配置均返回 409。不要与 retry: true 或 resume: true 同时使用。 续接同时保留原始 Plan/Deep 模式；被中断的任务也返回 409。也不能与 parent_session_id 或 Plan 审批续接同时使用。connector_continuation 是兼容旧客户端的别名，执行相同的能力检查；只能传入一个续接字段。

附件：先通过 POST /v1/files（multipart）上传文件取得 key，再在此引用。每项格式为 { key, filename, media_type, size, kind }。kind 支持 "image" | "pdf" | "spreadsheet" | "text" | "office"，不接受通用 "file" 类型。每轮最多 8 个附件；图片最大 5 MiB，其他文件最大 20 MiB。语音通过 voice_input_key 引用原始录音的 FileStore key（使用 POST /v1/voice/transcribe?persist 上传），方便历史回放；转录文本仍放在 message 中。

单轮模型覆盖：model 仅为本轮选择模型，不修改部署默认值（PUT /v1/llm/default-model），也不影响并发客户端。模型必须由当前连接的服务商提供，参见 GET /v1/llm/available-models。需要切换连接的模型返回 400。reasoning_effort 覆盖本轮推理档位，必须是有效模型支持的档位；无效值会在轮次启动前返回 400。

轮次中途引导事件：通过 POST /v1/chat/interject 排队的消息注入正在运行的轮次时，会发出 user_interjection 事件（{ "message": "...", "ts_ms": 1747000000000 }）。最终 done 事件数据有两个可选字段：轮次由 POST /v1/chat/interrupt 停止时为 interrupted: true；pending_interjections: string[] 列出到达过晚而未能注入的消息，客户端应将其作为普通消息重新发送。无头调用方可选择提示词变体：可选请求体字段 surface（"web" | "cli"，默认 "web"）和 prompt_mode（"full" | "minimal"，默认 "full"）会调整系统提示词。cli 会省略自定义 URI 线协议；minimal 会挂载精简骨架（身份、技能/工具机制和基础 Markdown），并从注入上下文中移除个性化信息，同时保留技能目录、日期和工作目录。

WebSocket 的 channel、订阅、序列号、回放和控制帧详见多路复用 WebSocket。