聊天数据交换标准化格式

v0.0.2

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

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

注意

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

概述

支持的文件格式

格式	扩展名	适用场景
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 关联，可查询被回复消息的内容和发送者
仅当消息是回复类型时才有意义
如果平台不支持或数据不包含回复关系，可省略此字段

消息类型对照表

提示

若您的聊天记录中有其他特殊类型需要支持，请提交 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

建议

如果需要离线使用或长期存档，推荐使用 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":"[图片]"}

解析规则

第一行必须是 header：包含 chatlab 版本和 meta 元信息
成员行在消息之前：可选，如果省略，成员信息会从消息中自动收集
消息按时间顺序排列：建议按 timestamp 升序排列
每行独立完整：单行解析错误可跳过继续处理
支持注释行：以 # 开头的行会被跳过（可用于添加备注）

注意

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

版本历史

版本	日期	变更
0.0.1	2025-12-22	初始版本
0.0.2	2026-01-09	新增 roles、ownerId、platformMessageId、replyToMessageId 字段；新增 JSONL 格式

聊天数据交换标准化格式 ​

概述 ​

支持的文件格式 ​

格式对比 ​

快速说明 ​

JSON 格式详细说明 ​

文件头 (chatlab) ​

元信息 (meta) ​

成员 (members) ​

角色 (roles) ​

消息 (messages) ​

消息 ID 与回复关系说明 ​

消息类型对照表 ​

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

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

系统消息类型 (80+) ​

头像格式说明 ​

1. Data URL ​

2. 网络 URL ​

完整示例 ​

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

私聊示例 ​

JSONL 流式格式 ​

格式特点 ​

行类型说明 ​

完整示例 ​

解析规则 ​

版本历史 ​

聊天数据交换标准化格式

概述

支持的文件格式

格式对比

快速说明

JSON 格式详细说明

文件头 (chatlab)

元信息 (meta)

成员 (members)

角色 (roles)

消息 (messages)

消息 ID 与回复关系说明

消息类型对照表

基础消息类型 (0-19)

交互消息类型 (20-39)

系统消息类型 (80+)

头像格式说明

1. Data URL

2. 网络 URL

完整示例

群聊示例（含可选字段）

私聊示例

JSONL 流式格式

格式特点

行类型说明

完整示例

解析规则

版本历史