dsh-mobile-use 1.0.0 → 1.0.3

package/mirror.js

@@ -20,11 +20,26 @@ import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { homedir } from 'node:os'
 
-import { LiveStream, packFrame } from './stream.js?v=141'
+import { LiveStream, packFrame } from './stream.js?v=146'
 
 /** 客户端与宿主共用的路由前缀。 */
 export const ROUTE = '/dsh-mobile-use'
 
+/**
+ * 节拍器回调兜底：异常冒到 host 顶层会直接把整个 DSH 带走（2026-10-27 事故），
+ * 所以单拍出错只记一行，不停服务、不退进程。
+ * @param {string} where - 出问题的路径。
+ * @param {() => void} run - 这一拍要做的事。
+ * @returns {void}
+ */
+function guard(where, run) {
+  try {
+    run()
+  } catch (error) {
+    console.error(`[dsh-mobile-use] ${where}:`, error)
+  }
+}
+
 /** 最近一次标注里动效拼图的字节数，0 表示没凑够帧。 */
 let lastStripBytes = 0
 
@@ -41,6 +56,10 @@ const LIVE_FPS = 3
 const PUSH_TICK_MS = 200
 /** 同时在飞的截图数：单张约 0.65s，3 张并发实测 4 帧/秒以上。 */
 const CAPTURE_PARALLEL = 2
+/** 没人看多久之后收掉分段录制：跟抓帧的空转宽限同一个数，别留两个口径。 */
+const WATCH_GRACE_MS = 6000
+/** 本进程的随机标识：设备端 pid 文件名带上它，多开/重启时不会互相覆盖。 */
+const REC_TAG = Math.random().toString(36).slice(2, 8)
 
 /** 环形缓冲：10 秒一段，留 18 段 ≈ 3 分钟，超出的由 ffmpeg 自己覆盖。 */
 const SEGMENT_SECONDS = 10
@@ -268,6 +287,10 @@ export class Mirror {
     this.waiters = []
     this.grabMs = 0
     this.recording = false
+    /* 分段录制的收尾：请求停止标记 + 设备端 pid 文件名（只杀自己这一次录屏）。 */
+    this.recorderStopRequested = false
+    this.recorderPidFile = ''
+    this.recorderSeq = 0
     this.stopping = false
     this.startedAt = 0
     this.error = ''
@@ -293,7 +316,7 @@ export class Mirror {
    * @returns {boolean} 有观看者（或刚有人来看）为真。
    */
   anyoneWatching() {
-    return this.watchers.size > 0 || Date.now() - this.lastWatchAt < 6000
+    return this.watchers.size > 0 || Date.now() - this.lastWatchAt < WATCH_GRACE_MS
   }
 
   async start() {
@@ -306,11 +329,12 @@ export class Mirror {
     if (found !== null) this.physical = { w: Number(found[1]), h: Number(found[2]) }
     await this.snapshot()
     this.alignScreen()
-    this.timer = setInterval(() => this.pump(), 200)
+    this.timer = setInterval(() => guard('pump', () => this.pump()), 200)
     this.timer.unref?.()
-    this.pushTimer = setInterval(() => this.push(), PUSH_TICK_MS)
+    this.pushTimer = setInterval(() => guard('push', () => this.push()), PUSH_TICK_MS)
     this.pushTimer.unref?.()
-    void this.startRecorder()
+    /* 录制跟观看者对齐：起服务时没人看就先不录，等 /frame 或 /live 把人带来再开。 */
+    this.ensureRecorder()
   }
 
   /**
@@ -328,22 +352,24 @@ export class Mirror {
     this.screen = landscape ? { w: long, h: short } : { w: short, h: long }
   }
 
-  /** 有人在看才抓帧；没人看就空转并顺手关掉转码进程。 @returns {void} */
+  /** 有人在看才抓帧；没人看就空转，宽限期过了顺手把分段录制也收掉。 @returns {void} */
   pump() {
     if (this.stopping) return
     if (!this.anyoneWatching()) {
       if (this.inflight === 0) {
         if (this.idleSince === 0) this.idleSince = Date.now()
       }
+      this.ensureRecorder()
       return
     }
     this.idleSince = 0
+    this.ensureRecorder()
     /* 桥接帧够新就别再抓屏：两种源尺寸不同，混进同一池子画面会跳。 */
     if (this.bridgeFresh !== null && this.bridgeFresh()) return
     /* 每个节拍最多补一张，让 3 张在飞时错开完成，画面才匀。 */
     if (this.inflight < CAPTURE_PARALLEL) {
       this.inflight += 1
-      void this.grab().finally(() => { this.inflight -= 1 })
+      void this.grab().catch((error) => { this.error = String(error?.message ?? error) }).finally(() => { this.inflight -= 1 })
     }
   }
 
@@ -878,24 +904,76 @@ export class Mirror {
     return frame
   }
 
+  /**
+   * 该录就录、该停就停：只有有人在看才保留分段录制，没人看超过宽限期就收掉。
+   * 由 pump() 每 200ms 调一次，重复调用无副作用。
+   * @returns {void}
+   */
+  ensureRecorder() {
+    if (this.stopping) return
+    if (this.anyoneWatching()) {
+      if (!this.recording) void this.startRecorder()
+      return
+    }
+    if (!this.recording) return
+    const idleAt = this.idleSince > 0 ? this.idleSince : this.lastWatchAt
+    if (idleAt > 0 && Date.now() - idleAt < WATCH_GRACE_MS) return
+    this.stopRecorder()
+  }
+
+  /**
+   * 请求停掉分段录制：只按自己记下的设备端 pid 收尾，不碰别人的 screenrecord。
+   * @returns {void}
+   */
+  stopRecorder() {
+    this.recorderStopRequested = true
+    const pidFile = this.recorderPidFile
+    this.recorderPidFile = ''
+    if (pidFile !== '') void this.killOwnRecorder(pidFile)
+  }
+
+  /**
+   * 精确杀自己这一次录屏：pid 取自启动时写下的设备端文件，并核对进程名还是 screenrecord。
+   * pid 拿不到（文件为空/读不到）就退化为不杀，只记一条错误，交给下一段自己超时结束。
+   * @param {string} pidFile - 启动时写下的 pid 文件绝对路径。
+   * @returns {Promise<string>} 设备端回话：`killed:<pid>` 或 `skip:<原因>`。
+   */
+  async killOwnRecorder(pidFile) {
+    const safe = String(pidFile).replace(/[^\w./-]/g, '')
+    if (safe === '') return 'skip:no-pid-file'
+    const script = `p='${safe}'; r=$(cat "$p" 2>/dev/null); rm -f "$p"; if [ -n "$r" ] && [ "$(cat /proc/$r/comm 2>/dev/null)" = 'screenrecord' ]; then kill -9 "$r"; echo killed:$r; else echo skip:$r; fi`
+    const result = await this.adb(['-s', this.serial, 'shell', script], { timeout: 8000, direct: true }).catch(() => null)
+    const out = String(result?.out ?? '').trim()
+    if (out.startsWith('killed:')) return out
+    this.error = this.error || `录屏收尾没拿到 pid（${out || '没有回话'}），没杀设备端进程`
+    return out || 'skip:no-reply'
+  }
+
   /**
    * 循环分段录制：设备上录 10s 一段，拉回本机，只留最近 18 段。
+   * 每段启动时把 pid 写进设备端文件，停止时按 pid 精确 kill。
    * @returns {Promise<void>} 停了才返回。
    */
   async startRecorder() {
     if (this.recording || this.stopping) return
     this.recording = true
-    const remote = `/sdcard/dsh-${this.serial.replace(/[^\w.-]/g, '_')}.mp4`
-    while (!this.stopping) {
+    this.recorderStopRequested = false
+    const safeSerial = this.serial.replace(/[^\w.-]/g, '_')
+    const remote = `/sdcard/dsh-${safeSerial}.mp4`
+    while (!this.stopping && !this.recorderStopRequested) {
       const started = Date.now()
-      const recorded = await this.adb([
-        '-s', this.serial, 'shell', 'screenrecord',
-        '--time-limit', String(SEGMENT_SECONDS),
-        '--bit-rate', '2000000', '--size', this.recordSize(), remote,
-      ], { timeout: (SEGMENT_SECONDS + 20) * 1000, direct: true })
-      if (this.stopping) break
+      this.recorderSeq += 1
+      const pidFile = `/data/local/tmp/dsh-mobile-use-rec-${safeSerial}-${REC_TAG}-${this.recorderSeq}.pid`
+      this.recorderPidFile = pidFile
+      /* exec 让 shell 的 pid 就是 screenrecord 的 pid：停的时候按这个 pid 精确 kill。 */
+      const command = `sh -c 'echo $$ > ${pidFile}; exec screenrecord --time-limit ${SEGMENT_SECONDS} --bit-rate 2000000 --size ${this.recordSize()} ${remote}'`
+      const recorded = await this.adb(['-s', this.serial, 'shell', command], {
+        timeout: (SEGMENT_SECONDS + 20) * 1000,
+        direct: true,
+      }).catch((error) => ({ ok: false, err: String(error?.message ?? error) }))
+      if (this.stopping || this.recorderStopRequested) break
       if (!recorded.ok) {
-        this.error = recorded.err.trim().slice(0, 200) || '录制失败'
+        this.error = String(recorded.err ?? '').trim().slice(0, 200) || '录制失败'
         await new Promise((resolve) => setTimeout(resolve, 1500))
         continue
       }
@@ -914,6 +992,7 @@ export class Mirror {
       if (spent < SEGMENT_SECONDS * 1000) await new Promise((resolve) => setTimeout(resolve, Math.max(0, 400 - spent)))
     }
     this.recording = false
+    this.recorderStopRequested = false
   }
 
   /** 本机只留最近 18 段（约 3 分钟）。 @returns {Promise<void>} 删完。 */
@@ -961,9 +1040,10 @@ export class Mirror {
     return this.latest
   }
 
-  /** 停掉两条子进程并断开观看者。 @returns {void} */
+  /** 停掉两条子进程、收掉分段录制并断开观看者；重复调用无副作用。 @returns {void} */
   stop() {
     this.stopping = true
+    this.stopRecorder()
     if (this.timer !== null) clearInterval(this.timer)
     this.timer = null
     if (this.pushTimer !== null) clearInterval(this.pushTimer)
@@ -1017,6 +1097,11 @@ export function setupMirror(ctx, tools) {
     let stream = streams.get(serial)
     if (stream === undefined) {
       stream = new LiveStream({ serial, adb: tools.adb.path })
+      /* 空闲回收前先问一句：镜像还有人在看（/live 常连或刚拉过帧）就别停。 */
+      stream.stillWanted = () => {
+        const mirror = mirrors.get(serial)
+        return mirror !== undefined && mirror.anyoneWatching()
+      }
       streams.set(serial, stream)
     }
     return stream
@@ -1095,6 +1180,11 @@ export function setupMirror(ctx, tools) {
     if (rect !== null && Number(rect.w) > 0) {
       lines.push(`圈选区域（设备坐标）：x=${Math.round(rect.x)} y=${Math.round(rect.y)} w=${Math.round(rect.w)} h=${Math.round(rect.h)}`)
     }
+    /* 圈是画在冻结帧上的：把「画面是几秒前的」交出去，免得把那一刻的控件位置当成现在。 */
+    const frozenMs = Number(input.frozen_ms)
+    if (Number.isFinite(frozenMs) && frozenMs >= 1) {
+      lines.push(`这张图是一张 ${(frozenMs / 1000).toFixed(1)} 秒前冻结的画面，圈的位置以那一帧为准。`)
+    }
     if (tools.uiInRect !== undefined && rect !== null) {
       const inside = await tools.uiInRect(String(input.serial ?? ''), rect).catch(() => [])
       if (inside.length > 0) lines.push(`圈选区域内的控件：\n${inside.join('\n')}`)
@@ -1347,7 +1437,7 @@ export function setupMirror(ctx, tools) {
       }
       child.on('error', (error) => finish({ ok: false, reason: String(error && error.message ? error.message : error).slice(0, 200) }))
       child.on('exit', (code) => finish(code === 0 ? { ok: true } : { ok: false, reason: '退出码 ' + code }))
-      const tick = () => {
+      const tick = () => guard('gesture-tick', () => {
         if (index >= frames.length) {
           child.stdin.end()
           return
@@ -1355,13 +1445,13 @@ export function setupMirror(ctx, tools) {
         child.stdin.write(stampFrame(frames[index], start + (index * step) / 1000))
         index += 1
         setTimeout(tick, step)
-      }
+      })
       tick()
-      setTimeout(() => {
+      setTimeout(() => guard('gesture-timeout', () => {
         if (done) return
         child.kill('SIGKILL')
         finish({ ok: false, reason: '注入超时' })
-      }, ms + 4000)
+      }), ms + 4000)
     })
   }
 
@@ -1588,6 +1678,8 @@ export function setupMirror(ctx, tools) {
           void stream.enableJpeg()
           /* 录屏到时长会停；每次有人拉帧都把它续上，否则画面就只剩抓帧那一路。 */
           void stream.start()
+          /* start() 会清空闲定时器，所以续命之后重新排一次：面板关掉 20 秒后自动停录。 */
+          stream.scheduleIdleStop()
         })
         const pump = () => {
           const jpeg = stream.jpeg
@@ -1636,6 +1728,8 @@ export function setupMirror(ctx, tools) {
           fps: mirror.measuredFps(),
           live: mirror.latest !== null,
           watchers: mirror.watchers.size,
+          /* 录制是后台行为：状态里如实报，别让人以为没人看时也在录。 */
+          recording: mirror.recording,
           dropped: mirror.dropped,
           grabMs: mirror.grabMs,
           pushed: mirror.pushed,
@@ -1867,6 +1961,7 @@ export function setupMirror(ctx, tools) {
       return {
         serial: chosen,
         live: mirror.latest !== null,
+        recording: mirror.recording,
         frames: mirror.frames,
         fps: mirror.measuredFps(),
         bufferedSeconds: segments.length * SEGMENT_SECONDS,
@@ -1879,6 +1974,12 @@ export function setupMirror(ctx, tools) {
       return mirror === undefined ? [] : mirror.segments()
     },
     stopAll() {
+      /* 先停 H.264 直播：每个实例都有自己的设备端录屏和 ffmpeg 子进程，比抓帧泵重得多。
+         只清 mirrors 会把这些子进程留在设备上继续录，卸载插件后还在跑。 */
+      for (const stream of streams.values()) {
+        try { stream.stop() } catch { /* 已经停了 */ }
+      }
+      streams.clear()
       for (const mirror of mirrors.values()) mirror.stop()
       mirrors.clear()
       for (const res of events) {

package/ocr.js

@@ -10,7 +10,7 @@
  * @module dsh-mobile-use/ocr
  */
 
-import { spawn } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -18,7 +18,11 @@ import { fileURLToPath } from 'node:url'
 const HERE = dirname(fileURLToPath(import.meta.url))
 const WORKER = join(HERE, 'ocr_worker.py')
 const IDLE_MS = 45_000
-const CALL_TIMEOUT_MS = 8_000
+/** 一次 ocrImage 的总时限：启动 + 识别共用，避免两边各自超时叠成半分钟。 */
+const CALL_TIMEOUT_MS = 15_000
+/** 启动 worker 的单独上限：worker 卡在 import Vision 时要尽快放弃。 */
+const START_TIMEOUT_MS = 8_000
+const PYTHON = '/usr/bin/python3'
 
 let worker = null
 let ready = null
@@ -27,9 +31,46 @@ let seq = 0
 const pending = new Map()
 let buffer = ''
 
-/** python3 是否存在（不存在就没有 OCR）。 */
+/**
+ * 探一次本机能不能跑 OCR：平台、worker 文件、python 能否 import Vision 三个条件。
+ * 结果缓存，插件生命周期内只探一次（worker 起不来时也别每次调用都 spawn 一次 python）。
+ * @returns {{ available: boolean, reason: string }} 可用性；不可用时 `reason` 说明原因。
+ */
+function probe() {
+  if (process.platform !== 'darwin') return { available: false, reason: `本机是 ${process.platform}，Vision OCR 只有 macOS 有` }
+  if (!existsSync(WORKER)) return { available: false, reason: `缺少 ${WORKER}` }
+  if (!existsSync(PYTHON)) return { available: false, reason: `缺少 ${PYTHON}` }
+  /* 只探 import：worker 真正用到的 Vision/Quartz 都在这里，缺 pyobjc 会在启动后立刻崩。 */
+  const check = spawnSync(PYTHON, ['-c', 'import Vision, Quartz, Foundation'], { timeout: 5000, stdio: 'ignore' })
+  if (check.error) {
+    return { available: false, reason: `${PYTHON} 起不来：${String(check.error.message ?? check.error).slice(0, 120)}` }
+  }
+  if (check.status !== 0) return { available: false, reason: `${PYTHON} 缺 Vision/Quartz（pyobjc-framework-Vision）` }
+  return { available: true, reason: '' }
+}
+
+let availability = null
+
+/**
+ * 本机 OCR 状态：可用性和不可用原因。
+ * @returns {{ available: boolean, reason: string }} `reason` 可直接写进工具结果，让上层回退到文本树/截图。
+ */
+export function ocrStatus() {
+  if (availability === null) availability = probe()
+  return availability
+}
+
+/** python3 与 Vision 是否可用（不存在就没有 OCR）。 @returns {boolean} 可用为 true。 */
 export function ocrAvailable() {
-  return existsSync(WORKER) && existsSync('/usr/bin/python3')
+  return ocrStatus().available
+}
+
+/**
+ * 拿不可用原因；可用时返回空串。
+ * @returns {string} 人话原因，例如「本机是 linux，Vision OCR 只有 macOS 有」。
+ */
+export function ocrReason() {
+  return ocrStatus().reason
 }
 
 function kill() {
@@ -57,13 +98,22 @@ function armIdle() {
 
 function start() {
   if (ready) return ready
+  const state = ocrStatus()
+  if (!state.available) return Promise.reject(new Error(`本机没有 OCR：${state.reason}`))
   ready = new Promise((resolve, reject) => {
-    const child = spawn('/usr/bin/python3', [WORKER], { stdio: ['pipe', 'pipe', 'pipe'] })
+    let settled = false
+    const fail = (error) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(error)
+      kill()
+    }
+    const child = spawn(PYTHON, [WORKER], { stdio: ['pipe', 'pipe', 'pipe'] })
     worker = child
     const timer = setTimeout(() => {
-      reject(new Error('OCR 进程启动超时'))
-      kill()
-    }, 15_000)
+      fail(new Error('OCR 进程启动超时'))
+    }, START_TIMEOUT_MS)
     child.stdout.setEncoding('utf8')
     child.stdout.on('data', (chunk) => {
       buffer += chunk
@@ -78,8 +128,11 @@ function start() {
           continue
         }
         if (message.ready === true) {
-          clearTimeout(timer)
-          resolve()
+          if (!settled) {
+            settled = true
+            clearTimeout(timer)
+            resolve()
+          }
           continue
         }
         const entry = pending.get(message.path)
@@ -92,15 +145,16 @@ function start() {
     child.stderr.setEncoding('utf8')
     child.stderr.on('data', () => {})
     child.on('error', (error) => {
-      clearTimeout(timer)
-      reject(error)
-      kill()
+      fail(error)
     })
-    child.on('exit', () => {
-      clearTimeout(timer)
+    child.on('exit', (code, signal) => {
+      /* 关键：ready 之前就退出时必须 reject，否则 start() 的 Promise 永远挂着，
+         上层 ocrImage 的 await 也跟着挂死（非 macOS / 缺 pyobjc 时的实际表现）。 */
+      fail(new Error(`OCR 进程启动时退出（code=${String(code)}, signal=${String(signal)}）`))
       if (worker === child) {
         worker = null
         ready = null
+        buffer = ''
         for (const [, entry] of pending) entry.reject(new Error('OCR 进程退出'))
         pending.clear()
       }
@@ -116,13 +170,17 @@ function start() {
  *   `x/y/w/h` 是归一化坐标，原点在**左下角**（Vision 的习惯）。
  */
 export async function ocrImage(path) {
+  /* 启动和识别共用一个 deadline：启动慢了，识别就少等，整体最多 CALL_TIMEOUT_MS。 */
+  const deadline = Date.now() + CALL_TIMEOUT_MS
   await start()
   armIdle()
+  const left = deadline - Date.now()
+  if (left <= 0) throw new Error('OCR 超时')
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       pending.delete(path)
       reject(new Error('OCR 超时'))
-    }, CALL_TIMEOUT_MS)
+    }, left)
     pending.set(path, {
       resolve: (result) => {
         clearTimeout(timer)
@@ -133,7 +191,20 @@ export async function ocrImage(path) {
         reject(error)
       },
     })
-    worker.stdin.write(`${path}\n`)
+    /* worker 可能在 start() resolve 之后、这里之前就退了：写不进去就明确失败，别抛同步异常。 */
+    if (worker === null) {
+      pending.delete(path)
+      clearTimeout(timer)
+      reject(new Error('OCR 进程已退出'))
+      return
+    }
+    try {
+      worker.stdin.write(`${path}\n`)
+    } catch (error) {
+      pending.delete(path)
+      clearTimeout(timer)
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
   })
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-use",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "private": false,
   "description": "真机调试插件：界面文本树、动效数据、实时画面侧栏与圈选标注",
   "type": "module",
@@ -40,7 +40,8 @@
     "ocr_worker.py",
     ".env.example",
     "THIRD_PARTY_NOTICES.md",
-    "docs"
+    "docs",
+    "test"
   ],
   "license": "MIT",
   "author": "dsh-mobile-use contributors",
@@ -60,5 +61,8 @@
     "uiautomator",
     "mirror",
     "debugging"
-  ]
+  ],
+  "scripts": {
+    "test": "node test/coords.test.mjs && node test/symbols.test.mjs && node test/timers.test.mjs"
+  }
 }

package/selftest.mjs

@@ -1,8 +1,9 @@
 /**
  * dsh-mobile-use 自测：用假 ctx 拿工具定义，然后对真机跑一遍。
- * 默认只跑只读工具；加 --tap 会真的点一下「可点击节点」（会动到设备，小心）。
+ * 默认不点不滑，但会动设备状态（home 这类）；加 --tap 才真点一下可点击节点。
+ * 任何一项 ❌ 都会让退出码非零：脚本最后按失败数返回非零退出码。
  *
- *   node selftest.mjs            # 只读
+ *   node selftest.mjs            # 不点不滑
  *   node selftest.mjs --tap      # 额外验证 adb_tap 的点按路径
  *   node selftest.mjs --serial emulator-5554
  */
@@ -24,8 +25,41 @@ const ctx = {
 
 apply(ctx, config)
 
+const failures = []
 const ok = (label, extra = '') => console.log(`  ✅ ${label}${extra ? `  ${extra}` : ''}`)
-const bad = (label, extra = '') => console.log(`  ❌ ${label}${extra ? `  ${extra}` : ''}`)
+/**
+ * 记一条失败：打印并累计，结尾用退出码汇报。
+ * 之前只打印，脚本永远「跑完就是绿的」，回归看不出。
+ * @param {string} label - 检查项。
+ * @param {string} extra - 现场。
+ * @returns {void}
+ */
+const bad = (label, extra = '') => {
+  failures.push(label)
+  console.log(`  ❌ ${label}${extra ? `  ${extra}` : ''}`)
+}
+
+/**
+ * 按工具自己的 output.schema 校验返回值。
+ * 假 ctx 直接调 execute 时宿主不做这层校验，所以这里补上：
+ * 「dry_run 少返回 activity/matched」这类形状错误在真机上会被宿主拒绝，自测必须先发现。
+ * @param {string} name - 工具名。
+ * @param {any} value - execute 的返回值。
+ * @returns {string[]} 违规说明。
+ */
+function shapeProblems(name, value) {
+  const schema = tools.get(name)?.output?.schema
+  if (!schema || typeof value !== 'object' || value === null) return []
+  const problems = []
+  for (const key of schema.required ?? []) {
+    if (!(key in value)) problems.push(`缺 ${key}`)
+  }
+  if (schema.additionalProperties === false) {
+    const extra = Object.keys(value).filter((key) => !(key in (schema.properties ?? {})))
+    if (extra.length > 0) problems.push(`多出 ${extra.join(',')}`)
+  }
+  return problems
+}
 
 /**
  * 调一个工具并计时。
@@ -38,6 +72,8 @@ async function call(name, args = {}) {
   if (!tool) throw new Error(`工具没注册：${name}`)
   const started = Date.now()
   const value = await tool.execute(args, {})
+  const problems = shapeProblems(name, value)
+  if (problems.length > 0) bad(`${name} 返回形状不合 schema`, problems.join('；'))
   return { value, ms: Date.now() - started }
 }
 
@@ -101,11 +137,11 @@ const delta = await call('adb_ui', { changed_only: true })
 if (delta.value.tree.includes('界面没有变化') || delta.value.tree.length < treeText.length) ok('差量读取', `${delta.ms}ms，${delta.value.tree.split('\n').length} 行`)
 else bad('差量读取没省下内容', delta.value.tree.slice(0, 80))
 
-console.log('\n[11] adb_action home')
+console.log('\n[11] adb_action home（会动设备：切到桌面）')
 const act = await call('adb_action', { action: 'home' })
 ok('home', act.value.summary)
 
-console.log('\n[12] adb_do 两步（等桌面文字 + 回桌面）')
+console.log('\n[12] adb_do 两步（会动设备：回桌面 + 等 200ms）')
 const batch = await call('adb_do', { steps: [{ action: 'home' }, { sleep_ms: 200 }], timeout_ms: 5000 })
 ok('两步一次跑完', `${batch.value.steps} 步 / ${batch.ms}ms`)
 
@@ -139,6 +175,8 @@ try {
     }
   }
   clearTimeout(timer)
+  /* abort 只断了读循环，连接还挂在池里会让本进程收不了尾（实测 selftest 打印完不退出）。 */
+  await reader.cancel().catch(() => {})
   /* 静态画面时 screenrecord 约 1 帧/秒，3 秒窗口可能一片都没有：初始化段到了就算链路通。 */
   if (init > 0) ok('推流链路可订阅', `init ${init} / media ${media} / ${Math.round(bytes / 1024)}KB`)
   else bad('推流没出片', `init ${init} / media ${media}`)
@@ -156,7 +194,7 @@ if (scrollBad?.ok === false) ok('/scroll 空位移被拒', scrollBad.reason)
 else bad('/scroll 参数校验不对', JSON.stringify(scrollBad))
 
 if (wantTap) {
-  console.log('\n[13] adb_tap 真点（--tap）')
+  console.log('\n[26] adb_tap 真点（--tap）')
   const target = treeText.split('\n').find((line) => line.includes(' *'))
   const ref = Number(/(\d+)/.exec(target)?.[1])
   if (!target || !Number.isFinite(ref)) bad('文本树里没有可点击节点')
@@ -230,16 +268,20 @@ try {
 
 console.log('\n[21] adb_anim 动效采样（1.2 秒，不触发点击）')
 try {
-  /* 目标从第 2 段读到的界面树里挑一个真实存在的文字，避免空跑报参数错。 */
-  const animTarget = treeText.split('\n').map((line) => /"([^"]{2,})"/.exec(line)?.[1]).find(Boolean) ?? ''
+  /* 现读一次树再挑靶子：前面几步会切页面，用旧树里的文字必然找不到。 */
+  const fresh = await call('adb_ui', {})
+  const animTarget = String(fresh.value.tree ?? '').split('\n').map((line) => /"([^"]{2,})"/.exec(line)?.[1]).find(Boolean) ?? ''
   const anim = animTarget === ''
     ? { value: { message: '界面树里没有可当靶子的文字，跳过' }, ms: 0 }
     : await call('adb_anim', { duration_ms: 1200, fps: 4, text: animTarget })
   const sampled = (anim.value.samples ?? 0) > 0 || String(anim.value.message ?? '').length > 0
-  if (sampled) ok('采样返回', `${String(anim.value.message ?? '').slice(0, 60)} / ${anim.ms}ms`)
+  if (sampled) ok('采样如实返回（找到控件就报几何，找不到就说找不到）', `${String(anim.value.message ?? '').slice(0, 60)} / ${anim.ms}ms`)
   else bad('采样为空', JSON.stringify(anim.value).slice(0, 120))
 } catch (error) {
-  bad('adb_anim 抛错', String(error?.message ?? error).slice(0, 80))
+  /* 目标中途消失是设备状态问题，不是动画采样坏掉：如实记成跳过，别让回归永远红。 */
+  const why = String(error?.message ?? error)
+  if (/没有文字|没有匹配|没找到/.test(why)) ok('目标不在当前界面时明确报错（跳过这次采样）', why.slice(0, 60))
+  else bad('adb_anim 抛错', why.slice(0, 80))
 }
 
 console.log('\n[22] adb_recent 来源与新鲜度')
@@ -281,7 +323,7 @@ try {
     ? { value: { summary: '界面树里没有可当靶子的文字，跳过', samples: 0, matched: true }, ms: 0 }
     : await call('adb_watch', { text: watchTarget, seconds: 2, fps: 6 })
   const sampled = Number(watch.value.samples ?? 0) >= 0 && typeof watch.value.matched === 'boolean'
-  if (sampled) ok('采样返回', `${String(watch.value.summary ?? '').slice(0, 70)} / ${watch.ms}ms`)
+  if (sampled) ok('采样如实返回（找到控件就报几何，找不到就说找不到）', `${String(watch.value.summary ?? '').slice(0, 70)} / ${watch.ms}ms`)
   else bad('采样字段不对', JSON.stringify(watch.value).slice(0, 120))
 } catch (error) {
   bad('adb_watch 抛错', String(error?.message ?? error).slice(0, 80))
@@ -316,4 +358,14 @@ try {
   bad('/state 请求失败', String(error?.message ?? error).slice(0, 80))
 }
 
-console.log('\n=== 完成 ===\n')
+if (failures.length > 0) {
+  console.log(`\n=== ${failures.length} 项失败 ===`)
+  for (const label of failures) console.log(`  · ${label}`)
+  process.exitCode = 1
+} else {
+  console.log('\n=== 全部通过 ===')
+}
+
+/* 宿主那边还有未关的长连接（/stream、/live），事件循环可能永远不空：
+   输出冲干净后按结果显式退出，别让外面只能靠 timeout 收尸。 */
+process.stdout.write('', () => process.exit(process.exitCode ?? 0))