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）失敗"