@core-workspace/infoflow-openclaw-plugin 2026.3.8

package/docs/architecture.md

@@ -0,0 +1,423 @@
+# 如流 Openclaw 插件 - 技术架构文档
+
+## 项目概述
+
+这是一个如流(百度企业沟通平台)的 Openclaw 插件项目，采用 Webhook 方式实现消息收发，支持单聊和群聊，支持多账号和丰富的参数配置。
+
+---
+
+## 项目结构
+
+```
+infoflow/
+├── index.ts                      # 插件入口，注册Channel和Webhook路由
+├── openclaw.plugin.json          # 插件元数据和配置schema
+├── package.json                  # 项目依赖和元数据
+├── tsconfig.json                 # TypeScript配置
+├── src/
+│   ├── channel.ts                # Channel插件定义（核心）
+│   ├── monitor.ts                # Webhook监听器
+│   ├── infoflow-req-parse.ts     # Webhook请求解析、解密、去重
+│   ├── bot.ts                    # 消息处理核心逻辑（replyMode决策）
+│   ├── send.ts                   # 消息发送API（私聊/群聊）
+│   ├── reply-dispatcher.ts       # 回复分发器（@mentions解析、分块）
+│   ├── media.ts                  # 图片处理（下载、压缩、Base64）
+│   ├── actions.ts                # LLM Tool适配（send/delete）
+│   ├── accounts.ts               # 多账号支持、配置合并
+│   ├── targets.ts                # 目标规范化（用户/群）
+│   ├── sent-message-store.ts     # 已发送消息存储（SQLite）
+│   ├── types.ts                  # TypeScript类型定义
+│   ├── logging.ts                # 日志模块
+│   └── runtime.ts                # Runtime访问器
+├── docs/
+│   └── architecture.md           # 本技术架构文档
+└── README.md                     # 完整文档
+```
+
+---
+
+## 核心模块职责
+
+| 模块 | 文件 | 核心职责 |
+|------|------|---------|
+| **插件入口** | [index.ts](../index.ts) | 注册插件、Channel定义、Webhook路由 |
+| **Channel定义** | [src/channel.ts](../src/channel.ts) | 定义插件结构、生命周期、Actions、配置管理 |
+| **Webhook监听** | [src/monitor.ts](../src/monitor.ts) | Webhook目标注册、HTTP请求路由 |
+| **请求解析** | [src/infoflow-req-parse.ts](../src/infoflow-req-parse.ts) | AES-ECB解密、消息去重、私聊/群聊路由 |
+| **消息处理** | [src/bot.ts](../src/bot.ts) | replyMode决策、历史注入、LLM调用 |
+| **消息发送** | [src/send.ts](../src/send.ts) | Token管理、私聊/群聊发送、消息撤回 |
+| **回复分发** | [src/reply-dispatcher.ts](../src/reply-dispatcher.ts) | @mentions解析、文本分块、replyTo构造 |
+| **图片处理** | [src/media.ts](../src/media.ts) | 图片下载、压缩到1MB、Base64编码 |
+| **Actions** | [src/actions.ts](../src/actions.ts) | LLM Tool（send/delete消息） |
+| **多账号** | [src/accounts.ts](../src/accounts.ts) | 账号解析、配置合并 |
+| **存储** | [src/sent-message-store.ts](../src/sent-message-store.ts) | 已发送消息记录（SQLite） |
+
+---
+
+## 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| **语言** | TypeScript |
+| **运行时** | Node.js >= 18 |
+| **框架** | OpenClaw Plugin SDK (>= 2026.3.2) |
+| **加密** | node:crypto (AES-128/192/256-ECB) |
+| **存储** | node:sqlite (同步API) |
+| **HTTP** | fetch API |
+
+---
+
+## 配置管理
+
+### 配置文件
+- [openclaw.plugin.json](../openclaw.plugin.json) - 插件元数据和配置 schema
+
+### 核心配置项
+
+| 配置项 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `checkToken` | string | ✅ | Webhook验证token |
+| `encodingAESKey` | string | ✅ | AES-ECB加密密钥 |
+| `appKey` | string | ✅ | 应用Key |
+| `appSecret` | string | ✅ | 应用Secret |
+| `apiHost` | string | ❌ | 如流API地址 |
+| `robotName` | string | ❌ | 机器人名称，用于@检测 |
+| `appAgentId` | number | ❌ | 应用ID，私聊消息撤回需要 |
+| `replyMode` | string | ❌ | 回复模式（默认: mention-and-watch） |
+| `followUp` | boolean | ❌ | 是否启用跟进回复 |
+| `followUpWindow` | number | ❌ | 跟进窗口（秒） |
+| `watchMentions` | string[] | ❌ | 关注提及的人员列表 |
+| `watchRegex` | string | ❌ | 正则匹配规则 |
+| `dmPolicy` | string | ❌ | 私聊策略 |
+| `groupPolicy` | string | ❌ | 群聊策略 |
+| `defaultAccount` | string | ❌ | 默认账号ID |
+| `accounts` | object | ❌ | 多账号配置 |
+| `groups` | object | ❌ | 按群配置 |
+
+### DEFAULT_ACCOUNT_ID
+- 来自 `openclaw/plugin-sdk`，值为 `"default"`
+- 用于单账号场景和向后兼容
+- 多账号场景下，通过 `defaultAccount` 字段指定默认账号
+
+---
+
+## 系统架构图
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        如流服务器                         │
+│                    (发送 Webhook)                        │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                      Webhook 层                           │
+│  ┌──────────────┐    ┌─────────────────────────────┐  │
+│  │  monitor.ts  │───▶│ infoflow-req-parse.ts        │  │
+│  │  (路由监听)   │    │ (解密/去重/解析)              │  │
+│  └──────────────┘    └─────────────────────────────┘  │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                       业务层                              │
+│  ┌──────────────┐    ┌─────────────────────────────┐  │
+│  │   bot.ts     │───▶│ accounts.ts / targets.ts    │  │
+│  │(replyMode/   │    │ (多账号/目标规范化)          │  │
+│  │ LLM调用)     │    └─────────────────────────────┘  │
+│  └──────────────┘                                        │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                       发送层                              │
+│  ┌──────────────┐    ┌─────────────────────────────┐  │
+│  │   send.ts     │───▶│ reply-dispatcher.ts         │  │
+│  │(Token/消息   │    │ (@mentions/分块)             │  │
+│  │ 发送/撤回)   │    └─────────────────────────────┘  │
+│  └──────────────┘         ┌──────────────────────┐     │
+│                           │    media.ts          │     │
+│                           │ (图片处理/压缩)       │     │
+│                           └──────────────────────┘     │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                       存储层                              │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │        sent-message-store.ts (SQLite)          │   │
+│  │        - 已发送消息记录                          │   │
+│  │        - 内存缓存 (chatHistories, 20条/群)      │   │
+│  │        - 去重缓存 (5分钟)                       │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Webhook 处理流程
+
+### 消息接收流程图
+
+```
+用户发送消息
+    │
+    ▼
+如流服务器 → POST /webhook/infoflow
+    │
+    ▼
+┌──────────────────────────────────────────────────┐
+│ handleInfoflowWebhookRequest (monitor.ts)        │
+│ - 检查路径匹配                                    │
+│ - 验证HTTP方法（POST only）                       │
+│ - 读取原始body                                    │
+└────────────────────┬─────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────┐
+│ parseAndDispatchInfoflowRequest                  │
+│ (infoflow-req-parse.ts)                          │
+│                                                  │
+│ 根据 Content-Type 分流：                         │
+│                                                  │
+│ application/x-www-form-urlencoded:               │
+│   - echostr验证 (Webhook验证)                    │
+│   - 私聊消息                                     │
+│                                                  │
+│ text/plain:                                      │
+│   - 群聊消息                                     │
+└────────────────────┬─────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────┐
+│ AES-ECB 解密                                     │
+│ - 私聊: 解密 messageJson.Encrypt                │
+│ - 群聊: 解密整个body                              │
+└────────────────────┬─────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────┐
+│ 消息去重                                         │
+│ - 5分钟缓存                                      │
+│ - 避免重复处理                                   │
+└────────────────────┬─────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────┐
+│ dispatch到bot处理                                │
+│ - handlePrivateChatMessage()                    │
+│ - handleGroupChatMessage()                      │
+└──────────────────────────────────────────────────┘
+```
+
+### 加密方式详情
+
+| 消息类型 | Content-Type | 加密内容 |
+|----------|--------------|----------|
+| **私聊** | application/x-www-form-urlencoded | `messageJson` 字段中的 `Encrypt` 字段（AES-ECB） |
+| **群聊** | text/plain | 整个body（AES-ECB） |
+
+---
+
+## 单聊/群聊支持
+
+### 消息接收
+
+| 类型 | 处理函数 | 文件 |
+|------|----------|------|
+| 私聊 | `handlePrivateChatMessage()` | [src/bot.ts](../src/bot.ts) |
+| 群聊 | `handleGroupChatMessage()` | [src/bot.ts](../src/bot.ts) |
+
+### 消息发送
+
+| 类型 | 发送函数 | 文件 |
+|------|----------|------|
+| 私聊 | `sendInfoflowPrivateMessage()` | [src/send.ts](../src/send.ts) |
+| 群聊 | `sendInfoflowGroupMessage()` | [src/send.ts](../src/send.ts) |
+
+### 消息撤回
+
+| 类型 | 撤回函数 | 依赖 |
+|------|----------|------|
+| 私聊 | `recallInfoflowPrivateMessage()` | 需要 `appAgentId` |
+| 群聊 | `recallInfoflowGroupMessage()` | - |
+
+---
+
+## 回复模式 (replyMode)
+
+| 模式 | 说明 |
+|------|------|
+| `ignore` | 丢弃消息，不做任何处理 |
+| `record` | 仅保存历史记录，不触发回复 |
+| `mention-only` | 仅被@机器人时回复 |
+| `mention-and-watch` | 被@或关注的人被@时回复（默认） |
+| `proactive` | 主动回复所有消息 |
+
+### replyMode 决策流程
+
+```
+收到消息
+    │
+    ▼
+┌──────────────────────────────────┐
+│ 配置级别判断                    │
+│ 1. 按群配置 (groups.groupId)    │
+│ 2. 按账号配置 (accounts.accountId)│
+│ 3. 全局默认配置                │
+└────────────┬─────────────────────┘
+             │
+             ▼
+┌──────────────────────────────────┐
+│ 消息类型判断                    │
+│ - 私聊使用 dmPolicy             │
+│ - 群聊使用 groupPolicy          │
+└────────────┬─────────────────────┘
+             │
+             ▼
+┌──────────────────────────────────┐
+│ 执行策略                        │
+│ - ignore: 跳过                  │
+│ - record: 仅记录                │
+│ - mention-*: 检查@条件          │
+│ - proactive: 直接处理           │
+└──────────────────────────────────┘
+```
+
+---
+
+## 支持的消息类型
+
+| 类型 | 私聊 | 群聊 | 说明 |
+|------|------|------|------|
+| `text` | ✅ | ✅ | 纯文本 |
+| `markdown` | ✅ | ✅ | Markdown格式 |
+| `at` | - | ✅ | @用户 |
+| `at-agent` | - | ✅ | @机器人 |
+| `link` | ✅ | ✅ | 链接 |
+| `image` | ✅ | ✅ | 图片 |
+
+### 特殊功能
+
+| 功能 | 说明 |
+|------|------|
+| **@all** | 群聊中@所有成员 |
+| **watchMentions** | 监控指定人员被@触发 |
+| **watchRegex** | 正则匹配触发 |
+| **replyTo** | 引用回复（支持messageid、preview、imid） |
+| **引用回复** | 群聊中支持引用原消息回复 |
+
+---
+
+## 数据流
+
+### 入站消息流程
+
+```
+Webhook 接收
+    │
+    ▼
+AES-ECB 解密
+    │
+    ▼
+消息去重 (5分钟缓存)
+    │
+    ▼
+解析消息内容
+    │
+    ▼
+replyMode 决策
+    │
+    ▼
+构造 LLM Payload
+    │
+    ├──────────▶ 记录 Session
+    │
+    ▼
+调用 LLM
+    │
+    ▼
+生成回复
+```
+
+### 出站消息流程
+
+```
+LLM 输出
+    │
+    ▼
+解析 @mentions
+    │
+    ▼
+文本分块 (4000字/块)
+    │
+    ▼
+构造 replyTo (仅第一块)
+    │
+    ▼
+获取访问 Token
+    │
+    ▼
+循环发送各块消息
+    │
+    ▼
+记录已发送消息 (SQLite)
+```
+
+---
+
+## 关键设计决策
+
+| 设计决策 | 说明 |
+|----------|------|
+| **Token缓存** | 按appKey缓存，提前5分钟刷新，避免频繁请求 |
+| **消息分批** | LINK/IMAGE类型单独发送，避免与其他类型混排 |
+| **文本分块** | 单条消息限制4000字符，超长自动分块 |
+| **replyTo复用** | 只在第一条消息中使用，避免重复引用 |
+| **@mentions复用** | 只在第一块文本中使用，后续块自动继承 |
+| **大整数处理** | 手动拼接JSON避免JS Number精度丢失（messageId等） |
+| **图片SSRF防护** | 白名单域名+路径检查，防止SSRF攻击 |
+| **内存缓存** | chatHistories最多20条/群，避免内存溢出 |
+| **持久化存储** | session transcript无限制，支持完整对话历史 |
+
+---
+
+## 扩展点
+
+### 1. 添加新消息类型
+
+**步骤**:
+1. 在 [src/types.ts](../src/types.ts) 中添加新类型定义
+2. 在 [src/send.ts](../src/send.ts) 中实现发送逻辑
+3. 在 [src/reply-dispatcher.ts](../src/reply-dispatcher.ts) 中添加处理分支
+
+### 2. 添加新回复模式
+
+**步骤**:
+1. 在 [src/bot.ts](../src/bot.ts) 中的 `InfoflowReplyMode` 类型添加新值
+2. 在 `shouldReply` 函数中添加判断逻辑
+
+### 3. 添加新媒体类型
+
+**步骤**:
+1. 在 [src/media.ts](../src/media.ts) 中扩展下载和处理函数
+2. 在 [src/types.ts](../src/types.ts) 中添加类型定义
+
+### 4. 添加新Action
+
+**步骤**:
+1. 在 [src/actions.ts](../src/actions.ts) 中添加新的 `ChannelMessageActionName`
+2. 在 [src/channel.ts](../src/channel.ts) 的 `actions` 中注册
+
+---
+
+## 总结
+
+这是一个功能完善的企业级聊天机器人插件，采用清晰的模块化设计：
+
+- **Webhook层**: 处理消息接收、解密、去重
+- **业务层**: replyMode决策、LLM调用
+- **发送层**: Token管理、消息发送、回复分发
+- **存储层**: SQLite持久化、内存缓存
+
+支持多账号、私聊/群聊、图片处理、消息撤回等丰富功能，并具备良好的扩展性。