dsh-qiyu-stack 0.15.4 → 0.15.6

package/docs/status.md

@@ -6,10 +6,53 @@
 
 **能用了，也发出去了，但还没被陌生人在干净机器上验证过。**
 
-- npm：`dsh-qiyu-stack@0.15.3`（`latest`），`npx dsh-qiyu-stack preflight --json` 实测可跑
+- npm：`dsh-qiyu-stack@0.15.6`（`latest`）
 - GitHub：<https://github.com/aesfls/dsh-qiyu-stack>（公开，main）
 - 千语（爸爸本人的实例）：正常运行中，桥、NapCat、Docker 都通
 
+## 2026-10-23 第五轮：DSH 端口自动探测（v0.15.6）
+
+`qiyu.config.json` 里的 `dsh.port` 是某一次写下的快照，而 DSH 的端口会变
+（这台机器就从 64657 变到了 62853）。doctor 只信这个值，就会一直报
+「DSH 端口 64657 没人听」——不是故障，但会让人以为桥坏了。
+
+0.15.6 新增 `src/dsh-port.mjs`：
+
+1. 先试配置里的端口；不通再扫本机正在监听的端口（`netstat`）
+2. 按特征认，不猜：`/dsh-qq-bridge/state` 返回 `{"ok":true,...}` → DSH + 桥；
+   `/` 返回 401 且带 `dsh web authentication required` → DSH 在、桥没装
+3. **不写回配置**——端口下次还会变，写回去只会制造新的过期快照
+
+现在 doctor 会自动找到实际端口，输出里注明「是自动探测到的（配置里写的是 64657）」。
+
+## 2026-10-23 第四轮：验收命令也补上沙箱降级（v0.15.5）
+
+第三轮只修了 `preflight`，**验收命令 `doctor` 漏了**——在 workspace-write 下它照样报
+「装了 Docker，但引擎没起来」，`有失败: true`。而 AGENTS.md 写的验收标准是「不通必须为 0」，
+陌生人跑验收会永远看到 1 个失败。0.15.5 补上：
+
+1. `doctor` 接 `沙箱受限过()`：Docker / 容器 / 端口相关的 fail 降级成 `warn`，
+   标题加「沙箱限制，这条不可信」，并附一句「去用户终端或提权再验」
+2. `qr.mjs` 的 `docker cp` 改走 `跑()`（原来直连 `execFileSync`，沙箱里会假失败「拿不到二维码」）
+
+## 2026-10-23 第三轮：沙箱假阴性（重要）
+
+另一个会话在**默认沙箱**（workspace-write）里实测发现：`preflight` 报「这台机器上没有 Docker」，
+可机器上 Docker 装着、容器还在跑。
+
+**根因**（平台文档写明）：受限沙箱不允许程序开命名管道，所以任何
+`execFile/spawn` 抓输出（`stdio: 'pipe'`）都会 `EPERM`。而 qiyu 的每个 `跑()` 都靠抓输出，
+于是所有判断变成假阴性——这是 agent 路径上最危险的一类 bug，会让 agent 去让用户装一个已经装好的东西。
+
+**修法（v0.15.4）**：
+
+1. 新增 `src/run.mjs`：先试管道，`EPERM/EACCES/EPIPE` 时**改走「重定向到临时文件再读」**
+   （沙箱允许写工作区），并把这次运行标记为「沙箱受限过」
+2. `preflight` 在受限时**把 Docker/端口/Python 这类 fail 降级成 `warn`**，
+   标题加「沙箱限制，这条不可信」，并明确告诉 agent：别让用户重装，去他自己的终端或提权再验
+3. `AGENTS.md` 专门加了一节讲这个坑
+4. `AGENTS.md` 已进 npm 包（`files` 字段，0.15.4 起 80 个文件）
+
 ## 2026-10-23 第二轮补的（agent 入口）
 
 一个陌生人会话实测后提的问题，采纳了三条：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-qiyu-stack",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "description": "栖语栈：让一个智能体住进 QQ —— QQ 双向桥、长期记忆、心情、语音、作息，以及把 NapCat 部署这件事一次做对",
   "type": "module",
   "bin": {

package/src/doctor.mjs

@@ -9,7 +9,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { 读配置 } from './config.mjs'
-import { 跑 } from './run.mjs'
+import { 跑, 沙箱受限过 } from './run.mjs'
+import { 探测DSH } from './dsh-port.mjs'
 
 const 包根 = join(dirname(fileURLToPath(import.meta.url)), '..')
 
@@ -179,26 +180,42 @@ export async function doctor({ 只输出JSON = false, 跳过WebSocket = false }
   }
 
   // ---------- 7. DSH 桥 ----------
-  const 桥端口 = 配置.dsh.port
-  if (!桥端口) {
-    记('skip', '跳过 DSH 桥检查（没配端口）', 'DSH 的端口每台机器都不一样，所以默认不猜', '知道的话设环境变量 QIYU_DSH_PORT，或写进 qiyu.config.json 的 dsh.port')
-  } else if (await 端口通('127.0.0.1', 桥端口)) {
+  //
+  // DSH 的端口每次启动可能变，不能只信 qiyu.config.json 里的快照。
+  // 先试配置端口，再扫本机监听端口，按特征认（见 src/dsh-port.mjs）。
+  const 探测 = await 探测DSH({ 已知端口: 配置.dsh.port })
+  if (!探测) {
+    if (配置.dsh.port) {
+      记(
+        'warn',
+        `DSH 端口 ${配置.dsh.port} 没人听，也没自动找到`,
+        'DSH 可能没开，或者端口变了',
+        '先把 DSH 开起来再跑一次；开了还找不到，设环境变量 QIYU_DSH_PORT'
+      )
+    } else {
+      记('skip', '跳过 DSH 桥检查（没找到运行中的 DSH）', 'DSH 的端口每台机器都不一样，所以默认不猜', '把 DSH 开起来再跑一次；或者设 QIYU_DSH_PORT')
+    }
+  } else if (!探测.有桥) {
+    记('warn', `DSH 在 ${探测.端口}，但没看到 dsh-qq-bridge`, '', '确认 DSH 里装了 dsh-qq-bridge 插件')
+  } else {
     try {
-      const r = await 请求(`http://127.0.0.1:${桥端口}/dsh-qq-bridge/state`)
+      const r = await 请求(`http://127.0.0.1:${探测.端口}/dsh-qq-bridge/state`)
       if (r.json && r.json.NapCat状态) {
         const 状 = r.json.NapCat状态
-        if (状.用户) 记('ok', `DSH 桥认到：${状.昵称}（${状.用户}）`)
+        const 注 = 探测.来源 === '自动探测' ? `DSH 端口 ${探测.端口} 是自动探测到的（配置里写的是 ${配置.dsh.port || '空'}）` : ''
+        if (状.用户) 记('ok', `DSH 桥认到：${状.昵称}（${状.用户}）`, 注)
         else 记('warn', 'DSH 桥连不上 NapCat', JSON.stringify(状).slice(0, 160), '桥的 NapCat 地址/令牌和 qiyu.config.json 要一致')
       } else {
-        记('warn', `DSH 在 ${桥端口}，但没看到 dsh-qq-bridge`, '', '确认 DSH 里装了 dsh-qq-bridge 插件')
+        记('warn', `DSH 在 ${探测.端口}，但没看到 dsh-qq-bridge`, '', '确认 DSH 里装了 dsh-qq-bridge 插件')
       }
     } catch (错) {
       记('warn', 'DSH 桥查不到', String(错.message || 错), '')
     }
-  } else {
-    记('warn', `DSH 端口 ${桥端口} 没人听`, '', 'DSH 没开？或者端口不是这个：设 QIYU_DSH_PORT')
   }
 
+  // 给 JSON 输出用：探测到的端口优先，没探测到就退回配置里的值
+  const 桥端口 = 探测 ? 探测.端口 : Number(配置.dsh.port) || 0
+
   // ---------- 7.5 部署路径体检 ----------
   if (配置.napcat && 配置.napcat.dataDir) {
     const 目录 = String(配置.napcat.dataDir)
@@ -284,6 +301,33 @@ export async function doctor({ 只输出JSON = false, 跳过WebSocket = false }
     记('skip', '跳过模板体检', String(错.message || 错))
   }
 
+  // ---------- 沙箱兜底：读不到子进程输出时，别把「没装/没起」当成事实 ----------
+  //
+  // 受限沙箱不允许程序开管道，所有"跑条命令看输出"的判断都可能拿到空结果。
+  // 这时把 Docker / 容器 / 端口相关的 fail 降级成 warn——否则 agent 会把
+  // 「验收标准：不通必须为 0」理解成"装失败了"，去修一台根本没坏的机器。
+  if (沙箱受限过()) {
+    let 降级了 = 0
+    for (const x of 结果) {
+      if (x.级别 !== 'fail') continue
+      if (!/Docker|引擎|容器|端口/.test(x.标题)) continue
+      x.级别 = 'warn'
+      x.标题 = '沙箱限制，这条不可信：' + x.标题
+      x.怎么修 = '在用户自己的终端里跑 qiyu doctor 再确认一次；或者把这次会话提到 danger-full-access'
+      降级了++
+    }
+    if (降级了) {
+      结果.push({
+        级别: 'warn',
+        标题: '当前沙箱读不到子进程输出',
+        依据:
+          '受限沙箱不允许程序开管道（stdio: pipe 会 EPERM）。qiyu 已改用"重定向到文件再读"兜底，' +
+          '但个别命令仍可能失败，上面 ' + 降级了 + ' 条结论已降级。',
+        怎么修: '这类结论不能当真：让用户在自己终端跑一遍，或把会话权限提到 danger-full-access',
+      })
+    }
+  }
+
   // ---------- 输出 ----------
   const 有失败 = 结果.some((x) => x.级别 === 'fail')
 

package/src/dsh-port.mjs

@@ -0,0 +1,83 @@
+// 找 DSH 正在听的端口。
+//
+// 为什么需要这个：DSH 的端口不是固定的（每次启动可能换一个），
+// 而 qiyu.config.json 里的 dsh.port 是某一次写下来的快照 —— 过一天就旧了。
+// 只信配置会让 doctor 一直报「DSH 端口没人听」，人就会以为桥坏了。
+//
+// 认法（按特征，不猜）：
+//   · GET /dsh-qq-bridge/state → 200 且 {"ok":true,...}      → DSH + 桥都在
+//   · GET /                     → 401 "dsh web authentication required" → DSH 在，但桥没装
+import { 跑 } from './run.mjs'
+
+const 探测超时 = 350
+
+async function 取(端口, 路径) {
+  try {
+    const r = await fetch(`http://127.0.0.1:${端口}${路径}`, { signal: AbortSignal.timeout(探测超时) })
+    return { 状态: r.status, 文本: await r.text() }
+  } catch {
+    return null
+  }
+}
+
+/** 这个端口是不是 DSH？返回 { 端口, 有桥 } 或 null */
+async function 认一认(端口) {
+  const 桥 = await 取(端口, '/dsh-qq-bridge/state')
+  if (桥 && 桥.状态 === 200) {
+    try {
+      const j = JSON.parse(桥.文本)
+      if (j && j.ok === true) return { 端口, 有桥: true }
+    } catch {
+      // 不是 JSON，继续看根路径
+    }
+  }
+  const 根 = await 取(端口, '/')
+  if (根 && 根.状态 === 401 && /dsh web authentication required/i.test(根.文本)) {
+    return { 端口, 有桥: false }
+  }
+  return null
+}
+
+/** 本机正在听的端口（只听回环/通配地址，跳过系统端口） */
+function 听着的端口() {
+  const r = 跑('netstat', ['-ano', '-p', 'TCP'], 8000)
+  if (!r.ok) return []
+  const 端口们 = new Set()
+  for (const 行 of r.出.split(/\r?\n/)) {
+    const m = 行.match(/^\s*TCP\s+(\S+):(\d+)\s+\S+\s+LISTENING/i)
+    if (!m) continue
+    const 地址 = m[1]
+    const 端口 = Number(m[2])
+    if (!(地址 === '0.0.0.0' || 地址 === '127.0.0.1' || 地址 === '[::]' || 地址 === '[::1]')) continue
+    if (端口 < 1024) continue
+    端口们.add(端口)
+  }
+  return [...端口们].sort((a, b) => a - b)
+}
+
+/**
+ * 找 DSH。先试已知端口（配置里的），再扫本机监听端口。
+ * @param {{已知端口?: number, 并发?: number, 上限?: number}} 选项
+ * @returns {Promise<{端口:number, 有桥:boolean, 来源:'配置'|'自动探测'}|null>}
+ */
+export async function 探测DSH({ 已知端口 = 0, 并发 = 16, 上限 = 200 } = {}) {
+  const 已知 = Number(已知端口) || 0
+  if (已知) {
+    const 中 = await 认一认(已知)
+    if (中) return { ...中, 来源: '配置' }
+  }
+
+  // NapCat 的三个端口不用试；已知端口试过了也不重复
+  const 别试 = new Set([3000, 3001, 6099, 已知].filter(Boolean))
+  const 候选 = 听着的端口()
+    .filter((p) => !别试.has(p))
+    .slice(0, 上限)
+
+  for (let i = 0; i < 候选.length; i += 并发) {
+    const 批 = 候选.slice(i, i + 并发)
+    const 结果 = await Promise.all(批.map((p) => 认一认(p)))
+    const 中 = 结果.find(Boolean)
+    if (中) return { ...中, 来源: '自动探测' }
+  }
+  return null
+}

package/src/qr.mjs

@@ -2,10 +2,11 @@
 //
 // 约定：需要用户扫码时，不能只给一个路径（用户还得自己去找文件）。
 // 一律「复制出来 + 用系统默认看图程序打开 + 在终端里说清什么时候过期」。
-import { execFileSync, spawn } from 'node:child_process'
+import { spawn } from 'node:child_process'
 import { resolve } from 'node:path'
 import { statSync } from 'node:fs'
 import { 读配置 } from './config.mjs'
+import { 跑 } from './run.mjs'
 
 export function 打开文件(路径) {
   try {
@@ -47,15 +48,11 @@ export async function qr() {
 
   const 目标 = resolve(process.cwd(), 'napcat-qrcode.png')
 
-  try {
-    execFileSync('docker', ['cp', `${配置.napcat.container}:/app/napcat/cache/qrcode.png`, 目标], {
-      encoding: 'utf8',
-      windowsHide: true,
-      timeout: 15000,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-  } catch (错) {
-    console.error('拿不到二维码：' + String((错 && (错.stderr || 错.message)) || 错).trim().slice(0, 200))
+  // 走 run.mjs：受限沙箱里 execFileSync 抓管道会 EPERM，
+  // 它会自动改成「重定向到临时文件再读」，不然会误报「拿不到二维码」。
+  const 复制 = 跑('docker', ['cp', `${配置.napcat.container}:/app/napcat/cache/qrcode.png`, 目标], 15000)
+  if (!复制.ok) {
+    console.error('拿不到二维码：' + String(复制.错 || 'docker cp 失败').trim().slice(0, 200))
     console.error('')
     console.error('可能的原因：')
     console.error('  · 容器没起 —— 跑 qiyu doctor 看看')