QQ 機器人

用 QQ 官方機器人 向 zqagent 發起任務，並在任務完成時通過 電子郵件（SMTP） 通知你。支援單聊、群聊（@機器人）、頻道，以及審核 / 提問 / 中斷等完整互動。

官方機器人走出站長連線，無需公網入站，自建/內網伺服器也能收訊息。

平臺準備（一次性）

在 QQ 開放平臺註冊並建立機器人，獲得 AppID + AppSecret。
申請 GROUP_AND_C2C_EVENT（1<<25） 等 intents 許可權（單聊+群聊訊息事件屬特殊許可權，需申請；否則閘道器鑑權會拒絕）。頻道 @ 與頻道私信分別對應 PUBLIC_GUILD_MESSAGES（1<<30）與 DIRECT_MESSAGE（1<<12）。
聯調階段使用沙箱環境（僅沙箱成員可測試），正式上線需稽核。

設定

方式一：.env 環境變數（啟動時讀入）

bash

# .env
QQ_BOT_APP_ID=你的AppID
QQ_BOT_APP_SECRET=你的AppSecret
QQ_BOT_SANDBOX=1          # 沙箱=1；正式環境=0 或留空

方式二：熱設定（server 已啟動時，無需重啟，立即重連生效）

bash

# 檢視當前設定（脫敏）
curl -s -H "Authorization: Bearer <租戶apiKey>" http://localhost:8787/api/v1/qq/config

# 設定 / 更新
curl -s -X POST -H "Authorization: Bearer <租戶apiKey>" -H "Content-Type: application/json" \
  -d '{"appId":"你的AppID","appSecret":"你的AppSecret","sandbox":true}' \
  http://localhost:8787/api/v1/qq/config

# 刪除設定（斷開）
curl -s -X DELETE -H "Authorization: Bearer <租戶apiKey>" http://localhost:8787/api/v1/qq/config

設定後日志出現 QQ 機器人: 已啟用。熱設定會隨服務端儲存，重啟後仍生效（設定來源優先順序：環境變數 > 儲存的設定）。

多租戶繫結

方式一：單租戶免繫結（推薦個人使用）

系統只有一個租戶（如預設的 demo）時，無需任何繫結操作，直接發訊息即自動繫結到唯一租戶並開始任務。

方式二：配對碼繫結（多租戶）

bash

# 生成配對碼（管理員，REST API）
curl -X POST http://localhost:8787/api/v1/qq/pairing-code \
  -H "Authorization: Bearer <租戶apiKey>"
# → { "data": { "code": "AB3CD5K7", "expiresIn": 300 } }

使用者在 QQ 內繫結：

/bind AB3CD5K7
→ 繫結成功 ✅ 租戶：demo。現在直接發訊息即可開始任務。

配對碼 5 分鐘有效、單次使用（避免 apiKey 明文進入聊天記錄）。
每個 QQ 會話對應一個租戶 + 一個 zqagent session；首次發任務時自動建立會話。
繫結對映落盤於 {DATA_DIR}/qq/bindings.json。

命令列表

命令	行為
直接發訊息	提交任務（等待提問時作為答案；任務執行中則作為補充資訊）
`/bind <配對碼>`	綁定當前 QQ 會話到租戶
`/unbind`	解除繫結
`/new`	新建會話並切換繫結
`/status`	檢視當前會話狀態
`/list`	會話列表
`/stop`	中斷當前任務
`/approve <once\|always_tool\|always_command\|deny>`	審核（也可直接發「同意/全部同意/拒絕」）
`/answer <內容>`	回答提問
`/help`	幫助

任務執行中直接發訊息，會作為**補充資訊（steering）**注入當前任務；需要另起任務時請先 /stop 或等任務結束。

通知回發與審核

任務執行中的關鍵事件會回發到對應 QQ 會話。審核請求會附上工具名 + 工具引數 + 原因：

需要審核：write_file
引數：
{
  "path": "/tmp/a.txt",
  "content": "hello"
}
原因：需要寫檔案
回覆：同意(僅本次) / 全部同意(總是允許) / 拒絕

同意 / 允許 / y → 僅本次允許（once）
全部同意 / 總是允許 → 本會話內總是允許該工具（always_tool）
拒絕 / n → 拒絕（deny）

⚠️ QQ 官方機器人對主動訊息有嚴格配額；任務完成通常超出「被動回覆 5 分鐘視窗」，因此完成通知以電子郵件為可靠通道，QQ 內回發盡力而為。

設定電子郵件通知

bash

curl -X POST http://localhost:8787/api/v1/notifications \
  -H "Authorization: Bearer <租戶apiKey>" -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "enabled": true,
    "config": {
      "host": "smtp.qq.com",
      "port": "465",
      "secure": "true",
      "user": "you@qq.com",
      "pass": "<QQ電子電子郵件授權碼>",
      "from": "you@qq.com",
      "to": "you@qq.com"
    },
    "events": { "approval": false, "question": false, "completed": true, "error": true }
  }'

QQ 電子電子郵件：smtp.qq.com:465（SSL）+ 授權碼（不是登入密碼）。
163：smtp.163.com:465；Gmail：smtp.gmail.com:587（secure:"false"）。
pass 等敏感欄位會用 SECRET_KEY AES 加密落盤。
events 控制觸發時機；上例只在「完成/錯誤」時發電子郵件。
短任務不打擾：minDurationSeconds（預設 60）——任務成功完成且執行時長未超過該閾值時不發電子郵件。

QQ 機器人 ​

平臺準備（一次性） ​

設定 ​

多租戶繫結 ​

命令列表 ​

通知回發與審核 ​

設定電子郵件通知 ​

QQ 機器人

平臺準備（一次性）

設定

多租戶繫結

命令列表

通知回發與審核

設定電子郵件通知