S-QC-Bot API 文档

S-QC-Bot 提供 REST API，允许外部系统（Web、App、CLI、其他 Bot 框架）通过 HTTP 调用完成完整的 AI 对话流程。

连接信息

鉴权

所有 API 请求必须在 HTTP 头中携带 API Key：

Authorization: Bearer APIKEY

或

X-API-Key: APIKEY

未携带 Key 返回 401，Key 错误返回 403。如未在 configs/bot_config.toml 的 [api] 段配置 api_keys，鉴权自动禁用。

端点一览

1. AI 对话

POST/api/v1/chat

发送消息并获取 AI 回复。经过完整管道：图片识别（如有）→ 情绪分析 → 记忆检索 → 知识库/搜索 → LLM 生成。

请求体

{
  "message": "你好呀",
  "user_id": "alice",
  "user_name": "小明",
  "image_url": null,
  "with_history": true,
  "knowledge_base": false,
  "session_id": null,
  "context": {
    "is_group": false,
    "perception": {}
  }
}

图片识别说明

当传入 image_url 时：

API 先调用 Qwen VL 视觉模型识别图片内容
将识别结果以 [图片识别结果] 标签拼入用户消息
再走完整的对话管道（情绪 → 记忆 → LLM → 回复）

image_url 必须是可公网访问的 URL（不支持本地路径或 Base64）。图片识别失败时会降级处理，不会阻塞对话。图片识别会增加约 1-3 秒延迟。

关于知识库

knowledge_base 参数控制是否启用知识库：

true — 自动读取该 API Key 所属账号下的所有知识库数据，注入到对话上下文中
false 或不传 — 不加载知识库

知识库数据来自用户在控制台导入或从对话中自动提炼的知识洞察。

响应体

{
  "success": true,
  "data": {
    "responses": [
      "你好呀～有什么可以帮你的吗？"
    ],
    "user_id": "alice",
    "session_id": null,
    "image_recognized": false,
    "timestamp": "2026-05-27T12:00:00.123456"
  },
  "error": null
}

关于记忆

user_id 是记忆的核心标识，AI 根据它检索该用户的对话历史、记忆、画像
不同 user_id = 不同的记忆空间
如果想和 QQ 端共享记忆，将 user_id 设为 QQ 号即可
with_history: false 时使用隔离的匿名 ID，不读取也不污染用户真实历史

调用示例

curl -X POST http://127.0.0.1:8080/api/v1/chat \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","user_id":"alice"}'

带图片识别

curl -X POST http://127.0.0.1:8080/api/v1/chat \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"这张图片里有什么？","user_id":"alice","image_url":"https://example.com/photo.jpg"}'

启用知识库

curl -X POST http://127.0.0.1:8080/api/v1/chat \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","user_id":"user001","knowledge_base":true}'

2. 查询对话历史

GET/api/v1/chat/history/{user_id}?limit=20

参数

响应体

{
  "success": true,
  "data": {
    "user_id": "alice",
    "conversations": [
      {
        "sender": "用户",
        "message": "你好",
        "timestamp": 1779887730.530
      },
      {
        "sender": "助手",
        "message": "你好呀～",
        "timestamp": 1779887730.530
      }
    ],
    "count": 2
  }
}

调用示例

curl -H "Authorization: Bearer APIKEY" \
  "http://127.0.0.1:8080/api/v1/chat/history/alice?limit=10"

3. 清除对话历史

DELETE/api/v1/chat/history/{user_id}

响应体

{
  "success": true,
  "data": {
    "user_id": "alice",
    "message": "对话历史已清除"
  }
}

调用示例

curl -X DELETE -H "Authorization: Bearer APIKEY" \
  "http://127.0.0.1:8080/api/v1/chat/history/alice"

4. 智能记忆检索

GET/api/v1/memory/{user_id}?query=关键词

根据关键词检索该用户的历史记忆。

参数

响应体

{
  "success": true,
  "data": {
    "user_id": "alice",
    "query": "猫",
    "results": ["用户的猫叫橘子，今年3岁了"]
  }
}

调用示例

curl -H "Authorization: Bearer APIKEY" \
  "http://127.0.0.1:8080/api/v1/memory/alice?query=猫"

5. 获取用户画像

GET/api/v1/person/{user_id}

响应体

{
  "success": true,
  "data": {
    "user_id": "alice",
    "exists": true,
    "nickname": "小明",
    "interaction_count": 42,
    "last_interaction": "2026-05-27 12:00:00",
    "message_count": 128,
    "traits": {}
  }
}

调用示例

curl -H "Authorization: Bearer APIKEY" \
  "http://127.0.0.1:8080/api/v1/person/alice"

6. 创建/更新用户画像

PUT/api/v1/person/{user_id}?nickname=小明

参数

响应体

{
  "success": true,
  "data": {
    "user_id": "alice",
    "nickname": "小明",
    "created": true
  }
}

调用示例

curl -X PUT -H "Authorization: Bearer APIKEY" \
  "http://127.0.0.1:8080/api/v1/person/alice?nickname=小明"

7. 决策引擎（调试）

POST/api/v1/decision

调用 v2 决策引擎获取原始决策结果。只返回决策（是否回复、理由、置信度），不生成实际回复。

请求体

{
  "message": "你好",
  "user_id": "alice",
  "user_name": "小明",
  "chat_id": "alice",
  "is_group": false
}

响应体

{
  "success": true,
  "data": {
    "action": "reply",
    "reason": "用户直接提问，需要回复",
    "method": "force",
    "params": {},
    "mood_delta": 0.0,
    "thought": "",
    "confidence": 1.0
  }
}

调用示例

curl -X POST http://127.0.0.1:8080/api/v1/decision \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","user_id":"alice"}'

8. 健康检查

GET/health

无需鉴权。

响应体

{
  "status": "ok",
  "ts_connected": false,
  "monitor_running": false,
  "timestamp": "2026-05-27 12:00:00",
  "loaded_routes": ["auth", "chat_api", "memory", ...]
}

错误处理

所有端点在失败时返回统一格式：

{
  "success": false,
  "data": null,
  "error": "错误描述信息"
}

HTTP 状态码：

配置

API 配置位于 configs/bot_config.toml：

[api]
enabled = true
api_keys = ["APIKEY"]  # 空=不鉴权

API Key 存储在 configs/.env：

API_ACCESS_KEY=APIKEY