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