# 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)