ChatLab

ChatLab 标准化格式规范 v0.0.1 ​

ChatLab 定义了一套标准的聊天记录数据交换格式，用于支持多平台数据的统一导入和分析。

只要你将聊天记录转为该格式，那么就可以被 ChatLab 解析并使用其分析能力。

注意

该格式规范目前仍处于早期制定阶段，部分字段和结构可能会在后续版本中调整。

概述 ​

支持的文件格式 ​

格式扩展名适用场景
JSON.json中小型记录（<100 万条），结构清晰，易于阅读
JSONL.jsonl超大规模记录（>100 万条），流式处理，内存占用恒定

格式对比 ​

特性JSONJSONL
内存占用需加载完整结构逐行处理，恒定 (~100MB)
文件大小限制~1GB（取决于内存）无实际限制
追加写入- 需重写整个文件✅ 直接追加行
错误恢复单处错误整文件失效可跳过错误行继续
可读性⭐⭐⭐ 易于阅读⭐⭐ 每行一条记录
推荐场景小中型记录 (<100 万条)大型记录 (>100 万条)

快速说明 ​

以下是一个最小化的 ChatLab 格式示例，只包含必要字段：

json
{
  "chatlab": {
    "version": "0.0.1",
    "exportedAt": 1703001600
  },
  "meta": {
    "name": "我的群聊",
    "platform": "qq",
    "type": "group"
  },
  "members": [
    {
      "platformId": "123456",
      "accountName": "张三"
    }
  ],
  "messages": [
    {
      "sender": "123456",
      "accountName": "张三",
      "timestamp": 1703001600,
      "type": 0,
      "content": "大家好！"
    }
  ]
}

JSON 格式详细说明 ​

文件头 (chatlab) ​

字段类型必填说明
versionstring✅格式版本号，当前为 "0.0.1"
exportedAtnumber✅导出时间（秒级 Unix 时间戳）
generatorstring-生成工具名称
descriptionstring-描述信息

元信息 (meta) ​

字段类型必填说明
namestring✅群名或对话名
platformstring✅平台标识，如 qq / wechat / discord / whatsapp 等
typestring✅聊天类型：group（群聊）/ private（私聊）
groupIdstring-群 ID（仅群聊）
groupAvatarstring-群头像（Data URL 格式）
sourcesMergeSource[]-合并来源（合并工具生成，见下方说明）

MergeSource 结构（合并来源） ​

当使用合并工具合并多个聊天记录文件时，sources 字段会记录原始文件的来源信息：

字段类型必填说明
filenamestring✅原文件名
platformstring-原平台
messageCountnumber✅消息数量

成员 (members) ​

字段类型必填说明
platformIdstring✅用户唯一标识
accountNamestring✅账号名称
groupNicknamestring-群昵称（仅群聊）
aliasesstring[]-用户自定义别名
avatarstring-用户头像（Data URL 格式）

消息 (messages) ​

字段类型必填说明
senderstring✅发送者的 platformId
accountNamestring✅发送时的账号名称
groupNicknamestring-发送时的群昵称
timestampnumber✅秒级 Unix 时间戳
typenumber✅消息类型（见下方对照表）
contentstring | null✅消息内容（非文本消息可为 null）

消息类型对照表 ​

提示

若您的聊天记录中有其他特殊类型需要支持，请提交 issue 说明情况，我们会评估是否加入标准消息类型中。

基础消息类型 (0-19) ​

值名称说明
0TEXT文本消息
1IMAGE图片
2VOICE语音
3VIDEO视频
4FILE文件
5EMOJI表情包/贴纸
7LINK链接/卡片
8LOCATION位置

交互消息类型 (20-39) ​

值名称说明
20RED_PACKET红包
21TRANSFER转账
22POKE拍一拍/戳一戳
23CALL语音/视频通话
24SHARE分享（音乐、小程序等）
25REPLY引用回复
26FORWARD转发消息
27CONTACT名片消息

系统消息类型 (80+) ​

值名称说明
80SYSTEM系统消息（入群/退群/群公告等）
81RECALL撤回消息
99OTHER其他/未知

头像格式说明 ​

头像字段 avatar 和 groupAvatar 使用 Data URL 格式：

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...

支持的图片格式：

  • image/jpeg - JPEG 格式（推荐，体积较小）
  • image/png - PNG 格式
  • image/gif - GIF 格式
  • image/webp - WebP 格式

建议

导出时建议将头像压缩为 100×100 像素以内，以减小文件体积。

完整示例 ​

群聊示例（含可选字段） ​

json
{
  "chatlab": {
    "version": "0.0.1",
    "exportedAt": 1703001600,
    "generator": "My Converter Tool",
    "description": "2024年技术交流群聊天记录备份"
  },
  "meta": {
    "name": "技术交流群",
    "platform": "wechat",
    "type": "group",
    "groupId": "38988428513",
    "groupAvatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  },
  "members": [
    {
      "platformId": "abc123",
      "accountName": "张三",
      "groupNickname": "群主-张三",
      "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    },
    {
      "platformId": "def456",
      "accountName": "李四",
      "groupNickname": "管理员",
      "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    }
  ],
  "messages": [
    {
      "sender": "abc123",
      "accountName": "张三",
      "groupNickname": "群主-张三",
      "timestamp": 1703001600,
      "type": 0,
      "content": "大家好！欢迎加入技术交流群~"
    },
    {
      "sender": "def456",
      "accountName": "李四",
      "groupNickname": "管理员",
      "timestamp": 1703001610,
      "type": 1,
      "content": "[图片: screenshot.jpg]"
    }
  ]
}

私聊示例 ​

json
{
  "chatlab": {
    "version": "0.0.1",
    "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.1","exportedAt":1703001600},"meta":{"name":"技术交流群","platform":"qq","type":"group"}}
{"_type":"member","platformId":"123456","accountName":"张三","groupNickname":"群主"}
{"_type":"member","platformId":"789012","accountName":"李四"}
{"_type":"message","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. 支持注释行：以 # 开头的行会被跳过（可用于添加备注）

注意

  • 每行必须是有效的 JSON（不能跨行）
  • 行之间用换行符 \n 分隔

版本历史 ​

版本日期变更
0.0.12025-12初始版本