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

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+<!--
+开发规范：新改动写在 "## 开发中" 下方。
+发布时由 publish.sh 自动将 "## 开发中" 替换为版本号和日期（如 "## 1.1.0 (2026-03-18)"）。
+-->
+
+# 更新日志
+
+## 2026-03-26
+
+**问题修复**
+- 修复非标准 npm 全局路径下 SDK 加载失败的问题：通过 `realpathSync` 解析 `process.argv[1]` 的 symlink，使 `createRequire` 从真实安装目录而非 `bin/` 出发解析模块；同时新增 `npm_config_prefix` 环境变量作为 fallback 路径来源，覆盖自定义 npm prefix 场景（如 `/home/work/opt/npm-global/`）
+
+## 2026-03-25
+
+**新功能**
+- 新增 `wsConnectDomain` 配置项：支持两阶段 WebSocket 连接的独立域名/端口指定。`wsGateway` 控制 Phase 1 端点分配请求，`wsConnectDomain` 控制 Phase 2 实际 WS 握手地址，内网/NAT 环境下可分别指定，格式支持 `domain:port`
+
+## 2026-03-24
+
+**兼容性**
+- 兼容 openclaw 2026.3.22 及以上版本：新增统一兼容层 `src/compat/openclaw-sdk.ts`，适配 SDK 拆包后的各子路径导入（`plugin-entry`、`core`、`reply-runtime`、`channel-contract` 等），升级 SDK 版本无需逐一修改业务代码
+
+**新功能**
+- 支持发送文件消息
+- 支持在单聊和群聊中引用回复指定消息
+- 新增获取群成员列表接口，用于拉取群内其他机器人的 agents 信息
+- 支持 @ 其他机器人：可在群消息中主动 @ 并触发其他机器人响应
+
+**问题修复**
+- 修复接收所有消息时的 bug，确保消息不被意外丢弃
+- 修复域名配置问题，恢复外网连接可用性
+- 修复机器人无法响应群内其他机器人消息的问题：显式区分消息来源类型（`regular` 普通用户 / `robot` 机器人），避免机器人消息被误过滤
+- 修复 @ 其他机器人的边界条件处理，优化请求发送策略，提升稳定性
+- 减少日志冗余输出，新增日志分级控制，按级别过滤更清晰
+- 修复在开发机环境下因网络限制导致请求失败的问题
+
+## 2026.3.39 (2026-03-19)
+
+**问题修复**
+- 修复群聊 @ 检测不依赖 `robotName` 配置：WebSocket 模式通过 SDK `eventtype` 字段区分（`MESSAGE_RECEIVE` = @机器人，`ALL_MESSAGE_FORWARD` = 全量消息）；Webhook 模式通过 body AT 元素的 `robotid` 字段判断，两种模式均无需配置 `robotName`
+- 修复 Token 获取接口路径错误（缺少 `/api/v1` 前缀导致返回 HTML 404）
+- 修复默认 `apiHost` 与 SDK 不一致（由 `api.im.baidu.com` 改为 `api.im.baidu.com`）
+
+**安装工具（@baidu/infoflow-openclaw-tools）**
+- 新增 `uninstall` / `remove` 命令：一键卸载插件并清理配置
+- 安装/升级流程调整：先选择连接方式，再按模式填写最小配置（websocket 只需 AppKey + AppSecret；webhook 额外需要 Token + EncodingAESKey）
+- 修复连接方式选项（移除不支持的 `polling`，改为正确的 `webhook`）
+
+
+
+**新功能**
+- 消息格式默认改为 Markdown，加粗、代码块、列表等格式开箱即用，无需手动配置 `dmMessageFormat` / `groupMessageFormat`
+- `/infoflow-doctor` 支持 `/infoflow-doctor <userId>` 参数，Web UI 场景下也可向指定用户发送自检消息
+- `/infoflow-logs` 日志可读性优化：按会话聚合展示，每条显示发送方、消息内容预览、回复耗时和字数；支持 `/infoflow-logs error` / `warn` 按等级过滤
+
+**问题修复**
+- 修复 WebSocket 重连后消息被丢弃的问题（`receiver stopped`）：SDK 自动重连是正常行为，现在重连后消息可以正常接收和处理
+- 修复 `/infoflow-doctor` 自检时 WebSocket 连通性检查报错 `client.start is not a function` 的问题
+- 修复 `/infoflow-logs` 中回复字数统计不准、指令类消息显示"无回复"的问题
+
+**其他**
+- `/infoflow-doctor` 自检报告改为 Markdown 格式发送，加粗和表情符号现在可以正常渲染
+- `/infoflow-changelog` 更新日志改为 Markdown 格式发送
+
+## 1.0.0 (2026-03-17)
+
+**新功能**
+- 新增定时任务工具 `infoflow_cron`：支持向如流发送定时消息，可设置一次性触发（`at`）、固定间隔（`every`）或 Cron 表达式（`cron`），让 AI 能主动按时推送提醒/报告
+- 新增定时任务结果转发（`cronRelay`）：OpenClaw 定时任务完成后自动将结果转发到如流会话
+
+**问题修复**
+- 新增 WebSocket 断连/重连日志，断线后在 `/infoflow-logs` 中可查看完整时间线
+
+## 0.9.0 (2026-03-17)
+
+**问题修复**
+- 修复了机器人名称未填写时，群聊消息全部收不到的问题
+- 修复了群聊中机器人的回复有时因为内容过长而发送失败的问题
+- 修复了不填写连接方式时，机器人无法启动的问题
+- 修复了 WebSocket 模式下消息发送报错的问题
+- 修复了「自检」工具在 WebSocket 模式下误报验签和加密密钥未配置的问题
+
+**新功能**
+- 连接方式默认改为 WebSocket，只需配置 AppKey 和 AppSecret 即可使用，无需额外填写 Token 和密钥
+- 新增「查看日志」命令：在如流中发送 `/infoflow-logs` 即可查看机器人最近的收发消息记录，方便排查问题
+- 新增「查看更新日志」命令：在如流中发送 `/infoflow-changelog` 即可查看插件更新历史
+- 新增每条消息最大长度配置项，超长回复会自动拆成多条消息发送，默认每条不超过 1800 字
+- 「自检」报告优化：排查工具 `/infoflow-doctor` 的输出更加简洁易读
+
+**其他**
+- 长消息自动拆分时，现在会在段落或列表的自然边界处断开，避免内容被切断到奇怪的位置

package/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OpenClaw channel plugin for Baidu Infoflow (如流) enterprise messaging platform. Enables AI chatbots to integrate with Infoflow, supporting private/group chat, Webhook and WebSocket connections, image handling, message recall, and sophisticated group reply modes.
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+npm test -- --watch    # Watch mode
+
+# Deploy to OpenClaw (sync to extensions dir and restart gateway)
+./scripts/deploy.sh
+
+# Manual deploy
+rsync -av --delete . ~/.openclaw/extensions/infoflow/ --exclude node_modules --exclude dist --exclude .git
+openclaw gateway restart
+
+# View logs
+openclaw logs | grep infoflow
+tail -f ~/.openclaw/logs/gateway.log | grep -i infoflow
+
+# Debug commands
+openclaw doctor                    # Check config
+openclaw status                    # Channel status
+openclaw directory groups infoflow # List group IDs
+```
+
+## Architecture
+
+### Layered Structure
+
+| Layer | Directory | Responsibility |
+|-------|-----------|----------------|
+| Plugin Entry | `channel/` | OpenClaw SDK integration, network I/O |
+| Message Adapter | `adapter/` | Format conversion (pure functions) |
+| Event Bridge | `handler/` | Event routing, security decisions |
+| Security Policy | `security/` | Pure policy logic, no I/O |
+| Tool Registration | `tools/` | LLM function calling tools |
+| Shared Utilities | `utils/` | Cross-layer utilities |
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Plugin entry: registers channel, HTTP route, tools, hooks |
+| `src/types.ts` | All TypeScript type definitions |
+| `src/channel/channel.ts` | ChannelPlugin definition with actions, config, security |
+| `src/handler/message-handler.ts` | Core message routing and LLM dispatch |
+| `src/tools/index.ts` | LLM tools: `infoflow_send`, `infoflow_recall` |
+| `src/security/group-policy.ts` | Reply mode logic, @mention detection, follow-up window |
+| `src/channel/outbound.ts` | Send/recall message API wrappers |
+| `openclaw.plugin.json` | Plugin metadata and JSON Schema for configuration |
+
+### Data Flow (Inbound)
+
+```
+如流服务器 → POST /webhook/infoflow
+  → channel/monitor.ts (AES decrypt, checkToken verify)
+  → adapter/inbound/webhook-parser.ts (dedup, route)
+  → handler/message-handler.ts (policy check, replyMode)
+  → LLM dispatch → adapter/outbound/reply-dispatcher.ts
+  → channel/outbound.ts → 如流 API
+  → utils/store/message-store.ts (record for recall)
+```
+
+## Critical Conventions
+
+### ESM Import Paths
+
+**All TypeScript imports must use `.js` extension** (ESM runtime requirement):
+
+```typescript
+// ✅ Correct
+import { sendInfoflowMessage } from "../channel/outbound.js";
+
+// ❌ Wrong - will fail at runtime
+import { sendInfoflowMessage } from "../channel/outbound";
+```
+
+### 64-bit Integer Handling
+
+Infoflow message IDs exceed JavaScript's `Number.MAX_SAFE_INTEGER`. Always extract from raw JSON as strings:
+
+```typescript
+import { extractIdFromRawJson } from "../channel/outbound.js";
+const messageId = extractIdFromRawJson(rawJsonText, "messageid");
+```
+
+### Mock Paths in Tests
+
+Use `.js` extension in `vi.mock` paths:
+
+```typescript
+vi.mock("../../src/channel/outbound.js", () => ({
+  sendInfoflowMessage: vi.fn().mockResolvedValue({ ok: true }),
+}));
+```
+
+## Testing
+
+- Test files mirror `src/` structure in `tests/` directory
+- `security/` functions require branch coverage ≥ 80%
+- Network functions are mocked; no real HTTP requests in tests
+
+## Message ID Requirements
+
+- **Group recall**: requires `messageid` + `msgseqid` (stored in SQLite via `message-store.ts`)
+- **Private recall**: requires `msgkey` + `appAgentId` (config field)
+
+## Group Reply Modes
+
+| Mode | Trigger Condition |
+|------|-------------------|
+| `mention-only` | Only when bot is @mentioned |
+| `mention-and-watch` | @bot, @watchMentions users, or watchRegex match |
+| `proactive` | All messages go to LLM (LLM decides NO_REPLY or respond) |
+| `record` | Log only, no reply |
+| `ignore` | Discard completely |
+
+## Configuration Hierarchy
+
+Priority: `groups.<groupId>` > `accounts.<id>` > top-level defaults
+
+Key config paths:
+- `channels.infoflow` - main config
+- `channels.infoflow.accounts.<id>` - multi-account
+- `channels.infoflow.groups.<groupId>` - per-group override

package/COLLABORATION_REPORT.md

@@ -0,0 +1,209 @@
+# Infoflow 插件项目协作报告
+
+**生成日期**: 2026-03-23
+**团队成员**: researcher, analyst
+
+---
+
+## 1. 项目概述
+
+OpenClaw 的百度如流（Infoflow）企业消息平台插件，使 AI 聊天机器人能够与如流平台集成，支持私聊/群聊、Webhook 和 WebSocket 连接、图片处理、消息撤回、以及灵活的群回复模式。
+
+---
+
+## 2. 架构分析
+
+### 2.1 分层架构
+
+| 层级 | 目录 | 职责 |
+|------|------|------|
+| 插件入口层 | `channel/` | OpenClaw SDK 集成、网络 I/O |
+| 消息适配层 | `adapter/` | 格式转换（纯函数） |
+| 事件桥接层 | `handler/` | 事件路由、安全决策 |
+| 安全策略层 | `security/` | 纯策略逻辑，无 I/O |
+| 工具注册层 | `tools/` | LLM function calling 工具 |
+| 共享工具层 | `utils/` | 跨层工具 |
+
+### 2.2 核心模块
+
+#### 插件入口层 (`src/channel/`)
+- `channel.ts` - ChannelPlugin 定义：actions、config、security
+- `monitor.ts` - Webhook 入口，AES 解密、checkToken 验证
+- `outbound.ts` - 发送/撤回消息 API 封装
+- `accounts.ts` - 多账号管理
+- `streaming.ts` - 流式响应处理
+- `media.ts` - 媒体文件处理
+
+#### 消息适配层 (`src/adapter/`)
+- `inbound/webhook-parser.ts` - 入站消息解析、去重、路由
+- `inbound/ws-receiver.ts` - WebSocket 接收器
+- `outbound/reply-dispatcher.ts` - 回复分发
+- `outbound/target-resolver.ts` - 目标解析
+- `outbound/markdown-local-images.ts` - Markdown 本地图片处理
+
+#### 事件桥接层 (`src/handler/`)
+- `message-handler.ts` - 核心消息路由和 LLM 分发
+
+#### 安全策略层 (`src/security/`)
+- `group-policy.ts` - 群回复模式逻辑、@mention 检测、follow-up 窗口
+- `dm-policy.ts` - 私聊策略
+
+#### 工具注册层 (`src/tools/`)
+- `index.ts` - LLM 工具：`infoflow_send`、`infoflow_recall`
+- `hooks/index.ts` - 工具钩子
+- `actions/index.ts` - 动作定义
+- `cron/relay.ts` - 定时任务中继
+
+#### 共享工具层 (`src/utils/`)
+- `store/message-store.ts` - 消息存储（SQLite，用于撤回）
+- `audio/g722/` - G.722 音频解码器
+- `bos/im-bos-client.ts` - BOS 存储客户端
+- `token-adapter.ts` - Token 适配器
+
+---
+
+## 3. 消息处理流程
+
+### 3.1 入站数据流
+
+```
+如流服务器 → POST /webhook/infoflow
+  → channel/monitor.ts (路由分发)
+  → adapter/inbound/webhook-parser.ts
+      ├─ AES 解密 (encodingAESKey)
+      ├─ 64位整数ID精度修复
+      ├─ 消息去重 (5分钟TTL, 1000条缓存)
+      └─ 按聊天类型路由
+  → handler/message-handler.ts
+      ├─ 安全校验 (dm-policy / group-policy)
+      ├─ 群回复模式判断 (replyMode)
+      │   ├─ mention-only: 仅 @机器人 时响应
+      │   ├─ mention-and-watch: @机器人 / @监控用户 / 正则匹配
+      │   ├─ proactive: 全部消息送 LLM 决策
+      │   ├─ record: 仅记录，不响应
+      │   └─ ignore: 完全忽略
+      └─ LLM 分发
+  → adapter/outbound/reply-dispatcher.ts
+  → channel/outbound.ts → 如流 API
+  → utils/store/message-store.ts (记录消息ID用于撤回)
+```
+
+### 3.2 关键处理细节
+
+#### Webhook 入口 (`monitor.ts`)
+- 仅接受 POST 请求
+- 支持多账号，按路径注册
+- 最大请求体 20MB
+
+#### 消息解析 (`webhook-parser.ts`)
+- **私聊**: `application/x-www-form-urlencoded`，包含 `messageJson` 字段
+- **群聊**: `text/plain`，请求体即 AES 加密内容
+- **echostr 验证**: MD5 签名验证用于服务器配置
+
+#### AES 解密
+- 模式: AES-ECB (Infoflow API 约束)
+- 密钥: Base64 URLSafe 编码 (支持 128/192/256 位)
+- 支持多账号密钥尝试
+
+#### 64位整数处理
+如流消息 ID 超过 JavaScript `Number.MAX_SAFE_INTEGER`：
+- 从原始 JSON 文本中用正则提取为字符串
+- 修复 JSON.parse 的精度丢失
+
+#### 消息去重
+- TTL: 5 分钟
+- 最大缓存: 1000 条
+- 键值: `messageid` 或 `{fromuserid}_{groupid}_{ctime}`
+
+### 3.3 群回复模式
+
+| 模式 | 触发条件 |
+|------|----------|
+| `mention-only` | 仅 @机器人 时响应 |
+| `mention-and-watch` | @机器人 / @监控用户 / watchRegex 匹配 |
+| `proactive` | 全部消息送 LLM，由 LLM 决定是否响应 |
+| `record` | 仅记录，不响应 |
+| `ignore` | 完全丢弃 |
+
+### 3.4 Follow-up 机制
+- 机器人回复后开启时间窗口（默认 300 秒）
+- 窗口内用户消息直接触发回复
+- 用于多轮对话场景
+
+---
+
+## 4. 关键约定
+
+### 4.1 ESM 导入路径
+**所有 TypeScript 导入必须使用 `.js` 扩展名**（ESM 运行时要求）:
+
+```typescript
+// ✅ 正确
+import { sendInfoflowMessage } from "../channel/outbound.js";
+
+// ❌ 错误 - 运行时失败
+import { sendInfoflowMessage } from "../channel/outbound";
+```
+
+### 4.2 测试 Mock 路径
+`vi.mock` 路径也需使用 `.js` 扩展名：
+
+```typescript
+vi.mock("../../src/channel/outbound.js", () => ({
+  sendInfoflowMessage: vi.fn().mockResolvedValue({ ok: true }),
+}));
+```
+
+### 4.3 消息 ID 提取
+```typescript
+import { extractIdFromRawJson } from "../channel/outbound.js";
+const messageId = extractIdFromRawJson(rawJsonText, "messageid");
+```
+
+---
+
+## 5. 配置层级
+
+优先级: `groups.<groupId>` > `accounts.<id>` > 顶层默认值
+
+关键配置路径:
+- `channels.infoflow` - 主配置
+- `channels.infoflow.accounts.<id>` - 多账号配置
+- `channels.infoflow.groups.<groupId>` - 群级覆盖
+
+---
+
+## 6. 常用命令
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+npm test -- --watch    # 监视模式
+
+# 部署
+./scripts/deploy.sh
+
+# 查看日志
+openclaw logs | grep infoflow
+tail -f ~/.openclaw/logs/gateway.log | grep -i infoflow
+
+# 调试
+openclaw doctor                    # 检查配置
+openclaw status                    # Channel 状态
+openclaw directory groups infoflow # 列出群 ID
+```
+
+---
+
+## 7. 测试规范
+
+- 测试文件镜像 `src/` 结构于 `tests/` 目录
+- `security/` 函数要求分支覆盖率 ≥ 80%
+- 网络函数需 mock，测试中不发真实 HTTP 请求
+
+---
+
+**报告完成**