mirror of
https://github.com/hellodigua/ChatLab.git
synced 2026-04-25 04:52:43 +08:00
500 lines
13 KiB
Markdown
500 lines
13 KiB
Markdown
# ChatLab API 文档
|
||
|
||
ChatLab 提供本地 RESTful API 服务，允许外部工具、脚本和 MCP 等通过 HTTP 接口查询聊天记录、执行 SQL 查询、导入聊天数据。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 启用服务
|
||
|
||
打开 ChatLab → 设置 → ChatLab API → 开启服务。
|
||
|
||
启用后会自动生成 API Token，默认监听端口 `5200`。
|
||
|
||
### 2. 验证服务状态
|
||
|
||
```bash
|
||
curl http://127.0.0.1:5200/api/v1/status \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"name": "ChatLab API",
|
||
"version": "1.0.0",
|
||
"uptime": 3600,
|
||
"sessionCount": 5
|
||
},
|
||
"meta": {
|
||
"timestamp": 1711468800,
|
||
"version": "0.0.2"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 基本信息
|
||
|
||
| 项目 | 说明 |
|
||
| -------- | ------------------------- |
|
||
| 基础 URL | `http://127.0.0.1:5200` |
|
||
| API 前缀 | `/api/v1` |
|
||
| 认证方式 | Bearer Token |
|
||
| 数据格式 | JSON |
|
||
| 绑定地址 | `127.0.0.1`（仅本机访问） |
|
||
|
||
### 认证
|
||
|
||
所有请求必须携带 `Authorization` 请求头：
|
||
|
||
```
|
||
Authorization: Bearer clb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
Token 可在 设置 → ChatLab API 页面查看和重新生成。
|
||
|
||
### 统一响应格式
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... },
|
||
"meta": {
|
||
"timestamp": 1711468800,
|
||
"version": "0.0.2"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "SESSION_NOT_FOUND",
|
||
"message": "Session not found: abc123"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 端点列表
|
||
|
||
### 系统
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ---------------- | -------------------------- |
|
||
| GET | `/api/v1/status` | 服务状态 |
|
||
| GET | `/api/v1/schema` | ChatLab Format JSON Schema |
|
||
|
||
### 数据查询（导出）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ------------------------------------- | ------------------------ |
|
||
| GET | `/api/v1/sessions` | 获取所有会话列表 |
|
||
| GET | `/api/v1/sessions/:id` | 获取单个会话详情 |
|
||
| GET | `/api/v1/sessions/:id/messages` | 查询消息（分页） |
|
||
| GET | `/api/v1/sessions/:id/members` | 获取成员列表 |
|
||
| GET | `/api/v1/sessions/:id/stats/overview` | 获取概览统计 |
|
||
| POST | `/api/v1/sessions/:id/sql` | 执行自定义 SQL（只读） |
|
||
| GET | `/api/v1/sessions/:id/export` | 导出 ChatLab Format JSON |
|
||
|
||
### 数据导入
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| ---- | ----------------------------- | ------------------------ |
|
||
| POST | `/api/v1/import` | 导入聊天记录（新建会话） |
|
||
| POST | `/api/v1/sessions/:id/import` | 增量导入到指定会话 |
|
||
|
||
---
|
||
|
||
## 端点详细说明
|
||
|
||
### GET /api/v1/status
|
||
|
||
获取 API 服务的运行状态。
|
||
|
||
**响应：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| -------------- | ------ | ------------------------- |
|
||
| `name` | string | 服务名称（`ChatLab API`） |
|
||
| `version` | string | ChatLab 应用版本 |
|
||
| `uptime` | number | 服务运行时间（秒） |
|
||
| `sessionCount` | number | 当前会话总数 |
|
||
|
||
---
|
||
|
||
### GET /api/v1/schema
|
||
|
||
获取 ChatLab Format 的 JSON Schema 定义，便于构建符合规范的导入数据。
|
||
|
||
---
|
||
|
||
### GET /api/v1/sessions
|
||
|
||
获取所有已导入的会话列表。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "session_abc123",
|
||
"name": "技术交流群",
|
||
"platform": "qq",
|
||
"type": "group",
|
||
"messageCount": 58000,
|
||
"memberCount": 120
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### GET /api/v1/sessions/:id
|
||
|
||
获取单个会话的详细信息。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| ---- | ------ | ------- |
|
||
| `id` | string | 会话 ID |
|
||
|
||
---
|
||
|
||
### GET /api/v1/sessions/:id/messages
|
||
|
||
分页查询指定会话的消息列表，支持多种过滤条件。
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
| ----------- | ------ | ------ | ------------------------ |
|
||
| `page` | number | 1 | 页码 |
|
||
| `limit` | number | 100 | 每页条数（最大 1000） |
|
||
| `startTime` | number | - | 起始时间戳（秒级 Unix） |
|
||
| `endTime` | number | - | 结束时间戳（秒级 Unix） |
|
||
| `keyword` | string | - | 关键词搜索 |
|
||
| `senderId` | string | - | 按发送者 platformId 筛选 |
|
||
| `type` | number | - | 按消息类型筛选 |
|
||
|
||
**请求示例：**
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:5200/api/v1/sessions/abc123/messages?page=1&limit=50&keyword=你好" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"messages": [
|
||
{
|
||
"senderPlatformId": "123456",
|
||
"senderName": "张三",
|
||
"timestamp": 1703001600,
|
||
"type": 0,
|
||
"content": "你好！"
|
||
}
|
||
],
|
||
"total": 1500,
|
||
"page": 1,
|
||
"limit": 50,
|
||
"totalPages": 30
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### GET /api/v1/sessions/:id/members
|
||
|
||
获取指定会话的所有成员列表。
|
||
|
||
---
|
||
|
||
### GET /api/v1/sessions/:id/stats/overview
|
||
|
||
获取指定会话的概览统计信息。
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"messageCount": 58000,
|
||
"memberCount": 120,
|
||
"timeRange": {
|
||
"start": 1609459200,
|
||
"end": 1703001600
|
||
},
|
||
"messageTypeDistribution": {
|
||
"0": 45000,
|
||
"1": 8000,
|
||
"5": 3000,
|
||
"80": 2000
|
||
},
|
||
"topMembers": [
|
||
{
|
||
"platformId": "123456",
|
||
"name": "张三",
|
||
"messageCount": 5800,
|
||
"percentage": 10.0
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| ------------------------- | -------------------------------------------------------------------------------- |
|
||
| `messageCount` | 总消息数 |
|
||
| `memberCount` | 成员数 |
|
||
| `timeRange` | 最早/最新消息时间戳（秒级 Unix） |
|
||
| `messageTypeDistribution` | 各消息类型的数量（key 为 [消息类型](./chatlab-format.md#消息类型对照表) 枚举值） |
|
||
| `topMembers` | 前 10 活跃成员（按消息数降序） |
|
||
|
||
---
|
||
|
||
### POST /api/v1/sessions/:id/sql
|
||
|
||
对指定会话的数据库执行只读 SQL 查询。仅允许 `SELECT` 语句。
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"sql": "SELECT sender, COUNT(*) as count FROM messages GROUP BY sender ORDER BY count DESC LIMIT 10"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"columns": ["sender", "count"],
|
||
"rows": [
|
||
["123456", 5800],
|
||
["789012", 3200]
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> 关于数据库表结构，请参考 ChatLab 内部文档或使用 `SELECT * FROM sqlite_master WHERE type='table'` 查询。
|
||
|
||
---
|
||
|
||
### GET /api/v1/sessions/:id/export
|
||
|
||
导出完整会话数据，格式为 [ChatLab Format](./chatlab-format.md) JSON。
|
||
|
||
**限制：** 最多导出 **10 万条** 消息。如果会话消息数超过此限制，返回 `400 EXPORT_TOO_LARGE` 错误。超大会话建议使用 `/messages` 分页 API 逐页获取。
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"chatlab": {
|
||
"version": "0.0.2",
|
||
"exportedAt": 1711468800,
|
||
"generator": "ChatLab API"
|
||
},
|
||
"meta": {
|
||
"name": "技术交流群",
|
||
"platform": "qq",
|
||
"type": "group"
|
||
},
|
||
"members": [...],
|
||
"messages": [...]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### POST /api/v1/import
|
||
|
||
将聊天记录导入 ChatLab，**创建新会话**。
|
||
|
||
#### 支持的 Content-Type
|
||
|
||
| Content-Type | 格式 | 适用场景 | Body 限制 |
|
||
| ---------------------- | ------------------- | ------------------------------ | ---------- |
|
||
| `application/json` | ChatLab Format JSON | 中小数据（快速测试、脚本集成） | **50MB** |
|
||
| `application/x-ndjson` | ChatLab JSONL 格式 | 大规模数据（生产级集成） | **无限制** |
|
||
|
||
#### JSON 模式示例
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:5200/api/v1/import \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"chatlab": {
|
||
"version": "0.0.2",
|
||
"exportedAt": 1711468800
|
||
},
|
||
"meta": {
|
||
"name": "导入测试",
|
||
"platform": "qq",
|
||
"type": "group"
|
||
},
|
||
"members": [
|
||
{ "platformId": "123", "accountName": "测试用户" }
|
||
],
|
||
"messages": [
|
||
{
|
||
"sender": "123",
|
||
"accountName": "测试用户",
|
||
"timestamp": 1711468800,
|
||
"type": 0,
|
||
"content": "Hello World"
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
#### JSONL 模式示例
|
||
|
||
```bash
|
||
cat data.jsonl | curl -X POST http://127.0.0.1:5200/api/v1/import \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-H "Content-Type: application/x-ndjson" \
|
||
--data-binary @-
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"mode": "new",
|
||
"sessionId": "session_xyz789"
|
||
}
|
||
}
|
||
```
|
||
|
||
> 关于 ChatLab Format 的详细规范，请参考 [ChatLab 标准化格式规范](./chatlab-format.md)。
|
||
|
||
---
|
||
|
||
### POST /api/v1/sessions/:id/import
|
||
|
||
将聊天记录**增量导入**到已存在的会话。支持去重，相同消息不会重复插入。
|
||
|
||
**去重规则：**
|
||
|
||
消息唯一键为 `timestamp + senderPlatformId + contentLength`。如果一条消息的时间戳、发送者和内容长度与已有消息完全相同，则视为重复并跳过。
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| ---- | ------ | ----------- |
|
||
| `id` | string | 目标会话 ID |
|
||
|
||
Content-Type 和请求体格式与 `POST /api/v1/import` 相同。
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"mode": "incremental",
|
||
"sessionId": "session_abc123",
|
||
"newMessageCount": 150
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 并发与限制
|
||
|
||
| 限制项 | 值 | 说明 |
|
||
| ---------------- | ------- | ------------------------------- |
|
||
| JSON 请求体大小 | 50MB | `application/json` 模式 |
|
||
| JSONL 请求体大小 | 无限制 | `application/x-ndjson` 流式模式 |
|
||
| 导出消息上限 | 10 万条 | `/export` 端点 |
|
||
| 分页最大每页 | 1000 条 | `/messages` 端点 |
|
||
| 导入并发 | 1 | 同一时刻仅允许一个导入操作 |
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | HTTP 状态码 | 说明 |
|
||
| ------------------------ | ----------- | ------------------------------- |
|
||
| `UNAUTHORIZED` | 401 | Token 无效或缺失 |
|
||
| `SESSION_NOT_FOUND` | 404 | 会话不存在 |
|
||
| `INVALID_FORMAT` | 400 | 请求体不符合 ChatLab Format |
|
||
| `SQL_READONLY_VIOLATION` | 400 | SQL 不是 SELECT 语句 |
|
||
| `SQL_EXECUTION_ERROR` | 400 | SQL 执行出错 |
|
||
| `EXPORT_TOO_LARGE` | 400 | 消息数超过导出上限（10 万条） |
|
||
| `BODY_TOO_LARGE` | 413 | 请求体超过 50MB（仅 JSON 模式） |
|
||
| `IMPORT_IN_PROGRESS` | 409 | 有其他导入正在进行 |
|
||
| `IMPORT_FAILED` | 500 | 导入失败 |
|
||
| `SERVER_ERROR` | 500 | 服务内部错误 |
|
||
|
||
---
|
||
|
||
## 安全说明
|
||
|
||
- **仅本机访问**：API 绑定 `127.0.0.1`，不对外暴露
|
||
- **Token 认证**：所有端点需携带有效 Bearer Token
|
||
- **SQL 只读限制**：`/sql` 端点仅允许 `SELECT` 查询
|
||
- **默认关闭**：API 服务需手动开启
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
### 1. MCP 集成
|
||
|
||
将 ChatLab API 接入 Claude Desktop 等 AI 工具，实现 AI 对聊天记录的直接查询和分析。
|
||
|
||
### 2. 自动化脚本
|
||
|
||
编写脚本定期从其他平台导出聊天记录，转换为 ChatLab Format 后通过 Push API 自动导入。
|
||
|
||
### 3. 数据分析
|
||
|
||
通过 SQL 端点执行自定义查询，配合 Python/R 等工具进行高级数据分析。
|
||
|
||
### 4. 数据备份
|
||
|
||
通过 `/export` 端点定期导出重要会话数据作为 JSON 备份。
|
||
|
||
### 5. 定时拉取
|
||
|
||
在设置页配置外部数据源 URL，ChatLab 会按设定间隔自动拉取并导入新数据。
|
||
|
||
---
|
||
|
||
## 版本信息
|
||
|
||
| 版本 | 说明 |
|
||
| ---- | ------------------------------------------------------------------------------ |
|
||
| v1 | 初始版本，支持会话查询、消息搜索、SQL、导出、导入（JSON + JSONL）、Pull 调度器 |
|