dsh-napcat-keeper 2.7.2 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 2.8.0 — 认得出反向 WebSocket（和 dsh-onebot-qq 共存）
+- **修的什么**：装了 `dsh-onebot-qq` 这类插件、把 NapCat 配成**反向 WebSocket** 连过来的机器上，本插件永远判「离线」，然后无限重启。原因是探测只用 HTTP 打 `get_login_info`，而反向 WS 的端口根本不吃 HTTP（换来 401 / 426）；老代码只看返回的 body、不看 HTTP 状态码，于是把「端口明明在回话」当成「端口不通」→ 卡死判定 → 杀掉重拉 → 循环。
+- 现在 `postOneBot` 会把 HTTP 状态码带回来，`probe()` 据此分清四种情况：能问到 `login_info`（普通 HTTP）、只收 WebSocket（反向 WS）、端口要求鉴权（多半是令牌不对）、端口没开。
+- 新增「在线探测方式」（`probeMode`）：`auto`（默认，先按 HTTP 问，问不通再看是不是反向 WS）/ `http` / `reverse` / `process`（只看进程，不碰端口）。设置页「连接」那组里能直接选。
+- 反向 WS 模式下「在线」的判定改成：端口上有**客户端连进来**（`Get-NetTCPConnection` 数客户端那一侧的连接）。关键的一条是**进程在 + 端口有服务就别杀** —— 端口回 401/426 说明服务活着，重拉解决不了任何问题，只会把正在连的那条链踹下去。
+- 真等不来客户端时也不再每轮都杀：先按 `stuckSec` 等，超时才**温和重拉**一次，最多两次，还不成就进 `reverse-giveup`，在日志和状态条里说清楚该去 NapCat 里把反向 WS 地址填成 `ws://127.0.0.1:<端口>`。
+- 顺带加了拉起退避：连续拉不起来时宽限期按 2 的幂放大（最多 8 倍），不会再 45 秒一次地反复拉。
+- 状态条能显示「反向 WS 已连接 / 客户端 N」，端口回 401 时显示「需鉴权」，并把该改哪里写在提示里。
+- 补了 `pnpm selftest:probe`（27 项）：本地起假服务器分别模拟正常 OneBot / 426 无客户端 / 426 有客户端 / 401 / 端口没开，另加 `probeMode` 的强制值归一化。全程环回 + 临时端口，不碰真配置。
+
+## 2.7.3 — 修「设置页保存不进去」+ README 补「装不上」的两条排障
+- **修了个真 bug，2.7.0 起就有**：设置页点「保存」、「用这个」、或者「清除密码」，值当场弹回原样，什么都没存下来。起因是 2.7.0 把插件自己的文件收进 `~/.dsh/dsh-napcat-keeper/` 时，只把**读取**改成了新目录，**写入**还留在老地方 `~/.dsh/config.json` —— 于是存进一个没人读的文件，界面重新渲染时拿到的还是旧值。2.7.0 / 2.7.1 / 2.7.2 都中招。
+- 现在读和写认同一个目录（`saveAndApply` 与「清除密码」都改走 `keeperDir()`）。
+- **老版本留下的那份被误写的配置会被自动认领**：启动时如果发现 `~/.dsh/config.json` 里有 `shellDir` / `onebotPort` 这类自家字段、而且比插件目录里的配置新，就把它的内容并进真配置（多半正是你当初点了保存却没生效的那次），原文归档进 `legacy/config.adopted-*.json`，认领前的旧配置备份成 `legacy/config.before-adopt.json`。不像插件配置的 `config.json` 一概不碰，也不会拿旧文件顶掉更新的配置。
+- 补了 `pnpm selftest:save`（12 项）：保存真的落到新目录、认领逻辑、keeper 更新时不认领、别人的 `config.json` 不动。
+- **没发版，顺带补了 README 两条排障**：有人从 GitHub 装插件报 `'git' is not recognized as an internal or external command`，查下来是对方机器没装 Git —— `github:` 规格要 pnpm 调外部 `git ls-remote`，插件一个字节都还没下载，跟插件本身无关（npm 上的 2.7.2 一直正常）。
+- 「安装」那节加了一句：**别加 `github:` 前缀**，用 npm 名装全程不碰 git。
+- 「常见问题」补一条，三条路：npm 名装 / 装 Git 后**彻底重启 DSH**（子进程继承 DSH 启动时的 PATH，不重启照旧报错）/ 无 git 时走 `codeload` 的 tarball。
+- 又有人报 `无法识别这个包名或地址：not a package name the registry accepts`：那是 DSH「设置 → 插件 → 添加插件」输入框的**规格校验**，跟插件和网络都无关 —— 他把整条命令（或 `add dsh-napcat-keeper` 这种）粘进了只认「包名 / 仓库地址 / 本地目录」的那一栏。桌面版安装目录里根本没有 `dsh` 命令，用户只能走界面，于是把命令行原样贴进去。
+- README「安装」改成**先桌面版点界面、再命令行**两条路，并点明那一栏只填 `dsh-napcat-keeper`；「常见问题」再加一条，用表格列清楚哪些写法会被拒（整条命令 / 多出的 `add` / 大写 / 全角标点）。
+- 已经在 2.7.0~2.7.2 上装过的，升级到 2.7.3 就行：配置会被自动认领回来，不用手改任何文件。
+
 ## 2.7.2 — 根上一点不留
 - **修的什么**：2.7.0 的搬迁兜底扫描会跳过「规范老名字」（`napcat-keeper-state.json` 这种已经安排好去处的），本意是别把刚搬完的东西又归一次档。但碰上**目标位已经有同名文件**的情况（新目录里先躺着一份 `state.json`），根上那份老的既搬不走、也不归档，就永远留在 `~/.dsh` 根上了 —— 正是这次要收拾的那种乱。
 - 现在兜底扫描不再挑名字：只要还留在根上、名字对得上插件的老命名，一律归档进 `legacy/`；被别的进程攥着搬不动的，下次启动再搬。跑完根上一个不剩。

package/README.md

@@ -40,10 +40,26 @@
 
 ## 安装
 
+**桌面版（点界面的）**：设置 → 插件 → **添加插件**，「包名或地址」那一栏只填包名 ——
+
+```
+dsh-napcat-keeper
+```
+
+> 只填包名，**别把整条命令粘进去**：那一栏是按「包名 / 仓库地址 / 本地目录」解析的，
+> 多一个空格、多一个 `add`、多一个大写字母，就会报 `无法识别这个包名或地址：not a package name the registry accepts`。
+> 顺带一提，桌面版装完之后 DSH 目录里并没有 `dsh` 命令，所以下面那条命令行不是人人都能跑 —— 用不了就走上面这条路。
+
+**命令行**：
+
 ```bash
 dsh plugin --profile <profile> add dsh-napcat-keeper
 ```
 
+> **别加 `github:` 前缀。** 写成 `add github:waning-sun/dsh-napcat-keeper` 走的是 git 通道，pnpm 会去调外部 `git ls-remote`；
+> 机器上没装 Git（或者 Git 不在 PATH 里）就当场报 `'git' is not recognized as an internal or external command`。
+> 上面这条是 npm 名安装，全程不碰 git。真踩到了看「常见问题」里 `'git' is not recognized` 那条。
+
 装完重启一次 DSH（第一次装载才生效），然后去 **设置 → napcat桥**。
 
 ## 首次配置：其实就三个空
@@ -177,6 +193,34 @@ QQ 那条进程链挂在本 DSH 实例下面——DSH 开着它就在，DSH 关
 
 > 顺带一提：`versions\*\resources\app\napcat\napcat.mjs` 那份**不会**被当成入口——它是等 QQ 注入用的，拿普通 Node 直接跑必崩。
 
+## 反向 WebSocket：和 dsh-onebot-qq 共存
+
+NapCat 连 OneBot 有两条相反的路：
+
+- **正向（HTTP / 正向 WS）**：NapCat 自己开端口（`httpServers`），外面去问它 —— 本插件默认就是这么看它的；
+- **反向 WebSocket**：端口由**别人**开着（比如 `dsh-onebot-qq` 插件起的反向 WS 服务，或者你自己写的服务），**NapCat 反过来连进去**。
+
+第二条路上没有 HTTP 接口可问：拿 HTTP 去敲那个端口，换来的是 `401` / `426`。2.7.3 及更早的版本只看返回内容、不看 HTTP 状态码，于是把「端口明明在回话」当成「端口不通」→ 判卡死 → 杀掉重拉 → 无限循环。现在不会了：
+
+| 探测到的情况 | 插件怎么判 | 会不会重启 |
+| --- | --- | --- |
+| 能问到 `get_login_info` | 在线（普通 HTTP） | 不会 |
+| 端口回 `426`（只收 WebSocket） | **反向 WS 模式** | 不重启；等 NapCat 连进来 |
+| 端口回 `401` | 需鉴权（多半是令牌不对） | 不重启，提示你去对 `accessToken` |
+| 端口开着、也有客户端连进来 | 在线（反向 WS） | 不会 |
+| 端口连不上、进程也不在 | 离线 | 拉起（带退避） |
+
+配置上只要两步：
+
+1. 把 `onebotPort` 填成**反向 WS 服务监听的端口**（不是 NapCat 里那个 `httpServers` 的端口——反向模式下 NapCat 根本不监听）；
+2. 「在线探测方式」留 `auto` 就行；想明确指定就选 `反向 WebSocket`。
+
+然后在 NapCat 那边把反向 WS 地址填成 `ws://127.0.0.1:<上面那个端口>`，令牌对上 `accessToken`。
+
+真等不来客户端时，插件也不会每轮都杀进程：先按 `stuckSec`（默认 420 秒）等，超时才**温和重拉**一次，最多两次；还不行就进 `reverse-giveup`，把「该去 NapCat 里改反向 WS 地址」写进日志和状态条，不再折磨那条链。
+
+> 同一个端口没法既当 HTTP 接口又当反向 WS 服务 —— 谁先占着就听谁的。两样都想要，就给它们分两个端口。
+
 ## 给 agent 用的三个工具
 
 | 工具 | 作用 |
@@ -197,8 +241,9 @@ QQ 那条进程链挂在本 DSH 实例下面——DSH 开着它就在，DSH 关
 | `nodePath` | 空（自动） | 指定 `node.exe`；留空按「DSH 自带 → 系统 PATH → 常见安装目录 → NapCat 目录」找，见上一节 |
 | `rememberPassword` | `false` | 记住 QQ 密码、令牌失效时自动密码登录（**明文落盘，详见上节**） |
 | `quickPassword` | 空 | QQ 密码；只在保存时写入，接口不回显、日志不打印 |
-| `onebotPort` | `3000` | OneBot 11 HTTP 端口 |
-| `accessToken` | 空 | OneBot access token |
+| `onebotPort` | `3000` | OneBot 端口。普通部署填 NapCat 里 `httpServers` 的端口；反向 WebSocket 部署填**反向 WS 服务**监听的端口 |
+| `accessToken` | 空 | OneBot access token（跟 NapCat 或反向 WS 服务里填的一致） |
+| `probeMode` | `auto` | 在线探测方式：`auto` 先按 HTTP 问、问不通再看是不是反向 WS；`http` 只认 HTTP 接口；`reverse` 只认反向 WebSocket；`process` 只看进程不碰端口 |
 | `taskName` | 空（= 用 cscript，QQ 跟着 DSH 生灭） | 想脱离 DSH 才填计划任务名 |
 | `autoCreateTask` | `false` | 填了 `taskName` 且任务不存在时自动创建 |
 | `hideConsole` | `true` | 拉起时不显示黑框（用 wscript 壳藏窗口） |
@@ -279,6 +324,14 @@ npm run check:privacy              # 只查隐私（发版前必跑）
 **换端口了？**
 改「OneBot HTTP 端口」保存即可；如果同时换了 Shell 目录，跨进程锁会自动清掉。
 
+**用着 dsh-onebot-qq（反向 WebSocket），插件永远显示离线、进程反复重启？**
+2.7.3 及更早的版本只会用 HTTP 去问 `get_login_info`，而反向 WS 的端口不吃 HTTP（回 `401` / `426`），
+于是被当成「端口不通」→ 判卡死 → 杀掉重拉，一轮一轮地折腾。
+现在的版本认这条路：端口回 426 就判成**反向 WS 模式**，改成看「端口上有没有客户端连进来」，
+进程在 + 端口有服务时**不再杀**。设置上只要把「OneBot HTTP 端口」改成反向 WS 服务监听的端口，
+「在线探测方式」留 `auto`（或直接选「反向 WebSocket」），细节见前面「反向 WebSocket：和 dsh-onebot-qq 共存」那节。
+状态条里会显示 `探测：反向 WebSocket · 客户端 N`，卡住时给的提示也是「去 NapCat 里把反向 WS 地址填成 `ws://127.0.0.1:<端口>`」。
+
 **老是掉线、每次都要扫码？**
 令牌过期了。要么每次手机扫，要么开「记住密码」让它自己用密码登（先看上上节的风险）。
 `napcat_status` 会直接告诉你现在是 `password` 还是 `token` 在撑、以及密码文件在不在。
@@ -293,6 +346,36 @@ npm run check:privacy              # 只查隐私（发版前必跑）
 2.2.1 之前是 `settings.section` 钩子签名对不上新版 DSH（抛 `Cannot add property N, object is not extensible`），异常冒到设置面板层，整个面板一起白。升级后重开 DSH 即可。
 另外设置页会轮询 `/state`，2.2.1 起热路径有 300 秒进程快照缓存，不再每次都新起 PowerShell；如果你自己写脚本调这个接口，加 `?light=1` 只读缓存、不扫描进程。
 
+**装的时候报 `'git' is not recognized as an internal or external command`？**
+不是插件的问题。那句是 pnpm 在解析 **git 规格的依赖**（`github:owner/repo`、`git+https://…`）时调的外部 `git`；
+DSH 自带的 pnpm 不捎带 git，Windows 上又默认没装，于是就卡在「拉代码」这一步，插件一个字节都还没下载。
+包里的 `lib/` 本来就是入库的、没有构建步骤，所以跟「源码要编译」也没关系。三条路，越靠前越省事：
+
+1. **用 npm 名装** —— 就是上面「安装」那节那条命令，全程不碰 git。
+2. **装 Git**：`winget install --id Git.Git -e`，或者从 [git-scm.com](https://git-scm.com/download/win) 下安装包。
+   装完 **必须彻底退出 DSH 再重开**：pnpm 是 DSH 的子进程，继承的是 DSH 启动那一刻的 PATH，
+   不重启会继续报一模一样的错（很多人以为白装了）。重开后在新的终端里 `git --version` 有输出，再去装插件。
+3. **不装 git、又非要从 GitHub 拉**：改用源码 tarball，pnpm 走 HTTPS 下载、不调 git ——
+   `dsh plugin --profile <profile> add https://codeload.github.com/waning-sun/dsh-napcat-keeper/tar.gz/refs/heads/main`
+   仓库目前没打 tag，所以只能指 `refs/heads/main`；缺点是版本号只能读包里的 `package.json`，也不跟着发版更新。
+
+**装的时候报 `无法识别这个包名或地址：not a package name the registry accepts`？**
+这句是 DSH 在**解析你填的那串字**，还没到下载那一步 —— 跟插件、跟网络都没关系。它是「设置 → 插件 → 添加插件」
+那个输入框的校验：那一栏认三种东西，**npm 包名**（`dsh-napcat-keeper`、`@作者/名字`）、**仓库地址**（`https://github.com/…`）、
+**本地目录**。包名只允许小写字母、数字和 `. _ ~ -`，所以下面这些写法一律被拒：
+
+| 填进去的 | 结果 |
+| --- | --- |
+| `dsh-napcat-keeper` | ✅ |
+| `dsh-napcat-keeper@2.8.0` | ✅（指定版本） |
+| `dsh plugin --profile desktop add dsh-napcat-keeper` | ❌ 整条命令 |
+| `add dsh-napcat-keeper` | ❌ 多了 `add` |
+| `Dsh-napcat-keeper` | ❌ 大写 |
+| `dsh-napcat-keeper。`、`dsh-napcat-keeper；` | ❌ 全角标点 |
+
+改法就一句：**那一栏只填 `dsh-napcat-keeper`**（要指定版本就 `dsh-napcat-keeper@2.8.0`）。想跑命令行的话，得在终端里跑，
+不是在输入框里跑。
+
 ## License
 
 MIT

package/lib/client.js

@@ -126,8 +126,10 @@ window.__ModuleLoader__.load({
           ['launcherScript', '启动脚本', '留空自动挑（quick 优先，其次 napcat*.bat）', 'text'],
           ['nodePath', 'Node 运行时（node.exe）', '留空 = 自动：DSH 自带那份 → 系统 PATH → 常见安装目录 → NapCat 目录。只有「Shell 型」NapCat（目录顶层有 napcat.mjs）才真的用到它；OneKey 注入型跑在 QQ 自己的 Node 里，跟这里无关', 'text'],
           ['launchAccount', '要快登的 QQ 号', '填了它、脚本又找不到时，会自动生成一个直接调 NapCatWinBootMain.exe 的脚本', 'text'],
-          ['onebotPort', 'OneBot HTTP 端口', 'NapCat 里 onebot11 的 httpServers 端口，默认 3000', 'number', true],
-          ['accessToken', 'OneBot 访问令牌', '没设就留空；设了要跟 NapCat 里填的一致', 'password'],
+          ['onebotPort', 'OneBot HTTP 端口', 'NapCat 里 onebot11 的 httpServers 端口，默认 3000。反向 WebSocket 模式下填反向 WS 服务占的那个端口（装了 dsh-onebot-qq 的话通常是它监听的那个）', 'number', true],
+          ['accessToken', 'OneBot 访问令牌', '没设就留空；设了要跟 NapCat（或反向 WS 服务）里填的一致', 'password'],
+          ['probeMode', '在线探测方式', '自动 = 先按 HTTP 接口问；端口只收 WebSocket 时会认成「反向 WS」。如果端口是 dsh-onebot-qq 这类反向 WS 服务在听（HTTP 换来 401/426、老被判离线），明确选「反向 WebSocket」最省事', 'select', false,
+            [['auto', '自动（推荐）'], ['http', '只认 HTTP 接口'], ['reverse', '反向 WebSocket'], ['process', '只看进程']]],
         ],
       },
       {
@@ -177,11 +179,42 @@ window.__ModuleLoader__.load({
     function 状态条(runtime) {
       if (!runtime) return null
       const 在 = runtime.online
+      // 反向 WS：端口是别人在听（dsh-onebot-qq 之类），NapCat 反过来连进去，
+      // 「在线」= 端口上有客户端连进来了，跟 HTTP 那套不是一回事，词得写清楚
+      const 反向 = runtime.mode === 'reverse'
+      const 模式名 = 反向
+        ? '反向 WebSocket'
+        : runtime.mode === 'auth'
+          ? '端口要求鉴权'
+          : runtime.mode === 'process'
+            ? '只看进程'
+            : runtime.mode === 'http'
+              ? 'HTTP 接口'
+              : '端口不通'
+      const 阶段名 = {
+        idle: '待机',
+        online: '在线',
+        launching: '正在拉起',
+        starting: '正在启动',
+        'need-scan': '等扫码',
+        'need-scan-giveup': '扫码放弃',
+        'reverse-wait': '等反向 WS 客户端连进来',
+        'reverse-giveup': '反向 WS 等不到客户端',
+        'need-token': '令牌不对',
+        'port-busy': '端口被别的程序占着',
+        'dedupe-blocked': '去重没杀干净',
+        offline: '离线',
+      }[String(runtime.phase || '')] || String(runtime.phase || '?')
       return h('div', { style: S.card },
         h('div', { style: { display: 'flex', gap: 14, alignItems: 'center', flexWrap: 'wrap' } },
-          h('span', { style: 在 ? S.ok : S.bad }, 在 ? '● 在线' : '○ 离线'),
-          在 ? h('span', null, String(runtime.nickname || '') + '（' + String(runtime.userId || '') + '）') : null,
-          h('span', { style: S.dim }, '阶段：' + String(runtime.phase || '?')),
+          h('span', { style: 在 ? S.ok : S.bad }, 在 ? (反向 ? '● 反向 WS 已连接' : '● 在线') : '○ 离线'),
+          在 && (runtime.nickname || runtime.userId)
+            ? h('span', null, String(runtime.nickname || '') + '（' + String(runtime.userId || '') + '）')
+            : null,
+          h('span', { style: S.dim }, '探测：' + 模式名 + (runtime.portStatus ? ' · HTTP ' + String(runtime.portStatus) : '')),
+          反向 ? h('span', { style: S.dim },
+            '客户端 ' + (runtime.clients === null || runtime.clients === undefined ? '查不到' : String(runtime.clients))) : null,
+          h('span', { style: S.dim }, '阶段：' + 阶段名),
           h('span', { style: S.dim }, '启动 ' + String(runtime.launchCount || 0) + ' 次'),
           runtime.dedupeCount ? h('span', { style: S.dim }, '去重 ' + String(runtime.dedupeCount) + ' 次') : null,
         ),
@@ -214,6 +247,7 @@ window.__ModuleLoader__.load({
           h('span', null, runtime.bridge && runtime.bridge.ageSec !== null ? String(runtime.bridge.ageSec) + ' 秒前' : '没读到'),
         ),
         runtime.error ? h('div', { style: { ...S.bad, marginTop: 6 } }, '最近错误：' + String(runtime.error)) : null,
+        runtime.hint ? h('div', { style: { ...S.dim, marginTop: 4 } }, '提示：' + String(runtime.hint)) : null,
       )
     }
 
@@ -661,7 +695,7 @@ window.__ModuleLoader__.load({
       }
 
       const 渲染项 = (item) => {
-        const [key, label, hint, type] = item
+        const [key, label, hint, type, , options] = item
         const val = 取(草, key)
         let ctl
         if (type === 'bool') {
@@ -672,6 +706,13 @@ window.__ModuleLoader__.load({
               onChange: (e) => 改(key, e.target.checked),
             }),
             h('span', null, val !== false && String(val) !== 'false' ? '开' : '关'))
+        } else if (type === 'select') {
+          ctl = h('select', {
+            style: { ...S.input, maxWidth: 260 },
+            value: val === null || val === undefined || val === '' ? 'auto' : String(val),
+            onChange: (e) => 改(key, e.target.value),
+          },
+            (options || []).map(([v, text]) => h('option', { key: v, value: v }, text)))
         } else {
           ctl = h('input', {
             style: S.input,

package/lib/index.js

@@ -1,9 +1,24 @@
 /**
- * dsh-napcat-keeper —— NapCat 看门狗 v2.7.2（可发布通用版）
+ * dsh-napcat-keeper —— NapCat 看门狗 v2.8.0（可发布通用版）
  *
  * 解决的问题：DSH 是桌面应用，重启 DSH 时 NapCat(QQ 协议端) 不会跟着起来，
  * 于是 dsh-qq-bridge 一直轮询一个死端口，你在 QQ 里说的话就石沉大海。
  *
+ * v2.8.0：认得出反向 WebSocket（和 dsh-onebot-qq 共存）
+ *   - NapCat 走反向 WS 时端口是别人在听（dsh-onebot-qq 之类），HTTP 换来 401/426；
+ *     postOneBot 原先只看 body 不看状态码，于是把「端口在回话」当成「端口不通」
+ *     → 判卡死 → 杀掉重拉 → 无限循环；
+ *   - 现在 probe() 分出 http / reverse / auth / process / dead，反向模式下「在线」=
+ *     端口上有客户端连进来（Get-NetTCPConnection -RemotePort 数），进程在 + 端口有服务
+ *     就不杀；真等不来客户端也只温和重拉两次，之后给提示而不是继续杀；
+ *   - 新增 probeMode（auto / http / reverse / process）；拉起连续失败时宽限期按 2 的幂退避。
+ *
+ * v2.7.3：设置页保存不再空转
+ *   - 2.7.0 把配置文件收进 keeperDir 时只改了「读」，saveAndApply / clearPassword
+ *     还在写 ~/.dsh/config.json，于是点保存 / 点「用这个」之后值立刻弹回原样；
+ *   - 现在读写都走 keeperDir；启动时还会把那份误写的 ~/.dsh/config.json 认领回来
+ *     （带自家字段且比 keeper 里的新才认领，原文归档进 legacy/）。
+ *
  * v2.7.2：根上一点不留
  *   - 搬迁的兜底扫描原先跳过「规范老名字」，于是目标位已经有同名文件时（比如新目录里
  *     已经躺着一份 state.json），根上那份老文件既搬不走、也不归档，永远留在那儿；
@@ -132,7 +147,7 @@ import { homedir, tmpdir } from 'node:os'
 import path from 'node:path'
 
 export const name = 'napcat-keeper'
-export const version = '2.7.2'
+export const version = '2.8.0'
 
 /** tools 用来注册 napcat_* 工具；webServer 用来挂设置界面接口。拿不到也不至于把 DSH 拖崩。 */
 export const inject = ['tools', 'webServer']
@@ -165,6 +180,14 @@ const DEFAULTS = {
   onebotPort: 3000,
   /** OneBot access token，没有就留空 */
   accessToken: '',
+  /**
+   * 怎么判断「NapCat 在线」。
+   *   auto     先当 HTTP 接口问，问不通再看端口是不是反向 WebSocket（默认，两边都能用）
+   *   http     只认 HTTP OneBot 接口
+   *   reverse  只认反向 WebSocket：端口上有没有客户端连进来（配合 dsh-onebot-qq 这类反向 WS 服务）
+   *   process  只看进程在不在，不碰端口
+   */
+  probeMode: 'auto',
   /** 只在这些路径下找 QQ/NapCat 进程；留空 = 由 shellDir 推导（上层目录） */
   procPathMatch: '',
   /** 复查间隔（秒） */
@@ -225,12 +248,16 @@ const STATE_KEY = Symbol.for('dsh.napcat-keeper.state')
 const state =
   globalThis[STATE_KEY] ||
   (globalThis[STATE_KEY] = {
-    phase: 'idle', // idle | online | launching | starting | need-scan | need-scan-giveup | offline
+    phase: 'idle', // idle | online | launching | starting | need-scan | need-scan-giveup | reverse-wait | reverse-giveup | need-token | port-busy | offline
     lastProbeAt: null,
     lastOnlineAt: 0,
     lastLaunchAt: 0,
     lastError: '',
     launchCount: 0,
+    /** 连续拉起几次都没等到上线：宽限期按 2 的幂放大，免得每 45 秒杀一次 */
+    launchFails: 0,
+    /** 反向 WS 模式下「温和重拉」的次数，用完就认命给提示，不再折腾进程 */
+    reverseRetries: 0,
     dedupeCount: 0,
     scanSince: 0,
     scanRetries: 0,
@@ -309,6 +336,59 @@ function moveOne(from, to) {
   }
 }
 
+/**
+ * 认领 2.7.0~2.7.2 因保存 bug 误写到 ~/.dsh/config.json 的那份配置。
+ *
+ * 那三个版本的 saveAndApply 写的是 dshHome()/config.json，而所有读取都走 keeperDir()，
+ * 于是用户每次「保存设置」只是往一个没人读的文件里抄了一遍 —— 值当场弹回旧的样子。
+ * 升级到修好的版本后，把那份（可能是用户最后一次真正想保存的内容）并进真配置里，原文归档进 legacy/。
+ *
+ * 只在不含糊的前提下动手：根上得有 config.json、得能解析成对象、得带至少两个自家字段
+ * （别把别的程序放在 ~/.dsh 的 config.json 抢走），而且它得比 keeper 里的新 ——
+ * 修好以后再保存就会写 keeper，mtime 立刻反超，这条认领自然不会再触发。
+ */
+function adoptStrayConfig(dir) {
+  const home = dshHome()
+  const stray = path.join(home, 'config.json')
+  const target = configFilePath(dir)
+  let strayAt
+  try {
+    strayAt = statSync(stray).mtimeMs
+  } catch {
+    return 0
+  }
+  let mine = false
+  let parsed = null
+  try {
+    parsed = JSON.parse(readFileSync(stray, 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return 0
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return 0
+  const marks = ['shellDir', 'onebotPort', 'launchAccount', 'taskName', 'procPathMatch', 'scanTimeoutSec']
+  if (marks.filter((k) => Object.prototype.hasOwnProperty.call(parsed, k)).length < 2) return 0
+  try {
+    mine = statSync(target).mtimeMs < strayAt
+  } catch {
+    mine = true // keeper 里还没有配置，那它就是唯一的一份
+  }
+  if (!mine) return 0
+  const keep = readConfigFile(dir)
+  const merged = { ...keep, ...parsed }
+  try {
+    mkdirSync(path.join(dir, 'legacy'), { recursive: true })
+    if (existsSync(target)) {
+      copyFileSync(target, path.join(dir, 'legacy', 'config.before-adopt.json'))
+    }
+    writeConfigFile(dir, merged)
+    // 归档原文，不留一份会被下次认领的副本
+    moveOne(stray, path.join(dir, 'legacy', `config.adopted-${new Date().toISOString().replace(/[:.]/g, '-')}.json`))
+    return 1
+  } catch {
+    return 0
+  }
+}
+
 /** 把老版本散在 ~/.dsh 根上的文件搬进 keeperDir；重复调用是空操作，返回搬了几个 */
 function migrateLegacyFiles(dir) {
   const target = dir || keeperDir()
@@ -343,6 +423,8 @@ function migrateLegacyFiles(dir) {
       } catch {}
     }
   } catch {}
+  // 根上那份 config.json 是 2.7.0~2.7.2 的保存 bug 留下的，认领回来
+  if (adoptStrayConfig(target)) moved += 1
   lastMigrated = moved
   return moved
 }
@@ -703,6 +785,9 @@ function normalizeConfig(cfg) {
   cfg.launchAccount = String(cfg.launchAccount || '').trim().replace(/\D/g, '')
   cfg.launchArgs = String(cfg.launchArgs || '').trim()
   cfg.accessToken = String(cfg.accessToken || '').trim()
+  cfg.probeMode = PROBE_MODES.has(String(cfg.probeMode || '').trim().toLowerCase())
+    ? String(cfg.probeMode).trim().toLowerCase()
+    : 'auto'
   cfg.procPathMatch = String(cfg.procPathMatch || '').trim()
   cfg.taskName = String(cfg.taskName || '').trim()
   cfg.onebotPort = clampNum(cfg.onebotPort, 1, 65535, 3000)
@@ -804,6 +889,13 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 /* OneBot                                                             */
 /* ------------------------------------------------------------------ */
 
+/**
+ * 发一个 OneBot HTTP 动作。
+ *
+ * 返回值里带上 HTTP 状态码：反向 WebSocket 模式下（比如 dsh-onebot-qq 占着这个端口）
+ * 对方根本不会回 OneBot 的 JSON，能拿到的唯一线索就是 401 / 426 这类状态码 ——
+ * 老版本把状态码丢了，于是一律当成「端口不通」，接着就是杀掉重拉，无限循环。
+ */
 function postOneBot(cfg, action, payload, timeoutMs = 4000) {
   return new Promise((resolve) => {
     const body = JSON.stringify(payload || {})
@@ -824,50 +916,177 @@ function postOneBot(cfg, action, payload, timeoutMs = 4000) {
           timeout: timeoutMs,
         },
         (res) => {
+          const status = Number(res.statusCode) || 0
           let buf = ''
           res.setEncoding('utf8')
           res.on('data', (c) => {
             buf += c
           })
           res.on('end', () => {
+            const raw = String(buf).slice(0, 200)
+            let parsed = null
             try {
-              resolve(JSON.parse(buf))
-            } catch {
-              resolve({ retcode: -1, raw: String(buf).slice(0, 200) })
+              parsed = JSON.parse(buf)
+            } catch {}
+            if (parsed && typeof parsed === 'object') {
+              resolve({ ...parsed, status })
+              return
             }
+            resolve({ retcode: -1, status, raw })
           })
         },
       )
     } catch (error) {
-      return resolve({ retcode: -1, error: String((error && error.message) || error) })
+      return resolve({ retcode: -1, status: 0, error: String((error && error.message) || error) })
     }
     req.on('timeout', () => {
       try {
         req.destroy(new Error('timeout'))
       } catch {}
-      resolve({ retcode: -1, error: 'timeout' })
+      resolve({ retcode: -1, status: 0, error: 'timeout' })
     })
-    req.on('error', (error) => resolve({ retcode: -1, error: String((error && error.message) || error) }))
+    req.on('error', (error) =>
+      resolve({ retcode: -1, status: 0, error: String((error && error.message) || error) }),
+    )
     try {
       req.write(body)
       req.end()
     } catch (error) {
-      resolve({ retcode: -1, error: String((error && error.message) || error) })
+      resolve({ retcode: -1, status: 0, error: String((error && error.message) || error) })
     }
   })
 }
 
+const PROBE_MODES = new Set(['auto', 'http', 'reverse', 'process'])
+
+/** portClients 的缓存：设置页轮询很密，别每 1.5 秒起一个 powershell */
+const linksCache = { port: 0, at: 0, value: null, inflight: null }
+
+/**
+ * 这个端口上现在挂着几个「已经连进来」的客户端？
+ *
+ * 反向 WebSocket 的形态是：端口由 DSH 这边的插件监听（常见是 dsh-onebot-qq），
+ * NapCat 反过来连进去。这种部署下没有任何 HTTP 接口能问「你在线吗」，
+ * 但有件事可以从系统侧看见：这个端口上有没有一条 ESTABLISHED 的回环连接 ——
+ * 有，就说明对面真的连上了。
+ *
+ * 查不出来就返回 count: null。「查不到」和「没连上」是两回事，
+ * 混成一个就会又变成瞎判离线、瞎杀进程。
+ */
+async function portClients(cfg, maxAgeMs = 5000) {
+  const port = Number(cfg.onebotPort) || 0
+  if (!port) return { count: null, pids: [], source: 'no-port' }
+  // 设置页 1.5s 轮询 /state，而这个函数要新开一个 powershell：
+  // 缓存 + 同刻只允许一个子进程，否则又是一场 PowerShell 风暴（见 uiCache 那段注释）
+  if (linksCache.port === port && linksCache.value && Date.now() - linksCache.at < maxAgeMs) {
+    return linksCache.value
+  }
+  if (linksCache.port === port && linksCache.inflight) return linksCache.inflight
+  linksCache.port = port
+  linksCache.inflight = (async () => {
+    const self = String(process.pid)
+    // 看的是「谁连进了这个端口」，所以按 RemotePort 找客户端那一侧：
+    // 按 LocalPort 找会命中服务端那条 socket，而它的所有者是跑反向 WS 服务的进程（就是 DSH 自己），
+    // 把它排除掉就一条都数不到了 —— 这个坑第一版就踩了。
+    const script =
+      "$ErrorActionPreference='SilentlyContinue';" +
+      `$c=@(Get-NetTCPConnection -State Established -RemotePort ${port} -ErrorAction SilentlyContinue | ` +
+      `Where-Object { [string]$_.OwningProcess -ne '${self}' });` +
+      `'CLIENTS=' + $c.Count + ' PIDS=' + (($c | Select-Object -ExpandProperty OwningProcess -Unique) -join ',')`
+    const out = await runPs(script, 12000)
+    const m = /CLIENTS=(\d+)\s+PIDS=([0-9,]*)/.exec(String(out || ''))
+    if (!m) return { count: null, pids: [], source: 'ps-fail' }
+    const pids = m[2] ? m[2].split(',').map(Number).filter((n) => Number.isInteger(n) && n > 0) : []
+    return { count: Number(m[1]) || 0, pids, source: 'ps' }
+  })()
+    .then((value) => {
+      linksCache.value = value
+      linksCache.at = Date.now()
+      return value
+    })
+    .finally(() => {
+      linksCache.inflight = null
+    })
+  return linksCache.inflight
+}
+
+/**
+ * 问一句「NapCat 现在怎么样」，顺带分辨端口是被谁占着的。
+ *
+ * 返回的 mode 决定看门狗后面怎么走：
+ *   http     正常 HTTP OneBot 接口，能问到 login_info
+ *   reverse  端口只收 WebSocket（反向 WS 服务在跑，HTTP 换来 426/401）
+ *   auth     端口有响应但拒绝鉴权，多半是 accessToken 对不上
+ *   http     其它 HTTP 响应（不是 OneBot API 该有的样子）
+ *   dead     连不上，端口没开
+ *   process  配置里关了端口探测，只看进程
+ */
 async function probe(cfg) {
+  const want = PROBE_MODES.has(cfg.probeMode) ? cfg.probeMode : 'auto'
   const login = await postOneBot(cfg, 'get_login_info')
   const data = login && login.data
+  const status = Number(login && login.status) || 0
   const online = Boolean(login && login.retcode === 0 && data && (data.user_id || data.uin))
-  return {
+  const portAlive = status > 0
+  const result = {
     online,
     retcode: login && login.retcode,
+    status,
+    portAlive,
+    mode: 'dead',
+    clients: null,
     nickname: online ? data.nickname : '',
     userId: online ? data.user_id || data.uin : '',
-    error: online ? '' : String((login && (login.error || login.raw || login.wording)) || 'no response'),
+    error: '',
+    hint: '',
+  }
+  if (online) {
+    result.mode = 'http'
+    return result
+  }
+  if (want === 'process') {
+    result.mode = 'process'
+    result.error = '按配置只看进程（probeMode=process）'
+    return result
+  }
+  if (!portAlive) {
+    result.error = String((login && (login.error || login.raw || login.wording)) || 'no response')
+    result.hint = '端口连不上'
+    return result
+  }
+  // 端口肯回 HTTP，说明有个服务在听 —— 这本身就意味着「进程是活的」，不该被杀
+  const links = await portClients(cfg)
+  result.clients = links.count
+  if (want === 'reverse') {
+    result.mode = 'reverse'
+  } else if (status === 426) {
+    // 426 = 服务端只收 WebSocket 升级。auto 直接判反向；设了「只认 HTTP」就老实说端口回的是 426
+    result.mode = want === 'http' ? 'http' : 'reverse'
+  } else if (status === 401) {
+    // 反向 WS 服务对任何 HTTP 请求都回 401，NapCat 的 HTTP API 令牌不对也回 401，
+    // 靠「有没有客户端连进来」区分这两件事
+    result.mode = links.count !== null && links.count > 0 ? 'reverse' : 'auth'
+  } else {
+    result.mode = 'http'
+  }
+  if (result.mode === 'reverse') {
+    if (links.count === null) {
+      result.hint = '反向 WebSocket 服务在跑（这个端口不收 HTTP），客户端数暂时查不到'
+    } else if (links.count > 0) {
+      result.online = true
+      result.hint = `反向 WebSocket 已连上 ${links.count} 个客户端`
+    } else {
+      result.hint = '反向 WebSocket 服务在跑，但还没有客户端连进来'
+    }
+    result.error = result.online ? '' : result.hint
+    return result
   }
+  result.error = `端口有响应但 ${status === 401 ? '要求鉴权' : `回的是 HTTP ${status}`}`
+  result.hint =
+    status === 401
+      ? 'HTTP 401：多半是 accessToken 和对面配的不一致；如果对面只开反向 WebSocket，把探测方式改成「反向 WebSocket」'
+      : `HTTP ${status}：这个端口上跑的可能不是 OneBot 接口`
+  return result
 }
 
 /* ------------------------------------------------------------------ */
@@ -2218,6 +2437,7 @@ function launchNapcat(cfg, reason = '') {
       writeLock(cfg)
       state.lastLaunchAt = Date.now()
       state.launchCount += 1
+      state.launchFails += 1
       state.phase = 'launching'
       state.scanSince = 0
       state.lastError = ''
@@ -2275,6 +2495,7 @@ function launchNapcat(cfg, reason = '') {
   writeLock(cfg)
   state.lastLaunchAt = Date.now()
   state.launchCount += 1
+  state.launchFails += 1
   state.phase = 'launching'
   state.scanSince = 0
   state.lastError = ''
@@ -2361,12 +2582,23 @@ async function tick(cfg) {
   const health = await probe(cfg)
 
   if (health.online) {
-    if (state.phase !== 'online') log(cfg, `ONLINE: ${health.nickname} (${health.userId})`)
+    if (state.phase !== 'online') {
+      const who =
+        health.nickname || health.userId
+          ? `${health.nickname} (${health.userId})`
+          : health.mode === 'reverse'
+            ? '反向 WebSocket 已连接'
+            : '已连接'
+      log(cfg, `ONLINE${health.mode === 'reverse' ? '[reverse]' : ''}: ${who}`)
+    }
     state.phase = 'online'
     state.lastOnlineAt = Date.now()
     state.lastError = ''
     state.scanSince = 0
     state.scanRetries = 0
+    // 真连上了就把失败计数清掉，下次出事重新给足宽限
+    state.launchFails = 0
+    state.reverseRetries = 0
     const bridge = bridgeAge(cfg)
     if (bridge.ageSec !== null && bridge.ageSec > cfg.bridgeStaleSec) {
       log(cfg, `WARN bridge state stale ${bridge.ageSec}s (${bridge.path}) —— 桥接可能卡住`)
@@ -2390,6 +2622,8 @@ async function tick(cfg) {
       nickname: health.nickname,
       userId: health.userId,
       port: cfg.onebotPort,
+      mode: health.mode,
+      clients: health.clients,
       bridge,
       launches: state.launchCount,
       dedupes: state.dedupeCount,
@@ -2442,10 +2676,116 @@ async function tick(cfg) {
     return { phase: state.phase, health, procs, deduped: true, launched }
   }
 
+  const hasProcess = procs.boot > 0 || procs.qq > 0
+
+  /*
+   * 反向 WebSocket（dsh-onebot-qq 这类插件占着端口，NapCat 反过来连进去）：
+   * 这种部署下 HTTP 永远问不出「在线」，只能看端口上有没有客户端连进来。
+   * 关键的一条：进程在 + 端口有服务，就别杀 —— 老版本在这儿一路判离线，无限重拉。
+   */
+  if (health.mode === 'reverse' && hasProcess) {
+    if (health.clients === null) {
+      // 客户端数查不到：模糊信息不杀人，先按在线处理，日志里留一句
+      if (state.phase !== 'online') log(cfg, 'REVERSE: 查不到反向 WS 客户端数，按「在线」处理（不重启）')
+      state.phase = 'online'
+      state.lastOnlineAt = Date.now()
+      state.lastError = ''
+      state.launchFails = 0
+      writeSnapshot(cfg, {
+        phase: state.phase,
+        online: true,
+        mode: health.mode,
+        clients: null,
+        procs,
+        port: cfg.onebotPort,
+        updatedAt: new Date().toISOString(),
+      })
+      return { phase: state.phase, health, procs }
+    }
+    const waitedSec = state.lastLaunchAt ? Math.round((Date.now() - state.lastLaunchAt) / 1000) : 0
+    const overStuck = state.lastLaunchAt ? Date.now() - state.lastLaunchAt > cfg.stuckSec * 1000 : true
+    if (overStuck && state.reverseRetries < 2) {
+      state.reverseRetries += 1
+      log(
+        cfg,
+        `REVERSE-WAIT ${waitedSec}s 端口上还没有客户端连进来 → 温和重拉一次 ` +
+          `(${state.reverseRetries}/2)。若反复这样，检查 NapCat 里的反向 WS 地址是不是 ` +
+          `ws://127.0.0.1:${cfg.onebotPort}（令牌要对上 accessToken）`,
+      )
+      const cleaned = await killNapcat(cfg)
+      if (cleaned) {
+        await sleep(1200)
+        launchNapcat(cfg, 'reverse-wait')
+      } else {
+        log(cfg, 'REVERSE-WAIT: 旧链没清干净，先不拉新链')
+      }
+      writeSnapshot(cfg, {
+        phase: 'launching',
+        online: false,
+        mode: health.mode,
+        procs,
+        relaunched: cleaned,
+        updatedAt: new Date().toISOString(),
+      })
+      return { phase: 'launching', health, procs, relaunched: cleaned }
+    }
+    const before = state.phase
+    state.phase = overStuck ? 'reverse-giveup' : 'reverse-wait'
+    state.lastError = health.hint || health.error
+    if (before !== state.phase) {
+      if (state.phase === 'reverse-giveup') {
+        log(
+          cfg,
+          `REVERSE-GIVEUP: ${waitedSec}s 里 NapCat 一直没连上反向 WS，重拉 ${state.reverseRetries} 次也没用。` +
+            `去 NapCat 配置里把「反向 WebSocket」地址填成 ws://127.0.0.1:${cfg.onebotPort}` +
+            '（令牌对上 accessToken），改完把设置里的「在线探测方式」留 auto 就行。',
+        )
+      } else {
+        log(cfg, `REVERSE-WAIT: ${health.hint || '等 NapCat 连反向 WS'}（不重启，等它自己连）`)
+      }
+    }
+    writeSnapshot(cfg, {
+      phase: state.phase,
+      online: false,
+      mode: health.mode,
+      clients: health.clients,
+      procs,
+      port: cfg.onebotPort,
+      updatedAt: new Date().toISOString(),
+    })
+    return { phase: state.phase, health, procs }
+  }
+
+  /*
+   * 端口肯回 HTTP，但回的是 401 或别的状态：说明有服务在听、NapCat 进程也在。
+   * 这时候「杀掉重拉」什么也解决不了（令牌不对、或者端口被别的程序占着），
+   * 单独报出来，别再掉进 STUCK 那条死循环。
+   */
+  if (health.portAlive && health.mode !== 'reverse' && hasProcess) {
+    const before = state.phase
+    state.phase = health.mode === 'auth' ? 'need-token' : 'port-busy'
+    state.lastError = health.error || health.hint
+    if (before !== state.phase) {
+      log(cfg, `${state.phase.toUpperCase()}: ${health.error} —— ${health.hint}（不重启）`)
+    }
+    writeSnapshot(cfg, {
+      phase: state.phase,
+      online: false,
+      mode: health.mode,
+      status: health.status,
+      procs,
+      port: cfg.onebotPort,
+      updatedAt: new Date().toISOString(),
+    })
+    return { phase: state.phase, health, procs }
+  }
+
   // ② 完全没有进程：拉起（带宽限期 + 跨进程锁）
   if (procs.boot === 0 && procs.qq === 0) {
     const since = Date.now() - state.lastLaunchAt
-    if (since < cfg.launchGraceSec * 1000) {
+    // 连续拉不起来就别每轮的宽限期都硬等一遍：2 的幂放大，最多 8 倍
+    const backoff = Math.min(2 ** Math.min(state.launchFails, 3), 8)
+    if (since < cfg.launchGraceSec * backoff * 1000) {
       state.phase = 'launching'
       writeSnapshot(cfg, { phase: state.phase, online: false, procs, launches: state.launchCount })
       return { phase: state.phase, health, procs }
@@ -2643,6 +2983,13 @@ function registerTools(ctx, cfg) {
                 onebot: {
                   port: cfg.onebotPort,
                   online: health.online,
+                  /** http / reverse / auth / http / process / dead —— 反向 WS 时看这个 */
+                  mode: health.mode,
+                  portAlive: health.portAlive,
+                  httpStatus: health.status,
+                  /** 反向 WS 模式下端口上连进来的客户端数（null = 查不到） */
+                  clients: health.clients,
+                  hint: health.hint,
                   nickname: health.nickname,
                   user_id: health.userId,
                   error: health.error,
@@ -2673,7 +3020,21 @@ function registerTools(ctx, cfg) {
                 logTail: tail,
                 note: health.online
                   ? '在线。若 QQ 里还是没回音，问题在 dsh-qq-bridge 那一侧（绑定/试运行开关）。'
-                  : qr && qr.ageSec <= cfg.qrFreshSec
+                  : health.mode === 'reverse'
+                    ? health.clients === null
+                      ? '反向 WebSocket 模式：端口是反向 WS 服务在听（HTTP 问不出在线），客户端数还查不到——按在线处理，不会重启。'
+                      : '反向 WebSocket 模式：端口活着，但还没有客户端连进来。让 NapCat 把反向 WS 地址填成 ws://127.0.0.1:' +
+                        String(cfg.onebotPort) +
+                        '（令牌对上 accessToken）；超过 stuckSec 才会温和重拉，最多两次。'
+                    : health.mode === 'auth'
+                      ? '端口有响应但要求鉴权（HTTP ' +
+                        String(health.status) +
+                        '）：多半是 accessToken 跟 NapCat（或反向 WS 服务）里填的不一致。不会重启，先把令牌对一下。'
+                      : health.portAlive
+                        ? '端口活着但回的不是 OneBot 接口（HTTP ' +
+                          String(health.status) +
+                          '）：看看是不是别的程序占着这个端口。不会重启。'
+                        : qr && qr.ageSec <= cfg.qrFreshSec
                     ? passwordActive(cfg)
                       ? '离线，且在等扫码——但「记住密码」是开着的：看一眼日志里“快速登录错误”后面是不是仍回退到二维码（密码登录可能被腾讯要求验证）。'
                       : '离线，且二维码是新的：需要手机扫码（或在设置里打开「记住密码」让 NapCat 自己用密码登录）。文件在 qrCopyPath。'
@@ -2856,6 +3217,7 @@ function publicConfig(cfg) {
     passwordActive: passwordActive(cfg),
     onebotPort: cfg.onebotPort,
     accessToken: cfg.accessToken,
+    probeMode: cfg.probeMode,
     procPathMatch: cfg.procPathMatch,
     probeIntervalSec: cfg.probeIntervalSec,
     launchGraceSec: cfg.launchGraceSec,
@@ -3020,6 +3382,12 @@ async function uiState(cfg, options = {}) {
       enabled: cfg.enabled,
       phase: state.phase,
       online: !!health.online,
+      /** http / reverse / auth / http-odd / process / dead —— 设置页据此显示「反向 WS」那套词 */
+      mode: health.mode || '',
+      portAlive: !!health.portAlive,
+      portStatus: health.status || 0,
+      clients: health.clients,
+      hint: health.hint || '',
       nickname: health.nickname || '',
       userId: health.userId || 0,
       error: health.error || '',
@@ -3069,8 +3437,12 @@ function uiStateFull(cfg) {
 
 /** 保存配置：写文件 → 重新解析 → 热应用（不用重启 DSH） */
 function saveAndApply(ctx, patch) {
-  const home = dshHome()
-  const fileCfg = { ...readConfigFile(home) }
+  // ⚠ 必须读写的都是 keeperDir()：resolveConfig 读的是 <keeperDir>/config.json。
+  // 2.7.0 把配置收进 keeperDir 时只改了「读」，这两行还留着 dshHome()，
+  // 于是 2.7.0~2.7.2 的「保存设置」全写进了 ~/.dsh/config.json —— 谁都不读它。
+  // 表现：设置页点保存/点「用这个」之后，值立刻弹回空。
+  const dir = keeperDir()
+  const fileCfg = { ...readConfigFile(dir) }
   for (const [key, value] of Object.entries(patch || {})) {
     if (!Object.prototype.hasOwnProperty.call(DEFAULTS, key)) continue
     if (key === 'quickPassword') {
@@ -3098,7 +3470,7 @@ function saveAndApply(ctx, patch) {
     }
     fileCfg[key] = value == null ? '' : String(value).trim()
   }
-  const written = writeConfigFile(home, fileCfg)
+  const written = writeConfigFile(dir, fileCfg)
   const prev = state.cfg
   const next = resolveConfig(state.patchConfig || {})
   state.cfg = next
@@ -3190,11 +3562,12 @@ async function doAction(ctx, cfg, action, payload) {
     }
     case 'clearPassword': {
       // 把密码从本机彻底删掉：配置文件两条 + 中间层 bat，再让任务回到不带密码的样子
-      const home = dshHome()
-      const fileCfg = { ...readConfigFile(home) }
+      // 同样必须落在 keeperDir() 的 config.json 上，否则删的是一份没人读的文件（见 saveAndApply 注释）
+      const dir = keeperDir()
+      const fileCfg = { ...readConfigFile(dir) }
       fileCfg.rememberPassword = false
       fileCfg.quickPassword = ''
-      writeConfigFile(home, fileCfg)
+      writeConfigFile(dir, fileCfg)
       const next = resolveConfig(state.patchConfig || {})
       state.cfg = next
       removeEnvBat(next)
@@ -3422,6 +3795,8 @@ export const __internals = {
   procRoot,
   probe,
   probeProcs,
+  portClients,
+  PROBE_MODES,
   qrInfo,
   bridgeAge,
   launchNapcat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-napcat-keeper",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "description": "发现没有能够随着dsh打开自动启动napcat的插件，遂使用大肥鱼制作此插件，建议搭配Yuuyuko-uu的dsh-qq-bridge使用~",
   "type": "module",
   "main": "lib/index.js",
@@ -24,6 +24,8 @@
     "check:fix": "node scripts/check-manifest.mjs --fix",
     "smoke:client": "node scripts/smoke-client.mjs",
     "selftest:scan": "node scripts/selftest-scan.mjs",
+    "selftest:save": "node scripts/selftest-save.mjs",
+    "selftest:probe": "node scripts/selftest-probe.mjs",
     "selftest:setup": "node scripts/selftest-setup.mjs"
   },
   "keywords": [

package/scripts/selftest-probe.mjs

@@ -0,0 +1,186 @@
+/**
+ * 「在线探测」回归自检。
+ *
+ * 守的是这次适配反向 WebSocket 的那个坑：老版本 postOneBot 只看 body 不看状态码，
+ * 于是 dsh-onebot-qq 之类反向 WS 服务占着端口时（HTTP 换来 401/426），
+ * 一律被当成「端口不通」→ 卡死判定 → 杀掉重拉 → 无限循环。
+ *
+ * 现在 probe() 要能把这几种情况分清楚：
+ *   200 OneBot JSON → online / http
+ *   426              → reverse（端口只收 WebSocket）
+ *   401              → auth（令牌不对）或 reverse（有客户端连进来时）
+ *   端口没人听        → dead
+ *   probeMode=process→ 直接不碰端口
+ *
+ * 全程在本地环回上起假服务器，端口用临时的，不碰真配置、不碰真 NapCat。
+ *   node scripts/selftest-probe.mjs
+ */
+import http from 'node:http'
+import net from 'node:net'
+import { spawn } from 'node:child_process'
+
+let pass = 0
+let fail = 0
+const ok = (cond, name, extra = '') => {
+  if (cond) {
+    pass += 1
+    console.log(`  ✓ ${name}`)
+  } else {
+    fail += 1
+    console.log(`  ✗ ${name}${extra ? '  — ' + extra : ''}`)
+  }
+}
+
+const loadInternals = async () => (await import('../lib/index.js?t=' + Date.now())).__internals
+
+/** 起一个假服务器，返回 { port, close } */
+const serve = (handler) =>
+  new Promise((resolve) => {
+    const srv = http.createServer(handler)
+    srv.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: srv.address().port,
+        close: () => new Promise((r) => srv.close(r)),
+      })
+    })
+  })
+
+/** 找一个没人用的端口（开着再关掉），用来模拟「端口没开」 */
+const deadPort = () =>
+  new Promise((resolve) => {
+    const srv = net.createServer()
+    srv.listen(0, '127.0.0.1', () => {
+      const port = srv.address().port
+      srv.close(() => resolve(port))
+    })
+  })
+
+/** 起一个孩子进程，朝 port 建一条常连接（模拟 NapCat 反向连进来） */
+const connectAndHold = (port) => {
+  const code =
+    `const net=require('net');` +
+    `const s=net.connect(${port},'127.0.0.1',()=>{process.stdout.write('up\\n')});` +
+    's.on("error",()=>{});' +
+    'setInterval(()=>{},1000)'
+  const child = spawn(process.execPath, ['-e', code], { stdio: 'ignore', windowsHide: true })
+  return {
+    child,
+    up: () => new Promise((r) => setTimeout(r, 900)),
+    stop: () => {
+      try {
+        child.kill()
+      } catch {}
+    },
+  }
+}
+
+const { probe, portClients, PROBE_MODES } = await loadInternals()
+
+/* 1. 普通 NapCat HTTP 接口 ------------------------------------------------- */
+console.log('1) 端口上是正常的 OneBot HTTP 接口')
+let port1
+{
+  const srv = await serve((req, res) => {
+    res.writeHead(200, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ status: 'ok', retcode: 0, data: { user_id: 10086, nickname: '测试号' } }))
+  })
+  port1 = srv.port
+  const health = await probe({ onebotPort: port1, accessToken: '', probeMode: 'auto' })
+  ok(health.online === true, '判为在线')
+  ok(health.mode === 'http', 'mode = http', health.mode)
+  ok(health.status === 200, '抓到 HTTP 200', String(health.status))
+  await srv.close()
+}
+
+/* 2. 只收 WebSocket 的端口：426，且没人连 -------------------------------- */
+console.log('\n2) 端口只收 WebSocket（426）、还没有客户端连进来')
+let port2
+{
+  const srv = await serve((req, res) => {
+    res.writeHead(426, { 'content-type': 'text/plain' })
+    res.end('Upgrade Required')
+  })
+  port2 = srv.port
+  const health = await probe({ onebotPort: port2, accessToken: '', probeMode: 'auto' })
+  ok(health.online === false, '没客户端时不判在线')
+  ok(health.mode === 'reverse', 'mode = reverse', health.mode)
+  ok(health.portAlive === true, '认得出「端口是活的」', JSON.stringify(health.portAlive))
+  ok(health.status === 426, '抓到 HTTP 426', String(health.status))
+  const links = await portClients({ onebotPort: port2 }, 0)
+  ok(links.count === 0 || links.count === null, '客户端数 = 0 或查不到（不是 1）', String(links.count))
+  await srv.close()
+}
+
+/* 3. 426 + 真有客户端连进来 → 反向 WS 在线 -------------------------------- */
+console.log('\n3) 反向 WS：端口上有客户端连进来了')
+{
+  const srv = await serve((req, res) => {
+    res.writeHead(426, { 'content-type': 'text/plain' })
+    res.end('Upgrade Required')
+  })
+  const client = connectAndHold(srv.port)
+  await client.up()
+  const health = await probe({ onebotPort: srv.port, accessToken: '', probeMode: 'auto' })
+  ok(health.mode === 'reverse', 'mode = reverse', health.mode)
+  ok(health.online === true, '有客户端就判在线')
+  ok(health.clients !== null && health.clients >= 1, '数到了客户端', String(health.clients))
+  client.stop()
+  await srv.close()
+}
+
+/* 4. 401：可能是反向 WS 服务，也可能是令牌不对 --------------------------- */
+console.log('\n4) 端口回 401')
+{
+  const srv = await serve((req, res) => {
+    res.writeHead(401, { 'content-type': 'text/plain' })
+    res.end('Unauthorized')
+  })
+  const health = await probe({ onebotPort: srv.port, accessToken: '', probeMode: 'auto' })
+  ok(health.mode === 'auth', '没客户端时判 auth（多半是令牌不对）', health.mode)
+  ok(health.online === false, '不判在线')
+  ok(health.portAlive === true, '但仍认得出端口是活的（所以不会去杀进程）')
+  ok(String(health.hint || '').includes('401'), '给得出 401 的提示', health.hint)
+  await srv.close()
+}
+
+/* 5. 端口没开 ------------------------------------------------------------ */
+console.log('\n5) 端口没人听')
+{
+  const port = await deadPort()
+  const health = await probe({ onebotPort: port, accessToken: '', probeMode: 'auto' })
+  ok(health.online === false, '不判在线')
+  ok(health.mode === 'dead', 'mode = dead', health.mode)
+  ok(health.portAlive === false, 'portAlive = false')
+  ok(health.status === 0, '没有 HTTP 状态码', String(health.status))
+}
+
+/* 6. probeMode 的几种强制值 --------------------------------------------- */
+console.log('\n6) probeMode 强制值')
+{
+  const srv = await serve((req, res) => {
+    res.writeHead(426)
+    res.end('Upgrade Required')
+  })
+  const asProcess = await probe({ onebotPort: srv.port, accessToken: '', probeMode: 'process' })
+  ok(asProcess.mode === 'process', 'process：连端口都不看', asProcess.mode)
+  const asHttp = await probe({ onebotPort: srv.port, accessToken: '', probeMode: 'http' })
+  ok(asHttp.mode === 'auth' || asHttp.mode === 'http', 'http：不认反向（判成 auth/http）', asHttp.mode)
+  const asReverse = await probe({ onebotPort: srv.port, accessToken: '', probeMode: 'reverse' })
+  ok(asReverse.mode === 'reverse', 'reverse：直接按反向 WS 处理', asReverse.mode)
+  const bad = await probe({ onebotPort: srv.port, accessToken: '', probeMode: '乱填' })
+  ok(bad.mode === 'reverse', '乱填的 probeMode 退回 auto（这里应判成 reverse）', bad.mode)
+  await srv.close()
+}
+
+/* 7. 归一化 -------------------------------------------------------------- */
+console.log('\n7) 配置归一化')
+{
+  const { normalizeConfig } = await loadInternals()
+  ok(normalizeConfig({ probeMode: 'REVERSE' }).probeMode === 'reverse', '大小写归一')
+  ok(normalizeConfig({ probeMode: '' }).probeMode === 'auto', '空值 → auto')
+  ok(normalizeConfig({ probeMode: 'xyz' }).probeMode === 'auto', '非法值 → auto')
+  ok(PROBE_MODES.has('auto') && PROBE_MODES.has('reverse'), 'PROBE_MODES 导出可用')
+}
+
+console.log(`\n结果：${pass} 通过，${fail} 失败`)
+process.exit(fail ? 1 : 0)

package/scripts/selftest-save.mjs

@@ -0,0 +1,100 @@
+/**
+ * 「保存设置」回归自检。
+ *
+ * 守的是 2.7.0 引入、2.7.3 修掉的那个 bug：saveAndApply 写的是 $DSH_HOME/config.json，
+ * 而所有读取都走 <keeperDir>/config.json，于是设置页点保存/点「用这个」之后值立刻弹回空。
+ *
+ * 全程在临时 DSH_HOME 里跑，不碰真实配置。
+ *   node scripts/selftest-save.mjs
+ */
+import { existsSync, mkdtempSync, readFileSync, readdirSync, utimesSync, writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+let pass = 0
+let fail = 0
+const ok = (cond, name, extra = '') => {
+  if (cond) {
+    pass += 1
+    console.log(`  ✓ ${name}`)
+  } else {
+    fail += 1
+    console.log(`  ✗ ${name}${extra ? ' — ' + extra : ''}`)
+  }
+}
+
+const freshHome = (tag) => {
+  const home = mkdtempSync(path.join(tmpdir(), `npk-save-${tag}-`))
+  process.env.DSH_HOME = home
+  return { home, dir: path.join(home, 'dsh-napcat-keeper') }
+}
+
+const loadInternals = async () => (await import('../lib/index.js?t=' + Date.now())).__internals
+
+const fakeCtx = { effect: (fn) => fn(), logger: null, tools: { register() {} } }
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+
+/* 1. 保存必须落到 keeperDir/config.json，回读一致 --------------------------- */
+console.log('1) saveAndApply 真的写进 keeperDir 了吗')
+{
+  const { home, dir } = freshHome('write')
+  const { resolveConfig, saveAndApply } = await loadInternals()
+  const target = 'D:/fake/NapCat.Shell'
+  const next = saveAndApply(fakeCtx, { shellDir: target, onebotPort: 3011 })
+  ok(next.shellDir === target, 'saveAndApply 返回值里就有新值', JSON.stringify(next.shellDir))
+  ok(existsSync(path.join(dir, 'config.json')), 'keeperDir/config.json 被写出来了')
+  ok(readJson(path.join(dir, 'config.json')).shellDir === target, '落盘内容对得上')
+  ok(!existsSync(path.join(home, 'config.json')), '根上没再冒出 config.json')
+  ok(resolveConfig({}).shellDir === target, '重新 resolveConfig 读回新值（重启 DSH 后也生效）')
+}
+
+/* 2. 老版本误写的那份要被认领回来 ------------------------------------------- */
+console.log('\n2) 认领 2.7.0~2.7.2 误写到根上的 config.json')
+{
+  const { home, dir } = freshHome('adopt')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(path.join(dir, 'config.json'), JSON.stringify({ shellDir: '', onebotPort: 3000 }, null, 2) + '\n')
+  // 根上那份是「用户最后一次点保存」的内容，比 keeper 的新
+  const stray = path.join(home, 'config.json')
+  writeFileSync(stray, JSON.stringify({ shellDir: 'E:/NapCat.Shell', onebotPort: 3000, launchAccount: '10001' }, null, 2) + '\n')
+  const old = (Date.now() - 60000) / 1000
+  utimesSync(path.join(dir, 'config.json'), old, old)
+
+  const { resolveConfig } = await loadInternals()
+  ok(resolveConfig({}).shellDir === 'E:/NapCat.Shell', '认领后读到的就是用户当初想存的那份')
+  ok(!existsSync(stray), '根上那份已归档，不会下次又被认领一遍')
+  const leg = readdirSync(path.join(dir, 'legacy'))
+  ok(leg.some((f) => f.startsWith('config.adopted-')), '原文留在 legacy/ 里（可回滚）', leg.join(','))
+}
+
+/* 3. keeper 更新时不许被根上那份覆盖 ---------------------------------------- */
+console.log('\n3) keeper 比根上新时不认领（别把新配置写旧）')
+{
+  const { home, dir } = freshHome('noadopt')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(path.join(dir, 'config.json'), JSON.stringify({ shellDir: 'F:/good', onebotPort: 3000, launchAccount: '1' }, null, 2) + '\n')
+  const stray = path.join(home, 'config.json')
+  writeFileSync(stray, JSON.stringify({ shellDir: 'G:/stale', onebotPort: 3000, launchAccount: '1' }, null, 2) + '\n')
+  const old = (Date.now() - 120000) / 1000
+  utimesSync(stray, old, old)
+
+  const { resolveConfig } = await loadInternals()
+  ok(resolveConfig({}).shellDir === 'F:/good', 'keeper 里的值没被旧文件顶掉')
+  ok(existsSync(stray), '不认领就不动它')
+}
+
+/* 4. 不是自家的 config.json 不许抢 ----------------------------------------- */
+console.log('\n4) 根上的 config.json 若不像插件的，一概不碰')
+{
+  const { home, dir } = freshHome('foreign')
+  mkdirSync(dir, { recursive: true })
+  const stray = path.join(home, 'config.json')
+  writeFileSync(stray, JSON.stringify({ theme: 'dark', language: 'zh-CN' }, null, 2) + '\n')
+  const { resolveConfig } = await loadInternals()
+  resolveConfig({})
+  ok(existsSync(stray), '别人的 config.json 原样留着')
+  ok(!existsSync(path.join(dir, 'config.json')), '也没凭空造一份 keeper 配置')
+}
+
+console.log(`\n结果：${pass} 通过，${fail} 失败`)
+process.exit(fail ? 1 : 0)

package/scripts/smoke-client.mjs

@@ -41,6 +41,7 @@ function render() { idx = 0; return Section({}); }
 function collect(tree) {
   const buttons = [];
   const boxes = [];
+  const selects = [];
   const texts = [];
   (function walk(n) {
     if (n === null || n === undefined || n === false) return;
@@ -51,10 +52,16 @@ function collect(tree) {
       if (n.type === 'input' && n.props && n.props.type === 'checkbox') {
         boxes.push({ name: String(n.props.name || ''), checked: Boolean(n.props.checked), disabled: Boolean(n.props.disabled) });
       }
+      if (n.type === 'select') {
+        selects.push({
+          value: String(n.props && n.props.value),
+          options: n.children.filter((c) => c && c.__el && c.type === 'option').map((o) => String(o.props.value)),
+        });
+      }
       n.children.forEach(walk);
     }
   })(tree);
-  return { buttons, boxes, text: texts.join(' ') };
+  return { buttons, boxes, selects, text: texts.join(' ') };
 }
 
 render(); // 第一次：态=null 的 loading 分支
@@ -121,6 +128,25 @@ check('三块盘三个按钮', ['扫 C:', '扫 D:', '扫 E:'].every((b) => base.
 check('盘数提示 3 块', /读到 3 块盘：C:、D:、E:/.test(base.text));
 check('shellDir 指向分盘扫描', base.text.includes('不想手填就用上面「分盘扫描」'));
 
+// 反向 WebSocket：下拉得在、默认 auto、四项齐；runtime 报反向态时状态条得换词
+const modeSel = base.selects[0];
+check('有「在线探测方式」下拉，默认 auto', Boolean(modeSel) && modeSel.value === 'auto', JSON.stringify(modeSel));
+check('下拉四项齐全', Boolean(modeSel) && ['auto', 'http', 'reverse', 'process'].every((v) => modeSel.options.includes(v)),
+  JSON.stringify(modeSel && modeSel.options));
+states[0].runtime.mode = 'reverse';
+states[0].runtime.portStatus = 426;
+states[0].runtime.clients = 2;
+const rev = collect(render());
+check('反向 WS 时状态条说「反向 WS 已连接」', rev.text.includes('反向 WS 已连接'));
+check('反向 WS 时显示客户端数', /客户端 2/.test(rev.text));
+check('反向 WS 时显示探测方式与 HTTP 状态', rev.text.includes('反向 WebSocket') && rev.text.includes('HTTP 426'));
+states[0].runtime.mode = 'auth';
+states[0].runtime.online = false;
+states[0].runtime.portStatus = 401;
+delete states[0].runtime.clients;
+const auth = collect(render());
+check('401 时显示「端口要求鉴权」', auth.text.includes('端口要求鉴权'));
+
 // 盘数跟 drives 走：1 块 / 5 块 / 0 块
 for (const drives of [['C:'], ['C:', 'D:', 'E:', 'F:', 'G:'], []]) {
   states[0].drives = drives;