## ✨ 核心特性
#### 🤖 灵活的模型配置
- 支持为不同的群聊和私聊设置不同的 AI 模型和 system prompt
- OpenAI (ChatGPT)
- DeepSeek
- Moonshot (Kimi)
#### 🛠️ 智能路由系统
- 基于 AI 的意图识别，无需记住特定命令格式
- 支持为功能提供描述、示例和参数说明，帮助模型精准调用
- 通过装饰器注册新功能即可扩展机器人能力
消息处理流程说明：
1. **消息预处理**：系统接收用户消息，提取纯文本、发送者等上下文
2. **权限判断**：仅在私聊或群聊中被 @ 时才进入 AI 路由，避免打扰其他群成员
3. **AI 决策**：大模型根据功能描述判断是否调用某个功能或直接聊天
4. **结果输出**：调用成功的功能会返回处理结果，否则使用默认闲聊响应
### ⏰ 定时任务与提醒功能
- 每日天气预报推送
- 每日新闻资讯推送
- 工作日报/周报/月报提醒
- 个人自定义提醒系统（通过自然语言设置定时提醒）
### 📊 对话管理
- 不管是群里的消息还是自己的消息，都本地写入 sql 队列中（长度可自定义）
- 智能消息总结功能
- 处理各类微信消息（文本、图片、小程序、链接等）
#### 🔧 实用工具
- 自动接受好友请求并打招呼（可通过 `auto_accept_friend_request` 配置开启）
- 自动响应群聊和私聊消息
#### 🔁 关键词转发
- 支持在 `message_forwarding` 中配置多个规则，监听指定群聊的关键词
- 当命中关键词时，会携带原始内容和来源信息，将完整消息转发到目标群聊
- 规则支持一个群聊转发到多个目标群，关键词可配置为单个或列表
## 🛠️ 安装指南
#### 系统要求
- Python 3.8 或更高版本
- Windows 操作系统（wcferry 要求）
- 微信 PC 版客户端
- 云配置要求（如需）：2vCPU 2GiB （经济型）
#### 安装步骤
1. **克隆仓库**
```bash
git clone https://github.com/zippland/Bubbles.git
cd Bubbles
```
2. **创建并激活虚拟环境（可选但推荐）**
```bash
python -m venv .venv
.venv\Scripts\activate
```
3. **安装依赖**
```bash
pip install -r requirements.txt
```
4. **配置项目**
```bash
# 复制配置模板
cp config.yaml.template config.yaml
# 编辑配置文件，填入您的 API 密钥等信息
notepad config.yaml
```
## ⚙️ 配置说明
配置文件 `config.yaml` 包含以下主要部分：
#### AI 模型配置
每个 AI 模型都有自己的配置部分，例如：
```yaml
# ChatGPT 配置
CHATGPT:
key: "your-openai-api-key" # 填写你 ChatGPT 的 key
api: "https://api.openai.com/v1"
model: "gpt-4.1-mini" # 可选：gpt-4, gpt-3.5-turbo 等
proxy: "http://127.0.0.1:7890" # 可选：如需代理请填写
system_prompt: "你是一个有用的助手。"
max_history_messages: 20 # 设置 ChatGPT 默认最多回顾 20 条历史消息
```
#### 群组/私聊模型映射
您可以为不同的群聊或私聊指定不同的 AI 模型：
```yaml
# 群组模型配置
GROUP_MODELS:
# 默认模型 ID
default: 1 # 1 代表 CHATGPT
# 群聊模型映射
mapping:
- room_id: "12345678@chatroom" # 群聊 ID
model: 1 # 1 代表 CHATGPT
max_history: 30 # 回顾最近30条消息
# 私聊模型映射
private_mapping:
- wxid: "wxid_abc123" # 用户 wxid
model: 2 # 2 代表 Deepseek
max_history: 50 # 回顾最近50条消息
```
#### 群聊随机闲聊回复
如果希望机器人在群聊中偶尔主动开聊，可在 `groups.models.mapping` 中为群添加 `random_chitchat_probability`：
```yaml
groups:
models:
mapping:
- room_id: "12345678@chatroom"
model: 2
max_history: 30
random_chitchat_probability: 0.3 # 0-1，0 表示关闭
```
`random_chitchat_probability` 表示该群的上限概率。命中一次后会直接清零，随后每条符合条件的群消息自动 +0.05 逐步回升，直至回到上限；未配置该字段的群默认关闭随机闲聊。
#### 消息关键词转发
通过 `message_forwarding` 可以监听某些群聊的特定关键词，并把命中的整段消息转发到其他群聊：
```yaml
message_forwarding:
enable: true
rules:
- source_room_id: "12345678@chatroom" # 需要监听的群
target_room_ids:
- "87654321@chatroom" # 接受转发的群，可配置多个
keywords:
- "紧急"
- "求助"
```
- `source_room_id`：需要监听的群聊 ID
- `target_room_ids`：接受转发的群 ID，支持单个或多个
- `keywords`：触发转发的关键词，任何一个命中就会转发
#### 功能开关
您可以启用或禁用各种功能：
```yaml
# 功能开关
news_report # 每日新闻推送
weather_report # 每日天气推送
image_generation # AI生图
perplexity # perplexity
```
## 🚀 使用方法
#### 启动机器人
```bash
python main.py
```
#### 可用功能示例（AI 路由）
以下是已经注册到 AI 路由的典型意图，机器人会尽力理解类似的自然语言表述：
##### 提醒功能
- “提醒我明天下午三点开会” —— 设置一次性提醒
- “每天早上 8 点提醒我跑步” —— 支持循环提醒
- “查看我的提醒” / “我有哪些提醒” —— 查看当前所有提醒
- “把明天的开会提醒删掉” —— 删除指定提醒
##### 搜索与资讯
- “帮我查查最近的 AI 新闻” —— 使用 Perplexity 进行深度检索
- “看看今天的新闻” —— 推送最新要闻
##### 天气工具
- “北京天气怎么样”
- “查一下上海未来几天的天气”
## 📋 项目结构
```
Bubbles-WechatAI/
├── ai_providers/ # AI 模块
│ ├── ai_name.py # AI 模型接口实现
│ └── ...
├── commands/ # 消息上下文与 AI 路由
│ ├── handlers.py # 功能处理函数
│ ├── ai_router.py # AI智能路由器
│ ├── ai_functions.py # AI路由功能注册
│ └── ...
├── data/ # 数据文件
│
├── function/ # 功能模块
│ ├── func_feature.py # 各种功能的具体实现
│ └── ...
├── config.yaml # 配置文件
└── ...
```
### ✨ 如何添加新功能
目前所有新功能均通过 AI 智能路由接入，开发流程如下：
1. **实现功能逻辑**
* 在 `function/` 目录下创建或复用功能模块，封装核心业务逻辑，便于测试和复用。
2. **注册 AI 路由功能**
* 打开 `commands/ai_functions.py`
* 使用装饰器注册功能，提供给模型判定意图所需的描述信息：
```python
@ai_router.register(
name="your_function_name",
description="功能描述（AI 会根据这个判断用户意图）",
examples=[
"示例用法1",
"示例用法2",
"示例用法3"
],
params_description="参数说明"
)
def ai_handle_your_function(ctx: MessageContext, params: str) -> bool:
# params 是 AI 从用户输入中提取的参数
# 调用你的功能逻辑
# 使用 ctx.send_text() 发送回复
return True
```
3. **理解路由机制**
* 用户消息会在私聊或被 @ 时进入 AI 路由
* AI 根据 `description`、`examples` 和 `params_description` 选择最合适的功能
* `params` 字段由模型提取，可根据需要进一步解析或校验
例如，注册了天气查询功能后，用户可以说：
- "北京天气怎么样"
- "查一下上海的天气"
- "明天深圳会下雨吗"
AI 都能理解并调用天气查询功能。
完成以上步骤后，重启机器人即可测试你的新功能！
## 📄 许可证
本项目采用 Apache 2.0 许可证，详情请参阅 [LICENSE](LICENSE) 文件。
## 🙏 致谢
- [wcferry](https://github.com/lich0821/wcferry) - 提供微信机器人底层支持
- 所有贡献者和用户
## ❓ 常见问题
**Q: 如何获取群聊 ID？**
A: 在群聊中发送一条消息，机器人日志会显示该消息的来源群聊 ID。
**Q: 如何添加新的 AI 模型？**
A: 在 `ai_providers` 目录下创建新的模型接口实现，然后在 `robot.py` 中注册该模型。
**Q: 出现 "AI 模型未响应" 错误怎么办？**
A: 检查相应 AI 模型的 API 密钥配置和网络连接，确保 API 可访问。
**Q: 机器人不回复消息怎么办？**
A: 检查 wcferry 服务是否正常运行，查看日志文件了解详细错误信息。
## 📞 联系方式
如有任何问题或建议，请通过以下方式联系我们：
- GitHub Issues: [提交问题](https://github.com/zippland/Bubbles/issues)
- Email: zylanjian@outlook.com
---
**注意**：本项目仅供学习和个人使用，请遵守微信使用条款，不要用于任何违反法律法规的活动。