✨ 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:
44
README.md
44
README.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user