@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/daemon/reco_child.mjs

@@ -0,0 +1,287 @@
+/**
+ * reco_child —— 识别单测的一次性子进程（崩溃隔离）。
+ * 用法：node reco_child.mjs --cfg <json> --out <result.json>
+ * cfg = { resourceDirs? | resourceDir, type, image, cases?, node?, nodeName?, templateImage? }
+ *   cases: 父进程（framed.mjs）已折叠好的参数用例列表，逐例执行
+ *   node : 整节点 JSON 原样透传（V1 扁平 / V2 嵌套均支持，不转换）
+ *   nodeName: 按资源里的原名跑（不 dump 注入——dump 是缺省填满的 V2，与手写稀疏 V1 不是同一份）
+ *   param/sweep: 直接调用（调试）时的单例路径，与 cases 二选一
+ *
+ * 为什么要造一个"图像假控制器"：裸 post_recognition 不产出 RecoId，于是 recognition_detail 拿不到
+ * 详情（也就是命中框）。上游 maa-support 的做法是：用给定图像造一个 CustomController，让框架以为自己
+ * 在截图，再在自定义 action 里调 context.run_recognition —— 详情直接由那次调用返回。这里沿用同一条路径。
+ */
+import { createRequire } from "node:module"
+import fs from "node:fs"
+
+const require = createRequire(import.meta.url)
+const cfgArg = process.argv.indexOf("--cfg")
+const outArg = process.argv.indexOf("--out")
+if (cfgArg < 0 || outArg < 0) { console.error("usage: reco_child --cfg <json> --out <json>"); process.exit(2) }
+const cfg = JSON.parse(fs.readFileSync(process.argv[cfgArg + 1], "utf8"))
+const out = process.argv[outArg + 1]
+
+function toArrayBuffer(buf) {
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
+}
+
+/** 参数扫描折叠成用例列表（与 CLI 的 --sweep 语义一致；step 带方向）。 */
+function casesOf(c) {
+  /* 父进程路径：cases 已折好，逐例透传——子进程不再自行折叠，避免两边语义分叉 */
+  if (Array.isArray(c.cases) && c.cases.length) {
+    return c.cases.filter((p) => p && typeof p === "object")
+  }
+  const base = c.param && typeof c.param === "object" ? c.param : {}
+  const sweep = c.sweep && typeof c.sweep === "object" ? c.sweep : null
+  const cases = []
+  if (sweep && typeof sweep.min === "number" && typeof sweep.max === "number") {
+    const step = sweep.step !== undefined && Number(sweep.step) !== 0 ? Number(sweep.step) : 1
+    const up = step > 0
+    for (let v = sweep.min; up ? v <= sweep.max + 1e-9 : v >= sweep.max - 1e-9; v += step) {
+      cases.push({ ...base, [String(sweep.key || "threshold")]: Math.round(v * 1000) / 1000 })
+    }
+  } else {
+    cases.push(base)
+  }
+  return cases
+}
+
+/**
+ * --node 整节点透传的入口构造：不做 V1/V2 互转，框架的 pipeline 解析两种形态都认识。
+ * 只在"模板由调用方图像提供"（override_image）且节点自己没写模板时补一个模板引用，
+ * 补的位置按节点形态放（V1 顶层 / V2 recognition.param 内），其余字段一律原样。
+ */
+function nodeEntry(node, templateImage) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    throw new Error("--node 必须是 JSON 对象（pipeline 节点）")
+  }
+  const rec = node.recognition
+  const v2 = rec && typeof rec === "object" && !Array.isArray(rec)
+  if (rec === undefined || (typeof rec !== "string" && !v2)) {
+    throw new Error("--node 缺少可用的 recognition 字段（V1 字符串或 V2 {type,param}）")
+  }
+  if (!templateImage) return node
+  if (v2) {
+    const param = rec.param && typeof rec.param === "object" ? rec.param : {}
+    if (param.template !== undefined) return node
+    return { ...node, recognition: { ...rec, param: { ...param, template: "@reco_template" } } }
+  }
+  if (node.template !== undefined) return node
+  return { ...node, template: "@reco_template" }
+}
+
+/** 页面/工具只需要判定信息：像素类字段（draws / raw）一律不带出去。 */
+function strip(detail) {
+  if (!detail || typeof detail !== "object") return null
+  const copy = { ...detail }
+  delete copy.draws
+  delete copy.raw
+  return copy
+}
+
+function writeOut(payload) {
+  fs.writeFileSync(out, JSON.stringify(payload), "utf8")
+}
+
+/** dump 里的识别类型：V2 是 `recognition.type`，个别版本/形态可能还是 V1 的字符串。 */
+function recoTypeOf(dump) {
+  const rec = dump && dump.recognition
+  if (typeof rec === "string") return rec
+  if (rec && typeof rec === "object") return String(rec.type ?? "")
+  return ""
+}
+
+function editDistance(a, b) {
+  if (a === b) return 0
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i]
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = cur
+  }
+  return prev[b.length]
+}
+
+/**
+ * 近邻节点名：命令拼错会给建议，节点名拼错同样要给——否则 `--node-name` 写错一个字只会得到
+ * "资源里没有这个节点"，而正确名字就在资源里。距离阈值随名字长度放宽（长名的单个字符笔误
+ * 距离仍是 1；短名放宽到 2 就够，再宽会把无关节点列出来）。
+ */
+function nearestNames(names, target, limit) {
+  const want = String(target)
+  const cap = Math.max(2, Math.min(4, Math.floor(want.length / 3)))
+  const scored = []
+  for (const n of Array.isArray(names) ? names : []) {
+    if (typeof n !== "string" || !n || n === want) continue
+    const d = editDistance(n.toLowerCase(), want.toLowerCase())
+    if (d <= cap) scored.push({ n, d })
+  }
+  return scored.sort((x, y) => x.d - y.d || x.n.localeCompare(y.n)).slice(0, limit).map((x) => x.n)
+}
+
+/**
+ * dump 里的 Custom 识别：顶层 `type: "Custom"` / V1 的 `custom_recognition`，**以及 And / Or 里嵌的
+ * 子识别**。只看顶层会让"And 里挂了一个 custom 子识别"落回 miss 或"识别调用报错"，看起来像没命中，
+ * 而它其实和顶层 custom 是同一条能力边界（reco_test 不桥接 agent 子进程）。
+ * 返回命中位置（便于在报错里说清是哪一层），深度与条数都封顶，避免异常 dump 撑爆回执。
+ */
+function customHits(dump) {
+  const hits = []
+  /* key 要一起带下来：字符串 `"Custom"` 只有落在**识别类型位**上才算（V1 的 `recognition` / V2 的
+   * `type`）。整棵子树里任何字符串都认会把 `expected: "Custom"`（OCR 要认的文字）和名字恰好叫
+   * Custom 的引用节点误判成 Custom 子识别。 */
+  const walk = (v, path, key, depth) => {
+    if (hits.length >= 8 || depth > 6 || v === null || v === undefined) return
+    if (typeof v === "string") {
+      if (v === "Custom" && (key === "recognition" || key === "type")) hits.push(path)
+      return
+    }
+    if (typeof v !== "object") return
+    if (Array.isArray(v)) {
+      v.forEach((x, i) => walk(x, path + "[" + i + "]", null, depth + 1))
+      return
+    }
+    if (typeof v.type === "string" && v.type === "Custom") { hits.push(path + ".type"); return }
+    if (v.custom_recognition !== undefined) { hits.push(path + ".custom_recognition"); return }
+    for (const [k, x] of Object.entries(v)) walk(x, path === "" ? k : path + "." + k, k, depth + 1)
+  }
+  walk(dump && dump.recognition, "recognition", "recognition", 0)
+  return hits
+}
+
+async function main() {
+  const maa = require("@maaxyz/maa-node")
+  const image = toArrayBuffer(fs.readFileSync(cfg.image))
+
+  const ctrl = new maa.CustomController({
+    connect() { return true },
+    request_uuid() { return "0" },
+    screencap() { return image },
+  })
+  ctrl.screenshot_use_raw_size = true
+  await ctrl.post_connection().wait()
+  if (!ctrl.connected) throw new Error("假控制器连接失败")
+
+  /* 资源链：interface.json 的 resource.path[]（+ 控制器 attach_resource_path）按声明顺序叠加，
+   * 后一段覆盖前一段——与 cmdRun 的 buildResource 同一语义。只加载单包时，overlay 包里的节点改写、
+   * 只存在于 overlay 的模板、被 And/Or 按名引用的子节点全部缺失，测出来的就不是项目里那个节点。 */
+  const dirs = Array.isArray(cfg.resourceDirs) && cfg.resourceDirs.length
+    ? cfg.resourceDirs.map(String)
+    : [String(cfg.resourceDir)]
+  const res = new maa.Resource()
+  /* 逐段点名失败：整链一起报只说"加载失败"，看不出是哪一层读不进（原先是父进程
+   * probeResourceChain 先加载一遍做先验——探针挪进这里后只加载一次，失败定位不变）。 */
+  for (let i = 0; i < dirs.length; i++) {
+    const where = '第 ' + (i + 1) + '/' + dirs.length + ' 段（' + dirs[i] + '）'
+    let job = null
+    try {
+      job = res.post_bundle(dirs[i])
+      await job.wait()
+    } catch (e) {
+      writeOut({ ok: false, code: 'RESOURCE_LOAD', error: '资源链加载失败：' + where + '：' + String(e && e.message || e) })
+      return
+    }
+    const st = Number(job && job.status)
+    if (Number.isFinite(st) && st !== 3000) {
+      writeOut({ ok: false, code: 'RESOURCE_LOAD', error: '资源链加载失败：' + where + '返回 status=' + st + '（成功应为 3000）' })
+      return
+    }
+  }
+  /* 面板裁出来的模板走 override_image：不必把它塞进任何资源目录，也不写用户项目。 */
+  if (cfg.templateImage) res.override_image("@reco_template", toArrayBuffer(fs.readFileSync(cfg.templateImage)))
+
+  const tasker = new maa.Tasker()
+  tasker.controller = ctrl
+  tasker.resource = res
+
+  const nodeMode = cfg.node !== undefined
+  const nodeNameMode = typeof cfg.nodeName === "string" && cfg.nodeName !== ""
+  const node = nodeMode ? nodeEntry(cfg.node, cfg.templateImage) : null
+  /* --node-name：dump 只进回执给人看，**不注入识别**。dump 是 DumpTask（V2 嵌套 + 缺省值全部
+   * 填满），与手写稀疏 V1 JSON 不是同一份；dump 再注入会让"测的到底是不是真节点"多一层不确定性。 */
+  let nodeDump = null
+  if (nodeNameMode) {
+    nodeDump = res.get_node_data_parsed(cfg.nodeName)
+    if (!nodeDump) {
+      const candidates = nearestNames(res.node_list, cfg.nodeName, 3)
+      writeOut({
+        ok: false, code: "NODE_MISSING", nodeName: cfg.nodeName, resourceDirs: dirs,
+        ...(candidates.length ? { candidates } : {}),
+        error: "资源里没有名为 " + cfg.nodeName + " 的节点（只查资源合并结果，不含 interface 的 pipeline_override）",
+      })
+      return
+    }
+    /* custom / agent 节点：reco_test 不桥接 agent 子进程（run 才桥接），明确报能力边界而不是让它看起来像 miss。
+     * And / Or 里嵌的子识别同样算——它们会在 run_recognition 里被真的走到。 */
+    const customs = customHits(nodeDump)
+    if (customs.length > 0) {
+      const onlyTop = customs.length === 1
+        && (customs[0] === "recognition.type" || customs[0] === "recognition")
+      writeOut({
+        ok: false, code: "CUSTOM_NODE", nodeName: cfg.nodeName, nodeDump, resourceDirs: dirs, customPaths: customs,
+        error: onlyTop
+          ? "节点 " + cfg.nodeName + " 的识别是 Custom：reco_test 不桥接 custom/agent 识别（run --project 才桥接 agent 子进程）"
+          : "节点 " + cfg.nodeName + " 的识别含 Custom 子识别（" + customs.length + " 处："
+            + customs.slice(0, 3).join(" / ") + (customs.length > 3 ? " …" : "")
+            + "）：reco_test 不桥接 custom/agent 识别（run --project 才桥接 agent 子进程）",
+      })
+      return
+    }
+  }
+  const cases = nodeMode || nodeNameMode ? [node] : casesOf(cfg)
+  const results = []
+  let slot = null
+  let started = Date.now()
+
+  res.register_custom_action("@reco/run", async self => {
+    /* 入口三形态：--node-name 用资源原名（无 override）；--node 原样透传；--type 用折叠好的一例参数。
+     * param 只用于回执展示"测的是哪个/组参数"。 */
+    let param = null
+    let detail = null
+    try {
+      if (nodeNameMode) {
+        param = { nodeName: cfg.nodeName }
+        detail = await self.context.run_recognition(cfg.nodeName, image)
+      } else {
+        const entry = nodeMode ? node : { recognition: cfg.type, ...(slot || {}) }
+        if (!nodeMode && cfg.templateImage && entry.template === undefined) entry.template = "@reco_template"
+        param = entry
+        detail = await self.context.run_recognition("@reco/node", image, { "@reco/node": entry })
+      }
+    } catch (e) {
+      results.push({ param, ms: Date.now() - started, ok: false, error: String(e && e.message || e), detail: null })
+      return true
+    }
+    /* ok 只认 hit===true：miss 时 run_recognition 仍返回 detail 对象（hit:false、box 全零），
+     * 旧判 !!detail 恒真——识别未中会标成命中，制造假观测证据。 */
+    results.push({ param, ms: Date.now() - started, ok: !!detail && detail.hit === true, detail: strip(detail) })
+    return true
+  })
+
+  try {
+    for (const param of cases) {
+      slot = param
+      started = Date.now()
+      await tasker.post_task("@reco/entry", { "@reco/entry": { action: "Custom", custom_action: "@reco/run" } }).wait()
+    }
+  } finally {
+    try { tasker.destroy() } catch (e) { /* ignore */ }
+    try { res.destroy() } catch (e) { /* ignore */ }
+    try { ctrl.destroy() } catch (e) { /* ignore */ }
+  }
+
+  writeOut({
+    ok: true,
+    ...(nodeNameMode ? { type: recoTypeOf(nodeDump), nodeName: cfg.nodeName, nodeDump } : { type: cfg.type }),
+    results,
+  })
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((e) => {
+    try { fs.writeFileSync(out, JSON.stringify({ ok: false, error: String(e && e.message || e) }), "utf8") } catch (e2) { /* ignore */ }
+    process.exit(1)
+  })

package/lib/exec.js

@@ -0,0 +1,96 @@
+/**
+ * 外部命令执行封装。
+ *
+ * 约定：**永不抛异常**，一律返回结果对象。原因是环境探针的本质就是「探测可能不存在的东西」——
+ * 缺 adb、缺 python、缺 git 都是正常结果，不是异常路径。
+ */
+import { execFile } from 'node:child_process';
+const DEFAULT_TIMEOUT = 8000;
+function once(bin, args, opts) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = execFile(bin, args, {
+                timeout: opts.timeout ?? DEFAULT_TIMEOUT,
+                cwd: opts.cwd,
+                windowsHide: true,
+                maxBuffer: 8 * 1024 * 1024,
+                encoding: 'utf8',
+                windowsVerbatimArguments: opts.verbatim === true,
+            }, (err, stdout, stderr) => {
+                const e = err;
+                if (!e) {
+                    resolve({ ok: true, code: 0, stdout: String(stdout), stderr: String(stderr) });
+                    return;
+                }
+                // 启动失败（ENOENT/EACCES）与「跑起来但退出码非 0」要分开报
+                const isSpawnFailure = typeof e.code === 'string';
+                resolve({
+                    ok: false,
+                    code: isSpawnFailure ? null : typeof e.code === 'number' ? e.code : null,
+                    stdout: String(stdout ?? ''),
+                    stderr: String(stderr ?? ''),
+                    spawnError: isSpawnFailure ? e.code : undefined,
+                });
+            });
+        }
+        catch (e) {
+            /* execFile 在部分情况下是**同步**抛的（Windows 上直接跑 .cmd/.bat → EINVAL）。
+             * 本模块的契约是「永不抛异常」：环境探针的本质就是探测可能不存在的东西，
+             * 同步抛也必须收敛成结果对象，否则整个命令（如 env）会因为一个缺失的探测目标而失败。 */
+            const err = e;
+            resolve({
+                ok: false, code: null, stdout: '', stderr: String(err?.message ?? e),
+                spawnError: String(err?.code ?? 'EINVAL'),
+            });
+            return;
+        }
+        if (opts.input !== undefined) {
+            child.stdin?.end(opts.input);
+        }
+    });
+}
+/** Windows：`where` 解析目标（含 PATHEXT），拿到可执行的绝对路径用于经 shell 执行。找不到返回 null。 */
+async function wherePath(bin) {
+    const r = await once('where', [bin], { timeout: 3000 });
+    if (!r.ok)
+        return null;
+    const all = String(r.stdout).split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== '');
+    /* where 会同时列出无扩展名的 POSIX 壳（如 nodejs\npm，是给 sh 用的）与 npm.cmd；
+     * cmd 只能跑后者，所以优先取可执行扩展名，避免拿到壳脚本后"跑不起来"。 */
+    return all.find((p) => /\.(cmd|exe|bat)$/i.test(p)) ?? all[0] ?? null;
+}
+/** 极简 cmd 引号：只在含空白/引号/元字符时加引号并转义内部引号。 */
+function quoteForCmd(arg) {
+    return /[\s"&|<>^]/.test(arg) ? '"' + arg.replace(/"/g, '""') + '"' : arg;
+}
+/**
+ * 执行外部命令。
+ *
+ * Windows 上 `.cmd` / `.bat`（npm、npx、pnpm）不是可执行文件：execFile 直接跑会**同步抛 EINVAL**
+ * （Node 对 CVE-2024-27980 的修复，本模块曾因此让 `env` 在只缺 adb 的机器上整条失败），
+ * 所以先 `where` 解析出可执行路径，再经 `ComSpec` 执行。而 cmd 的引号规则有讲究：`/s` 会剥掉最外层
+ * 引号，所以命令串要**整体再包一层引号**并配 `windowsVerbatimArguments`——实测
+ * `cmd /d /s /c ""C:\Program Files\nodejs\npm.cmd" --version"` 是唯一能跑通的拼法。
+ * 不直接用 `shell: true`：给 shell 传参会触发 `DEP0190` 弃用警告，且"命令不存在"会退化成
+ * "cmd 跑起来了但退出 1"（本地化报错，判不准）。
+ */
+export async function run(bin, args = [], opts = {}) {
+    const first = await once(bin, args, opts);
+    if (first.spawnError === 'ENOENT' && process.platform === 'win32' && !/\.(exe|cmd|bat|ps1)$/i.test(bin)) {
+        const resolved = await wherePath(bin);
+        if (resolved) {
+            const comspec = process.env.ComSpec ?? 'cmd.exe';
+            const line = [resolved, ...args].map(quoteForCmd).join(' ');
+            const retry = await once(comspec, ['/d', '/s', '/c', '"' + line + '"'], { ...opts, verbatim: true });
+            if (retry.ok || retry.code !== null)
+                return retry;
+        }
+    }
+    return first;
+}
+/** 取首行有效输出，供「版本号探测」这类场景用 */
+export function firstLine(s) {
+    return s.split(/\r?\n/).map((l) => l.trim()).find((l) => l !== '') ?? '';
+}
+//# sourceMappingURL=exec.js.map

package/lib/flags.js

@@ -0,0 +1,44 @@
+export const GLOBAL_OPTIONS = {
+    json: { type: 'boolean' },
+    'dry-run': { type: 'boolean' },
+    yes: { type: 'boolean' },
+    'no-interactive': { type: 'boolean' },
+    'no-color': { type: 'boolean' },
+    cwd: { type: 'string' },
+    limit: { type: 'string' },
+    verbose: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'V' },
+    /** 把命令转发到命名会话的常驻 daemon（`repl --session <name>` 起的那个） */
+    session: { type: 'string' },
+};
+const DEFAULT_LIMIT = 200;
+/**
+ * 从 parseArgs 的 values 推导全局标志。
+ *
+ * `--no-color` 只关闭颜色；未指定时按 TTY 自动判断（管道里自动无色）。
+ * 注意不能用 NO_COLOR 环境变量以外的方式覆盖显式传入的值。
+ */
+export function readGlobalFlags(values, cwd) {
+    const rawLimit = values.limit;
+    let limit = DEFAULT_LIMIT;
+    if (typeof rawLimit === 'string' && rawLimit !== '') {
+        const n = Number(rawLimit);
+        limit = Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_LIMIT;
+    }
+    const noColor = values['no-color'] === true;
+    const color = !noColor && process.env.NO_COLOR === undefined && process.stdout.isTTY === true;
+    return {
+        json: values.json === true,
+        dryRun: values['dry-run'] === true,
+        yes: values.yes === true,
+        interactive: values['no-interactive'] !== true && process.env.MAAFW_RUN_NON_INTERACTIVE === undefined,
+        color,
+        cwd,
+        limit,
+        verbose: values.verbose === true,
+        help: values.help === true,
+        version: values.version === true,
+    };
+}
+//# sourceMappingURL=flags.js.map

package/lib/image.js

@@ -0,0 +1,90 @@
+/**
+ * 纯 JS 图像工具：复用 daemon 里那套无依赖 PNG 编解码（不做第二份实现）。
+ *
+ * daemon（daemon/framed.mjs）本来就带 PNG 解码 / 缩放 / 编码 —— 它要在没有 native 依赖的
+ * 前提下处理帧 —— 但只在子进程里用。这里用非字面量说明符动态 import 取它的 __test 导出：
+ * 避免为一个 .mjs 引入声明文件、把构建链复杂化，同时用下面的接口把契约钉死。
+ *
+ * 与 daemon 帧流共用同一条降采样路径，因此"面板预览看到的缩放"和"识别用的缩放"不会分叉。
+ */
+let cached = null;
+async function helpers() {
+    if (cached)
+        return cached;
+    const spec = "./daemon/framed.mjs";
+    const mod = (await import(spec));
+    cached = mod.__test;
+    return cached;
+}
+/** 解码结果 → 3 字节/像素的 RGB（daemon 的 toRgb 没导出，这里只补这一步）。 */
+function toRgb(dec) {
+    if (dec.ch === 3)
+        return dec.data;
+    if (dec.ch === 4) {
+        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;
+    }
+    throw new Error("只支持 RGB/RGBA 的 PNG（该图为 " + dec.ch + " 通道）");
+}
+/** PNG Buffer 的尺寸。 */
+export async function pngSize(buf) {
+    const t = await helpers();
+    const dec = t.pngDecode(buf);
+    return { w: dec.w, h: dec.h };
+}
+/** 按"长边不超过 maxSide"缩放 PNG（只缩不放，原图更小时原样返回）。 */
+export async function scalePngLongSide(buf, maxSide) {
+    const t = await helpers();
+    const dec = t.pngDecode(buf);
+    const target = Math.max(16, Math.floor(maxSide));
+    if (dec.w <= target && dec.h <= target)
+        return buf;
+    const scaled = t.downscale(toRgb(dec), dec.w, dec.h, target);
+    return t.pngEncodeRGB(scaled.data, scaled.w, scaled.h);
+}
+/**
+ * 按矩形裁一块出来（控制器分辨率坐标系，越界自动夹紧）。
+ *
+ * 面板的"模板匹配即时校验"用它：把人框的这块裁成模板图，再交给识别去比对 —— 因此这一步
+ * 必须与帧流/识别走同一条解码路径，不能各自实现（否则裁出来的像素与识别看到的不是同一份）。
+ */
+export async function cropPng(buf, rect) {
+    const t = await helpers();
+    const dec = t.pngDecode(buf);
+    const [rx, ry, rw, rh] = rect.map((n) => Math.round(Number(n) || 0));
+    const x = Math.max(0, Math.min(dec.w - 1, rx));
+    const y = Math.max(0, Math.min(dec.h - 1, ry));
+    const w = Math.max(1, Math.min(dec.w - x, rw));
+    const h = Math.max(1, Math.min(dec.h - y, rh));
+    const rgb = toRgb(dec);
+    const out = Buffer.alloc(w * h * 3);
+    for (let row = 0; row < h; row++) {
+        const from = ((y + row) * dec.w + x) * 3;
+        rgb.copy(out, row * w * 3, from, from + w * 3);
+    }
+    return t.pngEncodeRGB(out, w, h);
+}
+/** data URL → PNG Buffer；非图片 data URL 返回 null。 */
+export function dataUrlToPng(dataUrl) {
+    if (!dataUrl.startsWith("data:image/"))
+        return null;
+    const comma = dataUrl.indexOf(",");
+    if (comma < 0)
+        return null;
+    try {
+        return Buffer.from(dataUrl.slice(comma + 1), "base64");
+    }
+    catch {
+        return null;
+    }
+}
+/** PNG Buffer → data URL（面板侧统一 data:image/png）。 */
+export function pngToDataUrl(buf) {
+    return "data:image/png;base64," + buf.toString("base64");
+}
+//# sourceMappingURL=image.js.map

package/lib/index.js

@@ -0,0 +1,143 @@
+/**
+ * maafw-live CLI 入口：解析 → 分发 → 输出。
+ *
+ * 入口只做四件事，任何领域逻辑都不许放进来：
+ *  1. 处理无命令 / --help / --version 这类不进入命令的路径
+ *  2. 合并全局选项与命令选项并解析
+ *  3. 解析并校验 cwd
+ *  4. 执行命令、输出结果、返回退出码
+ *
+ * 未预期异常一律兜成 FAIL 信封——技能拿到的必须是结构化的错误，
+ * 而不是一段堆栈（堆栈会直接灌进模型上下文）。
+ */
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { findCommand, suggestCommand } from './commands/index.js';
+import { dispatchArgv } from './commands/dispatch.js';
+import { GLOBAL_OPTIONS, readGlobalFlags } from './flags.js';
+import { cliPackage } from './pkg.js';
+import { EXIT, emit, fail } from './protocol.js';
+import { forwardToSession, stripSessionFlag } from './runtime/session-forward.js';
+import { commandUsage, topLevelUsage } from './usage.js';
+function print(lines, toStderr = false) {
+    const text = lines.join('\n') + '\n';
+    if (toStderr)
+        process.stderr.write(text);
+    else
+        process.stdout.write(text);
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+export async function main(argv) {
+    const head = argv[0];
+    // 不进入命令的路径
+    if (head === undefined || head === 'help') {
+        const topic = argv[1];
+        if (topic) {
+            const cmd = findCommand(topic);
+            if (cmd) {
+                print(commandUsage(cmd));
+                return EXIT.OK;
+            }
+            print([`未知命令：${topic}`], true);
+            print(topLevelUsage(), true);
+            return EXIT.USAGE;
+        }
+        print(topLevelUsage());
+        return head === undefined ? EXIT.USAGE : EXIT.OK;
+    }
+    if (head === '--version' || head === '-V') {
+        const pkg = cliPackage();
+        print([`${pkg.name} ${pkg.version}`]);
+        return EXIT.OK;
+    }
+    if (head === '--help' || head === '-h') {
+        print(topLevelUsage());
+        return EXIT.OK;
+    }
+    const cmd = findCommand(head);
+    if (!cmd) {
+        const suggestion = suggestCommand(head);
+        const result = {
+            exitCode: EXIT.USAGE,
+            error: {
+                code: 'UNKNOWN_COMMAND',
+                message: `未知命令：${head}`,
+                ...(suggestion ? { hint: `是否想执行 ${cliPackage().name} ${suggestion}？` } : {}),
+            },
+        };
+        emit(head, result, { json: argv.includes('--json'), color: false });
+        if (!argv.includes('--json'))
+            print(topLevelUsage(), true);
+        return EXIT.USAGE;
+    }
+    /* cwd 与 --json/--color 先粗解析（全局选项集即可，命令私有选项不在这层消费）。
+     * --session 转发发生在 dispatchArgv **之前**：会话侧跑的是同一份命令实现，
+     * 本地不该为"转发给会话的命令"先新起一个 daemon 再丢（requiresSession 闸门
+     * 在会话侧才有意义——ctx.client 已注入时不拦）。 */
+    let rough;
+    try {
+        rough = parseArgs({
+            args: argv.slice(1),
+            options: GLOBAL_OPTIONS,
+            allowPositionals: true,
+            strict: false,
+        });
+    }
+    catch {
+        /* 全局层解析不过就让 dispatchArgv 走完整错误路径（BAD_ARGUMENTS 信封） */
+        rough = { values: {}, positionals: argv.slice(1) };
+    }
+    let cwd = process.cwd();
+    if (typeof rough.values.cwd === 'string' && rough.values.cwd !== '') {
+        cwd = resolve(rough.values.cwd);
+    }
+    const flags = readGlobalFlags(rough.values, cwd);
+    if (flags.help) {
+        print(commandUsage(cmd));
+        return EXIT.OK;
+    }
+    if (!isDirectory(cwd)) {
+        const result = fail('CWD_NOT_FOUND', `工作目录不存在：${cwd}`, '用 --cwd 指定一个存在的目录', EXIT.ENV);
+        emit(cmd.name, result, { json: flags.json, color: flags.color });
+        return EXIT.ENV;
+    }
+    /* `--session <name>`：把整条 argv（剥掉 --session 本体）送进常驻会话执行。
+     * `repl` 自己的 --session 是"起/查/收会话"的参数，不是转发旗标，不能拦。 */
+    const sessionName = typeof rough.values.session === 'string' ? rough.values.session : undefined;
+    if (sessionName && cmd.name !== 'repl') {
+        const result = await forwardToSession(sessionName, stripSessionFlag(argv));
+        emit(cmd.name, result, { json: flags.json, color: flags.color });
+        return result.exitCode;
+    }
+    const { result } = await dispatchArgv(argv, { cwd });
+    emit(cmd.name, result, { json: flags.json, color: flags.color });
+    return result.exitCode;
+}
+function isDirectory(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/* 允许 `node lib/index.js` 直接运行（bin/maafw-live.mjs 是常规入口） */
+const directRun = (() => {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(entry).href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (directRun) {
+    process.exitCode = await main(process.argv.slice(2));
+}
+//# sourceMappingURL=index.js.map