@core-workspace/infoflow-openclaw-plugin 2026.3.8

package/docs/architecture-data-flow.md

@@ -0,0 +1,429 @@
+# Infoflow OpenClaw 插件架构说明
+
+## 一、整体分层
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     如流服务端 / WS Gateway                      │
+└──────────────────────┬────────────────────┬──────────────────────┘
+                       │ HTTP POST          │ WebSocket 长连接
+              ─────────▼─────────  ─────────▼─────────
+             │  Webhook 接入层   │  │  WebSocket 接入层 │   ← 【区分层】
+             │  webhook-parser  │  │   ws-receiver    │
+              ─────────┬─────── ──────────┬────────────
+                       │                  │
+                        ▼   汇合点（复用）  ▼
+              ┌──────────────────────────────────────┐
+              │         统一消息处理层                 │   ← 【复用层】
+              │       message-handler.ts             │
+              │  (私聊/群聊路由、权限、replyMode 门控)  │
+              └──────────────────┬───────────────────┘
+                                 │
+              ┌──────────────────▼───────────────────┐
+              │         LLM 调度层（OpenClaw core）    │   ← 【复用层】
+              │  dispatchReplyWithBufferedBlock...    │
+              └──────────────────┬───────────────────┘
+                                 │
+              ┌──────────────────▼───────────────────┐
+              │         统一发送层                    │   ← 【复用层】
+              │  reply-dispatcher.ts → send.ts       │
+              │  (文本分片、@处理、引用回复、HTTP POST) │
+              └──────────────────────────────────────┘
+```
+
+---
+
+## 二、Webhook vs WebSocket：区别在哪里
+
+### 区别点（仅在接入层）
+
+| 对比项 | Webhook (`webhook-parser.ts`) | WebSocket (`ws-receiver.ts`) |
+|--------|-------------------------------|-------------------------------|
+| 连接方向 | 如流服务器主动 POST 到本机 | 插件主动连接 WS Gateway |
+| 私聊消息格式 | form-urlencoded + `Encrypt` 密文 | SDK 归一化后直接拿到明文 |
+| 群聊消息格式 | text/plain，rawBody 是 AES 密文 | SDK 归一化后的 JSON body |
+| 需要解密 | ✅ AES-ECB 解密（encodingAESKey） | ❌ 不需要，WS 握手时已鉴权 |
+| echostr 验签 | ✅ 首次验签（MD5） | ❌ 无 |
+| 图片字段来源 | 解密后 JSON 里的 `PicUrl` | SDK bug 丢失字段，需 monkey-patch `originalMessage.PicUrl` |
+| 响应方式 | fire-and-forget，立即返回 200 | async/await，事件回调中处理 |
+
+**两者汇合在同一个函数**：
+- `handlePrivateChatMessage({ cfg, msgData, accountId })`
+- `handleGroupChatMessage({ cfg, msgData, accountId })`
+
+两条路径都将各自的消息格式整形为统一的 `msgData` 结构后，调用同一入口。
+
+---
+
+## 三、三种消息类型的完整收发流程
+
+### 3.1 普通文本消息
+
+#### 收（以群聊为例）
+
+**Webhook 路径**：
+```
+POST /webhook/infoflow
+Content-Type: text/plain
+Body: <AES密文>
+    │
+    ▼ webhook-parser.ts: tryDecryptAndDispatch
+AES-ECB 解密 → JSON.parse
+{
+  eventtype: "MESSAGE_RECEIVE",
+  groupid: "12600364",
+  message: {
+    header: { fromuserid: "zhangsan", msgtype: "mixed", at: { atrobotids: [1234] } },
+    body: [
+      { type: "AT", name: "龙虾", robotid: 1234 },
+      { type: "TEXT", content: "今天天气怎么样" }
+    ]
+  }
+}
+    │
+    ▼ handleGroupChatMessage
+```
+
+**WebSocket 路径**：
+```
+WS event: "group.text"
+event.data = {
+  chatType: "group",
+  msgType: "mixed",
+  fromUserId: "zhangsan",
+  groupId: "12600364",
+  body: [
+    { type: "AT", name: "龙虾", robotid: 1234 },
+    { type: "TEXT", content: "今天天气怎么样" }
+  ],
+  originalMessage: { header: { ... } }
+}
+    │
+    ▼ ws-receiver.ts: handleGroupEvent 重组为同样的 msgData 结构
+    ▼ handleGroupChatMessage  ← 与 webhook 走同一函数
+```
+
+**之后（两条路径完全一致）**：
+```
+message-handler.ts:
+  1. 提取 bodyItems → mes = "今天天气怎么样"
+  2. checkBotMentioned(bodyItems, "龙虾") → true
+  3. replyMode="mention-only"，@了机器人，触发 LLM
+  4. buildAgentMediaPayload(无图片) → ctxPayload
+  5. dispatchReplyWithBufferedBlock → LLM 推理
+
+reply-dispatcher.ts:
+  6. LLM 输出 → chunkText (4000字切片)
+  7. sendInfoflowMessage({ to: "group:12600364", contents: [{ type: "markdown", content: "..." }] })
+
+send.ts:
+  8. POST ${apiHost}/api/v1/robot/msg/groupmsgsend
+     body: { groupid, robotid, contents: [{ type: "markdown", content: "..." }] }
+```
+
+---
+
+### 3.2 Markdown 格式消息
+
+Markdown 与纯文本的**收**流程完全相同，区别只在**发送侧**配置：
+
+**配置决定格式**（`openclaw.json`）：
+```json
+"channels": {
+  "infoflow": {
+    "dmMessageFormat": "markdown",
+    "groupMessageFormat": "text"
+  }
+}
+```
+
+**发送时（message-handler.ts → reply-dispatcher.ts）**：
+```typescript
+// message-handler.ts 中：
+messageFormat: isGroup
+  ? (account.config.groupMessageFormat ?? "text")   // "text"
+  : (account.config.dmMessageFormat ?? "text"),      // "markdown"
+```
+
+**群聊发送（text 格式）**：
+```
+send.ts: sendInfoflowGroupMessage
+POST /api/v1/robot/msg/groupmsgsend
+{
+  "groupid": "12600364",
+  "robotid": 1234,
+  "contents": [
+    { "type": "text", "content": "今天天气晴，适合出门。" }
+  ]
+}
+```
+
+**私聊发送（markdown 格式）**：
+```
+send.ts: sendInfoflowPrivateMessage
+POST /api/v1/app/message/send
+{
+  "tousers": ["zhangsan"],
+  "appid": "appKey",
+  "msgtype": "markdown",
+  "markdown": { "content": "## 天气预报\n今天**晴**，气温 25°C" }
+}
+```
+
+---
+
+### 3.3 图片消息
+
+图片消息在 webhook 和 websocket 两条路径上有明显差异：
+
+#### 收图片（私聊）
+
+**Webhook 路径**：
+```
+POST /webhook/infoflow（私聊，form-urlencoded）
+AES 解密后 JSON：
+{
+  "MsgType": "image",
+  "FromUserId": "zhangsan",
+  "PicUrl": "https://infoflow.baidu.com/xxxxx/image.jpg",
+  "MsgId": "12345678",
+  "CreateTime": "1234567890"
+}
+    │
+    ▼ handlePrivateChatMessage
+```
+
+**WebSocket 路径（存在 SDK Bug）**：
+```
+WS event: "private.image"
+SDK 调用 normalizePrivateMessage(payload)
+  ← SDK Bug: 丢失了 PicUrl / MsgId！
+
+  → 插件 Monkey-patch 解决：
+  dispatcher.normalizePrivateMessage = function(payload) {
+    const normalized = original(payload);
+    normalized.originalMessage = payload;  // 保留原始 payload
+    return normalized;
+  }
+    │
+    ▼ ws-receiver.ts: handlePrivateEvent
+msgData = {
+  FromUserId: data.fromUserId,
+  MsgType: "image",
+  PicUrl: data.picUrl ?? originalMessage.PicUrl,   ← 从 originalMessage 兜底
+  MsgId: data.msgId ?? originalMessage.MsgId,
+  ...
+}
+    │
+    ▼ handlePrivateChatMessage  ← 与 webhook 走同一函数
+```
+
+**之后（两条路径完全一致，图片下载 + 注入 LLM）**：
+```
+message-handler.ts:
+  1. MsgType === "image"，有 PicUrl
+  2. fetchRemoteMedia(PicUrl, allowedHostnames: ["infoflow.baidu.com"])
+     ← SSRF 防护：只允许如流域名
+  3. saveMediaBuffer → 写入临时文件
+  4. buildAgentMediaPayload([{ path: tmpFile, contentType: "image/jpeg" }])
+     → { MediaPath, MediaPaths, MediaTypes }
+  5. ctxPayload 携带 mediaPayload → LLM 可看到图片内容（多模态）
+  6. LLM 识别图片 → 回复文字结果
+```
+
+#### 收图片（群聊）
+
+```
+群消息 body item 中有 IMAGE 类型：
+body: [
+  { type: "AT", name: "龙虾", robotid: 1234 },
+  { type: "IMAGE", downloadurl: "https://infoflow.baidu.com/xxx.jpg" }
+]
+    │
+    ▼ message-handler.ts: 遍历 bodyItems
+imageItems = body.filter(item => item.type === "IMAGE")
+imageItems.forEach(item => downloadUrl = item.downloadurl)
+    │ 下载 + 注入（与私聊图片处理相同）
+```
+
+#### 发图片（LLM 调用工具 `infoflow_send`）
+
+```
+tools/index.ts: infoflow_send 工具（LLM function calling）
+{
+  "to": "group:12600364",
+  "message": "![图表](https://xxx.com/chart.png)"
+}
+  │ OR 通过 outbound/media.ts 发送原生图片
+  ▼
+send.ts: sendInfoflowGroupMessage
+  - LINK/IMAGE 类型 contents 必须单独发送（API 限制）
+  - contents: [{ type: "image", url: "https://..." }]
+
+POST /api/v1/robot/msg/groupmsgsend
+{
+  "groupid": "12600364",
+  "robotid": 1234,
+  "contents": [{ "type": "image", "url": "https://..." }]
+}
+```
+
+---
+
+## 四、如流 → OpenClaw（入方向）完整路线
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          如流服务端                                  │
+└──────────────────┬────────────────────────────┬──────────────────────┘
+                   │ HTTP POST /webhook/infoflow │ WebSocket 长连接推送
+                   │                            │
+      ─────────────▼──────────           ───────▼────────────
+     │    【适配层 ①】Webhook   │         │  【适配层 ①】WebSocket │
+     │    monitor.ts           │         │   ws-receiver.ts       │
+     │  - 路由注册与分发         │         │  - SDK WSClient 封装    │
+     │  - loadRawBody (≤20MB)  │         │  - 监听 group.* /       │
+     │  - 405/413 错误处理      │         │    private.* 事件       │
+      ─────────────┬──────────           ───────┬────────────
+                   │                            │
+      ─────────────▼──────────                  │
+     │    【适配层 ②】解密解析   │                │
+     │    webhook-parser.ts    │                │
+     │  私聊:                   │                │
+     │  form-urlencoded        │                │
+     │  → JSON.parse(Encrypt)  │                │
+     │  → AES-ECB 解密          │                │
+     │  群聊:                   │         ───────▼────────────
+     │  text/plain (密文)       │        │  【适配层 ②】格式整形  │
+     │  → AES-ECB 解密          │        │   ws-receiver.ts      │
+     │  echostr → MD5 验签      │        │  重组成统一 msgData:    │
+      ─────────────┬──────────  │        │  { FromUserId,         │
+                   │            │        │    groupid,            │
+                   │            │        │    message.body,       │
+                   │            │        │    PicUrl(兜底fix), .. }│
+                   │             ────────┘                │
+                   │                                      │
+                   └──────────────┬───────────────────────┘
+                                  │ 统一 msgData 结构（两路完全对齐）
+                                  │
+                    ══════════════▼══════════════════════════
+                    ║         【复用层 A】去重过滤             ║
+                    ║         isDuplicateMessage()           ║
+                    ║   (webhook-parser 定义，ws-receiver 复用)║
+                    ║   key: messageid / clientmsgid /       ║
+                    ║        fromuserid_groupid_ctime        ║
+                    ╚══════════════╤══════════════════════════╝
+                                   │
+                    ══════════════▼══════════════════════════
+                    ║        【复用层 B】统一消息处理           ║
+                    ║        message-handler.ts              ║
+                    ║                                        ║
+                    ║  handlePrivateChatMessage              ║
+                    ║    ↓ 字段提取（兼容大小写变体）            ║
+                    ║    ↓ dmPolicy 权限校验                  ║
+                    ║    ↓ MsgType=image → 下载图片            ║
+                    ║                                        ║
+                    ║  handleGroupChatMessage                ║
+                    ║    ↓ 解析 bodyItems（TEXT/AT/IMAGE/LINK）║
+                    ║    ↓ groupPolicy 权限校验               ║
+                    ║    ↓ checkBotMentioned(@机器人检测)      ║
+                    ║    ↓ replyMode 门控                     ║
+                    ║      (ignore/record/mention-only/      ║
+                    ║       mention-and-watch/proactive)     ║
+                    ║    ↓ 下载 IMAGE body item 图片           ║
+                    ║                                        ║
+                    ║  共用: buildAgentMediaPayload → ctxPayload ║
+                    ╚══════════════╤══════════════════════════╝
+                                   │
+                    ══════════════▼══════════════════════════
+                    ║       【复用层 C】OpenClaw Core LLM      ║
+                    ║   dispatchReplyWithBufferedBlock...    ║
+                    ║   (OpenClaw 内置，插件不感知细节)         ║
+                    ╚═════════════════════════════════════════╝
+```
+
+---
+
+## 五、OpenClaw → 如流（出方向）完整路线
+
+```
+                    ╔═════════════════════════════════════════╗
+                    ║       【复用层 C】OpenClaw Core LLM      ║
+                    ║   LLM 流式输出 → ReplyPayload            ║
+                    ║   { text, mediaUrl?, mediaUrls? }       ║
+                    ╚══════════════╤══════════════════════════╝
+                                   │
+                    ══════════════▼══════════════════════════
+                    ║       【复用层 D】回复调度器              ║
+                    ║       reply-dispatcher.ts              ║
+                    ║                                        ║
+                    ║  1. LLM 输出中解析 @id 模式              ║
+                    ║     → resolvedUserIds / agentIds        ║
+                    ║  2. 合并 atOptions（回 @发送者）          ║
+                    ║  3. chunkText 4000字分片                 ║
+                    ║  4. 仅首片附 replyTo（引用回复）           ║
+                    ║     注: markdown 格式禁用 replyTo         ║
+                    ║  5. mediaUrl → prepareInfoflowImageBase64║
+                    ║     失败则降级为 link 类型                ║
+                    ╚══════════════╤══════════════════════════╝
+                                   │ contents[] 构建完成
+                                   │
+                    ══════════════▼══════════════════════════
+                    ║        【复用层 E】统一发送入口            ║
+                    ║        send.ts: sendInfoflowMessage     ║
+                    ║                                        ║
+                    ║  解析 to:                               ║
+                    ║  "group:12600364" → sendGroup          ║
+                    ║  "zhangsan"       → sendPrivate        ║
+                    ║                                        ║
+                    ║  共用: getOrCreateAdapter()             ║
+                    ║        → accessToken 缓存+自动刷新       ║
+                    ║        → recordSentMessageId (防自回环)  ║
+                    ║        → recordSentMessage (备撤回)     ║
+                    ╚══════════════╤══════════════════════════╝
+                    ┌─────────────┴────────────────┐
+                    │                              │
+      ──────────────▼─────────         ────────────▼──────────
+     │   【适配层 ③】群聊发送   │        │  【适配层 ③】私聊发送  │
+     │  sendInfoflowGroupMessage│        │ sendInfoflowPrivateMessage│
+     │                         │        │                       │
+     │  - contents[] 逐项处理   │        │  按 messageFormat:    │
+     │  - LINK/IMAGE 必须单独   │        │  "text" →             │
+     │    发送（API 限制）       │        │    msgtype: "text"    │
+     │  - AT 节点置首位          │        │  "markdown" →         │
+     │  - replyTo 引用结构        │        │    msgtype: "markdown"│
+     │                         │        │  - appid 字段          │
+     │  POST /api/v1/robot/msg/ │        │                       │
+     │    groupmsgsend          │        │  POST /api/v1/app/    │
+      ──────────────┬──────────          │    message/send       │
+                    │                     ───────────┬───────────
+                    └──────────────┬───────────────────┘
+                                   │
+┌──────────────────────────────────▼──────────────────────────────────┐
+│                           如流服务端                                  │
+│                     消息投递到用户/群                                  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 六、复用 vs 适配 一览表
+
+| 层级 | 文件 | 性质 | 说明 |
+|------|------|------|------|
+| 适配层 ① | `monitor.ts` | **Infoflow 专属** | Webhook HTTP 路由注册；WS Monitor 启动 |
+| 适配层 ① | `ws-receiver.ts` | **Infoflow 专属** | SDK WSClient 封装，监听 group.*/private.* |
+| 适配层 ② | `webhook-parser.ts` | **Infoflow 专属** | AES-ECB 解密、echostr 验签、Content-Type 分支 |
+| 适配层 ② | `ws-receiver.ts` | **Infoflow 专属** | SDK 格式整形为统一 msgData；monkey-patch 修 SDK bug |
+| **复用层 A** | `webhook-parser.ts` | **webhook+WS 共用** | `isDuplicateMessage()` 去重缓存，两条路径共享 |
+| **复用层 B** | `message-handler.ts` | **webhook+WS 共用** | 权限校验、bodyItems 解析、replyMode、图片下载、LLM 调度 |
+| **复用层 C** | OpenClaw Core | **所有通道共用** | LLM 推理、流式输出缓冲（插件不感知） |
+| **复用层 D** | `reply-dispatcher.ts` | **所有消息类型共用** | @解析、4000字分片、引用回复、图片降级 |
+| **复用层 E** | `send.ts` | **私聊+群聊共用** | Token 管理、防自回环、消息记录、统一入口 |
+| 适配层 ③ | `send.ts` | **私聊/群聊各自适配** | 群聊：LINK/IMAGE 单独发、AT 节点结构；私聊：msgtype 字段、appid |
+
+---
+
+## 七、一句话总结
+
+> **两条路（Webhook / WebSocket）只在「接入 + 解密」阶段有区别，整形成统一 `msgData` 结构后，完全走同一套逻辑**；发送侧在「群聊 / 私聊 API 适配」前也完全共用，差异只在最后一步的 HTTP Body 格式。