WechatHookBot/docs/架构设计.md

# WechatHookBot 架构设计

## 技术架构

### 四层架构

```
┌─────────────────────────────────────────────────────────────┐
│  第四层：WebUI 层（可选）                                     │
│  Flask + SocketIO + Bootstrap                                │
│  - 插件管理、消息监控、配置管理                               │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│  第三层：插件层（完全复用 XYBot）                             │
│  PluginManager → PluginBase → 具体插件                       │
│  装饰器：@on_text_message, @on_image_message, @schedule     │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│  第二层：Bot 核心层                                           │
│  HookBot - 消息预处理、路由、类型映射                         │
│  EventManager - 事件分发、优先级、阻塞机制                    │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│  第一层：WechatHook 层                                        │
│  WechatHookClient - API 封装                                 │
│  NoveLoader - DLL 调用                                       │
│  回调处理器 - Socket 回调                                     │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│  底层：DLL 层                                                 │
│  Loader.dll ←→ Helper.dll (注入微信进程) ←→ 微信客户端       │
└─────────────────────────────────────────────────────────────┘
```

## 消息流转

### 接收消息流程

```
微信消息
  → Helper.dll (注入微信进程)
  → Socket 回调
  → on_recv_callback(client_id, msg_type, data)
  → HookBot.process_message()
  → 消息类型映射 (type → event)
  → EventManager.emit(event_type, client, message)
  → 插件事件处理器（按优先级执行）
```

### 发送消息流程

```
插件调用
  → client.send_text(wxid, content)
  → WechatHookClient 封装
  → 构造 JSON payload {"type": 11036, "data": {...}}
  → NoveLoader.SendWeChatData()
  → Loader.dll
  → Helper.dll
  → 微信发送
```

## 核心模块

### 1. WechatHook 层

**NoveLoader** - DLL 函数封装
```python
class NoveLoader:
    - InitWeChatSocket()      # 初始化回调
    - InjectWeChat()          # 注入微信
    - SendWeChatData()        # 发送数据
    - DestroyWeChat()         # 销毁连接
```

**WechatHookClient** - API 封装
```python
class WechatHookClient:
    - send_text()             # 发送文本
    - send_image()            # 发送图片
    - send_file()             # 发送文件
    - get_friend_list()       # 获取好友列表
    - get_chatroom_list()     # 获取群聊列表
    - add_friend()            # 添加好友
    # ... 更多 API
```

### 2. Bot 核心层

**HookBot** - 消息处理核心
```python
class HookBot:
    - process_message()       # 处理消息
    - _normalize_message()    # 统一消息格式
    - _filter_message()       # 白名单/黑名单过滤
```

**EventManager** - 事件管理（复用 XYBot）
```python
class EventManager:
    - bind_instance()         # 绑定插件实例
    - emit()                  # 触发事件
    - unbind_instance()       # 解绑实例
```

### 3. 插件层

**PluginBase** - 插件基类（复用 XYBot）
```python
class PluginBase:
    description: str
    author: str
    version: str

    async def on_enable()     # 启用时调用
    async def on_disable()    # 禁用时调用
    async def async_init()    # 异步初始化
```

**装饰器系统**（复用 XYBot）
- `@on_text_message` - 文本消息
- `@on_image_message` - 图片消息
- `@on_voice_message` - 语音消息
- `@on_at_message` - @消息
- `@schedule` - 定时任务

## 消息类型映射

从个微 API 的 type 值映射到内部事件类型：

```python
MESSAGE_TYPE_MAP = {
    # 需要根据实际 API 文档补充
    10001: "text_message",
    10002: "image_message",
    10003: "voice_message",
    10004: "video_message",
    10005: "file_message",
    10006: "card_message",
    10007: "location_message",
    10008: "link_message",
    10009: "miniapp_message",
    10010: "emoji_message",
    10011: "revoke_message",
    10012: "system_message",
    10013: "friend_request",
    # 群聊通知
    10020: "chatroom_member_add",
    10021: "chatroom_member_remove",
}
```

## 数据库设计

复用 XYBot 的数据库架构：

### XYBotDB (SQLite)
- 用户表 - 用户信息、积分
- 签到表 - 签到记录
- 其他业务表

### MessageDB (SQLite + aiosqlite)
- 消息记录表（可选）

### KeyvalDB (SQLite + aiosqlite)
- 键值存储表
- 用于配置、状态管理

## 配置系统

### main_config.toml

```toml
[WechatHook]
loader-dll = "libs/Loader.dll"
helper-dll = "libs/Helper.dll"

[Bot]
version = "v1.0.0"
admins = ["admin_wxid"]
disabled-plugins = []
timezone = "Asia/Shanghai"

# 消息过滤
ignore-mode = "None"  # None/Whitelist/Blacklist
whitelist = []
blacklist = []

[Database]
xybot-db = "sqlite:///database/hookbot.db"
message-db = "sqlite+aiosqlite:///database/message.db"
keyval-db = "sqlite+aiosqlite:///database/keyval.db"

[WebUI]
admin-username = "admin"
admin-password = "admin123"
session-timeout = 30
```

## 与 XYBot 的对比

| 特性 | XYBot | WechatHookBot |
|------|-------|---------------|
| 底层技术 | 协议实现 | DLL Hook |
| 登录方式 | 二维码/唤醒 | 无需登录 |
| 依赖 | Redis | 无 |
| 消息接收 | sync_message 轮询 | Socket 回调 |
| 插件系统 | ✅ | ✅ 完全兼容 |
| 风控风险 | 中 | 高 |
| 多开支持 | 需多实例 | 原生支持 |
| Python 版本 | 3.11 | 3.x (32位) |

## 优势

1. **架构更简单**：无需 Redis，减少依赖
2. **无需登录**：Hook 已登录微信，省去登录流程
3. **实时性更好**：Socket 回调，无需轮询
4. **代码复用**：80% 代码可复用 XYBot

## 注意事项

1. **32位限制**：DLL 是 32位，必须使用 32位 Python
2. **风控风险**：Hook 方式风控风险较高
3. **依赖微信**：必须有微信客户端在运行
4. **杀软拦截**：DLL 可能被杀毒软件拦截

## 开发路线

### 第一阶段：基础框架
- [ ] WechatHook 层实现
- [ ] HookBot 核心类
- [ ] 消息类型映射
- [ ] 基础 API 封装

### 第二阶段：插件系统
- [ ] 复用 XYBot 插件系统
- [ ] 适配消息格式
- [ ] 测试插件兼容性

### 第三阶段：完善功能
- [ ] 数据库集成
- [ ] 配置系统
- [ ] 日志系统
- [ ] 错误处理

### 第四阶段：WebUI（可选）
- [ ] 复用 XYBot WebUI
- [ ] 适配 Hook API
- [ ] 实时监控界面