docs: 添加完整 API 文档 — Gateway 统一文档 + 后端服务文档
新增 docs/api/gateway-api.md：面向客户端开发的网关 API 统一文档，覆盖全部 16 个模块。 新增 docs/api/backend-services/：后端服务详细文档 (ai-core, memory-service, voice-service, iot-debug, tool-engine)。 更新 .gitignore：docs/api/ 例外允许推送，其他 docs/ 内容仍忽略。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,260 @@
|
||||
# AI-Core Service API
|
||||
|
||||
**Base URL:** `http://<host>:8091` | **Auth:** 无（/internal 路由除外）
|
||||
|
||||
AI-Core 是 LLM 编排引擎，负责对话处理、意图分析、子会话调度、结果合成。所有对话和记忆端点通过 **Server-Sent Events (SSE)** 或 **JSON** 返回。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [POST /api/v1/chat — 对话](#1-post-apiv1chat)
|
||||
2. [GET /api/v1/memory/search — 记忆搜索](#2-get-apiv1memorysearch)
|
||||
3. [GET /api/v1/memory — 记忆列表](#3-get-apiv1memory)
|
||||
4. [POST /api/v1/memory — 添加记忆](#4-post-apiv1memory)
|
||||
5. [DELETE /api/v1/memory — 删除记忆](#5-delete-apiv1memory)
|
||||
6. [POST /api/v1/internal/presence — 在线状态](#6-post-apiv1internalpresence)
|
||||
7. [GET /api/v1/health — 健康检查](#7-get-apiv1health)
|
||||
8. [Model Selector 路由说明](#8-model-selector-路由说明)
|
||||
|
||||
---
|
||||
|
||||
## 1. POST /api/v1/chat
|
||||
|
||||
**类型:** SSE 流式 | **Content-Type:** `application/json` → `text/event-stream`
|
||||
|
||||
### 请求体 (JSON)
|
||||
|
||||
| JSON 字段 | Go 类型 | 必填 | 说明 |
|
||||
|-----------|---------|------|------|
|
||||
| `user_id` | string | 是 | 用户 ID |
|
||||
| `session_id` | string | 是 | 会话 ID |
|
||||
| `message` | string | 是 | 用户消息文本 |
|
||||
| `images` | []string | 否 | base64 Data URL 数组 |
|
||||
| `mode` | string | 否 | 默认 `"text"` |
|
||||
| `nickname` | string | 否 | 用户昵称 |
|
||||
|
||||
### SSE 事件
|
||||
|
||||
**delta** — 逐 token 发送
|
||||
```json
|
||||
{ "delta": "token 文本", "message_id": "msg-1717000000000000000" }
|
||||
```
|
||||
|
||||
**segments** — 断句事件（生成完成后）
|
||||
```json
|
||||
{
|
||||
"message_id": "string",
|
||||
"mode": "string",
|
||||
"segments": [
|
||||
{ "index": 0, "text": "第一句话" },
|
||||
{ "index": 1, "text": "第二句话" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**review** — 审查后结构化消息（action/chat 分离）
|
||||
```json
|
||||
{
|
||||
"message_id": "string",
|
||||
"review_messages": [
|
||||
{ "type": "action", "content": "打开灯光", "delay_ms": 0 },
|
||||
{ "type": "chat", "content": "好的，已为你打开客厅的灯光。", "delay_ms": 200 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**done** — 流结束
|
||||
```json
|
||||
{ "message_id": "string", "mode": "string", "done": true }
|
||||
```
|
||||
|
||||
**error** — 错误
|
||||
```json
|
||||
{ "delta": "", "error": "错误描述" }
|
||||
```
|
||||
|
||||
终端标记: `data: [DONE]\n\n`
|
||||
|
||||
### HTTP 状态码
|
||||
|
||||
| 状态码 | 含义 |
|
||||
|--------|------|
|
||||
| 200 | 流开始 |
|
||||
| 400 | JSON 解析失败 |
|
||||
| 405 | 非 POST 请求 |
|
||||
| 500 | 服务端不支持流式 |
|
||||
|
||||
---
|
||||
|
||||
## 2. GET /api/v1/memory/search
|
||||
|
||||
### Query 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `user_id` | 是 | 用户 ID |
|
||||
| `q` | 是 | 搜索关键词 |
|
||||
|
||||
### 响应 200
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"query": "搜索词",
|
||||
"memories": [ MemoryEntry, ... ],
|
||||
"total": 5
|
||||
}
|
||||
```
|
||||
|
||||
### 错误 (200 + error 字段)
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"query": "string",
|
||||
"memories": [],
|
||||
"error": "错误描述",
|
||||
"errorType": "memory_store_unavailable|retrieve_failed",
|
||||
"hint": "解决方案 (仅 memory_store_unavailable)"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. GET /api/v1/memory — 记忆列表
|
||||
|
||||
`?user_id=xxx` 最大返回 50 条。
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"memories": [ MemoryEntry, ... ],
|
||||
"total": 3
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. POST /api/v1/memory — 添加记忆
|
||||
|
||||
```json
|
||||
// 请求
|
||||
{
|
||||
"user_id": "string (必填)",
|
||||
"content": "string (必填)",
|
||||
"category": "string (默认 other)",
|
||||
"priority": 1
|
||||
}
|
||||
|
||||
// 响应 201
|
||||
{
|
||||
"status": "saved",
|
||||
"memory": MemoryEntry
|
||||
}
|
||||
```
|
||||
|
||||
### 错误
|
||||
|
||||
| 状态码 | errorType | 说明 |
|
||||
|--------|-----------|------|
|
||||
| 400 | — | 缺少 user_id 或 content |
|
||||
| 500 | `save_failed` | 保存失败 |
|
||||
| 503 | `memory_store_unavailable` | 存储未初始化 |
|
||||
|
||||
---
|
||||
|
||||
## 5. DELETE /api/v1/memory — 删除记忆
|
||||
|
||||
`?id=<memory_id>`
|
||||
|
||||
```json
|
||||
// 响应 200
|
||||
{ "status": "deleted", "memory_id": "string" }
|
||||
```
|
||||
|
||||
### 错误
|
||||
|
||||
| 状态码 | errorType |
|
||||
|--------|-----------|
|
||||
| 400 | 缺少 id 参数 |
|
||||
| 500 | `delete_failed` |
|
||||
| 503 | `memory_store_unavailable` |
|
||||
|
||||
---
|
||||
|
||||
## 6. POST /api/v1/internal/presence
|
||||
|
||||
**Auth:** `X-Internal-Token` header。Gateway 内部调用的用户上线/下线通知。
|
||||
|
||||
```json
|
||||
// 请求
|
||||
{
|
||||
"user_id": "string (必填)",
|
||||
"status": "online|offline (必填)",
|
||||
"session_id": "string (必填)"
|
||||
}
|
||||
|
||||
// 响应 200
|
||||
{ "status": "ok" }
|
||||
```
|
||||
|
||||
| 状态码 | 含义 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | JSON 无效 |
|
||||
| 401 | Token 无效 |
|
||||
|
||||
---
|
||||
|
||||
## 7. GET /api/v1/health
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"service": "ai-core",
|
||||
"model": "gpt-4o"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Model Selector 路由说明
|
||||
|
||||
AI-Core 使用基于用途的模型路由。模型配置从 `models.json` 加载，回退到 `.env` 环境变量。
|
||||
|
||||
### Purpose 常量
|
||||
|
||||
| Purpose | 常量 | 用途 |
|
||||
|---------|------|------|
|
||||
| `chat` | `PurposeChat` | 通用对话 |
|
||||
| `deep_thinking` | `PurposeDeepThinking` | 后台深度思考 |
|
||||
| `intent_analysis` | `PurposeIntentAnalysis` | 意图分析 |
|
||||
| `tool_calling` | `PurposeToolCalling` | 工具调用 |
|
||||
| `memory_extraction` | `PurposeMemoryExtraction` | 记忆提取 |
|
||||
|
||||
### 路由策略
|
||||
|
||||
1. `models.json` 存在 → 按 `routing.<purpose>.fallback_chain` 顺序尝试
|
||||
2. `models.json` 不存在 → 回退到 `.env` 的 `LLM_API_URL`/`LLM_API_KEY`/`LLM_MODEL`
|
||||
3. 全部失败 → 返回 `DefaultAdapter()` 使用 fallback model
|
||||
|
||||
### MemoryEntry 结构
|
||||
|
||||
| JSON 字段 | Go 类型 | 说明 |
|
||||
|-----------|---------|------|
|
||||
| `id` | string | UUID |
|
||||
| `user_id` | string | 所属用户 |
|
||||
| `content` | string | 完整内容 |
|
||||
| `summary` | string | 摘要 |
|
||||
| `category` | string | `user_preference`, `personal_info`, `conversation`, `knowledge`, `event`, `task`, `relationship` |
|
||||
| `priority` | int | 0=Temp, 1=Normal, 2=Important, 3=Core |
|
||||
| `importance` | int | 1-10 |
|
||||
| `keywords` | []string | 关键词标签 |
|
||||
| `session_id` | string | 来源会话 |
|
||||
| `source` | string | `conversation`, `thinking`, `manual` |
|
||||
| `access_count` | int | 访问次数 |
|
||||
| `last_access` | time | 最近访问 |
|
||||
| `created_at` | time | 创建时间 |
|
||||
| `updated_at` | time | 更新时间 |
|
||||
| `expires_at` | *time | 临时记忆过期（可空） |
|
||||
Reference in New Issue
Block a user