github/ChatLab
1
0
Fork 0
mirror of https://github.com/hellodigua/ChatLab.git synced 2026-05-28 01:57:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 新增繁体中文文档

Browse Source
This commit is contained in:
digua
2026-04-13 21:56:30 +08:00
parent 3c022b069a
commit c69dcdffbb
24 changed files with 1704 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tw/chatlab-format.md
+389
View File
@@ -0,0 +1,389 @@
# 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 格式 |