@core-workspace/infoflow-openclaw-plugin 2026.3.9 → 2026.3.27-beta.0

package/PROJECT_GUIDE.md

@@ -0,0 +1,355 @@
+# Infoflow OpenClaw Plugin — 项目导读
+
+> 本文档面向初次接触此项目的开发者，帮助快速建立对项目结构、模块职责和核心逻辑的完整认知。
+
+---
+
+## 一、项目定位
+
+这是一个 **OpenClaw 渠道插件**，把百度如流（Infoflow）企业消息平台接入 OpenClaw AI Agent 框架。
+
+```
+如流用户  ←→  如流服务器  ←→  OpenClaw (本插件)  ←→  LLM
+```
+
+插件负责：接收消息 → 安全判断 → 分发给 LLM → 把回复发回如流。
+
+---
+
+## 二、目录结构全览
+
+```
+openclaw_infoflow/
+├── index.ts                    # 插件入口：注册所有能力
+├── src/
+│   ├── types.ts                # 所有 TypeScript 类型定义
+│   ├── runtime.ts              # OpenClaw runtime 单例
+│   ├── logging.ts              # 日志工具（多个命名 logger）
+│   ├── events.ts               # 内部事件总线（message:sent）
+│   ├── compat/
+│   │   └── openclaw-sdk.ts     # SDK 兼容层（统一导出 openclaw/* 子路径）
+│   │
+│   ├── channel/                # 与如流 API 直接交互的 I/O 层
+│   │   ├── channel.ts          # ChannelPlugin 定义（OpenClaw 渠道注册）
+│   │   ├── monitor.ts          # Webhook/WebSocket 监听器生命周期
+│   │   ├── outbound.ts         # 发消息/撤回/ASR/群成员列表 API
+│   │   ├── accounts.ts         # 多账号配置解析
+│   │   ├── media.ts            # 图片 base64 准备与发送
+│   │   └── streaming.ts        # 流式卡片会话（streaming-card 格式）
+│   │
+│   ├── adapter/
+│   │   ├── inbound/
+│   │   │   ├── webhook-parser.ts  # AES 解密、签名验证、去重、路由
+│   │   │   └── ws-receiver.ts     # WebSocket 接收器
+│   │   └── outbound/
+│   │       ├── reply-dispatcher.ts   # LLM 回复 → Infoflow 消息的适配
+│   │       ├── target-resolver.ts    # infoflow: 前缀标准化
+│   │       └── markdown-local-images.ts  # Markdown 中本地图片替换
+│   │
+│   ├── handler/
+│   │   └── message-handler.ts  # 核心分发逻辑（最复杂的模块）
+│   │
+│   ├── security/
+│   │   ├── dm-policy.ts        # 私聊访问策略（open/pairing/allowlist）
+│   │   └── group-policy.ts     # 群聊策略（replyMode 判断、@mention 检测）
+│   │
+│   ├── tools/
+│   │   ├── index.ts            # LLM 工具注册（send/recall/cron/bos）
+│   │   ├── hooks/index.ts      # OpenClaw hooks 注册
+│   │   ├── actions/index.ts    # Channel action 定义
+│   │   └── cron/relay.ts       # 定时任务中继服务
+│   │
+│   ├── commands/
+│   │   ├── doctor.ts           # /infoflow-doctor 诊断命令
+│   │   ├── logs.ts             # /infoflow-logs 日志命令
+│   │   ├── changelog.ts        # /infoflow-changelog 更新日志命令
+│   │   └── version.ts          # 版本信息
+│   │
+│   └── utils/
+│       ├── store/
+│       │   └── message-store.ts  # SQLite：已发消息记录（撤回依赖）
+│       ├── audio/g722/           # 如流私有音频格式 .hd → WAV 解码
+│       ├── bos/
+│       │   └── im-bos-client.ts  # 百度 BOS 文件上传/预签名 URL
+│       ├── group-agent-cache.ts  # 群成员 name→agentId 缓存
+│       └── token-adapter.ts      # App Access Token 管理（自动刷新）
+│
+├── tests/                      # 测试（镜像 src/ 结构）
+└── scripts/
+    ├── deploy.sh               # 部署脚本（sync + openclaw gateway restart）
+    └── build-tools/            # 构建辅助
+```
+
+---
+
+## 三、模块职责速查
+
+| 模块 | 职责一句话 |
+|------|-----------|
+| `index.ts` | 插件入口，注册所有能力（渠道/路由/工具/命令/服务） |
+| `channel/channel.ts` | 向 OpenClaw 描述本渠道（配置 schema、启停逻辑） |
+| `channel/monitor.ts` | 管理 Webhook 路径注册表；启/停 WS 接收器 |
+| `adapter/inbound/webhook-parser.ts` | **入口解析**：AES 解密、签名验证、消息去重、路由私聊/群聊 |
+| `handler/message-handler.ts` | **核心**：策略门控 → 构建上下文 → 媒体下载 → 分发 LLM |
+| `security/dm-policy.ts` | 私聊白名单/配对策略（纯函数，无 I/O） |
+| `security/group-policy.ts` | 群聊 replyMode 判断、@mention 检测（纯函数，无 I/O） |
+| `channel/outbound.ts` | 发送/撤回/ASR/群成员 API 封装（所有 HTTP 出口） |
+| `adapter/outbound/reply-dispatcher.ts` | 把 LLM 的 ReplyPayload 转为 Infoflow 消息并发送 |
+| `tools/index.ts` | 注册 LLM 可调用工具：send/recall/cron/bos |
+| `utils/store/message-store.ts` | SQLite 存储已发消息（撤回时查 messageid+msgseqid） |
+| `utils/token-adapter.ts` | App Token 缓存，自动刷新，并发安全 |
+| `utils/group-agent-cache.ts` | 群 robot name→agentId 映射缓存（@机器人名字→正确 AT） |
+
+---
+
+## 四、消息入站全流程
+
+```
+如流服务器 POST /webhook/infoflow
+         │
+         ▼
+monitor.ts: handleInfoflowWebhookRequest
+  - 路径匹配 webhookTargets 注册表
+  - 只允许 POST，否则 405
+  - 读取原始 body（≤20MB）
+         │
+         ▼
+webhook-parser.ts: parseAndDispatchInfoflowRequest
+  按 Content-Type 分支：
+  ┌── application/x-www-form-urlencoded
+  │     ├── echostr 字段 → 验签（MD5: rn+timestamp+checkToken）→ 200/403
+  │     └── messageJson 字段 → 私聊路径
+  └── text/plain → 群聊路径（body 本身就是密文）
+
+  tryDecryptAndDispatch（私聊/群聊共用）：
+    1. AES-ECB 解密（尝试所有账号的 encodingAESKey）
+    2. patchPreciseIds：16+ 位整数转字符串（防 JSON.parse 精度丢失）
+    3. JSON.parse（私聊 fallback: XML 解析）
+    4. 去重检查（5分钟 TTL，1000条 LRU）
+    5. fire-and-forget 分发
+         │
+         ▼
+message-handler.ts: handlePrivateChatMessage
+                 或  handleGroupChatMessage
+  ┌── 私聊：提取字段 → dmPolicy 检查 → 语音处理 → handleInfoflowMessage
+  └── 群聊：提取字段 → groupPolicy 检查 → robotId 自发现 → 去自身消息
+           → body 解析（TEXT/AT/IMAGE/replyData）→ handleInfoflowMessage
+         │
+         ▼
+message-handler.ts: handleInfoflowMessage（核心分发）
+  1. resolveAgentRoute → 确定 LLM agent 和 sessionKey
+  2. peerId 路由计算（group/user 模式）
+  3. 图片/语音媒体下载（SSRF 白名单保护）
+  4. 构建 ctxPayload（Body/From/To/MessageSid 等）
+  5. replyMode 门控（见第五节）
+  6. 启动 processing hint 定时器（默认 5s）
+  7. createInfoflowReplyDispatcher → 配置 deliver 回调
+  8. dispatchReplyWithBufferedBlockDispatcher → 送入 LLM
+  9. 清理历史、记录 followUp 时间戳
+```
+
+---
+
+## 五、群聊 replyMode 门控（最核心的业务逻辑）
+
+```
+                    ┌─────────────────────────────────┐
+                    │   resolveGroupConfig             │
+                    │   groups.<id> > account > legacy │
+                    └───────────────┬─────────────────┘
+                                    │ replyMode
+              ┌─────────────────────┼──────────────────────┐
+              │                     │                       │
+           ignore                 record              mention-only
+              │                     │                       │
+           丢弃                  仅存历史           @机器人才触发
+                                                            │
+                                              否─→ followUp 窗口内？─→ 是
+                                                            │          │
+                                                         存历史     LLM判断
+                                                          丢弃
+
+              mention-and-watch                      proactive
+              ─────────────────                      ─────────
+              @机器人 ─→ 触发                        全量消息送 LLM
+              watchMentions 命中 ─→ 触发（watch提示）  LLM 自决定 NO_REPLY
+              watchRegex 命中 ─→ 触发（regex提示）
+              否 ─→ followUp 窗口 ─→ 触发/存历史
+```
+
+### followUp 窗口机制
+- 机器人每次发出回复时，`recordGroupReply(groupId)` 记录时间戳
+- 后续消息到达时，`isWithinFollowUpWindow(groupId, windowSeconds)` 判断是否在窗口内
+- 窗口内的消息会注入 `GroupSystemPrompt`，让 LLM 判断是否是跟进问题，并允许输出 `NO_REPLY`
+
+### GroupSystemPrompt 注入场景
+
+| 触发原因 | 注入的提示 |
+|---------|-----------|
+| `followUp` | 告知 LLM 刚刚回复过，让它判断新消息是否跟进 |
+| `watchMentions(id)` | 告知 LLM 某人被 @，作为其助手决定是否代回 |
+| `watchRegex(pattern)` | 告知 LLM 内容命中配置的正则，决定是否回复 |
+| `proactive` | 告知 LLM 在群里观察到消息，决定是否主动回复 |
+
+---
+
+## 六、消息出站全流程
+
+```
+LLM 输出文本/工具调用
+         │
+         ▼
+reply-dispatcher.ts: createInfoflowReplyDispatcher
+  - 文本按 textChunkLimit（默认1800字符）切分
+  - 解析 @name 引用 → 通过 group-agent-cache 转换为 at-agent agentId
+  - 清理 bodyForAgent 注解（如 "(robotid:123)"）
+  - Markdown 本地图片 → base64 嵌入
+         │
+         ▼
+outbound.ts: sendInfoflowMessage
+  解析 to 格式：
+  ┌── "group:12345" → sendInfoflowGroupMessage
+  │     - TEXT/MD/AT 合并一条发
+  │     - LINK 逐条单独发
+  │     - IMAGE 逐条单独发
+  └── "username"    → sendInfoflowPrivateMessage
+        + 图片 → sendInfoflowPrivateImage（单独调用）
+
+  每条发送成功后：
+  - recordSentMessageId → 去重缓存（防止自己的发出消息被处理）
+  - coreEvents.emit("message:sent") → message-store.ts 写入 SQLite
+```
+
+### 鉴权
+- Token 通过 `getAppAccessToken` 获取，由 `token-adapter.ts` 缓存并在到期前自动刷新
+- 请求头格式：`Authorization: Bearer-<token>`（如流私有格式，非标准）
+
+---
+
+## 七、64 位整数精度问题（重要）
+
+如流的 messageid 超过 `Number.MAX_SAFE_INTEGER (2^53-1)`，直接 `JSON.parse` 会丢失精度。
+
+**入站**（`webhook-parser.ts`）：
+```
+patchPreciseIds(rawText)
+  正则: /"(messageid|msgid|MsgId|msgkey)"\s*:\s*(\d{16,})/g
+  替换: "messageid": 12345678901234567  →  "messageid": "12345678901234567"
+```
+
+**出站**（`outbound.ts`）：
+```
+extractIdFromRawJson(responseText, "messageid")
+  从原始响应字符串中用正则提取，不经过 JSON.parse
+```
+
+**撤回**：手动拼 JSON 字符串，避免 stringify 精度丢失：
+```ts
+const bodyStr = `{"groupId":${groupId},"messageid":${messageid},"msgseqid":${msgseqid}}`;
+```
+
+---
+
+## 八、语音消息处理流程
+
+```
+收到 msgType=voice
+  │
+  ├── voiceUrl 包含 .mp3
+  │     → 直接下载，传给 openclaw 处理
+  │
+  └── voiceUrl 其他格式（.hd 等）
+        → 提取 MD5（从 fileid 参数）
+        → 调用 ASR 接口（/api/v1/va/queryASRResult）
+              ├── 成功 → mes = 识别文字
+              └── 失败 → 下载 .hd → decodeHdToWav（src/utils/audio/g722/）
+                            ├── 成功 → mes = "[语音消息]", localVoicePath = wav路径
+                            └── 失败 → 丢弃消息
+```
+
+---
+
+## 九、LLM 工具（Tools）
+
+注册在 `tools/index.ts`，LLM 在对话中可以主动调用：
+
+| 工具名 | 功能 |
+|--------|------|
+| `infoflow_send` | 主动发私聊或群消息（文本/Markdown/图片/@ 成员） |
+| `infoflow_recall` | 撤回最近 N 条或按 messageId 撤回 |
+| `infoflow_cron` | 创建定时消息（绑定当前会话目标，LLM 无法伪造收件人） |
+| `infoflow_bos_upload` | 上传文件到 BOS，返回预签名下载 URL |
+| `infoflow_bos_get_url` | 刷新已上传文件的预签名 URL |
+
+`infoflow_cron` 安全机制：收件人从可信的 session 上下文（groupId/FromUserId）自动绑定，
+LLM 参数里没有 `to` 字段，防止模型被诱导给任意目标发定时消息。
+
+---
+
+## 十、配置优先级
+
+```
+groups.<groupId> > accounts.<id> > 顶层 defaults
+```
+
+关键配置字段速查：
+
+| 字段 | 作用 |
+|------|------|
+| `replyMode` | 群聊触发策略（ignore/record/mention-only/mention-and-watch/proactive） |
+| `groupSessionMode` | group=群共享会话，user=群内按人分会话 |
+| `followUp` / `followUpWindow` | 跟进窗口开关与时长（默认 300s） |
+| `watchMentions` | 监控 @某人触发 |
+| `watchRegex` | 正则匹配触发 |
+| `dmMessageFormat` | 私聊消息格式（text/markdown/streaming-card） |
+| `groupMessageFormat` | 群聊消息格式 |
+| `textChunkLimit` | 单条消息最大字符数（默认 1800） |
+| `processingHint` / `processingHintDelay` | 慢响应提示（默认开启，5s 后发"👌收到啦"） |
+| `appAgentId` | 企业后台应用 ID（私聊撤回必填） |
+| `robotId` | 机器人 ID（自动发现并写回配置） |
+
+---
+
+## 十一、连接模式
+
+| 模式 | 说明 |
+|------|------|
+| `webhook`（默认） | 如流主动 POST 到 `/webhook/infoflow` |
+| `websocket` | 插件主动连接如流 WS 网关，`ws-receiver.ts` 接收推送 |
+
+WebSocket 模式需配置 `wsGateway`（Phase 1 端点分配）和可选的 `wsConnectDomain`（Phase 2 握手地址）。
+
+---
+
+## 十二、关键约定
+
+1. **所有 TS import 必须带 `.js` 后缀**（ESM 运行时要求）
+2. **messageid 始终用字符串操作**，不经 Number 转换
+3. **`openclaw` 是 peerDependency**，`deploy.sh` 部署时用 symlink 指向全局安装
+4. **群消息 LINK 和 IMAGE 必须单独发送**（如流 API 限制，不能和文字混在同一条）
+5. **撤回群消息需要 `messageid + msgseqid`**，私聊撤回需要 `msgkey + appAgentId`
+6. **`robotId` 自动发现**：首次被 @时从 body AT 元素中读取并持久化到配置文件
+
+---
+
+## 十三、本地调试
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+
+# 部署（sync 到 ~/.openclaw/extensions/infoflow-openclaw-plugin/ 并重启网关）
+./scripts/deploy.sh
+
+# 查看实时日志
+openclaw logs | grep infoflow
+
+# 诊断配置
+/infoflow-doctor
+
+# 查看收发日志（最近 50 条）
+/infoflow-logs 50
+```