前言¶
在 Windows 上跑 NapCat 並開啓 OneBot 11 HTTP 服務後，模型或自動化腳本要發消息、查羣、調官方 action，往往需要自己拼 URL、對照文檔填參數，還要處理返回 JSON。手工 curl 或零散腳本難以在 Harness 對話裏複用，也不利於覆蓋官方文檔裏的大量接口。
下面介紹維護者 EviMing 發佈的聯網工具插件 dsh-napcat-tools（GitHub：EviMing/dsh-napcat-tools）。它把本機 NapCat 的 HTTP API 封裝成 Harness 可調用的工具，並附帶零第三方依賴的 Python CLI，當前快照對齊 NapCat 官方文檔 4.18.42 的 204 個 action。插件本身不實現 QQ 協議，只負責組參、啓動倉庫內 Python 包，並把 --json 結果交回 Harness。
這是什麼¶
dsh-napcat-tools 提供兩層能力：
- DeepSeek Harness Host 插件：註冊
napcat_call、napcat_send兩個模型工具； - 獨立 Python 包
napcat_api：可通過python -m napcat_api使用，不依賴 DSH。
NapCat 的地址、token、QQ 號由 Python 包自動發現：掃描 <NapCat>/napcat/config/onebot11_*.json 裏啓用的 httpServers；也可用環境變量 NAPCAT_ROOT、NAPCAT_HTTP、NAPCAT_TOKEN、NAPCAT_QQ 覆蓋。許可證爲 MIT（package.json 版本 1.0.0）。
核心功能¶
Harness 工具¶
napcat_call¶
調用任意官方 action，返回 { ok, action, data }。參數名不在官方文檔裏時默認拒絕，可加 "force": true 跳過校驗。
napcat_send¶
羣聊/私聊快捷發送，支持 text、images、files、at、reply、record、video、face、markdown、jsonCard、dryRun 等。target 形如 group:羣號 或 user:QQ號；本地媒體由 Python 側讀成 base64://，也可直接給 http(s):// 或 base64://。
Python CLI¶
覆蓋官方 spec 中的 204 個 action，並提供 version、whoami、groups、history、send、call、actions、doc、sync-docs 等子命令。倉庫內 docs/ACTIONS.md 爲 action 參考，docs/QZONE.md 爲 28 個 QQ 空間接口，docs/TOOLS.md 爲 DSH 工具說明。
架構要點¶
DSH 側 index.js 註冊工具，lib/runner.mjs 通過 spawn python -m napcat_api 收集並解析 JSON。napcat_api/spec.json 爲 4.18.42 的 action 裁剪快照；NapCat 升級後可執行 python -m napcat_api sync-docs 更新 spec，再運行 python tools/gen_docs.py 重新生成文檔。
前置條件¶
安裝與使用前需確認：
- Windows 上的 NapCat 已登錄，並啓用 OneBot 11 HTTP 服務（默認常見爲
127.0.0.1:3000）； - Python 3.9+，無需安裝第三方包；
- 可選 Node.js：僅在
sync-docs解析官方 OpenAPI 分塊時需要； - DeepSeek Harness，且本機 profile 支持安裝 Host 插件 bundle。
安裝與啓用¶
1. 準備倉庫路徑¶
將 dsh-napcat-tools 源碼放到本機目錄，記下根路徑（下文以該路徑作爲 bundle 目標）。
2. 驗證 Python CLI¶
在倉庫根目錄執行：
python -m napcat_api version --check
python -m napcat_api whoami
若輸出包含 NapCat 版本、文檔版本與在線探測等信息，說明自動發現或環境變量配置正常。更多命令見倉庫內 napcat_api/README.md。
3. 安裝 DSH 插件 bundle¶
編輯 cordis.patch.yml，將 cwd 改爲本倉庫根目錄：
config:
cwd: 'D:\path\to\dsh-napcat-tools'
python: ''
timeoutMs: 120000
隨後通過插件管理安裝（路徑替換爲實際目錄）：
plugin_manager action=install_bundle target=D:\path\to\dsh-napcat-tools
新安裝的 bundle 立即生效；之後若修改 index.js，需重啓 DSH 纔會重新加載。
典型用法¶
在 Harness 中調用 action¶
查詢登錄信息：
{ "action": "get_login_info" }
查羣信息與發羣消息：
{ "action": "get_group_info", "params": { "group_id": 1103136906 } }
{ "action": "send_group_msg", "params": { "group_id": 1103136906, "message": "hello" } }
快捷發消息¶
羣聊帶 @：
{ "target": "group:1103136906", "text": "晚上好", "at": ["10001"] }
私聊帶圖片路徑：
{ "target": "user:10001", "text": "看圖", "images": ["D:\\pics\\a.png"] }
回覆某條消息：
{ "target": "group:1103136906", "text": "回覆你", "reply": "123456789" }
命令行速查¶
python -m napcat_api version --check
python -m napcat_api whoami
python -m napcat_api groups
python -m napcat_api history -g 1103136906 -n 20
python -m napcat_api send -g 1103136906 -t "你好" --image D:\pics\a.png
python -m napcat_api call get_group_list --json
python -m napcat_api actions --search group
python -m napcat_api doc send_group_msg
python -m napcat_api sync-docs
version --check 會同時對照本地 version.json、在線 NapCat 與官方文檔三方版本。
適用場景與注意¶
適合誰：已在 Windows 本機部署 NapCat，希望在 DSH 對話裏讓模型查羣、發消息或調用完整 OneBot action；或希望用同一套 Python CLI 做腳本化操作而不綁死 Harness。
運行權限：插件隨當前 DSH 進程在本機執行，會調用本地 Python 與 NapCat HTTP 接口。安裝前應閱讀倉庫源碼與 MIT 許可證，確認路徑與 cordis.patch.yml 中的 cwd、python、timeoutMs 符合你的環境。
安全：napcat_call 不做業務風控，set_group_ban、set_group_kick、退羣等操作會直接執行。access token 僅存在於 NapCat 本地配置，倉庫不包含 token 或賬號密碼。建議只在可信網絡暴露 OneBot HTTP 端口。
生態說明：DeepSeek Harness 採用「一切皆插件」的擴展方式；社區目錄 SkillHub 插件頁 爲獨立收錄站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
經過上面的步驟，你可以把 NapCat 的 204 個官方 action 與快捷發消息能力接到 Harness，同時保留可獨立使用的 napcat_api CLI。進一步參數與返回值見倉庫 docs/TOOLS.md、docs/ACTIONS.md。
