新增了一个消息推送

docs/HTTP-API.md

@@ -1,6 +1,6 @@
-# WeFlow HTTP API 文档
+# WeFlow HTTP API / Push 文档
 
-WeFlow 提供本地 HTTP API，便于外部脚本或工具读取聊天记录、会话、联系人、群成员和导出的媒体文件。
+WeFlow 提供本地 HTTP API，便于外部脚本或工具读取聊天记录、会话、联系人、群成员和导出的媒体文件；也支持在检测到新消息后通过固定 SSE 地址主动推送消息事件。
 
 ## 启用方式
 
@@ -9,12 +9,15 @@ WeFlow 提供本地 HTTP API，便于外部脚本或工具读取聊天记录、
 - 默认监听地址：`127.0.0.1`
 - 默认端口：`5031`
 - 基础地址：`http://127.0.0.1:5031`
+- 可选开启 `主动推送`，检测到新收到的消息后会通过 `GET /api/v1/push/messages` 推送给 SSE 订阅端
 
 ## 接口列表
 
 - `GET /health`
 - `GET /api/v1/health`
+- `GET /api/v1/push/messages`
 - `GET /api/v1/messages`
+- `GET /api/v1/messages/new`
 - `GET /api/v1/sessions`
 - `GET /api/v1/contacts`
 - `GET /api/v1/group-members`
@@ -46,7 +49,50 @@ GET /api/v1/health
 
 ---
 
-## 2. 获取消息
+## 2. 主动推送
+
+通过 SSE 长连接接收新消息事件，端口与 HTTP API 共用。
+
+**请求**
+
+```http
+GET /api/v1/push/messages
+```
+
+### 说明
+
+- 需要先在设置页开启 `HTTP API 服务`
+- 同时需要开启 `主动推送`
+- 响应类型为 `text/event-stream`
+- 新消息事件名固定为 `message.new`
+- 建议接收端按 `messageKey` 去重
+
+### 事件字段
+
+- `event`
+- `sessionId`
+- `messageKey`
+- `avatarUrl`
+- `sourceName`
+- `groupName`（仅群聊）
+- `content`
+
+### 示例
+
+```bash
+curl -N "http://127.0.0.1:5031/api/v1/push/messages"
+```
+
+示例事件：
+
+```text
+event: message.new
+data: {"event":"message.new","sessionId":"xxx@chatroom","messageKey":"server:123456:1760000123:1760000123000:321:wxid_member:1","avatarUrl":"https://example.com/group.jpg","sourceName":"李四","groupName":"项目群","content":"[图片]"}
+```
+
+---
+
+## 3. 获取消息
 
 读取指定会话的消息，支持原始 JSON 和 ChatLab 格式。
 
@@ -183,7 +229,7 @@ curl "http://127.0.0.1:5031/api/v1/messages?talker=xxx@chatroom&media=1&image=1&
 
 ---
 
-## 3. 获取会话列表
+## 4. 获取会话列表
 
 **请求**
 
@@ -228,7 +274,7 @@ GET /api/v1/sessions
 
 ---
 
-## 4. 获取联系人列表
+## 5. 获取联系人列表
 
 **请求**
 
@@ -277,7 +323,7 @@ GET /api/v1/contacts
 
 ---
 
-## 5. 获取群成员列表
+## 6. 获取群成员列表
 
 返回群成员的 `wxid`、群昵称、备注、微信号等信息。
 
@@ -369,7 +415,7 @@ curl "http://127.0.0.1:5031/api/v1/group-members?chatroomId=xxx@chatroom&include
 
 ---
 
-## 6. 访问导出媒体
+## 7. 访问导出媒体
 
 通过消息接口启用 `media=1` 后，接口会先把图片、语音、视频、表情导出到本地缓存目录，再返回可访问的 HTTP 地址。
 
@@ -410,7 +456,7 @@ curl "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/emojis/emoji_300.gif"
 
 ---
 
-## 7. 使用示例
+## 8. 使用示例
 
 ### PowerShell
 
@@ -453,7 +499,7 @@ print(members)
 
 ---
 
-## 8. 注意事项
+## 9. 注意事项
 
 1. API 仅监听本机 `127.0.0.1`，不对外网开放。
 2. 使用前需要先在 WeFlow 中完成数据库连接。