WechatHookBot/Memory Bank/systemPatterns.md

系统模式和最佳实践

代码模式

1. DLL 函数调用模式

# 通过内存偏移调用未导出函数
def __get_non_exported_func(self, offset: int, arg_types, return_type):
    func_addr = self.loader_module_base + offset
    func_type = ctypes.WINFUNCTYPE(return_type, *arg_types)
    return func_type(func_addr)

2. 回调装饰器模式

@CONNECT_CALLBACK(in_class=True)
def on_connect(self, client_id):
    # 处理连接
    pass

@RECV_CALLBACK(in_class=True)
def on_receive(self, client_id, message_type, data):
    # 处理消息
    pass

3. 异步 API 封装模式

async def send_text(self, to_wxid: str, content: str) -> bool:
    payload = {"type": 11036, "data": {"to_wxid": to_wxid, "content": content}}
    return await asyncio.to_thread(
        self.loader.SendWeChatData,
        self.client_id,
        json.dumps(payload, ensure_ascii=False)
    )

4. 消息类型映射模式

MESSAGE_TYPE_MAP = {
    10001: "text_message",
    10002: "image_message",
}

event_type = MESSAGE_TYPE_MAP.get(msg_type)
if event_type:
    await EventManager.emit(event_type, client, message)

5. 插件事件处理模式

@on_text_message(priority=50)
async def handle_text(self, client, message):
    # 处理逻辑
    return True  # 继续执行后续处理器

架构模式

分层架构

应用层 (Plugins)
    ↓
业务层 (HookBot)
    ↓
服务层 (WechatHookClient)
    ↓
基础层 (NoveLoader)
    ↓
系统层 (DLL)

事件驱动模式

消息接收 → 回调触发 → 类型映射 → 事件分发 → 插件处理

命名规范

文件命名

• 模块文件：小写下划线 loader.py, message_types.py
• 类文件：大驼峰 WechatHookClient, HookBot

变量命名

• 常量：大写下划线 MESSAGE_TYPE_MAP
• 变量：小写下划线 client_id, msg_type
• 类名：大驼峰 NoveLoader
• 函数：小写下划线 send_text()

API 命名

• 发送类：send_xxx() - send_text, send_image
• 获取类：get_xxx() - get_friend_list, get_chatroom_info
• 设置类：set_xxx() - set_friend_remark

错误处理模式

API 调用错误处理

try:
    result = await client.send_text(wxid, content)
    if result:
        logger.info("发送成功")
    else:
        logger.error("发送失败")
except Exception as e:
    logger.error(f"发送异常: {e}")

DLL 调用错误处理

if not os.path.exists(dll_path):
    logger.error(f"DLL 文件不存在: {dll_path}")
    return False

日志模式

日志级别使用

logger.debug("调试信息")      # 详细的调试信息
logger.info("普通信息")       # 一般信息
logger.success("成功信息")    # 操作成功
logger.warning("警告信息")    # 警告但不影响运行
logger.error("错误信息")      # 错误需要关注

日志格式

logger.info(f"收到消息: FromWxid={from_wxid}, Content={content}")

配置模式

TOML 配置读取

import tomllib

with open("main_config.toml", "rb") as f:
    config = tomllib.load(f)

value = config.get("section", {}).get("key", default_value)

数据库模式

异步数据库操作

from database.keyvalDB import KeyvalDB

keyval_db = KeyvalDB()
await keyval_db.set("key", "value")
value = await keyval_db.get("key")

测试模式

远程测试流程

1. 实现功能代码
2. 添加详细日志
3. 提交给用户测试
4. 根据反馈修复
5. 重复直到通过

需要用户提供的测试信息

• API 返回的实际数据格式
• 消息的实际 type 值
• 错误信息和日志
• 功能是否正常工作

代码复用模式

从 XYBot 复用

# 完全复用（不修改）
- utils/plugin_base.py
- utils/plugin_manager.py
- utils/event_manager.py
- utils/decorators.py
- utils/singleton.py
- database/

# 参考实现（需修改）
- utils/xybot.py → utils/hookbot.py

性能优化模式

异步并发

# 并发执行多个任务
tasks = [
    client.send_text(wxid1, msg1),
    client.send_text(wxid2, msg2),
]
results = await asyncio.gather(*tasks)

消息队列

# 避免消息发送过快
await asyncio.sleep(0.5)  # 每条消息间隔

安全模式

路径处理

# 使用绝对路径
path = os.path.realpath(relative_path)

参数验证

if not wxid or not content:
    logger.error("参数不能为空")
    return False

扩展模式

添加新消息类型

1. 在 message_types.py 添加映射
2. 在 decorators.py 添加装饰器（如需要）
3. 在 client.py 添加发送方法（如需要）

添加新 API

1. 在 client.py 添加方法
2. 构造正确的 payload
3. 调用 SendWeChatData
4. 处理返回结果