104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
# qq-messenger Skill
|
||
|
||
主动向 QQ 发送消息和文件的能力。
|
||
|
||
## 原理
|
||
|
||
[qqrebot](https://github.com/.../qqrebot) 使用 go-cqhttp HTTP API (`send_private_msg` / `send_group_msg`) 发送消息。NapCat4 扩展支持 `upload_group_file` / `upload_private_file` 发送文件。本技能包装了这些 API 为命令行脚本，方便 qq-agent 在需要时主动推送。
|
||
|
||
## 自动回复 vs 主动发送
|
||
|
||
| | 回复场景 | 主动发信 |
|
||
|---|---|---|
|
||
| 触发 | 用户在 QQ 上发消息给你 | 你自己决定要推送 |
|
||
| 方式 | 系统自动将回复转发到 QQ | 调用本脚本 |
|
||
| 示例 | 用户问"服务器状态"，你回答"正常" | 你发现磁盘快满了，主动给管理员发告警 |
|
||
|
||
**即使不调用本脚本，用户发给你的消息你回复后，系统会自动转发回 QQ。** 本脚本只用于"非回复"场景的主动推送。
|
||
|
||
## 脚本清单
|
||
|
||
| 脚本 | 用途 | 特点 |
|
||
|---|---|---|
|
||
| `qq_send_msg.py` | 发送文本消息 | 即时发送，阻塞直到返回 |
|
||
| `qq_send_file.py` | 发送文件/图片 | 异步执行，调用后立即返回，后台复制→发送→清理 |
|
||
|
||
## 用法
|
||
|
||
### 发送私聊消息
|
||
|
||
```python
|
||
import subprocess
|
||
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_msg.py",
|
||
"--private", "YOUR_ADMIN_QQ", "--message", "消息内容"], text=True, timeout=15, capture_output=True)
|
||
```
|
||
|
||
### 发送群聊消息
|
||
|
||
```python
|
||
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_msg.py",
|
||
"--group", "YOUR_GROUP_ID", "--message", "消息内容"], text=True, timeout=15, capture_output=True)
|
||
```
|
||
|
||
### 发送文件（后台发送，立即返回）
|
||
|
||
```python
|
||
import subprocess
|
||
# 私聊发文件
|
||
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
|
||
"--private", "YOUR_ADMIN_QQ", "/path/to/file"], text=True, timeout=5, capture_output=True)
|
||
# 群聊发文件
|
||
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
|
||
"--group", "YOUR_GROUP_ID", "/path/to/file"], text=True, timeout=5, capture_output=True)
|
||
```
|
||
|
||
**特点**：调用后立即返回（~75ms），后台独立进程处理复制→发送。完成后通过 OpenClaw Gateway 的 `/v1/chat/completions` API 发送 `[系统通知]` 消息给 qq-agent，agent 在会话历史中看到通知。
|
||
|
||
### 发送图片
|
||
|
||
```python
|
||
import subprocess
|
||
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
|
||
"--group", "YOUR_GROUP_ID", "--image", "/tmp/screenshot.png"], text=True, timeout=5, capture_output=True)
|
||
```
|
||
|
||
**特点**：图片用 `[CQ:image]` 发送，QQ 直接显示缩略图，不会进群文件。
|
||
|
||
```python
|
||
subprocess.run(["python3", "YOUR_WORKSPACE_PATH/scripts/qq_send_file.py",
|
||
"--group", "YOUR_GROUP_ID", "--image", "/tmp/screenshot.png"], text=True, timeout=5, capture_output=True)
|
||
```
|
||
|
||
**图片说明**：用 `[CQ:image,file=...]` 发送，QQ 直接显示缩略图，不会进群文件。
|
||
|
||
## 参数说明
|
||
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| `--private <QQ号>` | 发送私聊，默认管理员 YOUR_ADMIN_QQ |
|
||
| `--group <群号>` | 发送群聊 |
|
||
| `--message <内容>` | 消息文本（qq_send_msg.py） |
|
||
| `--file <路径>` | 从文件读消息内容（qq_send_msg.py） |
|
||
| `--auto_escape` | 转义 CQ 码（默认不转义） |
|
||
| `<文件路径>` | 要发送的本地文件路径（qq_send_file.py） |
|
||
| `--name <显示名>` | 群文件内显示的文件名（qq_send_file.py） |
|
||
| `--image` | 作为图片发送，QQ 直接显示缩略图（qq_send_file.py） |
|
||
|
||
## 通知机制
|
||
|
||
文件发送完成/失败后，后台进程通过 **OpenClaw Gateway 的 `/v1/chat/completions` API** 推送 `[系统通知]` 给 qq-agent：
|
||
- 内容格式：`[系统通知] 给uid=YOUR_ADMIN_QQ发送文件的任务已上传完毕：文件名.ext (1.0MB) ✅`
|
||
- 使用 Gateway Token 鉴权
|
||
- Fire-and-forget：`timeout=3`，仅确认投递
|
||
- 这是 openclaw_bridge 插件用的同一个 API
|
||
- agent 在自己的会话历史中看到通知
|
||
|
||
## 注意事项
|
||
|
||
1. 消息尽量简洁，QQ 消息太长可读性差
|
||
2. 不要滥用主动推送，避免打扰管理员
|
||
3. 正常回复由系统自动转发，**无需调用本脚本**
|
||
4. 连接失败时检查 go-cqhttp 是否在运行（`http://YOUR_NAPCAT_HOST:25570`）
|
||
5. 文件发送依赖 `YOUR_SHARED_DIR` 目录（映射到 NapCat 容器内 `/app/files`）
|
||
6. 通知走 OpenClaw Gateway API，不走 QQ 本身
|