Skip to main content

Chat API

intermediate 🤖 LLM 友好 1 分钟 · 109 字 更新于： 2026-06-27 中文

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

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Chat API

Chat API 支持人类与 LLM Agent 之间的异步消息通信。与同步聊天（ChatGPT 风格）不同，人类可以在 Agent 工作期间留言 — Agent 在工具调用之间轮询消息。

工作原理

Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)
                                     │
                                     └── 轮询时将消息标记为已读
  1. 人类通过 Web UI 发送消息（使用 JWT）
  2. 消息被存储，并标记为未读
  3. Agent 在工具调用之间轮询 GET /chat/poll
  4. 轮询返回所有未读消息并将其标记为已读
  5. Agent 处理消息，可选择通过 POST /chat/reply 回复

端点

GET /chat/poll

轮询来自人类的新消息。返回未读消息并将其标记为已读。请在工具调用之间使用此接口。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/poll

响应：

{
  "messages": [
    {
      "id": "msg_001",
      "role": "human",
      "content": "How's the deployment going?",
      "created_at": "2026-06-27T..."
    }
  ]
}

POST /chat/reply

以 Agent 身份发送消息。

curl -X POST https://synapse.schaefer.zone/chat/reply \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

以人类身份发送消息（需要 JWT，而非 Mind Key）。

curl -X POST https://synapse.schaefer.zone/chat/send \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"content": "Can you check the logs?"}'

GET /chat/history

获取最近的聊天历史（双方角色）。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=50"

GET /chat/unread

获取未读消息数量。

# 统计来自人类的未读消息（供 Agent 使用）
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# 统计来自 Agent 的未读消息（供人类使用）
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

获取聊天会话状态（最近消息时间戳、未读数量）。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/status

POST /chat/upload

为特定消息上传文件附件（multipart 表单）。

curl -X POST https://synapse.schaefer.zone/chat/upload \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "message_id=msg_001" \
  -F "file=@screenshot.png"

GET /chat/files/:message_id

列出某条消息的文件附件。

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/files/msg_001

GET /chat/file/:file_id

下载文件附件。

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/file/file_001 --output download.png

轮询模式

在工具调用之间每 30-60 秒轮询一次。不要更频繁地轮询 — 既浪费 API 配额，也带不来任何收益。
# 伪代码
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()

下一步

← 返回 API 参考