feat(command): 添加命令监听与外接回调功能

- 新增 `#四个中文字+空格` 消息匹配规则,可配置前缀和长度
- 匹配成功后 POST 到 COMMAND_CALLBACK_URL,携带命令名、内容、用户信息
- 使用 EventMixin.events() 订阅消息流,on_close 自动取消监听
- 新增配置项:COMMAND_PREFIX、COMMAND_LENGTH、COMMAND_CALLBACK_URL
- 更新 .env.example 和 README 文档
This commit is contained in:
2026-05-02 19:02:40 +08:00
parent b86a2d4c4e
commit ee1bd583d8
5 changed files with 159 additions and 1 deletions

View File

@@ -41,6 +41,9 @@ uv run python -m ncatbot
| `ALLOWED_EXTENSIONS` | 否 | 空(不限) | 允许的扩展名,逗号分隔,如 `jpg,png,pdf` |
| `QQ_API_TIMEOUT` | 否 | `10` | QQ API 超时秒数 |
| `QQ_API_MAX_RETRIES` | 否 | `2` | QQ API 失败重试次数 |
| `COMMAND_PREFIX` | 否 | `#` | 命令前缀 |
| `COMMAND_LENGTH` | 否 | `4` | 命令名字符数(中文字数) |
| `COMMAND_CALLBACK_URL` | 否 | 空(不监听) | 命令匹配后的回调 URL |
## 接口说明
@@ -182,6 +185,46 @@ curl -X POST http://localhost:8081/webhook \
每条消息独立处理,一条失败不影响其他消息。`results` 数组按原始 `index` 排序,包含每条消息的发送结果。
### 命令监听
插件会自动监听 QQ 消息,当消息以 `#四个中文字+空格` 开头时,将命令内容 POST 到 `COMMAND_CALLBACK_URL`
**匹配规则:**
```
#测试命令 你好世界
│ │ │ │
│ │ │ └── 命令内容content
│ └── 空格分隔
└── 命令名4个中文字
└── 前缀(默认 #
```
- 前缀、命令名长度可通过 `COMMAND_PREFIX``COMMAND_LENGTH` 配置
- 不配置 `COMMAND_CALLBACK_URL` 则不监听
**回调请求体POST JSON**
```json
{
"command": "测试命令",
"content": "你好世界",
"raw_message": "#测试命令 你好世界",
"user_id": "123456",
"group_id": "789012",
"message_id": "abc123"
}
```
| 字段 | 说明 |
|---|---|
| `command` | 命令名4个中文字 |
| `content` | 命令后的内容 |
| `raw_message` | 原始消息文本 |
| `user_id` | 发送者 QQ 号 |
| `group_id` | 群号(私聊消息无此字段) |
| `message_id` | 消息 ID |
## 项目结构
```
@@ -191,6 +234,7 @@ curl -X POST http://localhost:8081/webhook \
├── response.py # 统一响应格式
├── handlers/
│ ├── __init__.py
│ ├── command.py # 命令监听匹配与回调
│ ├── health.py # GET /healthz
│ ├── message.py # POST /webhook
│ └── upload.py # POST /upload