# WechatHookBot 功能与指令总结

> 基于微信 Hook API 的智能机器人框架，采用 HTTP 协议通信

## 目录

- [核心架构](#核心架构)
- [基础功能](#基础功能)
- [AI 对话功能](#ai-对话功能)
- [AI 绘图功能](#ai-绘图功能)
- [AI 视频生成](#ai-视频生成)
- [娱乐功能](#娱乐功能)
- [实用工具](#实用工具)
- [群聊管理](#群聊管理)
- [签到系统](#签到系统)
- [系统管理](#系统管理)
- [LLM 工具集成](#llm-工具集成)
- [配置说明](#配置说明)

---

## 核心架构

### 技术栈
- **通信协议**: HTTP RESTful API + HTTP 回调服务器
- **API 地址**: `http://127.0.0.1:61108` (可配置)
- **回调地址**: `http://IP:PORT/vxapi`
- **插件系统**: 基于装饰器的模块化插件架构
- **数据库**: SQLite (消息记录、键值存储)
- **缓存**: Redis (可选)

### 消息处理流程
1. Hook 推送消息到回调服务器 `/vxapi`
2. 消息标准化处理 (MessageNormalizer)
3. 消息入队 (PriorityMessageQueue)
4. 事件分发到各插件处理器
5. 按优先级执行插件响应

---

## 基础功能

### 菜单帮助 (Menu)
| 指令 | 说明 |
|------|------|
| `/菜单` | 显示功能菜单 |
| `/帮助` | 显示帮助信息 |
| `/help` | 英文帮助 |
| `/menu` | 英文菜单 |

### 插件管理 (ManagePlugin)
> 仅管理员可用

| 指令 | 说明 |
|------|------|
| `/插件列表` | 查看所有插件状态 |
| `/重载插件 <插件名>` | 重新加载指定插件 |
| `/启用插件 <插件名>` | 启用指定插件 |
| `/禁用插件 <插件名>` | 禁用指定插件 |

---

## AI 对话功能

### 智能对话 (AIChat)
- **触发方式**: @机器人 或 私聊
- **功能**: 基于大语言模型的智能对话
- **支持**: 多轮对话、上下文记忆

### 智能自动回复 (AutoReply)
- **触发方式**: 自动检测需要回复的消息
- **架构**: 双 LLM 架构 (判断 + 回复)
- **功能**: 智能判断是否需要回复，自动生成回复内容

---

## AI 绘图功能

### Flow2API 绘图
| 指令 | 说明 |
|------|------|
| `/绘画f <提示词>` | 生成图片 |
| `/绘画f横屏 <提示词>` | 横屏图片 (16:9) |
| `/绘画f竖屏 <提示词>` | 竖屏图片 (9:16) |
| 引用图片 + `/绘画f <提示词>` | 图生图 |

### NanoImage 绘图
| 指令 | 说明 |
|------|------|
| `/绘画n <提示词>` | 使用 OpenAI 格式 API 生成图片 |

### ZImageTurbo 绘图
| 指令 | 说明 |
|------|------|
| `/z绘图 <提示词>` | 使用 Z-Image-Turbo 生成图片 |

---

## AI 视频生成

### Sora2API 视频
| 指令 | 说明 |
|------|------|
| `/sora <提示词>` | 生成 AI 视频 |
| `/sora横屏 <提示词>` | 横屏视频 |
| `/sora竖屏 <提示词>` | 竖屏视频 |

### GrokVideo 视频
| 指令 | 说明 |
|------|------|
| `/视频 <提示词>` | 基于引用图片生成视频 |

> 注意: GrokVideo 需要先引用一张图片

---

## 娱乐功能

### 随机图片 (RandomImage)
| 指令 | 说明 |
|------|------|
| `随机图片` | 随机美图 |
| `图来` | 随机图片 |
| `黑丝` | 黑丝图片 |
| `白丝` | 白丝图片 |

### 随机视频 (RandomVideo)
| 指令 | 说明 |
|------|------|
| `随机视频` | 随机短视频 |
| `小姐姐视频` | 小姐姐短视频 |

### 舔狗日记 (DogDiary)
| 触发词 | 说明 |
|--------|------|
| `舔狗` | 获取舔狗日记 |
| `舔狗日记` | 获取舔狗日记 |

### KFC 文案 (KFC)
| 触发词 | 说明 |
|--------|------|
| `疯狂星期四` | 获取 KFC 文案 |
| `KFC` | 获取 KFC 文案 |
| `V我50` | 获取 KFC 文案 |

### 复读姬 (Repeater)
- **功能**: 自动复读群聊中的连续相同消息
- **触发**: 群内连续多人发送相同消息时自动复读

---

## 实用工具

### 60秒新闻 (News60s)
| 指令 | 说明 |
|------|------|
| `60秒` | 获取60秒读懂世界新闻 |
| `新闻` | 获取今日新闻 |

### 点歌 (Music)
| 指令 | 说明 |
|------|------|
| `点歌 <歌名>` | 搜索并发送歌曲 |

### 短视频解析 (VideoParser)
- **功能**: 自动解析抖音、快手等短视频链接
- **触发**: 发送包含短视频链接的消息

### 短剧搜索 (PlayletSearch)
| 指令 | 说明 |
|------|------|
| `/搜索短剧 <名称>` | 搜索短剧资源 |

### Epic 免费游戏 (EpicFreeGames)
| 触发词 | 说明 |
|--------|------|
| `喜加一` | 获取 Epic 免费游戏 |
| `Epic` | 获取 Epic 免费游戏 |
| `免费游戏` | 获取 Epic 免费游戏 |

### 群聊总结 (ChatRoomSummary)
| 指令 | 说明 |
|------|------|
| `/总结` | 总结今日群聊内容 |
| `/群聊总结` | 总结群聊内容 |
| `/昨日总结` | 总结昨日群聊内容 |

---

## 群聊管理

### 新人欢迎 (GroupWelcome)
- **功能**: 新成员加入群聊时自动发送欢迎消息
- **触发**: 自动检测新成员入群事件

### 退群通知 (GroupLeave)
- **功能**: 成员退出群聊时发送通知
- **触发**: 自动检测成员退群事件

---

## 签到系统

### 普通签到 (SignInPlugin)
| 指令 | 说明 |
|------|------|
| `签到` | 每日签到 |

### 鹿打卡 (DeerCheckin)
| 指令 | 说明 |
|------|------|
| `🦌` | 鹿打卡 |
| `🦌日历` | 查看打卡日历 |
| `🦌帮助` | 查看打卡帮助 |
| `🦌补签 <月> <日>` | 补签指定日期 |

---

## 系统管理

### 性能监控 (PerformanceMonitor)
| 指令 | 说明 |
|------|------|
| `/性能` | 查看系统性能 |
| `/stats` | 查看统计信息 |
| `/状态` | 查看运行状态 |

### MCP 管理 (MCPManager)
| 指令 | 说明 |
|------|------|
| `/mcp status` | 查看 MCP 服务器状态 |
| `/mcp list` | 列出可用工具 |
| `/mcp reload` | 重载 MCP 配置 |

### 消息记录 (MessageLogger)
- **功能**: 自动记录所有消息到 MySQL 数据库
- **存储**: 消息内容、发送者、时间、图片(MinIO)
- **用途**: 群聊总结、消息查询

---

## LLM 工具集成

以下插件作为 LLM 工具，可在 AI 对话中自动调用：

### Tavily 搜索 (TavilySearch)
- **功能**: AI 对话中的联网搜索能力
- **调用**: AI 自动判断是否需要搜索

### 旅行规划 (TravelPlanner)
- **功能**: 基于高德 API 的旅行规划
- **调用**: AI 对话中提及旅行相关话题时自动调用

---

## 配置说明

### 主配置文件 (`main_config.toml`)

```toml
[HttpHook]
api-url = "http://127.0.0.1:61108"    # Hook API 地址
callback-host = "0.0.0.0"              # 回调监听地址
callback-port = 80                      # 回调监听端口

[Bot]
admins = ["wxid_xxx"]                   # 管理员 wxid
disabled-plugins = []                   # 禁用的插件
ignore-mode = "None"                    # 消息过滤模式
whitelist = []                          # 白名单
blacklist = []                          # 黑名单

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

[Performance]
log_level_console = "INFO"
log_sampling_rate = 1.0

[Concurrency]
message_interval_ms = 200               # 消息间隔(毫秒)
plugin_task_timeout_seconds = 720       # 插件超时
```

### 消息过滤模式
- `None`: 处理所有消息
- `Whitelist`: 仅处理白名单中的 wxid/群
- `Blacklist`: 屏蔽黑名单中的 wxid/群

### 插件配置
每个插件在 `plugins/<插件名>/config.toml` 中有独立配置

---

## Bot API 接口

### 消息发送
```python
await bot.send_text(to_wxid, content)           # 发送文本
await bot.send_image(to_wxid, image_path)       # 发送图片
await bot.send_file(to_wxid, file_path)         # 发送文件
await bot.send_video(to_wxid, video_path)       # 发送视频
await bot.send_at_message(room_id, content, at_list)  # @消息
await bot.send_card(to_wxid, card_wxid)         # 发送名片
await bot.send_link(to_wxid, title, desc, url)  # 发送链接
await bot.revoke_message(msg_id)                # 撤回消息
```

### 信息获取
```python
await bot.get_login_info()                      # 获取登录信息
await bot.get_friend_list()                     # 获取好友列表
await bot.get_friend_info(wxid)                 # 获取好友信息
await bot.get_chatroom_list()                   # 获取群列表
await bot.get_chatroom_members(room_id)         # 获取群成员
await bot.get_chatroom_info(room_id)            # 获取群信息
await bot.get_user_info_in_chatroom(room_id, wxid)  # 获取群内用户信息
```

### 好友管理
```python
await bot.add_friend(wxid, verify_msg, scene)   # 添加好友
await bot.accept_friend(v3, v4, scene)          # 同意好友请求
await bot.delete_friend(wxid)                   # 删除好友
await bot.set_friend_remark(wxid, remark)       # 设置备注
```

### 群聊管理
```python
await bot.create_chatroom(member_list)          # 创建群聊
await bot.invite_to_chatroom(room_id, wxid_list)  # 邀请入群
await bot.remove_chatroom_member(room_id, wxid_list)  # 踢出成员
await bot.quit_chatroom(room_id)                # 退出群聊
await bot.set_chatroom_announcement(room_id, text)  # 设置群公告
```

---

## 运行要求

- **操作系统**: Windows
- **Python**: 3.x
- **微信**: 需已登录微信客户端
- **Hook**: d3d11.dll 放置于微信安装目录

## 依赖项

```
loguru==0.7.3
APScheduler==3.11.0
aiohttp>=3.9.1
httpx>=0.27.0
Pillow>=10.0.0
aiohttp-socks>=0.8.0
redis>=5.0.0  (可选)
```

---

*更新时间: 2026-01-12*