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

- 新增 `#四个中文字+空格` 消息匹配规则，可配置前缀和长度
- 匹配成功后 POST 到 COMMAND_CALLBACK_URL，携带命令名、内容、用户信息
- 使用 EventMixin.events() 订阅消息流，on_close 自动取消监听
- 新增配置项：COMMAND_PREFIX、COMMAND_LENGTH、COMMAND_CALLBACK_URL
- 更新 .env.example 和 README 文档

.env.example

@@ -15,3 +15,11 @@ ALLOWED_EXTENSIONS=
 # ── QQ API ──
 QQ_API_TIMEOUT=10
 QQ_API_MAX_RETRIES=2
+
+# ── 命令监听 ──
+# 命令前缀，默认 #
+COMMAND_PREFIX=#
+# 命令名长度（中文字数），默认 4
+COMMAND_LENGTH=4
+# 匹配到命令后的回调 URL，留空则不监听
+COMMAND_CALLBACK_URL=

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

config.py

@@ -31,3 +31,8 @@ ALLOWED_EXTENSIONS: set[str] = set(
 # ── QQ API ───────────────────────────────────────────────────
 QQ_API_TIMEOUT: float = float(os.environ.get("QQ_API_TIMEOUT", "10"))
 QQ_API_MAX_RETRIES: int = int(os.environ.get("QQ_API_MAX_RETRIES", "2"))
+
+# ── 命令监听 ────────────────────────────────────────────────
+COMMAND_PREFIX: str = os.environ.get("COMMAND_PREFIX", "#")
+COMMAND_LENGTH: int = int(os.environ.get("COMMAND_LENGTH", "4"))
+COMMAND_CALLBACK_URL: str = os.environ.get("COMMAND_CALLBACK_URL", "")

handlers/command.py

@@ -0,0 +1,57 @@
+"""命令监听处理器：匹配 #命令名+空格 格式的消息，转发到外部回调 URL。"""
+
+import re
+
+import aiohttp
+
+from ..config import COMMAND_CALLBACK_URL, COMMAND_LENGTH, COMMAND_PREFIX
+from ..response import error, ok
+
+
+def build_command_pattern() -> re.Pattern:
+    """构建命令匹配正则：# + N个中文字 + 空格。"""
+    return re.compile(
+        rf"^{re.escape(COMMAND_PREFIX)}([\u4e00-\u9fff]{{{COMMAND_LENGTH}}})\s+(.+)",
+        re.DOTALL,
+    )
+
+
+COMMAND_PATTERN = build_command_pattern()
+
+
+def parse_command(raw_message: str) -> dict | None:
+    """解析消息，匹配命令模式。返回 {command, content, raw_message} 或 None。"""
+    match = COMMAND_PATTERN.match(raw_message.strip())
+    if not match:
+        return None
+    return {
+        "command": match.group(1),
+        "content": match.group(2).strip(),
+        "raw_message": raw_message.strip(),
+    }
+
+
+async def send_command_callback(data: dict, logger) -> bool:
+    """将命令数据 POST 到外部回调 URL。返回是否成功。"""
+    if not COMMAND_CALLBACK_URL:
+        logger.warning("COMMAND_CALLBACK_URL 未配置，跳过命令回调")
+        return False
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                COMMAND_CALLBACK_URL,
+                json=data,
+                timeout=aiohttp.ClientTimeout(total=10),
+            ) as resp:
+                if resp.status >= 400:
+                    body = await resp.text()
+                    logger.error(
+                        "命令回调失败: status=%d url=%s body=%s",
+                        resp.status, COMMAND_CALLBACK_URL, body[:200],
+                    )
+                    return False
+                return True
+    except Exception as exc:
+        logger.error("命令回调异常: url=%s error=%s", COMMAND_CALLBACK_URL, exc)
+        return False

plugin.py

@@ -7,7 +7,8 @@ import os
 from aiohttp import web
 from ncatbot.plugin import NcatBotPlugin
 
-from .config import HOST, PORT, UPLOAD_DIR, WEBHOOK_API_KEY
+from .config import COMMAND_CALLBACK_URL, COMMAND_LENGTH, COMMAND_PREFIX, HOST, PORT, UPLOAD_DIR, WEBHOOK_API_KEY
+from .handlers.command import parse_command, send_command_callback
 from .handlers.health import health_handler
 from .handlers.message import webhook_handler
 from .handlers.upload import cleanup_expired_files, upload_handler
@@ -26,14 +27,25 @@ class WebHookPlugin(NcatBotPlugin):
         super().__init__(*args, **kwargs)
         self._webhook_runner: web.AppRunner | None = None
         self._cleanup_task: asyncio.Task | None = None
+        self._listener_task: asyncio.Task | None = None
 
     async def on_load(self):
         self.logger.info("Webhook 插件已加载")
         self.logger.info("WEBHOOK_API_KEY: %s", "已配置" if os.environ.get("WEBHOOK_API_KEY") else "自动生成")
+        self.logger.info("命令监听: 前缀=%s 长度=%d 回调=%s", COMMAND_PREFIX, COMMAND_LENGTH,
+                         COMMAND_CALLBACK_URL or "未配置")
         asyncio.create_task(self._start_webhook())
         self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+        self._listener_task = asyncio.create_task(self._message_listener())
 
     async def on_close(self):
+        if self._listener_task is not None:
+            self._listener_task.cancel()
+            try:
+                await self._listener_task
+            except asyncio.CancelledError:
+                pass
+            self._listener_task = None
         if self._cleanup_task is not None:
             self._cleanup_task.cancel()
             try:
@@ -53,6 +65,38 @@ class WebHookPlugin(NcatBotPlugin):
             except Exception as exc:
                 self.logger.error("清理过期文件失败: %s", exc)
 
+    async def _message_listener(self) -> None:
+        """监听 QQ 消息，匹配命令模式后转发到外部回调。"""
+        try:
+            async with self.events("message") as stream:
+                async for event in stream:
+                    try:
+                        raw_message = event.data.raw_message
+                        if not raw_message:
+                            continue
+                        parsed = parse_command(raw_message)
+                        if not parsed:
+                            continue
+                        # 构建回调数据
+                        data = {
+                            "command": parsed["command"],
+                            "content": parsed["content"],
+                            "raw_message": parsed["raw_message"],
+                            "user_id": event.data.user_id,
+                            "message_id": event.data.message_id,
+                        }
+                        if hasattr(event.data, "group_id"):
+                            data["group_id"] = event.data.group_id
+                        self.logger.info(
+                            "命令监听匹配: command=%s user=%s group=%s",
+                            parsed["command"], data["user_id"], data.get("group_id", "-"),
+                        )
+                        asyncio.create_task(send_command_callback(data, self.logger))
+                    except Exception as exc:
+                        self.logger.error("消息处理异常: %s", exc)
+        except asyncio.CancelledError:
+            return
+
     def _create_app(self) -> web.Application:
         app = web.Application(middlewares=[request_id_middleware, auth_middleware])
         app["qq_api"] = self.api