onezion-chatlab

name	onezion-chatlab
description	ChatLab 本地聊天记录查询工具。通过 ChatLab REST API 查询、搜索、统计导入的聊天记录（WhatsApp、微信等）。支持关键词搜索、SQL 聚合查询、会话管理、数据导入导出。触发词：ChatLab、聊天记录、chat history、search chat、聊天搜索、查询消息、聊天统计
agent_created	true
triggers	["ChatLab","chatlab","聊天记录","chat history","search chat","聊天搜索","查询消息","聊天统计","聊天导出"]

onezion-chatlab — ChatLab 本地聊天记录查询

通过 ChatLab REST API 查询、搜索和分析导入的本地聊天记录。

前置条件

ChatLab API 已启用（Settings → ChatLab API → Enable Service）。Token 已配置，无需用户额外操作。

API 配置

项目	值
Base URL	http://127.0.0.1:5200
API Prefix	/api/v1
认证	Authorization: Bearer YOUR_CHATLAB_TOKEN
数据格式	JSON

Token 前缀为 clb_。如过期，引导用户到 ChatLab Settings → ChatLab API 重新生成。

常用 curl 命令模板

所有请求都必须带上认证 header：

TOKEN="YOUR_CHATLAB_TOKEN"
AUTH="-H 'Authorization: Bearer $TOKEN'"

服务状态

curl -s http://127.0.0.1:5200/api/v1/status \
  -H "Authorization: Bearer $TOKEN"

列出所有会话

curl -s http://127.0.0.1:5200/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN"

获取单个会话详情

curl -s http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID> \
  -H "Authorization: Bearer $TOKEN"

查询消息（带过滤）

# 关键词搜索
curl -s "http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/messages?keyword=<KEYWORD>&page=1&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# 时间范围过滤（Unix 时间戳）
curl -s "http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/messages?startTime=1700000000&endTime=1710000000" \
  -H "Authorization: Bearer $TOKEN"

# 按发送者过滤
curl -s "http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/messages?senderId=<SENDER_ID>" \
  -H "Authorization: Bearer $TOKEN"

# 组合过滤
curl -s "http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/messages?keyword=<KEYWORD>&startTime=<TS>&endTime=<TS>&senderId=<ID>&page=1&limit=100" \
  -H "Authorization: Bearer $TOKEN"

消息查询支持参数：page, limit（最大1000）, startTime, endTime（Unix时间戳）, keyword, senderId, type

获取成员列表

curl -s http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/members \
  -H "Authorization: Bearer $TOKEN"

获取会话统计概览

curl -s http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/stats/overview \
  -H "Authorization: Bearer $TOKEN"

执行 SQL 查询（只读）

curl -s -X POST http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/sql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT sender, COUNT(*) as count FROM messages GROUP BY sender ORDER BY count DESC LIMIT 10"}'

注意：仅允许 SELECT 查询。 常用 SQL 示例：

-- 消息数量按发送者统计
SELECT sender, COUNT(*) as count FROM messages GROUP BY sender ORDER BY count DESC;

-- 按日期统计消息量
SELECT date(timestamp, 'unixepoch') as day, COUNT(*) as count FROM messages GROUP BY day ORDER BY day;

-- 关键词搜索（SQL 方式）
SELECT * FROM messages WHERE content LIKE '%关键词%' ORDER BY timestamp DESC LIMIT 20;

-- 最活跃时段
SELECT strftime('%H', timestamp, 'unixepoch') as hour, COUNT(*) as count FROM messages GROUP BY hour ORDER BY count DESC;

导出会话

curl -s "http://127.0.0.1:5200/api/v1/sessions/<SESSION_ID>/export" \
  -H "Authorization: Bearer $TOKEN"

导出限制：最多 100,000 条消息。

导入聊天记录

⚠️ 2026-05-07 踩坑：ChatLab API 的 JSON import endpoint (POST /api/v1/import) 会返回 error.unrecognized_format，无论怎么调格式都不认。必须通过 GUI 文件导入。

ChatLab 的导入方式是拖拽文件到 GUI，它会自动检测格式。支持的格式包括：

• WhatsApp native txt (.txt) ✅ 最可靠
• 微信聊天记录导出文件
• 其他平台导出

从 chatlog 导入微信数据到 ChatLab 的正确流程：

1. 确保 chatlog 服务正在运行（sudo ./chatlog）
2. 用 chatlog API 拉取消息（分页，每次最多 5000 条）：

   # 分页拉取
   curl -s "http://127.0.0.1:5030/api/v1/history?chat=<CHAT_ID>&limit=5000&format=json"
   curl -s "http://127.0.0.1:5030/api/v1/history?chat=<CHAT_ID>&limit=5000&offset=5000&format=json"
   # ... 继续增加 offset 直到返回空
   

3. 将 JSON 转换为 WhatsApp native txt 格式：

   [DD/MM/YYYY, HH:MM:SS] Sender: Message
   

   系统消息格式：DD/MM/YYYY, HH:MM:SS - System message content 图片/视频/语音：[DD/MM/YYYY, HH:MM:SS] Sender: [image omitted]
4. 保存为 .txt 文件
5. 在 ChatLab GUI 中导入该文件（拖拽或文件选择器）
6. ChatLab 会自动解析并创建数据库

⚠️ 重要：直接往 ChatLab 的 SQLite 数据库写入不可行——ChatLab 启动时会校验数据库完整性，手动创建的 db 文件会导致 API 无法响应（端口开但请求超时）。

工作流程

查询聊天记录时

1. 先用 GET /sessions 获取会话列表，确认目标会话 ID
2. 用 GET /sessions/:id/members 获取成员列表（了解发送者）
3. 根据需求选择：
   • 简单搜索 → GET /sessions/:id/messages?keyword=xxx
   • 统计分析 → POST /sessions/:id/sql 执行聚合查询
   • 内容导出 → GET /sessions/:id/export

分析聊天内容时

1. 先用 GET /sessions/:id/stats/overview 了解整体概况
2. 用 SQL 查询进行维度分析（按人、按时间、按类型）
3. 用关键词搜索定位具体消息
4. 结果过多时分页获取（page 参数）

从微信导出到 ChatLab（完整流程）

1. sudo ./chatlog 启动 chatlog 服务（端口 5030）
2. GET /sessions?format=json 找到目标群的 chat ID
3. 分页拉取 GET /history?chat=<ID>&limit=5000&offset=<N>
4. Python 转换为 WhatsApp native txt 格式
5. 保存为 .txt 文件
6. ChatLab GUI 导入

ChatLab 数据库结构

数据库路径：~/Library/Application Support/ChatLab/data/databases/<session_id>.db

-- 会话元信息
CREATE TABLE meta (name, platform, type, imported_at, group_id, group_avatar, owner_id, schema_version, session_gap_threshold);

-- 成员
CREATE TABLE member (id INTEGER PRIMARY KEY AUTOINCREMENT, account_name, group_nickname, platform_id TEXT UNIQUE, avatar);

-- 成员昵称变更历史
CREATE TABLE member_name_history (id, member_id, name, changed_at);

-- 消息
CREATE TABLE message (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    sender_id INTEGER NOT NULL,
    sender_account_name TEXT,
    sender_group_nickname TEXT,
    ts INTEGER NOT NULL,
    type INTEGER NOT NULL,
    content TEXT,
    reply_to_message_id TEXT,
    platform_message_id TEXT,
    FOREIGN KEY(sender_id) REFERENCES member(id)
);

注意事项

• ChatLab 服务仅绑定 127.0.0.1，仅本地可访问
• SQL 查询只允许 SELECT，不支持写操作
• 消息分页最大每页 1000 条
• 导出最多 100,000 条消息
• JSON API import 不可用，必须通过 GUI 文件导入
• 直接写 SQLite 不可行，ChatLab 会校验完整性