hicccc77/WeFlow
1
0
Fork 0
mirror of https://github.com/hicccc77/WeFlow.git synced 2026-04-22 15:09:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: API服务支持ChatLab新版协议

Browse Source
This commit is contained in:
digua
2026-04-19 14:50:13 +08:00
parent 55885449a3
commit 0ba1067123
3 changed files with 265 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

240
docs/HTTP-API.md
View File

@@ -27,8 +27,8 @@ WeFlow 提供本地 HTTP API（已支持GET 和 POST请求），便于外部脚
- `GET|POST /api/v1/health`
- `GET|POST /api/v1/push/messages`
- `GET|POST /api/v1/messages`
- `GET|POST /api/v1/messages/new`
- `GET|POST /api/v1/sessions`
- `GET /api/v1/sessions/:id/messages` (ChatLab Pull)
- `GET|POST /api/v1/contacts`
- `GET|POST /api/v1/group-members`
- `GET|POST /api/v1/media/*`
@@ -116,21 +116,21 @@ GET /api/v1/messages
### 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `talker` | string | 是 | 会话 ID。私聊通常是对方 `wxid`，群聊是 `xxx@chatroom` |
| `limit` | number | 否 | 返回条数，默认 `100`，范围 `1~10000` |
| `offset` | number | 否 | 分页偏移，默认 `0` |
| `start` | string | 否 | 开始时间，支持 `YYYYMMDD` 或时间戳 |
| `end` | string | 否 | 结束时间，支持 `YYYYMMDD` 或时间戳 |
| `keyword` | string | 否 | 基于消息显示文本过滤 |
| `chatlab` | string | 否 | `1/true` 时输出 ChatLab 格式 |
| `format` | string | 否 | `json` 或 `chatlab` |
| `media` | string | 否 | `1/true` 时导出媒体并返回媒体地址，兼容别名 `meiti` |
| `image` | string | 否 | 在 `media=1` 时控制图片导出，兼容别名 `tupian` |
| `voice` | string | 否 | 在 `media=1` 时控制语音导出，兼容别名 `vioce` |
| `video` | string | 否 | 在 `media=1` 时控制视频导出 |
| `emoji` | string | 否 | 在 `media=1` 时控制表情导出 |
| 参数 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ----------------------------------------------------- |
| `talker` | string | 是 | 会话 ID。私聊通常是对方 `wxid`，群聊是 `xxx@chatroom` |
| `limit` | number | 否 | 返回条数，默认 `100`，范围 `1~10000` |
| `offset` | number | 否 | 分页偏移，默认 `0` |
| `start` | string | 否 | 开始时间，支持 `YYYYMMDD` 或时间戳 |
| `end` | string | 否 | 结束时间，支持 `YYYYMMDD` 或时间戳 |
| `keyword` | string | 否 | 基于消息显示文本过滤 |
| `chatlab` | string | 否 | `1/true` 时输出 ChatLab 格式 |
| `format` | string | 否 | `json` 或 `chatlab` |
| `media` | string | 否 | `1/true` 时导出媒体并返回媒体地址，兼容别名 `meiti` |
| `image` | string | 否 | 在 `media=1` 时控制图片导出，兼容别名 `tupian` |
| `voice` | string | 否 | 在 `media=1` 时控制语音导出，兼容别名 `vioce` |
| `video` | string | 否 | 在 `media=1` 时控制视频导出 |
| `emoji` | string | 否 | 在 `media=1` 时控制表情导出 |
### 示例
@@ -253,10 +253,10 @@ GET /api/v1/sessions
### 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `keyword` | string | 否 | 匹配 `username` 或 `displayName` |
| `limit` | number | 否 | 默认 `100` |
| 参数 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | -------------------------------- |
| `keyword` | string | 否 | 匹配 `username` 或 `displayName` |
| `limit` | number | 否 | 默认 `100` |
### 响应字段
@@ -288,6 +288,130 @@ GET /api/v1/sessions
---
## 4.1 获取会话列表（ChatLab 格式）
当 `format=chatlab` 时，返回 ChatLab Pull 协议兼容格式，可直接作为 ChatLab 远程数据源。
**请求**
```http
GET /api/v1/sessions?format=chatlab
```
### 参数
| 参数 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | -------------------------------- |
| `format` | string | 是 | 设为 `chatlab` |
| `keyword` | string | 否 | 匹配 `username` 或 `displayName` |
| `limit` | number | 否 | 默认 `100` |
### 响应
```json
{
"sessions": [
{
"id": "xxx@chatroom",
"name": "项目群",
"platform": "wechat",
"type": "group",
"messageCount": 58000,
"lastMessageAt": 1738713600
}
]
}
```
| 字段 | 说明 |
| --------------- | ----------------------------------- |
| `id` | 会话 ID（微信 username） |
| `name` | 会话显示名称 |
| `platform` | 固定 `wechat` |
| `type` | `group`（群聊）或 `private`（私聊） |
| `messageCount` | 消息数量（估算值，可能不精确） |
| `lastMessageAt` | 最后消息的秒级 Unix 时间戳 |
---
## 4.2 拉取会话消息（ChatLab Pull）
返回 ChatLab 标准格式的聊天数据，支持增量拉取和分页。
**请求**
```http
GET /api/v1/sessions/:id/messages
```
### 参数
| 参数 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ---------------------------------------- |
| `:id` | string | 是 | 会话 ID（Path 参数） |
| `since` | number | 否 | 秒级 Unix 时间戳，仅返回此时间之后的消息 |
| `end` | number | 否 | 秒级 Unix 时间戳，时间上界 |
| `limit` | number | 否 | 单次返回上限，默认且最大 `5000` |
| `offset` | number | 否 | 分页偏移，默认 `0` |
### 响应
返回 ChatLab 标准 JSON 格式，外加 `sync` 分页块：
```json
{
"chatlab": {
"version": "0.0.2",
"exportedAt": 1738713600,
"generator": "WeFlow"
},
"meta": {
"name": "项目群",
"platform": "wechat",
"type": "group",
"groupId": "xxx@chatroom",
"ownerId": "wxid_xxx"
},
"members": [
{
"platformId": "wxid_a",
"accountName": "张三",
"groupNickname": "产品",
"avatar": "https://example.com/avatar.jpg"
}
],
"messages": [
{
"sender": "wxid_a",
"accountName": "张三",
"timestamp": 1738713600,
"type": 0,
"content": "你好",
"platformMessageId": "123456"
}
],
"sync": {
"hasMore": true,
"nextSince": 1738713600,
"nextOffset": 5000,
"watermark": 1738714000
}
}
```
### sync 块
| 字段 | 说明 |
| ------------ | -------------------------------- |
| `hasMore` | 是否还有更多数据 |
| `nextSince` | 下次请求的 `since` 值 |
| `nextOffset` | 下次请求的 `offset` 值 |
| `watermark` | 本次拉取的时间上界（秒级时间戳） |
**ChatLab 对接方式**：在 ChatLab 设置中添加远程数据源，`baseUrl` 填 `http://127.0.0.1:5031/api/v1`，Token 填 WeFlow 中配置的 API Token。
---
## 5. 获取联系人列表
> 当使用 POST 时，请将参数放在 JSON Body 中（Content-Type: application/json）
@@ -300,10 +424,10 @@ GET /api/v1/contacts
### 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `keyword` | string | 否 | 匹配 `username`、`nickname`、`remark`、`displayName` |
| `limit` | number | 否 | 默认 `100` |
| 参数 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ---------------------------------------------------- |
| `keyword` | string | 否 | 匹配 `username`、`nickname`、`remark`、`displayName` |
| `limit` | number | 否 | 默认 `100` |
### 响应字段
@@ -353,12 +477,12 @@ GET /api/v1/group-members
### 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `chatroomId` | string | 是 | 群 ID，兼容使用 `talker` 传入 |
| `includeMessageCounts` | string | 否 | `1/true` 时附带成员发言数 |
| `withCounts` | string | 否 | `includeMessageCounts` 的别名 |
| `forceRefresh` | string | 否 | `1/true` 时跳过内存缓存强制刷新 |
| 参数 | 类型 | 必填 | 说明 |
| ---------------------- | ------ | ---- | ------------------------------- |
| `chatroomId` | string | 是 | 群 ID，兼容使用 `talker` 传入 |
| `includeMessageCounts` | string | 否 | `1/true` 时附带成员发言数 |
| `withCounts` | string | 否 | `includeMessageCounts` 的别名 |
| `forceRefresh` | string | 否 | `1/true` 时跳过内存缓存强制刷新 |
### 响应字段
@@ -443,17 +567,17 @@ GET /api/v1/sns/timeline
参数：
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `limit` | number | 否 | 返回数量，默认 20，范围 `1~200` |
| `offset` | number | 否 | 偏移量，默认 0 |
| `usernames` | string | 否 | 发布者过滤，逗号分隔，如 `wxid_a,wxid_b` |
| `keyword` | string | 否 | 关键词过滤（正文） |
| `start` | string | 否 | 开始时间，支持 `YYYYMMDD` 或秒/毫秒时间戳 |
| `end` | string | 否 | 结束时间，支持 `YYYYMMDD` 或秒/毫秒时间戳 |
| `media` | number | 否 | 是否返回可直接访问的媒体地址，默认 `1` |
| `replace` | number | 否 | `media=1` 时，是否用解析地址覆盖 `media.url/thumb`，默认 `1` |
| `inline` | number | 否 | `media=1` 时，是否内联返回 `data:` URL，默认 `0` |
| 参数 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ------------------------------------------------------------ |
| `limit` | number | 否 | 返回数量，默认 20，范围 `1~200` |
| `offset` | number | 否 | 偏移量，默认 0 |
| `usernames` | string | 否 | 发布者过滤，逗号分隔，如 `wxid_a,wxid_b` |
| `keyword` | string | 否 | 关键词过滤（正文） |
| `start` | string | 否 | 开始时间，支持 `YYYYMMDD` 或秒/毫秒时间戳 |
| `end` | string | 否 | 结束时间，支持 `YYYYMMDD` 或秒/毫秒时间戳 |
| `media` | number | 否 | 是否返回可直接访问的媒体地址，默认 `1` |
| `replace` | number | 否 | `media=1` 时，是否用解析地址覆盖 `media.url/thumb`，默认 `1` |
| `inline` | number | 否 | `media=1` 时，是否内联返回 `data:` URL，默认 `0` |
示例：
@@ -490,9 +614,9 @@ GET /api/v1/sns/export/stats
参数：
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fast` | number | 否 | `1` 使用快速统计（优先缓存） |
| 参数 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------------------- |
| `fast` | number | 否 | `1` 使用快速统计（优先缓存） |
### 7.4 朋友圈媒体代理
@@ -502,10 +626,10 @@ GET /api/v1/sns/media/proxy
参数：
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 媒体原始 URL |
| `key` | string/number | 否 | 解密 key（部分资源需要） |
| 参数 | 类型 | 必填 | 说明 |
| ----- | ------------- | ---- | ------------------------ |
| `url` | string | 是 | 媒体原始 URL |
| `key` | string/number | 否 | 解密 key（部分资源需要） |
### 7.5 导出朋友圈
@@ -572,15 +696,15 @@ curl "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/emojis/emoji_300.gif"
### 支持的 Content-Type
| 扩展名 | Content-Type |
| --- | --- |
| `.png` | `image/png` |
| 扩展名 | Content-Type |
| ---------------- | ------------ |
| `.png` | `image/png` |
| `.jpg` / `.jpeg` | `image/jpeg` |
| `.gif` | `image/gif` |
| `.webp` | `image/webp` |
| `.wav` | `audio/wav` |
| `.mp3` | `audio/mpeg` |
| `.mp4` | `video/mp4` |
| `.gif` | `image/gif` |
| `.webp` | `image/webp` |
| `.wav` | `audio/wav` |
| `.mp3` | `audio/mpeg` |
| `.mp4` | `video/mp4` |
常见错误响应：
@@ -626,8 +750,8 @@ headers = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/js
# POST 方式获取消息
messages = requests.post(
f"{BASE_URL}/api/v1/messages",
json={"talker": "xxx@chatroom", "limit": 50},
f"{BASE_URL}/api/v1/messages",
json={"talker": "xxx@chatroom", "limit": 50},
headers=headers
).json()