nonebot-plugin-grok-bot 0.1.0__tar.gz

nonebot_plugin_grok_bot-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.3
+Name: nonebot-plugin-grok-bot
+Version: 0.1.0
+Summary: NoneBot2 plugin bridging chats with Grok Bot via MCP server + webhook
+Author: Yan
+Author-email: Yan <1964649083@qq.com>
+Requires-Dist: anyio>=4.15.1
+Requires-Dist: mcp>=1.9
+Requires-Dist: nonebot-plugin-alconna>=0.57
+Requires-Dist: nonebot2>=2.4.0
+Requires-Dist: nonebot-plugin-savepic>=0.6.7 ; extra == 'savepic'
+Requires-Python: >=3.11
+Provides-Extra: savepic
+Description-Content-Type: text/markdown
+
+# nonebot-plugin-grok-bot
+
+把 NoneBot2 接入 [Grok Bot](https://cursor.com/help/grok-bot)：
+
+- **发送**：插件在 NoneBot 自身的 FastAPI 上挂一个 MCP Server（Streamable HTTP），Grok Bot 通过它发消息，支持图文混排、QQ 内置表情、本地表情包（[savepic](https://github.com/Yan-Zero/nonebot-plugin-savepic)）。
+- **接收**：收到的消息按会话路由，POST 到对应 Grok Bot Routine 的 Webhook。
+
+## 安装
+
+```bash
+uv add nonebot-plugin-grok-bot            # 基础
+uv add "nonebot-plugin-grok-bot[savepic]" # 启用本地表情包
+```
+
+驱动器需要同时具备 ASGI 和 HTTP 客户端，例如 `DRIVER=~fastapi+~httpx+~aiohttp`。
+
+## 配置
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `GROK_BOT_MCP_PREFIX` | `/grok_bot` | MCP 端点为 `{prefix}/mcp` |
+| `GROK_BOT_MCP_TOKEN` | 无 | MCP 端点的 Bearer Token，在 Grok Bot 里存为 `Authorization` secret |
+| `GROK_BOT_OWNERS` | `[]` | Owner 的用户 ID |
+| `GROK_BOT_ALLOWED_USERS` | `[]` | 除 Owner 外允许私聊的用户 ID |
+| `GROK_BOT_ALLOWED_GROUPS` | `[]` | 允许的群号（频道为 `<guild>/<channel>`） |
+| `GROK_BOT_ROUTES` | `[]` | 推送路由，见下 |
+| `GROK_BOT_WEBHOOK_TIMEOUT` | `10` | 秒 |
+| `GROK_BOT_WEBHOOK_RETRIES` | `3` | 5xx / 429 / 网络错误时重试 |
+| `GROK_BOT_HISTORY_SIZE` | `100` | 每个会话保留的最近消息数，供 `get_history` 查询 |
+
+Grok Bot 只能访问公网或 Tailscale 网络内的地址，`HOST` 需要绑定到对应网卡（例如 Tailscale IP 或 `0.0.0.0`）。
+
+### 白名单
+
+- 私聊只接受 Owner 和 `GROK_BOT_ALLOWED_USERS`。
+- 群聊只接受 `GROK_BOT_ALLOWED_GROUPS`。
+
+白名单外的消息不记录、不推送，MCP 也不能向其发送。
+
+### 路由
+
+会话标识为 `group:<群号>`、`private:<QQ号>`、`channel:<guild>/<channel>`。路由按顺序匹配（fnmatch），首个命中的生效；未命中的会话不推送。
+
+```json
+[
+  {
+    "name": "owner",
+    "sessions": ["private:*"],
+    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
+    "webhook_key": "crsr_xxx",
+    "owner_trigger": "always"
+  },
+  {
+    "name": "groups",
+    "sessions": ["group:*"],
+    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
+    "webhook_key": "crsr_xxx",
+    "flush_interval": 300,
+    "flush_size": 30,
+    "max_pending": 100
+  }
+]
+```
+
+推送时机：
+
+- Owner 的消息：按路由的 `owner_trigger` 决定是否立即推送（并带上该会话中尚未推送的消息）。
+  - `always`：Owner 任何发言都推送，适合私聊和特殊群。
+  - `to_me`（默认）：仅 @bot、回复 bot 或私聊时推送，群里普通发言不推送。
+  - `never`：Owner 也不触发。
+- 其他人的消息：先积压起来，满 `flush_size` 条，或第一条积压消息之后过了 `flush_interval` 秒时推送；两者都不设置时，只作为上下文等 Owner 触发。
+- bot 自己发出的消息：只记入上下文，不触发推送。
+
+### Webhook Payload
+
+```json
+{
+  "route": "groups",
+  "trigger": "owner",
+  "session": "group:123456",
+  "messages": [
+    {
+      "session": "group:123456",
+      "message_id": "1001",
+      "time": "2026-10-10T18:00:00+08:00",
+      "sender": {"user_id": "10000", "nickname": "Yan", "is_owner": true, "is_self": false},
+      "to_me": false,
+      "segments": [
+        {"type": "text", "text": "看看这个"},
+        {"type": "image", "url": "https://multimedia.nt.qq.com.cn/download?appid=1407&fileid=…&rkey=…", "sticker": false},
+        {"type": "emoji", "id": "14", "name": "微笑"}
+      ]
+    }
+  ]
+}
+```
+
+`trigger` 为 `owner` / `size` / `interval`。图片直接给原始链接，插件不缓存。QQ 图片链接里的 rkey 会过期，通过 MCP `get_image(url)` 查看或在 `send_message` 中转发时，插件会自动调用 `get_rkey` 重新签发（需要 NapCat / LLOneBot 等支持该扩展 API 的实现）。
+
+## MCP 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `send_message(session, segments, reply_to?, self_id?)` | 发送消息，消息段类型有 `text` / `image`（`url` / `base64`）/ `emoji` / `sticker` / `at` / `at_all` |
+| `get_history(session, limit)` | 会话最近消息，格式同 Webhook |
+| `get_image(url, session?)` | 查看图片，QQ 链接自动续签 rkey |
+| `list_sessions()` | 收到过消息的会话 |
+| `list_emojis()` | QQ 内置表情 ID → 名称 |
+| `search_stickers(query, session, limit)` | 搜索本地表情包（需 savepic） |
+| `view_sticker(name, session)` | 查看表情包图片（需 savepic） |
+
+## 开发
+
+```bash
+uv sync
+uv run pytest
+uv run python bot.py
+```

nonebot_plugin_grok_bot-0.1.0/README.md

@@ -0,0 +1,118 @@
+# nonebot-plugin-grok-bot
+
+把 NoneBot2 接入 [Grok Bot](https://cursor.com/help/grok-bot)：
+
+- **发送**：插件在 NoneBot 自身的 FastAPI 上挂一个 MCP Server（Streamable HTTP），Grok Bot 通过它发消息，支持图文混排、QQ 内置表情、本地表情包（[savepic](https://github.com/Yan-Zero/nonebot-plugin-savepic)）。
+- **接收**：收到的消息按会话路由，POST 到对应 Grok Bot Routine 的 Webhook。
+
+## 安装
+
+```bash
+uv add nonebot-plugin-grok-bot            # 基础
+uv add "nonebot-plugin-grok-bot[savepic]" # 启用本地表情包
+```
+
+驱动器需要同时具备 ASGI 和 HTTP 客户端，例如 `DRIVER=~fastapi+~httpx+~aiohttp`。
+
+## 配置
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `GROK_BOT_MCP_PREFIX` | `/grok_bot` | MCP 端点为 `{prefix}/mcp` |
+| `GROK_BOT_MCP_TOKEN` | 无 | MCP 端点的 Bearer Token，在 Grok Bot 里存为 `Authorization` secret |
+| `GROK_BOT_OWNERS` | `[]` | Owner 的用户 ID |
+| `GROK_BOT_ALLOWED_USERS` | `[]` | 除 Owner 外允许私聊的用户 ID |
+| `GROK_BOT_ALLOWED_GROUPS` | `[]` | 允许的群号（频道为 `<guild>/<channel>`） |
+| `GROK_BOT_ROUTES` | `[]` | 推送路由，见下 |
+| `GROK_BOT_WEBHOOK_TIMEOUT` | `10` | 秒 |
+| `GROK_BOT_WEBHOOK_RETRIES` | `3` | 5xx / 429 / 网络错误时重试 |
+| `GROK_BOT_HISTORY_SIZE` | `100` | 每个会话保留的最近消息数，供 `get_history` 查询 |
+
+Grok Bot 只能访问公网或 Tailscale 网络内的地址，`HOST` 需要绑定到对应网卡（例如 Tailscale IP 或 `0.0.0.0`）。
+
+### 白名单
+
+- 私聊只接受 Owner 和 `GROK_BOT_ALLOWED_USERS`。
+- 群聊只接受 `GROK_BOT_ALLOWED_GROUPS`。
+
+白名单外的消息不记录、不推送，MCP 也不能向其发送。
+
+### 路由
+
+会话标识为 `group:<群号>`、`private:<QQ号>`、`channel:<guild>/<channel>`。路由按顺序匹配（fnmatch），首个命中的生效；未命中的会话不推送。
+
+```json
+[
+  {
+    "name": "owner",
+    "sessions": ["private:*"],
+    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
+    "webhook_key": "crsr_xxx",
+    "owner_trigger": "always"
+  },
+  {
+    "name": "groups",
+    "sessions": ["group:*"],
+    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
+    "webhook_key": "crsr_xxx",
+    "flush_interval": 300,
+    "flush_size": 30,
+    "max_pending": 100
+  }
+]
+```
+
+推送时机：
+
+- Owner 的消息：按路由的 `owner_trigger` 决定是否立即推送（并带上该会话中尚未推送的消息）。
+  - `always`：Owner 任何发言都推送，适合私聊和特殊群。
+  - `to_me`（默认）：仅 @bot、回复 bot 或私聊时推送，群里普通发言不推送。
+  - `never`：Owner 也不触发。
+- 其他人的消息：先积压起来，满 `flush_size` 条，或第一条积压消息之后过了 `flush_interval` 秒时推送；两者都不设置时，只作为上下文等 Owner 触发。
+- bot 自己发出的消息：只记入上下文，不触发推送。
+
+### Webhook Payload
+
+```json
+{
+  "route": "groups",
+  "trigger": "owner",
+  "session": "group:123456",
+  "messages": [
+    {
+      "session": "group:123456",
+      "message_id": "1001",
+      "time": "2026-10-10T18:00:00+08:00",
+      "sender": {"user_id": "10000", "nickname": "Yan", "is_owner": true, "is_self": false},
+      "to_me": false,
+      "segments": [
+        {"type": "text", "text": "看看这个"},
+        {"type": "image", "url": "https://multimedia.nt.qq.com.cn/download?appid=1407&fileid=…&rkey=…", "sticker": false},
+        {"type": "emoji", "id": "14", "name": "微笑"}
+      ]
+    }
+  ]
+}
+```
+
+`trigger` 为 `owner` / `size` / `interval`。图片直接给原始链接，插件不缓存。QQ 图片链接里的 rkey 会过期，通过 MCP `get_image(url)` 查看或在 `send_message` 中转发时，插件会自动调用 `get_rkey` 重新签发（需要 NapCat / LLOneBot 等支持该扩展 API 的实现）。
+
+## MCP 工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `send_message(session, segments, reply_to?, self_id?)` | 发送消息，消息段类型有 `text` / `image`（`url` / `base64`）/ `emoji` / `sticker` / `at` / `at_all` |
+| `get_history(session, limit)` | 会话最近消息，格式同 Webhook |
+| `get_image(url, session?)` | 查看图片，QQ 链接自动续签 rkey |
+| `list_sessions()` | 收到过消息的会话 |
+| `list_emojis()` | QQ 内置表情 ID → 名称 |
+| `search_stickers(query, session, limit)` | 搜索本地表情包（需 savepic） |
+| `view_sticker(name, session)` | 查看表情包图片（需 savepic） |
+
+## 开发
+
+```bash
+uv sync
+uv run pytest
+uv run python bot.py
+```

nonebot_plugin_grok_bot-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "nonebot-plugin-grok-bot"
+version = "0.1.0"
+description = "NoneBot2 plugin bridging chats with Grok Bot via MCP server + webhook"
+readme = "README.md"
+authors = [
+    { name = "Yan", email = "1964649083@qq.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "anyio>=4.15.1",
+    "mcp>=1.9",
+    "nonebot-plugin-alconna>=0.57",
+    "nonebot2>=2.4.0",
+]
+
+[project.optional-dependencies]
+savepic = [
+    "nonebot-plugin-savepic>=0.6.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.17,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "nonebot-adapter-onebot>=2.4.6",
+    "nonebot-plugin-savepic",
+    "nonebot2[aiohttp,fastapi,httpx]>=2.5.0",
+    "nonebug>=0.4.4",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.17.0",
+]
+
+[tool.nonebot]
+plugins = ["nonebot_plugin_grok_bot"]
+adapters = [{ name = "OneBot V11", module_name = "nonebot.adapters.onebot.v11" }]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+
+[tool.uv.sources]
+nonebot-plugin-savepic = { git = "https://github.com/Yan-Zero/nonebot-plugin-savepic" }

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/__init__.py

@@ -0,0 +1,18 @@
+from nonebot import require
+from nonebot.plugin import PluginMetadata, inherit_supported_adapters
+
+require("nonebot_plugin_alconna")
+
+from . import mcp_server as mcp_server  # noqa: E402
+from . import webhook as webhook  # noqa: E402
+from .config import Config  # noqa: E402
+
+__plugin_meta__ = PluginMetadata(
+    name="Grok Bot",
+    description="通过 MCP Server 让 Grok Bot 发送消息，并将收到的消息推送到 Grok Bot 的 Routine Webhook",
+    usage="配置 GROK_BOT_ROUTES / GROK_BOT_OWNERS / GROK_BOT_MCP_TOKEN 后，将 MCP 端点提供给 Grok Bot",
+    type="application",
+    homepage="https://github.com/Yan-Zero/nonebot-plugin-grok-bot",
+    config=Config,
+    supported_adapters=inherit_supported_adapters("nonebot_plugin_alconna"),
+)

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/config.py

@@ -0,0 +1,46 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class Route(BaseModel):
+    """一条推送路由：匹配到的会话的消息会推送到对应 Grok Bot 的 Routine Webhook"""
+
+    name: str = "default"
+    sessions: list[str] = Field(default_factory=lambda: ["*"])
+    """会话匹配规则（fnmatch），如 `group:123`、`private:*`、`*`，按路由顺序首个匹配生效"""
+    webhook_url: str
+    webhook_key: str | None = None
+    """Routine Webhook 的 key，以 `Authorization: Bearer <key>` 发送"""
+    owner_trigger: Literal["always", "to_me", "never"] = "to_me"
+    """Owner 的消息何时立即推送：always 任何发言；to_me 仅 @bot / 回复 bot / 私聊；never 不触发"""
+    flush_interval: float | None = None
+    """非 Owner 消息累积多少秒后推送一次，None 表示不按时间推送"""
+    flush_size: int | None = None
+    """非 Owner 消息累积多少条后推送一次，None 表示不按数量推送"""
+    max_pending: int = 100
+    """待推送消息的上限，超出后丢弃最旧的；Owner 触发推送时会一并带上"""
+
+
+class Config(BaseModel):
+    # MCP Server（Grok Bot -> NoneBot，用于发送消息）
+    grok_bot_mcp_prefix: str = "/grok_bot"
+    """MCP 子应用挂载前缀，最终端点为 `{prefix}/mcp`"""
+    grok_bot_mcp_token: str | None = None
+    """MCP 端点的 Bearer Token，未设置则不鉴权（仅建议本地调试）"""
+
+    # Webhook（NoneBot -> Grok Bot，用于推送收到的消息）
+    grok_bot_owners: set[str] = Field(default_factory=set)
+    """Owner 的用户 ID，私聊默认只接受 Owner；其消息是否立即推送见 Route.owner_trigger"""
+    grok_bot_allowed_users: set[str] = Field(default_factory=set)
+    """除 Owner 外，额外允许私聊的用户 ID"""
+    grok_bot_allowed_groups: set[str] = Field(default_factory=set)
+    """允许的群号（频道为 `<guild>/<channel>`），不在其中的群消息会被忽略，也不能向其发送"""
+    grok_bot_routes: list[Route] = Field(default_factory=list)
+    grok_bot_webhook_timeout: float = 10.0
+    grok_bot_webhook_retries: int = 3
+
+    # 上下文
+
+    grok_bot_history_size: int = 100
+    """每个会话保留的最近消息条数，供 MCP `get_history` 查询"""

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/errors.py

@@ -0,0 +1,25 @@
+import functools
+from collections.abc import Awaitable, Callable
+from typing import ParamSpec, TypeVar
+
+from mcp.server.mcpserver.exceptions import ToolError
+from nonebot import logger
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def expose_errors(fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+    """mcp 默认隐藏工具内部异常的信息，这里转成 ToolError 让 Grok Bot 能看到原因并自行修正"""
+
+    @functools.wraps(fn)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return await fn(*args, **kwargs)
+        except ToolError:
+            raise
+        except Exception as e:
+            logger.opt(exception=e).debug(f"MCP 工具 {fn.__name__} 执行失败")
+            raise ToolError(f"{type(e).__name__}: {e}") from e
+
+    return wrapper

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/faces.py

@@ -0,0 +1,5 @@
+import json
+from pathlib import Path
+
+# QQ 内置表情（小黄脸）ID -> 名称，来自 nonebot-plugin-chatgpt-vision
+FACES: dict[str, str] = json.loads((Path(__file__).parent / "qface.json").read_text(encoding="utf-8"))

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/mcp_server.py

@@ -0,0 +1,205 @@
+import base64
+from contextlib import AsyncExitStack
+from typing import Annotated, Any, Literal
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.utilities.types import Image as MCPImage
+from nonebot import get_app, get_driver, get_plugin_config, logger
+from nonebot.adapters import Bot
+from nonebot.drivers import ASGIMixin
+from nonebot_plugin_alconna.uniseg import At, AtAll, Emoji, Image, Reply, Segment, Text, UniMessage
+from pydantic import BaseModel, Field
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from . import stickers
+from .config import Config
+from .errors import expose_errors
+from .faces import FACES
+from .rkey import with_rkey
+from .session import (
+    build_message,
+    download,
+    dump_segments,
+    image_format,
+    known_sessions,
+    resolve_target,
+)
+from .session import (
+    get_history as history_of,
+)
+from .webhook import record_outgoing
+
+driver = get_driver()
+config = get_plugin_config(Config)
+
+if not isinstance(driver, ASGIMixin):
+    raise RuntimeError("nonebot-plugin-grok-bot 需要 ASGI 驱动器（如 ~fastapi）来挂载 MCP Server")
+
+mcp = MCPServer(
+    name="nonebot-grok-bot",
+    instructions=(
+        "通过这些工具向聊天平台发送消息。会话用 `group:<群号>` / `private:<QQ号>` 表示，"
+        "与 Webhook 推送中的 `session` 字段一致。消息由多个消息段组成，可图文混排，"
+        "可使用 QQ 内置表情（list_emojis）和本地表情包（search_stickers）。"
+    ),
+)
+
+
+class TextSegment(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+class ImageSegment(BaseModel):
+    type: Literal["image"]
+    url: str | None = Field(default=None, description="图片链接，可直接用 Webhook 推送中的链接（会自动续签 rkey）")
+    base64: str | None = Field(default=None, description="base64 编码的图片数据")
+
+
+class EmojiSegment(BaseModel):
+    type: Literal["emoji"]
+    id: str = Field(description="QQ 内置表情 ID，见 list_emojis")
+
+
+class StickerSegment(BaseModel):
+    type: Literal["sticker"]
+    name: str = Field(description="本地表情包名称，见 search_stickers")
+
+
+class AtSegment(BaseModel):
+    type: Literal["at"]
+    user_id: str
+
+
+class AtAllSegment(BaseModel):
+    type: Literal["at_all"]
+
+
+OutSegment = Annotated[
+    TextSegment | ImageSegment | EmojiSegment | StickerSegment | AtSegment | AtAllSegment,
+    Field(discriminator="type"),
+]
+
+
+async def to_segment(seg: OutSegment, session: str, bot: Bot) -> Segment:
+    match seg:
+        case TextSegment(text=text):
+            return Text(text)
+        case EmojiSegment(id=id_):
+            return Emoji(id_, FACES.get(id_))
+        case AtSegment(user_id=user_id):
+            return At("user", user_id)
+        case AtAllSegment():
+            return AtAll()
+        case StickerSegment(name=name):
+            return await stickers.load(name, session, bot)
+        case ImageSegment(url=str(url)):
+            return Image(url=await with_rkey(url, bot))
+        case ImageSegment(base64=str(b64)):
+            return Image(raw=base64.b64decode(b64))
+        case ImageSegment():
+            raise ValueError("image 消息段需要 url 或 base64 之一")
+    raise ValueError(f"不支持的消息段：{seg!r}")
+
+
+@mcp.tool()
+@expose_errors
+async def send_message(
+    session: str,
+    segments: list[OutSegment],
+    reply_to: str | None = None,
+    self_id: str | None = None,
+) -> dict[str, Any]:
+    """向会话发送一条消息，支持文字、图片、QQ 内置表情、本地表情包、@ 混排。
+
+    Args:
+        session: 目标会话，如 `group:123456` 或 `private:123456`
+        segments: 消息段列表，按顺序拼接
+        reply_to: 要回复的消息 ID（来自 Webhook 推送的 message_id）
+        self_id: 指定用哪个 bot 账号发送，默认自动选择
+    """
+    if not segments:
+        raise ValueError("segments 不能为空")
+    target = resolve_target(session, self_id)
+    bot = await target.select()
+    message = UniMessage([await to_segment(seg, session, bot) for seg in segments])
+    if reply_to:
+        message.insert(0, Reply(reply_to))
+    receipt = await target.send(message, bot)
+    message_ids = [str(r.id) for r in receipt.get_reply() or []]
+    record_outgoing(
+        session,
+        build_message(
+            session, message_ids[0] if message_ids else None, bot.self_id, None, dump_segments(message), is_self=True
+        ),
+    )
+    return {"message_ids": message_ids}
+
+
+@mcp.tool()
+@expose_errors
+async def list_sessions() -> list[str]:
+    """列出自启动以来收到过消息的会话"""
+    return known_sessions()
+
+
+@mcp.tool()
+@expose_errors
+async def get_history(session: str, limit: int = 20) -> list[dict[str, Any]]:
+    """获取会话最近的消息（包括 bot 自己发的），格式与 Webhook 推送一致"""
+    return history_of(session, limit)
+
+
+@mcp.tool()
+@expose_errors
+async def get_image(url: str, session: str | None = None) -> MCPImage:
+    """查看图片内容，例如 Webhook 推送或历史消息中的图片；QQ 图片链接过期会自动续签
+
+    Args:
+        url: 图片链接
+        session: 图片所在会话，用于选择续签 rkey 的 bot 账号，可省略
+    """
+    bot = await resolve_target(session).select() if session else None
+    data = await download(url, bot)
+    return MCPImage(data=data, format=image_format(data))
+
+
+@mcp.tool()
+@expose_errors
+async def list_emojis() -> dict[str, str]:
+    """列出常用的 QQ 内置表情，返回 ID -> 名称"""
+    return FACES
+
+
+class _BearerAuth:
+    def __init__(self, app: ASGIApp, token: str) -> None:
+        self.app = app
+        self.expected = f"Bearer {token}".encode()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http" and dict(scope["headers"]).get(b"authorization") != self.expected:
+            await send({"type": "http.response.start", "status": 401, "headers": []})
+            await send({"type": "http.response.body", "body": b"Unauthorized"})
+            return
+        await self.app(scope, receive, send)
+
+
+_mcp_app: ASGIApp = mcp.streamable_http_app(host=str(driver.config.host))
+if config.grok_bot_mcp_token:
+    _mcp_app = _BearerAuth(_mcp_app, config.grok_bot_mcp_token)
+get_app().mount(config.grok_bot_mcp_prefix, _mcp_app)
+
+# 挂载的子应用不会触发自身 lifespan，需要手动管理 session manager
+_stack = AsyncExitStack()
+
+
+@driver.on_startup
+async def _() -> None:
+    stickers.register_tools(mcp)
+    await _stack.enter_async_context(mcp.session_manager.run())
+    logger.info(f"Grok Bot MCP Server 已挂载于 {config.grok_bot_mcp_prefix}/mcp")
+
+
+@driver.on_shutdown
+async def _() -> None:
+    await _stack.aclose()

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/qface.json

@@ -0,0 +1,280 @@
+{
+    "0": "惊讶",
+    "1": "撇嘴",
+    "2": "色",
+    "3": "发呆",
+    "4": "得意",
+    "5": "流泪",
+    "6": "害羞",
+    "7": "闭嘴",
+    "8": "睡",
+    "9": "大哭",
+    "10": "尴尬",
+    "11": "发怒",
+    "12": "调皮",
+    "13": "呲牙",
+    "14": "微笑",
+    "15": "难过",
+    "16": "酷",
+    "18": "抓狂",
+    "19": "吐",
+    "20": "偷笑",
+    "21": "可爱",
+    "22": "白眼",
+    "23": "傲慢",
+    "24": "饥饿",
+    "25": "困",
+    "26": "惊恐",
+    "27": "流汗",
+    "28": "憨笑",
+    "29": "悠闲",
+    "30": "奋斗",
+    "31": "咒骂",
+    "32": "疑问",
+    "33": "嘘",
+    "34": "晕",
+    "35": "折磨",
+    "36": "衰",
+    "37": "骷髅",
+    "38": "敲打",
+    "39": "再见",
+    "41": "发抖",
+    "42": "爱情",
+    "43": "跳跳",
+    "46": "猪头",
+    "49": "拥抱",
+    "53": "蛋糕",
+    "54": "闪电",
+    "55": "炸弹",
+    "56": "刀",
+    "57": "足球",
+    "59": "便便",
+    "60": "咖啡",
+    "61": "饭",
+    "63": "玫瑰",
+    "64": "凋谢",
+    "66": "爱心",
+    "67": "心碎",
+    "69": "礼物",
+    "74": "太阳",
+    "75": "月亮",
+    "76": "赞",
+    "77": "踩",
+    "78": "握手",
+    "79": "胜利",
+    "85": "飞吻",
+    "86": "怄火",
+    "89": "西瓜",
+    "96": "冷汗",
+    "97": "擦汗",
+    "98": "抠鼻",
+    "99": "鼓掌",
+    "100": "糗大了",
+    "101": "坏笑",
+    "102": "左哼哼",
+    "103": "右哼哼",
+    "104": "哈欠",
+    "105": "鄙视",
+    "106": "委屈",
+    "107": "快哭了",
+    "108": "阴险",
+    "109": "左亲亲",
+    "110": "吓",
+    "111": "可怜",
+    "112": "菜刀",
+    "113": "啤酒",
+    "114": "篮球",
+    "115": "乒乓",
+    "116": "示爱",
+    "117": "瓢虫",
+    "118": "抱拳",
+    "119": "勾引",
+    "120": "拳头",
+    "121": "差劲",
+    "122": "爱你",
+    "123": "NO",
+    "124": "OK",
+    "125": "转圈",
+    "126": "磕头",
+    "127": "回头",
+    "128": "跳绳",
+    "129": "挥手",
+    "130": "激动",
+    "131": "街舞",
+    "132": "献吻",
+    "133": "左太极",
+    "134": "右太极",
+    "136": "双喜",
+    "137": "鞭炮",
+    "138": "灯笼",
+    "140": "K歌",
+    "144": "喝彩",
+    "145": "祈祷",
+    "146": "爆筋",
+    "147": "棒棒糖",
+    "148": "喝奶",
+    "151": "飞机",
+    "158": "钞票",
+    "168": "药",
+    "169": "手枪",
+    "171": "茶",
+    "172": "眨眼睛",
+    "173": "泪奔",
+    "174": "无奈",
+    "175": "卖萌",
+    "176": "小纠结",
+    "177": "喷血",
+    "178": "斜眼笑",
+    "179": "doge",
+    "180": "惊喜",
+    "181": "骚扰",
+    "182": "笑哭",
+    "183": "我最美",
+    "184": "河蟹",
+    "185": "羊驼",
+    "187": "幽灵",
+    "188": "蛋",
+    "190": "菊花",
+    "192": "红包",
+    "193": "大笑",
+    "194": "不开心",
+    "197": "冷漠",
+    "198": "呃",
+    "199": "好棒",
+    "200": "拜托",
+    "201": "点赞",
+    "202": "无聊",
+    "203": "托脸",
+    "204": "吃",
+    "205": "送花",
+    "206": "害怕",
+    "207": "花痴",
+    "208": "小样儿",
+    "210": "飙泪",
+    "211": "我不看",
+    "212": "托腮",
+    "214": "啵啵",
+    "215": "糊脸",
+    "216": "拍头",
+    "217": "扯一扯",
+    "218": "舔一舔",
+    "219": "蹭一蹭",
+    "220": "拽炸天",
+    "221": "顶呱呱",
+    "222": "抱抱",
+    "223": "暴击",
+    "224": "开枪",
+    "225": "撩一撩",
+    "226": "拍桌",
+    "227": "拍手",
+    "228": "恭喜",
+    "229": "干杯",
+    "230": "嘲讽",
+    "231": "哼",
+    "232": "佛系",
+    "233": "掐一掐",
+    "234": "惊呆",
+    "235": "颤抖",
+    "236": "啃头",
+    "237": "偷看",
+    "238": "扇脸",
+    "239": "原谅",
+    "240": "喷脸",
+    "241": "生日快乐",
+    "242": "头撞击",
+    "243": "甩头",
+    "244": "扔狗",
+    "245": "加油必胜",
+    "246": "加油抱抱",
+    "247": "口罩护体",
+    "260": "搬砖中",
+    "261": "忙到飞起",
+    "262": "脑阔疼",
+    "263": "沧桑",
+    "264": "捂脸",
+    "265": "辣眼睛",
+    "266": "哦哟",
+    "267": "头秃",
+    "268": "问号脸",
+    "269": "暗中观察",
+    "270": "emm",
+    "271": "吃瓜",
+    "272": "呵呵哒",
+    "273": "我酸了",
+    "274": "太南了",
+    "276": "辣椒酱",
+    "277": "汪汪",
+    "278": "汗",
+    "279": "打脸",
+    "280": "击掌",
+    "281": "无眼笑",
+    "282": "敬礼",
+    "283": "狂笑",
+    "284": "面无表情",
+    "285": "摸鱼",
+    "286": "魔鬼笑",
+    "287": "哦",
+    "288": "请",
+    "289": "睁眼",
+    "290": "敲开心",
+    "291": "震惊",
+    "292": "让我康康",
+    "293": "摸锦鲤",
+    "294": "期待",
+    "295": "拿到红包",
+    "296": "真好",
+    "297": "拜谢",
+    "298": "元宝",
+    "299": "牛啊",
+    "300": "胖三斤",
+    "301": "好闪",
+    "302": "左拜年",
+    "303": "右拜年",
+    "304": "红包包",
+    "305": "右亲亲",
+    "306": "牛气冲天",
+    "307": "喵喵",
+    "308": "求红包",
+    "309": "谢红包",
+    "310": "新年烟花",
+    "311": "打call",
+    "312": "变形",
+    "313": "嗑到了",
+    "314": "仔细分析",
+    "315": "加油",
+    "316": "我没事",
+    "317": "菜狗",
+    "318": "崇拜",
+    "319": "比心",
+    "320": "庆祝",
+    "321": "老色痞",
+    "322": "拒绝",
+    "323": "嫌弃",
+    "324": "吃糖",
+    "325": "惊吓",
+    "326": "生气",
+    "327": "加一",
+    "328": "错号",
+    "329": "对号",
+    "330": "完成",
+    "331": "明白",
+    "332": "举牌牌",
+    "333": "烟花",
+    "334": "虎虎生威",
+    "336": "豹富",
+    "337": "花朵脸",
+    "338": "我想开了",
+    "339": "舔屏",
+    "340": "热化了",
+    "341": "打招呼",
+    "342": "酸Q",
+    "343": "我方了",
+    "344": "大怨种",
+    "345": "红包多多",
+    "346": "你真棒棒",
+    "347": "大展宏兔",
+    "348": "福萝卜",
+    "351": "敲敲",
+    "424": "狂敲按钮",
+    "429": "蛇年快乐"
+}

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/rkey.py

@@ -0,0 +1,59 @@
+"""QQ NT 图片链接带有会过期的 rkey，过期后通过 OneBot 扩展 API `get_rkey` 重新签发"""
+
+import asyncio
+from datetime import datetime, timedelta
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+from nonebot import get_bots, logger
+from nonebot.adapters import Bot
+
+_rkeys: dict[str, tuple[datetime, str]] = {}
+_lock = asyncio.Lock()
+
+
+def is_qq_media(url: str) -> bool:
+    return urlparse(url).hostname == "multimedia.nt.qq.com.cn"
+
+
+def _kind(url: str) -> str:
+    # appid 1406 为私聊图片，1407 为群聊图片
+    return "private" if parse_qs(urlparse(url).query).get("appid") == ["1406"] else "group"
+
+
+def any_onebot_bot() -> Bot | None:
+    return next((bot for bot in get_bots().values() if bot.adapter.get_name() == "OneBot V11"), None)
+
+
+async def _refresh(bot: Bot, force: bool) -> None:
+    async with _lock:
+        now = datetime.now()
+        if not force and all(_rkeys.get(k, (datetime.min, ""))[0] > now for k in ("group", "private")):
+            return
+        try:
+            ret = await bot.call_api("get_rkey")
+        except Exception as e:
+            logger.warning(f"get_rkey 调用失败：{e!r}")
+            return
+        if isinstance(ret, dict):
+            ret = ret.get("rkeys", [])
+        if not isinstance(ret, list):
+            logger.warning(f"get_rkey 返回了奇怪的东西：{ret!r}")
+            return
+        for item in ret:
+            expire = datetime.fromtimestamp(int(item.get("created_at", 0))) + timedelta(
+                seconds=int(item.get("ttl", 0)) - 300
+            )
+            _rkeys[item.get("type")] = (expire, item.get("rkey", "").removeprefix("&rkey="))
+
+
+async def with_rkey(url: str, bot: Bot | None = None, *, force: bool = False) -> str:
+    """给 QQ 图片链接换上当前有效的 rkey，非 QQ 链接或无法获取时原样返回"""
+    if not is_qq_media(url) or not (bot := bot or any_onebot_bot()):
+        return url
+    await _refresh(bot, force)
+    if not (rkey := _rkeys.get(_kind(url), (None, ""))[1]):
+        return url
+    parsed = urlparse(url)
+    params = parse_qs(parsed.query)
+    params["rkey"] = [rkey]
+    return urlunparse(parsed._replace(query=urlencode(params, doseq=True)))

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/session.py

@@ -0,0 +1,154 @@
+from collections import defaultdict, deque
+from datetime import datetime
+from typing import Any
+
+from nonebot import get_driver, get_plugin_config, logger
+from nonebot.adapters import Bot
+from nonebot.drivers import HTTPClientMixin, Request
+from nonebot_plugin_alconna.uniseg import (
+    At,
+    AtAll,
+    Emoji,
+    Image,
+    Reply,
+    Target,
+    Text,
+    UniMessage,
+)
+
+from .config import Config
+from .faces import FACES
+from .rkey import is_qq_media, with_rkey
+
+config = get_plugin_config(Config)
+
+
+def session_key(target: Target) -> str:
+    if target.private:
+        return f"private:{target.id}"
+    if target.channel:
+        return f"channel:{target.parent_id}/{target.id}"
+    return f"group:{target.id}"
+
+
+def is_allowed(session: str) -> bool:
+    kind, _, id_ = session.partition(":")
+    if kind == "private":
+        return id_ in config.grok_bot_owners or id_ in config.grok_bot_allowed_users
+    return id_ in config.grok_bot_allowed_groups
+
+
+def savepic_scope(session: str) -> str:
+    kind, _, id_ = session.partition(":")
+    return f"qq_group:{id_}" if kind == "group" else "globe"
+
+
+_targets: dict[str, Target] = {}
+_history: defaultdict[str, deque[dict[str, Any]]] = defaultdict(lambda: deque(maxlen=config.grok_bot_history_size))
+
+
+def remember_target(target: Target) -> str:
+    key = session_key(target)
+    _targets[key] = target
+    return key
+
+
+def resolve_target(session: str, self_id: str | None = None) -> Target:
+    kind, _, id_ = session.partition(":")
+    if kind not in ("private", "group", "channel"):
+        raise ValueError(f"无法解析的会话：{session}，应为 group:<id> / private:<id> / channel:<guild>/<channel>")
+    if not is_allowed(session):
+        raise PermissionError(f"会话 {session} 不在白名单中")
+    if target := _targets.get(session):
+        return target
+    if kind == "private":
+        return Target(id_, private=True, self_id=self_id)
+    if kind == "channel":
+        parent_id, _, channel_id = id_.partition("/")
+        return Target(channel_id, parent_id=parent_id, channel=True, self_id=self_id)
+    return Target(id_, self_id=self_id)
+
+
+def known_sessions() -> list[str]:
+    return list(_targets)
+
+
+def record_history(session: str, message: dict[str, Any]) -> None:
+    _history[session].append(message)
+
+
+def get_history(session: str, limit: int) -> list[dict[str, Any]]:
+    return list(_history[session])[-limit:]
+
+
+async def _get(url: str) -> bytes:
+    driver = get_driver()
+    if not isinstance(driver, HTTPClientMixin):
+        raise RuntimeError("下载图片需要 HTTP 客户端驱动器（如 ~httpx 或 ~aiohttp）")
+    resp = await driver.request(Request("GET", url, timeout=config.grok_bot_webhook_timeout))
+    if resp.status_code != 200 or resp.content is None:
+        raise RuntimeError(f"下载图片失败：HTTP {resp.status_code}")
+    return resp.content if isinstance(resp.content, bytes) else resp.content.encode()
+
+
+async def download(url: str, bot: Bot | None = None) -> bytes:
+    """下载图片；QQ 图片链接先换上有效的 rkey，失败时强制重新签发后再试一次"""
+    if not is_qq_media(url):
+        return await _get(url)
+    try:
+        return await _get(await with_rkey(url, bot))
+    except RuntimeError:
+        return await _get(await with_rkey(url, bot, force=True))
+
+
+def image_format(data: bytes) -> str:
+    if data.startswith(b"\x89PNG"):
+        return "png"
+    if data.startswith(b"GIF8"):
+        return "gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "webp"
+    return "jpeg"
+
+
+def dump_segments(message: UniMessage) -> list[dict[str, Any]]:
+    """把 UniMessage 转成给 Grok Bot 看的精简格式，与 MCP send_message 的入参格式对应"""
+    ret: list[dict[str, Any]] = []
+    for seg in message:
+        if isinstance(seg, Text):
+            ret.append({"type": "text", "text": seg.text})
+        elif isinstance(seg, At):
+            ret.append({"type": "at", "user_id": seg.target})
+        elif isinstance(seg, AtAll):
+            ret.append({"type": "at_all"})
+        elif isinstance(seg, Emoji):
+            ret.append({"type": "emoji", "id": seg.id, "name": seg.name or FACES.get(seg.id)})
+        elif isinstance(seg, Image):
+            ret.append({"type": "image", "url": seg.url, "sticker": seg.sticker})
+        elif isinstance(seg, Reply):
+            ret.append({"type": "reply", "message_id": seg.id})
+        else:
+            logger.debug(f"未专门处理的消息段：{seg!r}")
+            ret.append({"type": seg.type, "text": str(seg)})
+    return ret
+
+
+def build_message(
+    session: str,
+    message_id: str | None,
+    user_id: str,
+    nickname: str | None,
+    segments: list[dict[str, Any]],
+    *,
+    is_owner: bool = False,
+    is_self: bool = False,
+    to_me: bool = False,
+) -> dict[str, Any]:
+    return {
+        "session": session,
+        "message_id": message_id,
+        "time": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "sender": {"user_id": user_id, "nickname": nickname, "is_owner": is_owner, "is_self": is_self},
+        "to_me": to_me,
+        "segments": segments,
+    }

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/stickers.py

@@ -0,0 +1,75 @@
+"""本地表情包，基于可选依赖 nonebot-plugin-savepic"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import anyio
+from nonebot import logger
+from nonebot.adapters import Bot
+from nonebot.plugin import get_plugin
+from nonebot_plugin_alconna.uniseg import Image
+
+from .errors import expose_errors
+from .rkey import with_rkey
+from .session import download, image_format, savepic_scope
+
+if TYPE_CHECKING:
+    from mcp.server.mcpserver import MCPServer
+
+
+def available() -> bool:
+    return get_plugin("nonebot_plugin_savepic") is not None
+
+
+async def _url(name: str, session: str) -> str:
+    if not available():
+        raise RuntimeError("未加载 nonebot-plugin-savepic，无法使用本地表情包")
+    from nonebot_plugin_savepic.core.sql import select_pic
+
+    if not (url := await select_pic(name, savepic_scope(session))):
+        raise ValueError(f"表情包 {name} 不存在，请先用 search_stickers 搜索")
+    return url
+
+
+async def load(name: str, session: str, bot: Bot) -> Image:
+    url = await _url(name, session)
+    if url.startswith("http"):
+        return Image(url=await with_rkey(url, bot), sticker=True)
+    return Image(path=Path(url), sticker=True)
+
+
+def register_tools(mcp: "MCPServer") -> None:
+    if not available():
+        logger.info("未加载 nonebot-plugin-savepic，跳过表情包工具")
+        return
+
+    from mcp.server.mcpserver.utilities.types import Image as MCPImage
+
+    try:
+        from nonebot_plugin_savepic.core.sql import search_pic
+    except ImportError:
+        logger.warning("nonebot-plugin-savepic 版本过旧（缺少 search_pic），跳过表情包工具")
+        return
+
+    @mcp.tool()
+    @expose_errors
+    async def search_stickers(query: str, session: str, limit: int = 10) -> list[dict[str, Any]]:
+        """搜索本地表情包，先按名称匹配，不足时按语义相似度补充。
+
+        Args:
+            query: 关键词，可以是名称片段或想表达的情绪/含义
+            session: 要发送到的会话，决定可用的表情包范围（群表情包 + 全局表情包）
+            limit: 最多返回多少个
+        """
+        return [
+            {"name": pic.name, "global": "globe" in pic.scope, "similarity": similarity}
+            for pic, similarity in await search_pic(query, savepic_scope(session), limit)
+        ]
+
+    @mcp.tool()
+    @expose_errors
+    async def view_sticker(name: str, session: str) -> MCPImage:
+        """查看某个本地表情包的图片内容，确认是否合适再发送"""
+        url = await _url(name, session)
+        data = await download(url) if url.startswith("http") else await anyio.Path(url).read_bytes()
+        return MCPImage(data=data, format=image_format(data))

nonebot_plugin_grok_bot-0.1.0/src/nonebot_plugin_grok_bot/webhook.py

@@ -0,0 +1,163 @@
+import asyncio
+import fnmatch
+from collections import deque
+from typing import Any, Literal
+
+from nonebot import get_driver, get_plugin_config, logger, on_message
+from nonebot.adapters import Bot, Event
+from nonebot.drivers import HTTPClientMixin, Request
+from nonebot_plugin_alconna.uniseg import UniMsg, get_message_id, get_target
+
+from .config import Config, Route
+from .session import build_message, dump_segments, is_allowed, record_history, remember_target, session_key
+
+driver = get_driver()
+config = get_plugin_config(Config)
+
+if config.grok_bot_routes and not isinstance(driver, HTTPClientMixin):
+    raise RuntimeError("推送 Webhook 需要 HTTP 客户端驱动器（如 ~httpx 或 ~aiohttp）")
+
+Trigger = Literal["owner", "interval", "size"]
+
+
+def match_route(session: str) -> Route | None:
+    for route in config.grok_bot_routes:
+        if any(fnmatch.fnmatchcase(session, pattern) for pattern in route.sessions):
+            return route
+    return None
+
+
+class SessionBuffer:
+    def __init__(self, session: str, route: Route) -> None:
+        self.session = session
+        self.route = route
+        self.pending: deque[dict[str, Any]] = deque(maxlen=route.max_pending)
+        self.timer: asyncio.Task[None] | None = None
+
+    def add(self, message: dict[str, Any], *, trigger: bool) -> None:
+        self.pending.append(message)
+        if not trigger:
+            return
+        if self._owner_triggers(message):
+            self.flush("owner")
+        elif self.route.flush_size and len(self.pending) >= self.route.flush_size:
+            self.flush("size")
+        elif self.route.flush_interval is not None and self.timer is None:
+            self.timer = asyncio.create_task(self._wait(self.route.flush_interval))
+
+    def _owner_triggers(self, message: dict[str, Any]) -> bool:
+        if not message["sender"]["is_owner"]:
+            return False
+        return self.route.owner_trigger == "always" or (self.route.owner_trigger == "to_me" and message["to_me"])
+
+    async def _wait(self, delay: float) -> None:
+        await asyncio.sleep(delay)
+        self.timer = None
+        self.flush("interval")
+
+    def flush(self, trigger: Trigger) -> None:
+        if self.timer:
+            self.timer.cancel()
+            self.timer = None
+        if not self.pending:
+            return
+        payload = {
+            "route": self.route.name,
+            "trigger": trigger,
+            "session": self.session,
+            "messages": list(self.pending),
+        }
+        self.pending.clear()
+        _background(post(self.route, payload))
+
+
+_buffers: dict[str, SessionBuffer] = {}
+_tasks: set[asyncio.Task[None]] = set()
+
+
+def _background(coro) -> None:
+    task = asyncio.create_task(coro)
+    _tasks.add(task)
+    task.add_done_callback(_tasks.discard)
+
+
+def get_buffer(session: str) -> SessionBuffer | None:
+    if session not in _buffers:
+        if not (route := match_route(session)):
+            return None
+        _buffers[session] = SessionBuffer(session, route)
+    return _buffers[session]
+
+
+async def post(route: Route, payload: dict[str, Any]) -> None:
+    assert isinstance(driver, HTTPClientMixin)
+    headers = {"Authorization": f"Bearer {route.webhook_key}"} if route.webhook_key else {}
+    for attempt in range(1, config.grok_bot_webhook_retries + 1):
+        try:
+            resp = await driver.request(
+                Request(
+                    "POST",
+                    route.webhook_url,
+                    headers=headers,
+                    json=payload,
+                    timeout=config.grok_bot_webhook_timeout,
+                )
+            )
+            if 200 <= resp.status_code < 300:
+                logger.debug(f"已推送 {len(payload['messages'])} 条消息到路由 {route.name}（{payload['trigger']}）")
+                return
+            if 400 <= resp.status_code < 500 and resp.status_code != 429:
+                logger.error(f"推送到路由 {route.name} 被拒绝：HTTP {resp.status_code} {resp.content!r}")
+                return
+            logger.warning(f"推送到路由 {route.name} 失败（第 {attempt} 次）：HTTP {resp.status_code}")
+        except Exception as e:
+            logger.warning(f"推送到路由 {route.name} 失败（第 {attempt} 次）：{e!r}")
+        await asyncio.sleep(2**attempt)
+    logger.error(f"推送到路由 {route.name} 最终失败，丢弃 {len(payload['messages'])} 条消息")
+
+
+def record_outgoing(session: str, message: dict[str, Any]) -> None:
+    """bot 自己发出的消息也记入上下文，但不触发推送"""
+    record_history(session, message)
+    if buffer := get_buffer(session):
+        buffer.add(message, trigger=False)
+
+
+async def _allowed(bot: Bot, event: Event) -> bool:
+    try:
+        return is_allowed(session_key(get_target(event, bot)))
+    except Exception:
+        return False
+
+
+listener = on_message(rule=_allowed, priority=1, block=False)
+
+
+@listener.handle()
+async def _(bot: Bot, event: Event, msg: UniMsg) -> None:
+    session = remember_target(get_target(event, bot))
+    user_id = event.get_user_id()
+    sender = getattr(event, "sender", None)
+    nickname = getattr(sender, "card", None) or getattr(sender, "nickname", None)
+    message = build_message(
+        session,
+        get_message_id(event, bot),
+        user_id,
+        nickname,
+        dump_segments(msg),
+        is_owner=user_id in config.grok_bot_owners,
+        to_me=event.is_tome(),
+    )
+    record_history(session, message)
+    if buffer := get_buffer(session):
+        buffer.add(message, trigger=True)
+
+
+@driver.on_shutdown
+async def _() -> None:
+    # 只有配置了自动推送的路由才在退出前清空积压，否则这些消息只是等待 Owner 触发的上下文
+    for buffer in _buffers.values():
+        if buffer.route.flush_interval is not None or buffer.route.flush_size:
+            buffer.flush("interval")
+    if _tasks:
+        await asyncio.wait(_tasks, timeout=config.grok_bot_webhook_timeout)