dsh-whale-inurqq：接入 DeepSeek Harness 的 QQ 客戶端

DeepSeek Harness 是一個基於插件架構的框架，它的理念是「一切皆插件」。要把 QQ 接入這個框架，需要實現協議層面的通信。dsh-whale-inurqq 是一個 OneBot 11 協議客戶端插件。它本身不處理 QQ 登錄、簽名或加密，這些工作由協議端（如 NapCat）負責。因此，它保持了中立，可以像任何 IM 通道插件一樣分發。

下面介紹如何安裝、配置以及理解它的運行機制。

核心功能¶

本插件主要解決 QQ 與 DSH 之間的消息路由與會話管理問題：

1. 消息歸一化與分類：接收 QQ 消息後，進行歸一化處理，並根據內容判斷爲「閒聊」或「任務」。這一步只決定措辭，不決定後續路由。
2. 常駐對接會話：每個 QQ 會話（羣或私聊）對應 DSH 中的一個工作區。該工作區下有一個常駐對接會話，聊天和執行任務都在這個會話中進行，而不是每條消息新建會話。
3. 上下文交班機制：當常駐會話的上下文達到閾值（默認 handoffAtRatio: 0.25）時，會觸發交班。舊會話歸檔，新會話接管，碎片記憶保留。
4. 回合發起者判定：插件通過 source.rpcId 判定當前回合是「插件發起的」還是「用戶在 GUI 裏發起的」。只有前者纔會回傳消息到 QQ，後者則完全靜默。
5. 非主動推送：插件不會主動推送「正在執行中」的狀態。用戶需要主動查詢時，插件纔會通過 qq_alive 和 qq_tasks 查詢狀態並回答。

前置條件¶

在開始之前，需要準備以下環境：

安裝與遷移¶

使用官方命令安裝插件：

dsh plugin --profile <你的profile> add dsh-whale-inurqq

安裝後重啓 DSH 進程。

老用戶必讀：從 dsh-qq 改名而來¶

本插件原名 dsh-qq，現已改名爲 dsh-whale-inurqq。這個改名是無情的字符串替換，運行時數據目錄也隨之改變：

如果你之前安裝過 dsh-qq，建議執行以下遷移步驟以保留數據：

1. 卸載舊插件（它仍以舊包名註冊）：

    dsh plugin --profile <你的profile> remove dsh-qq

2. 安裝新插件：

    dsh plugin --profile <你的profile> add dsh-whale-inurqq

3. 搬運運行時數據（假設 DSH 默認在 ~/.dsh）：

    # Linux / macOS
    mv ~/.dsh/dsh-qq ~/.dsh/dsh-whale-inurqq
    # Windows PowerShell
    Rename-Item "$env:USERPROFILE\.dsh\dsh-qq" "$env:USERPROFILE\.dsh\dsh-whale-inurqq"

*注意：如果不搬運目錄，新插件會視爲全新安裝，無法讀取舊的會話與語料庫。*

配置協議端（NapCat）¶

插件默認監聽 127.0.0.1:6700。需要在 NapCat 的 config/onebot11.json 中配置一個反向 WebSocket 客戶端：

{
  "network": {
    "websocketClients": [
      {
        "name": "dsh-whale-inurqq-reverse",
        "enable": true,
        "url": "ws://127.0.0.1:6700",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "reconnectInterval": 5000,
        "token": "<你的 access token>",
        "heartInterval": 30000
      }
    ]
  }
}

關鍵配置點：
* url：指向插件監聽的地址。
* messagePostFormat：必須設爲 array。
* token：需與插件配置中的 QQ_ONEBOT_TOKEN 或 connection.token 一致。

配置項說明¶

插件安裝後，會在 DSH 的設置頁生成配置項。以下是關鍵配置的邏輯與風險點。

常駐對接會話（默認開啓）¶

conversation.enabled 默認爲 true。開啓後，QQ 會話與 DSH 工作區共用一個常駐會話。

• 回滾開關：如果將 conversation.enabled 設爲 false，插件將回滾到 v2 行爲：每條任務新建會話，受 tasks.maxConcurrent 限流，不掛載常駐記憶。
• 交班閾值：handoffAtRatio（默認 0.25）控制上下文窗口使用多少比例時觸發交班。此值必須低於宿主壓縮的 thresholdRatio，否則壓縮會先摘要掉歷史。

權限與風險（Scope）¶

QQ 觸發的新會話會繼承 DSH profile 的默認權限預設。

• 風險提示：如果默認預設是 danger-full-access 且 approval: never，任何能給你的 bot 發消息的人（在 scope 允許範圍內）都會獲得不受限的文件與 shell 執行能力。
• 公開部署：建議收緊 scope，或使用更嚴格的默認預設。

任務配置¶

• tasks.workspaceRoot：必填項，指定 QQ 項目目錄的父目錄。
• ingest.forwardRecords：開啓後，合併轉發會自動展開入語料。

工作原理與行爲細節¶

回傳機制的判定邏輯¶

插件通過 source.rpcId 判定回合發起者：
1. 如果 source.rpcId 屬於插件發出的 prompt id 集合，說明是插件發起的，照常回傳 QQ。
2. 如果不命中（例如用戶在 DSH GUI 裏自己敲的那句），說明是 GUI 發起的，該回合不回傳任何內容。

這一機制防止了用戶在電腦前操作 GUI 時，QQ 那邊莫名收到回傳消息。

進度展示¶

插件不主動推送進度。中間態一律靜默。只有當用戶在 QQ 上發起查詢時，插件纔會查詢真實狀態並如實回答。

交班換新會話¶

當上下文達到閾值時，插件會：
1. 整理成交接束 + 碎片記憶落盤。
2. 歸檔舊會話。
3. 建立新會話並注入交接文本。
4. 交班期間新來的消息會進入排隊（frozenQueue），交班結束後按原順序補投。

狀態查詢¶

插件在反向 WebSocket 端口暴露了一個只讀狀態端點，可用於調試：

curl http://127.0.0.1:6700/dsh-whale-inurqq/status

該接口返回連接狀態、事件統計、工作區映射、回傳來源判定賬目以及任務調度信息。

總結¶

dsh-whale-inurqq 是一個連接 QQ 與 DeepSeek Harness 的 OneBot 11 客戶端。它通過常駐會話和上下文交班機制，簡化了任務管理的流程，同時通過嚴格的回合發起者判定和權限控制，保證了交互的安全性。

• 作者：FABAGV
• 許可：MIT
• 倉庫：https://github.com/FABAGV/dsh-whale-inurqq
• 目錄頁：https://www.skillhub.cn/plugins/FABAGV/dsh-whale-inurqq