对话 / 消息 API

向 Lyncore 发送消息并接收 AI 回复。支持 SSE 流式与**非流式（异步轮询）**两种模式。

版本说明：POST /api/v1/chat 两者都提供。/api/v1/chat/approval 与 /api/v1/chat/clarification 为个人版独有（人工审批/澄清回填）。企业版异步结果通过 GET /api/v1/chat/:workflowID 获取。

---

POST /api/v1/chat

发送一条消息。默认流式（SSE）。

请求：

{
  "message": "今天的天气怎么样？",
  "session_id": "conv_xxx（可选，不传则创建新会话）",
  "agent_id": "agent_xxx（可选，指定 Agent 回复）",
  "stream": true,
  "model": "lyncore-chat（可选，覆盖默认模型）",
  "temperature": 0.7,
  "max_tokens": 4096
}

参数	类型	必填	说明
message	string	✅	用户消息文本
session_id	string	-	会话 ID；不传则自动创建新会话
agent_id	string	-	指定由哪个 Agent 回复，不传用默认
stream	bool	-	是否流式，默认 true
model	string	-	覆盖本次使用的模型名
temperature	float	-	采样温度 0.0–2.0
max_tokens	int	-	最大输出 Token

流式响应（SSE）

当 stream=true（默认）或请求头为 Accept: text/event-stream 时，响应为 SSE 流，内容类型 text/event-stream，禁用缓冲（X-Accel-Buffering: no）。

每帧为 data: {json}\n\n，JSON 内 type 字段区分事件；首帧为心跳，终止帧为 data: [DONE]\n\n。

POST /api/v1/chat
Authorization: Bearer <access_token>
Content-Type: application/json

{"message": "1+1等于几？"}

data: {"type":"heartbeat"}

data: {"type":"message","delta":"1+1"}

data: {"type":"message","delta":"等于 2"}

data: {"type":"tool_call","name":"calculator","args":{"expression":"1+1"},"id":"call_xxx"}

data: {"type":"tool_result","id":"call_xxx","result":"2"}

data: {"type":"message","delta":"1+1 等于 2。"}

data: {"type":"done","usage":{"prompt_tokens":50,"completion_tokens":15,"total_tokens":65}}

data: [DONE]

type	说明
heartbeat	心跳保活帧
message	文本增量，含 delta
tool_call	Agent 调用了工具，含 name / args / id
tool_result	工具执行结果，含 id / result
done	消息完成，含 usage
error	错误信息

个人版同时支持 event: <type>\ndata: {json}\n\n 具名事件格式；企业版心跳以 SSE 注释 : heartbeat 形式发送。

非流式 / 异步响应

当 stream=false（或未声明流式）时，企业版返回 202 Accepted 并附 workflow_id，可通过 GET /api/v1/chat/:workflowID 轮询结果；个人版在非流式下直接返回完整 JSON。

{
  "code": 0,
  "data": {
    "id": "msg_xxx",
    "session_id": "conv_xxx",
    "role": "assistant",
    "content": "1 + 1 等于 2",
    "tool_calls": [],
    "usage": { "prompt_tokens": 50, "completion_tokens": 15, "total_tokens": 65 }
  },
  "message": "ok",
  "request_id": "req_abc123"
}

---

POST /api/v1/chat/approval

个人版独有。当对话中的步骤需要人工审批时，用此端点回填审批结果。

请求：

{
  "request_id": "req_xxx",
  "approved": true,
  "comment": "允许执行"
}

---

POST /api/v1/chat/clarification

个人版独有。当 Agent 提出澄清问题，用此端点回填用户答复。

请求：

{
  "request_id": "req_xxx",
  "answer": "使用上海时区"
}

---

GET /api/v1/chat/:workflowID

企业版独有。异步对话任务的结果查询（对应非流式 202 返回的 workflowID）。

---

相关：会话管理

会话（对话线程）的增删改查通过 /api/v1/chat/conversations 系列端点，详见 会话 API。