# 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 格式 |
