WechatHookBot/docs/快速开始.md

快速开始

环境准备

1. 系统要求

• ✅ Windows 系统（Win10/Win11）
• ✅ Python 3.x 32位版本（重要！）
• ✅ 微信客户端已安装并登录

2. 检查 Python 版本

python --version
# 应显示 Python 3.x.x

# 检查是否为 32位
python -c "import sys; print(sys.maxsize > 2**32)"
# 应显示 False（表示 32位）

如果是 64位 Python，需要下载安装 32位版本： https://www.python.org/downloads/

安装步骤

1. 克隆或下载项目

cd D:\project\shrobot
# 项目已在 WechatHookBot 目录

2. 安装依赖

cd WechatHookBot
pip install -r requirements.txt

3. 准备 DLL 文件

将个微大客户版的 DLL 文件放到 libs/ 目录：

WechatHookBot/
  libs/
    Loader.dll
    Helper.dll

4. 配置文件

复制配置模板并修改：

# main_config.toml 已存在，修改以下内容：

[Bot]
admins = ["your_wxid"]  # 改为你的 wxid

运行

方式一：简单启动（无 WebUI）

python bot.py

方式二：完整启动（带 WebUI）

python app.py

然后访问：http://localhost:9999

默认账号：admin / admin123

第一次运行

1. 启动微信：确保微信客户端已登录
2. 运行程序：执行 python bot.py
3. 观察日志：查看是否成功注入微信
4. 测试消息：给机器人发送消息测试

测试插件

创建测试插件

在 plugins/ 目录创建 TestPlugin/ 文件夹：

plugins/
  TestPlugin/
    __init__.py      # 空文件
    main.py

main.py 内容：

from utils.plugin_base import PluginBase
from utils.decorators import *
from WechatHook import WechatHookClient
from loguru import logger

class TestPlugin(PluginBase):
    description = "测试插件"
    author = "Your Name"
    version = "1.0.0"

    @on_text_message
    async def handle_text(self, client: WechatHookClient, message: dict):
        content = message.get("Content", "")
        from_wxid = message.get("FromWxid", "")

        if content == "ping":
            await client.send_text(from_wxid, "pong")
            logger.info("收到 ping，回复 pong")

重启程序，给机器人发送 "ping"，应该会收到 "pong" 回复。

常见问题

1. DLL 注入失败

现象： 提示 "注入微信失败"

解决：

• 确认使用 32位 Python
• 确认微信已登录
• 关闭杀毒软件或添加信任
• 以管理员身份运行

2. 找不到 DLL 文件

现象： "Loader DLL 文件不存在"

解决：

• 检查 libs/ 目录是否有 DLL 文件
• 检查 main_config.toml 中的路径配置

3. 收不到消息

现象： 程序运行正常但收不到消息

解决：

• 检查是否启用了白名单/黑名单过滤
• 查看日志是否有错误信息
• 确认插件已正确加载

4. 发送消息失败

现象： 调用 send_text 返回 False

解决：

• 检查 wxid 是否正确
• 检查是否是好友/群成员
• 查看日志中的详细错误信息

获取 wxid

方法一：通过日志

运行程序后，给机器人发送消息，在日志中可以看到：

收到消息: FromWxid=wxid_xxx, Content=...

方法二：通过 API

创建临时插件打印所有消息：

@on_text_message
async def handle_text(self, client, message):
    logger.info(f"消息详情: {message}")

下一步

• 📖 阅读 插件开发指南
• 🏗️ 了解 架构设计
• 📚 查看 API 文档
• 🔌 开发自己的插件

获取帮助

如遇到问题，请：

1. 查看日志文件 logs/hookbot.log
2. 检查配置文件是否正确
3. 确认环境要求是否满足
4. 查看项目文档