QQ 机器人

QQ 官方机器人 v2 消息通知，支持 Ed25519 webhook 事件。每个机器人每月主动消息上限为 4 条，建议设计为被动回复模式。

⚠️ 使用被动回复，而非主动推送。 QQ 对每个机器人的主动消息上限为每月 4 条。每日上限：主动私信 200 条，每个频道子频道主动消息 20 条。大多数生产交互须回复用户的入站消息（机器人有 5 秒响应，不计配额），仅在关键提醒时才主动推送。

功能概览

四个发送入口，按 channel 前缀路由：
- c2c:<openid> → /v2/users/{openid}/messages（C2C 私信）
- group:<openid> → /v2/groups/{openid}/messages（群组）
- channel:<id>（默认）→ /channels/{channel_id}/messages（公开频道）
- dm:<guild_id> → /dms/{guild_id}/messages（频道私信）
入站 webhook 地址为 /webhooks/qq，使用 Ed25519 签名验证。
access_token 缓存 7200 秒，自动刷新。
仅支持文本。 富媒体消息（图片、文件、ARK 卡片）为后续功能。
文本长度上限 4000 字符。

选择最常用的目标，并加上对应前缀：

公开频道场景可省略前缀（最常见）：

QQ_BOT_DEFAULT_CHANNEL_ID=1234567890

等同于 channel:1234567890。

minara auth messaging add
# 选择 `qq`；粘贴 AppID、AppSecret 及默认目标。

或设置环境变量：

QQ_BOT_APP_ID=12345678
QQ_BOT_APP_SECRET=<opaque secret>
QQ_BOT_TOKEN=<bot token>
QQ_BOT_DEFAULT_CHANNEL_ID=channel:1234567890

minara auth messaging test qq

会消耗每月主动消息配额，请合理规划。

QQ 使用 Ed25519 对入站请求体签名，签名内容为 <timestamp><raw_body>。平台不公开公钥；公钥由机器人密钥派生：

Minara 在内部处理此 seed 派生密钥对。重放窗口为 5 分钟（与 Discord、Slack 约定一致）。

验证握手：平台发送 {op: 13, d: {plain_token, event_ts}} 时， Minara 使用派生私钥对 event_ts + plain_token 签名，并回复签名后的十六进制字符串。平台以此证明端点持有密钥。

接受的入站事件类型：

其他 op=0 分发事件（频道更新、表情回应等）会被忽略。

主动消息配额。 每月 4 条，私信每日 200 条，每个子频道每日 20 条。配额耗尽后返回错误码 130_001；若有一定推送量，此错误属于预期现象。
被动回复是推荐模式。 用户 @ 机器人，机器人在 5 秒内回复，不计主动配额。
新机器人必须使用 Webhook。 WebSocket 沙盒模式在 v2 中已弃用。

"测试消息返回 errcode 130001"

"入站 webhook 返回 401"

"验证握手（op=13）失败"