前言¶
在 DSH 里接 QQ，常见组合是 NapCat 作 OneBot 协议端，再用 dsh-qq-bridge 把消息接到会话。NapCat 需要自己先跑起来、端口要通、扫码或快速登录状态还要稳定；DSH 一重启，进程链往往跟着断，OneBot 端口不通时 bridge 侧还会出现 ECONNREFUSED。手工每次开 DSH 再开 NapCat，和「Harness 常驻、插件扩展能力」的用法也不合拍。社区里此前缺少「DSH 打开就自动把 NapCat 拉起来并盯着别掉线」的现成插件；dsh-napcat-keeper（维护者 waning-sun，GitHub：waning-sun/dsh-napcat-keeper）就是面向这个缺口的工作流类插件，README 建议与 Yuuyuko-uu 的 dsh-qq-bridge 搭配使用。
这是什么¶
一句话：在 DSH 运行时自动运行并看护 NapCat（QQ 协议端）的小插件——DSH 在，看门狗就按规则把 QQ 接上；掉线、卡死、重复进程会按文档里的策略处理。bridge 负责「说话」，keeper 负责「别掉线」；也可以单独用，只要需要 NapCat 长期存活。
插件通过 npm 包名 dsh-napcat-keeper 发布（资料中当前版本 2.8.2，许可证 MIT，dshTarget 为 0.2.1-rc.2，Node 引擎要求 >=20）。配置与状态集中在 DSH 设置 → napcat桥，保存后写入 ~/.dsh/dsh-napcat-keeper/config.json 并热生效，无需为此重启 DSH。
核心功能¶
下面介绍看门狗在 README 中明确列出的行为（均为插件自述能力，使用前请自行核对环境与风险）。
探活与拉起¶
| 情况 | 行为 |
|---|---|
| OneBot 端口不通且没有 NapCat 进程 | 拉起（默认 cscript；仅当填写了计划任务名时走计划任务） |
| 刚拉起、端口尚未通 | 宽限期（默认 150s），期间不重复拉 |
| 卡在扫码 | 记 need-scan；超过 scanTimeoutSec 则杀掉重来，重试 maxScanRetries 次后放弃并写日志 |
| 两条 QQ 进程链（互踢常见原因） | 按启动时间聚类，只杀晚出现的链，保留正在服务的那条 |
| 进程在、端口不通且无新信号 | 判为卡死，杀掉重来 |
| 一切正常 | 心跳（默认 10 分钟一行），并检查 dsh-qq-bridge 轮询是否仍新鲜 |
外部调用带超时，异常写日志；跨进程有锁，避免两个 DSH 实例同时拉崩环境。
反向 WebSocket 与 dsh-onebot-qq¶
NapCat 可走正向 HTTP/WS（NapCat 自己监听），也可走反向 WebSocket（由其它服务监听，NapCat 连进去）。反向模式下用 HTTP 探端口可能得到 401 / 426；较新版本会区分：426 视为反向 WS 模式不误杀，401 提示核对 accessToken。配置要点：把 onebotPort 填成反向 WS 服务监听端口，NapCat 侧 WS 地址与令牌与 DSH 侧一致；「在线探测方式」可用 auto 或明确选「反向 WebSocket」。
分盘扫描与 Shell 目录¶
自 2.2.2 起，不再自动猜测 NapCat 安装路径：shellDir 留空即留空。设置页提供分盘深扫（深度上限 7 层，跳过系统目录等，单盘时间与结果上限见 README），命中带 napcat 或含 NapCatWinBootMain.exe 与 .bat 的目录；再用 versions/、QQ.exe、napcat.mjs 等经验规则区分「更像真 Shell」与「仍可选用」的候选。
需管理员或写系统位置的操作¶
DSH 以普通用户权限运行。防火墙规则、往不可写目录补脚本等，插件生成 apply.ps1 / apply-admin.cmd 等，由用户在资源管理器中双击执行（含管理员步骤时会弹 UAC）；结果读回 result.json，撤销用同目录 undo-admin.cmd。可选项包括：自动启动脚本、中间层 env.bat、用户级计划任务、防火墙放行 OneBot 入站等，详见 README 表格。
记住密码（默认关闭）¶
快速登录令牌会失效；若需无人值守自动登录，可勾选「记住密码」，但 README 明确：明文写入 config.json 与 env.bat，风险自担，可随时「清除密码」。密码经环境变量注入，不写进命令行参数。
拉起方式与黑框¶
默认 NapCat 进程链随 本 DSH 实例 生灭（cscript）；DSH 重启后 QQ 掉线是预期行为，新实例会再拉。若希望 DSH 关闭后 QQ 仍存活，需填写计划任务名并配合计划任务拉起（schtasks /run）。默认通过 launch.vbs 隐藏控制台窗口；可关闭「拉起时不显示黑框」或对已运行链使用「收起黑框」。
Node 运行时优先用 DSH 自带 Node，一般无需单独安装；Shell 型 NapCat（顶层有 napcat.mjs）与 OneKey 注入型路径不同，README 有说明。
安装与启用¶
前置：NapCat 与 OneBot HTTP¶
- 安装 NapCat.Shell（Windows 有一键包）。
- NapCat WebUI → 网络配置 → 添加 HTTP 服务器：
127.0.0.1，端口如3000，按需设置 token。 - 手动运行一次并完成扫码登录（有登录缓存时可减少重复扫码）。
安装插件¶
桌面版：设置 → 插件 → 添加插件，在「包名或地址」中只填包名：
dsh-napcat-keeper
不要粘贴整条 CLI，也不要加 github: 前缀；错误写法会触发 registry 或 git 相关报错（README「常见问题」有 'git' is not recognized 说明）。
命令行：
dsh plugin --profile <profile> add dsh-napcat-keeper
安装后重启一次 DSH（首次装载生效），再打开 设置 → napcat桥。
典型用法¶
首次配置（三个主要字段）¶
| 配置项 | 说明 |
|---|---|
| NapCat Shell 目录 | 分盘扫描后点「用这个」，或手填如 C:/Users/你/NapCat/OneKey/NapCat.Shell |
| 要快登的 QQ 号 | 优先选用该号的启动脚本；必要时自动生成调 NapCatWinBootMain.exe 的脚本 |
| OneBot HTTP 端口 | 与 NapCat httpServers 一致，默认 3000 |
保存后在「状态」查看在线昵称与 QQ 号；离线可点「拉起 NapCat」。常用按钮还包括：重新探活、杀掉重拉、去重复链、全部杀掉等（见 README「页面上的按钮」表）。
与 dsh-qq-bridge 配合¶
先保证 keeper 让 NapCat 与 OneBot 端口稳定，再安装 bridge 做会话桥接；两者分工在 README 开头已说明。
适用场景与注意¶
适合：在 Windows 上用 DSH + NapCat +（可选）QQ bridge 做本地 QQ 工作流，希望 DSH 启动后 NapCat 自动拉起、端口与进程异常时能按规则自愈的用户。
注意：
- 插件在 当前 DSH 进程的用户权限 下运行；安装前请阅读 GitHub 仓库 源码与 MIT 许可证，作者声明 README 多为辅助生成、可能存在未检出的问题。
- 社区插件目录 SkillHub 条目 与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，以自行评估为准。
- 勿将含
plan.json（开启记住密码时可能含 base64 密码）的目录同步或外发。 - 命令行安装使用 npm 包名，不要使用资料未给出的
dsh plugin add github:waning-sun/dsh-napcat-keeper形式。
结尾¶
dsh-napcat-keeper 把 NapCat 的启动与看护收进 DSH 设置页：端口不通就拉、重复进程就清、扫码与卡死有超时与重试策略，并可与 dsh-qq-bridge、反向 WS 场景衔接。经过上面的步骤装好 NapCat、添加插件并填好 napcat桥，即可在 DSH 常驻开发时减少手工盯 QQ 进程的时间。
- 目录页：https://www.skillhub.cn/plugins/waning-sun/dsh-napcat-keeper
- GitHub：https://github.com/waning-sun/dsh-napcat-keeper
