前言¶
在 DeepSeek Harness（DSH）裏做智能體，常見做法是接 Web、終端或自建 HTTP 通道。個人 QQ 仍依賴 OneBot 生態裏的 NapCat 等客戶端：要自己下載運行包、填 API token、事件上報地址，還要單獨維護登錄與進程。下面介紹的 dsh-qq-access 把 NapCat 託管、消息自動回覆、本地歸檔和 QQ 空間讀寫收進一個 DSH 插件，並在 Harness 左側欄提供「QQ 接入」管理面板。
這是什麼¶
dsh-qq-access 由社區維護者 Applepinea 發佈，在 SkillHub 插件目錄 中歸類爲客戶端插件（GitHub 約 2 stars）。它面向「用 Harness 驅動個人 QQ」的場景：在 Windows x64 上可固定官方 NapCat Node 運行包（v4.18.41）、自動生成連接配置、隨插件啓停進程；Linux、macOS、Windows ARM 當前走外部 NapCat 模式（見倉庫 docs/EXTERNAL_MODE.md）。
插件以 MIT 許可發佈自寫代碼；NapCat 與官方運行包遵循上游許可，使用前請閱讀倉庫 來源說明。插件在 DSH 進程權限下運行，安裝前應自行覈對源碼與許可證。
核心功能¶
資料中明確的能力如下。
| 能力 | 說明 |
|---|---|
| NapCat 託管（Windows x64） | 校驗並解壓固定版本運行包，生成 API token、事件簽名與本機連接；掃碼頁就緒後可自動打開瀏覽器 |
| QQ 聊天 | 接收可上報的入站消息；默認私聊自動回覆，羣聊在被 @ 時回覆；圖片可轉爲模型可見內容（PNG/JPEG/GIF/WEBP，單條最多 4 張，可通過 reply.vision 關閉） |
| 歷史與歸檔 | 本地歸檔、搜索，或調用 QQ 歷史接口分頁查詢；retentionDays 默認 30 天 |
| QQ 空間 | 獨立 Edge 瀏覽器登錄，讀取可見文字，在留言板發表純文本留言（不含說說評論、發說說、相冊導出等） |
| 管理面板 | 左側欄「QQ 接入」：自動回覆開關、批量窗口與輪詢、回覆範圍白名單、NapCat 託管、人格編輯、在線狀態 |
訪問範圍受登錄賬號權限與 QQ 接口數據限制；語音等媒體仍以類型佔位文字呈現。聊天內容在回覆或主動查詢時會進入 Harness 配置的模型服務。
安裝與啓用¶
環境要求（README）：Node.js 22.14+（建議 24 LTS）、提供當前 Agent/工具接口的 Harness（文檔參考 0.2.1-rc.4），QQ 空間功能需要 Edge 瀏覽器。package.json 聲明 node >=22.14.0、dsh >=0.2.1-rc.3。
Windows x64 新安裝¶
- 解壓插件源碼目錄
dsh-qq-access，在 PowerShell 中執行：
npm ci
node cli.mjs setup
按提示輸入要接入的 QQ 號。管理員 QQ 可留空（僅在本地 Harness 管理）；若填寫，應使用另一個 QQ 號，避免登錄號自身出站消息觸發自動回覆。setup 在 Windows x64 上會啓用託管模式、生成密鑰並下載運行包（約 118.3 MiB，首次需聯網）。默認配置路徑爲 %USERPROFILE%\.dsh-qq-access\config.json，不會覆蓋已有文件。下載失敗可執行 node cli.mjs napcat-install 重試。
- 從 GitHub Releases 下載最新
dsh-qq-access.tgz，在 Harness 桌面版插件管理中指定完整路徑；或在 CLI / Web profile 中：
dsh plugin --profile web add C:/Plugins/dsh-qq-access.tgz
dsh web
profile 須與實際啓動環境一致。插件會自動啓動 NapCat，掃碼頁就緒後打開瀏覽器；未彈出時可執行 node cli.mjs napcat-login。
- QQ 空間需單獨登錄（與 NapCat 狀態分離）：
node cli.mjs qzone-login
在獨立 Edge 窗口登錄同一 QQ 號，回終端按回車。關閉登錄窗口後再調用空間相關工具。
從舊版升級¶
解壓新源碼、npm ci 後運行 node cli.mjs napcat-enable（備份配置並啓用託管），再在 Harness 中用新 .tgz 替換並重載。無 napcat 配置段時仍爲 external 模式。
離線準備 NapCat 包¶
從 NapCat v4.18.41 官方 Release 下載 NapCat.Shell.Windows.Node.zip，在已啓用託管的配置下：
node cli.mjs napcat-install --archive C:/Downloads/NapCat.Shell.Windows.Node.zip
文件須與固定版本及 SHA256 一致，不能用 Framework、普通 Shell 或 OneKey 包代替。
典型用法¶
在 Harness 對話中可直接用自然語言驅動工具，README 示例包括：
- 查看 QQ 接入狀態
- 列出我的羣
- 讀取好友 234567890 最近 30 條消息
- 給 QQ 234567890 發：今晚八點見
- 在 QQ 234567890 的空間留言板留言：週末快樂
發送與留言使用唯一 request_id；重試須複用同一標識。只有 status: sent 表示成功，pending 或 uncertain 需先覈對實際結果。
常用配置項（修改後重載插件）：
| 配置項 | 默認與用途 |
|---|---|
napcat.mode |
新 Windows x64 爲 managed；外部接入爲 external |
reply.private / reply.group |
私聊默認開；羣聊默認 mention，可改 off 或 all |
access.privateMode / access.groupMode |
默認 all，可改 allowlist 或 disabled |
access.privateIds / access.groupIds |
白名單，QQ 號/羣號爲字符串 |
ownerIds |
管理員私聊賬號，默認空 |
persona |
稱呼、性格、語氣、回覆習慣 |
retentionDays |
默認 30 |
普通聯繫人僅允許本會話聊天與歷史查詢；管理員權限以傳輸層確認的私聊賬號爲準，羣內按普通成員處理。
排查時可只讀執行：
node cli.mjs doctor
尚未啓動 Harness 或未掃碼時，API 離線不一定表示安裝失敗；qq_status.napcat.state 可查看啓動、待掃碼、在線狀態。
適用場景與注意¶
適合：已在用 DSH、希望把個人 QQ（私聊、羣 @、可選空間留言）接到同一 Harness 工作流，並在 Windows x64 上減少手工維護 NapCat 的用戶。
注意：
- 插件以當前 DSH 進程權限運行；安裝前請檢查源碼與許可證，勿在未審計的環境中接入生產 QQ 號。
- README 說明本版在 Linux 做過本地測試並校驗運行包，未在 Windows 完成真實 QQ 登錄與空間驗收；空間頁面結構、權限與驗證碼需在目標機器自行驗證。
- API、上報與登錄頁僅綁定本機；端口衝突時退出衝突程序或改配置後重載。控制台日誌在配置對應
data/napcat/logs/console.log，可能含敏感信息，僅用於本機排查。 - DSH 社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件來自社區，非官方應用商店條目。
結尾¶
dsh-qq-access 把 NapCat 託管、QQ 消息 AI 回覆（含可選圖片理解）、本地歸檔與 QQ 空間留言，以及左側欄可視化人設與權限管理，收斂爲單一 DSH 客戶端插件。需要細節、外部模式說明與驗證記錄時，以倉庫爲準：
- 目錄頁：https://www.skillhub.cn/plugins/Applepinea/dsh-qq-access
- GitHub：https://github.com/Applepinea/dsh-qq-access
