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>
2026-05-24 12:39:55 +08:00
parent 9c29459fb6
commit 70f8b30d04
7 changed files with 2343 additions and 2 deletions
@@ -0,0 +1,298 @@
+# Memory-Service API
+
+**Base URL:** `http://<host>:8094` | **Auth:** 无（按 `user_id` 隔离数据）
+
+记忆服务负责长期记忆的存储、检索、合并、衰减以及后台思考日志记录。
+
+---
+
+## 目录
+
+1. [数据模型](#数据模型)
+2. [POST /api/v1/memories — 创建记忆](#1-post-apiv1memories)
+3. [GET /api/v1/memories — 记忆列表](#2-get-apiv1memories)
+4. [GET /api/v1/memories/:id — 获取记忆](#3-get-apiv1memoriesid)
+5. [PUT /api/v1/memories/:id — 更新记忆](#4-put-apiv1memoriesid)
+6. [DELETE /api/v1/memories/:id — 删除记忆](#5-delete-apiv1memoriesid)
+7. [POST /api/v1/memories/query — 搜索记忆](#6-post-apiv1memoriesquery)
+8. [POST /api/v1/memories/consolidate — 合并记忆](#7-post-apiv1memoriesconsolidate)
+9. [POST /api/v1/memories/decay — 记忆衰减](#8-post-apiv1memoriesdecay)
+10. [GET /api/v1/memories/categories — 分类统计](#9-get-apiv1memoriescategories)
+11. [POST /api/v1/thinking — 记录思考](#10-post-apiv1thinking)
+12. [GET /api/v1/thinking — 思考列表](#11-get-apiv1thinking)
+13. [GET /api/v1/thinking/:id — 思考详情](#12-get-apiv1thinkingid)
+14. [GET /api/v1/thinking/stats — 思考统计](#13-get-apiv1thinkingstats)
+15. [GET /api/v1/health — 健康检查](#14-get-apiv1health)
+
+---
+
+## 数据模型
+
+### MemoryEntry
+
+| JSON 字段 | Go 类型 | 说明 |
+|-----------|---------|------|
+| `id` | string | UUID 主键 |
+| `user_id` | string | 所属用户 (max 64 chars) |
+| `content` | string | 完整记忆文本 |
+| `summary` | string | 简短摘要 |
+| `category` | string | 7 种: `user_preference`, `personal_info`, `conversation`, `knowledge`, `event`, `task`, `relationship` |
+| `priority` | int | 0=Temp, 1=Normal, 2=Important, 3=Core (写入时 clamp [0,10]) |
+| `importance` | int | 1-10 (默认 5) |
+| `keywords` | []string | 关键词标签 |
+| `session_id` | string | 来源会话 ID |
+| `source` | string | `conversation`, `manual`, `merged`, `consolidated` |
+| `access_count` | int | 访问次数 |
+| `last_access` | string | 最近访问时间 (RFC3339) |
+| `created_at` | string | 创建时间 |
+| `updated_at` | string | 更新时间 |
+| `expires_at` | string/null | 临时记忆过期时间 (omitempty) |
+
+### ThinkingLog
+
+| JSON 字段 | Go 类型 | 说明 |
+|-----------|---------|------|
+| `id` | string | UUID |
+| `user_id` | string | 所属用户 |
+| `content` | string | 思考日志全文 |
+| `tool_calls` | string | JSON 数组 (字符串存储) |
+| `tool_call_count` | int | 工具调用次数 |
+| `content_length` | int | 内容字符长度 |
+| `created_at` | string | 创建时间 (RFC3339) |
+
+### ThinkingStats
+
+| JSON 字段 | Go 类型 | 说明 |
+|-----------|---------|------|
+| `total_logs` | int | 思考日志总数 |
+| `total_tool_calls` | int | 工具调用总次数 |
+| `avg_content_length` | float64 | 平均内容长度 |
+| `latest_at` | string | 最近日志时间 |
+
+---
+
+## 1. POST /api/v1/memories — 创建记忆
+
+创建时自动去重：与已有记忆的 Jaccard/双字母组相似度 >= 0.75 时，合并内容到已有条目而非新建。
+
+```json
+// 请求
+{
+  "user_id": "string (必填)",
+  "content": "string (必填)",
+  "summary": "string",
+  "category": "string (默认 knowledge, 七选一)",
+  "priority": 1,
+  "importance": 5,
+  "keywords": ["tag1", "tag2"],
+  "session_id": "string",
+  "source": "string (默认 manual)"
+}
+
+// 响应 201
+{ "status": "saved", "memory": MemoryEntry }
+```
+
+### 错误
+
+| 状态码 | 错误 |
+|--------|------|
+| 400 | `缺少 user_id 或 content` |
+| 400 | `请求格式错误: ...` |
+| 405 | `method not allowed` |
+| 500 | 数据库错误 |
+
+---
+
+## 2. GET /api/v1/memories — 记忆列表
+
+### Query 参数
+
+| 参数 | 必填 | 默认 | 说明 |
+|------|------|------|------|
+| `user_id` | 是 | — | 用户 ID |
+| `category` | 否 | 全部 | 分类过滤 |
+| `min_importance` | 否 | 0 | 最低重要度 |
+| `limit` | 否 | 50 | 最大条数 |
+
+### 响应 200
+
+```json
+{ "user_id": "string", "memories": [ MemoryEntry, ... ], "total": 10 }
+```
+
+---
+
+## 3. GET /api/v1/memories/:id — 获取记忆
+
+访问后异步递增 `access_count`。
+
+```json
+// 响应 200
+{ "memory": MemoryEntry }
+
+// 错误 404
+{ "error": "记忆不存在" }
+```
+
+---
+
+## 4. PUT /api/v1/memories/:id — 更新记忆
+
+Body 所有字段可选 (partial update)。`user_id` 和 `session_id` 不可修改。
+
+```json
+// 请求
+{
+  "content": "新内容",
+  "summary": "新摘要",
+  "category": "knowledge",
+  "priority": 2,
+  "importance": 8,
+  "keywords": ["新标签"],
+  "source": "manual"
+}
+
+// 响应 200
+{ "status": "updated", "memory_id": "uuid" }
+```
+
+---
+
+## 5. DELETE /api/v1/memories/:id — 删除记忆
+
+不检查存在性，始终返回成功。
+
+```json
+{ "status": "deleted", "memory_id": "uuid" }
+```
+
+---
+
+## 6. POST /api/v1/memories/query — 搜索记忆
+
+内部使用 SQL ILIKE + 应用层子串匹配在 content/summary/keywords 中搜索，按 importance 降序排序并去重。
+
+```json
+// 请求
+{
+  "user_id": "string (必填)",
+  "query_text": "关键词",
+  "category": "knowledge",
+  "min_importance": 3,
+  "limit": 10
+}
+
+// 响应 200
+{ "user_id": "string", "query": "关键词", "memories": [ MemoryEntry ], "total": 3 }
+```
+
+---
+
+## 7. POST /api/v1/memories/consolidate — 合并记忆
+
+查找 Jaccard 相似度 >= 0.75 的记忆对，合并关键词、增加 importance、删除重复条目。
+
+```json
+// 请求
+{ "user_id": "string (必填)" }
+
+// 响应 200
+{ "status": "consolidated", "user_id": "string", "merged": 3, "message": "记忆整理完成" }
+```
+
+---
+
+## 8. POST /api/v1/memories/decay — 记忆衰减
+
+两阶段操作：
+1. **降级:** access_count < 3、最近 30 天未访问、importance < 3、priority > 0、非 personal_info/user_preference → priority -1
+2. **删除:** priority = 0、access_count = 0、最近 14 天未访问
+
+```json
+// 请求
+{ "user_id": "string (必填)" }
+
+// 响应 200
+{ "status": "decayed", "user_id": "string", "decayed": 5, "deleted": 2, "message": "记忆衰减完成" }
+```
+
+---
+
+## 9. GET /api/v1/memories/categories — 分类统计
+
+`?user_id=xxx`
+
+```json
+// 响应 200
+{
+  "user_id": "string",
+  "categories": {
+    "knowledge": 12,
+    "user_preference": 3,
+    "conversation": 8
+  }
+}
+```
+
+---
+
+## 10. POST /api/v1/thinking — 记录思考
+
+```json
+// 请求
+{
+  "user_id": "string (默认 admin)",
+  "content": "string (必填)",
+  "tool_calls": "string (默认 [])",
+  "tool_call_count": 0,
+  "content_length": 0
+}
+
+// 响应 201
+{ "status": "saved", "thinking": ThinkingLog }
+```
+
+---
+
+## 11. GET /api/v1/thinking — 思考列表
+
+`?user_id=xxx&limit=20&offset=0`
+
+```json
+// 响应 200
+{ "logs": [ ThinkingLog ], "total": 5 }
+```
+
+---
+
+## 12. GET /api/v1/thinking/:id — 思考详情
+
+```json
+// 响应 200
+{ "thinking": ThinkingLog }
+
+// 错误 404
+{ "error": "思考日志不存在" }
+```
+
+---
+
+## 13. GET /api/v1/thinking/stats — 思考统计
+
+`?user_id=xxx` (可选，缺省返回全部用户)
+
+```json
+// 响应 200
+{ "total_logs": 100, "total_tool_calls": 250, "avg_content_length": 512.3, "latest_at": "2024-01-01T12:00:00Z" }
+```
+
+---
+
+## 14. GET /api/v1/health — 健康检查
+
+```json
+{ "status": "ok", "service": "memory-service" }
+// 或数据库不可用时
+{ "status": "degraded", "service": "memory-service" }
+```