前言¶

在 DSH 裏做自動化或對話式助手時，常見需求是讓模型能讀 QQ 私聊和羣消息、代你回覆，或按規則自動應答。自己寫 OneBot 客戶端、維護會話映射和去重，工作量大且容易和宿主進程的狀態打架。社區插件 mira_qqbot（維護者 Stella-Mira）走另一條路：用 OneBot v11 正向 WebSocket 連本機 NapCat（跑在你的 QQ 客戶端裏），把「你本人的 QQ」交給 DSH，並把協議能力收成 qq_* 工具；賬號池、會話綁定、入站路由與 message_id 去重則交給同生態的 mira_account（1.18.0 起協議層與賬號層刻意拆分）。下面介紹它是什麼、能做什麼，以及如何配置與使用。

這是什麼¶

mira_qqbot 是 DSH 的 QQ 接管插件（協議層），當前版本 1.18.0（MIT）。在 SkillHub 社區目錄中歸類爲 聯網工具（目錄頁：https://www.skillhub.cn/plugins/Stella-Mira/mira_qqbot；源碼：https://github.com/Stella-Mira/mira_qqbot）。

一句話定位：連 NapCat 的 OneBot 端點，向模型暴露 21 個 qq_* 工具，並可選地把入站消息投遞給 agent（steer/queue、忙通告、超時、/stop 與 /new 等）。

硬依賴：安裝 mira_qqbot 必須同時安裝 mira_account。宿主需注入 tools、agents、workspaceRegistry、miraAccount；缺少 mira_account 時本插件 deliberately 不加載，工具不會出現，便於排查「起來了但發不出去」類問題。

配置與附件落盤位置（DSH_HOME 缺省爲 ~/.dsh）：

$DSH_HOME/mira_config/mira_qqbot/
  config.json      schemaVersion 1；含 accessToken 時文件權限 600，且永不回顯/不進日誌
  files/           入站附件；可用 mediaDir 覆蓋

核心功能¶

協議與賬號分工¶

自 1.18.0 起，本插件只做 OneBot 連接、事件解析、媒體與 qq_* 工具；舊的 chatId → sessionId 本地表（<agentCwd>/data/meta.json）已刪除，一律使用 mira_account 的綁定表。與 mira_account 的三條約定在 README 中寫死：

入站：不維護本地 session 映射；已綁定 peer 由本插件 route 投遞（支持 per-peer queue、忙通告、超時）；未綁定走 miraAccount.inbound() 與賬號 inboundPolicy。
出站：qq_send_* 經 miraAccount.send；發送成功會把該會話登記爲該 peer 的 taker（反向綁定）。
錯誤：工具統一返回 {ok:false,error:{code,message,hint}}，平臺側常見碼包括 delivery/failed、binding/conflict、account/*、config/*。

連接層支持 WebSocket 指數退避重連（reconnectMinMs / reconnectMaxMs）、單次 API 調用超時（callTimeoutMs），以及斷線期間的 積壓策略（backlog.policy：drop / latest_n / replay）。

qq_* 工具集（21 個）¶

模型側主要通過這些工具操作 QQ（前綴均爲 qq_）：

類別	工具
狀態與角色	`qq_status`、`qq_role`
資料與列表	`qq_get_login_info`、`qq_get_friend_list`、`qq_get_group_list`、`qq_get_group_member_list`、`qq_get_stranger_info`
發送	`qq_send_private_msg`、`qq_send_group_msg`、`qq_send_msg`、`qq_send_media_file`、`qq_send_voice`
接收與歷史	`qq_recv_messages`、`qq_get_msg`、`qq_get_group_msg_history`
管理與審批	`qq_delete_msg`、`qq_set_group_ban`、`qq_set_group_kick`、`qq_set_group_whole_ban`、`qq_handle_friend_request`、`qq_handle_group_request`
逃生艙	`qq_api`（通用 OneBot action）

qq_recv_messages 使用環形緩衝（默認上限 bufferSize: 500），按 since 增量拉取；入站去重在 mira_account 投遞路徑完成，緩衝本身保留原始事件視圖。

自動應答與羣策略¶

reply.* 配置塊控制是否把入站消息投給 agent（reply.enabled）、人設與規則提示詞、私聊白名單（reply.privateWhitelist）、羣內 @/關鍵詞觸發（reply.groupAccess、reply.trigger.*）、消息合併窗口（reply.mergeWindowMs）、agent 超時（reply.agentTimeoutMs）以及 /new、/stop 命令文案。默認入站投遞方式爲 steer（插話），可按 peer 在 delivery.byPeer 中改爲 queue。

安裝與啓用¶

README 與倉庫 未給出 單獨的 dsh plugin add … 一行命令；安裝方式請以 SkillHub 目錄頁 與當前 DSH 版本的插件管理文檔爲準，源碼倉庫爲 https://github.com/Stella-Mira/mira_qqbot。不要只裝本插件：須一併啓用 mira_account，並在 $DSH_HOME/mira_config/mira_account/accounts.json 登記 QQ 賬號（例如 {"id":"qq-main","platform":"qq","enabled":true,"inboundPolicy":"create"}）。

1. 部署 NapCat 與 OneBot WebSocket¶

插件不替你做 QQ 登錄；需要本機 NapCat 暴露 OneBot v11 正向 WebSocket。倉庫自帶腳本（用法見腳本頭部註釋）：

bash scripts/setup-napcat.sh            # 部署/配置 OneBot WS
bash scripts/start-napcat.sh            # 按 napcat.conf 啓動

Linux/macOS 可用 setup-napcat.sh / start-napcat.sh；Windows 使用 setup-napcat.ps1，啓動腳本在原生環境下需 Git Bash 或 WSL。核心目標是把 ws 地址 與 access_token（若啓用）記下來，填進下面配置文件。

2. 編寫 config.json¶

首次加載會在 $DSH_HOME/mira_config/mira_qqbot/config.json 生成僅含 schemaVersion 與 _hint 的模板。必填項包括 wsUrl（如 ws://127.0.0.1:3001）；爲空時工具會直接返回 config/missing，本插件不會自動探測端口。accountId 應對應 mira_account 裏登記的 id；若賬號池只有一個 QQ 賬號且留空，會 warn 一次並使用該賬號；多個 QQ 賬號且未指定則會報 config/missing 並列出候選。

最小可用示例（來自 README，請把 agentCwd 換成你的 DSH 工作空間路徑）：

{
  "schemaVersion": 1,
  "wsUrl": "ws://127.0.0.1:3001",
  "accessToken": "",
  "accountId": "qq-main",
  "reply": { "enabled": true, "agentPreset": "stella", "agentCwd": "<您的 workspace>" }
}

accessToken 爲空字符串是合法值（NapCat 未開鑑權時）；非空時只通過 OneBot Authorization 頭髮送，不會出現在日誌或 qq_status 返回值中。

3. 重啓 DSH 並自檢¶

重啓宿主後，在 agent 會話中調用 qq_status：期望 connected: true，且 config.wsUrlConfigured 等爲 true。若缺 wsUrl，qq_status 本身會返回 config/missing（而不是空狀態對象）。插件自帶 smoke 測試（不連真實 NapCat）：

cd mira_qqbot && node test/smoke.mjs

期望末行：==== ALL PASS（219 項斷言）====，退出碼 0。

典型用法¶

用 qq_status 確認鏈路¶

連接正常時，qq_status 會彙總連接態、selfId、綁定行、隊列長度、斷線積壓計數、忽略原因（白名單/羣未觸發等）以及 legacyConfigKeys（若 profile 裏仍保留 1.17 時代的 autoReply.* 鍵）。缺配置時優先讀 error.code 與 hint，例如 wsUrl 未填時按 hint 編輯 config.json。

模型主動發消息¶

統一入口 qq_send_msg：純數字 QQ 號走私聊，group:羣號 走羣聊。發送類工具默認按純文本發出（會對 [ ] & 做 CQ 實體轉義）；確需 CQ 碼（如 [CQ:at,qq=…]）時傳 cq: true。成功時返回含 messageId 與 binding 的對象；若 peer 已被其他會話佔用，會返回 binding/conflict，hint 說明可用 force:true 接管或 observer:true 旁聽。

拉取緩衝中的入站¶

關閉自動應答（reply.enabled: false）或只想由模型輪詢時，使用 qq_recv_messages，以返回的 maxSeq 作爲下次的 since。hasMore / truncated 爲 true 時繼續拉，避免跳過中間消息。

從 1.17 升級¶

若你曾使用舊版本地 meta.json 映射，需按 README「遷移（1.17.0 → 1.18.0）」備份 profile 與 meta，登記 mira_account 賬號，把 autoReply.* 鍵遷到 reply.*，並用 tool_shared/migrate/bindings.mjs 把舊綁定寫入 mira_account。升級後羣觸發、白名單與默認投遞方式（steer 相對舊版 followup）有文檔化的語義變化，升級前應對照 README 中的對照表。

適用場景與注意¶

適合誰：已在 DSH 中開發 agent，希望用真實 QQ 號（非獨立 Bot 賬號）收發消息、查好友/羣/成員、處理好友/加羣申請，並需要與 mira_account 統一的綁定與多會話模型。

運行權限：插件隨 當前 DSH 進程 運行，能訪問進程可見的文件與環境；安裝前請閱讀源碼與 MIT 許可證，自行評估 NapCat、OneBot 與 QQ 使用條款帶來的風險。

配置與安全：accessToken 與賬號憑證文件應限制權限；勿在不可信環境暴露 OneBot WebSocket 端口。reply.privateWhitelist 與 reply.trustedUsers 語義不同：前者管私聊是否應答，後者主要影響提示詞中的【識別名單】。

生態說明：DSH 主張「一切皆插件」；SkillHub 目錄是社區站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

mira_qqbot 把 NapCat + OneBot v11 收成 DSH 內的 qq_* 工具，並與 mira_account 分工處理綁定與路由；配好 wsUrl 與賬號池後，可用 qq_status 驗連接，用發送/接收工具或 reply.* 自動應答完成日常 QQ 自動化。

目錄頁：https://www.skillhub.cn/plugins/Stella-Mira/mira_qqbot
GitHub：https://github.com/Stella-Mira/mira_qqbot

mira_qqbot：通過 OneBot v11 把 QQ 接到 DeepSeek Harness

前言¶

這是什麼¶

核心功能¶

協議與賬號分工¶

qq_* 工具集（21 個）¶

自動應答與羣策略¶

安裝與啓用¶

1. 部署 NapCat 與 OneBot WebSocket¶

2. 編寫 config.json¶

3. 重啓 DSH 並自檢¶

典型用法¶

用 qq_status 確認鏈路¶

模型主動發消息¶

拉取緩衝中的入站¶

從 1.17 升級¶

適用場景與注意¶

結尾¶

精选优惠券

mira_qqbot：通過 OneBot v11 把 QQ 接到 DeepSeek Harness

前言¶

這是什麼¶

核心功能¶

協議與賬號分工¶

qq_* 工具集（21 個）¶

自動應答與羣策略¶

安裝與啓用¶

1. 部署 NapCat 與 OneBot WebSocket¶

2. 編寫 config.json¶

3. 重啓 DSH 並自檢¶

典型用法¶

用 qq_status 確認鏈路¶

模型主動發消息¶

拉取緩衝中的入站¶

從 1.17 升級¶

適用場景與注意¶

結尾¶

精选优惠券

相關文章