功能：通过 HTTP API 实现 Danding_QqPush 插件，用于 QQ 群通知

- 增加了通过外部 HTTP API 向 QQ 群组发送消息的核心功能。 - 实现了对长文本消息的图片渲染，以避免被认定为垃圾信息。 - 支持在消息中提及特定的 QQ 用户。 - 创建了用于 API 令牌和图片渲染设置的配置选项。 - 开发了一个测试脚本以验证 API 功能。 - 对现有代码进行了重构，以提高组织性和可维护性。
2026-01-20 21:19:05 +08:00
parent 4a944316fe
commit dedc872f1b
14 changed files with 1065 additions and 48 deletions
--- a/danding_bot/plugins/danding_qqpush/README.md
+++ b/danding_bot/plugins/danding_qqpush/README.md
@@ -0,0 +1,219 @@
+# Danding_QqPush 插件
+
+用于通过外部 HTTP API 向 QQ 群定向推送通知的 NoneBot 插件。
+
+## 功能特性
+
+- ✅ 通过 HTTP API 推送消息到指定 QQ 群
+- ✅ 自动将文本渲染为图片，避免长文本刷屏
+- ✅ 支持 @指定 QQ 用户
+- ✅ 使用 `#` 符号表示换行
+- ✅ 基于 Token 的简单鉴权机制
+- ✅ 支持中文文本渲染
+
+## 目录结构
+
+```
+danding_qqpush/
+├── __init__.py         # 插件初始化模块
+├── config.py           # 配置模块
+├── api.py              # FastAPI 路由模块
+├── text_parser.py      # 文本处理模块
+├── image_render.py     # 图片生成模块
+├── sender.py           # 消息发送模块
+└── utils.py            # 工具函数模块
+```
+
+## 安装与配置
+
+### 1. 确保依赖已安装
+
+```bash
+pip install pillow
+```
+
+### 2. 配置 Token
+
+在 `.env` 文件或 NoneBot 配置文件中添加：
+
+```env
+DANDING_QQPUSH_TOKEN = "your-custom-token-here"
+```
+
+如果不配置，默认使用 `danding-8HkL9xQ2`。
+
+### 3. 启动 NoneBot
+
+```bash
+nb run
+```
+
+插件会自动加载，并在日志中显示注册的 API 路径。
+
+## API 使用说明
+
+### 接口信息
+
+- **方法**: `POST`
+- **路径**: `/danding/qqpush/{token}`
+- **Content-Type**: `application/json`
+
+### 请求参数
+
+| 参数名   | 类型   | 必填 | 说明                     |
+| -------- | ------ | ---- | ------------------------ |
+| token    | path   | 是   | 配置的 Token             |
+| group_id | int    | 是   | 接收消息的 QQ 群号       |
+| qq       | int    | 是   | 被 @ 的 QQ 号            |
+| text     | string | 是   | 通知文本（`#` 表示换行） |
+
+### 请求示例
+
+```bash
+curl -X POST "http://localhost:8080/danding/qqpush/danding-8HkL9xQ2" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "group_id": 123456789,
+    "qq": 987654321,
+    "text": "系统告警#数据库连接失败#请立即处理"
+  }'
+```
+
+### Python 请求示例
+
+```python
+import requests
+
+url = "http://localhost:8080/danding/qqpush/danding-8HkL9xQ2"
+data = {
+    "group_id": 123456789,
+    "qq": 987654321,
+    "text": "系统告警#数据库连接失败#请立即处理"
+}
+
+response = requests.post(url, json=data)
+print(response.json())
+```
+
+### 响应示例
+
+**成功响应** (200):
+
+```json
+{
+  "success": true,
+  "message": "推送成功",
+  "data": {
+    "group_id": 123456789,
+    "qq": 987654321,
+    "message_id": 12345
+  }
+}
+```
+
+**错误响应** (400):
+
+```json
+{
+  "detail": "group_id 不能为空"
+}
+```
+
+**错误响应** (403):
+
+```json
+{
+  "detail": "Token 验证失败"
+}
+```
+
+**错误响应** (500):
+
+```json
+{
+  "detail": "Bot 未连接，请检查机器人状态"
+}
+```
+
+## 配置选项
+
+可以在配置文件中自定义以下选项：
+
+```python
+class Config(BaseModel):
+    Token: str = "danding-8HkL9xQ2"
+    """API 访问 Token"""
+    
+    ImageWidth: int = 800
+    """图片宽度（像素）"""
+    
+    ImageFontSize: int = 24
+    """字体大小（像素）"""
+    
+    ImagePadding: int = 30
+    """图片内边距（像素）"""
+    
+    ImageLineSpacing: float = 1.4
+    """行距倍数"""
+    
+    ImageBgColor: tuple = (252, 252, 252)
+    """图片背景颜色 (R, G, B)"""
+    
+    ImageTextColor: tuple = (0, 0, 0)
+    """文本颜色 (R, G, B)"""
+    
+    MaxTextLength: int = 2000
+    """最大文本长度（字符数）"""
+    
+    FontPaths: list = [...]
+    """字体文件路径列表"""
+```
+
+## 文本格式说明
+
+- 使用 `#` 符号表示换行
+- 示例：`第一行#第二行#第三行` 会被渲染为三行文本
+- 超过最大长度的文本会被自动截断
+
+## 注意事项
+
+1. **安全性**: Token 泄露只影响推送能力，无账号风险，但建议定期更换
+2. **Bot 状态**: 确保 Bot 已连接，否则会返回 500 错误
+3. **群权限**: 确保 Bot 在目标群中有发送消息的权限
+4. **字体支持**: 插件会自动尝试加载系统中的中文字体
+
+## 故障排查
+
+### 问题：启动时显示 "未找到可用的 Bot 实例"
+
+**说明**: 这是正常现象。插件加载时 Bot 可能还未连接，API 调用时会动态获取 Bot 实例。
+
+### 问题：返回 "Bot 未连接"
+
+**解决方案**: 
+- 检查 NoneBot 是否正常启动
+- 检查 OneBot V11 连接状态
+- 确认 Bot 已成功连接到 QQ 服务器
+
+### 问题：图片显示乱码
+
+**解决方案**:
+- 检查系统是否安装了中文字体
+- 在 `FontPaths` 配置中添加正确的字体路径
+
+### 问题：消息发送失败
+
+**解决方案**:
+- 检查 Bot 是否在目标群中
+- 检查 Bot 是否有发送消息的权限
+- 查看日志中的详细错误信息
+
+## 测试
+
+使用提供的测试脚本进行测试：
+
+```bash
+python test_qqpush.py
+```
+
+修改脚本中的 `group_id` 和 `qq` 为实际值。