dsh-chain-check

dsh-chain-check

一条命令看清 DSH → 桥接 → SnowLuma → QQ 这条链断在哪一段。

$ node check.mjs

  ✓  DSH 进程             8 个进程
  ✓  桥接（surfcore）      127.0.0.1:3100 在听
  ✓  SnowLuma / OneBot    在线：阿砚（3574232603）
  ✓  preset「qq-chat-v2」  desktop（bundles 里有 surfcore）
  ✓  最近的唤醒失败        最近 400 行里没有唤醒失败
  ✓  最后一条消息          发出：17:10:32 … 成功 1/1 条

  全通。

---

两种用法

一、当插件装（会话里多一个 chain_check 工具，AI 自己就能查）：

dsh plugin --profile <你的 profile> add github:wuying1630/dsh-chain-check

装上只做一件事：注册 chain_check。不常驻、不改你的配置、不写文件。

二、不装插件直接跑——链已经断了的时候更推荐这条，因为那时候装插件本身可能就是断的那一环：

node check.mjs

两条路跑的是同一个脚本，不会出现两个版本说法不一致。

三、查完顺手修——只有两种情况能安全自动修：

node check.mjs --fix

• DSH 换了端口：surfcore/config.json 的 dsh.baseUrl 还写着旧端口 → 改成当前探到的那个
• 桥接没在跑：就是没在跑而已 → 拉起来

只修这两样，因为只有它们的「对」是机器能自己判断的。修完会打印修了什么，要再跑一次不带 --fix 的确认。

故意不修的：preset 没注册（得改 profile 的 bundles，改错了 DSH 起不来）、配置文件语法坏了（得人看）。

反面教材写在 lib/fix.js 注释里：别按「node 进程数 > 1」判断 SnowLuma 重复。正常跑着就是两个进程（launcher + 主进程），照这个杀会把正在服务的那份干掉，桥接立刻 code=1006，QQ 全断——比它想修的问题还严重。踩过一次。

它解决的是哪个疼

链子断了，表面上都长一个样：它不回话。

实际这一周断过四种，现象一模一样，修法完全不同：

真正断在哪	现象	人第一反应	真实原因
桥接进程没了	不回话	「它不理我了」	3100 没人监听
DSH 重启后 preset 没注册	不回话	「它生气了？」	桥接拒绝建会话，日志刷 不在 DSH 可用清单
DSH 换了端口	不回话	「是不是封号了」	桥接还对着旧端口说话
拿错令牌文件	不回话	「QQ 掉线了吧」	机器上两份 onebot_*.json，读到了主人号那份

人只能靠猜。这个工具把「猜」换成「看」。

它不是什么（先说清楚，省得误会）

• 装不装都行。 装了多一个工具；不装也能 node check.mjs 直接跑，不用重启 DSH。

  为什么不打包成插件：链路断的时候，装插件这件事本身可能就是断的那一环。一个救急工具，不能要求你先修好它才能跑。

• 不是监控。 跑一次看一次，不常驻、不写守护进程、不发通知。
• 默认只读，有一个明确的例外。 平时只读日志、只读配置、只探端口，不启动、不杀进程、不写配置；装成插件后注册的 chain_check 工具本身永远是只读的。唯一的例外是 CLI 的 --fix（见上文「查完顺手修」）：它只做两件能安全自动修的事——把 surfcore/config.json 的 dsh.baseUrl 对齐到当前端口、把没在跑的桥接拉起来。

快速开始

# 1. 有 Node 18+ 就行，不用 npm install
node --version

# 2. 跑
node check.mjs

# 3. 看 ✗ 后面那行 → 它会直接告诉你怎么修

Windows 上中文如果乱码，先 chcp 65001，或者用 Windows Terminal。

装到别人机器上要对的三件事

1. Node 18 以上。脚本用了内置 fetch 和 AbortSignal.timeout；版本不够会直接说一句人话退出，不甩 SyntaxError。
2. 别在 GBK 控制台里看。脚本会自己检测代码页并提示。
3. 它假定的是这套栈：DSH + surfcore 桥接 + 一个 OneBot 实现。
   • 用 NapCat / AstrBot 也行：在 chain.config.json 里直接给 onebotUrl、onebotToken，就不需要 SnowLuma 的目录结构。
   • 没有 surfcore 桥接的话，第 2、4 项会报不通，第 1、3 项照样有用。

只在一台 Windows 上实测过。 Linux / macOS 的分支（pgrep / ss）写是写了，没跑过——别当成已验证的东西。

用在 NapCat / AstrBot 上

先说清楚：这个工具不是只能配 SnowLuma。 第 3 项查的是标准 OneBot 接口 get_login_info，谁实现都行。但这两套栈断的东西不一样，别指望它全查。

NapCat（最省事）

1. 在 NapCat 的 WebUI 里开 HTTP 服务器（网络配置 → HTTP 服务器，比如 127.0.0.1:3000），设一个 access token。
2. 在 chain.config.json 里指过去：

{
  "onebotUrl": "http://127.0.0.1:3000",
  "onebotToken": "你设的那个 token",
  "skipSurfcore": true
}

3. 跑 node check.mjs。第 3 项会直接告诉你 QQ 在不在线、登的是哪个号。

skipSurfcore: true 是必须的——你没有 surfcore 桥接，不写的话第 2、4、5、6 项会报不通，那是误报，会把人带沟里。

NapCat 这条链它查得到什么：

• ✓ 协议端进程/端口通不通
• ✓ QQ 掉没掉线（最常断的一环）
• ✓ token 对不对
• ✗ 消息为什么没送到 AI（那是 DSH 那一侧，跟协议端无关）
• ✗ 群权限 / 被禁言 / 被踢（平台侧，本机看不出）

AstrBot

AstrBot 自带 QQ 适配（aiocqhttp），默认走 WebSocket，通常没有 HTTP 接口。所以：

• 如果开了 HTTP：同 NapCat，填 onebotUrl + onebotToken + skipSurfcore: true。
• 如果没开 HTTP：把 skipOneBot 也设成 true。这项就跳过，不再假装能验。

{
  "skipOneBot": true,
  "skipSurfcore": true
}

这时候它还剩什么用？第 1 项（DSH 进程在不在、端口有没有在听）。别的都查不了——工具会明确写「已按配置跳过」，不会给你一个假的 ✓。

一张表：你的栈能查哪几项

你的栈	1 DSH	2 桥接	3 QQ 在线	4 preset	5 唤醒失败	6 最后一条消息
DSH + surfcore + SnowLuma	✓	✓	✓	✓	✓	✓
DSH + surfcore + NapCat	✓	✓	✓（填 onebotUrl）	✓	✓	✓
DSH + AstrBot（无 HTTP）	✓	skip	skip	skip	skip	skip
纯 NapCat，没有 DSH	—	skip	✓	skip	skip	skip

没有 DSH 的话，它就不是给你用的——第 1 项查的就是 DSH。别装错了。

六项检查

#	检查	抓什么
1	DSH 进程	进程在不在，监听哪些端口
2	桥接	端口通不通
3	SnowLuma / OneBot	端口通不通，QQ 在不在线（每份 onebot_*.json 都试）
4	preset 注册	profile 的 dsh.profile.bundles 里有没有 surfcore
5	最近的唤醒失败	最近 400 行日志里有没有硬故障
6	最后一条消息	最近一次发出 / 唤醒是什么时候

每项只给三样：通没通 / 一句人话说清是什么 / 怎么修。

退出码：全通 0，有不通 1。接进别的脚本很方便：

node check.mjs --json | jq '.results[] | select(.ok==false)'

配置

全部可省。省了就走「环境变量 → chain.config.json → 常见位置猜」；用猜的会打印出来，不让人误以为是自己配的。

{
  "surfcoreDir": "D:/surfcore",
  "snowlumaDir": "D:/SnowLuma",
  "agentPreset": "qq-chat-v2",
  "processNames": ["DeepSeek", "dsh"],
  "onebotUrl": "http://127.0.0.1:3000",
  "onebotToken": "（可选）",
  "skipOneBot": false,
  "skipSurfcore": false
}

环境变量：DSH_HOME / SURFCORE_HOME / SNOWLUMA_HOME。

---

给大肥鱼（AI 鱼）看的注意须知

你好。你多半是被主人一句「你跑一下那个检查」叫来的。几条实话：

1. 这个脚本的输出是给人看的，不是给你「再加工」的。 主人要看的是「断在哪一段」。你可以复述，但别改写判定、别把 ✗ 说成「可能有点小问题」。

2. 看见 ✗，先把 → 那行原样交给主人，再动手。 里面有几步是要人点头的（重启 DSH、改 profile 配置）。不要自己改 package.json 的 bundles 然后不吭声——DSH 每次重启都会换端口，你改完不重起桥接，下一条消息照样丢。

3. 不要为了让它变绿而改标准。 这个脚本故意把「探针看不见端口」判成 ✓（说明里写清楚），也故意不算「忽略未授权会话」。 如果你发现某项一直红、你想把它调成绿——停。那是真断了。

4. 别拿它当日常心跳。 它是出问题时用的扳手，不是监护仪。每 30 分钟跑一次既没用又吵。

5. 它的日志关键词是从真实故障里长出来的，包括：

   • 裸的 401 不能当关键词（QQ 号 1584763401 里就有这三个数字）
   • 日志会滚动，必须连 bridge.log.1 一起读

   你要是想加新关键词，先问自己：这个字符串会不会在无关的行里出现。

---

给真人看的注意须知

什么时候用它：

• 明明收到消息了，它却像没看见 → 第 5、6 项
• 改完配置、装完插件之后它不说话了 → 第 4 项
• 电脑重启过 → 第 2 项 + DSH 换端口那条

它判不了的事（别指望）：

• 模型本身抽风、答非所问 → 链路是通的，这是内容问题
• 群权限、被禁言、被踢 → 那是平台侧，本机看不出
• 网络慢、偶尔延迟 → 单次快照看不出趋势

安全：

• 只读。不写配置、不启动进程、不杀进程。
• 不会打印任何令牌，只打印「用的是哪个文件」。

已知限制（写在明处）：

• 端口探测可能看不见。 沙箱或非交互会话里，Get-NetTCPConnection / netstat 只能看到寥寥几个监听口。这不是链子断了，是探针看不见——所以那一项不判失败。
• 日志会滚动。 只读 bridge.log 和 bridge.log.1，再往前查不到。
• Windows 优先。 Linux / macOS 分支未实测。

---

授权

MIT。随便改，出问题自己扛——它只读，不背锅。

它是谁写的

一条会被自己写的工具查错的鱼，在 Windows 上，2026 年 10 月。

第一版写完第二天就被它自己的检查抓出一个 bug（拿错令牌文件报 unauthorized，看着像 QQ 掉线）。