前言¶
在 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。
