前言¶
DeepSeek Harness（命令是 dsh）把自己的架構概括成一句話：一切皆插件。模型、工具、會話、沙箱，甚至 Agent 循環本身，都可以替換。官方倉庫目前仍處於 developer preview，兼容性破壞變更是預期內的事。開箱後常見入口是 Web UI 和 headless 一次性任務；如果你希望同一套 Agent 出現在 QQ 裏——私聊能接着聊、羣裏被 @ 纔開口——就需要一條 IM 通道，而不是改 Agent 循環。
dsh-qqbot 做的就是這件事。倉庫由 tencent-connect 維護，定位是把 QQ 消息平臺當成 dsh Agent 的前端協議驅動：QQ 進來的消息進入 ctx.agents，模型回覆再以 Markdown 發回 QQ。社區插件目錄把它歸在「工具與能力」，收錄日期是 2026-08-15。需要說明：這個目錄是獨立站點，和 DeepSeek / 幻方沒有官方從屬關係，不能當成官方應用商店。倉庫自己寫的「官方插件」，指的是騰訊 QQ Bot 側接入 dsh 的插件，不是目錄站點的官方背書。
本文按插件目錄頁、GitHub 倉庫 README、package.json 以及 DeepSeek Harness 官方倉庫覈對後整理：它是什麼、裝到哪個 profile、掃碼之後怎麼聊。
這是什麼¶
dsh-qqbot 的 npm 包名是 @tencent-connect/dsh-qqbot，當前 package.json 版本爲 0.4.0，主要語言是 TypeScript，許可證 MIT（Copyright 2026 Tencent Connect）。GitHub 倉庫 tencent-connect/dsh-qqbot 創建於 2026-08-14；寫作時（2026-08-17）GitHub API 顯示 53 星，社區目錄頁當時展示爲 26 星，星標以 GitHub 一手數據爲準。
它解決的問題很具體：讓已經初始化好的 dsh 環境，通過 QQ Bot 收發消息。README 裏的數據流可以看成：
QQ 用戶 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
↑ │
└── session/event ──────────┘
(assistant reply → QQ sendMarkdown)
也就是說，QQ 不是另寫一套機器人邏輯，而是給現有 dsh Agent 加一條 IM 前端。插件聲明自己是純 Cordis 插件，遵循 dsh 的 “Plugins, not loop changes”：依賴寫成 inject = ['agents']，不直接耦合其他插件。
核心功能¶
私聊、羣聊各走獨立會話¶
每個 QQ 私聊用戶、每個羣各對應一個獨立 Agent。會話鍵是 qqbot:${appId}:${scope}:${peerId}，SessionId 由 SHA-256 確定性派生，進程重啓後可以按同一套規則恢復。解析順序是：進程內複用 → 持久化恢復 → 全新創建。閒置超時默認 30 分鐘（sessionIdleTimeout，1800000 ms），超時後自動 dispose Agent，避免會話一直佔着內存。
羣聊默認要 @ 纔回復¶
requireMention 默認是 true：羣裏沒有 @ 機器人，插件不會把普通閒聊送進 Agent。私聊和羣聊還可以分別加 directPrompt、groupPrompt，用來補一段額外的 system prompt。源碼裏的配置 Schema 還提供了訪問控制：私聊 / 羣聊可設爲 open、allowlist 或 disabled，並支持 openid 白名單。README 配置表沒有列出這一項，需要精細權限時以倉庫源碼爲準。
回覆走 Markdown，並按 QQ 長度切開¶
出站不是純文本直出，而是 sendMarkdown。單條消息默認最多 4500 字符（textChunkLimit），源碼註釋寫明 QQ 限制大約 5000 字符。切分會感知代碼塊和表格，避免把 Markdown 結構從中間截斷。
聊天裏可以管會話和模型¶
README 列出的斜槓命令如下：
| 命令 | 說明 |
|---|---|
/bot-reset |
重置當前會話（清除上下文） |
/bot-model |
查看或切換模型 |
/bot-status |
查看當前會話狀態 |
/bot-help |
查看所有指令 |
源碼裏還可以看到 /bot-new（新開會話）、/bot-clear（與 reset 同類）、/bot-ping、/bot-version 等註冊項；對外說明以 README 這四條爲準。默認 LLM 提供商是 deepseek-official，默認模型是 deepseek-chat，也可以改 provider、model，或通過 preset 掛上 agent-presets 裏的預設（工具集、prompt 等）。
安裝與啓用¶
開始前，先按 DeepSeek Harness 官方指引完成 dsh 初始化和模型配置。官方倉庫當前的開發者預覽啓動方式是：
npx @deepseek-ai/dsh web
社區目錄頁給出的安裝命令是：
dsh plugin add github:tencent-connect/dsh-qqbot
如需可復現安裝，目錄頁建議固定 commit 哈希：
dsh plugin add github:tencent-connect/dsh-qqbot#<commit>
把 <commit> 換成倉庫裏實際的提交哈希。插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；裝之前應檢查源代碼倉庫和許可證。
倉庫 README 推薦的日常用法是單獨建一個 qqbot profile，並安裝 npm 包（當前版本 0.4.0）。README 提示：建議升級到 0.4.0 以上再掃碼，支持點擊鏈接在瀏覽器打開，避免部分終端二維碼渲染錯位。
# 安裝到 profile
npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot
# 啓動
npx @deepseek-ai/dsh --profile qqbot
首次啓動時，如果憑據還沒配，插件會進入掃碼引導：終端輸出二維碼 → 手機 QQ 掃碼綁定 → 憑據寫入該 profile。之後再啓動不必重複掃碼。
本地改源碼、或不走掃碼、直接用環境變量時，README 給的是路徑安裝：
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 是必填項，也可以只走環境變量 QQBOT_APPID、QQBOT_SECRET。不要把密鑰寫進公開倉庫。
從 GitHub 源碼安裝時，dsh 官方文檔還提醒過：git 依賴拉取的是源碼而不是構建產物，pnpm ≥10 可能要求在 profile 的 pnpm-workspace.yaml 裏爲該包打開 allowBuilds 後再執行一次 add。若第一次 add 失敗，按終端提示處理，不要跳過授權檢查。
典型用法¶
綁定完成後，直接在 QQ 裏給機器人發消息即可。下面幾步都可以按倉庫說明覆現。
1. 私聊裏跑通一輪對話¶
啓動 qqbot profile 並完成掃碼後，向機器人發一句普通問題。消息會經 WebSocket 進入插件，再調用 agent.followup()。回覆以 Markdown 發回；超過 textChunkLimit 會被切開。默認模型是 deepseek-chat。
2. 羣裏只在被 @ 時說話¶
把機器人拉進羣后，默認不會對每條羣消息作答。需要 @ 機器人，或把 requireMention 改成 false（羣很吵時不建議關）。羣聊還可以單獨寫 groupPrompt，例如限制語氣、禁止代發敏感操作。
3. 用斜槓命令管理當前會話¶
在對應私聊或羣裏發送：
/bot-help
/bot-status
/bot-model
/bot-reset
/bot-help 列出指令；/bot-status 看當前會話；/bot-model 查看或切換模型；聊偏了用 /bot-reset 清上下文。這些命令作用在當前 peer 的會話上，不會把其他用戶或羣的記憶清掉。
4. 按 README 改常用配置¶
README 配置表裏和日常使用最相關的幾項：
| 配置 | 默認值 | 說明 |
|---|---|---|
appId |
必填 | QQ Bot AppID，或環境變量 QQBOT_APPID |
appSecret |
必填 | QQ Bot AppSecret，或環境變量 QQBOT_SECRET |
provider |
deepseek-official |
LLM 提供商名稱 |
model |
deepseek-chat |
模型名稱 |
preset |
- | Agent preset id |
cwd |
process.cwd() |
Agent 工作目錄 |
requireMention |
true |
羣聊是否需要 @bot 才觸發 |
textChunkLimit |
4500 |
單條消息最大字符數 |
sessionIdleTimeout |
1800000 |
會話閒置超時（毫秒） |
debug |
false |
調試模式 |
cwd 決定 Agent 在磁盤上的工作目錄。dsh 的工具默認跟當前進程權限走，把機器人接到 QQ 之後，等於把這套權限暴露給能發消息的人，白名單和 requireMention 值得先想清楚。
適用場景與注意事項¶
適合已經在用 dsh、希望把同一套 Agent 接到 QQ 的人：個人助手放在私聊、小團隊在羣裏 @ 機器人查代碼或跑任務、自己寫 preset 後再從 QQ 觸發。不適合把它理解成「裝完就能代替官方 QQ 客服後臺」——它是 IM 通道插件，模型、工具、沙箱仍然來自你當前的 dsh profile。
使用前注意這幾件事：
- 權限與源碼。 插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。裝之前閱讀
tencent-connect/dsh-qqbot源碼和 MIT 許可證；生產環境用目錄頁那種github:owner/repo#commit固定提交。 - 憑據。 AppID / AppSecret 或掃碼寫入的憑據等同於機器人身份，不要提交到 git，也不要在多人共享的機器上用未加訪問控制的開放模式。
- 預覽版兼容性。 DeepSeek Harness 官方 README 寫明當前是 developer preview，會有破壞性變更。插件的 peer 依賴指向
@deepseek-ai/cordis >=4.0.1以及@deepseek-ai/dsh-agent/dsh-llm/dsh-session的>=0.1.0-rc.6。dsh 升級後若加載失敗，先對一下這幾項版本。 - 羣聊打擾。 默認
@門控是爲了少插話。關掉requireMention前，先確認羣規模和訪問控制。 - 目錄與倉庫不是同一件事。 安裝命令以目錄頁原文爲準；具體掃碼流程、配置項和命令以 GitHub README 爲準。兩者衝突時，配置與用法以倉庫一手文檔更接近實現。
小結¶
dsh-qqbot 把 QQ 變成 dsh Agent 的一條前端：私聊和羣聊隔離會話，重啓可按同一 sessionKey 恢復，羣默認要 @ 才響應，回覆按 Markdown 切分發送。目錄頁安裝命令是 dsh plugin add github:tencent-connect/dsh-qqbot；實際跑起來，倉庫更完整的路徑是裝進 qqbot profile，啓動後掃碼綁定。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-qqbot/
GitHub：https://github.com/tencent-connect/dsh-qqbot
