mirror of
https://github.com/hellodigua/ChatLab.git
synced 2026-10-26 02:04:37 +08:00
docs: fix port 5200→3110, replace platform examples, add quick-test curl
- Correct default port from 5200 to 3110 (matches DEFAULT_API_PORT in config) - Replace platform-specific example identifiers with generic ones to avoid trademark concerns; update session IDs, member IDs, and groupId format - Add a copyable quick-test curl snippet to the import protocol doc (cn + en) - Expose lastPlatformMessageId and importedAt in sessions/:id doc example - Remove brand-name references from platform field descriptions in chatlab-format.md (kept valid platform identifiers in the enum table) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
diguaandClaude Sonnet 4.6 committed
1 parent
ced4ed16bd
commit
467222b68e
8 files changed
+114
-66
No files matched your search
@@ -23,12 +23,12 @@ ChatLab 提供本地 RESTful API 服务，允许外部工具、脚本和 MCP 等
|
||||
|
||||
打开 ChatLab → 设置 → ChatLab API → 开启服务。
|
||||
|
||||
启用后会自动生成 API Token，默认监听端口 `5200`。
|
||||
启用后会自动生成 API Token，默认监听端口 `3110`。
|
||||
|
||||
### 2. 验证服务状态
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:5200/api/v1/status \
|
||||
curl http://127.0.0.1:3110/api/v1/status \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
@@ -54,7 +54,7 @@ curl http://127.0.0.1:5200/api/v1/status \
|
||||
|
||||
| 项目 | 说明 |
|
||||
| -------- | ------------------------- |
|
||||
| 基础 URL | `http://127.0.0.1:5200` |
|
||||
| 基础 URL | `http://127.0.0.1:3110` |
|
||||
| API 前缀 | `/api/v1` |
|
||||
| 认证方式 | Bearer Token |
|
||||
| 数据格式 | JSON |
|
||||
@@ -192,16 +192,16 @@ Token 可在 设置 → ChatLab API 页面查看和重新生成。
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "wechat_xxx@chatroom",
|
||||
"id": "group_abc123",
|
||||
"name": "产品讨论群",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"messageCount": 58000,
|
||||
"memberCount": 86,
|
||||
"firstTimestamp": 1609459200,
|
||||
"lastTimestamp": 1711468800,
|
||||
"lastPlatformMessageId": "msg_900000",
|
||||
"groupId": "xxx@chatroom",
|
||||
"groupId": "112233445566",
|
||||
"importedAt": 1711469900
|
||||
}
|
||||
}
|
||||
@@ -236,7 +236,7 @@ Token 可在 设置 → ChatLab API 页面查看和重新生成。
|
||||
**请求示例：**
|
||||
|
||||
```bash
|
||||
curl "http://127.0.0.1:5200/api/v1/sessions/abc123/messages?page=1&limit=50&keyword=你好" \
|
||||
curl "http://127.0.0.1:3110/api/v1/sessions/abc123/messages?page=1&limit=50&keyword=你好" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ ChatLab 定义了一套标准的聊天记录数据交换格式，用于支持多
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ------------- | ------ | ---- | -------------------------------------------------------- |
|
||||
| `name` | string | ✅ | 群名或对话名 |
|
||||
| `platform` | string | ✅ | 平台标识，如 `qq` / `wechat` / `discord` / `whatsapp` 等 |
|
||||
| `platform` | string | ✅ | 平台标识，如 `qq` / `discord` / `whatsapp` / `slack` 等 |
|
||||
| `type` | string | ✅ | 聊天类型：`group`（群聊）/ `private`（私聊） |
|
||||
| `groupId` | string | - | 群 ID（仅群聊） |
|
||||
| `groupAvatar` | string | - | 群头像（Data URL 格式） |
|
||||
@@ -253,7 +253,7 @@ https://example.com/avatars/user123.jpg
|
||||
},
|
||||
"meta": {
|
||||
"name": "技术交流群",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"groupId": "38988428513",
|
||||
"groupAvatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
|
||||
|
||||
@@ -32,7 +32,7 @@ outline: deep
|
||||
### 服务地址
|
||||
|
||||
```
|
||||
Base URL：http://<host>:<port> （桌面端默认 127.0.0.1:5200）
|
||||
Base URL：http://<host>:<port> （桌面端默认 127.0.0.1:3110）
|
||||
Prefix： /api/v1
|
||||
```
|
||||
|
||||
@@ -81,8 +81,8 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
|
||||
| 优先级 | 场景 | 推荐格式 | 示例 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1（首选） | 有平台原始 ID | `{platform}_{originalId}` | `wechat_xxx@chatroom`、`qq_123456789` |
|
||||
| 2 | 文件导入（有结构化 ID） | `{platform}_{meta.groupId}` 或 `{platform}_{对方platformId}` | `wechat_xxx@chatroom` |
|
||||
| 1（首选） | 有平台原始 ID | `{platform}_{originalId}` | `whatsapp_112233445566`、`qq_123456789` |
|
||||
| 2 | 文件导入（有结构化 ID） | `{platform}_{meta.groupId}` 或 `{platform}_{对方platformId}` | `whatsapp_112233445566` |
|
||||
| 3 | 文件导入（无结构化标识） | `file_{SHA256(文件内容)[:16]}` | `file_a1b2c3d4e5f6g7h8` |
|
||||
| 4（兜底） | 一次性导入 | `import_{UUID}` | `import_550e8400-e29b-41d4-a716-446655440000` |
|
||||
|
||||
@@ -100,6 +100,30 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
| `Idempotency-Key` | 建议 | 当前批次的唯一标识，用于重试安全。建议格式：`{sessionId}-{batchIndex}-{windowStart}` |
|
||||
| `X-Dry-Run` | 否 | 设为 `true` 时仅分析不写入，返回预估结果 |
|
||||
|
||||
### 快速测试
|
||||
|
||||
复制以下命令即可直接测试（将 `YOUR_TOKEN` 和端口替换为实际值）：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:3110/api/v1/imports/group_abc123 \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"chatlab": { "version": "0.0.2", "exportedAt": 1711468800, "generator": "test" },
|
||||
"meta": { "name": "产品讨论群", "platform": "whatsapp", "type": "group", "groupId": "112233445566" },
|
||||
"members": [
|
||||
{ "platformId": "user_a", "accountName": "张三", "roles": [{ "id": "owner" }] }
|
||||
],
|
||||
"messages": [
|
||||
{ "platformMessageId": "msg_1001", "sender": "user_a", "timestamp": 1711468800, "type": 0, "content": "Hello" }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
成功时返回 `"success": true` 和写入统计；重复调用同一 `platformMessageId` 会被去重（`duplicateCount` 增加，`writtenCount` 不变）。
|
||||
|
||||
---
|
||||
|
||||
### 请求 Body（JSON 模式）
|
||||
|
||||
```json
|
||||
@@ -111,15 +135,15 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
},
|
||||
"meta": {
|
||||
"name": "产品讨论群",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"groupId": "xxx@chatroom",
|
||||
"groupId": "112233445566",
|
||||
"groupAvatar": "data:image/jpeg;base64,...",
|
||||
"ownerId": "wxid_owner"
|
||||
"ownerId": "user_owner"
|
||||
},
|
||||
"members": [
|
||||
{
|
||||
"platformId": "wxid_a",
|
||||
"platformId": "user_a",
|
||||
"accountName": "张三",
|
||||
"groupNickname": "产品",
|
||||
"avatar": "data:image/jpeg;base64,...",
|
||||
@@ -129,7 +153,7 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
"messages": [
|
||||
{
|
||||
"platformMessageId": "msg_1001",
|
||||
"sender": "wxid_a",
|
||||
"sender": "user_a",
|
||||
"accountName": "张三",
|
||||
"groupNickname": "产品",
|
||||
"timestamp": 1711468800,
|
||||
@@ -161,10 +185,10 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
每行一个 JSON 对象，通过 `_type` 字段区分类型。行顺序：`header` → `member`（零或多行） → `message`（一或多行）。
|
||||
|
||||
```jsonl
|
||||
{"_type":"header","chatlab":{"version":"0.0.2","exportedAt":1711468800,"generator":"YourSystem/1.0"},"meta":{"name":"产品讨论群","platform":"wechat","type":"group","groupId":"xxx@chatroom"},"options":{"metaUpdateMode":"patch","memberUpdateMode":"upsert"}}
|
||||
{"_type":"member","platformId":"wxid_a","accountName":"张三","groupNickname":"产品"}
|
||||
{"_type":"message","platformMessageId":"msg_1001","sender":"wxid_a","accountName":"张三","timestamp":1711468800,"type":0,"content":"Hello"}
|
||||
{"_type":"message","platformMessageId":"msg_1002","sender":"wxid_b","accountName":"李四","timestamp":1711468860,"type":0,"content":"Hi"}
|
||||
{"_type":"header","chatlab":{"version":"0.0.2","exportedAt":1711468800,"generator":"YourSystem/1.0"},"meta":{"name":"产品讨论群","platform":"telegram","type":"group","groupId":"112233445566"},"options":{"metaUpdateMode":"patch","memberUpdateMode":"upsert"}}
|
||||
{"_type":"member","platformId":"user_a","accountName":"张三","groupNickname":"产品"}
|
||||
{"_type":"message","platformMessageId":"msg_1001","sender":"user_a","accountName":"张三","timestamp":1711468800,"type":0,"content":"Hello"}
|
||||
{"_type":"message","platformMessageId":"msg_1002","sender":"user_b","accountName":"李四","timestamp":1711468860,"type":0,"content":"Hi"}
|
||||
```
|
||||
|
||||
### 各块携带规则
|
||||
@@ -231,7 +255,7 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| --------------- | ------ | ---- | -------------------------------------- |
|
||||
| `platformId` | string | 是 | 成员在平台的唯一标识（QQ号、微信ID等） |
|
||||
| `platformId` | string | 是 | 成员在平台的唯一标识（QQ号、用户ID等） |
|
||||
| `accountName` | string | 建议 | 账号名称（不随群变化的原始昵称） |
|
||||
| `groupNickname` | string | 否 | 群内专属昵称 |
|
||||
| `avatar` | string | 否 | 头像，base64 Data URL 或网络 URL |
|
||||
@@ -264,7 +288,7 @@ application/x-ndjson # JSONL 流式（无大小限制）
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"sessionId": "wechat_xxx@chatroom",
|
||||
"sessionId": "group_abc123",
|
||||
"created": false,
|
||||
"batch": {
|
||||
"receivedCount": 5000,
|
||||
@@ -351,7 +375,7 @@ ChatLab 不为调用方维护游标。推荐结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionId": "wechat_xxx@chatroom",
|
||||
"sessionId": "group_abc123",
|
||||
"lastSyncedTimestamp": 1711468800,
|
||||
"lastSyncedMessageId": "msg_900000"
|
||||
}
|
||||
@@ -373,19 +397,19 @@ ChatLab 不为调用方维护游标。推荐结构：
|
||||
1. 准备全量聊天数据，按时间顺序切分为 N 批（每批 ≤5000 条）
|
||||
|
||||
2. 第一批请求：
|
||||
POST /api/v1/imports/wechat_xxx@chatroom
|
||||
POST /api/v1/imports/group_abc123
|
||||
Body: { chatlab, meta, members, messages }
|
||||
→ 响应 created: true，会话创建成功
|
||||
|
||||
3. 第 2~N 批请求：
|
||||
POST /api/v1/imports/wechat_xxx@chatroom
|
||||
POST /api/v1/imports/group_abc123
|
||||
Body: { messages }
|
||||
Idempotency-Key: {sessionId}-{batchIndex}-{windowStart}
|
||||
|
||||
4. 每批成功后记录游标；失败用相同 Idempotency-Key 重试
|
||||
|
||||
5. 全部批次完成后对账：
|
||||
GET /api/v1/sessions/wechat_xxx@chatroom
|
||||
GET /api/v1/sessions/group_abc123
|
||||
→ 校验 totalCount、firstTimestamp、lastTimestamp
|
||||
```
|
||||
|
||||
|
||||
@@ -70,18 +70,18 @@ Accept: application/json
|
||||
{
|
||||
"sessions": [
|
||||
{
|
||||
"id": "xxx@chatroom",
|
||||
"id": "112233445566",
|
||||
"name": "产品讨论群",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"messageCount": 58000,
|
||||
"memberCount": 86,
|
||||
"lastMessageAt": 1711468800
|
||||
},
|
||||
{
|
||||
"id": "wxid_friend_a",
|
||||
"id": "user_a",
|
||||
"name": "张三",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "private",
|
||||
"messageCount": 1200,
|
||||
"memberCount": 2,
|
||||
@@ -169,7 +169,7 @@ Accept: application/json
|
||||
```json
|
||||
{
|
||||
"chatlab": { "version": "0.0.2", "exportedAt": 1711468800 },
|
||||
"meta": { "name": "产品讨论群", "platform": "wechat", "type": "group" },
|
||||
"meta": { "name": "产品讨论群", "platform": "whatsapp", "type": "group" },
|
||||
"members": [ ... ],
|
||||
"messages": [ ... ],
|
||||
"sync": {
|
||||
@@ -263,7 +263,7 @@ Accept: text/event-stream
|
||||
|
||||
```
|
||||
event: message.new
|
||||
data: {"eventId":"evt_001","sessionId":"xxx@chatroom","timestamp":1711468800}
|
||||
data: {"eventId":"evt_001","sessionId":"112233445566","timestamp":1711468800}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|
||||
@@ -8,12 +8,12 @@ ChatLab provides a local RESTful API service that allows external tools, scripts
|
||||
|
||||
Open ChatLab → Settings → ChatLab API → Enable Service.
|
||||
|
||||
Once enabled, an API Token is automatically generated. The default port is `5200`.
|
||||
Once enabled, an API Token is automatically generated. The default port is `3110`.
|
||||
|
||||
### 2. Verify Service Status
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:5200/api/v1/status \
|
||||
curl http://127.0.0.1:3110/api/v1/status \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
@@ -39,7 +39,7 @@ Response example:
|
||||
|
||||
| Item | Description |
|
||||
| -------------- | ---------------------------- |
|
||||
| Base URL | `http://127.0.0.1:5200` |
|
||||
| Base URL | `http://127.0.0.1:3110` |
|
||||
| API Prefix | `/api/v1` |
|
||||
| Authentication | Bearer Token |
|
||||
| Data Format | JSON |
|
||||
@@ -150,7 +150,7 @@ Get all imported sessions.
|
||||
{
|
||||
"id": "session_abc123",
|
||||
"name": "Tech Discussion Group",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"messageCount": 58000,
|
||||
"memberCount": 120
|
||||
@@ -192,7 +192,7 @@ Query messages from a specific session with pagination and filtering support.
|
||||
**Request example:**
|
||||
|
||||
```bash
|
||||
curl "http://127.0.0.1:5200/api/v1/sessions/abc123/messages?page=1&limit=50&keyword=hello" \
|
||||
curl "http://127.0.0.1:3110/api/v1/sessions/abc123/messages?page=1&limit=50&keyword=hello" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
@@ -321,7 +321,7 @@ Export complete session data in [ChatLab Format](./chatlab-format.md) JSON.
|
||||
},
|
||||
"meta": {
|
||||
"name": "Tech Discussion Group",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group"
|
||||
},
|
||||
"members": [...],
|
||||
@@ -346,7 +346,7 @@ Import chat records into ChatLab, **creating a new session**.
|
||||
#### JSON Mode Example
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:5200/api/v1/import \
|
||||
curl -X POST http://127.0.0.1:3110/api/v1/import \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
@@ -377,7 +377,7 @@ curl -X POST http://127.0.0.1:5200/api/v1/import \
|
||||
#### JSONL Mode Example
|
||||
|
||||
```bash
|
||||
cat data.jsonl | curl -X POST http://127.0.0.1:5200/api/v1/import \
|
||||
cat data.jsonl | curl -X POST http://127.0.0.1:3110/api/v1/import \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/x-ndjson" \
|
||||
--data-binary @-
|
||||
|
||||
@@ -83,7 +83,7 @@ Here's a **minimal** ChatLab format example with only required fields:
|
||||
| Field | Type | Required | Description |
|
||||
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
|
||||
| `name` | string | ✅ | Group name or conversation name |
|
||||
| `platform` | string | ✅ | Platform identifier: `qq` / `wechat` / `discord` / `whatsapp`, etc. |
|
||||
| `platform` | string | ✅ | Platform identifier: `qq` / `discord` / `whatsapp` / `slack`, etc. |
|
||||
| `type` | string | ✅ | Chat type: `group` / `private` |
|
||||
| `groupId` | string | - | Group ID (group chat only) |
|
||||
| `groupAvatar` | string | - | Group avatar (Data URL format) |
|
||||
@@ -184,7 +184,7 @@ When exporting, we recommend compressing avatars to 100×100 pixels or less to r
|
||||
},
|
||||
"meta": {
|
||||
"name": "Tech Exchange Group",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"groupId": "38988428513",
|
||||
"groupAvatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
|
||||
|
||||
@@ -32,7 +32,7 @@ Both modes share the same underlying import pipeline (deduplication, meta/member
|
||||
### Base URL
|
||||
|
||||
```
|
||||
Base URL: http://<host>:<port> (desktop default: 127.0.0.1:5200)
|
||||
Base URL: http://<host>:<port> (desktop default: 127.0.0.1:3110)
|
||||
Prefix: /api/v1
|
||||
```
|
||||
|
||||
@@ -81,8 +81,8 @@ For query endpoint details, see [ChatLab API](./chatlab-api.md).
|
||||
|
||||
| Priority | Scenario | Recommended Format | Example |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 (preferred) | Platform-native ID available | `{platform}_{originalId}` | `wechat_xxx@chatroom`, `qq_123456789` |
|
||||
| 2 | File import (structured ID available) | `{platform}_{meta.groupId}` or `{platform}_{platformId}` | `wechat_xxx@chatroom` |
|
||||
| 1 (preferred) | Platform-native ID available | `{platform}_{originalId}` | `whatsapp_112233445566`, `qq_123456789` |
|
||||
| 2 | File import (structured ID available) | `{platform}_{meta.groupId}` or `{platform}_{platformId}` | `whatsapp_112233445566` |
|
||||
| 3 | File import (no structured identifier) | `file_{SHA256(content)[:16]}` | `file_a1b2c3d4e5f6g7h8` |
|
||||
| 4 (fallback) | One-off import | `import_{UUID}` | `import_550e8400-e29b-41d4-a716-446655440000` |
|
||||
|
||||
@@ -100,6 +100,30 @@ For query endpoint details, see [ChatLab API](./chatlab-api.md).
|
||||
| `Idempotency-Key` | Recommended | Unique identifier for the current batch, for safe retries. Suggested format: `{sessionId}-{batchIndex}-{windowStart}` |
|
||||
| `X-Dry-Run` | No | Set to `true` to analyze without writing; returns estimated results |
|
||||
|
||||
### Quick Test
|
||||
|
||||
Copy the command below to test immediately (replace `YOUR_TOKEN` and the port with your actual values):
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:3110/api/v1/imports/group_abc123 \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"chatlab": { "version": "0.0.2", "exportedAt": 1711468800, "generator": "test" },
|
||||
"meta": { "name": "Product Discussion", "platform": "whatsapp", "type": "group", "groupId": "112233445566" },
|
||||
"members": [
|
||||
{ "platformId": "user_a", "accountName": "Alice", "roles": [{ "id": "owner" }] }
|
||||
],
|
||||
"messages": [
|
||||
{ "platformMessageId": "msg_1001", "sender": "user_a", "timestamp": 1711468800, "type": 0, "content": "Hello" }
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
A successful response returns `"success": true` with write statistics. Repeating the same `platformMessageId` is deduplicated — `duplicateCount` increases while `writtenCount` stays the same.
|
||||
|
||||
---
|
||||
|
||||
### Request Body (JSON)
|
||||
|
||||
```json
|
||||
@@ -111,15 +135,15 @@ For query endpoint details, see [ChatLab API](./chatlab-api.md).
|
||||
},
|
||||
"meta": {
|
||||
"name": "Product Discussion",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"groupId": "xxx@chatroom",
|
||||
"groupId": "112233445566",
|
||||
"groupAvatar": "data:image/jpeg;base64,...",
|
||||
"ownerId": "wxid_owner"
|
||||
"ownerId": "user_owner"
|
||||
},
|
||||
"members": [
|
||||
{
|
||||
"platformId": "wxid_a",
|
||||
"platformId": "user_a",
|
||||
"accountName": "Alice",
|
||||
"groupNickname": "Product",
|
||||
"avatar": "data:image/jpeg;base64,...",
|
||||
@@ -129,7 +153,7 @@ For query endpoint details, see [ChatLab API](./chatlab-api.md).
|
||||
"messages": [
|
||||
{
|
||||
"platformMessageId": "msg_1001",
|
||||
"sender": "wxid_a",
|
||||
"sender": "user_a",
|
||||
"accountName": "Alice",
|
||||
"groupNickname": "Product",
|
||||
"timestamp": 1711468800,
|
||||
@@ -161,10 +185,10 @@ When backfilling historical data, pass `"metaUpdateMode": "none"` to prevent old
|
||||
One JSON object per line, distinguished by the `_type` field. Line order: `header` → `member` (zero or more) → `message` (one or more).
|
||||
|
||||
```jsonl
|
||||
{"_type":"header","chatlab":{"version":"0.0.2","exportedAt":1711468800,"generator":"YourSystem/1.0"},"meta":{"name":"Product Discussion","platform":"wechat","type":"group","groupId":"xxx@chatroom"},"options":{"metaUpdateMode":"patch","memberUpdateMode":"upsert"}}
|
||||
{"_type":"member","platformId":"wxid_a","accountName":"Alice","groupNickname":"Product"}
|
||||
{"_type":"message","platformMessageId":"msg_1001","sender":"wxid_a","accountName":"Alice","timestamp":1711468800,"type":0,"content":"Hello"}
|
||||
{"_type":"message","platformMessageId":"msg_1002","sender":"wxid_b","accountName":"Bob","timestamp":1711468860,"type":0,"content":"Hi"}
|
||||
{"_type":"header","chatlab":{"version":"0.0.2","exportedAt":1711468800,"generator":"YourSystem/1.0"},"meta":{"name":"Product Discussion","platform":"whatsapp","type":"group","groupId":"112233445566"},"options":{"metaUpdateMode":"patch","memberUpdateMode":"upsert"}}
|
||||
{"_type":"member","platformId":"user_a","accountName":"Alice","groupNickname":"Product"}
|
||||
{"_type":"message","platformMessageId":"msg_1001","sender":"user_a","accountName":"Alice","timestamp":1711468800,"type":0,"content":"Hello"}
|
||||
{"_type":"message","platformMessageId":"msg_1002","sender":"user_b","accountName":"Bob","timestamp":1711468860,"type":0,"content":"Hi"}
|
||||
```
|
||||
|
||||
### Block Requirements
|
||||
@@ -264,7 +288,7 @@ If your platform isn't listed, use a lowercase identifier (e.g. `signal`, `matri
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"sessionId": "wechat_xxx@chatroom",
|
||||
"sessionId": "group_abc123",
|
||||
"created": false,
|
||||
"batch": {
|
||||
"receivedCount": 5000,
|
||||
@@ -351,7 +375,7 @@ ChatLab does not maintain cursors for callers. Recommended structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionId": "wechat_xxx@chatroom",
|
||||
"sessionId": "group_abc123",
|
||||
"lastSyncedTimestamp": 1711468800,
|
||||
"lastSyncedMessageId": "msg_900000"
|
||||
}
|
||||
@@ -373,19 +397,19 @@ Current version: **only one import task is allowed at a time per session**. Conc
|
||||
1. Prepare all chat data and split into N batches in chronological order (≤5,000 messages each)
|
||||
|
||||
2. First batch:
|
||||
POST /api/v1/imports/wechat_xxx@chatroom
|
||||
POST /api/v1/imports/group_abc123
|
||||
Body: { chatlab, meta, members, messages }
|
||||
→ Response: created: true, session created
|
||||
|
||||
3. Batches 2–N:
|
||||
POST /api/v1/imports/wechat_xxx@chatroom
|
||||
POST /api/v1/imports/group_abc123
|
||||
Body: { messages }
|
||||
Idempotency-Key: {sessionId}-{batchIndex}-{windowStart}
|
||||
|
||||
4. After each batch, record cursor; on failure, retry with the same Idempotency-Key
|
||||
|
||||
5. After all batches, reconcile:
|
||||
GET /api/v1/sessions/wechat_xxx@chatroom
|
||||
GET /api/v1/sessions/group_abc123
|
||||
→ Verify totalCount, firstTimestamp, lastTimestamp
|
||||
```
|
||||
|
||||
|
||||
@@ -70,18 +70,18 @@ Accept: application/json
|
||||
{
|
||||
"sessions": [
|
||||
{
|
||||
"id": "xxx@chatroom",
|
||||
"id": "112233445566",
|
||||
"name": "Product Discussion",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "group",
|
||||
"messageCount": 58000,
|
||||
"memberCount": 86,
|
||||
"lastMessageAt": 1711468800
|
||||
},
|
||||
{
|
||||
"id": "wxid_friend_a",
|
||||
"id": "user_a",
|
||||
"name": "Alice",
|
||||
"platform": "wechat",
|
||||
"platform": "whatsapp",
|
||||
"type": "private",
|
||||
"messageCount": 1200,
|
||||
"memberCount": 2,
|
||||
@@ -169,7 +169,7 @@ The response is standard [ChatLab Format](./chatlab-format.md) (JSON or JSONL),
|
||||
```json
|
||||
{
|
||||
"chatlab": { "version": "0.0.2", "exportedAt": 1711468800 },
|
||||
"meta": { "name": "Product Discussion", "platform": "wechat", "type": "group" },
|
||||
"meta": { "name": "Product Discussion", "platform": "whatsapp", "type": "group" },
|
||||
"members": [ ... ],
|
||||
"messages": [ ... ],
|
||||
"sync": {
|
||||
@@ -263,7 +263,7 @@ Accept: text/event-stream
|
||||
|
||||
```
|
||||
event: message.new
|
||||
data: {"eventId":"evt_001","sessionId":"xxx@chatroom","timestamp":1711468800}
|
||||
data: {"eventId":"evt_001","sessionId":"112233445566","timestamp":1711468800}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|
||||
Reference in new issue
Block a user