前言¶

DeepSeek Harness（dsh）把智能體能力封裝成可插拔的 Cordis 插件，但多數示例仍圍繞終端或 Web 界面。如果你希望同事、用戶直接在 QQ 裏與 Agent 對話，需要自己處理 QQ Bot API、WebSocket 長連接、消息入站出站，以及每個私聊/羣聊的會話隔離。

下面介紹 @tencent-connect/dsh-qqbot：由 tencent-connect 維護的 dsh 客戶端插件，把 QQ 私聊與羣聊接入 dsh 的 agent loop，憑據可通過掃碼綁定，也支持環境變量或配置文件傳入。

這是什麼¶

@tencent-connect/dsh-qqbot 是面向 deepseek-harness 的 QQ Bot IM 通道插件。消息路徑如下：

QQ 用戶 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
                                 ↑                           │
                                 └── session/event ──────────┘
                                       (assistant reply → QQ sendMarkdown)

插件遵循 dsh「Plugins, not loop changes」原則：純 Cordis 插件，通過 inject = ['agents'] 聲明依賴，不直接改動 agent loop。當前版本 0.4.0，許可證 MIT，要求 Node.js >= 18。GitHub 倉庫約 74 stars。

核心功能¶

消息與會話¶

• 私聊與羣聊均可觸發 Agent；羣聊默認需 @bot（requireMention，默認 true）。
• 每個 QQ 私聊用戶或羣聊對應獨立 Agent，會話 key 爲 qqbot:${appId}:${scope}:${peerId}，經 SHA-256 派生 SessionId，進程重啓後可恢復。
• 閒置超時（默認 30 分鐘）自動 dispose Agent，避免內存泄漏。
• 回覆以 Markdown 格式發送，支持代碼塊/表格感知的文本切分（單條上限默認 4500 字符）。

模型與預設¶

• 默認 LLM 提供商 deepseek-official，模型 deepseek-chat；可通過配置或 /model 命令切換。
• 支持掛載 agent-presets 預設（工具集、prompt 等），/preset 查看或切換，新會話生效。
• 私聊、羣聊可分別設置額外 system prompt（directPrompt、groupPrompt）。

內置斜槓命令¶

問答互動¶

支持 dsh 的 ask_user_question：單選生成內聯按鈕（點一個其餘變灰），多選回覆編號，逐題推進；單題超時默認 5 分鐘（askTimeoutMs）。

安裝與啓用¶

方式一：npm 安裝（推薦）¶

先把插件裝進獨立 profile，再啓動 dsh：

# 安裝到 profile
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot

# 啓動
npx @deepseek-ai/dsh --profile qqbot

首次啓動時，若憑據未配置，插件會進入掃碼引導：終端輸出二維碼，用手機 QQ 掃碼綁定，憑據自動保存到 profile，後續啓動無需再次掃碼。建議插件版本在 0.4.0 以上，支持點擊鏈接在瀏覽器打開二維碼，避免部分終端渲染錯位。

方式二：本地路徑安裝¶

適合需要改源碼的場景：

cd /path/to/dsh-qqbot
pnpm install && pnpm build

npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-qqbot

export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh --profile qqbot

方式三：–patch 開發模式¶

export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

配置項¶

AppID 與 AppSecret 需在 QQ 開放平臺 創建 Bot 後獲取，插件對接 QQ Bot API v2。

典型用法¶

1. 按方式一安裝並啓動，完成掃碼綁定。
2. 在 QQ 私聊或羣裏 @bot 發送問題，Agent 以 Markdown 回覆。
3. 長對話用 /compact 壓縮歷史；切換模型用 /model；重置上下文用 /new。
4. 本地開發時，pnpm dev 監聽構建，配合 --patch 調試：

pnpm install
pnpm build
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

適用場景與注意¶

適合誰

• 已在 dsh 上跑 Agent，希望把同一套能力暴露到 QQ 的團隊或個人。
• 需要羣聊 @觸發、私聊直連、per-peer 模型偏好等 IM 場景特化的部署。

使用前注意

• 插件以當前 dsh 進程的權限運行，Agent 能訪問的工作目錄、工具、網絡範圍與 dsh 實例一致。安裝前請閱讀 源碼 與 MIT 許可證，確認符合你的安全策略。
• 羣聊默認需 @bot，避免羣內每條消息都觸發 LLM 調用。
• 社區目錄 SkillHub 是獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件信息以 GitHub 倉庫爲準。

結尾¶

@tencent-connect/dsh-qqbot 把 QQ WebSocket 消息流接到 dsh 的 agent loop，掃碼或環境變量完成憑據配置，私聊與羣聊各自維護獨立會話。若你正在 dsh 生態裏找 QQ 接入方案，可以從 npm 安裝命令起步，按需調整模型、preset 與羣聊 prompt。

• 目錄頁：https://www.skillhub.cn/plugins/tencent-connect/dsh-qqbot
• GitHub：https://github.com/tencent-connect/dsh-qqbot