feat:初版

2025-12-03 15:48:44 +08:00
commit b4df26f61d
199 changed files with 23434 additions and 0 deletions
--- a/docs/架构设计.md
+++ b/docs/架构设计.md
@@ -0,0 +1,253 @@
+# 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
+- [ ] 实时监控界面