前言¶
在 DeepSeek Harness（DSH）裏做 QQ 側的智能體，常見有兩條路：走騰訊官方開放平臺（AppID、審覈、回調），或用 OneBot 協議端接普通 QQ 號。後者上手快，但要自己接協議、管會話和權限，還要把模型、工具和人設接到 DSH 上。qfish 是面向第二種路線的 DSH 客戶端插件：通過 NapCat / OneBot v11 連 QQ，聊天、記憶、工具和控制台都在一個 npm 包裏，模型與會話直接走 DSH，中間不夾額外中間層。下面介紹它是什麼、能做什麼，以及如何安裝與配置。
這是什麼¶
qfish（包名 qfish，倉庫 hyun20202023-ui/dsh-qfish）由維護者 hyun20202023-ui 發佈，在 SkillHub 目錄中歸類爲客戶端插件。當前 npm 版本爲 0.3.8，許可證 MIT，要求 DSH 引擎 ^0.2.1-rc.2。
一句話定位：用普通 QQ 號（經 NapCat）當機器人，在羣聊與私聊裏以人設、記憶和工具與 DSH 智能體聯動，並自帶網頁控制台。
核心功能¶
資料中明確的能力可歸納爲以下幾塊。
聊天與人設¶
- 人設寫在 markdown 裏；短句爲主，帶情緒與好感度，羣聊收斂、私聊更放開。
- 按人存儲記憶，滿額會壓成摘要；羣聊與私聊共用同一份記憶。會話過長會輪換上下文，舊內容壓成摘要，私聊輪換時還會寫入一條記憶。
- 會學習羣裏人的口頭禪與句式；黑話分「罵人」與「普通」兩張表，用於聽懂與回嘴。
- 切句按語氣斷句發多條，不按字數均分。
多模態與 B 站¶
- 發圖可看圖說話。
- 發 B 站鏈接會處理字幕、畫面、彈幕、熱評後再回復；過長會直接說明，不假裝看完。處理在臨時會話中完成，主線只留摘要。
工具與運維¶
搜圖、聯網、音樂卡片、提醒、羣管理、跨羣發消息；在具備後臺權限時可執行服務器命令（見 README 工具說明）。
控制台與客戶端集成¶
內置網頁控制台：會話、記憶、社交、觀看記錄、配置、日誌集中管理。DSH 頁面右下角有入口（默認指向本機 127.0.0.1:8090）。花費相關參數（上下文輪換、看圖批量、視頻時長與頻率等）可在控制台調整。
接入方式說明¶
插件走 OneBot / NapCat，不依賴 QQ 官方機器人開放平臺。協議端存在被風控的可能，適合自用、羣裏擬人陪伴；若要面向公衆的正式產品，需自行對比官方 Bot 的穩定性與合規要求。
安裝與啓用¶
安裝插件¶
推薦從 npm 安裝（README 原文命令）：
dsh plugin add qfish
裝完後重啓 DSH。
也可在 profile 中通過 Git 依賴安裝：
pnpm add git+https://github.com/hyun20202023-ui/dsh-qfish.git
並在 profile 的 package.json 裏把 qfish 放進 dsh.profile.bundles，再安裝依賴。
準備 NapCat¶
需要：已能正常對話的 DSH（含默認模型）、一個 QQ 小號、OneBot v11 協議端 NapCat（含 WebSocket）。
本地：安裝 NapCat 並登錄 QQ；網絡配置中新建 WebSocket 服務器，端口 3001，消息格式 array。
服務器（Docker 示例，來自 README）：
docker run -d --name napcat --restart unless-stopped \
-p 3001:3001 -p 6099:6099 \
-v /opt/napcat:/app/napcat \
mlikiowa/napcat-docker:latest
3001：插件連接的 WebSocket；6099：NapCat 網頁掃碼；3001建議僅本機訪問，勿暴露公網。
插件配置要點¶
在 DSH → 插件設置 → qfish（配置的 id 與 name 均應爲 qfish）中填寫，例如：
| 配置項 | 說明 |
|---|---|
url |
ws://127.0.0.1:3001 |
accessTokenRef |
NapCat 設了 token 時才填 |
consoleEnabled |
true |
consoleListen |
本地 127.0.0.1；服務器改爲 0.0.0.0 |
consolePort |
默認 8090（佔用會順延） |
consoleToken |
可留空自動生成；服務器建議自設長串 |
respondToPrivate |
本地默認 false；服務器常用 true |
userAccessMode / userIds |
默認 allowlist，空名單即全拒 |
groupAccessMode / groupIds |
同上 |
默認 全拒：allowlist 且名單爲空時不會回覆任何消息。白名單示例：
userAccessMode: allowlist
userIds: ["你的QQ號"]
groupAccessMode: allowlist
groupIds: ["你的羣號"]
全部放開示例：
userAccessMode: blocklist
userIds: []
groupAccessMode: blocklist
groupIds: []
按需配合 respondToPrivate: true、groupMentionOnly: false。服務器部署需放行 8090（控制台）與 6099（NapCat 網頁）。
登錄與打開控制台¶
掃碼可在 NapCat 網頁或控制台「行爲參數」中的二維碼完成。控制台地址須帶 token：
http://地址:8090/?t=令牌
token 來自配置 consoleToken、文件 <profile>/onebot-data/console-token.txt，或 DSH 啓動日誌中「控制台已啓動」那一行的完整 URL。服務器上請將 consoleListen 設爲 0.0.0.0 並放行端口；遠程訪問勿僅靠 DSH 右下角按鈕（其內置地址爲 127.0.0.1）。
更細的機制、行爲參數與排障見倉庫 docs/USER-GUIDE.md。
典型用法流程¶
按 README 快速開始，順序可概括爲：
- 執行
dsh plugin add qfish並重啓 DSH。 - 啓動 NapCat，確認 WebSocket 3001、格式 array。
- 在插件設置中填
url、訪問控制白名單及控制台相關項。 - 掃碼登錄 QQ。
- 用帶
?t=的地址打開控制台，調整人設、行爲與花費相關參數。 - 在已加入且已列入
groupIds的羣中 @ 機器人，或在允許私聊時發私聊驗證收發。
維護者在 README 中還提供了一段可交給 DSH 自動執行的安裝指令（判斷環境、裝依賴、起 NapCat、寫 cordis.patch.yml、驗證日誌），適合讓本機 DSH 按步排查；使用時需確認 profile 內已有默認模型（如 agent-default-model），否則新會話可能無法拿到模型。
適用場景與注意¶
適合：已在用 DSH、願意用 NapCat 養 QQ 小號、希望在羣/私聊裏做擬人陪伴、看圖看視頻、聯網與羣工具，並希望通過網頁管記憶與配置的用戶。
注意：
- 插件以當前 DSH 進程權限運行；安裝前宜查看 源碼 與 MIT 許可證，自行評估協議端風險與服務器命令等高危能力。
- 社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；「一切皆插件」是 DSH 生態理念，不等同於官方應用商店。
- 交流羣（README）：QQ 羣 480910887。
結尾¶
qfish 把 OneBot 接入、擬人對話、記憶與多模態、工具鏈和網頁控制台收進一個 DSH 插件，適合用普通 QQ 號在 DSH 上快速試跑 QQ 機器人。目錄與文檔：SkillHub 插件頁、GitHub 倉庫。
