github/ChatLab
1
0
Fork 0
mirror of https://github.com/hellodigua/ChatLab.git synced 2026-05-21 13:50:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 新增繁体中文文档

Browse Source
This commit is contained in:
digua
2026-04-13 21:56:30 +08:00
parent 3c022b069a
commit c69dcdffbb
24 changed files with 1704 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cn/standard/ai-converter.md
+6 -12
View File
@@ -24,11 +24,9 @@ outline: deep
#### 复制 JSON 转换提示词
```markdown
**角色设定**：
你是一个精通数据处理和脚本编写的专家。
**角色设定**：你是一个精通数据处理和脚本编写的专家。
**任务目标**：
请根据我提供的【ChatLab 标准格式规范】（chatlab-format.md），编写一个脚本，将我上传的【原始聊天记录】转换为符合该规范的 **JSON 格式**。
**任务目标**：请根据我提供的【ChatLab 标准格式规范】（chatlab-format.md），编写一个脚本，将我上传的【原始聊天记录】转换为符合该规范的 **JSON 格式**。
**执行要求**：
@@ -44,8 +42,7 @@ outline: deep
4. **结果验证**：
- 请确保生成的 JSON 结构严格符合 `chatlab-format.md` 中的定义。
**输出**：
请直接提供代码，并简要说明如何运行该脚本。
**输出**：请直接提供代码，并简要说明如何运行该脚本。
```
### 场景二：超大规模数据
@@ -57,11 +54,9 @@ outline: deep
#### 复制 JSONL 转换提示词
```markdown
**角色设定**：
你是一个精通大数据处理和流式计算的专家。
**角色设定**：你是一个精通大数据处理和流式计算的专家。
**任务目标**：
请根据我提供的【ChatLab 标准格式规范】（chatlab-format.md），编写一个脚本，将我上传的【原始聊天记录】转换为符合该规范的 **JSONL (JSON Lines) 格式**。
**任务目标**：请根据我提供的【ChatLab 标准格式规范】（chatlab-format.md），编写一个脚本，将我上传的【原始聊天记录】转换为符合该规范的 **JSONL (JSON Lines) 格式**。
**执行要求**：
@@ -77,8 +72,7 @@ outline: deep
- 请编写一个**高效的 Python 脚本**。
- 确保处理过程内存占用恒定，适合处理 GB 级别的大文件。
**输出**：
请直接提供代码，并简要说明如何运行该脚本。
**输出**：请直接提供代码，并简要说明如何运行该脚本。
```
## 后续步骤
docs/cn/standard/chatlab-format.md
+11 -16
View File
@@ -10,9 +10,7 @@ ChatLab 定义了一套标准的聊天记录数据交换格式，用于支持多
只要你将聊天记录转为该格式，那么就可以被 ChatLab 解析并使用其分析能力。
::: warning 注意
该格式规范目前仍处于早期制定阶段，部分字段和结构可能会在后续版本中调整。
:::
::: warning 注意该格式规范目前仍处于早期制定阶段，部分字段和结构可能会在后续版本中调整。:::
## 概述
@@ -82,14 +80,14 @@ ChatLab 定义了一套标准的聊天记录数据交换格式，用于支持多
### 元信息 (meta)
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------------- | ---- | -------------------------------------------------------- |
| `name` | string | ✅ | 群名或对话名 |
| `platform` | string | ✅ | 平台标识，如 `qq` / `wechat` / `discord` / `whatsapp` 等 |
| `type` | string | ✅ | 聊天类型：`group`（群聊）/ `private`（私聊） |
| `groupId` | string | - | 群 ID（仅群聊） |
| `groupAvatar` | string | - | 群头像（Data URL 格式） |
| `ownerId` | string | - | 所有者/导出者的 platformId |
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | -------------------------------------------------------- |
| `name` | string | ✅ | 群名或对话名 |
| `platform` | string | ✅ | 平台标识，如 `qq` / `wechat` / `discord` / `whatsapp` 等 |
| `type` | string | ✅ | 聊天类型：`group`（群聊）/ `private`（私聊） |
| `groupId` | string | - | 群 ID（仅群聊） |
| `groupAvatar` | string | - | 群头像（Data URL 格式） |
| `ownerId` | string | - | 所有者/导出者的 platformId |
### 成员 (members)
@@ -167,9 +165,7 @@ ChatLab 定义了一套标准的聊天记录数据交换格式，用于支持多
## 消息类型对照表
::: tip 提示
若您的聊天记录中有其他特殊类型需要支持，请提交 issue 说明情况，我们会评估是否加入标准消息类型中。
:::
::: tip 提示若您的聊天记录中有其他特殊类型需要支持，请提交 issue 说明情况，我们会评估是否加入标准消息类型中。:::
### 基础消息类型 (0-19)
@@ -236,8 +232,7 @@ https://example.com/avatars/user123.jpg
- 如果需要离线使用或长期存档，推荐使用 Data URL 格式
- 导出 Data URL 时建议将头像压缩为 100×100 像素以内，以减小文件体积
- 如果头像来自可靠的长期有效的 CDN，可使用网络 URL 以减小文件体积
:::
- 如果头像来自可靠的长期有效的 CDN，可使用网络 URL 以减小文件体积 :::
## 完整示例
docs/cn/usage/index.md
+1 -1
View File
@@ -2,4 +2,4 @@
outline: deep
---
# USAGE
# USAGE
docs/en/quick-start.md
+2 -2
View File
@@ -16,11 +16,11 @@ This page tells you what the docs can help with and gives the shortest reading p
## Fastest path
::: tip Suggested path
1. [Export Chat Records](./usage/how-to-export.md)
2. [Import Chat Records](./usage/how-to-import.md)
3. [How to Configure AI](./usage/how-to-config-ai.md)
4. [Troubleshooting](./usage/troubleshooting.md)
:::
4. [Troubleshooting](./usage/troubleshooting.md) :::
## Useful links
docs/en/standard/ai-converter.md
+6 -12
View File
@@ -24,11 +24,9 @@ Select the appropriate prompt based on your data size.
#### Copy JSON Conversion Prompt
```markdown
**Role Setting**:
You are an expert in data processing and script writing.
**Role Setting**: You are an expert in data processing and script writing.
**Task Objective**:
Based on the [ChatLab Standard Format Specification] (chatlab-format.md) I provide, please write a script to convert my uploaded [original chat records] into the compliant **JSON format**.
**Task Objective**: Based on the [ChatLab Standard Format Specification] (chatlab-format.md) I provide, please write a script to convert my uploaded [original chat records] into the compliant **JSON format**.
**Requirements**:
@@ -44,8 +42,7 @@ Based on the [ChatLab Standard Format Specification] (chatlab-format.md) I provi
4. **Result Validation**:
- Ensure the generated JSON structure strictly conforms to the definitions in `chatlab-format.md`.
**Output**:
Please provide the code directly and briefly explain how to run the script.
**Output**: Please provide the code directly and briefly explain how to run the script.
```
### Scenario 2: Very Large Data
@@ -57,11 +54,9 @@ Please provide the code directly and briefly explain how to run the script.
#### Copy JSONL Conversion Prompt
```markdown
**Role Setting**:
You are an expert in big data processing and stream computing.
**Role Setting**: You are an expert in big data processing and stream computing.
**Task Objective**:
Based on the [ChatLab Standard Format Specification] (chatlab-format.md) I provide, please write a script to convert my uploaded [original chat records] into the compliant **JSONL (JSON Lines) format**.
**Task Objective**: Based on the [ChatLab Standard Format Specification] (chatlab-format.md) I provide, please write a script to convert my uploaded [original chat records] into the compliant **JSONL (JSON Lines) format**.
**Requirements**:
@@ -77,8 +72,7 @@ Based on the [ChatLab Standard Format Specification] (chatlab-format.md) I provi
- Please write an **efficient Python script**.
- Ensure constant memory usage during processing, suitable for GB-level large files.
**Output**:
Please provide the code directly and briefly explain how to run the script.
**Output**: Please provide the code directly and briefly explain how to run the script.
```
## Next Steps
docs/en/standard/chatlab-format.md
+11 -18
View File
@@ -8,9 +8,7 @@ ChatLab defines a standard chat record data exchange format to support unified i
As long as you convert your chat records to this format, ChatLab can parse and analyze them.
::: warning Notice
This format specification is still in its early development stage. Some fields and structures may be adjusted in future versions.
:::
::: warning Notice This format specification is still in its early development stage. Some fields and structures may be adjusted in future versions. :::
## Overview
@@ -80,13 +78,13 @@ Here's a **minimal** ChatLab format example with only required fields:
### Metadata (meta)
| Field | Type | Required | Description |
| ------------- | ------------- | -------- | ------------------------------------------------------------------- |
| `name` | string | ✅ | Group name or conversation name |
| `platform` | string | ✅ | Platform identifier: `qq` / `wechat` / `discord` / `whatsapp`, etc. |
| `type` | string | ✅ | Chat type: `group` / `private` |
| `groupId` | string | - | Group ID (group chat only) |
| `groupAvatar` | string | - | Group avatar (Data URL format) |
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `name` | string | ✅ | Group name or conversation name |
| `platform` | string | ✅ | Platform identifier: `qq` / `wechat` / `discord` / `whatsapp`, etc. |
| `type` | string | ✅ | Chat type: `group` / `private` |
| `groupId` | string | - | Group ID (group chat only) |
| `groupAvatar` | string | - | Group avatar (Data URL format) |
### Members (members)
@@ -113,9 +111,7 @@ Here's a **minimal** ChatLab format example with only required fields:
## Message Type Reference
::: warning Tip
If you have other special types in your chat records that need support, please submit an issue explaining your situation. We'll evaluate whether to add them to the standard message types.
:::
::: warning Tip If you have other special types in your chat records that need support, please submit an issue explaining your situation. We'll evaluate whether to add them to the standard message types. :::
### Basic Message Types (0-19)
@@ -166,9 +162,7 @@ Supported image formats:
- `image/gif` - GIF format
- `image/webp` - WebP format
::: tip Suggestion
When exporting, we recommend compressing avatars to 100×100 pixels or less to reduce file size.
:::
::: tip Suggestion When exporting, we recommend compressing avatars to 100×100 pixels or less to reduce file size. :::
## Complete Examples
@@ -302,8 +296,7 @@ JSONL (JSON Lines) format is suitable for **very large chat records** (>1 millio
::: warning Notice
- Each line must be **valid JSON** (cannot span lines)
- Lines are separated by newline `\n`
:::
- Lines are separated by newline `\n` :::
## Version History
docs/en/usage/index.md
+1 -1
View File
@@ -2,4 +2,4 @@
outline: deep
---
# USAGE
# USAGE
docs/env.d.ts
Vendored
+3 -3
View File
@@ -1,4 +1,4 @@
declare module "*.md?raw" {
const content: string;
export default content;
declare module '*.md?raw' {
const content: string
export default content
}
docs/tw/chatlab-api.md
+499
View File
@@ -0,0 +1,499 @@
# 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 调度器 |
docs/tw/chatlab-format.md
+389
View File
@@ -0,0 +1,389 @@
# ChatLab 標準化格式規範 v0.0.2
ChatLab 定義了一套標準的聊天記錄資料交換格式，用於支援多平台資料的統一匯入和分析。
只要你將聊天記錄轉為該格式，那麼就可以被 ChatLab 解析並使用其分析能力。
::: warning 注意該格式規範目前仍處於早期制定階段，部分欄位和結構可能會在後續版本中調整。:::
## 概述
### 支援的檔案格式
| 格式 | 副檔名 | 適用場景 |
| --------- | -------- | --------------------------------------------------- |
| **JSON** | `.json` | 中小型記錄（<100 萬條），結構清晰，易於閱讀 |
| **JSONL** | `.jsonl` | 超大規模記錄（>100 萬條），流式處理，記憶體佔用恆定 |
### 格式對比
| 特性 | JSON | JSONL |
| ------------ | ---------------------- | ----------------------- |
| 記憶體佔用 | 需載入完整結構 | 逐行處理，恆定 (~100MB) |
| 檔案大小限制 | ~1GB（取決於記憶體） | 無實際限制 |
| 追加寫入 | ❌ 需重寫整個檔案 | ✅ 直接追加行 |
| 錯誤復原 | 單處錯誤整檔案失效 | 可跳過錯誤行繼續 |
| 可讀性 | ⭐⭐⭐ 易於閱讀 | ⭐⭐ 每行一條記錄 |
| 推薦場景 | 小中型記錄 (<100 萬條) | 大型記錄 (>100 萬條) |
## 快速說明
以下是一個**最小化**的 ChatLab 格式範例，只包含必要欄位：
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1703001600
},
"meta": {
"name": "我的群聊",
"platform": "qq",
"type": "group"
},
"members": [
{
"platformId": "123456",
"accountName": "張三"
}
],
"messages": [
{
"sender": "123456",
"accountName": "張三",
"timestamp": 1703001600,
"type": 0,
"content": "大家好！"
}
]
}
```
---
## JSON 格式詳細說明
### 檔案頭 (chatlab)
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | ------ | ---- | ---------------------------- |
| `version` | string | ✅ | 格式版本號，目前為 `"0.0.2"` |
| `exportedAt` | number | ✅ | 匯出時間（秒級 Unix 時間戳） |
| `generator` | string | - | 產生工具名稱 |
| `description` | string | - | 描述資訊 |
### 元資訊 (meta)
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | ------------- | ---- | -------------------------------------------------------- |
| `name` | string | ✅ | 群名或對話名 |
| `platform` | string | ✅ | 平台標識，如 `qq` / `wechat` / `discord` / `whatsapp` 等 |
| `type` | string | ✅ | 聊天類型：`group`（群聊）/ `private`（私聊） |
| `groupId` | string | - | 群 ID（僅群聊） |
| `groupAvatar` | string | - | 群頭像（Data URL 格式） |
| `ownerId` | string | - | 所有者/匯出者的 platformId |
| `sources` | MergeSource[] | - | 合併來源（合併工具產生，見下方說明） |
#### MergeSource 結構（合併來源）
當使用合併工具合併多個聊天記錄檔案時，`sources` 欄位會記錄原始檔案的來源資訊：
| 欄位 | 類型 | 必填 | 說明 |
| -------------- | ------ | ---- | -------- |
| `filename` | string | ✅ | 原檔名 |
| `platform` | string | - | 原平台 |
| `messageCount` | number | ✅ | 訊息數量 |
### 成員 (members)
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | ------------ | ---- | --------------------------- |
| `platformId` | string | ✅ | 使用者唯一標識 |
| `accountName` | string | ✅ | 帳號名稱 |
| `groupNickname` | string | - | 群暱稱（僅群聊） |
| `aliases` | string[] | - | 使用者自訂別名 |
| `avatar` | string | - | 使用者頭像（Data URL 格式） |
| `roles` | MemberRole[] | - | 成員角色（可多個） |
#### 角色 (roles)
成員可以擁有一個或多個角色，用於標示群主、管理員等身份：
| 欄位 | 類型 | 必填 | 說明 |
| ------ | ------ | ---- | ------------------------------------ |
| `id` | string | ✅ | 角色標識：`owner` / `admin` / 自訂ID |
| `name` | string | - | 角色顯示名稱（自訂角色需要） |
**標準角色 ID：**
| ID | 說明 |
| ------- | ----------- |
| `owner` | 群主/建立者 |
| `admin` | 管理員 |
**角色範例：**
```json
// 群主
"roles": [{ "id": "owner" }]
// 管理員
"roles": [{ "id": "admin" }]
// 多角色
"roles": [
{ "id": "owner" },
{ "id": "tech-team", "name": "技術組" },
{ "id": "vip", "name": "VIP會員" }
]
```
### 訊息 (messages)
| 欄位 | 類型 | 必填 | 說明 |
| ------------------- | -------------- | ---- | --------------------------------- |
| `sender` | string | ✅ | 發送者的 `platformId` |
| `accountName` | string | ✅ | 發送時的帳號名稱 |
| `groupNickname` | string | - | 發送時的群暱稱 |
| `timestamp` | number | ✅ | 秒級 Unix 時間戳 |
| `type` | number | ✅ | 訊息類型（見下方對照表） |
| `content` | string \| null | ✅ | 訊息內容（非文字訊息可為 `null`） |
| `platformMessageId` | string | - | 訊息的平台原始 ID |
| `replyToMessageId` | string | - | 回覆的目標訊息 ID |
#### 訊息 ID 與回覆關係說明
**`platformMessageId`**（訊息的平台原始 ID）：
- 儲存訊息在原始平台上的唯一標識（如 Discord 的 snowflake ID、QQ 的訊息 ID）
- 用於在查詢時關聯 `replyToMessageId`，以顯示被回覆訊息的內容
- 如果平台不提供訊息 ID，可省略此欄位
**`replyToMessageId`**（回覆的目標訊息 ID）：
- 儲存被回覆訊息的**平台原始 ID**
- 透過與其他訊息的 `platformMessageId` 關聯，可查詢被回覆訊息的內容和發送者
- 僅當訊息是回覆類型時才有意義
- 如果平台不支援或資料不包含回覆關係，可省略此欄位
---
## 訊息類型對照表
::: tip 提示若您的聊天記錄中有其他特殊類型需要支援，請提交 issue 說明情況，我們會評估是否加入標準訊息類型中。:::
### 基礎訊息類型 (0-19)
| 值 | 名稱 | 說明 |
| --- | -------- | ----------- |
| 0 | TEXT | 文字訊息 |
| 1 | IMAGE | 圖片 |
| 2 | VOICE | 語音 |
| 3 | VIDEO | 影片 |
| 4 | FILE | 檔案 |
| 5 | EMOJI | 表情包/貼紙 |
| 7 | LINK | 連結/卡片 |
| 8 | LOCATION | 位置 |
### 互動訊息類型 (20-39)
| 值 | 名稱 | 說明 |
| --- | ---------- | ---------------------- |
| 20 | RED_PACKET | 紅包 |
| 21 | TRANSFER | 轉帳 |
| 22 | POKE | 拍一拍/戳一戳 |
| 23 | CALL | 語音/視訊通話 |
| 24 | SHARE | 分享（音樂、小程序等） |
| 25 | REPLY | 引用回覆 |
| 26 | FORWARD | 轉傳訊息 |
| 27 | CONTACT | 名片訊息 |
### 系統訊息類型 (80+)
| 值 | 名稱 | 說明 |
| --- | ------ | ------------------------------ |
| 80 | SYSTEM | 系統訊息（入群/退群/群公告等） |
| 81 | RECALL | 撤回訊息 |
| 99 | OTHER | 其他/未知 |
## 頭像格式說明
頭像欄位 `avatar` 和 `groupAvatar` 支援兩種格式：
### 1. Data URL
內嵌式格式，圖片資料直接編碼在檔案中，離線可用：
```
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
```
支援的圖片 MIME 類型：
- `image/jpeg` - JPEG 格式（推薦，體積較小）
- `image/png` - PNG 格式
- `image/gif` - GIF 格式
- `image/webp` - WebP 格式
### 2. 網路 URL
外連格式，圖片儲存在網路伺服器，體積更小但需網路存取：
```
https://example.com/avatars/user123.jpg
```
::: tip 建議
- 如果需要離線使用或長期存檔，推薦使用 Data URL 格式
- 匯出 Data URL 時建議將頭像壓縮為 100×100 像素以內，以減小檔案體積
- 如果頭像來自可靠的長期有效的 CDN，可使用網路 URL 以減小檔案體積 :::
## 完整範例
### 群聊範例（含可選欄位）
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1703001600,
"generator": "My Converter Tool",
"description": "2024年技術交流群聊天記錄備份"
},
"meta": {
"name": "技術交流群",
"platform": "wechat",
"type": "group",
"groupId": "38988428513",
"groupAvatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"ownerId": "abc123"
},
"members": [
{
"platformId": "abc123",
"accountName": "張三",
"groupNickname": "群主-張三",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"roles": [{ "id": "owner" }]
},
{
"platformId": "def456",
"accountName": "李四",
"groupNickname": "管理員",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"roles": [{ "id": "admin" }]
}
],
"messages": [
{
"platformMessageId": "msg_001",
"sender": "abc123",
"accountName": "張三",
"groupNickname": "群主-張三",
"timestamp": 1703001600,
"type": 0,
"content": "大家好！歡迎加入技術交流群~"
},
{
"platformMessageId": "msg_002",
"sender": "def456",
"accountName": "李四",
"groupNickname": "管理員",
"timestamp": 1703001610,
"type": 25,
"content": "收到！",
"replyToMessageId": "msg_001"
}
]
}
```
### 私聊範例
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1703001600
},
"meta": {
"name": "與小明的對話",
"platform": "qq",
"type": "private"
},
"members": [
{
"platformId": "123456789",
"accountName": "我",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
},
{
"platformId": "987654321",
"accountName": "小明",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
],
"messages": [
{
"sender": "123456789",
"accountName": "我",
"timestamp": 1703001600,
"type": 0,
"content": "在嗎？"
}
]
}
```
## JSONL 流式格式
JSONL（JSON Lines）格式適用於**超大規模聊天記錄**（>100 萬條），可避免記憶體溢位問題。
### 格式特點
- 每行一個 JSON 物件
- 透過 `_type` 欄位區分行類型：`header` / `member` / `message`
- 記憶體佔用恆定（約 100MB），支援 GB 級檔案
- 支援串流寫入，可邊匯出邊追加
### 行類型說明
| `_type` | 說明 | 是否必需 |
| --------- | -------------------------------- | --------------- |
| `header` | 檔案頭，包含 `chatlab` 和 `meta` | ✅ 必須在第一行 |
| `member` | 成員資訊 | - 可選 |
| `message` | 訊息記錄 | ✅ 至少一條 |
### 完整範例
```jsonl
{"_type":"header","chatlab":{"version":"0.0.2","exportedAt":1703001600},"meta":{"name":"技術交流群","platform":"qq","type":"group"}}
{"_type":"member","platformId":"123456","accountName":"張三","groupNickname":"群主","roles":[{"id":"owner"}]}
{"_type":"member","platformId":"789012","accountName":"李四"}
{"_type":"message","platformMessageId":"msg_001","sender":"123456","accountName":"張三","groupNickname":"群主","timestamp":1703001600,"type":0,"content":"大家好！"}
{"_type":"message","sender":"789012","accountName":"李四","timestamp":1703001610,"type":0,"content":"你好！"}
{"_type":"message","sender":"123456","accountName":"張三","groupNickname":"群主","timestamp":1703001620,"type":1,"content":"[圖片]"}
```
### 解析規則
1. **第一行必須是 header**：包含 `chatlab` 版本和 `meta` 元資訊
2. **成員行在訊息之前**：可選，如果省略，成員資訊會從訊息中自動收集
3. **訊息按時間順序排列**：建議按 `timestamp` 升冪排列
4. **每行獨立完整**：單行解析錯誤可跳過繼續處理
5. **支援註解行**：以 `#` 開頭的行會被跳過（可用於新增備註）
::: warning 注意
- 每行必須是**有效的 JSON**（不能跨行）
- 行之間用換行符 `\n` 分隔
:::
## 版本歷史
| 版本 | 日期 | 變更 |
| ----- | ---------- | ------------------------------------------------------------------------------ |
| 0.0.1 | 2025-12-22 | 初始版本 |
| 0.0.2 | 2026-01-09 | 新增 roles、ownerId、platformMessageId、replyToMessageId 欄位；新增 JSONL 格式 |
docs/tw/dev/design-philosophy.md
+28
View File
@@ -0,0 +1,28 @@
---
outline: deep
---
# 设计理念
ChatLab 在开发之初，就确立了以下核心设计原则，它们指导着软件的每一项功能实现与架构选择：
### 1. 彻底的本地化架构
- **数据主权**：我们认为聊天记录是极其私密的个人资产，因此 ChatLab 采用本地优先架构，核心数据库始终留存在用户设备中。
- **隐私屏障**：通过适配 Ollama 等工具支持本地 LLM 模型，确保即使在深度语义分析时，也可以实现完全的断网运行。
- **前置脱敏**：对于必须调用云端 API 的场景，系统内置了脱敏引擎，在数据离开本地前对敏感信息进行去标识化处理。
### 2. 语义化与非线性探索
- **超越检索**：传统的关键词搜索无法还原社交语境，ChatLab 引入 AI Agent 旨在实现语义层面的理解。
- **多维透视**：通过 AI 与 SQL 引擎的结合，用户可以从情感倾向、社交图谱、话题聚类等多个非线性维度重新审视数据。
### 3. 低门槛的分析体验
- **抹平技术鸿沟**：我们致力于将其封装为直观的可视化操作。
- **开箱即用**：用户无需配置复杂的编程环境或运行脚本，即可拥有专业级的数据拆解能力。
### 4. 开放的标准与生态 (Open Ecosystem)
- **透明可追溯**：作为处理私密数据的工具，ChatLab 坚持代码完全开源，接受全球开发者的安全监督。
- **数据交换规范**：我们正在建立一套通用的聊天记录交换格式，旨在打破不同社交平台间的“数据孤岛”，实现跨平台的数据兼容与迁移。
docs/tw/index.md
+8
View File
@@ -0,0 +1,8 @@
---
layout: page
sidebar: false
title: ChatLab — 重構你的社交記憶
titleTemplate: false
---
<HomePage />
docs/tw/intro.md
+32
View File
@@ -0,0 +1,32 @@
---
outline: deep
---
# ChatLab 介紹
ChatLab 是一個免費、開源、本地化的聊天記錄分析軟體。
在數位時代，聊天記錄早已不再是簡單的文字檔，它是長達十年的社交關係脈絡，是親人珍貴的語音片段，更是我們外掛在數位世界的情感大腦。
ChatLab 的誕生，就是為了**讓每位使用者都能安全地分析、回顧屬於自己的社交記憶。**
## 如何使用
想要分析你的聊天記錄，你需要完成以下兩步：
1. 匯出聊天記錄
2. 匯入聊天記錄
由於每個聊天軟體的匯出方式不同，具體步驟請參照 [匯出聊天記錄](./usage/how-to-export.md)。
## 下一步
<!-- 想要快速了解如何使用 ChatLab，請閱讀 [快速上手](./quick-start.md) 指南。 -->
遇到了匯入、AI 對話錯誤等問題，請參照 [常見問題](./usage/faq.md) 解決。
如果您匯出的聊天記錄格式不在目前支援範圍，請參照 [AI 輔助轉換指南](./standard/ai-converter.md)。
如果您是開發者，並支援了其他聊天應用的聊天記錄匯出，歡迎相容 [聊天資料交換標準化格式](./standard/chatlab-format.md)。
如果還有其他問題，歡迎加入社群回饋與交流：[加入社群](./other/community.md)
docs/tw/other/community.md
+21
View File
@@ -0,0 +1,21 @@
# 加入社群
歡迎加入社群取得最新進展、回饋問題，或透過郵箱聯繫開發者。
## 微信群
<WeChatGroupFlow />
## QQ 群
> **注意：QQ群僅討論 QQ 聊天記錄分析相關的話題，其他聊天軟體的問題不提供解答。**
群號：**1070511173**
## Discord
[點擊邀請連結](https://discord.gg/zWZnxNtDNz) 加入討論組
## 聯絡開發者
如果有其他問題諮詢討論，請郵件聯繫 hello@digua.me
docs/tw/quick-start.md
+7
View File
@@ -0,0 +1,7 @@
---
outline: deep
---
# 快速上手
待完善
docs/tw/standard/ai-converter.md
+82
View File
@@ -0,0 +1,82 @@
---
outline: deep
---
# AI 輔助轉換指南
如果你的聊天記錄格式（如 CSV, HTML, TXT 或其他資料庫匯出）目前不被 ChatLab 直接支援，你可以利用 AI（如 ChatGPT, Claude, DeepSeek 等）快速編寫一個轉換腳本，將你的資料轉換為 ChatLab 標準格式。
## 準備工作
1. **查看標準規範**：[ChatLab 標準格式規範 v0.0.2](./chatlab-format.md)
2. **準備資料**：準備好你匯出的原始聊天記錄檔案（如果是線上服務，建議僅提供幾百條脫敏後的樣本即可）。
## 選擇目標格式
請根據你的資料量大小，選擇合適的提示詞。
### 場景一：中小規模資料 (推薦)
- **目標格式**：JSON (`.json`)
- **適用場景**：記錄數 < 100 萬條，檔案體積 < 100MB。
- **特點**：結構清晰，相容性最好。
#### 複製 JSON 轉換提示詞
```markdown
**角色設定**：你是一個精通資料處理和腳本編寫的專家。
**任務目標**：請根據我提供的【ChatLab 標準格式規範】（chatlab-format.md），編寫一個腳本，將我上傳的【原始聊天記錄】轉換為符合該規範的 **JSON 格式**。
**執行要求**：
1. **分析結構**：分析原始聊天記錄的文字規律或資料結構。
2. **欄位映射**：
- 將原始欄位映射到 ChatLab 標準欄位（`timestamp`, `sender`, `content`, `type` 等）。
- 如果原始資料缺少 `sender` (使用者 ID)，請根據 `accountName` (使用者名) 自動產生一個唯一的雜湊值或虛擬 ID。
- `type` 預設為 0 (文字)。如果能從內容中識別出圖片、語音等類型，請嘗試映射。
3. **腳本產生**：
- 請編寫一個**完整的、可執行的腳本**（推薦 Python 或 Node.js）。
- **輸出結構**：腳本應建構一個包含 `chatlab`, `meta`, `members`, `messages` 的完整 JSON 物件，並一次性寫入檔案。
- 腳本需包含必要的錯誤處理，並列印進度。
4. **結果驗證**：
- 請確保產生的 JSON 結構嚴格符合 `chatlab-format.md` 中的定義。
**輸出**：請直接提供程式碼，並簡要說明如何執行該腳本。
```
### 場景二：超大規模資料
- **目標格式**：JSONL (`.jsonl`)
- **適用場景**：記錄數 > 100 萬條，或檔案體積巨大。
- **特點**：串流讀寫，記憶體佔用極低，不會因為資料量大而崩潰。
#### 複製 JSONL 轉換提示詞
```markdown
**角色設定**：你是一個精通大資料處理和串流計算的專家。
**任務目標**：請根據我提供的【ChatLab 標準格式規範】（chatlab-format.md），編寫一個腳本，將我上傳的【原始聊天記錄】轉換為符合該規範的 **JSONL (JSON Lines) 格式**。
**執行要求**：
1. **分析結構**：分析原始聊天記錄的文字規律。
2. **串流處理**：
- **必須採用串流讀寫**（Line-by-Line）的方式，不要一次性將所有資料載入到記憶體中。
- 逐行讀取原始檔案，逐行寫入目標檔案。
3. **JSONL 結構要求**：
- **第一行**：必須寫入 `_type: "header"` 行（包含 `chatlab` 和 `meta` 資訊）。
- **成員資訊**：如果可能，先掃描一遍或在處理過程中收集成員資訊，寫入 `_type: "member"` 行。
- **訊息記錄**：每一條聊天記錄寫入一行 `_type: "message"`。
4. **腳本產生**：
- 請編寫一個**高效的 Python 腳本**。
- 確保處理過程記憶體佔用恆定，適合處理 GB 級別的大檔案。
**輸出**：請直接提供程式碼，並簡要說明如何執行該腳本。
```
## 後續步驟
1. **執行腳本**：在本機環境中執行 AI 產生的腳本。
2. **檢查結果**：開啟產生的檔案，確認格式是否正確。
3. **匯入 ChatLab**：將產生的檔案匯入 ChatLab 進行分析。
docs/tw/standard/chatlab-format.md
+384
View File
@@ -0,0 +1,384 @@
---
outline: deep
---
# 聊天資料交換標準化格式
> v0.0.2
ChatLab 定義了一套標準的聊天記錄資料交換格式，用於支援多平台資料的統一匯入和分析。
只要你將聊天記錄轉為該格式，那麼就可以被 ChatLab 解析並使用其分析能力。
::: warning 注意該格式規範目前仍處於早期制定階段，部分欄位和結構可能會在後續版本中調整。:::
## 概述
### 支援的檔案格式
| 格式 | 副檔名 | 適用場景 |
| --------- | -------- | --------------------------------------------------- |
| **JSON** | `.json` | 中小型記錄（<100 萬條），結構清晰，易於閱讀 |
| **JSONL** | `.jsonl` | 超大規模記錄（>100 萬條），流式處理，記憶體佔用恆定 |
### 格式對比
| 特性 | JSON | JSONL |
| ------------ | ---------------------- | ----------------------- |
| 記憶體佔用 | 需載入完整結構 | 逐行處理，恆定 (~100MB) |
| 檔案大小限制 | ~1GB（取決於記憶體） | 無實際限制 |
| 追加寫入 | - 需重寫整個檔案 | ✅ 直接追加行 |
| 錯誤復原 | 單處錯誤整檔案失效 | 可跳過錯誤行繼續 |
| 可讀性 | ⭐⭐⭐ 易於閱讀 | ⭐⭐ 每行一條記錄 |
| 推薦場景 | 小中型記錄 (<100 萬條) | 大型記錄 (>100 萬條) |
## 快速說明
以下是一個**最小化**的 ChatLab 格式範例，只包含必要欄位：
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1703001600
},
"meta": {
"name": "我的群聊",
"platform": "qq",
"type": "group"
},
"members": [
{
"platformId": "123456",
"accountName": "張三"
}
],
"messages": [
{
"sender": "123456",
"accountName": "張三",
"timestamp": 1703001600,
"type": 0,
"content": "大家好！"
}
]
}
```
---
## JSON 格式詳細說明
### 檔案頭 (chatlab)
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | ------ | ---- | ---------------------------- |
| `version` | string | ✅ | 格式版本號，目前為 `"0.0.2"` |
| `exportedAt` | number | ✅ | 匯出時間（秒級 Unix 時間戳） |
| `generator` | string | - | 產生工具名稱 |
| `description` | string | - | 描述資訊 |
### 元資訊 (meta)
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | ------ | ---- | -------------------------------------------------------- |
| `name` | string | ✅ | 群名或對話名 |
| `platform` | string | ✅ | 平台標識，如 `qq` / `wechat` / `discord` / `whatsapp` 等 |
| `type` | string | ✅ | 聊天類型：`group`（群聊）/ `private`（私聊） |
| `groupId` | string | - | 群 ID（僅群聊） |
| `groupAvatar` | string | - | 群頭像（Data URL 格式） |
| `ownerId` | string | - | 所有者/匯出者的 platformId |
### 成員 (members)
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | ------------ | ---- | --------------------------- |
| `platformId` | string | ✅ | 使用者唯一標識 |
| `accountName` | string | ✅ | 帳號名稱 |
| `groupNickname` | string | - | 群暱稱（僅群聊） |
| `aliases` | string[] | - | 使用者自訂別名 |
| `avatar` | string | - | 使用者頭像（Data URL 格式） |
| `roles` | MemberRole[] | - | 成員角色（可多個） |
#### 角色 (roles)
成員可以擁有一個或多個角色，用於標示群主、管理員等身份：
| 欄位 | 類型 | 必填 | 說明 |
| ------ | ------ | ---- | ------------------------------------- |
| `id` | string | ✅ | 角色標識：`owner` / `admin` / 自訂 ID |
| `name` | string | - | 角色顯示名稱（自訂角色需要） |
**標準角色 ID：**
| ID | 說明 |
| ------- | ----------- |
| `owner` | 群主/建立者 |
| `admin` | 管理員 |
**角色範例：**
```json
// 群主
"roles": [{ "id": "owner" }]
// 管理員
"roles": [{ "id": "admin" }]
// 多角色
"roles": [
{ "id": "owner" },
{ "id": "tech-team", "name": "技術組" },
{ "id": "vip", "name": "VIP會員" }
]
```
### 訊息 (messages)
| 欄位 | 類型 | 必填 | 說明 |
| ------------------- | -------------- | ---- | --------------------------------- |
| `sender` | string | ✅ | 發送者的 `platformId` |
| `accountName` | string | ✅ | 發送時的帳號名稱 |
| `groupNickname` | string | - | 發送時的群暱稱 |
| `timestamp` | number | ✅ | 秒級 Unix 時間戳 |
| `type` | number | ✅ | 訊息類型（見下方對照表） |
| `content` | string \| null | ✅ | 訊息內容（非文字訊息可為 `null`） |
| `platformMessageId` | string | - | 訊息的平台原始 ID |
| `replyToMessageId` | string | - | 回覆的目標訊息 ID |
#### 訊息 ID 與回覆關係說明
**`platformMessageId`**（訊息的平台原始 ID）：
- 儲存訊息在原始平台上的唯一標識（如 Discord 的 snowflake ID、QQ 的訊息 ID）
- 用於在查詢時關聯 `replyToMessageId`，以顯示被回覆訊息的內容
- 如果平台不提供訊息 ID，可省略此欄位
**`replyToMessageId`**（回覆的目標訊息 ID）：
- 儲存被回覆訊息的**平台原始 ID**
- 透過與其他訊息的 `platformMessageId` 關聯，可查詢被回覆訊息的內容和發送者
- 僅當訊息是回覆類型時才有意義
- 如果平台不支援或資料不包含回覆關係，可省略此欄位
---
## 訊息類型對照表
::: tip 提示若您的聊天記錄中有其他特殊類型需要支援，請提交 issue 說明情況，我們會評估是否加入標準訊息類型中。:::
### 基礎訊息類型 (0-19)
| 值 | 名稱 | 說明 |
| --- | -------- | ----------- |
| 0 | TEXT | 文字訊息 |
| 1 | IMAGE | 圖片 |
| 2 | VOICE | 語音 |
| 3 | VIDEO | 影片 |
| 4 | FILE | 檔案 |
| 5 | EMOJI | 表情包/貼紙 |
| 7 | LINK | 連結/卡片 |
| 8 | LOCATION | 位置 |
### 互動訊息類型 (20-39)
| 值 | 名稱 | 說明 |
| --- | ---------- | ---------------------- |
| 20 | RED_PACKET | 紅包 |
| 21 | TRANSFER | 轉帳 |
| 22 | POKE | 拍一拍/戳一戳 |
| 23 | CALL | 語音/視訊通話 |
| 24 | SHARE | 分享（音樂、小程序等） |
| 25 | REPLY | 引用回覆 |
| 26 | FORWARD | 轉傳訊息 |
| 27 | CONTACT | 名片訊息 |
### 系統訊息類型 (80+)
| 值 | 名稱 | 說明 |
| --- | ------ | ------------------------------ |
| 80 | SYSTEM | 系統訊息（入群/退群/群公告等） |
| 81 | RECALL | 撤回訊息 |
| 99 | OTHER | 其他/未知 |
## 頭像格式說明
頭像欄位 `avatar` 和 `groupAvatar` 支援兩種格式：
### 1. Data URL
內嵌式格式，圖片資料直接編碼在檔案中，離線可用：
```
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
```
支援的圖片 MIME 類型：
- `image/jpeg` - JPEG 格式（推薦，體積較小）
- `image/png` - PNG 格式
- `image/gif` - GIF 格式
- `image/webp` - WebP 格式
### 2. 網路 URL
外連格式，圖片儲存在網路伺服器，體積更小但需網路存取：
```
https://example.com/avatars/user123.jpg
```
::: tip 建議
- 如果需要離線使用或長期存檔，推薦使用 Data URL 格式
- 匯出 Data URL 時建議將頭像壓縮為 100×100 像素以內，以減小檔案體積
- 如果頭像來自可靠的長期有效的 CDN，可使用網路 URL 以減小檔案體積 :::
## 完整範例
### 群聊範例（含可選欄位）
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1703001600,
"generator": "My Converter Tool",
"description": "2024年技術交流群聊天記錄備份"
},
"meta": {
"name": "技術交流群",
"platform": "wechat",
"type": "group",
"groupId": "38988428513",
"groupAvatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"ownerId": "abc123"
},
"members": [
{
"platformId": "abc123",
"accountName": "張三",
"groupNickname": "群主-張三",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"roles": [{ "id": "owner" }]
},
{
"platformId": "def456",
"accountName": "李四",
"groupNickname": "管理員",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
"roles": [{ "id": "admin" }]
}
],
"messages": [
{
"platformMessageId": "msg_001",
"sender": "abc123",
"accountName": "張三",
"groupNickname": "群主-張三",
"timestamp": 1703001600,
"type": 0,
"content": "大家好！歡迎加入技術交流群~"
},
{
"platformMessageId": "msg_002",
"sender": "def456",
"accountName": "李四",
"groupNickname": "管理員",
"timestamp": 1703001610,
"type": 25,
"content": "收到！",
"replyToMessageId": "msg_001"
}
]
}
```
### 私聊範例
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1703001600
},
"meta": {
"name": "與小明的對話",
"platform": "qq",
"type": "private"
},
"members": [
{
"platformId": "123456789",
"accountName": "我",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
},
{
"platformId": "987654321",
"accountName": "小明",
"avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
],
"messages": [
{
"sender": "123456789",
"accountName": "我",
"timestamp": 1703001600,
"type": 0,
"content": "在嗎？"
}
]
}
```
## JSONL 流式格式
JSONL（JSON Lines）格式適用於**超大規模聊天記錄**（>100 萬條），可避免記憶體溢位問題。
### 格式特點
- 每行一個 JSON 物件
- 透過 `_type` 欄位區分行類型：`header` / `member` / `message`
- 記憶體佔用恆定（約 100MB），支援 GB 級檔案
- 支援串流寫入，可邊匯出邊追加
### 行類型說明
| `_type` | 說明 | 是否必需 |
| --------- | -------------------------------- | --------------- |
| `header` | 檔案頭，包含 `chatlab` 和 `meta` | ✅ 必須在第一行 |
| `member` | 成員資訊 | - 可選 |
| `message` | 訊息記錄 | ✅ 至少一條 |
### 完整範例
```jsonl
{"_type":"header","chatlab":{"version":"0.0.2","exportedAt":1703001600},"meta":{"name":"技術交流群","platform":"qq","type":"group"}}
{"_type":"member","platformId":"123456","accountName":"張三","groupNickname":"群主","roles":[{"id":"owner"}]}
{"_type":"member","platformId":"789012","accountName":"李四"}
{"_type":"message","platformMessageId":"msg_001","sender":"123456","accountName":"張三","groupNickname":"群主","timestamp":1703001600,"type":0,"content":"大家好！"}
{"_type":"message","sender":"789012","accountName":"李四","timestamp":1703001610,"type":0,"content":"你好！"}
{"_type":"message","sender":"123456","accountName":"張三","groupNickname":"群主","timestamp":1703001620,"type":1,"content":"[圖片]"}
```
### 解析規則
1. **第一行必須是 header**：包含 `chatlab` 版本和 `meta` 元資訊
2. **成員行在訊息之前**：可選，如果省略，成員資訊會從訊息中自動收集
3. **訊息按時間順序排列**：建議按 `timestamp` 升冪排列
4. **每行獨立完整**：單行解析錯誤可跳過繼續處理
5. **支援註解行**：以 `#` 開頭的行會被跳過（可用於新增備註）
::: warning 注意
- 每行必須是**有效的 JSON**（不能跨行）
- 行之間用換行符 `\n` 分隔
:::
## 版本歷史
| 版本 | 日期 | 變更 |
| ----- | ---------- | ------------------------------------------------------------------------------ |
| 0.0.1 | 2025-12-22 | 初始版本 |
| 0.0.2 | 2026-01-09 | 新增 roles、ownerId、platformMessageId、replyToMessageId 欄位；新增 JSONL 格式 |
docs/tw/usage/faq.md
+23
View File
@@ -0,0 +1,23 @@
---
outline: deep
---
# 常見問題
這裡彙總 ChatLab 使用中高頻出現的問題與處理思路。
## 匯出問題
待補充。
## 匯入問題
待補充。
## AI相關問題
待補充。
## 軟體異常錯誤問題
待補充。
docs/tw/usage/how-to-config-ai.md
+31
View File
@@ -0,0 +1,31 @@
---
outline: deep
---
# 如何配置 AI 模型
## 在线 AI 模型
这里以 deepseek 为例，其他的模型请自行搜索配置方法：
1. 访问 [Deepseek 官网](https://www.deepseek.com/)，选择 API 开放平台，注册并登录
![](/cn/img/ai-guide/1.png)
2. 选择左侧充值，充值你所需要的金额（建议先充 10 块钱，足够用很久了）
![](/cn/img/ai-guide/2.png)
3. 选择左侧 API Keys，点击创建 API key，随便填写一个标题，然后复制 API Key
![](/cn/img/ai-guide/3.png)
4. 打开 ChatLab，右下角点击设置，然后「模型配置」>「添加新配置」
把刚才复制的 API Key 填写到 API Keys 中，点击验证确认没问题后，点击右下角添加后，即可开始使用 AI 相关功能
![](/cn/img/ai-guide/4.png)
5. 在左侧的用量信息中，你可以查看你充值和消费的额度
![](/cn/img/ai-guide/5.png)
docs/tw/usage/how-to-export.md
+5
View File
@@ -0,0 +1,5 @@
---
outline: deep
---
<HowToExportCNDoc />
docs/tw/usage/how-to-import.md
+18
View File
@@ -0,0 +1,18 @@
---
outline: deep
---
# 匯入聊天記錄指南
完成匯出後，您只需在 ChatLab 的首頁：
1. 將匯出的**資料檔案**直接拖入上傳區域。
2. 等待 ChatLab 解析完成即可。
## BUG 排查
如果匯入失敗，可以透過日誌快速排查問題：
軟體左下角「設定」 > 「基礎設定」 > 「日誌檔案」，開啟該目錄，該目錄下有個「import」目錄，就是所有匯入的日誌記錄了。
如果您看不懂，可以透過 Github issue 提交問題。
docs/tw/usage/index.md
+5
View File
@@ -0,0 +1,5 @@
---
outline: deep
---
# 使用說明
docs/tw/usage/qa.md
+50
View File
@@ -0,0 +1,50 @@
# Q&A
## 未来会支持音频、图片导入吗？
不确定，目前的文本分析功能仍然有非常多的 TODO 需要实现，计划文本分析的功能完善之后再考虑音频和图片的分析。
## 如何直接访问本地数据库
ChatLab 使用 SQLite 存储聊天记录，你可以用任何 SQLite 客户端工具直接查看数据。
### 数据库位置
你可直接通过软件的 设置 > 存储管理 > 聊天记录数据库 > 打开，打开数据库所在文件夹。
| 平台 | 路径 |
| ------- | ------------------------------------------------------- |
| macOS | `~/Library/Application Support/ChatLab/data/databases/` |
| Windows | `%APPDATA%/ChatLab/data/databases/` |
| Linux | `~/.config/ChatLab/data/databases/` |
每个聊天记录是一个独立的 `.db` 文件。
### 推荐工具
- [DB Browser for SQLite](https://sqlitebrowser.org/) - 免费开源，新手友好
- [TablePlus](https://tableplus.com/) - 界面美观
- [DBeaver](https://dbeaver.io/) - 功能强大
### 命令行访问
```bash
# macOS/Linux
sqlite3 ~/Library/Application\ Support/ChatLab/data/databases/你的数据库.db
# 常用命令
.tables # 查看所有表
.schema message # 查看 message 表结构
SELECT * FROM message LIMIT 10; # 查询消息
```
### 表结构
- `meta` - 聊天记录元信息
- `member` - 成员信息
- `message` - 消息内容
- `member_name_history` - 成员改名历史
### 注意事项
⚠️ 建议在 ChatLab **关闭时**访问数据库，避免锁冲突。
docs/tw/usage/troubleshooting.md
+81
View File
@@ -0,0 +1,81 @@
---
outline: deep
---
# 故障排查指南
本文档帮助用户和开发者排查 ChatLab 使用中遇到的问题。
## 日志文件
**获取日志文件**：软件左下角的 **「设置」 > 「存储管理」 > 「日志文件」 > 打开目录**
日志存储在 `文档/ChatLab/logs/` 目录下：
```
ChatLab/logs/
├── app.log # 主程序日志
├── ai/ # AI 相关日志
│ └── ai_YYYY-MM-DD_HH-mm.log
└── import/ # 导入日志
└── import_{sessionId}_{timestamp}.log
```
### 日志文件说明
| 目录/文件 | 内容 |
| -------------- | ------------------------------------------------ |
| `app.log` | 主程序日志，包含文件解析、数据库操作、IPC 通信等 |
| `ai/*.log` | AI 日志，包含 LLM 调用、Agent 执行、工具调用等 |
| `import/*.log` | 导入性能日志，包含导入速度、内存使用、各阶段耗时 |
## 常见问题
### 1. 导入失败
**症状**：拖入文件后提示解析失败
**排查步骤**：
1. 确认文件格式是否支持（.json / .jsonl / .txt）
2. 检查文件是否损坏（用文本编辑器打开查看）
3. 查看日志文件中的 `[Parser]` 相关错误
### 2. AI 功能无响应
**症状**：AI 实验室发送消息后无回复
**排查步骤**：
1. 检查是否已配置 API Key（设置 > AI 设置）
2. 点击「验证」，确认 API 连接正常
3. 查看日志文件中的 `[LLM]` 或 `[Agent]` 相关错误
**常见原因**：
- API Key 无效或余额不足
- API 服务商限流
### 3. 数据库错误
**症状**：打开会话时提示错误
**排查步骤**：
1. 查看日志文件中的 `[Database]` 相关错误
2. 检查数据库文件是否存在
## 反馈问题
如果以上方法无法解决问题，请：
1. 收集日志文件
2. 描述问题复现步骤
3. 提交 Issue 到 GitHub
**提交 Issue 时请包含**：
- 操作系统及版本
- ChatLab 版本
- 问题描述及复现步骤
- 相关日志片段（注意脱敏）