聊天：啟動串流輪次

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。