wechaty-web-panel 1.6.113 → 1.6.114

package/ARCHITECTURE.md

@@ -0,0 +1,683 @@
+# Wechaty Web Panel 项目架构文档
+
+## 项目概述
+
+Wechaty Web Panel 是一个功能完整的微信机器人管理和 AI 集成平台，基于 Wechaty 框架，支持多种 AI 服务、复杂的消息处理逻辑、定时任务调度和高级数据分析能力。
+
+---
+
+## 1. 目录结构
+
+```
+wechaty-web-panel/
+├── src/                          # 源代码主目录
+│   ├── index.js                 # 插件入口文件
+│   ├── package-json.js          # 版本管理
+│   ├── bot/                     # 机器人集成模块（多AI平台）
+│   │   ├── chatgpt/            # ChatGPT集成
+│   │   ├── dify/               # Dify平台集成
+│   │   ├── fastgpt/            # FastGPT集成
+│   │   ├── coze/               # Coze集成
+│   │   └── qanything/          # QAnything集成
+│   ├── botInstance/            # AI机器人实例管理
+│   │   ├── dify.js            # Dify AI客户端
+│   │   ├── cozev3.js          # Coze V3客户端
+│   │   ├── fastgpt.js         # FastGPT客户端
+│   │   ├── officialOpenAi.js  # OpenAI官方API
+│   │   ├── gpt4v.js           # GPT-4V视觉模型
+│   │   └── sdk/               # 各种AI SDK
+│   ├── handlers/               # Wechaty事件处理器
+│   │   ├── on-message.js       # 消息处理（核心~25KB）
+│   │   ├── on-login.js         # 登录处理
+│   │   ├── on-friend.js        # 好友请求处理
+│   │   ├── on-roomjoin.js      # 群聊加入处理
+│   │   ├── on-scan.js          # 扫码处理
+│   │   └── on-*.js             # 其他事件处理
+│   ├── proxy/                  # 代理层（API调用）
+│   │   ├── aibotk.js           # 与aibotk服务通信
+│   │   ├── openAi.js           # OpenAI API代理
+│   │   ├── difyAi.js           # Dify API代理
+│   │   ├── cozeAi.js           # Coze API代理
+│   │   ├── mqtt.js             # MQTT通信
+│   │   └── bot/                # 机器人类型分发器
+│   │       └── dispatch.js     # 机器人分发逻辑
+│   ├── db/                     # 数据持久化层
+│   │   ├── nedb.js             # NeDB数据库封装
+│   │   ├── global.js           # 全局配置存储
+│   │   ├── configDb.js         # 配置数据库
+│   │   ├── chatHistory.js      # 聊天历史
+│   │   ├── aichatDb.js         # AI对话记录
+│   │   ├── userDb.js           # 用户信息
+│   │   ├── roomDb.js           # 群信息
+│   │   └── gptConfig.js        # GPT配置
+│   ├── service/                # 业务服务层
+│   │   ├── event-dispatch-service.js    # 事件分发
+│   │   ├── room-async-service.js        # 群聊同步
+│   │   ├── msg-filters.js               # 消息过滤
+│   │   ├── msg-filter-service.js        # 过滤服务
+│   │   └── gpt4vService.js              # GPT-4V服务
+│   ├── mcp/                    # Model Context Protocol服务
+│   │   ├── src/
+│   │   │   ├── mcp/            # MCP服务器实现
+│   │   │   │   └── server.js   # MCP标准服务器
+│   │   │   ├── models/         # 数据模型
+│   │   │   │   ├── Friend.js   # 好友模型
+│   │   │   │   ├── Group.js    # 群组模型
+│   │   │   │   ├── GroupMember.js  # 群成员模型
+│   │   │   │   └── ChatMessage.js  # 消息模型
+│   │   │   ├── services/       # MCP服务
+│   │   │   │   ├── ChatDataService.js   # 数据服务
+│   │   │   │   ├── McpService.js       # 查询服务
+│   │   │   │   └── McpTools.js         # 工具方法
+│   │   │   └── config/
+│   │   │       └── database.js # PostgreSQL配置
+│   │   └── mcp-server.js       # 核心MCP服务器
+│   ├── task/                   # 定时任务模块
+│   │   ├── index.js            # 任务管理
+│   │   └── rss.js              # RSS订阅任务
+│   ├── common/                 # 通用工具
+│   │   ├── index.js            # 消息发送工具
+│   │   ├── reply.js            # 回复处理
+│   │   ├── hook.js             # 钩子机制
+│   │   └── multiReply.js       # 多回复处理
+│   ├── lib/                    # 实用函数库
+│   │   ├── index.js            # 主要工具函数（定时、加密等）
+│   │   ├── contentCensor.js    # 内容审查
+│   │   └── oss.js              # 对象存储
+│   └── const/                  # 常量定义
+│       └── puppet-type.js      # Puppet类型定义
+├── test/                        # 测试文件
+├── .github/                     # GitHub CI/CD配置
+├── tsconfig.json               # TypeScript配置
+├── package.json                # 项目依赖配置
+├── .eslintrc.js               # ESLint配置
+├── .prettierrc                 # Prettier配置
+└── verpub.config.js           # 版本发布配置
+```
+
+---
+
+## 2. 核心模块功能
+
+### 2.1 插件入口系统
+
+**文件**: [src/index.js](src/index.js)
+
+导出三个主要插件：
+- `WechatyWebPanelPlugin`：主插件，处理所有Wechaty事件
+- `WechatyMessageRecordPlugin`：消息记录插件
+- `WechatyMessageCallBackPlugin`：消息回调插件
+
+支持通过环境变量配置：`AIBOTK_KEY`和`AIBOTK_SECRET`
+
+### 2.2 事件处理系统
+
+**核心文件**: [src/handlers/on-message.js](src/handlers/on-message.js)
+
+消息处理核心功能：
+- 支持私聊和群聊消息分离处理
+- 集成多种AI回复方式（GPT、Dify、FastGPT等）
+- 消息过滤机制（关键词检测）
+- 文件处理和视觉识别
+
+**其他事件处理器**：
+- [on-login.js](src/handlers/on-login.js)：登录后获取配置、初始化MQTT、更新用户信息
+- [on-friend.js](src/handlers/on-friend.js)：好友请求处理
+- [on-roomjoin.js](src/handlers/on-roomjoin.js)：群加入事件
+- [on-record-message.js](src/handlers/on-record-message.js)：消息记录
+- [on-callback-message.js](src/handlers/on-callback-message.js)：回调事件处理
+
+### 2.3 AI机器人集成层
+
+**目录**: [src/botInstance/](src/botInstance/)
+
+支持多种AI平台，每个都有独立的客户端类：
+
+| AI平台 | 文件 | 功能 |
+|--------|------|------|
+| Dify | [dify.js](src/botInstance/dify.js) | LLM应用平台集成 |
+| Coze V2 | [coze.js](src/botInstance/coze.js) | 字节AI平台（已废弃） |
+| Coze V3 | [cozev3.js](src/botInstance/cozev3.js) | 字节AI新版本 |
+| FastGPT | [fastgpt.js](src/botInstance/fastgpt.js) | 开源LLM应用 |
+| OpenAI | [officialOpenAi.js](src/botInstance/officialOpenAi.js) | OpenAI官方API |
+| GPT-4V | [gpt4v.js](src/botInstance/gpt4v.js) | 视觉识别模型 |
+| Q-Anything | [qany.js](src/botInstance/qany.js) | 本地知识库 |
+
+每个客户端都支持：
+- 初始化和配置管理
+- Token和API密钥管理
+- 流式和非流式响应
+- 内容审查和过滤
+
+### 2.4 消息分发系统
+
+**文件**: [src/proxy/bot/dispatch.js](src/proxy/bot/dispatch.js)
+
+根据botType分发消息到不同AI平台：
+- 支持13+种机器人类型
+- 上下文变量传递（userId、isMention、room信息等）
+- 文件处理管道
+
+### 2.5 数据持久化层
+
+**目录**: [src/db/](src/db/)
+
+两套数据存储系统：
+
+#### 本地存储（NeDB）
+- 轻量级嵌入式数据库
+- 存储配置、AI聊天记录、用户信息
+- 支持查询、排序、分页
+
+**核心文件**:
+- [nedb.js](src/db/nedb.js)：数据库抽象层
+- [global.js](src/db/global.js)：全局配置存储
+- [chatHistory.js](src/db/chatHistory.js)：聊天历史
+
+#### PostgreSQL（MCP服务）
+- 用于生产级数据分析
+- 存储结构化的聊天数据
+- Sequelize ORM映射
+
+### 2.6 MCP服务（Model Context Protocol）
+
+**目录**: [src/mcp/](src/mcp/)
+
+提供高级查询和数据分析能力：
+
+| 功能 | 说明 |
+|------|------|
+| 好友管理 | 搜索、批量创建、批量删除 |
+| 群组管理 | 群信息检索、成员分析 |
+| 消息查询 | 全文搜索、热力图分析 |
+| 关系分析 | 会话详情、用户关系图 |
+| 活动分析 | 消息频率、活跃度统计 |
+| 内容分析 | 话题提取、情感分析 |
+| 数据导出 | CSV、JSON导出 |
+
+**核心模型** ([src/mcp/src/models/](src/mcp/src/models/)):
+- [Friend.js](src/mcp/src/models/Friend.js)：好友信息
+- [Group.js](src/mcp/src/models/Group.js)：群信息
+- [GroupMember.js](src/mcp/src/models/GroupMember.js)：群成员
+- [ChatMessage.js](src/mcp/src/models/ChatMessage.js)：消息记录
+
+### 2.7 代理层
+
+**目录**: [src/proxy/](src/proxy/)
+
+- [aibotk.js](src/proxy/aibotk.js)：与AiBotK后端服务通信
+  - 获取/更新配置
+  - 发送机器人信息
+  - 二维码管理
+  - Qiniu云存储集成
+
+- 其他代理：
+  - [openAi.js](src/proxy/openAi.js), [difyAi.js](src/proxy/difyAi.js), [cozeAi.js](src/proxy/cozeAi.js)：各平台API调用
+  - [mqtt.js](src/proxy/mqtt.js)：实时消息推送
+  - [multimodal.js](src/proxy/multimodal.js)：多模态处理（语音转文字、文字转语音）
+
+### 2.8 定时任务系统
+
+**目录**: [src/task/](src/task/)
+
+- [index.js](src/task/index.js)：任务调度和执行
+  - 支持三种提醒：当天、每天、指定日期
+  - 使用node-schedule库
+  - 支持群发、群内同步
+
+- [rss.js](src/task/rss.js)：RSS订阅和推送
+
+### 2.9 服务层
+
+**目录**: [src/service/](src/service/)
+
+- [event-dispatch-service.js](src/service/event-dispatch-service.js)：事件分发和路由
+- [room-async-service.js](src/service/room-async-service.js)：群聊消息同步
+- [msg-filters.js](src/service/msg-filters.js)：复杂消息过滤逻辑
+- [gpt4vService.js](src/service/gpt4vService.js)：视觉识别处理
+
+---
+
+## 3. 技术栈
+
+### 3.1 核心框架
+
+| 类别 | 技术 | 版本 |
+|------|------|------|
+| 运行时 | Node.js | >=16 |
+| 包管理 | npm | >=7 |
+| 语言 | JavaScript (ES Module) | esnext |
+| 类型检查 | TypeScript | ^5.4 |
+
+### 3.2 Wechaty生态
+
+```json
+{
+  "@juzi/wechaty": "^1.0.108",
+  "@juzi/wechaty-puppet": "^1.0.100",
+  "@juzi/wechaty-puppet-service": "^1.0.105",
+  "wechaty-puppet-matrix": "^0.0.34",
+  "wechaty-puppet-wechat4u": "^1.14.12"
+}
+```
+
+### 3.3 AI和LLM集成
+
+```json
+{
+  "@langchain/core": "^0.3.40",
+  "@langchain/openai": "^0.4.4",
+  "@langchain/community": "^0.3.32",
+  "@langchain/redis": "^0.1.1",
+  "@dqbd/tiktoken": "^1.0.2",
+  "@coze/api": "^1.0.19"
+}
+```
+
+### 3.4 数据存储
+
+```json
+{
+  "sequelize": "^6.37.0",
+  "pg": "^8.11.0",
+  "pg-hstore": "^2.3.4",
+  "nedb": "^1.8.0",
+  "keyv": "^4.5.2"
+}
+```
+
+### 3.5 API和通信
+
+```json
+{
+  "@modelcontextprotocol/sdk": "^1.17.0",
+  "express": "^5.1.0",
+  "cors": "^2.8.5",
+  "axios": "1.8.2",
+  "mqtt": "^4.2.6",
+  "superagent": "^5.3.1",
+  "node-fetch": "^2.6.9"
+}
+```
+
+### 3.6 工具和实用库
+
+```json
+{
+  "dayjs": "^1.11.7",
+  "node-schedule": "^1.3.2",
+  "uuid": "^9.0.0",
+  "zod": "^3.25.76",
+  "jsonwebtoken": "^9.0.2",
+  "mustache": "^4.2.0",
+  "rss-parser": "^3.13.0"
+}
+```
+
+### 3.7 云服务集成
+
+```json
+{
+  "@aws-sdk/client-s3": "^3.828.0",
+  "ali-oss": "^6.21.0",
+  "baidu-aip-sdk": "^4.16.10"
+}
+```
+
+---
+
+## 4. 核心流程
+
+### 4.1 插件初始化流程
+
+```
+插件导出
+  ↓
+WechatyWebPanelPlugin({apiKey, apiSecret, ignoreMessages, ignoreEvents})
+  ↓
+设置全局配置（global.js）
+  ↓
+返回初始化函数
+  ↓
+bot.use(plugin) 绑定到Wechaty
+  ↓
+注册事件监听器
+  └── on('scan') → onScan
+  └── on('login') → onLogin
+  └── on('message') → onMessage
+  └── on('friendship') → onFriend
+  └── on('room-join') → onRoomjoin
+  └── ... 其他事件
+```
+
+### 4.2 消息处理流程
+
+详见 [src/handlers/on-message.js](src/handlers/on-message.js)
+
+```
+收到消息事件
+  ↓
+消息类型检查 → 系统消息/文本/链接/文件/图片
+  ↓
+私聊消息处理
+  ├── 检查忽略列表
+  ├── 获取AI配置
+  ├── 调用dispatchBot()
+  └── 获取AI回复
+
+群聊消息处理
+  ├── 检查@提及
+  ├── 消息过滤（自定义规则）
+  ├── 关键词匹配
+  ├── 事件分发
+  └── 定时任务触发
+
+消息记录
+  └── addRoomRecord() / addChatRecord()
+
+发送回复
+  └── contactSay() / roomSay()
+```
+
+### 4.3 登录流程
+
+详见 [src/handlers/on-login.js](src/handlers/on-login.js)
+
+```
+登录成功
+  ↓
+获取配置文件 → getConfig()
+  ↓
+更新puppet类型信息
+  ↓
+保存用户信息 → addUser()
+  ↓
+处理用户头像 → putqn()
+  ↓
+初始化MQTT连接 → initMqtt()
+  ↓
+版本检查和更新提醒
+```
+
+### 4.4 AI回复流程
+
+详见 [src/proxy/bot/dispatch.js](src/proxy/bot/dispatch.js)
+
+```
+进入dispatchBot()
+  ↓
+根据botType判断AI平台
+  ├── case 6: ChatGPT API
+  ├── case 8: Dify
+  ├── case 9: FastGPT
+  ├── case 11: Coze V2
+  ├── case 12: Coze V3
+  ├── case 13: Q-Anything
+  └── ...其他类型
+
+调用对应AI客户端
+  ↓
+传递上下文变量
+  ├── userId: 用户ID
+  ├── isMention: 是否@
+  ├── roomId/roomName: 群信息
+  ├── file: 文件信息
+  └── inputs/variables: 平台特定参数
+
+处理流式响应
+  ↓
+内容审查和过滤
+  ↓
+返回回复数组 [{type, content, url}, ...]
+```
+
+### 4.5 MCP服务流程
+
+详见 [src/mcp/mcp-server.js](src/mcp/mcp-server.js)
+
+```
+ChatMcpServer初始化
+  ↓
+setupHandlers() 注册工具处理器
+  ↓
+ListToolsRequestSchema: 列举可用工具
+  ├── search_friends
+  ├── search_groups
+  ├── search_messages
+  └── 20+其他工具
+
+CallToolRequestSchema: 执行工具
+  ├── 参数验证 (Zod schema)
+  ├── 调用对应服务
+  └── 返回结果
+```
+
+---
+
+## 5. 配置文件说明
+
+### 5.1 TypeScript配置
+
+**文件**: [tsconfig.json](tsconfig.json)
+
+- **编译目标**：ES Next（现代JavaScript）
+- **模块系统**：ESM（ES Modules）
+- **输出目录**：`dist/`
+- **严格模式**：启用所有strict检查
+- **装饰器支持**：启用（用于Sequelize ORM）
+- **Source Map**：生成，便于调试
+
+### 5.2 包管理配置
+
+**文件**: [package.json](package.json)
+
+- **入口点**：`dist/index.js`（ES Module）
+- **关键脚本**：
+  - `npm run build`：TypeScript编译
+  - `npm run dist`：完整构建
+  - `npm run test:wechat`：测试微信
+  - `npm run test:wework`：测试企业微信
+  - `npm run release`：发布到npm
+  - `npm run db:migrate`：数据库迁移
+
+### 5.3 代码风格配置
+
+**文件**: [.prettierrc](.prettierrc)
+
+```json
+{
+  "printWidth": 300,      // 每行300字符（长行代码）
+  "tabWidth": 2,          // 缩进2空格
+  "semi": false,          // 不使用分号
+  "singleQuote": true,    // 单引号
+  "arrowParens": "always" // 箭头函数参数总使用括号
+}
+```
+
+### 5.4 ESLint配置
+
+**文件**: [.eslintrc.js](.eslintrc.js)
+
+- 基于Prettier推荐配置
+- 禁用console和未使用变量的警告
+- 支持Node.js ES6环境
+
+---
+
+## 6. 核心类和接口
+
+### 6.1 全局配置类
+
+**文件**: [src/db/global.js](src/db/global.js)
+
+```javascript
+class Config {
+  apiKey: string              // API密钥
+  qrcodeKey: string           // 企微二维码
+  verifyCode: string          // 企微验证码
+  gptconfig: Array            // GPT配置列表
+  allTasks: Array             // 所有任务列表
+
+  // 方法
+  getApikey() / setApikey(val)
+  getGptConfigById(id)
+  updateOneGptConfig(id, info)
+}
+```
+
+### 6.2 数据库抽象
+
+**文件**: [src/db/nedb.js](src/db/nedb.js)
+
+```javascript
+class DB {
+  find(query, select): Promise<Array>     // 查询多条
+  findOne(query, select): Promise<Object> // 查询单条
+  insert(values): Promise<Object>         // 插入
+  update(query, values): Promise<Number>  // 更新
+  remove(query): Promise<Number>          // 删除
+  sort(orderby) / limit(offset, limit)    // 链式调用
+}
+```
+
+### 6.3 MCP数据模型
+
+**目录**: [src/mcp/src/models/](src/mcp/src/models/)
+
+使用Sequelize ORM定义：
+- **Friend**：好友信息（robotId, wxid, name, avatar, alias, tags）
+- **Group**：群信息（robotId, wxid, topic, memberCount）
+- **GroupMember**：群成员（robotId, roomWxid, wxid, name, alias）
+- **ChatMessage**：消息记录（robotId, conversationId, content, type, timestamp）
+
+---
+
+## 7. 通信协议
+
+### 7.1 内部通信
+
+- **与AiBotK服务**：HTTP/HTTPS (REST API)
+  - 获取配置文件
+  - 上报机器人状态
+  - 管理二维码和验证
+
+- **MQTT实时推送**：连接AiBotK消息队列
+  - 接收远程指令
+  - 实时配置更新
+
+### 7.2 AI平台调用
+
+- **OpenAI**：官方API + 代理支持
+- **Dify**：HTTP StreamAPI（流式响应）
+- **FastGPT**：HTTP API（支持流式）
+- **Coze**：官方SDK + 自定义客户端
+- **LangChain**：统一LLM接口
+
+### 7.3 数据库通信
+
+- **NeDB**：本地进程内通信（无网络）
+- **PostgreSQL**：TCP连接（MCP服务）
+- **Redis**：缓存层（LangChain Redis集成）
+
+---
+
+## 8. 构建和部署
+
+### 8.1 构建流程
+
+```bash
+npm run build
+  ↓
+TypeScript编译 (tsc)
+  ↓
+输出到 dist/ 目录
+  ↓
+生成 dist/index.js 等JavaScript文件
+```
+
+### 8.2 发布流程
+
+```bash
+npm run release
+  ↓
+verpub工具验证版本
+  ↓
+发布到npm Registry
+  ↓
+创建Git标签：{name}@{version}
+```
+
+### 8.3 测试
+
+```bash
+npm run test:wechat  # 微信Puppet测试
+npm run test:wework  # 企业微信测试
+```
+
+---
+
+## 9. 扩展点
+
+项目设计了多个易于扩展的点：
+
+1. **新AI平台**：在 [src/botInstance/](src/botInstance/) 和 [src/proxy/](src/proxy/) 中添加新类
+2. **新事件类型**：在 [src/handlers/](src/handlers/) 中添加 `on-xxx.js` 文件
+3. **新过滤规则**：在 [src/service/msg-filters.js](src/service/msg-filters.js) 中添加
+4. **新数据模型**：使用MCP的Sequelize模型，在 [src/mcp/src/models/](src/mcp/src/models/) 中定义
+5. **新定时任务**：在 [src/task/](src/task/) 中添加
+6. **MCP工具**：在 [src/mcp/src/mcp/schemas.js](src/mcp/src/mcp/schemas.js) 和 [src/mcp/src/mcp/server.js](src/mcp/src/mcp/server.js) 中定义
+
+---
+
+## 10. 核心流程总结
+
+| 流程 | 关键文件 | 说明 |
+|------|---------|------|
+| 插件初始化 | [src/index.js](src/index.js) | 绑定事件监听器 |
+| 消息处理 | [src/handlers/on-message.js](src/handlers/on-message.js) | 核心消息分发 |
+| AI回复 | [src/proxy/bot/dispatch.js](src/proxy/bot/dispatch.js) | 调用AI平台 |
+| 数据存储 | [src/db/](src/db/) | 本地或数据库存储 |
+| 定时任务 | [src/task/index.js](src/task/index.js) | 调度执行 |
+| MCP查询 | [src/mcp/](src/mcp/) | 高级数据分析 |
+| 事件分发 | [src/service/event-dispatch-service.js](src/service/event-dispatch-service.js) | 自定义事件处理 |
+
+---
+
+## 11. 项目特色
+
+1. **多AI平台支持**：无缝集成13+种AI服务
+2. **灵活的消息处理**：支持复杂的过滤规则和事件分发机制
+3. **高级数据分析**：通过MCP服务提供强大的查询和分析能力
+4. **双存储系统**：本地NeDB用于快速访问，PostgreSQL用于生产级分析
+5. **定时任务调度**：支持灵活的提醒和RSS订阅
+6. **实时通信**：MQTT支持远程控制和配置更新
+7. **插件化架构**：易于扩展和定制
+
+---
+
+## 附录：关键依赖版本
+
+### 核心依赖
+- Node.js: >=16
+- TypeScript: ^5.4
+- Wechaty: ^1.0.108
+
+### AI相关
+- @langchain/core: ^0.3.40
+- @langchain/openai: ^0.4.4
+- @coze/api: ^1.0.19
+
+### 数据存储
+- sequelize: ^6.37.0
+- pg: ^8.11.0
+- nedb: ^1.8.0
+
+### 通信
+- express: ^5.1.0
+- axios: 1.8.2
+- mqtt: ^4.2.6
+
+---
+
+**文档生成时间**: 2026-01-14
+**项目版本**: 参见 [package.json](package.json)