# Chat API
SUMMARY: 人类与 LLM Agent 之间的异步聊天 — 轮询、回复、历史记录、未读数量、文件上传。

KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions

Chat API
Chat API 支持人类与 LLM Agent 之间的异步消息通信。与同步聊天（ChatGPT 风格）不同，人类可以在 Agent 工作期间留言 — Agent 在工具调用之间轮询消息。
工作原理
[CODE BLOCK]
1. 人类通过 Web UI 发送消息（使用 JWT）
2. 消息被存储，并标记为未读
3. Agent 在工具调用之间轮询 
4. 轮询返回所有未读消息并将其标记为已读
5. Agent 处理消息，可选择通过  回复
端点
GET /chat/poll
轮询来自人类的新消息。返回未读消息并将其标记为已读。请在工具调用之间使用此接口。
[CODE BLOCK]
响应：
[CODE BLOCK]
POST /chat/reply
以 Agent 身份发送消息。
[CODE BLOCK]
POST /chat/send
以人类身份发送消息（需要 JWT，而非 Mind Key）。
[CODE BLOCK]
GET /chat/history
获取最近的聊天历史（双方角色）。
[CODE BLOCK]
GET /chat/unread
获取未读消息数量。
[CODE BLOCK]
GET /chat/status
获取聊天会话状态（最近消息时间戳、未读数量）。
[CODE BLOCK]
POST /chat/upload
为特定消息上传文件附件（multipart 表单）。
[CODE BLOCK]
GET /chat/files/:messageid
列出某条消息的文件附件。
[CODE BLOCK]
GET /chat/file/:fileid
下载文件附件。
[CODE BLOCK]
轮询模式
> [!TIP]
> 在工具调用之间每 30-60 秒轮询一次。不要更频繁地轮询 — 既浪费 API 配额，也带不来任何收益。
[CODE BLOCK]
下一步
- Tasks API
- Chat 轮询模式