@windsland52/maafw-live 0.0.0-stage → 0.3.0

package/lib/daemon/framed.mjs

@@ -0,0 +1,2850 @@
+/**
+ * FrameDaemon —— 设备 daemon，独立子进程运行（maa-node 的 .wait() 可能同步阻塞，
+ * 绝不允许进入宿主进程）。
+ *
+ * 职责（分层消费模型的生产端）：
+ *  - 持有 maa-node 的 Controller / Resource / Tasker（连接能力全部来自 maafw 本体）
+ *  - 抓帧循环 → 降采样 → 块亮度哈希 → 变化/稳定事件（合并）→ 环形缓冲
+ *  - 像素默认不出 daemon：仅发元数据；面板实时预览走落盘的预览帧；精查走 ROI 裁剪
+ *  - Tasker 运行：节点事件流按帧序对齐，内置超时 + post_stop（防 JumpBack 死循环）
+ *  - 识别单测：在环形缓冲历史帧上跑 post_recognition（支持阈值扫描）
+ *
+ * 协议（--child 模式：stdin/stdout JSON 行协议，一行一条消息）：
+ *   host → daemon: { id, cmd, ...args }
+ *   daemon → host: { kind:'reply', id, ok, data|error }   （请求应答）
+ *                  { kind:'frame', meta, preview }         （每接受帧的元数据与预览帧路径）
+ *                  { kind:'event', ev }                    （变化/稳定/节点事件）
+ *                  { kind:'stream_error', error }
+ */
+import { createRequire } from 'node:module'
+import { execFile, spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { createHash, randomUUID } from 'node:crypto'
+import readline from 'node:readline'
+import zlib from 'node:zlib'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const require = createRequire(import.meta.url)
+/* 子进程模式（host 经 spawn 启动带 --child）：stdin/stdout 走 JSON 行协议；
+ * 无 --child 时（headless 单测 import）模块无副作用。原生崩溃只杀子进程，不陪葬 host。 */
+const CHILD = process.argv.includes('--child')
+const send = (m, done) => {
+  if (!CHILD) { if (done) done(); return }
+  const line = JSON.stringify(m) + '\n'
+  if (done) process.stdout.write(line, done)
+  else process.stdout.write(line)
+}
+
+let maa = null
+function loadMaa() {
+  if (!maa) maa = require('@maaxyz/maa-node')
+  return maa
+}
+
+/* ────────────────────────── 最小 PNG 解码（8bit RGB/RGBA，非隔行） ────────────────────────── */
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xEDB88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c
+  }
+  return t
+})()
+function crc32(buf) {
+  let c = 0xFFFFFFFF
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xFF] ^ (c >>> 8)
+  return (c ^ 0xFFFFFFFF) >>> 0
+}
+function pngChunk(type, data) {
+  const len = Buffer.alloc(4); len.writeUInt32BE(data.length, 0)
+  const t = Buffer.from(type, 'ascii')
+  const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(Buffer.concat([t, data])), 0)
+  return Buffer.concat([len, t, data, crc])
+}
+function pngDecode(buf) {
+  if (buf[0] !== 0x89 || buf[1] !== 0x50) throw new Error('not a png')
+  let off = 8, w = 0, h = 0, bitDepth = 0, colorType = 0
+  const idat = []
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off)
+    const type = buf.toString('ascii', off + 4, off + 8)
+    const data = buf.subarray(off + 8, off + 8 + len)
+    if (type === 'IHDR') {
+      w = data.readUInt32BE(0); h = data.readUInt32BE(4)
+      bitDepth = data[8]; colorType = data[9]
+      if (data[12] !== 0) throw new Error('interlaced png unsupported')
+    } else if (type === 'IDAT') idat.push(Buffer.from(data))
+    else if (type === 'IEND') break
+    off += 12 + len
+  }
+  if (bitDepth !== 8 || (colorType !== 2 && colorType !== 6)) {
+    throw new Error('unsupported png: depth=' + bitDepth + ' color=' + colorType)
+  }
+  const ch = colorType === 6 ? 4 : 3
+  const raw = zlib.inflateSync(Buffer.concat(idat))
+  const stride = w * ch
+  /* 解压后必须正好是 h 行 ×（每行 1 个滤镜字节 + 行字节）。少了就是文件被截断 / IDAT 不完整——
+   * 不校验的话 line[x] 取到 undefined，NaN & 255 静默变成 0，产出一张全黑图被当成证据。 */
+  const need = h * (stride + 1)
+  if (raw.length !== need) {
+    throw new Error('png 像素数据长度不符：期望 ' + need + ' 字节（' + h + ' 行 ×（1 + ' + stride + '）），实际 ' + raw.length)
+  }
+  const out = Buffer.alloc(w * h * ch)
+  let pos = 0
+  for (let y = 0; y < h; y++) {
+    const filter = raw[pos++]
+    const line = raw.subarray(pos, pos + stride); pos += stride
+    const cur = out.subarray(y * stride, (y + 1) * stride)
+    const prev = y > 0 ? out.subarray((y - 1) * stride, y * stride) : null
+    for (let x = 0; x < stride; x++) {
+      const a = x >= ch ? cur[x - ch] : 0
+      const b = prev ? prev[x] : 0
+      const c = prev && x >= ch ? prev[x - ch] : 0
+      let v = line[x]
+      if (filter === 1) v += a
+      else if (filter === 2) v += b
+      else if (filter === 3) v += (a + b) >> 1
+      else if (filter === 4) {
+        const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c)
+        v += (pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c)
+      }
+      cur[x] = v & 255
+    }
+  }
+  return { w, h, ch, data: out }
+}
+/** 归一化为 RGB（丢弃 alpha），返回新 Buffer */
+function toRgb(dec) {
+  if (dec.ch === 3) return dec.data
+  const out = Buffer.alloc(dec.w * dec.h * 3)
+  for (let i = 0, o = 0; i < dec.data.length; i += 4, o += 3) {
+    out[o] = dec.data[i]; out[o + 1] = dec.data[i + 1]; out[o + 2] = dec.data[i + 2]
+  }
+  return out
+}
+function pngEncodeRGB(rgb, w, h) {
+  const stride = w * 3
+  const raw = Buffer.alloc((stride + 1) * h)
+  for (let y = 0; y < h; y++) {
+    raw[y * (stride + 1)] = 0
+    rgb.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride)
+  }
+  const ihdr = Buffer.alloc(13)
+  ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4)
+  ihdr[8] = 8; ihdr[9] = 2
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ])
+}
+
+/* ────────────────────────── 图像降采样 / 感知哈希 ────────────────────────── */
+function downscale(rgb, sw, sh, maxSide) {
+  const sc = Math.min(1, maxSide / Math.max(sw, sh))
+  const w = Math.max(8, Math.round(sw * sc))
+  const h = Math.max(8, Math.round(sh * sc))
+  if (w === sw && h === sh) return { w, h, data: rgb }
+  const out = Buffer.alloc(w * h * 3)
+  for (let y = 0; y < h; y++) {
+    const sy0 = Math.floor(y * sh / h)
+    const sy1 = Math.max(sy0 + 1, Math.floor((y + 1) * sh / h))
+    for (let x = 0; x < w; x++) {
+      const sx0 = Math.floor(x * sw / w)
+      const sx1 = Math.max(sx0 + 1, Math.floor((x + 1) * sw / w))
+      let r = 0, g = 0, b = 0
+      const n = (sx1 - sx0) * (sy1 - sy0)
+      for (let sy = sy0; sy < sy1; sy++) {
+        let i = (sy * sw + sx0) * 3
+        for (let sx = sx0; sx < sx1; sx++, i += 3) { r += rgb[i]; g += rgb[i + 1]; b += rgb[i + 2] }
+      }
+      const o = (y * w + x) * 3
+      out[o] = r / n; out[o + 1] = g / n; out[o + 2] = b / n
+    }
+  }
+  return { w, h, data: out }
+}
+/** 8×8 分块亮度哈希（相对整体均值）+ 分块亮度均值（局部变化检测用） */
+function blockAnalyze(rgb, w, h) {
+  const cells = new Float64Array(64)
+  const cnt = new Float64Array(64)
+  let total = 0, n = 0
+  for (let y = 0; y < h; y++) {
+    const cy = Math.min(7, (y * 8 / h) | 0) * 8
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 3
+      const l = (rgb[i] * 3 + rgb[i + 1] * 6 + rgb[i + 2]) * 0.1
+      const ci = cy + Math.min(7, (x * 8 / w) | 0)
+      cells[ci] += l; cnt[ci]++; total += l; n++
+    }
+  }
+  const mean = total / Math.max(1, n)
+  const hash = new Uint8Array(64)
+  const means = new Float64Array(64)
+  for (let k = 0; k < 64; k++) {
+    means[k] = cells[k] / Math.max(1, cnt[k])
+    hash[k] = means[k] >= mean ? 1 : 0
+  }
+  return { hash, means }
+}
+/** 兼容导出：只要哈希位 */
+function blockHash(rgb, w, h) {
+  return blockAnalyze(rgb, w, h).hash
+}
+function hashDist(a, b) {
+  let d = 0
+  for (let i = 0; i < 64; i++) if (a[i] !== b[i]) d++
+  return d / 64
+}
+const hashStr = (h) => Array.from(h, (v) => (v ? '1' : '0')).join('')
+
+/* ────────────────────────── 状态 ────────────────────────── */
+/* 关键帧库磁盘配额（契约 §4.1 保留与清理）：满额拒绝新增留存并报告，不后台静默删除——
+ * 清理是用户的决定。init 可覆盖；env MAAFW_KF_QUOTA_BYTES 次之。
+ * 判据是 `S.kfQuota > 0`，也就是 0 = 不设限（单测直接改 S 走这条）；但**从 env 与 init 到不了 0**：
+ * 两处都只认 >0 的值（缺省 1GiB），想不设限得由宿主直接控制 S。 */
+const KF_QUOTA_DEFAULT = (() => {
+  const v = Number(process.env.MAAFW_KF_QUOTA_BYTES)
+  return Number.isFinite(v) && v > 0 ? v : 1024 * 1024 * 1024
+})()
+const S = {
+  ctrl: null, res: null, tasker: null,
+  session: null,                       // { kind, target, method }
+  daemonId: randomUUID(),              // 本 daemon 实例身份（留存记录的 session.daemon）
+  connGen: 0,                          // 连接代次：每次 connect 成功 +1（留存记录定位用）
+  runDir: null,                        // host init 传入；关键帧库 = runDir/frames
+  kfQuota: KF_QUOTA_DEFAULT,           // 库目录字节配额（>0 生效，0 = 不设限；env/init 都只认 >0）
+  fullW: 0, fullH: 0,                  // 控制器分辨率（默认短边 720p，pipeline roi/模板同空间）
+  previewPath: null,                   // 面板实时预览帧落盘路径（host 传 runDir 初始化）
+  stream: false, streamTimer: null,
+  streamFps: 8, streamScale: 480, maxFrames: 120,
+  /* 变化检测双阈值：全局 blockHash 位差率（分布式变化）+ 分块亮度差（局部变化，任一块超限即变化）。
+   * blockThresh 单位为亮度（0-255），默认 8 ≈ 3%；阈值需按真机噪声实测校准（roadmap 条目13）。 */
+  changeGlobal: 0.06, blockThresh: 8,
+  seq: 0,
+  ring: [],                            // {seq,t,rgb,w,h,fw,fh,hash,diff}——fw/fh 为该帧捕获时控制器尺寸
+  events: [],                          // {type:'change'|'stable', seq, t, diff, dur?}
+  framesMeta: [],                      // {seq,t,hash,diff,w,h}（元数据）
+  quietNow: false, stableCount: 0,
+  lastPng: null,
+  runActive: false,
+  /* agent 桥接（PI agent 子进程 ↔ maa.Client）：绑定在某个 Resource 实例上，
+   * 同资源 + 同声明集合复用，换资源 / disconnect / shutdown 时清理。 */
+  agentBind: null,
+  /* L0 原图有界缓存（关键帧留存契约 §1-2）：滚动区=最近 K 张原图（"刚看到就能留"）；
+   * 锚区=change/stable 事件锚点、动作边界、run 起止（各自 FIFO，容量有界可配）。
+   * 张数之外还有字节预算：跨两区唯一 seq 去重计字节，超限先淘汰滚动区（锚区是策展证据，
+   * 滚动区只是"最近"）；Buffer 由两区共享，只有两区都淘汰才真正释放。 */
+  l0: {
+    roll: [],                          // {seq,t,png,w,h}
+    anchor: [],                        // {seq,t,png,w,h,source}
+    rollCap: 16, anchorCap: 32,
+    bytesCap: 192 * 1024 * 1024,       // 唯一字节预算（默认 192MB ≈ 1080p×48 张上限）
+    evicted: 0,
+  },
+}
+const STATUS = { pending: 1000, running: 2000, succeeded: 3000, failed: 4000 }
+
+function reply(id, ok, data, done) {
+  send({ kind: 'reply', id, ok, ...(ok ? { data } : { error: data }) }, done)
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/* ────────────────────────── 设备 / 连接 / 截图 ────────────────────────── */
+async function cmdProbe() {
+  const m = loadMaa()
+  const out = { version: null, adb: null, win32: null, errors: [] }
+  try { out.version = String(m.Global.version) } catch (e) { out.errors.push('version: ' + e.message) }
+  try { const a = await m.AdbController.find(); out.adb = a ? a.length : 0 } catch (e) { out.errors.push('adb: ' + e.message) }
+  try { const w = await m.Win32Controller.find(); out.win32 = w ? w.length : 0 } catch (e) { out.errors.push('win32: ' + e.message) }
+  return out
+}
+
+async function cmdDeviceList(kind) {
+  const m = loadMaa()
+  const list = []
+  if (kind !== 'win32') {
+    try {
+      const a = await m.AdbController.find()
+      if (a) for (const d of a) list.push({ kind: 'adb', id: String(d[2] ?? d[0]), name: String(d[0]), adbPath: String(d[1] ?? 'adb') })
+    } catch (e) { /* 无 adb 环境 */ }
+  }
+  if (kind !== 'adb') {
+    try {
+      const w = await m.Win32Controller.find()
+      if (w) for (const d of w) list.push({ kind: 'win32', id: String(d[0]), cls: String(d[1]), name: String(d[2] ?? '') })
+    } catch (e) { /* 无窗口 */ }
+  }
+  return list
+}
+
+function pickWin32(target, wins) {
+  const named = wins.filter((d) => d.kind === 'win32')
+  if (!named.length) return null
+  if (target) {
+    const t = String(target)
+    /* hwnd 精确匹配优先：面板与控制器规划器传的就是 hwnd（id）。
+       标题匹配放后面——窗口标题可能重复或互为子串。 */
+    const exact = named.find((d) => d.id === t)
+    if (exact) return exact
+    const lower = t.toLowerCase()
+    const hit = named.find((d) => d.name.toLowerCase().includes(lower) || d.cls.toLowerCase().includes(lower))
+    /* 指定了 target 却没匹配上时**不**退化成"随便挑一个"：
+       那是静默连错窗口，比连不上更难查（实测踩过）。 */
+    return hit ?? null
+  }
+  return named.find((d) => d.name) || named[0]
+}
+
+/**
+ * 枚举名 → 数值。interface.json 里 screencap/mouse/keyboard 写的是枚举名
+ * （如 PrintWindow / SendMessageWithCursorPos），maa-node 要的是数值；
+ * 名字大小写不敏感（与本体 string_to_enum 的 iequals 一致）。
+ * 认不出的名字不硬塞给原生层，退回默认并把警告带回上层。
+ */
+function resolveEnum(table, value, fallback, label, warns) {
+  if (value === undefined || value === null || value === '') return String(fallback)
+  const s = String(value)
+  if (/^\d+$/.test(s)) return s
+  if (table && typeof table === 'object') {
+    const key = Object.keys(table).find((k) => k.toLowerCase() === s.toLowerCase())
+    if (key !== undefined) return String(table[key])
+  }
+  warns.push(label + '=' + s + ' 不是当前 maa-node 绑定认识的枚举名，已退回默认值 ' + fallback)
+  return String(fallback)
+}
+
+async function cmdConnect(args) {
+  const m = loadMaa()
+  if (S.ctrl) { try { S.ctrl.destroy() } catch (e) { /* ignore */ } S.ctrl = null }
+  /* 控制器重建 = 旧流失效：显式停掉并在回执里说明（`streamStopped`），别让调用方以为流还在跑。
+   * 曾经的行为是"tick 撞到空控制器后静默死掉、S.stream 仍为 true"，于是重连后的 stream_start 被
+   * "已启动"挡回去，表现为一帧都不来（实测：seq 卡死，而 screencap 正常）。 */
+  const streamStopped = S.stream === true
+  if (S.stream) await cmdStreamStop()
+  S.session = null
+  let ctrl = null
+  let session = null
+  const warns = []
+  if (args.kind === 'adb') {
+    const adbs = (await m.AdbController.find()) || []
+    const addr = args.target || (adbs[0] ? String(adbs[0][2] ?? adbs[0][0]) : null)
+    if (!addr) return { ok: false, error: '未发现 adb 设备，且未提供 address' }
+    const dev = adbs.find((d) => String(d[2] ?? d[0]) === String(addr))
+      ?? (args.target ? null : adbs[0])
+    /* 指定了 address 却不在已发现列表里：明确报错，不静默连到别的设备上 */
+    if (!dev) return { ok: false, error: 'adb 地址 ' + addr + ' 不在已发现设备中（共 ' + adbs.length + ' 台）' }
+    const [name, adbPath, address, caps, inputs, config] = dev
+    ctrl = new m.AdbController(adbPath || 'adb', String(address ?? addr),
+      caps && caps.length ? caps : [1, 2], inputs && inputs.length ? inputs : [1, 2], config || '{}')
+    session = { kind: 'adb', target: String(address ?? addr), name: String(name) }
+  } else if (args.kind === 'win32' || args.kind === 'gamepad') {
+    const wins = await cmdDeviceList('win32')
+    const pick = pickWin32(args.target, wins)
+    if (!pick) {
+      return {
+        ok: false,
+        error: args.target
+          ? 'win32 窗口未找到：' + args.target + '（当前 ' + wins.length + ' 个窗口；hwnd 变了或窗口已关闭）'
+          : '未发现 win32 窗口',
+      }
+    }
+    /* 截图/输入方法：优先用调用方给的（项目驱动路径 = interface.json 声明 + 官方缺省）。
+       缺省值照 maa-support buildControllerRuntime（controller.ts:95-102）的官方解释：
+       screencap=FramePool、mouse=SendMessageWithCursorPos、keyboard=SendMessage。
+       （此前用的 Foreground/SendMessage 是 daemon 自己的历史缺省，项目没声明时会偏离官方行为。） */
+    const cap = resolveEnum(m.Win32ScreencapMethod, args.screencap, m.Win32ScreencapMethod?.FramePool ?? 2, 'screencap', warns)
+    if (args.kind === 'gamepad') {
+      /* GamepadController 构造器签名（maa-node .d.ts）：(hwnd, gamepad_type, screencap_method)。
+         gamepad_type 枚举名→值照 m.GamepadType（Xbox360/DualShock4，缺省 Xbox360）。
+         输入走虚拟手柄，需宿主装 ViGEm Bus Driver，否则 connect 会在原生层失败。 */
+      const padType = resolveEnum(m.GamepadType, args.gamepadType, m.GamepadType?.Xbox360 ?? 0, 'gamepadType', warns)
+      ctrl = new m.GamepadController(pick.id, padType, cap)
+      session = { kind: 'gamepad', target: pick.id, name: pick.name || pick.cls, cls: pick.cls, method: { screencap: cap, gamepadType: padType } }
+    } else {
+      const mouse = resolveEnum(m.Win32InputMethod, args.mouse, m.Win32InputMethod?.SendMessageWithCursorPos ?? 32, 'mouse', warns)
+      const key = resolveEnum(m.Win32InputMethod, args.keyboard, m.Win32InputMethod?.SendMessage ?? 2, 'keyboard', warns)
+      ctrl = new m.Win32Controller(pick.id, cap, mouse, key)
+      session = { kind: 'win32', target: pick.id, name: pick.name || pick.cls, cls: pick.cls, method: { screencap: cap, mouse, keyboard: key } }
+    }
+  } else if (args.kind === 'playcover' || args.kind === 'macos') {
+    /* PlayCover / MacOS 控制器仅 macOS 可用（maa-node 本体在其它平台编译即排除）。
+       非 macOS 宿主不给"也许能连"的尝试，直接说明。 */
+    if (process.platform !== 'darwin') {
+      return { ok: false, error: '控制器类型 ' + args.kind + ' 仅支持在 macOS 上使用；当前宿主是 ' + process.platform }
+    }
+    if (args.kind === 'playcover') {
+      /* PlayCoverController(address, uuid)：address 是 PlayCover 设备侧服务地址（如 127.0.0.1:port），
+         uuid 是 PlayCover 显示的设备 UUID；两个都必须显式给，猜不了。 */
+      const parts = String(args.target ?? '').split('/')
+      const address = parts[0] || ''
+      const uuid = args.uuid ? String(args.uuid) : (parts[1] || '')
+      if (!address || !uuid) {
+        return { ok: false, error: 'playcover 需要 target=<address>/<uuid>（PlayCover 设置里可见，两者都必填）' }
+      }
+      ctrl = new m.PlayCoverController(address, uuid)
+      session = { kind: 'playcover', target: address + '/' + uuid }
+    } else {
+      /* MacOSController(window_id, screencap_method, input_method)：窗口用 MacOSController.find() 枚举。 */
+      const wins = (await m.MacOSController.find()) || []
+      const pick = args.target
+        ? (wins.find((d) => String(d[0]) === String(args.target)) ??
+           wins.find((d) => String(d[2] ?? '').includes(String(args.target))))
+        : (wins[0] ?? null)
+      if (!pick) {
+        return { ok: false, error: args.target ? 'macOS 窗口未找到：' + args.target : '未发现 macOS 窗口' }
+      }
+      const cap = resolveEnum(m.MacOSScreencapMethod, args.screencap, m.MacOSScreencapMethod?.ScreenCaptureKit ?? 2, 'screencap', warns)
+      const input = resolveEnum(m.MacOSScreencapMethod, args.keyboard, m.MacOSScreencapMethod?.ScreenCaptureKit ?? 2, 'keyboard', warns)
+      ctrl = new m.MacOSController(pick.id ?? pick[0], cap, input)
+      session = { kind: 'macos', target: String(pick[0]), name: String(pick[2] ?? ''), method: { screencap: cap, input } }
+    }
+  } else if (args.kind === 'linux') {
+    /* LinuxController(config JSON)：wlroots / PipeWire / uinput / Libei 会话按配置串交给本体。
+       config 必须显式给（含 screencap_method / input_method 等必填字段），工具不猜会话形态。 */
+    if (process.platform !== 'linux') {
+      return { ok: false, error: '控制器类型 linux 仅支持在 Linux 上使用；当前宿主是 ' + process.platform }
+    }
+    const cfg = String(args.config ?? args.target ?? '')
+    if (!cfg.trim().startsWith('{')) {
+      return { ok: false, error: 'linux 控制器需要 config=<JSON>（screencap_method/input_method 必填；wlroots 要 wlr_socket_path，PipeWire 要 pw_socket_fd+pw_node_id 等）' }
+    }
+    ctrl = new m.LinuxController(cfg)
+    session = { kind: 'linux', target: '(config)' }
+  } else {
+    return { ok: false, error: '未知控制器类型：' + args.kind + '（支持 win32/adb/gamepad/playcover/macos/linux）' }
+  }
+  /* 截图缩放目标：默认不干预 —— maafw 本体按 interface.json 的 short_side（缺省最短边 720p）缩放。
+   * 只有用户显式传参才覆盖；注意这会改变 Tasker 识别图像的尺寸（模板/ROI 坐标系随之变化）。 */
+  try {
+    if (args.shortSide) ctrl.screenshot_target_short_side = Number(args.shortSide)
+    if (args.longSide) ctrl.screenshot_target_long_side = Number(args.longSide)
+    if (args.rawSize) ctrl.screenshot_use_raw_size = true
+  } catch (e) { /* 绑定版本不支持 setter 时忽略 */ }
+  S.ctrl = ctrl
+  await ctrl.post_connection().wait()
+  S.session = session
+  S.connGen++
+  /* 预热一次截图，取控制器分辨率（默认短边 720 的坐标系，pipeline 的 roi/模板即此空间） */
+  let res = null
+  try {
+    const j = ctrl.post_screencap(); await j.wait()
+    const buf = j.get()
+    if (buf && buf.byteLength > 8) {
+      const dec = pngDecode(Buffer.from(buf))
+      S.fullW = dec.w; S.fullH = dec.h
+      res = { w: dec.w, h: dec.h, bytes: buf.byteLength }
+    }
+  } catch (e) { res = { error: String(e.message) } }
+  return {
+    ok: true,
+    session: { ...session, resolution: res, ...(warns.length ? { warns } : {}) },
+    /* 重连会重建控制器 → 旧流已停；调用方要接着看帧就得重新 stream_start（回执里说清楚，不靠猜） */
+    ...(streamStopped ? { streamStopped: true } : {}),
+  }
+}
+
+async function cmdDisconnect() {
+  if (S.stream) await cmdStreamStop()
+  await cleanupAgents()
+  if (S.tasker) { try { S.tasker.destroy() } catch (e) { /* ignore */ } S.tasker = null }
+  if (S.ctrl) { try { S.ctrl.destroy() } catch (e) { /* ignore */ } S.ctrl = null }
+  S.session = null
+  return { ok: true }
+}
+
+async function cmdScreencap(outFile) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备（先 maa_connect）' }
+  const j = S.ctrl.post_screencap()
+  await j.wait()
+  const buf = j.get()
+  if (!buf || buf.byteLength < 8) return { ok: false, error: '截图为空' }
+  const b = Buffer.from(buf)
+  const dec = pngDecode(b)
+  /* 截图也是一次观测：进环、进 L0（有捕获身份，可被 kf promote --seq 指定升格） */
+  pushFrame(dec, b)
+  const d = defaultOutFile(S.runDir, 'screencap');
+  const file = outFile || d.file
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, b)
+  return { ok: true, path: file, bytes: b.length, w: dec.w, h: dec.h, seq: S.seq }
+}
+
+/* ────────────────────────── 帧流（自适应节奏 + 事件合并） ────────────────────────── */
+/** 变化块的联合 bbox：小图坐标 + 控制器坐标（8×8 网格，块边界按小图像素取整，外扩不收缩） */
+function regionOfBlocks(blocks, w, h, fw, fh) {
+  let bx0 = 8, by0 = 8, bx1 = -1, by1 = -1
+  for (const k of blocks) {
+    const bx = k % 8, by = (k / 8) | 0
+    if (bx < bx0) bx0 = bx
+    if (by < by0) by0 = by
+    if (bx > bx1) bx1 = bx
+    if (by > by1) by1 = by
+  }
+  const x0 = Math.round(bx0 * w / 8), y0 = Math.round(by0 * h / 8)
+  const x1 = Math.round((bx1 + 1) * w / 8), y1 = Math.round((by1 + 1) * h / 8)
+  const sx = fw > 0 ? fw / w : 1, sy = fh > 0 ? fh / h : 1
+  return {
+    small: [x0, y0, x1 - x0, y1 - y0],
+    ctrl: [Math.round(x0 * sx), Math.round(y0 * sy), Math.round((x1 - x0) * sx), Math.round((y1 - y0) * sy)],
+  }
+}
+
+/** L0 锚区入队（按 seq 去重：同一捕获可能既是滚动帧又是事件锚点，字节共用同一 Buffer）。
+ * relabel：显式来源（动作边界/节点锚点）覆盖同帧已被事件路径标上的 change/stable——
+ * 一个捕获一个锚点，但标签以显式意图为准。 */
+function l0AnchorAdd(entry, relabel = false) {
+  const existing = S.l0.anchor.find((x) => x.seq === entry.seq)
+  if (existing) {
+    if (relabel && entry.source) existing.source = entry.source
+    return
+  }
+  S.l0.anchor.push(entry)
+  if (S.l0.anchor.length > S.l0.anchorCap) S.l0.anchor.splice(0, S.l0.anchor.length - S.l0.anchorCap)
+  l0EvictToBudget()
+}
+
+/** 字节预算淘汰：唯一 seq 去重计总字节，超限先淘汰滚动区最旧、仍超再淘汰锚区最旧。 */
+function l0EvictToBudget() {
+  const cap = S.l0.bytesCap
+  if (!(cap > 0)) return
+  const bytesOf = (e) => (e.png ? e.png.length : 0)
+  let total = 0
+  const seen = new Set()
+  for (const e of S.l0.roll) if (!seen.has(e.seq)) { seen.add(e.seq); total += bytesOf(e) }
+  for (const e of S.l0.anchor) if (!seen.has(e.seq)) { seen.add(e.seq); total += bytesOf(e) }
+  while (total > cap) {
+    const r0 = S.l0.roll[0]
+    if (r0) {
+      S.l0.roll.shift()
+      if (!S.l0.anchor.some((x) => x.seq === r0.seq)) total -= bytesOf(r0)
+    } else if (S.l0.anchor.length) {
+      total -= bytesOf(S.l0.anchor.shift())
+    } else break
+    S.l0.evicted++
+  }
+}
+
+/**
+ * 一次捕获的统一入口：原图字节先进 L0（先存后解，不解码即落袋），观测面再解码进环。
+ * png 是控制器交付的原始 PNG 字节（不解码、不重编码）；dec 是它解码后的观测数据。
+ */
+function pushFrame(dec, png) {
+  const rgb = toRgb(dec)
+  const small = downscale(rgb, dec.w, dec.h, S.streamScale)
+  const { hash, means } = blockAnalyze(small.data, small.w, small.h)
+  const prev = S.ring.length ? S.ring[S.ring.length - 1] : null
+  const diff = prev ? hashDist(prev.hash, hash) : 0
+  S.seq++
+  const fr = { seq: S.seq, t: Date.now(), rgb: small.data, w: small.w, h: small.h, fw: dec.w, fh: dec.h, hash, means, diff }
+  S.ring.push(fr)
+  if (S.ring.length > S.maxFrames) S.ring.shift()
+  S.fullW = dec.w; S.fullH = dec.h
+  const l0 = { seq: fr.seq, t: fr.t, png, w: dec.w, h: dec.h }
+  S.l0.roll.push(l0)
+  if (S.l0.roll.length > S.l0.rollCap) S.l0.roll.splice(0, S.l0.roll.length - S.l0.rollCap)
+  l0EvictToBudget()
+  const meta = { seq: fr.seq, t: fr.t, hash: hashStr(hash), diff: Math.round(diff * 1000) / 1000, w: fr.w, h: fr.h }
+  S.framesMeta.push(meta)
+  if (S.framesMeta.length > 2000) S.framesMeta.splice(0, S.framesMeta.length - 2000)
+  /* 预览帧落盘（原子替换）：面板 HTTP 直读，避免二进制走 JSON 行协议 */
+  const preview = pngEncodeRGB(small.data, small.w, small.h)
+  if (S.previewPath) {
+    const tmp = S.previewPath + '.tmp'
+    try { fs.writeFileSync(tmp, preview); fs.renameSync(tmp, S.previewPath) } catch (e) { /* 落盘失败不致命 */ }
+  }
+  send({ kind: 'frame', meta, preview: S.previewPath })
+  /* 变化 / 稳定事件（400ms 窗口合并）；锚区只收"新事件"的首帧，合并窗口内不重复入锚。
+   * 双阈值：全局位差率管分布式小变化，分块亮度差管局部小区域变化（小区域位差占比低，
+   * 单看全局阈值会漏检且漏检导致降频加剧漏检）。变化事件携带变化区域 bbox（小图与控制器两套坐标）。 */
+  let changed = null
+  if (prev && means) {
+    const blocks = []
+    for (let k = 0; k < 64; k++) {
+      if (Math.abs(means[k] - prev.means[k]) > S.blockThresh) blocks.push(k)
+    }
+    if (blocks.length) changed = { blocks, region: regionOfBlocks(blocks, fr.w, fr.h, fr.fw, fr.fh) }
+  }
+  const isChange = diff > S.changeGlobal || changed !== null
+  if (isChange) {
+    S.quietNow = false
+    const last = S.events.length ? S.events[S.events.length - 1] : null
+    if (last && last.type === 'change' && fr.t - last.t < 400) {
+      last.t = fr.t; last.seq = fr.seq; last.diff = Math.max(last.diff, diff)
+    } else {
+      pushEvent({
+        type: 'change', seq: fr.seq, t: fr.t, diff: Math.round(diff * 1000) / 1000,
+        ...(changed ? { blocks: changed.blocks.length, region: changed.region } : {}),
+      })
+      l0AnchorAdd({ ...l0, source: 'change' })
+    }
+  } else if (prev) {
+    if (!S.quietNow) {
+      S.quietNow = true
+      pushEvent({ type: 'stable', seq: fr.seq, t: fr.t, diff: Math.round(diff * 1000) / 1000 })
+      l0AnchorAdd({ ...l0, source: 'stable' })
+    }
+  }
+}
+/**
+ * 主动抓一张原图并入观测流（seq 前进、进环、进 L0，可作动作/run 边界锚点）。
+ * 采集失败如实上报，绝不阻断调用方的动作——动作结果与留存失败分别报告（契约 §9）。
+ */
+async function captureNow(source) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备' }
+  try {
+    const j = S.ctrl.post_screencap()
+    await j.wait()
+    const buf = j.get()
+    if (!buf || buf.byteLength < 8) return { ok: false, error: '空截图' }
+    const b = Buffer.from(buf)
+    const dec = pngDecode(b)
+    pushFrame(dec, b)
+    const ent = S.l0.roll[S.l0.roll.length - 1]
+    l0AnchorAdd({ ...ent, source }, true)
+    return { ok: true, seq: ent.seq, t: ent.t, w: ent.w, h: ent.h }
+  } catch (e) {
+    return { ok: false, error: String(e && e.message || e) }
+  }
+}
+
+/**
+ * 用控制器缓存图入锚区（node-ok/fail 锚点的实现方式）。
+ * 关键约束：不要在节点回调里发 post_screencap——add_sink 回调中并发截图会与 Tasker
+ * 识别回路竞争控制器，实测触发原生崩溃 0xC0000005（maa-node 5.14.2 win32-x64，
+ * 2026-10-05 真机：同任务关锚点正常 / 开锚点必崩）。
+ * cached_image 是框架识别回路自己截的图：零新任务、无竞争，且节点回调时刻的缓存
+ * 通常就是该节点识别所用的那张（bound 倾向）；但下一节点识别可能已刷新缓存，
+ * 关联强度按 adjacent 报，不冒称 bound（契约 §4）。 */
+function anchorFromCache(source) {
+  if (!S.ctrl) return
+  let img = null
+  try { img = S.ctrl.cached_image } catch (e) { return }
+  if (!img || img.byteLength < 9) return
+  const b = Buffer.from(img)
+  let dec = null
+  try { dec = pngDecode(b) } catch (e) { return }
+  pushFrame(dec, b)
+  const ent = S.l0.roll[S.l0.roll.length - 1]
+  l0AnchorAdd({ ...ent, source }, true)
+}
+/** 事件入环 + 推送 host（cap 1200） */
+function pushEvent(ev) {
+  S.events.push(ev)
+  if (S.events.length > 1200) S.events.splice(0, S.events.length - 1200)
+  send({ kind: 'event', ev })
+}
+
+async function streamTick() {
+  /* 控制器没了（典型：connect 会先销毁旧 Controller 再重建）时**必须把流的开关也关掉**：
+   * 只 return 不排期会让循环静默死掉，而 S.stream 仍是 true → 之后的 stream_start 被"已启动"挡回去，
+   * 表现为"重连后一帧都不来"（实测：seq 卡死、screencap 却正常）。 */
+  if (!S.ctrl) {
+    S.stream = false
+    if (S.streamTimer) { clearTimeout(S.streamTimer); S.streamTimer = null }
+    send({ kind: 'stream_stopped', reason: '控制器已销毁（connect 会重建控制器，需要时重新 stream_start）' })
+    return
+  }
+  if (!S.stream) return
+  const t0 = Date.now()
+  try {
+    const j = S.ctrl.post_screencap()
+    await j.wait()
+    const buf = j.get()
+    if (buf && buf.byteLength > 8) pushFrame(pngDecode(Buffer.from(buf)), Buffer.from(buf))
+  } catch (e) {
+    send({ kind: 'stream_error', error: String(e && e.message || e) })
+  }
+  if (!S.stream) return
+  const elapsed = Date.now() - t0
+  const recent = S.ring.slice(-3)
+  const quiet = S.quietNow || (recent.length >= 2 && recent.every((r) => r.diff <= S.changeGlobal))
+  const wait = quiet ? 1000 : Math.max(60, Math.round(1000 / Math.max(1, S.streamFps)))
+  S.streamTimer = setTimeout(streamTick, Math.max(0, wait - elapsed))
+}
+
+async function cmdStreamStart(args) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备（先 maa_connect）' }
+  if (args.fps) S.streamFps = Math.min(30, Math.max(1, Number(args.fps)))
+  if (args.scale) S.streamScale = Math.min(1280, Math.max(160, Number(args.scale)))
+  if (args.maxFrames) S.maxFrames = Math.min(600, Math.max(20, Number(args.maxFrames)))
+  if (args.l0Roll) S.l0.rollCap = Math.min(64, Math.max(1, Number(args.l0Roll)))
+  if (args.l0Anchor) S.l0.anchorCap = Math.min(128, Math.max(1, Number(args.l0Anchor)))
+  if (args.l0Bytes !== undefined) S.l0.bytesCap = Math.max(0, Number(args.l0Bytes))
+  if (args.blockThresh !== undefined) S.blockThresh = Math.min(64, Math.max(1, Number(args.blockThresh)))
+  if (args.changeGlobal !== undefined) S.changeGlobal = Math.min(1, Math.max(0.005, Number(args.changeGlobal)))
+  if (!S.stream) {
+    S.stream = true
+    S.quietNow = false
+    S.streamTimer = setTimeout(streamTick, 0)
+  }
+  return {
+    ok: true, fps: S.streamFps, scale: S.streamScale, maxFrames: S.maxFrames,
+    l0Roll: S.l0.rollCap, l0Anchor: S.l0.anchorCap,
+    blockThresh: S.blockThresh, changeGlobal: S.changeGlobal,
+  }
+}
+async function cmdStreamStop() {
+  S.stream = false
+  if (S.streamTimer) { clearTimeout(S.streamTimer); S.streamTimer = null }
+  return { ok: true }
+}
+function cmdStreamStatus() {
+  return {
+    ok: true, running: S.stream, fps: S.streamFps, scale: S.streamScale,
+    maxFrames: S.maxFrames, seq: S.seq, ring: S.ring.length,
+    events: S.events.length, full: S.fullW ? [S.fullW, S.fullH] : null,
+    session: S.session,
+  }
+}
+
+/* ────────────────────────── 历史帧取用（ROI 裁剪，像素按需出 worker） ────────────────────────── */
+/**
+ * roi 参数校验：只接受 4 个**有限数字**。
+ * 非数字会一路传成 NaN 框——`Math.max(0, Math.floor(NaN))` 还是 NaN，于是要么静默错剪一块、
+ * 要么在下游报一个跟病因无关的错（"越界"/"参数类型"）。与 tpl_crop 的 `roi/point/pad` 校验同一口径。
+ * 返回 `{ roi: null }` 表示"没给 roi"（调用方按整帧处理）。
+ */
+function readRoi(raw) {
+  if (raw === undefined || raw === null) return { roi: null }
+  if (!Array.isArray(raw) || raw.length !== 4) {
+    return { error: 'roi 必须是 4 个数字 [x,y,w,h]，收到 ' + JSON.stringify(raw) }
+  }
+  const roi = raw.map(Number)
+  if (!roi.every((v) => Number.isFinite(v))) {
+    /* 只拦 NaN（非数字字符串、对象等）。**`null` 会被 Number(null) 收成 0**，那是"合法的退化框"，
+     * 由下游夹取兜住——与 tpl_crop 的 roi/point/pad 校验同一口径（拦 NaN，不拦 0）。 */
+    return { error: 'roi 必须是数字（非数字字符串这类会退化成 NaN）：' + JSON.stringify(raw) }
+  }
+  return { roi }
+}
+
+/** L0（滚动区 + 锚区）里按 seq 找全分辨率原图；命中即拿到控制器分辨率的 1:1 像素。
+ * 两条区共用同一份 Buffer 时按 seq 去重，所以先滚后锚即可。 */
+function findL0(seq) {
+  return S.l0.roll.find((e) => e.seq === seq) || S.l0.anchor.find((e) => e.seq === seq) || null
+}
+
+function cmdFrameGet(args) {
+  let fr = null
+  if (args.seq === undefined || args.seq === null) fr = S.ring[S.ring.length - 1]
+  else fr = S.ring.find((r) => r.seq === Number(args.seq))
+  if (!fr) return { ok: false, error: '帧不在缓冲中（seq=' + args.seq + '，范围 ' + (S.ring[0] ? S.ring[0].seq : 0) + '..' + S.seq + '）' }
+  const outFile = args.out || defaultOutFile(S.runDir, 'frame-' + fr.seq).file
+  const roiIn = readRoi(args.roi)
+  if (roiIn.error) return { ok: false, error: roiIn.error }
+
+  /* `src` 决定像素从哪来——**降采样必须是显式选择，不能是静默降级**：
+   *   auto(缺省) ROI 先试 L0 全分辨率原图，淘汰了才退环形缓冲并如实标注；
+   *   full       只要全分辨率；L0 已淘汰就报错，绝不给一张缩小图冒充；
+   *   ring       强制走环形缓冲小图（旧行为，供面板等已知消费方）。
+   * 回执一律带 source / sourceResolution：调用方不必猜手里这张图是什么分辨率。 */
+  const src = String(args.src ?? 'auto').toLowerCase()
+  const wantRing = src === 'ring' || src === 'l1'
+  const wantFull = src === 'full' || src === 'l0'
+  if (!wantRing && !wantFull && src !== 'auto') {
+    return { ok: false, error: 'src 只支持 auto | full | ring，收到 ' + JSON.stringify(args.src) }
+  }
+  const l0hit = wantRing ? null : findL0(fr.seq)
+  let full = null
+  if (l0hit) {
+    try {
+      const dec = pngDecode(l0hit.png)
+      full = { dec, w: dec.w, h: dec.h }
+    } catch (e) { full = null }
+  }
+  const l0Gone = () => 'L0 全分辨率原图已淘汰（seq=' + fr.seq + '）：滚动区 ' + S.l0.roll.length
+    + ' 帧 / 锚区 ' + S.l0.anchor.length + ' 帧，实测 10fps 下滚动窗口约 1.6 秒。'
+    + '要全分辨率就在截图后立刻取 ROI，或先 kf promote 留存该帧再从库帧裁。'
+
+  if (roiIn.roi) {
+    const [x, y, w, h] = roiIn.roi
+    if (full) {
+      /* 控制器分辨率 1:1 裁剪：roi 本来就是控制器空间坐标，无需换算。 */
+      const rx = Math.max(0, Math.floor(x))
+      const ry = Math.max(0, Math.floor(y))
+      const rw = Math.min(full.w - rx, Math.max(1, Math.round(w)))
+      const rh = Math.min(full.h - ry, Math.max(1, Math.round(h)))
+      if (rx >= full.w || ry >= full.h || rw <= 0 || rh <= 0) {
+        return { ok: false, error: 'ROI 完全越界（' + JSON.stringify(args.roi) + ' vs 捕获时 ' + full.w + 'x' + full.h + '）' }
+      }
+      const src0 = toRgb(full.dec)
+      const crop = Buffer.alloc(rw * rh * 3)
+      for (let yy = 0; yy < rh; yy++) {
+        src0.copy(crop, yy * rw * 3, ((ry + yy) * full.w + rx) * 3, ((ry + yy) * full.w + rx + rw) * 3)
+      }
+      fs.mkdirSync(path.dirname(outFile), { recursive: true })
+      fs.writeFileSync(outFile, pngEncodeRGB(crop, rw, rh))
+      return {
+        ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: rw, h: rh,
+        seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: full.w, ctrlH: full.h,
+        source: 'l0-full', sourceResolution: 1, degraded: false,
+        requested: { w, h },
+      }
+    }
+    if (wantFull) return { ok: false, error: l0Gone() }
+    /* 降级：环形缓冲小图。按**该帧捕获时**尺寸换算（重连/改分辨率后旧帧会被错剪）。 */
+    const sx = fr.fw > 0 ? fr.w / fr.fw : 1
+    const sy = fr.fh > 0 ? fr.h / fr.fh : 1
+    const rx = Math.max(0, Math.floor(x * sx))
+    const ry = Math.max(0, Math.floor(y * sy))
+    const rw = Math.min(fr.w - rx, Math.max(1, Math.round(w * sx)))
+    const rh = Math.min(fr.h - ry, Math.max(1, Math.round(h * sy)))
+    if (rx >= fr.w || ry >= fr.h || rw <= 0 || rh <= 0) {
+      return { ok: false, error: 'ROI 完全越界（' + JSON.stringify(args.roi) + ' vs 捕获时 ' + fr.fw + 'x' + fr.fh + '）' }
+    }
+    const crop = Buffer.alloc(rw * rh * 3)
+    for (let yy = 0; yy < rh; yy++) {
+      fr.rgb.copy(crop, yy * rw * 3, ((ry + yy) * fr.w + rx) * 3, ((ry + yy) * fr.w + rx + rw) * 3)
+    }
+    fs.mkdirSync(path.dirname(outFile), { recursive: true })
+    fs.writeFileSync(outFile, pngEncodeRGB(crop, rw, rh))
+    return {
+      ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: rw, h: rh,
+      seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: fr.fw, ctrlH: fr.fh,
+      source: 'l1-ring', sourceResolution: sx,
+      requested: { w, h },
+      /* `degraded` 是**相对"调用方要什么"**的判断，不是"分辨率是否小于 1"：
+       * 带 roi 且 auto 时，调用方要的是控制器空间的 ROI，退成小图就是真降级（附 warn、判 findings）；
+       * 显式 ring 是小图预期，不算降级。整帧路径另有约定（见下）。 */
+      degraded: !wantRing,
+      ...(wantRing ? {} : {
+        warn: 'L0 全分辨率原图不可用，本图由环形缓冲小图裁出，有效分辨率 ' + (1 / sx).toFixed(3) + '×'
+          + '（请求 ' + w + 'x' + h + '，实得 ' + rw + 'x' + rh + '）。' + l0Gone(),
+      }),
+    }
+  }
+
+  /* 整帧导出：**只有显式 `full` 才导 L0 原图**。
+   * 为什么不给 auto 也导原图：整帧 `auto` 的既有契约就是"环形缓冲那一帧"，把它悄悄换成
+   * 1280×720 既改了这个最常见调用的产物尺寸（消费方按小图写的代码会突然拿到大图），
+   * 也与协议文档的迁移承诺冲突——本次行为变更**只限带 `roi` 的缺省路径**。
+   * 要整帧原图就显式 `--src full`（L0 淘汰则报错，不冒充）。 */
+  if (full && wantFull) {
+    fs.mkdirSync(path.dirname(outFile), { recursive: true })
+    fs.writeFileSync(outFile, pngEncodeRGB(toRgb(full.dec), full.w, full.h))
+    return {
+      ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: full.w, h: full.h,
+      seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: full.w, ctrlH: full.h,
+      source: 'l0-full', sourceResolution: 1,
+    }
+  }
+  if (wantFull) return { ok: false, error: l0Gone() }
+  fs.mkdirSync(path.dirname(outFile), { recursive: true })
+  fs.writeFileSync(outFile, pngEncodeRGB(fr.rgb, fr.w, fr.h))
+  const sx0 = fr.fw > 0 ? fr.w / fr.fw : 1
+  return {
+    ok: true, path: outFile, bytes: fs.statSync(outFile).size, w: fr.w, h: fr.h,
+    seq: fr.seq, t: fr.t, diff: fr.diff, ctrlW: fr.fw, ctrlH: fr.fh,
+    source: 'l1-ring', sourceResolution: sx0,
+    /* 整帧小图是**文档写明的缺省行为**，不是降级：只标注来源与分辨率，不警告、不判 findings——
+     * 否则最普通的 `frame get`（不带 roi）会时不时退 3。要原图就显式 `--src full`。 */
+    degraded: false,
+  }
+}
+
+/* ────────────────────────── 状态谓词：等到条件成立，而不是让调用方睡死 ──────────────────────────
+ * 为什么要有它：没有"什么时候可以读了"的可查询谓词，调用方只能用时钟猜。本案实测代价：
+ * 硬睡 39 次共 155 秒，而且**等了也不保证对**——抓到过渡帧并据此误判"还在大厅"。
+ * 判据复用帧流同一套（最近 quietMs 内有无 change 事件 + 可选 ROI 内逐帧均值差），不另立阈值口径。 */
+
+/** ROI（控制器空间）内两帧的平均亮度差；坐标按该帧捕获时尺寸换算。 */
+function roiMeanDiff(a, b, roi) {
+  if (!a || !b || a.w !== b.w || a.h !== b.h) return null
+  const sx = a.fw > 0 ? a.w / a.fw : 1
+  const sy = a.fh > 0 ? a.h / a.fh : 1
+  const x0 = Math.max(0, Math.floor(roi[0] * sx))
+  const y0 = Math.max(0, Math.floor(roi[1] * sy))
+  const x1 = Math.min(a.w, Math.ceil((roi[0] + roi[2]) * sx))
+  const y1 = Math.min(a.h, Math.ceil((roi[1] + roi[3]) * sy))
+  if (x1 <= x0 || y1 <= y0) return null
+  let sum = 0, n = 0
+  for (let y = y0; y < y1; y++) {
+    for (let x = x0; x < x1; x++) {
+      const i = (y * a.w + x) * 3
+      sum += Math.abs(a.rgb[i] - b.rgb[i]) + Math.abs(a.rgb[i + 1] - b.rgb[i + 1]) + Math.abs(a.rgb[i + 2] - b.rgb[i + 2])
+      n += 3
+    }
+  }
+  return n > 0 ? sum / n : null
+}
+
+async function cmdWait(args) {
+  const mode = String(args.mode ?? 'stable') === 'change' ? 'change' : 'stable'
+  const timeout = Math.min(120000, Math.max(200, Number(args.timeout ?? 10000)))
+  const quietMs = Math.min(10000, Math.max(100, Number(args.quiet ?? 600)))
+  const thr = Number(args.threshold ?? 3)
+  const roiIn = readRoi(args.roi)
+  if (roiIn.error) return { ok: false, error: roiIn.error }
+  /* 一帧都没有就别空转到超时再报"画面持续变化"——那是**假原因**，会让人去调阈值。
+   * 与 frame_get 同一口径：先要观测。 */
+  if (!S.ring.length) {
+    return {
+      ok: false,
+      error: '缓冲无任何帧：wait 判的是帧流（变化事件 / ROI 逐帧均值差），没有帧就无从判断稳定与否。先 screencap 或 stream start 产生观测。',
+    }
+  }
+  const t0 = Date.now()
+  let lastPairSeq = null
+  let lastDiff = null
+  while (Date.now() - t0 < timeout) {
+    const n = S.ring.length
+    const cur = n ? S.ring[n - 1] : null
+    const prev = n > 1 ? S.ring[n - 2] : null
+    if (!cur) { await sleep(80); continue }
+    if (roiIn.roi && prev && prev.seq !== lastPairSeq) {
+      lastPairSeq = prev.seq
+      const d = roiMeanDiff(prev, cur, roiIn.roi)
+      if (d !== null) lastDiff = d
+    }
+    const recentChange = S.events.some((e) => e.type === 'change' && Date.now() - e.t < quietMs)
+    const roiMoving = roiIn.roi ? (lastDiff !== null && lastDiff >= thr) : false
+    const moving = recentChange || roiMoving
+    if (mode === 'stable' ? !moving : moving) {
+      return {
+        ok: true, mode, satisfied: true, waitedMs: Date.now() - t0, seq: cur.seq, quietMs,
+        ...(roiIn.roi ? { roi: roiIn.roi, threshold: thr, lastRoiMeanDiff: lastDiff } : {}),
+        ...(mode === 'change' ? { note: '画面已动（change 事件或 ROI 均值差超阈）——注意这只说明"动了"，不说明"到了目标界面"；到了哪一屏要用识别或留存帧复核' } : {}),
+      }
+    }
+    await sleep(100)
+  }
+  const cur = S.ring.length ? S.ring[S.ring.length - 1] : null
+  return {
+    ok: true, mode, satisfied: false, waitedMs: Date.now() - t0, timeout, seq: cur ? cur.seq : null,
+    ...(roiIn.roi ? { roi: roiIn.roi, threshold: thr, lastRoiMeanDiff: lastDiff } : {}),
+    warn: mode === 'stable'
+      ? '超时仍未稳定（' + timeout + 'ms 内持续变化）：目标界面可能本来就在动（动画/加载/字幕），或阈值偏严——先 calibrate 定噪声地板再起流。'
+      : '超时仍未见变化：画面在这段时间内没动过。先确认目标是否已经在该界面，或动作是否真的生效（比对动作回执的 retention.before/after）。',
+  }
+}
+
+/** 两帧在若干 ROI 上的差分：回答"这一步究竟改了哪几格 / 哪几块"。
+ * 帧流事件给的是"整帧哪里变了"，而离散网格（棋盘 / 背包 / 技能格）要的是"每格变了多少"——
+ * 本案要用它判断"一次拖动选中了哪几格"，当时只能自己写脚本逐格比对。 */
+function cmdFrameDiff(args) {
+  const a = S.ring.find((r) => r.seq === Number(args.a))
+  const b = S.ring.find((r) => r.seq === Number(args.b))
+  if (!a || !b) {
+    return { ok: false, error: '帧不在缓冲中（a=' + args.a + ' b=' + args.b + '，范围 ' + (S.ring[0] ? S.ring[0].seq : 0) + '..' + S.seq + '）' }
+  }
+  if (a.w !== b.w || a.h !== b.h) {
+    return { ok: false, error: '两帧尺寸不同（' + a.w + 'x' + a.h + ' vs ' + b.w + 'x' + b.h + '）：不能直接比' }
+  }
+  const rois = Array.isArray(args.rois) ? args.rois : []
+  if (!rois.length) return { ok: false, error: 'rois 要给数组：[[x,y,w,h],...]（控制器空间坐标）' }
+  const sx = a.fw > 0 ? a.w / a.fw : 1
+  const sy = a.fh > 0 ? a.h / a.fh : 1
+  const out = []
+  for (const r of rois) {
+    const roi = (Array.isArray(r) ? r : [r.x, r.y, r.w, r.h]).map(Number)
+    if (roi.length !== 4 || !roi.every(Number.isFinite)) { out.push({ roi: r, error: 'roi 必须是 4 个数字' }); continue }
+    const x0 = Math.max(0, Math.floor(roi[0] * sx))
+    const y0 = Math.max(0, Math.floor(roi[1] * sy))
+    const x1 = Math.min(a.w, Math.ceil((roi[0] + roi[2]) * sx))
+    const y1 = Math.min(a.h, Math.ceil((roi[1] + roi[3]) * sy))
+    if (x1 <= x0 || y1 <= y0) { out.push({ roi, error: '完全越界' }); continue }
+    let sum = 0, n = 0, mx = 0
+    for (let y = y0; y < y1; y++) {
+      for (let x = x0; x < x1; x++) {
+        const i = (y * a.w + x) * 3
+        const d = (Math.abs(a.rgb[i] - b.rgb[i]) + Math.abs(a.rgb[i + 1] - b.rgb[i + 1]) + Math.abs(a.rgb[i + 2] - b.rgb[i + 2])) / 3
+        sum += d; n++
+        if (d > mx) mx = d
+      }
+    }
+    out.push({ roi, meanDiff: n ? Math.round((sum / n) * 100) / 100 : null, maxDiff: Math.round(mx * 100) / 100, pixels: n })
+  }
+  const rank = out.filter((o) => typeof o.meanDiff === 'number').slice().sort((p, q) => q.meanDiff - p.meanDiff)
+  return {
+    ok: true, a: a.seq, b: b.seq, dtMs: Math.abs((b.t || 0) - (a.t || 0)),
+    rois: out, ranked: rank.map((o) => o.roi), sourceResolution: sx,
+    note: 'meanDiff 是 0..255 的平均亮度差，量级随画面内容变；判"变了/没变"的闸门请先用静止画面实测（同 calibrate 的思路）。',
+  }
+}
+
+/* ────────────────────────── 资源 / 运行 / 识别 ────────────────────────── */
+async function ensureResource(dir) {
+  if (!S.res) {
+    const m = loadMaa()
+    S.res = new m.Resource()
+  }
+  if (dir) await S.res.post_bundle(dir).wait()
+  return S.res
+}
+/**
+ * 项目驱动的多路径资源：interface.json 的 resource.path[] + attach_resource_path
+ * 按顺序叠加、后者覆盖前者（MaaPiCli Configurator 的语义），对应逐个 post_bundle。
+ * 每次运行都新建 Resource——复用旧实例会把上一次运行的 bundle 残留进来
+ * （比如上次加载了皮肤包这次没选，残留会让 override 关系错乱）。
+ */
+async function buildResource(dirs) {
+  const m = loadMaa()
+  const res = new m.Resource()
+  for (const d of dirs) await res.post_bundle(d).wait()
+  return res
+}
+function ensureTasker() {
+  if (!S.tasker) {
+    const m = loadMaa()
+    S.tasker = new m.Tasker()
+  }
+  return S.tasker
+}
+
+/* ────────────────────────── agent 桥接（PI agent 子进程） ──────────────────────────
+ * 模式照 maa-support-extension 的 setupAgent：new Client() 自动生成 identifier，
+ * 把 identifier 追加为子进程最后一个参数（agent 侧 sys.argv[-1] → AgentServer.start_up），
+ * bind_resource 后 connect（与子进程退出/超时竞速）。custom action/recognition 经此
+ * 注册进绑定的 Resource——依赖 agent 的节点（M9A DisableNode 等）由此可用。 */
+async function cleanupAgents() {
+  const bind = S.agentBind
+  S.agentBind = null
+  if (!bind) return
+  for (const c of bind.clients) {
+    try { c.client.disconnect() } catch (e) { /* ignore */ }
+    try { c.client.destroy() } catch (e) { /* ignore */ }
+    try { c.child.kill() } catch (e) { /* ignore */ }
+  }
+}
+
+async function setupAgents(res, decls, cwd) {
+  const key = JSON.stringify(decls)
+  if (S.agentBind && S.agentBind.res === res && S.agentBind.key === key) {
+    const alive = S.agentBind.clients.every((c) => {
+      try { return c.client.connected && c.client.alive } catch (e) { return false }
+    })
+    if (alive) return { ok: true, reused: true, clients: S.agentBind }
+  }
+  await cleanupAgents()
+  const m = loadMaa()
+  const clients = []
+  for (const d of decls) {
+    const client = new m.Client()
+    const ident = client.identifier
+    let child = null
+    try {
+      child = spawn(d.exec, [...d.args, ident], { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    } catch (e) {
+      try { client.destroy() } catch (e2) { /* ignore */ }
+      return { ok: false, error: 'agent 子进程启动失败：' + d.exec + '（' + String(e && e.message || e) + '）' }
+    }
+    let out = ''
+    const feed = (b) => { out = (out + String(b)).slice(-4000) }
+    child.stdout?.on('data', feed)
+    child.stderr?.on('data', feed)
+    try { client.timeout = 60000 } catch (e) { /* 绑定不支持时用默认 */ }
+    try { client.bind_resource(res) } catch (e) {
+      try { child.kill() } catch (e2) { /* ignore */ }
+      try { client.destroy() } catch (e2) { /* ignore */ }
+      return { ok: false, error: 'agent 绑定资源失败：' + String(e && e.message || e) }
+    }
+    const exited = new Promise((r) => child.on('exit', () => r('exit')))
+    const ok = await Promise.race([
+      client.connect().then(() => 'ok', () => 'err'),
+      exited,
+      sleep(60000).then(() => 'timeout'),
+    ])
+    /* connect() resolve 不代表可用：协议版本错配（maa-node 与 agent 侧 maa 版本不一致）时
+     * 通道建立但握手被拒——必须复核 connected && alive（maa-support 同款检查）。 */
+    let usable = ok === 'ok'
+    if (usable) {
+      try { usable = client.connected === true && client.alive === true } catch (e) { usable = false }
+    }
+    if (!usable) {
+      const why = ok === 'exit' ? '子进程提前退出' : (ok === 'timeout' ? '连接超时（60s）' : '连接失败/握手被拒（版本错配？maa-node 与 agent 侧 maa 库需同版本）')
+      try { client.disconnect() } catch (e) { /* ignore */ }
+      try { client.destroy() } catch (e) { /* ignore */ }
+      try { child.kill() } catch (e) { /* ignore */ }
+      return { ok: false, error: 'agent ' + why + '：' + [d.exec, ...d.args].join(' ') + '；输出尾部：' + out.slice(-300) }
+    }
+    clients.push({ client, child, name: [d.exec, ...d.args].join(' '), out })
+  }
+  S.agentBind = { res, key, clients }
+  let actions = null
+  let recos = null
+  try { actions = clients[0].client.custom_action_list } catch (e) { /* ignore */ }
+  try { recos = clients[0].client.custom_recognition_list } catch (e) { /* ignore */ }
+  return { ok: true, clients: S.agentBind, actions, recos }
+}
+
+const sab = new Int32Array(new SharedArrayBuffer(4))
+/**
+ * 节点名取哪个字段：框架在 `PipelineNode.*` 的**顶层 `name` 上填的是任务入口名**，
+ * 真节点名在内嵌的 `node_details.name` / `action_details.name` / `reco_details.name` 里。
+ * 顶层名只作创建时的兜底，来源用 `source` 如实标出（`entry` = 未确认）。
+ * 形状来自真机抓取的原始通知（`MAAFW_NOTIFY_DUMP`），单测按同一形状钉住。
+ */
+function pickNodeName(m) {
+  const authoritative = (m.node_details && m.node_details.name) ||
+    (m.action_details && m.action_details.name) ||
+    (m.reco_details && m.reco_details.name) || null
+  if (authoritative) return { name: String(authoritative), source: 'node_details' }
+  return { name: String(m.name || ('node#' + m.node_id)), source: 'entry' }
+}
+
+async function cmdRun(args) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备（先 maa_connect）' }
+  if (S.runActive) return { ok: false, error: '已有任务在运行（先 maa_run_stop）' }
+  let res
+  if (Array.isArray(args.resourceDirs) && args.resourceDirs.length) {
+    res = await buildResource(args.resourceDirs.map(String))
+    S.res = res
+  } else {
+    if (!args.resourceDir) return { ok: false, error: '缺少 resourceDir（或 resourceDirs 数组）' }
+    res = await ensureResource(args.resourceDir)
+  }
+  /* agent 桥接：项目声明了 agent（PI interface 的 child_exec/child_args）就先连上——
+   * custom action 注册进本次运行的 Resource；失败不阻断（非 agent 节点照跑），结果如实报告 */
+  let agentInfo = null
+  if (Array.isArray(args.agents) && args.agents.length) {
+    const ag = await setupAgents(res, args.agents, String(args.agentCwd || process.cwd()))
+    agentInfo = ag.ok
+      ? { ok: true, reused: !!ag.reused, actions: ag.actions ?? null, recognitions: ag.recos ?? null }
+      : { ok: false, error: ag.error }
+  }
+  const tasker = ensureTasker()
+  tasker.resource = res
+  tasker.controller = S.ctrl
+  /* timeoutMs=0：不自动 post_stop，停止权交调用方（LLM 看事件流自行判断 + run_stop）。
+   * >0 时沿用超时保护（防 JumpBack 死循环）。300s 硬上限已移除——长任务用 0。 */
+  const rawT = Number(args.timeoutMs)
+  const timeoutMs = rawT === 0 ? 0 : (Number.isFinite(rawT) && rawT > 0 ? Math.max(500, rawT) : 30000)
+  const t0 = Date.now()
+  const retention = { start: await captureNow('run-start') }
+  const nodes = new Map()   // node_id → {name, start, end, msg, success, seq}
+  const order = []
+  const nextCandidates = []   // 框架本轮宣布过的候选（NextList 通知），按顺序
+  let nextCandidateCount = 0  // 全部公告次数（含超出上限未记入数组的）
+  const onMsg = (m) => {
+    const t = Date.now()
+    const seq = S.seq
+    if (!m || !m.msg) return
+    /* 原始通知转储（默认关，MAAFW_NOTIFY_DUMP=<file> 打开）：节点记录是"两条流按到达顺序归并"的产物，
+     * 归属存疑时（如 record.nodes[].name 重复为入口名）只有原始消息能回答"框架到底发了什么"。 */
+    if (process.env.MAAFW_NOTIFY_DUMP) {
+      try { fs.appendFileSync(process.env.MAAFW_NOTIFY_DUMP, JSON.stringify(m) + '\n') } catch (e) { /* 诊断失败不影响运行 */ }
+    }
+    if (m.node_id !== undefined && m.node_id !== null) {
+      /* 节点名的权威来源：框架在 `PipelineNode.*` 的**顶层 name 上填的是任务入口名**
+       * （实测：`ProbeA --next--> ProbeB` 两条记录顶层都叫 ProbeA），而内嵌
+       * `node_details.name` / `action_details.name` / `reco_details.name` 与同轮的
+       * `Recognition.*` / `Action.*` 通知里是**真节点名**。
+       * 所以：创建时先用顶层名兜底（`PipelineNode.Starting` 只有顶层名），拿到权威名就改写，
+       * 并把来源记进 `nameSource`——消费方据此判断这个名字能不能当"哪个节点跑过"的依据。 */
+      const named = pickNodeName(m)
+      let n = nodes.get(String(m.node_id))
+      if (!n) {
+        n = {
+          id: String(m.node_id),
+          name: named.name,
+          nameSource: named.source,
+          start: t, end: null, status: 'running', msgs: [], seq,
+        }
+        nodes.set(String(m.node_id), n)
+        order.push(n)
+      } else if (named.source === 'node_details') {
+        /* 权威名到了就采纳（哪怕与顶层名相同）——来源要如实升格，否则 nameSource 会一直挂着 entry */
+        n.name = named.name
+        n.nameSource = 'node_details'
+      }
+      /* node-ok/fail 锚点：读控制器缓存图（不发新截图任务，规避并发崩溃，见 anchorFromCache） */
+      if (/Starting$/.test(m.msg)) { n.status = 'running'; n.start = t }
+      else if (/Succeeded$/.test(m.msg)) { n.status = 'ok'; n.end = t; anchorFromCache('node-ok') }
+      else if (/Failed$/.test(m.msg)) { n.status = 'fail'; n.end = t; anchorFromCache('node-fail') }
+      else if (n.msgs.length < 6) n.msgs.push(m.msg)
+      n.seq = seq
+      /* 节点级消息进事件流：maa_frame_poll / maa_timing_measure 直接消费 */
+      pushEvent({ type: 'run', seq, t, diff: 0, node: n.name, msg: m.msg, id: m.node_id ?? null })
+    } else {
+      const ev = { type: 'run', seq, t, diff: 0, node: m.name ?? null, msg: m.msg, id: m.reco_id ?? m.action_id ?? null }
+      pushEvent(ev)
+      if (order.length) order[order.length - 1].msgs.push(ev.msg + (ev.id ? '#' + ev.id : ''))
+      /* NextList.* 通知带**候选数组** `list: [{name, jump_back, anchor}]`（实测：每次公告一个候选，
+       * Starting 与 Succeeded 各一次）。只取 Starting，免得同一候选记两遍；记在**任务级**按顺序，
+       * 不做"挂给哪个节点"的归属猜测——公告的到达时机在新节点记录创建之后，挂给最近记录会把
+       * "上一个节点的出口"算到下个节点头上。任务级序列 + 权威节点名，足以还原"轮询了哪些出口、最后走了哪个"。
+       * 上限 50 条（JumpBack 长列表会刷很多次），超出只累加计数，避免记录被候选公告撑爆。 */
+      if (!/Succeeded$/.test(m.msg) && Array.isArray(m.list)) {
+        for (const c of m.list) {
+          if (!c || !c.name) continue
+          nextCandidateCount++
+          const name = String(c.name)
+          const last = nextCandidates[nextCandidates.length - 1]
+          /* 同一候选会被反复轮询（例如目标页正在切换动画，识别还没命中）——连续重复折叠成 polls 计数，
+           * 序列读起来才是"轮询过哪些出口"，而不是同一行刷屏。 */
+          if (last && last.name === name && !c.jump_back && !last.jumpBack && !c.anchor && !last.anchor) {
+            last.polls++
+            last.seq = seq
+            continue
+          }
+          if (nextCandidates.length < 50) {
+            nextCandidates.push({
+              seq, t, name, polls: 1,
+              ...(c.jump_back ? { jumpBack: true } : {}),
+              ...(c.anchor ? { anchor: true } : {}),
+            })
+          }
+        }
+      }
+    }
+  }
+  const s1 = tasker.add_sink((_, m) => onMsg(m))
+  const s2 = tasker.add_context_sink((_, m) => onMsg(m))
+  S.runActive = true
+  let status = null
+  let stopped = false
+  try {
+    const job = tasker.post_task(String(args.entry), args.override || {})
+    /* 超时保护：与 wait() 竞速。wait() 内部会泵事件循环（探针实测：节点回调在 wait 期间送达），
+     * 因此 setTimeout 分支可在此期间触发并执行 post_stop —— JumpBack 死循环无法挂死 worker。 */
+    let finished = false
+    if (timeoutMs > 0) {
+      await Promise.race([
+        job.wait().then(() => { finished = true }),
+        sleep(timeoutMs),
+      ])
+      if (!finished) {
+        try { tasker.post_stop() } catch (e) { /* ignore */ }
+        stopped = true
+        await Promise.race([job.wait().catch(() => null), sleep(1500)])
+      }
+    } else {
+      await job.wait()
+    }
+    status = job.status
+  } catch (e) {
+    status = -1
+    order.push({ id: '-', name: 'exception', start: t0, end: Date.now(), status: 'fail', msgs: [String(e && e.message || e)], seq: S.seq })
+  } finally {
+    try { tasker.remove_sink(s1); tasker.remove_context_sink(s2) } catch (e) { /* ignore */ }
+    S.runActive = false
+  }
+  let dump = null
+  try { dump = S.ctrl.get_node_data_parsed('node') } catch (e) { /* ignore */ }
+  retention.end = await captureNow('run-end')
+  const rec = {
+    ok: status === STATUS.succeeded,
+    entry: String(args.entry),
+    status,
+    stopped,
+    durationMs: Date.now() - t0,
+    startSeq: nodes.size ? order[0].seq : null,
+    endSeq: S.seq,
+    framesCaptured: S.seq,
+    retention,
+    ...(agentInfo ? { agent: agentInfo } : {}),
+    ...(nextCandidateCount ? { nextCandidates, nextCandidateCount } : {}),
+    nodes: order.map((n) => ({
+      id: n.id, name: n.name, nameSource: n.nameSource, status: n.status,
+      ms: (n.end ?? Date.now()) - n.start, seq: n.seq, msgs: n.msgs.slice(-6),
+    })),
+    dump: dump ? { taskCount: dump.tasks ? dump.tasks.length : 0, nodes: Object.keys(dump.nodes || {}).length } : null,
+  }
+  return { ok: true, record: rec }
+}
+
+async function cmdRunStop() {
+  if (S.tasker) {
+    try { S.tasker.post_stop() } catch (e) { /* ignore */ }
+  }
+  S.runActive = false
+  return { ok: true }
+}
+
+/* 输入注入：全部经 maafw 控制器（adb/win32 由 maafw 本体选择注入方法），不直接调 adb。
+ * 动作边界（前/后）各抓一张原图进 L0 锚区（契约 §1"采得到"）：
+ * 采集失败不阻断动作——动作结果与留存失败分别报告（契约 §9）。 */
+async function cmdInput(args) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备（先 maa_connect）' }
+  const t0 = Date.now()
+  const k = String(args.kind || 'click')
+  const retention = {}
+  const done = (job) => ({ ok: true, kind: k, ms: Date.now() - t0, retention })
+  retention.before = await captureNow('action-before')
+  let job = null
+  if (k === 'click') {
+    job = S.ctrl.post_click(Number(args.x), Number(args.y), Number(args.contact ?? 0), Number(args.pressure ?? 1))
+  } else if (k === 'dbclick') {
+    /* 双击：两次 click 间隔一拍（控制器消息模型下无原子双击原语） */
+    await S.ctrl.post_click(Number(args.x), Number(args.y)).wait()
+    await sleep(Math.max(20, Number(args.gap ?? 60)))
+    job = S.ctrl.post_click(Number(args.x), Number(args.y))
+  } else if (k === 'press') {
+    /* 长按：touch_down → 保持 → touch_up（保持期不占用事件循环之外的资源） */
+    const contact = Number(args.contact ?? 0)
+    await S.ctrl.post_touch_down(contact, Number(args.x), Number(args.y), Number(args.pressure ?? 1)).wait()
+    await sleep(Math.max(50, Number(args.duration ?? 800)))
+    job = S.ctrl.post_touch_up(contact)
+  } else if (k === 'swipe') {
+    /* `via` 给中途路径点（`[[x,y],...]` 或 `"x,y;x,y"`）：走 touch_down → 逐点 touch_move → touch_up，
+     * 也就是**一条笔画画出折线**。为什么需要：`post_swipe` 只有两个端点，只能画直线；
+     * 而连线/谱曲/拖拽排序这类玩法要求"按住 → 经过若干点 → 抬起"，且**中途不能抬手**
+     * （一旦抬手就是新笔画，很多玩法会把新笔画当成另一次操作或直接忽略）。
+     * 不给 `via` 时走原生 post_swipe（保持旧行为与旧性能）。 */
+    const viaRaw = args.via
+    let via = []
+    if (Array.isArray(viaRaw)) {
+      via = viaRaw.map((p) => (Array.isArray(p) ? [Number(p[0]), Number(p[1])] : null))
+    } else if (typeof viaRaw === 'string' && viaRaw.trim()) {
+      via = viaRaw.split(';').map((s) => s.split(',').map(Number))
+    }
+    if (via.length) {
+      if (via.some((p) => !p || p.length !== 2 || !p.every(Number.isFinite))) {
+        return { ok: false, error: 'via 路径点格式错：要 [[x,y],...] 或 "x,y;x,y"（收到 ' + JSON.stringify(viaRaw) + '）' }
+      }
+      const contact = Number(args.contact ?? 0)
+      const pressure = Number(args.pressure ?? 1)
+      const pts = [[Number(args.x1), Number(args.y1)], ...via, [Number(args.x2), Number(args.y2)]]
+      if (!pts.flat().every(Number.isFinite)) return { ok: false, error: 'swipe 端点或 via 含非数字' }
+      const duration = Math.max(0, Number(args.duration ?? 300))
+      const step = pts.length > 1 ? Math.max(8, Math.round(duration / (pts.length - 1))) : 8
+      await S.ctrl.post_touch_down(contact, pts[0][0], pts[0][1], pressure).wait()
+      for (const p of pts.slice(1)) {
+        await S.ctrl.post_touch_move(contact, p[0], p[1], pressure).wait()
+        await sleep(step)
+      }
+      job = S.ctrl.post_touch_up(contact)
+      /* 与共享尾同一口径：**先 wait 再抓 after**。抓早了可能截在抬手落地之前，
+       * 而手势类动作恰恰要验证"抬手之后画面变成什么样"。 */
+      await job.wait()
+      retention.after = await captureNow('action-after')
+      return { ...done(null), path: pts, viaCount: via.length, stepMs: step }
+    }
+    job = S.ctrl.post_swipe(Number(args.x1), Number(args.y1), Number(args.x2), Number(args.y2),
+      Number(args.duration ?? 300), Number(args.contact ?? 0), Number(args.pressure ?? 1))
+  } else if (k === 'touch_move') {
+    /* 裸的移动原语：与 touch_down / touch_up 配对，供调用方自己拼任意手势序列
+     * （跨多个命令维持同一次按压——联系列动作之间不抬手）。 */
+    const contact = Number(args.contact ?? 0)
+    job = S.ctrl.post_touch_move(contact, Number(args.x), Number(args.y), Number(args.pressure ?? 1))
+    await job.wait()
+    retention.after = await captureNow('action-after')
+    return done(null)
+  } else if (k === 'touch_down' || k === 'touch_up') {
+    const contact = Number(args.contact ?? 0)
+    job = k === 'touch_down'
+      ? S.ctrl.post_touch_down(contact, Number(args.x), Number(args.y), Number(args.pressure ?? 1))
+      : S.ctrl.post_touch_up(contact)
+    await job.wait()
+    retention.after = await captureNow('action-after')
+    return done(null)
+  } else if (k === 'key') {
+    job = S.ctrl.post_click_key(Number(args.code))
+  } else if (k === 'keys') {
+    /* 组合键：全按下再全抬起（按下顺序=给定顺序，抬起反序，模拟真实手型） */
+    const codes = (Array.isArray(args.codes) ? args.codes : String(args.codes ?? '').split(/[+,]/))
+      .map((c) => Number(String(c).trim())).filter((c) => Number.isFinite(c) && c > 0)
+    if (!codes.length) return { ok: false, error: 'keys 需要至少一个键码（数组或逗号/加号分隔）' }
+    const hold = Math.max(20, Number(args.hold ?? 60))
+    for (const c of codes) await S.ctrl.post_key_down(c).wait()
+    await sleep(hold)
+    for (const c of codes.slice().reverse()) await S.ctrl.post_key_up(c).wait()
+    retention.after = await captureNow('action-after')
+    return done(null)
+  } else if (k === 'scroll') {
+    /* 滚轮：dx/dy 为格数，建议 120 的倍数（WHEEL_DELTA） */
+    job = S.ctrl.post_scroll(Number(args.dx ?? 0), Number(args.dy ?? 0))
+  } else if (k === 'move') {
+    /* 相对移动（Win32/MacOS；FPS 锁鼠标场景配 mouse_lock_follow） */
+    job = S.ctrl.post_relative_move(Number(args.dx ?? 0), Number(args.dy ?? 0))
+  } else if (k === 'text') {
+    job = S.ctrl.post_input_text(String(args.text ?? ''))
+  } else if (k === 'app') {
+    job = String(args.action) === 'stop'
+      ? S.ctrl.post_stop_app(String(args.intent ?? ''))
+      : S.ctrl.post_start_app(String(args.intent ?? ''))
+  } else {
+    return { ok: false, error: 'unknown input kind: ' + k + '（click|dbclick|press|swipe|key|keys|scroll|move|text|app）' }
+  }
+  await job.wait()
+  retention.after = await captureNow('action-after')
+  return done(job)
+}
+
+/* 识别单测：子进程隔离执行（beta 绑定的 post_recognition 在无效模板上会原生崩溃，
+ * 子进程炸掉只损失一次测试，绝不让宿主陪葬）。 */
+function spawnRecoChild(payload, timeoutMs) {
+  const script = path.join(path.dirname(fileURLToPath(import.meta.url)), 'reco_child.mjs')
+  const file = path.join(os.tmpdir(), 'maa_reco_' + Date.now() + '_' + Math.floor(Math.random() * 1e6) + '.json')
+  fs.writeFileSync(file, JSON.stringify(payload), 'utf8')
+  const out = file + '.out'
+  return new Promise((resolve) => {
+    execFile(process.execPath, [script, '--cfg', file, '--out', out],
+      { timeout: Math.min(120000, Math.max(10000, timeoutMs)), windowsHide: true, maxBuffer: 4 * 1024 * 1024 },
+      (err, stdout) => {
+        try { fs.rmSync(file, { force: true }) } catch (e) { /* ignore */ }
+        try {
+          if (fs.existsSync(out)) {
+            const r = JSON.parse(fs.readFileSync(out, 'utf8'))
+            fs.rmSync(out, { force: true })
+            resolve(r)
+            return
+          }
+        } catch (e) { /* 结果损坏则走失败分支 */ }
+        resolve({ ok: false, error: '识别子进程失败：' + ((err && (err.message || String(err.code))) || '无结果') + ' ' + String(stdout || '').slice(0, 200) })
+      })
+  })
+}
+
+/* 识别详情瘦身：像素类字段（draws / raw）一律不带出去（与 reco_child 同一规则）。 */
+function stripDetail(d) {
+  if (!d || typeof d !== 'object') return null
+  const copy = { ...d }
+  delete copy.draws
+  delete copy.raw
+  return copy
+}
+
+/**
+ * 节点级单测（--act）：识别拿框 → 用框 run_action，动作半在真机 daemon 侧执行。
+ * 与 reco_child 的静态路径互补：那条只测识别（图像假控制器、无输入）；这条串起两半，
+ * 专测 target 框语义（框中心/偏移）与组合动作。识别输入 = 抓帧时的当前画面原图
+ * （也是 action-before 边界锚点），动作执行后的画面另抓 action-after——效果可复核。
+ */
+async function recoActTest(args, node) {
+  const res = await ensureResource(String(args.resourceDir))
+  const tasker = ensureTasker()
+  tasker.resource = res
+  tasker.controller = S.ctrl
+  const before = await captureNow('action-before')
+  if (!before.ok) return { ok: false, error: '识别输入抓帧失败：' + before.error }
+  const imgBuf = S.l0.roll[S.l0.roll.length - 1].png
+  const image = imgBuf.buffer.slice(imgBuf.byteOffset, imgBuf.byteOffset + imgBuf.byteLength)
+  let out = null
+  res.register_custom_action('@reco/act', async (self) => {
+    let detail = null
+    try {
+      detail = await self.context.run_recognition('@reco/node', image, { '@reco/node': node })
+    } catch (e) {
+      out = { ok: false, stage: 'recognition', error: String(e && e.message || e) }
+      return true
+    }
+    /* miss 判定不能只看 box 真值：miss 时 run_recognition 返回 hit:false + box 全零（数组恒真），
+     * 漏检会把 run_action 打到 (0,0)。hit 标志为主，box 零尺寸兜底（防个别识别类型缺 hit）。 */
+    const boxDead = !detail || !Array.isArray(detail.box) || Number(detail.box[2]) === 0 || Number(detail.box[3]) === 0
+    if (!detail || detail.hit === false || boxDead) {
+      out = { ok: false, stage: 'recognition', miss: true, ...(detail ? { reco: stripDetail(detail) } : {}) }
+      return true
+    }
+    const rec = stripDetail(detail)
+    try {
+      const act = await self.context.run_action('@reco/node', detail.box, JSON.stringify(rec), { '@reco/node': node })
+      out = { ok: !!act, stage: 'action', reco: rec, action: stripDetail(act) }
+    } catch (e) {
+      out = { ok: false, stage: 'action', error: String(e && e.message || e), reco: rec }
+    }
+    return true
+  })
+  try {
+    await tasker.post_task('@reco/entry', { '@reco/entry': { action: 'Custom', custom_action: '@reco/act' } }).wait()
+  } catch (e) {
+    return { ok: false, error: '动作探针任务失败：' + String(e && e.message || e) }
+  } finally {
+    try { res.unregister_custom_action('@reco/act') } catch (e) { /* ignore */ }
+  }
+  const after = await captureNow('action-after')
+  if (!out) return { ok: false, error: '动作探针未被执行（custom action 回调未触发）' }
+  const rec = node && node.recognition
+  const shownType = rec && typeof rec === 'object' ? String(rec.type ?? 'DirectHit') : String(rec ?? 'DirectHit')
+  return {
+    ok: out.ok,
+    type: shownType,
+    meta: { seq: before.seq, w: before.w, h: before.h, t: before.t },
+    ...(out.error !== undefined ? { error: out.error } : {}),
+    ...(out.stage ? { stage: out.stage } : {}),
+    ...(out.miss !== undefined ? { miss: out.miss } : {}),
+    ...(out.reco ? { reco: out.reco } : {}),
+    ...(out.action ? { action: out.action } : {}),
+    retention: { before, after },
+  }
+}
+
+async function cmdRecoTest(args) {
+  /* --act：节点级单测（识别拿框 → 真机执行动作半），在 daemon 进程内跑（要真控制器） */
+  const actNode = args.act === true && args.node && typeof args.node === 'object' && !Array.isArray(args.node) ? args.node : null
+  if (args.act === true) {
+    if (!actNode) return { ok: false, error: '--act 需要同时给 --node（整节点 JSON，含 action）' }
+    if (!S.ctrl) return { ok: false, error: '--act 要在真机上执行动作：需要已连接设备（REPL 或 --project/--kind）' }
+    return await recoActTest(args, actNode)
+  }
+  await ensureResource(args.resourceDir)   // 校验资源可加载（子进程会重新加载）
+  /* 图像来源三条：库内留存帧（kfSource：控制器分辨率原图、**可无设备**）/ 显式文件 / 会话缓冲帧。
+   * daemon 自己写的那份临时 PNG **用完即删**——不删就是每跑一次漏一个（CLI 侧的截帧泄漏是同一类，
+   * 现场实测攒过 42 张；这条 `--seq` 路径同理，只是本机还没被触发过）。 */
+  let imageFile = null
+  let tempImage = null
+  let meta = {}
+  if (args.kfSource) {
+    const kf = readKfCropSource(args.kfSource)
+    if (kf.error) return { ok: false, error: kf.error }
+    imageFile = path.join(os.tmpdir(), 'maa_reco_kf_' + Date.now() + '.png')
+    fs.writeFileSync(imageFile, kf.png)     // 库帧原样字节，不重编码（裁剪无关，reco 只读这一张）
+    tempImage = imageFile
+    meta = { source: kf.source.id, sha256: kf.source.sha256, w: kf.dec.w, h: kf.dec.h, ctrlW: kf.dec.w, ctrlH: kf.dec.h }
+  } else if (args.image) {
+    imageFile = String(args.image)
+    meta = { source: args.image }
+  } else {
+    const fr = args.seq !== undefined && args.seq !== null
+      ? S.ring.find((r) => r.seq === Number(args.seq))
+      : S.ring[S.ring.length - 1]
+    if (!fr) return { ok: false, error: '缓冲无可用帧（seq=' + args.seq + '）' }
+    imageFile = path.join(os.tmpdir(), 'maa_reco_img_' + Date.now() + '.png')
+    fs.writeFileSync(imageFile, pngEncodeRGB(fr.rgb, fr.w, fr.h))
+    tempImage = imageFile
+    meta = { seq: fr.seq, w: fr.w, h: fr.h, t: fr.t }
+  }
+  /* --node：整节点 JSON 原样透传给子进程（V1 扁平 / V2 嵌套由框架解析，daemon 不转换） */
+  const node = args.node && typeof args.node === 'object' && !Array.isArray(args.node) ? args.node : null
+  if (node && (typeof node.recognition !== 'string') &&
+      !(node.recognition && typeof node.recognition === 'object' && !Array.isArray(node.recognition))) {
+    return { ok: false, error: '--node 缺少可用的 recognition 字段（V1 字符串或 V2 {type,param}）' }
+  }
+  const baseParam = args.param && typeof args.param === 'object' ? args.param : {}
+  const sweep = args.sweep && typeof args.sweep === 'object' ? args.sweep : null
+  const cases = []
+  if (sweep && typeof sweep.min === 'number' && typeof sweep.max === 'number') {
+    /* step 带方向：升序 0.5→0.9 / 降序 0.9→0.5 都合法；区间为空明确报错，不静默测个空 */
+    const step = sweep.step !== undefined && Number(sweep.step) !== 0 ? Number(sweep.step) : 1
+    const up = step > 0
+    if ((up && sweep.min > sweep.max) || (!up && sweep.min < sweep.max)) {
+      return { ok: false, error: 'sweep 区间为空：min=' + sweep.min + ' max=' + sweep.max + ' step=' + step + '（step 带方向）' }
+    }
+    for (let v = sweep.min; up ? v <= sweep.max + 1e-9 : v >= sweep.max - 1e-9; v += step) {
+      cases.push({ ...baseParam, [String(sweep.key || 'threshold')]: Math.round(v * 1000) / 1000 })
+    }
+  } else cases.push(baseParam)
+  let r = null
+  try {
+    r = await spawnRecoChild({
+      resourceDir: String(args.resourceDir),
+      type: String(args.type || 'TemplateMatch'),
+      image: imageFile,
+      /* 面板场景：模板由调用方裁好落盘传进来（子进程走 override_image），不写进任何资源目录 */
+      ...(args.templateImage ? { templateImage: String(args.templateImage) } : {}),
+      ...(node ? { node } : { cases }),
+    }, 90000)
+  } finally {
+    /* 子进程已经读完这张图（spawnRecoChild 会等到它退出），此时删除是安全的 */
+    if (tempImage) { try { fs.rmSync(tempImage, { force: true }) } catch (e) { /* ignore */ } }
+  }
+  if (r && r.ok) {
+    const rec = node && node.recognition
+    const shownType = node
+      ? (rec && typeof rec === 'object' ? String(rec.type ?? 'DirectHit') : String(rec))
+      : args.type
+    return { ok: true, type: shownType, meta, results: r.results }
+  }
+  return { ok: false, error: (r && r.error) || 'reco 失败', meta }
+}
+
+/* ────────────────────────── 关键帧库（L0 升格 + 登记，契约 §4） ──────────────────────────
+ * 库根：runDir/frames（host init 传入 runDir，默认 ~/.maafw-live）。
+ * manifest.json = { schema, libraryId, next, frames[] }；kf ID = kf:<库UUID>:<零填充序号>。
+ * 写入次序是硬约束：先固定像素（tmp+rename 落 L0 文件），再发布 manifest 记录；
+ * manifest 失败即回收文件，绝不返回半成品引用。库副本 v0 按单写者管理，不自动合并。 */
+const KF_SCHEMA = 1
+function kfRoot() { return path.join(S.runDir || path.join(os.homedir(), '.maafw-live'), 'frames') }
+function kfAbsPath(fileRel) { return path.join(kfRoot(), String(fileRel).split('/').join(path.sep)) }
+function kfLoad() {
+  const file = path.join(kfRoot(), 'manifest.json')
+  if (!fs.existsSync(file)) return null
+  let m = null
+  try { m = JSON.parse(fs.readFileSync(file, 'utf8')) } catch (e) { throw new Error('manifest.json 损坏（非合法 JSON）') }
+  if (!m || typeof m !== 'object' || !Array.isArray(m.frames)) throw new Error('manifest.json 结构不符（缺 frames 数组）')
+  /* 未知 schema 明确报错，不默认为当前版（契约 §4） */
+  if (Number(m.schema) !== KF_SCHEMA) throw new Error('manifest schema=' + m.schema + ' 不被当前版本支持（认识：' + KF_SCHEMA + '）')
+  return m
+}
+function kfOpen() {
+  return kfLoad() ?? { schema: KF_SCHEMA, libraryId: randomUUID(), next: 1, frames: [] }
+}
+function kfSave(m) {
+  const file = path.join(kfRoot(), 'manifest.json')
+  fs.mkdirSync(kfRoot(), { recursive: true })
+  const tmp = file + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(m, null, 2))
+  fs.renameSync(tmp, file)
+}
+
+/** 库目录现有 L0 字节（按 manifest 记录的文件实测；丢失文件计 0——磁盘占用只算真实存在的） */
+function kfUsageBytes(m) {
+  let total = 0
+  for (const f of m.frames) {
+    try { total += fs.statSync(kfAbsPath(f.file)).size } catch (e) { /* 丢失不计 */ }
+  }
+  return total
+}
+
+async function cmdKfPromote(args) {
+  /* 固定捕获身份：latest 在接受请求时解析成具体 seq；已淘汰则失败，绝不改取更新帧冒充 */
+  let seq = null
+  if (args.seq !== undefined && args.seq !== null) {
+    seq = Number(args.seq)
+    if (!Number.isFinite(seq)) return { ok: false, error: 'seq 必须是数字' }
+  } else if (args.latest === true) {
+    seq = S.seq
+  } else {
+    return { ok: false, error: '给 seq（数字）或 latest:true 指定要升格的捕获' }
+  }
+  if (seq <= 0) return { ok: false, error: '本会话尚无捕获（seq=0），无可升格' }
+  const ent = S.l0.anchor.find((x) => x.seq === seq) ?? S.l0.roll.find((x) => x.seq === seq)
+  if (!ent) {
+    const range = (l) => (l.length ? l[0].seq + '..' + l[l.length - 1].seq : '空')
+    return {
+      ok: false,
+      error: 'L0 已淘汰：seq=' + seq + '（滚动区 ' + range(S.l0.roll) + '，锚区 ' + range(S.l0.anchor) + '）。' +
+        'L1 参考帧可用 frame_get 导出，但按契约不作 state 证据本体',
+    }
+  }
+  let m
+  try { m = kfOpen() } catch (e) { return { ok: false, error: '关键帧库不可用：' + String(e && e.message || e) } }
+  const sess = S.session || {}
+  const sessionRef = { daemon: S.daemonId, gen: S.connGen, kind: sess.kind ?? null, target: sess.target ?? null }
+  const sha = createHash('sha256').update(ent.png).digest('hex')
+  /* 幂等：同一捕获（daemon + 代次 + seq）重试返回原对象；内容不符报冲突，不任选一份 */
+  const dup = m.frames.find((f) => f.session && f.session.daemon === sessionRef.daemon &&
+    Number(f.session.gen) === sessionRef.gen && Number(f.captureSeq) === seq)
+  if (dup) {
+    if (dup.sha256 === sha) return { ok: true, idempotent: true, id: dup.id, record: dup, path: kfAbsPath(dup.file), sha256: sha }
+    return { ok: false, error: '同一捕获已有内容不同的记录（' + dup.id + '）：冲突，拒绝改写旧 ID 的含义' }
+  }
+  /* 磁盘配额（契约 §4.1）：幂等重试在上面已返回，走到这里的都是新增字节。
+   * 满额拒绝并报告——已升格对象不后台清理，清理由用户决定。 */
+  if (S.kfQuota > 0) {
+    const used = kfUsageBytes(m)
+    const mb = (v) => (v / 1048576).toFixed(1) + 'MB'
+    if (used + ent.png.length > S.kfQuota) {
+      return {
+        ok: false,
+        error: '关键帧库配额不足：已用 ' + mb(used) + ' + 新增 ' + mb(ent.png.length) +
+          ' 超过配额 ' + mb(S.kfQuota) + '（' + m.frames.length + ' 帧留存于 ' + kfRoot() + '）。' +
+          '不会自动删除已升格帧——清理后重试，或调大配额（init kfQuotaBytes / MAAFW_KF_QUOTA_BYTES）',
+      }
+    }
+  }
+  const num = Number(m.next) || m.frames.length + 1
+  const id = 'kf:' + m.libraryId + ':' + String(num).padStart(4, '0')
+  const fileRel = 'l0/' + String(num).padStart(4, '0') + '.png'
+  const abs = kfAbsPath(fileRel)
+  try {
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    const tmp = abs + '.tmp'
+    fs.writeFileSync(tmp, ent.png)
+    fs.renameSync(tmp, abs)
+  } catch (e) {
+    return { ok: false, error: 'L0 文件写入失败：' + String(e && e.message || e) }
+  }
+  /* 小图信息只取环内同 seq 帧；已淘汰则明确为空，不借用最新帧数据（契约 §4） */
+  const small = S.ring.find((r) => r.seq === seq)
+  const rec = {
+    id, file: fileRel, sha256: sha,
+    session: sessionRef,
+    capturedAt: new Date(ent.t).toISOString(),
+    captureSeq: seq,
+    ctrlW: ent.w, ctrlH: ent.h,
+    smallW: small ? small.w : null, smallH: small ? small.h : null,
+    scale: small && ent.w ? Math.round((small.w / ent.w) * 1000) / 1000 : null,
+    source: ent.source || 'explicit',
+    note: args.note != null ? String(args.note) : null,
+  }
+  m.frames.push(rec)
+  m.next = num + 1
+  try { kfSave(m) } catch (e) {
+    try { fs.rmSync(abs, { force: true }) } catch (e2) { /* ignore */ }
+    return { ok: false, error: 'manifest 写入失败（L0 文件已回收，未发布引用）：' + String(e && e.message || e) }
+  }
+  return { ok: true, id, path: abs, sha256: sha, retained: 'promoted', record: rec }
+}
+
+function cmdL0Status() {
+  const brief = (e) => ({ seq: e.seq, t: e.t, source: e.source ?? null, w: e.w, h: e.h, bytes: e.png ? e.png.length : 0 })
+  /* 唯一字节：两区共享 Buffer，简单求和会双计 */
+  const seen = new Set()
+  let uniqueBytes = 0
+  for (const e of S.l0.roll) if (!seen.has(e.seq)) { seen.add(e.seq); uniqueBytes += e.png ? e.png.length : 0 }
+  for (const e of S.l0.anchor) if (!seen.has(e.seq)) { seen.add(e.seq); uniqueBytes += e.png ? e.png.length : 0 }
+  const sum = (list, cap) => ({
+    count: list.length, cap,
+    bytes: list.reduce((a, e) => a + (e.png ? e.png.length : 0), 0),
+    seqRange: list.length ? [list[0].seq, list[list.length - 1].seq] : null,
+  })
+  let m = null
+  try { m = kfLoad() } catch (e) { m = null } /* 状态上报不容因库坏而失败 */
+  const library = m
+    ? { frames: m.frames.length, bytes: kfUsageBytes(m), quota: S.kfQuota, dir: kfRoot() }
+    : { frames: 0, bytes: 0, quota: S.kfQuota, dir: kfRoot(), error: 'manifest 不可读' }
+  return {
+    ok: true, seq: S.seq,
+    roll: { ...sum(S.l0.roll, S.l0.rollCap), entries: S.l0.roll.map(brief) },
+    anchor: { ...sum(S.l0.anchor, S.l0.anchorCap), entries: S.l0.anchor.map(brief) },
+    bytes: { unique: uniqueBytes, cap: S.l0.bytesCap, evicted: S.l0.evicted },
+    framesDir: kfRoot(),
+    library,
+  }
+}
+
+/* ────────────────────────── 模板裁剪（snap 收紧 + 自匹配精修） ──────────────────────────
+ * 输入：宽松框（或点+外扩）；源 = L0 原图（控制器分辨率——模板尺寸必须与识别空间一致，
+ * 不能从降采样小图裁）。收紧 = 与边框背景差的行列占比；精修 = 逐边 ±2px 贪心重试，
+ * 以"裁出的模板在同帧上的 TemplateMatch 得分"为目标函数（自匹配验证闭环）。 */
+/* opts.tol / opts.frac 是**测量用覆盖**（默认即生产常数）：定标要能 A/B 才有数据，
+ * 不给就用 90 / 0.12，行为与加参数前逐字节一致。 */
+function tightenBounds(rgb, w, h, opts = {}) {
+  const ring = Math.max(2, Math.round(Math.min(w, h) / 12))
+  let br = 0, bg = 0, bb = 0, bn = 0
+  for (let y = 0; y < h; y++) {
+    const edgeRow = y < ring || y >= h - ring
+    for (let x = 0; x < w; x++) {
+      if (!edgeRow && !(x < ring || x >= w - ring)) continue
+      const i = (y * w + x) * 3
+      br += rgb[i]; bg += rgb[i + 1]; bb += rgb[i + 2]; bn++
+    }
+  }
+  br /= bn; bg /= bn; bb /= bn
+  const TOL = Number(opts.tol) > 0 ? Number(opts.tol) : 90   // 通道差之和超过此值视为"非背景"
+  const rowHit = new Array(h).fill(0)
+  const colHit = new Array(w).fill(0)
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 3
+      if (Math.abs(rgb[i] - br) + Math.abs(rgb[i + 1] - bg) + Math.abs(rgb[i + 2] - bb) > TOL) {
+        rowHit[y]++; colHit[x]++
+      }
+    }
+  }
+  const FRAC = Number(opts.frac) > 0 ? Number(opts.frac) : 0.12
+  let y0 = 0, y1 = h - 1
+  while (y0 < y1 && rowHit[y0] / w < FRAC) y0++
+  while (y1 > y0 && rowHit[y1] / w < FRAC) y1--
+  let x0 = 0, x1 = w - 1
+  while (x0 < x1 && colHit[x0] / h < FRAC) x0++
+  while (x1 > x0 && colHit[x1] / h < FRAC) x1--
+  if (y1 - y0 < 3 || x1 - x0 < 3) return null   // 内容撑满或无内容：交回调用方处理
+  return { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 }
+}
+
+/** 局部对比度图：左右 / 上下邻域差之和（3 通道累加）。文字/图标的描边远高于平铺纹理。 */
+function edgeMap(rgb, w, h) {
+  const e = new Int32Array(w * h)
+  for (let y = 1; y < h - 1; y++) {
+    for (let x = 1; x < w - 1; x++) {
+      const i = (y * w + x) * 3
+      const l = i - 3, r = i + 3, u = i - w * 3, d = i + w * 3
+      e[y * w + x] =
+        Math.abs(rgb[r] - rgb[l]) + Math.abs(rgb[r + 1] - rgb[l + 1]) + Math.abs(rgb[r + 2] - rgb[l + 2]) +
+        Math.abs(rgb[d] - rgb[u]) + Math.abs(rgb[d + 1] - rgb[u + 1]) + Math.abs(rgb[d + 2] - rgb[u + 2])
+    }
+  }
+  return e
+}
+
+/**
+ * 边缘/局部对比度收紧（roadmap 修法①）：`tightenBounds` 量的是"与背景色的距离"，而这类游戏 UI 的
+ * **背景自带纹理**——整片纹理都被算成非背景，行/列命中率全满，于是剪不动、留白留下（实测踩过：
+ * `signin_entry` 右半张是背景，自匹配照样报"位置正确 1.0"）。
+ *
+ * 这一路量**局部对比度**，判据是自适应阈值："边框环自身的对比度水平（p90）× z" 与绝对地板 `edgeMin`
+ * 取大者——环就是背景，所以阈值跟着背景纹理走；元素（文字/图标/描边）的对比度通常高出一截。
+ * 行/列的命中比例低于 `edgeFrac` 即判为背景并剪掉。返回 null 表示"没收到东西"（撑满或无内容）。
+ *
+ * 与背景差分**取更紧者**进候选池（不是硬交集）：两路都只剪不放，更紧的那个仍是内容的子集；
+ * 而"过紧会不会把元素裁掉"交给下游既有的自匹配判据（位置正确优先于得分）去裁决。
+ */
+function tightenBoundsByEdges(rgb, w, h, opts = {}) {
+  const Z = Number(opts.edgeZ) > 0 ? Number(opts.edgeZ) : 2
+  const MIN = Number(opts.edgeMin) > 0 ? Number(opts.edgeMin) : 24
+  const FRAC = Number(opts.edgeFrac) > 0 ? Number(opts.edgeFrac) : 0.02
+  const ring = Math.max(2, Math.round(Math.min(w, h) / 12))
+  const e = edgeMap(rgb, w, h)
+  /* 环上的对比度水平：p90（不是均值——有孤立强边时均值会被拖低，p90 更能代表"这片背景的纹理有多花"） */
+  const ringVals = []
+  for (let y = 0; y < h; y++) {
+    const edgeRow = y < ring || y >= h - ring
+    for (let x = 0; x < w; x++) {
+      if (!edgeRow && !(x < ring || x >= w - ring)) continue
+      ringVals.push(e[y * w + x])
+    }
+  }
+  ringVals.sort((a, b) => a - b)
+  const bgLevel = ringVals.length ? ringVals[Math.min(ringVals.length - 1, Math.floor(ringVals.length * 0.9))] : 0
+  const thresh = Math.max(MIN, bgLevel * Z)
+  const rowHit = new Array(h).fill(0)
+  const colHit = new Array(w).fill(0)
+  for (let y = 1; y < h - 1; y++) {
+    for (let x = 1; x < w - 1; x++) {
+      if (e[y * w + x] > thresh) { rowHit[y]++; colHit[x]++ }
+    }
+  }
+  let y0 = 0, y1 = h - 1
+  while (y0 < y1 && rowHit[y0] / w < FRAC) y0++
+  while (y1 > y0 && rowHit[y1] / w < FRAC) y1--
+  let x0 = 0, x1 = w - 1
+  while (x0 < x1 && colHit[x0] / h < FRAC) x0++
+  while (x1 > x0 && colHit[x1] / h < FRAC) x1--
+  if (y1 - y0 < 3 || x1 - x0 < 3) return null
+  return { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1, bgLevel, thresh }
+}
+
+function cropRgb(rgb, sw, sh, box) {
+  const w = Math.min(box.w, sw - box.x), h = Math.min(box.h, sh - box.y)
+  const out = Buffer.alloc(w * h * 3)
+  for (let y = 0; y < h; y++) {
+    rgb.copy(out, y * w * 3, ((box.y + y) * sw + box.x) * 3, ((box.y + y) * sw + box.x + w) * 3)
+  }
+  return { w, h, data: out }
+}
+
+/**
+ * 库帧裁剪源：读关键帧库内的 L0 文件并校验身份。纯文件操作，不碰 daemon 状态——
+ * 这正是"不可复现状态"的场景：捕获它的那次会话早已结束，设备也不在那个画面上。
+ *
+ * 校验三层，任一不符即拒绝（不许把"另一个字节"当成本次裁剪的依据）：
+ *  1. 文件在（调用方已按契约 §4.1 解析过完整 ID，这里是同一份字节的第二次确认）；
+ *  2. sha256 与库记录一致——防解析与读取之间文件被替换；
+ *  3. 像素尺寸与库记录 ctrlW/ctrlH 一致——记录与像素不同源即库本身不一致。
+ */
+function readKfCropSource(src) {
+  if (!src || typeof src !== 'object') return { error: 'kfSource 必须是对象' }
+  const id = String(src.id ?? '')
+  const file = String(src.path ?? '')
+  if (!id.startsWith('kf:') || !file) return { error: 'kfSource 需要 id（kf:<库UUID>:<序号>）与 path' }
+  let png = null
+  try { png = fs.readFileSync(file) } catch (e) { return { error: '库帧读取失败：' + String(e && e.message || e) } }
+  const sha = createHash('sha256').update(png).digest('hex')
+  if (src.sha256 && String(src.sha256) !== sha) {
+    return { error: '库帧内容与库记录不符（sha256 不匹配）：解析后文件被改动，拒绝裁剪' }
+  }
+  let dec = null
+  try { dec = pngDecode(png) } catch (e) { return { error: '库帧不是可解码的 PNG：' + String(e && e.message || e) } }
+  const recW = Number(src.ctrlW), recH = Number(src.ctrlH)
+  if (recW > 0 && recH > 0 && (recW !== dec.w || recH !== dec.h)) {
+    return {
+      error: '库记录尺寸 ' + recW + 'x' + recH + ' 与像素实际 ' + dec.w + 'x' + dec.h +
+        ' 不一致：库记录与文件不同源，拒绝裁剪',
+    }
+  }
+  return {
+    png, dec, sha, path: file,
+    source: {
+      kind: 'kf', id, sha256: sha, ctrlW: dec.w, ctrlH: dec.h,
+      captureSeq: Number.isFinite(Number(src.captureSeq)) ? Number(src.captureSeq) : null,
+      capturedAt: src.capturedAt ? String(src.capturedAt) : null,
+    },
+  }
+}
+
+/**
+ * L2 派生图的出处记录（契约 §5：L2 记录来源及裁剪 / 缩放变换）。
+ *
+ * 只记来源身份与变换，不记设备地址 / 目标 / daemon 身份 / 本地绝对路径——L2 是提交进仓库的
+ * 交付物，库帧本身（含设备来源）留在本地（契约 §4.1 隐私）。纯函数：时间由调用方传入，可断言。
+ */
+function buildL2Provenance(o) {
+  /* 来源字段白名单：即便调用方把整条库记录（含 session/target）递进来，也不落进 L2 出处。
+   * 库记录里的设备来源留在本地 manifest，是这两份文件的边界（契约 §4.1）。 */
+  const s = o.source || {}
+  const derivedFrom = s.kind === 'kf'
+    ? {
+        kind: 'kf', id: s.id, sha256: s.sha256, ctrlW: s.ctrlW, ctrlH: s.ctrlH,
+        captureSeq: s.captureSeq ?? null, capturedAt: s.capturedAt ?? null,
+      }
+    : {
+        kind: 'l0-cache', seq: s.seq ?? null, sha256: s.sha256,
+        ctrlW: s.ctrlW, ctrlH: s.ctrlH, capturedAt: s.capturedAt ?? null,
+      }
+  return {
+    schema: 1,
+    level: 'L2',
+    derivedFrom,
+    transform: { op: 'crop', resize: false, scale: 1, loose: o.loose, crop: o.box, snapped: o.snapped },
+    selfMatch: { score: o.score, positionOk: o.positionOk, box: o.selfMatchBox ?? null, tries: o.tries },
+    cross: o.cross ?? null,
+    output: { w: o.w, h: o.h },
+    createdAt: o.createdAt,
+    tool: 'maafw-live crop',
+  }
+}
+
+/** 缺省落点：daemon 的 run 目录下 `out/`（一次性命令给的是临时目录）——**不写调用方的 cwd**。
+ * 调用方的 cwd 通常就是项目仓库：一次 `frame_get` / `annotate` 就把产物丢进仓库。
+ * 实测踩过两次（`maa_frame_*.png` 十张进了 maafw-live 仓、`maa_som_*.png` 进了同一个根目录），
+ * 而这几个命令本质是"看/量"，产物只是顺便落盘——落哪儿由 `out` 说话，不落调用方家里。 */
+function defaultOutFile(runDir, prefix, ts = Date.now()) {
+  const dir = path.join(runDir || os.tmpdir(), 'out')
+  return { dir, file: path.join(dir, prefix + '-' + ts + '.png') }
+}
+
+async function cmdTplCrop(args) {
+  /* 源帧两条路，都必须是控制器分辨率的完整原图（模板尺寸要与识别空间一致，绝不从降采样小图裁）：
+   *  - L0 热缓存：seq 或最新（同一会话内，有设备）；
+   *  - 关键帧库留存帧：kfSource（跨会话、可无设备——契约 §2 库内 L0 即原图本体）。 */
+
+  /* 宽松框：显式 roi，或点 + 外扩（点→ROI 派生与裁剪共享同一条 snap 链）。
+   * 校验放在最前：坏参数（既没 roi 也没 point）不该有任何副作用——尤其不该把源帧升格进库。 */
+  let loose = null
+  if (Array.isArray(args.roi) && args.roi.length === 4) {
+    loose = args.roi.map(Number)
+  } else if (Array.isArray(args.point) && args.point.length === 2) {
+    const pad = Math.max(8, Number(args.pad ?? 24))
+    const [px, py] = args.point.map(Number)
+    loose = [px - pad, py - pad, pad * 2, pad * 2]
+  } else {
+    return { ok: false, error: '给 --roi x,y,w,h 或 --point x,y [--pad n]' }
+  }
+  /* 非数字入参要在算框之前拦掉：NaN 会一路传成 NaN 框，最后报一个跟病因无关的失败。
+   * 线上真会遇到的形态是 `[0,0,"x",10]` 这类（JSON 里 NaN 变 null，Number(null) = 0 是合法数字）。 */
+  if (!loose.every((v) => Number.isFinite(v))) {
+    return { ok: false, error: 'roi / point / pad 必须是数字：' + JSON.stringify(loose) }
+  }
+
+  let ent = null
+  let kf = null
+  if (args.kfSource) {
+    kf = readKfCropSource(args.kfSource)
+    if (kf.error) return { ok: false, error: kf.error }
+  } else {
+    ent = args.seq !== undefined && args.seq !== null
+      ? (S.l0.anchor.find((x) => x.seq === Number(args.seq)) ?? S.l0.roll.find((x) => x.seq === Number(args.seq)))
+      : (S.l0.anchor[S.l0.anchor.length - 1] ?? S.l0.roll[S.l0.roll.length - 1] ?? null)
+    if (!ent) {
+      return { ok: false, error: 'L0 无可用原图：先 screencap / stream / 输入产生观测（seq=' + args.seq + '）' }
+    }
+  }
+  const png = kf ? kf.png : ent.png
+  const dec = pngDecode(png)
+  /* 统一成 RGB：cropRgb 按 3 通道步进，RGBA 帧不归一化会静默错剪 */
+  const rgb = toRgb(dec)
+  const source = kf ? kf.source : {
+    kind: 'l0-cache', seq: ent.seq, sha256: createHash('sha256').update(png).digest('hex'),
+    ctrlW: dec.w, ctrlH: dec.h, capturedAt: new Date(ent.t).toISOString(),
+  }
+  /* 「源帧也留下」（--keep-source，只对热缓存路径有意义）：
+   * 契约的模型是 **L0 缓存 → 选择性升格 → 从库帧裁 L2**，但少走中间那一步时，模板的出处只剩一个
+   * 随进程消失的 seq（实测踩过：先做的五张模板出处全是 l0-cache，sha256 之外无从复核）。
+   * **必须在裁剪计算之前做**：自匹配 + 跨帧验证要 1–2 秒，滚动区小的时候（实测 l0Roll=2、流 5fps）
+   * 那一帧早就被淘汰了——曾经把升格放在末尾，验收里直接失败。按 ent.seq 升格本次用的那一帧，不取最新帧。 */
+  let keptSource = null
+  if (!kf && args.keepSource === true) {
+    const promoted = await cmdKfPromote({ seq: ent.seq })
+    if (promoted && promoted.ok && promoted.id) {
+      keptSource = { id: promoted.id, path: promoted.path ?? null, seq: ent.seq }
+      source.kind = 'kf'
+      source.id = promoted.id
+      source.captureSeq = ent.seq
+    } else {
+      keptSource = { error: String((promoted && promoted.error) || '升格失败'), seq: ent.seq }
+    }
+  }
+  const cl = (v, lo, hi) => Math.min(hi, Math.max(lo, Math.round(v)))
+  const box0 = {
+    x: cl(loose[0], 0, dec.w - 8),
+    y: cl(loose[1], 0, dec.h - 8),
+    w: 0, h: 0,
+  }
+  box0.w = cl(loose[2], 8, dec.w - box0.x)
+  box0.h = cl(loose[3], 8, dec.h - box0.y)
+
+  const region = cropRgb(rgb, dec.w, dec.h, box0)
+  /* 两路收紧：背景差分（与背景色的距离）是**生产默认**；边缘（局部对比度）是**测量用**、默认关
+   * （见下方 tightEdge 的说明与定标结论）。两路都进候选池，更紧的排前面（与自匹配 objective 配合：
+   * 都位置正确、都满分时保留先入者 = 更贴合的框；过紧的把元素裁掉了则 objective 会输给宽松档）。 */
+  const tightBg = tightenBounds(region.data, region.w, region.h, { tol: args.snapTol, frac: args.snapFrac })
+  /* 边缘那一路**默认关**：定标结论见 docs/daemon-protocol.md 的 tpl_crop 行——在现有真值集
+   * （scripts/truth/1999-720p.json，12 例）上它单独用 IoU 均值只有 0.50–0.59，而背景差分是 0.804：
+   * 边缘判据找的是**元素内部结构**（文字笔画、图标细节），不是元素的范围，所以"取更紧者"会把
+   * 框收进元素内部（实测 0005 物品卡片：0.866 → 0.449）。要试就显式给 `edge:true`（survey:crop --edge）。 */
+  const tightEdge = args.edge === true
+    ? tightenBoundsByEdges(region.data, region.w, region.h, {
+        edgeZ: args.edgeZ, edgeMin: args.edgeMin, edgeFrac: args.edgeFrac,
+      })
+    : null
+  const snapped = !!(tightBg || tightEdge)
+
+  /* 自匹配闭环：裁出的模板在同帧上匹配，逐边 ±2px 贪心取得分最高边界。
+   * 判据两层：位置正确（best 落回裁剪处）优先于得分——大面积纯色的模板在
+   * CCOEFF_NORMED 下得分为噪声（实测同帧自匹配 best 落到别处、0.736 高于真实位置），
+   * "找不到自己"比"分数低"更能说明模板不独特。 */
+  const resourceDir = String(args.resourceDir || '')
+  /* 自匹配的输入帧：库帧直接用库内文件（只读，不复制、不改写 L0）；热缓存帧落一份临时副本 */
+  const frameFile = kf ? kf.path : path.join(os.tmpdir(), 'maa_tpl_frame_' + Date.now() + '.png')
+  const candFile = path.join(os.tmpdir(), 'maa_tpl_cand_' + Date.now() + '.png')
+  if (!kf) fs.writeFileSync(frameFile, ent.png)
+  const writeCand = (b) => {
+    const c = cropRgb(rgb, dec.w, dec.h, b)
+    fs.writeFileSync(candFile, pngEncodeRGB(c.data, c.w, c.h))
+    return c
+  }
+  const overlapOk = (a, b) => {
+    const ix = Math.max(0, Math.min(a[0] + a[2], b[0] + b[2]) - Math.max(a[0], b[0]))
+    const iy = Math.max(0, Math.min(a[1] + a[3], b[1] + b[3]) - Math.max(a[1], b[1]))
+    const inter = ix * iy
+    const uni = a[2] * a[3] + b[2] * b[3] - inter
+    return uni > 0 && inter / uni > 0.75
+  }
+  const score = async (b) => {
+    if (b.w < 8 || b.h < 8) return { score: -1, posOk: false, at: null }
+    writeCand(b)
+    const r = await spawnRecoChild({
+      resourceDir, type: 'TemplateMatch', image: frameFile, templateImage: candFile, cases: [{}],
+    }, 60000)
+    if (!r || !r.ok) return { score: -1, posOk: false, at: null }
+    /* 子进程回 ok 但**一个 case 结果都没有**：识别压根没跑起来（实测最常见的原因是资源目录里没有可加载的
+     * pipeline，reco 会安静地回 `results: []`）。这与"识别跑了但没命中"是两回事——后者仍会有 1 条结果
+     * （hit:false）。记下来，别让它被下面的判据翻译成"低纹理/不独特"。 */
+    if (!Array.isArray(r.results) || r.results.length === 0) {
+      selfMatchDead = true
+      return { score: -1, posOk: false, at: null, noResults: true }
+    }
+    const det = r.results && r.results[0] ? r.results[0].detail : null
+    const best = det && det.detail && det.detail.best
+    if (!best || !Array.isArray(best.box)) return { score: 0, posOk: false, at: null }
+    const at = best.box.map(Number)
+    return { score: Number(best.score), posOk: overlapOk(at, [b.x, b.y, b.w, b.h]), at }
+  }
+  const obj = (s) => (s.posOk ? 1000 : 0) + s.score
+  /** 自匹配有没有跑起来（子进程回空结果 = 没跑起来）。跑到这里说明资源加载不出识别节点。 */
+  let selfMatchDead = false
+  const clampBox = (b) => ({
+    x: Math.max(0, b.x), y: Math.max(0, b.y),
+    w: Math.min(b.w, dec.w - Math.max(0, b.x)), h: Math.min(b.h, dec.h - Math.max(0, b.y)),
+  })
+  /* 候选池：snap 可能塌成细条（背景差分在混合内容上会选中稀疏行带），单靠它起步会让
+   * ±2px 精修困死在退化框里——**两路**收紧框、加边距、外扩档、原始宽松框都进池，位置正确者优先。
+   * 更紧的一路排前面：`obj` 相同时保留先入者，于是"同样位置正确、同样满分"时选更贴合的那个。 */
+  const cands = []
+  const pushFamily = (t, src) => {
+    if (!t) return
+    const box = { x: box0.x + t.x, y: box0.y + t.y, w: t.w, h: t.h }
+    cands.push({ ...box, src })
+    cands.push({ ...clampBox({ x: box.x - 4, y: box.y - 4, w: box.w + 8, h: box.h + 8 }), src: src + '+4' })
+    for (const f of [0.25, 0.5]) {
+      cands.push({
+        ...clampBox({
+          x: Math.round(box.x - box.w * f / 2), y: Math.round(box.y - box.h * f / 2),
+          w: Math.round(box.w * (1 + f)), h: Math.round(box.h * (1 + f)),
+        }),
+        src: src + '+' + Math.round(f * 100) + '%',
+      })
+    }
+  }
+  for (const f of [{ t: tightBg, src: 'bg' }, { t: tightEdge, src: 'edge' }]
+    .filter((x) => x.t)
+    .sort((a, b) => a.t.w * a.t.h - b.t.w * b.t.h)) pushFamily(f.t, f.src)
+  /* 池里最后放原始宽松框：**只在没被提前命中跳过时**它才会被评过分，有就如实带上。 */
+  const looseCand = { ...box0, src: 'loose' }
+  cands.push(looseCand)
+  let cand = cands[0]
+  let candSrc = cand.src
+  let best = { score: -1, posOk: false, at: null }
+  let bestObj = -Infinity
+  let looseScored = null
+  const tries = { n: 0 }
+  for (const c of cands) {
+    const s = await score(c)
+    if (c === looseCand) looseScored = s
+    tries.n++
+    if (obj(s) > bestObj) { cand = c; best = s; bestObj = obj(s); candSrc = c.src }
+    if (best.posOk && best.score >= 0.99) break
+  }
+  /* 逐边移动（每边独立尝试内收/外扩 2px，取更优） */
+  const moves = [
+    { k: 'left', apply: (b) => clampBox({ x: b.x - 2, y: b.y, w: b.w + 2, h: b.h }) },
+    { k: 'right', apply: (b) => clampBox({ x: b.x, y: b.y, w: b.w + 2, h: b.h }) },
+    { k: 'top', apply: (b) => clampBox({ x: b.x, y: b.y - 2, w: b.w, h: b.h + 2 }) },
+    { k: 'bottom', apply: (b) => clampBox({ x: b.x, y: b.y, w: b.w, h: b.h + 2 }) },
+    { k: 'left-in', apply: (b) => clampBox({ x: b.x + 2, y: b.y, w: b.w - 2, h: b.h }) },
+    { k: 'right-in', apply: (b) => clampBox({ x: b.x, y: b.y, w: b.w - 2, h: b.h }) },
+    { k: 'top-in', apply: (b) => clampBox({ x: b.x, y: b.y + 2, w: b.w, h: b.h - 2 }) },
+    { k: 'bottom-in', apply: (b) => clampBox({ x: b.x, y: b.y, w: b.w, h: b.h - 2 }) },
+  ]
+  for (let round = 0; round < 2; round++) {
+    let improved = false
+    for (const mv of moves) {
+      const nb = mv.apply(cand)
+      if (nb.w < 8 || nb.h < 8 || (nb.x + nb.w > dec.w) || (nb.y + nb.h > dec.h)) continue
+      if (nb.x === cand.x && nb.y === cand.y && nb.w === cand.w && nb.h === cand.h) continue
+      const s = await score(nb)
+      tries.n++
+      if (obj(s) > bestObj + 1e-3) { cand = nb; best = s; bestObj = obj(s); improved = true; candSrc = 'refine' }
+    }
+    if (!improved) break
+  }
+  /* 贴合度信号（这一条是**免费**的：两个框都是现成的）。
+   * 为什么不是"两个框各自的得分对比"：实测同一元素在 40×61（元素本体）/ 80×80（点选窗口）/
+   * 120×120（更大窗口）三种情况下自匹配**都是 1.0** 且都落回自己——像素完全相同，
+   * 自匹配本质上是自洽指标，分辨不出"框不贴合"。几何比例才分辨得出。
+   * `grew` = 最后选中的候选比宽松框还大：背景差分在这块内容上没收到元素边界（背景自带纹理时
+   * 实测常见），或收紧塌成细条后带边距的候选赢了。留白留下的后果是 Click 的随机落点可能落在元素外。 */
+  const looseArea = box0.w * box0.h
+  const boxArea = cand.w * cand.h
+  const areaRatio = looseArea > 0 ? Math.round((boxArea / looseArea) * 1000) / 1000 : null
+  const tighten = {
+    from: [box0.w, box0.h],
+    to: [cand.w, cand.h],
+    areaRatio,
+    grew: boxArea > looseArea,
+    /* 两路收紧各自给出的框（含自适应阈值）：定标时看"谁赢、差多少" */
+    bgBox: tightBg ? [tightBg.w, tightBg.h] : null,
+    edgeBox: tightEdge ? [tightEdge.w, tightEdge.h] : null,
+    ...(tightEdge ? { edgeThresh: tightEdge.thresh, edgeBgLevel: tightEdge.bgLevel } : {}),
+    /** 最终框来自哪一族：bg / edge / bg+4 / edge+25% / loose / refine */
+    winner: candSrc ?? null,
+    /* 宽松框自己的自匹配结果：有就带上（多数情况下被池内提前命中跳过，为 null 是正常的） */
+    ...(looseScored ? { looseMatch: { score: Math.round(looseScored.score * 1000) / 1000, positionOk: looseScored.posOk } } : {}),
+  }
+  const fitWarn = tighten.grew
+    ? 'snap 收紧反而放大：' + box0.w + 'x' + box0.h + ' → ' + cand.w + 'x' + cand.h + '（面积 ' + areaRatio + '×）；' +
+      '自匹配照样 1.0（它只证明模板与源帧一致，不证明框贴合）。留白仍在——Click 的随机落点可能落在元素外，' +
+      '换更贴合的框或把 target 收窄'
+    : (areaRatio !== null && areaRatio < 0.35
+        ? 'snap 把框收到了 ' + areaRatio + '×（' + box0.w + 'x' + box0.h + ' → ' + cand.w + 'x' + cand.h +
+          '）：属"塌陷"（定标数据里它位置通常仍正确），确认没把元素本身裁掉'
+        : null)
+  /* 跨帧验证：同帧自匹配 1.0 只证明模板与源帧一致；真正要的是在新帧上仍稳定。
+   * 连接着真机就再抓一帧验证，得分大幅衰减或位置漂移 → 模板跨帧不稳，如实警告。
+   * 库帧路径默认不做：留存帧对应的状态通常已不在画面上，拿当前帧比会得到假警告；
+   * 状态可复现时显式给 cross:true 才做。 */
+  let cross = null
+  const wantCross = kf ? args.cross === true : args.cross !== false
+  if (S.ctrl && wantCross) {
+    const fresh = await captureNow('tpl-verify')
+    if (fresh.ok) {
+      writeCand(cand)
+      const frame2 = path.join(os.tmpdir(), 'maa_tpl_frame2_' + Date.now() + '.png')
+      try {
+        fs.writeFileSync(frame2, S.l0.roll[S.l0.roll.length - 1].png)
+        const r2 = await spawnRecoChild({
+          resourceDir, type: 'TemplateMatch', image: frame2, templateImage: candFile, cases: [{}],
+        }, 60000)
+        const det = r2 && r2.ok && r2.results && r2.results[0] ? r2.results[0].detail : null
+        const b2 = det && det.detail && det.detail.best
+        cross = {
+          seq: fresh.seq,
+          score: b2 ? Math.round(Number(b2.score) * 1000) / 1000 : 0,
+          posOk: b2 && Array.isArray(b2.box) ? overlapOk(b2.box.map(Number), [cand.x, cand.y, cand.w, cand.h]) : false,
+          ...(b2 && Array.isArray(b2.box) ? { box: b2.box.map(Number) } : {}),
+        }
+      } finally {
+        try { fs.rmSync(frame2, { force: true }) } catch (e) { /* ignore */ }
+      }
+    }
+  }
+  try { if (!kf) fs.rmSync(frameFile, { force: true }); fs.rmSync(candFile, { force: true }) } catch (e) { /* ignore */ }
+
+  const final = cropRgb(rgb, dec.w, dec.h, cand)
+  const out = args.out || defaultOutFile(S.runDir, 'tpl').file
+  fs.mkdirSync(path.dirname(out), { recursive: true })
+  fs.writeFileSync(out, pngEncodeRGB(final.data, final.w, final.h))
+  const warn = selfMatchDead
+    ? '自匹配没跑起来：识别子进程一个结果都没回（实测最常见原因是资源目录里没有可加载的 pipeline）。' +
+      '这不是"模板不独特"——先写一个 pipeline 节点，或用 --resource-dir 指向真实资源，再重跑这次的框；' +
+      '在此之前它**未经自匹配验证**，不要拿它去写 pipeline'
+    : !best.posOk
+      ? '低纹理/不独特：模板在同帧上都定位不到自己（best 落在 ' + JSON.stringify(best.at) + '，得分 ' +
+        best.score.toFixed(3) + '）——换更纹理化的框，或走点选路径'
+      : (best.score < 0.7 ? '得分偏低（' + best.score.toFixed(3) + '）但位置正确：可用，注意跨帧稳定性' : null)
+  /* 模板空间 = 源帧捕获时的控制器尺寸。与当前控制器不一致时模板不能被当前识别空间直接使用
+   * （契约 §5：坐标 / ROI 必须声明所属图像空间；改过 shortSide 或换过设备就会出现）。 */
+  const spaceCheck = S.ctrl && S.fullW && S.fullH
+    ? { current: { w: S.fullW, h: S.fullH }, match: S.fullW === dec.w && S.fullH === dec.h }
+    : { current: null, match: null }
+  const spaceWarn = spaceCheck.match === false
+    ? '源帧空间 ' + dec.w + 'x' + dec.h + ' ≠ 当前控制器 ' + S.fullW + 'x' + S.fullH +
+      '：模板按源帧空间裁出，与当前识别空间不一致（改过 shortSide / 换过设备？）'
+    : null
+  const crossWarn = cross && best.posOk && (cross.score < best.score - 0.15 || !cross.posOk)
+    ? '跨帧不稳：新帧（seq=' + cross.seq + '）上得分 ' + cross.score + (cross.posOk ? '' : '且位置漂移') +
+      '，源帧 ' + best.score.toFixed(3) + '——' +
+      (spaceCheck.match === false
+        /* 空间不同源时跨帧匹配本就不可比：别把它归因成"动态区域" */
+        ? '源帧空间与当前控制器不一致（见下条），该比对不成立，先在当前空间重采一帧再验'
+        : '模板对动态区域敏感，慎用于识别')
+    : null
+  const box = [cand.x, cand.y, cand.w, cand.h]
+  const looseBox = [box0.x, box0.y, box0.w, box0.h]
+  const selfScore = Math.round(best.score * 1000) / 1000
+  /* L2 出处：字段白名单见 buildL2Provenance；落点由上面的 provOut / 缺省"模板旁"决定 */
+  const provenance = buildL2Provenance({
+    source, loose: looseBox, box, snapped, score: selfScore, positionOk: best.posOk,
+    ...(best.at ? { selfMatchBox: best.at } : {}), tries: tries.n, cross,
+    w: final.w, h: final.h, createdAt: new Date().toISOString(),
+  })
+  let provPath = null
+  let provWarn = null
+  if (args.prov !== false) {
+    /* 出处落点：缺省写在模板旁（"同生共死"，复制/改名时出处跟着走）；给了 provOut 就写到那个目录下、
+     * 保持同文件名。**为什么需要它**：模板常常要放进资源包的 image/（框架会整目录打包发给用户），
+     * 而出处是给开发者/计划用的过程资产——留在包外能让资源包只装框架要加载的东西（实测该项目一条：
+     * 发行打包按 resource[].path 整目录拷贝，侧车会随包发出去）。约定不变量：**同一相对路径**，
+     * 目录根由项目自定（例如 state-plan/provenance/ 与 image/ 同构）。 */
+    const provOut = typeof args.provOut === 'string' && args.provOut ? String(args.provOut) : null
+    provPath = provOut ? path.join(provOut, path.basename(out) + '.prov.json') : out + '.prov.json'
+    try {
+      fs.mkdirSync(path.dirname(provPath), { recursive: true })
+      fs.writeFileSync(provPath, JSON.stringify(provenance, null, 2) + '\n')
+    } catch (e) {
+      provPath = null
+      provWarn = 'L2 出处记录写入失败：' + String(e && e.message || e) + '（模板已裁出，但其出处未落盘）'
+    }
+  }
+  /* 出处是"热缓存帧"时给出可行动提示：这种出处在进程结束后无从复核（seq 指不回任何东西）。
+   * 它本身不是错误（真机上现裁现用是合法动线），但**入库的模板**该有可复核的来源。 */
+  const keepWarn = keptSource && keptSource.error
+    ? '--keep-source 没能升格源帧（' + keptSource.error + '）：出处仍是热缓存来源，无从复核'
+    : null
+  const transientWarn = provenance.derivedFrom.kind === 'l0-cache'
+    ? '出处来源是热缓存帧（seq=' + provenance.derivedFrom.seq + '）：本进程结束后无从复核。' +
+      '要入库的模板加 --keep-source（顺手把这一帧升格进库）或先 kf promote 再裁'
+    : null
+  const warns = [fitWarn, warn, crossWarn, spaceWarn, provWarn, keepWarn, transientWarn].filter(Boolean)
+  return {
+    ok: true, path: out, seq: kf ? null : ent.seq, source,
+    provPath, provenance,
+    ...(keptSource ? { keptSource } : {}),
+    box, loose: looseBox,
+    tighten,
+    snapped, score: selfScore,
+    positionOk: best.posOk,
+    ...(best.at ? { selfMatchBox: best.at } : {}),
+    ...(cross ? { cross } : {}),
+    tries: tries.n,
+    w: final.w, h: final.h,
+    ctrlW: dec.w, ctrlH: dec.h,
+    spaceCheck,
+    ...(warns.length ? { warn: warns[0], warns } : {}),
+  }
+}
+
+/* ────────────────────────── 探色（ROI 实测，模型只选色不报色值） ──────────────────────────
+ * 在缓冲帧（小图）上实测 ROI 的均值/HSV/主色；坐标用控制器空间（与 frame_get --roi 同语义，
+ * 按该帧捕获时尺寸换算）。选色后用 reco ColorMatch 出框（走已修好的参数透传链）。 */
+function rgbToHsv(r, g, b) {
+  const mx = Math.max(r, g, b), mn = Math.min(r, g, b), d = mx - mn
+  let h = 0
+  if (d !== 0) {
+    if (mx === r) h = ((g - b) / d + 6) % 6
+    else if (mx === g) h = (b - r) / d + 2
+    else h = (r - g) / d + 4
+    h *= 60
+  }
+  return { h: Math.round(h), s: Math.round(mx ? (d / mx) * 100 : 0), v: Math.round((mx / 255) * 100) }
+}
+
+function cmdColorProbe(args) {
+  const fr = args.seq !== undefined && args.seq !== null
+    ? S.ring.find((r) => r.seq === Number(args.seq))
+    : S.ring[S.ring.length - 1]
+  if (!fr) {
+    return { ok: false, error: '缓冲无可用帧（seq=' + args.seq + '）：先 screencap 或 stream start 产生观测' }
+  }
+  let rx = 0, ry = 0, rw = fr.w, rh = fr.h
+  let ctrlRoi = null
+  const roiIn = readRoi(args.roi)
+  if (roiIn.error) return { ok: false, error: roiIn.error }
+  if (roiIn.roi) {
+    const [x, y, w, h] = roiIn.roi
+    const sx = fr.fw > 0 ? fr.w / fr.fw : 1
+    const sy = fr.fh > 0 ? fr.h / fr.fh : 1
+    rx = Math.max(0, Math.floor(x * sx))
+    ry = Math.max(0, Math.floor(y * sy))
+    rw = Math.min(fr.w - rx, Math.max(1, Math.round(w * sx)))
+    rh = Math.min(fr.h - ry, Math.max(1, Math.round(h * sy)))
+    if (rx >= fr.w || ry >= fr.h || rw <= 0 || rh <= 0) {
+      return { ok: false, error: 'ROI 完全越界（' + JSON.stringify(args.roi) + ' vs 捕获时 ' + fr.fw + 'x' + fr.fh + '）' }
+    }
+    ctrlRoi = [x, y, w, h]
+  }
+  let r = 0, g = 0, b = 0, n = 0
+  const buckets = new Map()
+  for (let y = ry; y < ry + rh; y++) {
+    for (let x = rx; x < rx + rw; x++) {
+      const i = (y * fr.w + x) * 3
+      const R = fr.rgb[i], G = fr.rgb[i + 1], B = fr.rgb[i + 2]
+      r += R; g += G; b += B; n++
+      const key = ((R >> 4) << 8) | ((G >> 4) << 4) | (B >> 4)
+      buckets.set(key, (buckets.get(key) || 0) + 1)
+    }
+  }
+  r = Math.round(r / n); g = Math.round(g / n); b = Math.round(b / n)
+  let dKey = 0, dCnt = 0
+  for (const [k, c] of buckets) if (c > dCnt) { dCnt = c; dKey = k }
+  const dom = [((dKey >> 8) & 15) * 17, ((dKey >> 4) & 15) * 17, (dKey & 15) * 17]
+  return {
+    ok: true, seq: fr.seq,
+    ...(ctrlRoi ? { roi: ctrlRoi } : {}),
+    pixelRoi: [rx, ry, rw, rh], count: n,
+    mean: { r, g, b, gray: Math.round(0.299 * r + 0.587 * g + 0.114 * b) },
+    hsv: rgbToHsv(r, g, b),
+    dominant: { rgb: dom, ratio: Math.round((dCnt / n) * 1000) / 1000 },
+    space: { small: [fr.w, fr.h], ctrl: [fr.fw, fr.fh] },
+  }
+}
+
+/* ────────────────────────── annotate（轻量 SoM：候选区域 + 编号回画） ──────────────────────────
+ * 候选源：OCR 框（MaaFW OCR 管线，detail.all）+ 连通域（积分图背景差 + BFS）+ 边缘密度
+ * （Sobel 块 z 值聚类）+ 变化 diff 区域（change 事件的 ctrl bbox）。回画编号图 + 候选表，
+ * 模型看图选号 → 查 ctrl 坐标 → click/reco。半透明/粒子/渐变场景候选质量降级，走点选路径。 */
+const FONT3X5 = {
+  0: ['111', '101', '101', '101', '111'], 1: ['010', '110', '010', '010', '111'],
+  2: ['111', '001', '111', '100', '111'], 3: ['111', '001', '111', '001', '111'],
+  4: ['101', '101', '111', '001', '001'], 5: ['111', '100', '111', '001', '111'],
+  6: ['111', '100', '111', '101', '111'], 7: ['111', '001', '001', '001', '001'],
+  8: ['111', '101', '111', '101', '111'], 9: ['111', '101', '111', '001', '111'],
+}
+function drawLabel(buf, w, h, x, y, num, color) {
+  const s = String(num)
+  const lw = s.length * 4 + 1, lh = 7
+  const px = Math.max(0, Math.min(w - lw, x)), py = Math.max(0, Math.min(h - lh, y))
+  for (let yy = 0; yy < lh; yy++) for (let xx = 0; xx < lw; xx++) {
+    const i = ((py + yy) * w + px + xx) * 3
+    buf[i] = 255; buf[i + 1] = 255; buf[i + 2] = 255
+  }
+  for (let k = 0; k < s.length; k++) {
+    const glyph = FONT3X5[s[k]]
+    for (let gy = 0; gy < 5; gy++) for (let gx = 0; gx < 3; gx++) {
+      if (glyph[gy][gx] !== '1') continue
+      const i = ((py + 1 + gy) * w + px + 1 + k * 4 + gx) * 3
+      buf[i] = color[0]; buf[i + 1] = color[1]; buf[i + 2] = color[2]
+    }
+  }
+}
+function drawRect(buf, w, h, box, color) {
+  const [x, y, bw, bh] = box
+  const x1 = Math.min(w - 1, x + bw - 1), y1 = Math.min(h - 1, y + bh - 1)
+  for (let xx = Math.max(0, x); xx <= x1; xx++) {
+    for (const yy of [Math.max(0, y), y1]) {
+      const i = (yy * w + xx) * 3
+      buf[i] = color[0]; buf[i + 1] = color[1]; buf[i + 2] = color[2]
+    }
+  }
+  for (let yy = Math.max(0, y); yy <= y1; yy++) {
+    for (const xx of [Math.max(0, x), x1]) {
+      const i = (yy * w + xx) * 3
+      buf[i] = color[0]; buf[i + 1] = color[1]; buf[i + 2] = color[2]
+    }
+  }
+}
+
+/** 灰度图积分图 → 均值背景 → 背景差二值 → BFS 连通域（面积过滤） */
+/** 连通域候选（形态学偏离块 + BFS 成框）。stats 回填被面积窗与"太扁"拒掉的数量。 */
+function connComponents(rgb, w, h, stats = null) {
+  const gray = new Float64Array(w * h)
+  for (let i = 0, p = 0; i < w * h; i++, p += 3) {
+    gray[i] = (rgb[p] * 3 + rgb[p + 1] * 6 + rgb[p + 2]) * 0.1
+  }
+  const integ = new Float64Array((w + 1) * (h + 1))
+  for (let y = 0; y < h; y++) {
+    let rowSum = 0
+    for (let x = 0; x < w; x++) {
+      rowSum += gray[y * w + x]
+      integ[(y + 1) * (w + 1) + (x + 1)] = integ[y * (w + 1) + (x + 1)] + rowSum
+    }
+  }
+  const R = 12
+  const dev = new Uint8Array(w * h)
+  for (let y = 0; y < h; y++) {
+    const y0 = Math.max(0, y - R), y1 = Math.min(h, y + R + 1)
+    for (let x = 0; x < w; x++) {
+      const x0 = Math.max(0, x - R), x1 = Math.min(w, x + R + 1)
+      const area = (x1 - x0) * (y1 - y0)
+      const sum = integ[y1 * (w + 1) + x1] - integ[y0 * (w + 1) + x1] - integ[y1 * (w + 1) + x0] + integ[y0 * (w + 1) + x0]
+      if (Math.abs(gray[y * w + x] - sum / area) > 26) dev[y * w + x] = 1
+    }
+  }
+  const seen = new Uint8Array(w * h)
+  const boxes = []
+  const queue = new Int32Array(w * h)
+  for (let start = 0; start < w * h; start++) {
+    if (!dev[start] || seen[start]) continue
+    let qs = 0, qe = 0
+    queue[qe++] = start
+    seen[start] = 1
+    let minX = w, minY = h, maxX = 0, maxY = 0, area = 0
+    while (qs < qe) {
+      const p = queue[qs++]
+      const px = p % w, py = (p / w) | 0
+      area++
+      if (px < minX) minX = px; if (px > maxX) maxX = px
+      if (py < minY) minY = py; if (py > maxY) maxY = py
+      if (px > 0 && dev[p - 1] && !seen[p - 1]) { seen[p - 1] = 1; queue[qe++] = p - 1 }
+      if (px < w - 1 && dev[p + 1] && !seen[p + 1]) { seen[p + 1] = 1; queue[qe++] = p + 1 }
+      if (py > 0 && dev[p - w] && !seen[p - w]) { seen[p - w] = 1; queue[qe++] = p - w }
+      if (py < h - 1 && dev[p + w] && !seen[p + w]) { seen[p + w] = 1; queue[qe++] = p + w }
+    }
+    if (area >= 120 && area <= 24000 && maxX - minX >= 10 && maxY - minY >= 10) {
+      boxes.push([minX, minY, maxX - minX + 1, maxY - minY + 1])
+      if (stats) stats.passed++
+    } else if (stats) {
+      /* 三类拒绝分开记：面积窗（120–24000）与"太扁"是分辨率/内容相关的两道不同门槛，
+       * 混成一个数字就看不出"换分辨率会不会漂"。 */
+      if (area < 120) stats.tooSmall++
+      else if (area > 24000) stats.tooLarge++
+      else stats.tooNarrow++
+    }
+  }
+  return boxes
+}
+
+/** Sobel 边缘密度的块级聚类（16px 块，z 值超限块 BFS 成框）。
+ * opts.z / opts.min 是**测量用覆盖**（默认即生产常数 1.2 / 2000）：edge 源长期只出个位数候选，
+ * 要判断"是阈值太严还是这类内容真没边缘"，就得能调着量。stats 回填被两道门槛与簇大小拒掉的数量。 */
+function edgeDensityBoxes(rgb, w, h, opts = {}, stats = null) {
+  const BS = 16
+  const bw = Math.ceil(w / BS), bh = Math.ceil(h / BS)
+  const mag = new Float64Array(w * h)
+  for (let y = 1; y < h - 1; y++) {
+    for (let x = 1; x < w - 1; x++) {
+      const i = (y * w + x) * 3
+      const gx = (rgb[i + 3] * 2 + rgb[i - w * 3 + 3] + rgb[i + w * 3 + 3]) - (rgb[i - 3] * 2 + rgb[i - w * 3 - 3] + rgb[i + w * 3 - 3])
+      const gy = (rgb[i + w * 3] * 2 + rgb[i + w * 3 + 1] + rgb[i + w * 3 - 1]) - (rgb[i - w * 3] * 2 + rgb[i - w * 3 + 1] + rgb[i - w * 3 - 1])
+      mag[y * w + x] = Math.abs(gx) + Math.abs(gy)
+    }
+  }
+  const blk = new Float64Array(bw * bh)
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) blk[((y / BS) | 0) * bw + ((x / BS) | 0)] += mag[y * w + x]
+  let mean = 0
+  for (const v of blk) mean += v
+  mean /= blk.length
+  let sd = 0
+  for (const v of blk) sd += (v - mean) * (v - mean)
+  sd = Math.sqrt(sd / blk.length)
+  const hot = new Uint8Array(bw * bh)
+  const Z = Number(opts.z) > 0 ? Number(opts.z) : 1.2
+  const MIN = Number(opts.min) > 0 ? Number(opts.min) : 2000
+  /* stats 只记账不改行为：被两道门槛拒掉多少块，是"edge 为什么不出力"唯一能看的证据。 */
+  for (let k = 0; k < blk.length; k++) {
+    if (blk[k] <= mean + Z * sd) { if (stats) stats.belowZ++; continue }
+    if (blk[k] <= MIN) { if (stats) stats.belowMin++; continue }
+    hot[k] = 1
+  }
+  const seen = new Uint8Array(bw * bh)
+  const boxes = []
+  const stack = []
+  for (let k = 0; k < bw * bh; k++) {
+    if (!hot[k] || seen[k]) continue
+    stack.length = 0
+    stack.push(k)
+    seen[k] = 1
+    let minX = bw, minY = bh, maxX = 0, maxY = 0, n = 0
+    while (stack.length) {
+      const p = stack.pop()
+      const px = p % bw, py = (p / bw) | 0
+      n++
+      if (px < minX) minX = px; if (px > maxX) maxX = px
+      if (py < minY) minY = py; if (py > maxY) maxY = py
+      for (const [dx, dy] of [[1, 0], [-1, 0], [0, 1], [0, -1]]) {
+        const nx = px + dx, ny = py + dy
+        if (nx < 0 || ny < 0 || nx >= bw || ny >= bh) continue
+        const q = ny * bw + nx
+        if (hot[q] && !seen[q]) { seen[q] = 1; stack.push(q) }
+      }
+    }
+    if (n >= 2) {
+      const x = minX * BS, y = minY * BS
+      boxes.push([x, y, Math.min(w - x, (maxX - minX + 1) * BS), Math.min(h - y, (maxY - minY + 1) * BS)])
+      if (stats) stats.passed++
+    } else if (stats) stats.singleBlock++
+  }
+  return boxes
+}
+
+const SOM_COLORS = { ocr: [0, 190, 255], conn: [60, 220, 60], edge: [255, 160, 0], diff: [255, 70, 70] }
+const SOM_PRIORITY = { ocr: 0, diff: 1, conn: 2, edge: 3 }
+
+/**
+ * 上限截断：按**横向分带轮转**取样，而不是直接截前 N 个。
+ *
+ * 为什么：候选是先按源优先级、再按扫描顺序（自上而下）排的，直接截前 N 个会让候选表系统性偏顶部。
+ * 实测（6 帧 1280×720，上限 30）：合并总数中位数 54、最大 135，默认上限只放出 41%；
+ * 大厅帧 63 个底部候选**一个都没进表**，看上去像"底部没有可点区域"——那是策略造成的假象，
+ * 不是画面事实。轮转后各带按供给比例进表，源优先级在带内仍然保持。
+ */
+function pickBalancedCandidates(list, limit, h) {
+  const bands = [[], [], []]
+  for (const c of list) {
+    const cy = c.box[1] + c.box[3] / 2
+    bands[cy < h / 3 ? 0 : (cy < (2 * h) / 3 ? 1 : 2)].push(c)
+  }
+  /* 带内再按**来源轮转**。为什么：合并池是按源优先级（ocr > diff > conn > edge）排的，
+   * 而一个带里 OCR 常有几十条——直接把 conn / edge 挤光。偏偏**图标类目标多来自 conn / edge**
+   * （实测：主页面顶部那个图标在合并池里排 #55，默认上限 30 时永远进不了表，覆盖率 0%；
+   * 上限放开到 200 才出现，覆盖 62%）。来源轮转保证每带每一路都有代表，源优先级只决定同轮先后。 */
+  const interleave = (b) => {
+    const groups = {}
+    for (const c of b) (groups[c.source] = groups[c.source] || []).push(c)
+    const srcs = Object.keys(groups).sort((x, y) => (SOM_PRIORITY[x] ?? 9) - (SOM_PRIORITY[y] ?? 9))
+    const res = []
+    for (let i = 0; ; i++) {
+      let any = false
+      for (const s of srcs) {
+        if (groups[s][i]) { res.push(groups[s][i]); any = true }
+      }
+      if (!any) break
+    }
+    return res
+  }
+  const ordered = bands.map(interleave)
+  const out = []
+  for (let i = 0; out.length < limit; i++) {
+    let taken = false
+    for (const b of ordered) {
+      if (!b[i]) continue
+      out.push(b[i])
+      taken = true
+      if (out.length >= limit) break
+    }
+    if (!taken) break
+  }
+  return out
+}
+
+async function cmdAnnotate(args) {
+  /* 工作图两条路：会话内 L1 小图（缺省）或关键帧库留存帧（kfSource，控制器分辨率、**可无设备**）。
+   * 小图路径的候选要按该帧捕获时尺寸换算回控制器空间；库帧本身就是控制器空间，换算系数为 1。
+   * diff 源依赖会话内 change 事件——库帧路径没有，如实报不可用，不拿别的区域顶替（不冒称）。 */
+  let work = null
+  let seq = null
+  let source = null
+  let detectionSource = null
+  if (args.kfSource) {
+    const kf = readKfCropSource(args.kfSource)
+    if (kf.error) return { ok: false, error: kf.error }
+    work = { rgb: toRgb(kf.dec), w: kf.dec.w, h: kf.dec.h, fw: 0, fh: 0 }
+    source = kf.source
+    detectionSource = 'kf-frame'
+  } else {
+    const fr = args.seq !== undefined && args.seq !== null
+      ? S.ring.find((r) => r.seq === Number(args.seq))
+      : S.ring[S.ring.length - 1]
+    if (!fr) return { ok: false, error: '缓冲无可用帧（seq=' + args.seq + '）：先 screencap / stream 产生观测' }
+    /* 检测面分辨率：有同一 seq 的 L0 全分辨率原图就**优先用它**。
+     * 为什么：候选检测的分辨率下限直接决定"小图标能不能被找到"。实测大厅顶部那个 42×55 的图标，
+     * 在 480 宽的 L1 上四个源一个都没探到（合并池仅 30 条、无截断，却仍然没有它），
+     * 在 1280 宽的原图上 conn 一次就命中（527,36,42,55）——漏报的根因是分辨率，不是上限。
+     * L1 只作降级（L0 已淘汰时），且回执里如实标注，别让人以为降级图和原图同源。
+     * `somScale: 'small'` 可强制走小图（要快、且只关心大目标时）。 */
+    let det = null
+    if (String(args.somScale ?? 'full') !== 'small') {
+      const l0 = findL0(fr.seq)
+      if (l0) {
+        try {
+          const dec = pngDecode(l0.png)
+          det = { rgb: toRgb(dec), w: dec.w, h: dec.h }
+        } catch (e) { det = null }
+      }
+    }
+    work = det
+      ? { rgb: det.rgb, w: det.w, h: det.h, fw: det.w, fh: det.h }
+      : { rgb: fr.rgb, w: fr.w, h: fr.h, fw: fr.fw, fh: fr.fh }
+    seq = fr.seq
+    detectionSource = det ? 'l0-full' : 'l1-ring'
+    source = {
+      kind: detectionSource, seq: fr.seq, ctrlW: fr.fw, ctrlH: fr.fh,
+      ...(det ? {} : {
+        degraded: true,
+        note: 'L0 全分辨率原图已淘汰，检测在降采样图上进行（' + fr.w + 'x' + fr.h
+          + '，有效 ' + (fr.w / Math.max(1, fr.fw)).toFixed(3) + '×）：小目标可能根本探不到。'
+          + '要全分辨率就在截图后立刻跑 annotate，或先 kf promote 留存该帧再 --from-kf。',
+      }),
+    }
+  }
+  const sx = work.fw > 0 ? work.fw / work.w : 1
+  const sy = work.fh > 0 ? work.fh / work.h : 1
+  const toCtrl = (b) => [Math.round(b[0] * sx), Math.round(b[1] * sy), Math.round(b[2] * sx), Math.round(b[3] * sy)]
+  const raw = []
+
+  /* 源 1：OCR 框（子进程跑 MaaFW OCR，detail.all 是全部文本框） */
+  if (args.resourceDir) {
+    const imgFile = path.join(os.tmpdir(), 'maa_som_' + Date.now() + '.png')
+    try {
+      fs.writeFileSync(imgFile, pngEncodeRGB(work.rgb, work.w, work.h))
+      const r = await spawnRecoChild({ resourceDir: String(args.resourceDir), type: 'OCR', image: imgFile, cases: [{}] }, 60000)
+      if (r && r.ok) {
+        const det = r.results && r.results[0] && r.results[0].detail
+        const all = det && det.detail && Array.isArray(det.detail.all) ? det.detail.all : []
+        for (const hit of all) {
+          if (!Array.isArray(hit.box) || Number(hit.score) < 0.5) continue
+          raw.push({ source: 'ocr', box: hit.box.map(Number), extra: { text: String(hit.text ?? ''), score: Number(hit.score) } })
+        }
+      }
+    } finally {
+      try { fs.rmSync(imgFile, { force: true }) } catch (e) { /* ignore */ }
+    }
+  }
+  /* 源 2/3：连通域与边缘密度（纯 CPU，小图上毫秒级）；stats 记下被门槛拒掉的数量——
+   * "某段没有候选"到底是看不见还是被过滤掉，只有这个计数能回答（分辨率变化时尤其要紧）。 */
+  const connStats = { passed: 0, tooSmall: 0, tooLarge: 0, tooNarrow: 0 }
+  const edgeStats = { passed: 0, belowZ: 0, belowMin: 0, singleBlock: 0 }
+  for (const b of connComponents(work.rgb, work.w, work.h, connStats)) raw.push({ source: 'conn', box: b })
+  for (const b of edgeDensityBoxes(work.rgb, work.w, work.h, { z: args.somEdgeZ, min: args.somEdgeMin }, edgeStats)) {
+    raw.push({ source: 'edge', box: b })
+  }
+  /* 源 4：最近 change 事件的 diff 区域（ctrl → 小图坐标）；库帧路径没有会话事件 */
+  const diffs = []
+  if (!args.kfSource) {
+    for (let i = S.events.length - 1; i >= 0 && diffs.length < 3; i--) {
+      const ev = S.events[i]
+      if (ev.type === 'change' && ev.region && ev.region.ctrl) diffs.push(ev.region.ctrl)
+    }
+  }
+  for (const c of diffs) {
+    raw.push({ source: 'diff', box: [Math.round(c[0] / sx), Math.round(c[1] / sy), Math.round(c[2] / sx), Math.round(c[3] / sy)] })
+  }
+
+  /* 去重合并：IoU>0.6 保留优先级高的源（ocr > diff > conn > edge）；上限缺省 30。
+   * somLimit 是**测量用覆盖**：不放开上限就量不到"被截断前有多少候选"，也就无法判断 30 该不该动。 */
+  const LIMIT = Number(args.somLimit) > 0 ? Math.floor(Number(args.somLimit)) : 30
+  raw.sort((a, b) => (SOM_PRIORITY[a.source] ?? 9) - (SOM_PRIORITY[b.source] ?? 9))
+  const iou = (a, b) => {
+    const ix = Math.max(0, Math.min(a[0] + a[2], b[0] + b[2]) - Math.max(a[0], b[0]))
+    const iy = Math.max(0, Math.min(a[1] + a[3], b[1] + b[3]) - Math.max(a[1], b[1]))
+    const inter = ix * iy
+    const uni = a[2] * a[3] + b[2] * b[3] - inter
+    return uni > 0 ? inter / uni : 0
+  }
+  /* 巨框剔除：面积占画面比例过大的候选几乎必是背景 / 立绘 / 整屏变化区——对"找可点目标"是纯噪音，
+   * 而且因为面积大反而**遮住真目标**（实测每帧稳定 2 个，含一次 1280×720 全屏）。
+   * OCR 框不参与：文本包围盒天然有界，且是全表里最可信的一路。 */
+  const frameArea = work.w * work.h
+  const maxRatio = Number(args.somMaxAreaRatio) > 0 ? Number(args.somMaxAreaRatio) : 0.12
+  const dropped = { tooSmall: 0, tooBig: 0, duplicated: 0 }
+  const merged = []
+  const IOU = Number(args.somIoU) > 0 ? Math.min(0.99, Number(args.somIoU)) : 0.6
+  for (const c of raw) {
+    if (c.box[2] < 8 || c.box[3] < 8) { dropped.tooSmall++; continue }
+    const ratio = (c.box[2] * c.box[3]) / frameArea
+    if (c.source !== 'ocr' && ratio > maxRatio) { dropped.tooBig++; continue }
+    if (merged.some((x) => iou(x.box, c.box) > IOU)) { dropped.duplicated++; continue }
+    merged.push(c)
+  }
+  /* ROI 收窄（可选）：只保留**落在给定区域**的候选，且这一步在**取上限之前**做——
+   * 于是这个区域里的候选只跟自己竞争，不会因为画面别处有 160 条而被挤掉。
+   * 这是"上限截断"的正解：不是把上限调大（那是把上下文成本推给调用方），而是把搜索面收小。 */
+  const roiIn = readRoi(args.roi)
+  if (roiIn.error) return { ok: false, error: roiIn.error }
+  const ctrlW0 = work.fw > 0 ? work.fw : work.w
+  const ctrlH0 = work.fh > 0 ? work.fh : work.h
+  let pool = merged
+  let roiApplied = null
+  if (roiIn.roi) {
+    const [rx, ry, rw, rh] = roiIn.roi
+    const sx0 = work.w / Math.max(1, ctrlW0)
+    const sy0 = work.h / Math.max(1, ctrlH0)
+    const inRoi = (box) => {
+      const cx = (box[0] + box[2] / 2) * (1 / sx0)
+      const cy = (box[1] + box[3] / 2) * (1 / sy0)
+      return cx >= rx && cx <= rx + rw && cy >= ry && cy <= ry + rh
+    }
+    pool = merged.filter((c) => inRoi(c.box))
+    roiApplied = { roi: [rx, ry, rw, rh], inPool: pool.length, outsideRoi: merged.length - pool.length }
+  }
+  const cands = pickBalancedCandidates(pool, LIMIT, work.h)  /* 分带可用性：三分带各自"进表多少 / 合并池里有多少"。上限截断是分带轮转的，
+   * 于是"这一带没有候选"要么是供给真没有、要么是被门槛拒了或被上限截了——三列一起读才可归因。 */
+  const bandOf = (cy, h) => (cy < h / 3 ? 0 : (cy < (2 * h) / 3 ? 1 : 2))
+  const bandCount = (arr, bi) => arr.filter((c) => bandOf(c.box[1] + c.box[3] / 2, work.h) === bi).length
+  const bands = [0, 1, 2].map((bi) => ({
+    band: bi, yFrom: Math.round((bi * work.h) / 3), yTo: Math.round(((bi + 1) * work.h) / 3),
+    inPool: bandCount(pool, bi), inTable: bandCount(cands, bi),
+  }))
+  /* 回画：源配色边框 + 编号标签。**优先全分辨率**（回画物的用途是"人照着框选"，
+   * 480 宽的图在小目标上根本框不准——本案例实测被用户退回）。
+   * 检测若已用 L0，`work` 就是那张原图：**直接复用**，省掉第二次 PNG 解码，
+   * 也避免"检测时命中、回画时已淘汰"让来源标签说谎——中间隔着最长 60 秒的 OCR await，
+   * 而 L0 滚动窗在 10fps 下只有约 1.6 秒，这个竞态是真会发生的。
+   * 检测若走了降级小图，这里再试一次 L0：命中就能给出全分辨率回画（框按 kx 放大）。 */
+  let draw = { rgb: work.rgb, w: work.w, h: work.h, kx: 1, ky: 1, source: detectionSource ?? 'l1-ring' }
+  if (detectionSource !== 'l0-full' && !args.kfSource && seq !== null) {
+    const l0 = findL0(seq)
+    if (l0) {
+      try {
+        const dec = pngDecode(l0.png)
+        draw = { rgb: toRgb(dec), w: dec.w, h: dec.h, kx: dec.w / work.w, ky: dec.h / work.h, source: 'l0-full' }
+      } catch (e) { /* 解码失败就退回工作图 */ }
+    }
+  }
+  const buf = Buffer.from(draw.rgb)
+  cands.forEach((c, i) => {
+    const color = SOM_COLORS[c.source] ?? [200, 200, 200]
+    const sb = [
+      Math.round(c.box[0] * draw.kx), Math.round(c.box[1] * draw.ky),
+      Math.max(2, Math.round(c.box[2] * draw.kx)), Math.max(2, Math.round(c.box[3] * draw.ky)),
+    ]
+    drawRect(buf, draw.w, draw.h, sb, color)
+    drawLabel(buf, draw.w, draw.h, sb[0], Math.max(0, sb[1] - Math.round(8 * draw.ky)), i + 1, [20, 20, 20])
+  })
+  const out = args.out || defaultOutFile(S.runDir, 'som').file
+  fs.mkdirSync(path.dirname(out), { recursive: true })
+  /* ROI 收窄时把范围画出来（白色双线框）：人看图时才知道"表里这些是这一小块里的"，
+   * 不会误以为整屏就这些候选。 */
+  if (roiApplied) {
+    const sxr = draw.w / Math.max(1, ctrlW0)
+    const syr = draw.h / Math.max(1, ctrlH0)
+    const rb = [
+      Math.round(roiApplied.roi[0] * sxr), Math.round(roiApplied.roi[1] * syr),
+      Math.max(2, Math.round(roiApplied.roi[2] * sxr)), Math.max(2, Math.round(roiApplied.roi[3] * syr)),
+    ]
+    drawRect(buf, draw.w, draw.h, rb, [255, 255, 255])
+    drawRect(buf, draw.w, draw.h, [rb[0] + 1, rb[1] + 1, Math.max(2, rb[2] - 2), Math.max(2, rb[3] - 2)], [255, 255, 255])
+  }
+  fs.writeFileSync(out, pngEncodeRGB(buf, draw.w, draw.h))
+  const ctrlW = work.fw > 0 ? work.fw : work.w
+  const ctrlH = work.fh > 0 ? work.fh : work.h
+  /* 候选框的面积占比（控制器空间，与画面同尺度）：调用方可据此再排一次序——
+   * 面积越大越可能是面板/背景而不是小按钮。 */
+  const feat = (c) => {
+    const cb = toCtrl(c.box)
+    const r = (cb[2] * cb[3]) / Math.max(1, ctrlW * ctrlH)
+    return { ctrlBox: cb, areaRatio: Math.round(r * 10000) / 10000 }
+  }
+  return {
+    ok: true, out, seq, source, detectionSource,
+    small: [work.w, work.h], ctrl: [ctrlW, ctrlH],
+    count: cands.length,
+    limit: LIMIT,
+    mergedTotal: merged.length,
+    sources: { ocr: cands.filter((c) => c.source === 'ocr').length, conn: cands.filter((c) => c.source === 'conn').length, edge: cands.filter((c) => c.source === 'edge').length, diff: cands.filter((c) => c.source === 'diff').length },
+    /* 被门槛拒掉的候选：conn 的面积窗/太扁、edge 的两道门槛/单块簇。
+     * 与 sources 一起读，才知道"候选少"是内容如此还是被过滤掉了。 */
+    filtered: { conn: connStats, edge: edgeStats },
+    /* 可用性指标：**"看起来有结果"不等于"有结果"**。上限截断、巨框剔除、去重合并各扣了多少，
+     * 以及每带的供给/进表——没有这三列，调用方会把"30 条候选"读成"画面就这些可点区域"。 */
+    availability: {
+      limit: LIMIT,
+      mergedTotal: merged.length,
+      truncated: Math.max(0, pool.length - cands.length),
+      dropped,
+      maxAreaRatio: maxRatio,
+      ...(roiApplied ? { roi: roiApplied } : {}),
+      byBand: bands,
+      outResolution: { w: draw.w, h: draw.h, source: draw.source },
+      detectionResolution: { w: work.w, h: work.h, source: detectionSource ?? (args.kfSource ? 'kf-frame' : '?') },
+    },
+    ...(args.kfSource ? { sourcesUnavailable: { diff: '库帧路径无会话事件：diff 源不可用（不拿别的区域顶替）' } } : {}),
+    candidates: cands.map((c, i) => ({ id: i + 1, source: c.source, box: c.box, ctrl: toCtrl(c.box), ...feat(c), ...(c.extra ?? {}) })),
+    ...(cands.length === 0 ? { warn: '无候选：画面可能静止且低对比；换帧或走点选路径' } : {}),
+    ...(pool.length > LIMIT
+      ? { warn: '候选被上限截断：本区域池 ' + pool.length + ' 条，进表 ' + cands.length + ' 条。'
+          + (roiApplied ? '用更小的 roi 继续收窄' : '给 roi 把搜索面收小（这是正解），或给 somLimit 放开上限') }
+      : {}),
+  }
+}
+
+/* ────────────────────────── 阈值校准（静止画面噪声定标） ──────────────────────────
+ * 采集 N 帧（要求画面静止），统计相邻帧分块亮度差与全局位差率的分布，推荐
+ * blockThresh / changeGlobal。噪声地板之上留裕量，让真变化必超、静止必不超。
+ * 期间若有真实变化会抬高推荐值——max ≫ p99 时警告重跑。 */
+async function cmdCalibrate(args) {
+  if (!S.ctrl) return { ok: false, error: '未连接设备（先连接）' }
+  const frames = Math.min(60, Math.max(6, Number(args.frames ?? 24)))
+  const interval = Math.max(120, Number(args.interval ?? 300))
+  const blockDiffs = []
+  const globals = []
+  let last = null
+  for (let i = 0; i < frames; i++) {
+    const j = S.ctrl.post_screencap()
+    await j.wait()
+    const buf = j.get()
+    if (!buf || buf.byteLength < 8) return { ok: false, error: '第 ' + (i + 1) + ' 帧截图失败' }
+    const b = Buffer.from(buf)
+    const dec = pngDecode(b)
+    pushFrame(dec, b)   // 校准采集也是观测（进环进 L0，可复核）
+    const small = downscale(toRgb(dec), dec.w, dec.h, S.streamScale)
+    const { hash, means } = blockAnalyze(small.data, small.w, small.h)
+    if (last) {
+      globals.push(hashDist(last.hash, hash))
+      for (let k = 0; k < 64; k++) blockDiffs.push(Math.abs(means[k] - last.means[k]))
+    }
+    last = { hash, means }
+    if (i < frames - 1) await sleep(interval)
+  }
+  blockDiffs.sort((a, b) => a - b)
+  globals.sort((a, b) => a - b)
+  const pct = (arr, p) => arr[Math.min(arr.length - 1, Math.floor(arr.length * p))]
+  const stats = (arr) => ({
+    p50: Math.round(pct(arr, 0.5) * 1000) / 1000,
+    p99: Math.round(pct(arr, 0.99) * 1000) / 1000,
+    max: Math.round(arr[arr.length - 1] * 1000) / 1000,
+  })
+  const bs = stats(blockDiffs)
+  const gs = stats(globals)
+  const blockThresh = Math.min(32, Math.max(2, Math.ceil(bs.max + 2)))
+  const changeGlobal = Math.min(0.3, Math.max(0.02, Math.round((gs.max + 0.01) * 1000) / 1000))
+  const moved = bs.max > bs.p99 * 2 + 1
+  return {
+    ok: true, frames,
+    block: bs, global: gs,
+    recommended: { blockThresh, changeGlobal },
+    apply: 'stream start --block-thresh ' + blockThresh + ' --change-global ' + changeGlobal,
+    ...(moved ? { warn: 'max 远超 p99（' + bs.max + ' vs ' + bs.p99 + '）：校准期间疑似有真实变化，建议静止画面重跑' } : {}),
+  }
+}
+
+/* ────────────────────────── 消息分发 ────────────────────────── */
+const handlers = {
+  init: (a) => {
+    if (a.runDir) {
+      S.runDir = String(a.runDir)
+      S.previewPath = path.join(S.runDir, 'preview.png')
+      try { fs.mkdirSync(S.runDir, { recursive: true }) } catch (e) { /* ignore */ }
+    }
+    if (Number(a.kfQuotaBytes) > 0) S.kfQuota = Math.floor(Number(a.kfQuotaBytes))
+    return { ok: true, previewPath: S.previewPath, daemonId: S.daemonId, framesDir: kfRoot(), kfQuota: S.kfQuota }
+  },
+  probe: cmdProbe,
+  device_list: (a) => cmdDeviceList(a.kind),
+  connect: cmdConnect,
+  disconnect: cmdDisconnect,
+  screencap: (a) => cmdScreencap(a.out),
+  stream_start: cmdStreamStart,
+  stream_stop: cmdStreamStop,
+  stream_status: cmdStreamStatus,
+  frame_get: cmdFrameGet,
+  frame_diff: cmdFrameDiff,
+  wait: cmdWait,
+  tpl_crop: cmdTplCrop,
+  annotate: cmdAnnotate,
+  calibrate: cmdCalibrate,
+  color_probe: cmdColorProbe,
+  l0_status: cmdL0Status,
+  kf_promote: cmdKfPromote,
+  run: cmdRun,
+  run_stop: cmdRunStop,
+  input: cmdInput,
+  reco_test: cmdRecoTest,
+  shutdown: async () => { await cmdStreamStop(); await cleanupAgents(); await cmdDisconnect(); return { ok: true } },
+}
+
+/* 子进程模式：stdin JSON 行协议（每行一条消息）。非 --child（headless 单测 import）不挂监听。 */
+if (CHILD) {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity })
+  rl.on('line', (line) => {
+    let m = null
+    try { m = JSON.parse(line) } catch (e) {
+      send({ kind: 'reply', id: -1, ok: false, error: 'bad json line' })
+      return
+    }
+    if (!m || typeof m.cmd !== 'string') return
+    const h = handlers[m.cmd]
+    if (!h) { reply(m.id, false, 'unknown cmd: ' + m.cmd); return }
+    Promise.resolve()
+      .then(() => h(m))
+      /* shutdown 的回执要落地再退：process.exit 不等 stdout 冲刷，而调用方在等这条应答 */
+      .then((data) => reply(m.id, true, data, m.cmd === 'shutdown' ? () => process.exit(0) : null))
+      .catch((e) => reply(m.id, false, String(e && e.message || e)))
+  })
+}
+
+/* 纯函数导出（供 headless 验证直接断言，子进程运行中不使用）。
+ * S 一并导出：l0EvictToBudget 等维护函数作用于模块态，单测需直改后还原。 */
+export const __test = {
+  pngDecode, pngEncodeRGB, downscale, blockAnalyze, blockHash, hashDist,
+  regionOfBlocks, tightenBounds, tightenBoundsByEdges, edgeMap, cropRgb, connComponents, edgeDensityBoxes,
+  readKfCropSource, buildL2Provenance, pickBalancedCandidates, pickNodeName, readRoi,
+  l0EvictToBudget, cmdKfPromote, cmdTplCrop, kfUsageBytes, defaultOutFile, S,
+}