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