前言¶
在 DeepSeek Harness（DSH）裏做智能體，常見做法是瀏覽器或桌面會話裏對話。若你希望同一套 Harness 在手機上用 QQ 私聊也能收發——文字、圖片、表情、語音，並且回覆只回到發起那一側（QQ 來的回 QQ，桌面來的留在桌面），就需要一條從 QQ 生態到 DSH 的橋，而不是再搭一套 IM 機器人框架或消息隊列。
dsh-qq 由維護者 wyinthe 發佈，在 SkillHub 社區目錄中歸類爲客戶端插件。它只做橋接：通過 NapCat 的 OneBot11 WebSocket 把私聊進出接到指定 DSH 會話。本文介紹其定位、能力與安裝用法；事實以倉庫 README 與 package.json 爲準。
這是什麼¶
一句話：它是橋，不是機器人。
數據路徑可以理解爲：
QQ 客戶端 ──> NapCat(WSL) ──OneBot11 WS──> dsh-qq ──> DSH 會話
│
回話按來源分流 ◀───┘
（QQ 發起的纔回 QQ；桌面發起的留在桌面）
倉庫爲純 ESM、零依賴的單文件實現（index.js），當前版本 0.2.1，許可證 MIT，要求 Node.js >= 20，對 DSH 的 peer 依賴爲 @deepseek-ai/dsh >= 0.2.0。維護者自述在單機單人自用場景下已驗證文字、圖片、表情、語音（收）通路；發語音條尚未實現。
DSH 生態理念是「一切皆插件」；SkillHub 目錄頁 與 GitHub 倉庫爲社區資源，與 DeepSeek / 幻方無官方從屬關係，不宜當作官方應用商店條目理解。
核心功能¶
下面按「有什麼 / 沒有什麼」說明，避免預期錯位。
私聊與接入
- 支持 OneBot11 / NapCat 下的私聊雙向文字。
- 一個號只接白名單內用戶的私聊：
owners不填則誰都不接。 - 會話綁定：可接到指定會話，或首次使用時自建。
- 回話跟着來源走：僅 QQ 發起的那一輪纔回 QQ，避免桌面說一句、手機跟着震。
媒體與標記
| 方向 | 能力 |
|---|---|
| 收圖 | 落盤後把路徑交給 AI，由模型側 read_image 打開；插件不做識別 |
| 收表情 / 商城表情包 | 記成文本標記 |
| 發圖 / 發表情 / 發表情包 | 通過輸出標記（見下文「典型用法」） |
| 收語音 | 需自備轉寫腳本（earScript），DSH 側看到轉寫與語氣維度文本 |
| 發語音條 | 未做；文檔指向 ffmpeg + silk-wasm 外掛方案 |
明確不做（README 表格）
- 羣聊投遞：
groupMessages默認關閉，僅記日誌。 - 自帶 ASR、表情圖庫、記憶與上下文壓縮管理。
設計上的第三條原則：能力靠標記不靠魔法——要發圖就寫 [[img:路徑]]，不猜測用戶意圖。
安裝與啓用¶
安裝前請自行閱讀 GitHub 源碼 與許可證；插件在當前 dsh 進程權限下運行，白名單與 NapCat token 等配置涉及賬號安全，不宜在未審代碼的情況下直接用於生產賬號。
1、準備 NapCat
在 NapCat 中開啓 WebSocket 服務端（細節見倉庫 docs/配置.md），記下端口與 token。
2、安裝插件
官方 README 給出的命令爲（使用 Git 倉庫直裝，--profile web）：
dsh plugin --profile web add https://github.com/wyinthe/dsh-qq
3、配置四類信息
地址、token、白名單（owners）、工作目錄等，可參考帶註釋樣例 examples/cordis.patch.yml，並配合 cordis.patch.yml 掛載聲明使用。
4、重啓 DSH 並驗證
重啓後，在 QQ 上向該號發一句私聊；預期爲 QQ 側收到回覆，且桌面會話不會重複收到同一條迴流。
典型用法¶
QQ 進來的內容在 DSH 里長什麼樣¶
| 你發 | DSH 看到 |
|---|---|
| 文字 | 原文 |
| 語音 | [語音] 轉寫文本 + [語氣] 等（需配 earScript） |
| 圖片 | [用戶發了圖片，已存到本機，可以直接用 read_image 打開：<路徑>] |
| 表情 | [QQ表情 id=178] |
| 表情包 | [表情包「名字」emoji_id=… package_id=…] |
AI 輸出如何發到 QQ¶
| 寫入內容 | 發出結果 |
|---|---|
[[img:D:/pics/a.png]] |
圖片（自動轉 base64://，適配 NapCat 在 WSL 下無法直接讀 Windows 盤符的情況） |
[[face:178]] |
QQ 表情 |
[[mface:emoji_id/package_id/名字]] |
商城表情包 |
| 純文字 | 文字（超過 maxChars 自動切段） |
收發標記、行爲細節與已知限制見倉庫 docs/用法.md；連接、白名單、語音轉寫約定見 docs/配置.md；按症狀排查見 docs/排錯.md。
適用場景與注意¶
適合誰
- 已在用 DSH，且願意自建 NapCat（常見 WSL 部署）與 OneBot11 WS 的開發者。
- 需要單人私聊、來源分流，並願意用顯式標記控制發圖發情的場景。
- 接受語音轉寫、發語音條需自行擴展（腳本或 ffmpeg 方案），而非插件內置。
使用注意
- 默認不接羣聊；多人羣、多賬號需在上層擴展，README 寫明當前優先私聊是因爲可獨立跑通。
- 圖片理解依賴模型與
read_image，不是插件內置能力。 - 社區目錄顯示該倉庫 GitHub 1 stars（截至目錄收錄信息）；版本與能力以 CHANGELOG 與 README「狀態」一節爲準。
結尾¶
dsh-qq 把 QQ 私聊通過 NapCat / OneBot11 接到 DeepSeek Harness：白名單、會話綁定、按來源迴流，並用 [[img:]] / [[face:]] 等標記約束出站能力。若你要在 DSH 上接 QQ 而非另起一套機器人框架，可從 README 的 60 秒步驟與 examples/cordis.patch.yml 動手驗證。
