@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/daemon/reco_child.mjs

@@ -1,9 +1,10 @@
 /**
  * reco_child —— 识别单测的一次性子进程（崩溃隔离）。
  * 用法：node reco_child.mjs --cfg <json> --out <result.json>
- * cfg = { resourceDir, type, image, cases?, node?, templateImage? }
+ * 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 拿不到
@@ -78,6 +79,78 @@ function strip(detail) {
   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))
@@ -91,8 +164,31 @@ async function main() {
   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()
-  await res.post_bundle(cfg.resourceDir).wait()
+  /* 逐段点名失败：整链一起报只说"加载失败"，看不出是哪一层读不进（原先是父进程
+   * 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)))
 
@@ -101,25 +197,66 @@ async function main() {
   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
-  const cases = nodeMode ? [node] : casesOf(cfg)
+  /* --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 => {
-    const entry = nodeMode ? node : { recognition: cfg.type, ...(slot || {}) }
-    if (!nodeMode && cfg.templateImage && entry.template === undefined) entry.template = "@reco_template"
+    /* 入口三形态：--node-name 用资源原名（无 override）；--node 原样透传；--type 用折叠好的一例参数。
+     * param 只用于回执展示"测的是哪个/组参数"。 */
+    let param = null
     let detail = null
     try {
-      detail = await self.context.run_recognition("@reco/node", image, { "@reco/node": entry })
+      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: entry, ms: Date.now() - started, ok: false, error: String(e && e.message || e), detail: null })
+      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: entry, ms: Date.now() - started, ok: !!detail && detail.hit === true, detail: strip(detail) })
+    results.push({ param, ms: Date.now() - started, ok: !!detail && detail.hit === true, detail: strip(detail) })
     return true
   })
 
@@ -135,7 +272,11 @@ async function main() {
     try { ctrl.destroy() } catch (e) { /* ignore */ }
   }
 
-  fs.writeFileSync(out, JSON.stringify({ ok: true, type: cfg.type, results }), "utf8")
+  writeOut({
+    ok: true,
+    ...(nodeNameMode ? { type: recoTypeOf(nodeDump), nodeName: cfg.nodeName, nodeDump } : { type: cfg.type }),
+    results,
+  })
 }
 
 main()

package/lib/flags.js

@@ -9,6 +9,8 @@ export const GLOBAL_OPTIONS = {
     verbose: { type: 'boolean' },
     help: { type: 'boolean', short: 'h' },
     version: { type: 'boolean', short: 'V' },
+    /** 把命令转发到命名会话的常驻 daemon（`repl --session <name>` 起的那个） */
+    session: { type: 'string' },
 };
 const DEFAULT_LIMIT = 200;
 /**

package/lib/index.js

@@ -15,9 +15,11 @@ 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';
@@ -72,28 +74,28 @@ export async function main(argv) {
             print(topLevelUsage(), true);
         return EXIT.USAGE;
     }
-    // 解析选项：全局 + 命令私有
-    const options = { ...GLOBAL_OPTIONS, ...(cmd.options ?? {}) };
-    let parsed;
+    /* cwd 与 --json/--color 先粗解析（全局选项集即可，命令私有选项不在这层消费）。
+     * --session 转发发生在 dispatchArgv **之前**：会话侧跑的是同一份命令实现，
+     * 本地不该为"转发给会话的命令"先新起一个 daemon 再丢（requiresSession 闸门
+     * 在会话侧才有意义——ctx.client 已注入时不拦）。 */
+    let rough;
     try {
-        parsed = parseArgs({
+        rough = parseArgs({
             args: argv.slice(1),
-            options,
+            options: GLOBAL_OPTIONS,
             allowPositionals: true,
-            strict: true,
+            strict: false,
         });
     }
-    catch (e) {
-        const result = fail('BAD_ARGUMENTS', message(e), `用法：${cmd.usage}`, EXIT.USAGE);
-        emit(cmd.name, result, { json: argv.includes('--json'), color: false });
-        return EXIT.USAGE;
+    catch {
+        /* 全局层解析不过就让 dispatchArgv 走完整错误路径（BAD_ARGUMENTS 信封） */
+        rough = { values: {}, positionals: argv.slice(1) };
     }
-    // cwd 先解析，因为 --json 之外的所有输出都要用到它
     let cwd = process.cwd();
-    if (typeof parsed.values.cwd === 'string' && parsed.values.cwd !== '') {
-        cwd = resolve(parsed.values.cwd);
+    if (typeof rough.values.cwd === 'string' && rough.values.cwd !== '') {
+        cwd = resolve(rough.values.cwd);
     }
-    const flags = readGlobalFlags(parsed.values, cwd);
+    const flags = readGlobalFlags(rough.values, cwd);
     if (flags.help) {
         print(commandUsage(cmd));
         return EXIT.OK;
@@ -103,13 +105,15 @@ export async function main(argv) {
         emit(cmd.name, result, { json: flags.json, color: flags.color });
         return EXIT.ENV;
     }
-    let result;
-    try {
-        result = await cmd.run({ positionals: parsed.positionals, values: parsed.values, flags, cwd });
-    }
-    catch (e) {
-        result = fail('UNEXPECTED', message(e), '这是未预期异常，请把 --json 输出一并反馈', EXIT.FAIL);
+    /* `--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;
 }

package/lib/interface/hotkey.js

@@ -0,0 +1,142 @@
+/**
+ * hotkey 占位符 → 当前控制器的虚拟按键码（PI v2.8.0+）。
+ *
+ * 协议只给规则、不给表：`{名称}` / `{名称}.primary` / `{名称}.modifier1` / `{名称}.modifier2`
+ * 要替换成"**当前控制器 type** 支持的虚拟按键码"，且"映射规则应与 ClickKey、KeyDown 等动作所用
+ * 键码表一致"（MaaFW 5.14.2 `3.3-ProjectInterfaceV2协议`，pinned commit 8061d5bc）。
+ *
+ * 这里四张表的数值是各 OS **公开的键码常量**，不是谁发明的东西：
+ * - `Win32`  → Windows Virtual-Key Codes（`VK_*`，见 winuser.h）
+ * - `Adb`    → Android `KeyEvent`（`KEYCODE_*`）
+ * - `MacOS`  → Carbon `Events.h`（`kVK_*`，ANSI 键盘物理位置）
+ * - `WlRoots`/`Linux` → Linux `input-event-codes.h`（`KEY_*`/evdev）
+ *
+ * 取值与 MXU 的实现交叉核对过（MXU 是 AGPL-3.0，本仓 MIT：**只核数值，不搬代码**）。
+ * 键名按 MXU 的持久化约定规范化（大写、`+` 连接、末段为主键），因为它就是协议里"人类可读
+ * 快捷键字符串"的实际来源之一。
+ */
+const WIN32 = {
+    BACKSPACE: 0x08, TAB: 0x09, ENTER: 0x0d, SHIFT: 0x10, CTRL: 0x11, ALT: 0x12,
+    META: 0x5b, COMMAND: 0x5b, CMD: 0x5b, PAUSE: 0x13, CAPSLOCK: 0x14, ESC: 0x1b, SPACE: 0x20,
+    PAGEUP: 0x21, PAGEDOWN: 0x22, END: 0x23, HOME: 0x24,
+    LEFT: 0x25, UP: 0x26, RIGHT: 0x27, DOWN: 0x28, INSERT: 0x2d, DELETE: 0x2e,
+    '0': 0x30, '1': 0x31, '2': 0x32, '3': 0x33, '4': 0x34,
+    '5': 0x35, '6': 0x36, '7': 0x37, '8': 0x38, '9': 0x39,
+    A: 0x41, B: 0x42, C: 0x43, D: 0x44, E: 0x45, F: 0x46, G: 0x47, H: 0x48, I: 0x49,
+    J: 0x4a, K: 0x4b, L: 0x4c, M: 0x4d, N: 0x4e, O: 0x4f, P: 0x50, Q: 0x51, R: 0x52,
+    S: 0x53, T: 0x54, U: 0x55, V: 0x56, W: 0x57, X: 0x58, Y: 0x59, Z: 0x5a,
+    F1: 0x70, F2: 0x71, F3: 0x72, F4: 0x73, F5: 0x74, F6: 0x75,
+    F7: 0x76, F8: 0x77, F9: 0x78, F10: 0x79, F11: 0x7a, F12: 0x7b,
+};
+const MACOS = {
+    BACKSPACE: 0x33, TAB: 0x30, ENTER: 0x24, SHIFT: 0x38, CTRL: 0x3b, ALT: 0x3a,
+    META: 0x37, COMMAND: 0x37, CMD: 0x37, CAPSLOCK: 0x39, ESC: 0x35, SPACE: 0x31,
+    PAGEUP: 0x74, PAGEDOWN: 0x79, END: 0x77, HOME: 0x73,
+    LEFT: 0x7b, UP: 0x7e, RIGHT: 0x7c, DOWN: 0x7d, DELETE: 0x75,
+    '0': 0x1d, '1': 0x12, '2': 0x13, '3': 0x14, '4': 0x15,
+    '5': 0x17, '6': 0x16, '7': 0x1a, '8': 0x1c, '9': 0x19,
+    A: 0x00, B: 0x0b, C: 0x08, D: 0x02, E: 0x0e, F: 0x03, G: 0x05, H: 0x04, I: 0x22,
+    J: 0x26, K: 0x28, L: 0x25, M: 0x2e, N: 0x2d, O: 0x1f, P: 0x23, Q: 0x0c, R: 0x0f,
+    S: 0x01, T: 0x11, U: 0x20, V: 0x09, W: 0x0d, X: 0x07, Y: 0x10, Z: 0x06,
+    F1: 0x7a, F2: 0x78, F3: 0x63, F4: 0x76, F5: 0x60, F6: 0x61,
+    F7: 0x62, F8: 0x64, F9: 0x65, F10: 0x6d, F11: 0x67, F12: 0x6f,
+};
+const ADB = {
+    BACKSPACE: 67, TAB: 61, ENTER: 66, SHIFT: 59, CTRL: 113, ALT: 57,
+    META: 117, COMMAND: 117, CMD: 117, SPACE: 62, ESC: 111, DELETE: 112,
+    HOME: 3, END: 123, PAGEUP: 92, PAGEDOWN: 93,
+    LEFT: 21, RIGHT: 22, UP: 19, DOWN: 20,
+    '0': 7, '1': 8, '2': 9, '3': 10, '4': 11, '5': 12, '6': 13, '7': 14, '8': 15, '9': 16,
+    A: 29, B: 30, C: 31, D: 32, E: 33, F: 34, G: 35, H: 36, I: 37, J: 38, K: 39, L: 40,
+    M: 41, N: 42, O: 43, P: 44, Q: 45, R: 46, S: 47, T: 48, U: 49, V: 50, W: 51, X: 52,
+    Y: 53, Z: 54,
+    F1: 131, F2: 132, F3: 133, F4: 134, F5: 135, F6: 136, F7: 137, F8: 138, F9: 139,
+    F10: 140, F11: 141, F12: 142,
+};
+const WLROOTS = {
+    BACKSPACE: 14, TAB: 15, ENTER: 28, SHIFT: 42, CTRL: 29, ALT: 56,
+    META: 125, COMMAND: 125, CMD: 125, SPACE: 57, ESC: 1, DELETE: 111,
+    HOME: 102, END: 107, PAGEUP: 104, PAGEDOWN: 109,
+    LEFT: 105, RIGHT: 106, UP: 103, DOWN: 108,
+    '0': 11, '1': 2, '2': 3, '3': 4, '4': 5, '5': 6, '6': 7, '7': 8, '8': 9, '9': 10,
+    A: 30, B: 48, C: 46, D: 32, E: 18, F: 33, G: 34, H: 35, I: 23, J: 36, K: 37, L: 38,
+    M: 50, N: 49, O: 24, P: 25, Q: 16, R: 19, S: 31, T: 20, U: 22, V: 47, W: 17, X: 45,
+    Y: 21, Z: 44,
+    F1: 59, F2: 60, F3: 61, F4: 62, F5: 63, F6: 64, F7: 65, F8: 66, F9: 67, F10: 68,
+    F11: 87, F12: 88,
+};
+/** 同义键名归一：用户手写的组合键五花八门，认得出就认，认不出会在下面报"未知按键"。 */
+const ALIASES = {
+    CONTROL: 'CTRL', ESCAPE: 'ESC', RETURN: 'ENTER', DEL: 'DELETE', INS: 'INSERT',
+    PGUP: 'PAGEUP', PGDN: 'PAGEDOWN', WIN: 'META', WINDOWS: 'META', SUPER: 'META',
+    SPACEBAR: 'SPACE', CAPS: 'CAPSLOCK', OPTION: 'ALT',
+};
+/** 按控制器 **type** 取表（不是 name）。没有表的类型返回 null——调用方要告警，不能退回 Win32 猜。 */
+export function hotkeyTableFor(controllerType, useWin32VkCode = false) {
+    switch (controllerType) {
+        case 'Win32':
+            return WIN32;
+        case 'Adb':
+            return ADB;
+        case 'MacOS':
+            return MACOS;
+        case 'WlRoots':
+            return WLROOTS;
+        /* Linux 控制器可声明 `linux.use_win32_vk_code`：true 时服务端按 Win32 VK 解释，false 用 evdev */
+        case 'Linux':
+            return useWin32VkCode ? WIN32 : WLROOTS;
+        default:
+            return null;
+    }
+}
+function normalizeKey(name) {
+    const up = name.trim().toUpperCase();
+    return ALIASES[up] ?? up;
+}
+/** "Ctrl+Shift+A" → { primary: "A", modifiers: ["Ctrl","Shift"] }；末段为主键。 */
+export function splitHotkeyCombo(value) {
+    const parts = value.split('+').map((p) => p.trim()).filter(Boolean);
+    if (!parts.length)
+        return { primary: '', modifiers: [] };
+    return { primary: parts[parts.length - 1], modifiers: parts.slice(0, -1) };
+}
+/**
+ * 把一个 hotkey 字段解析成四种占位符的取值。
+ *
+ * 缺修饰键不是错（单键 "E" 本来就没有修饰键），补 0 = 无按键；**主键查不到是错**——
+ * 写个 0 进去等于"按了空键"，任务会静默点不动。
+ */
+export function resolveHotkeyTokens(fieldName, raw, table) {
+    const { primary, modifiers } = splitHotkeyCombo(raw);
+    if (!primary)
+        return { tokens: {}, error: '取值为空' };
+    const code = table[normalizeKey(primary)];
+    if (code === undefined) {
+        return { tokens: {}, error: '主键 ' + primary + ' 不在该控制器的键码表里（' + raw + '）' };
+    }
+    const mod = (name) => {
+        if (!name)
+            return 0;
+        const c = table[normalizeKey(name)];
+        /* 修饰键查不到也按"无"处理会让组合键变成单键——那是静默错，直接报错 */
+        if (c === undefined)
+            throw new Error('修饰键 ' + name + ' 不在该控制器的键码表里（' + raw + '）');
+        return c;
+    };
+    try {
+        const m1 = mod(modifiers[0]);
+        const m2 = mod(modifiers[1]);
+        return {
+            tokens: {
+                [fieldName]: code,
+                [fieldName + '.primary']: code,
+                [fieldName + '.modifier1']: m1,
+                [fieldName + '.modifier2']: m2,
+            },
+        };
+    }
+    catch (e) {
+        return { tokens: {}, error: String(e.message || e) };
+    }
+}
+//# sourceMappingURL=hotkey.js.map

package/lib/interface/index.js

@@ -8,5 +8,5 @@
 export { parseJsonc } from './jsonc.js';
 export { loadInterface, findInterfaceFile, } from './load.js';
 export { planController, resolveResourcePaths, } from './plan.js';
-export { computePipelineOverride, mergeOverride } from './override.js';
+export { computePipelineOverride, appendOverride } from './override.js';
 //# sourceMappingURL=index.js.map

package/lib/interface/load.js

@@ -1,8 +1,13 @@
 /**
  * 载入项目 interface.json（ProjectInterface v2）。
  *
- * 只做本工具需要的窄解析：控制器声明（连接规划用）、资源声明（路径解析用）、任务入口
- * （run --project 用）。其余字段（task 参数、option、i18n 等）不属于 CLI 的职责，原样忽略。
+ * 解析面就是本工具真正消费的那部分：控制器（连接规划）、资源（路径解析）、任务入口
+ * （run --project）、option / preset / global_option（pipeline_override 四级链）、
+ * agent 与 pretask（子进程相关）、import（v2.2.0 合并规则）。
+ *
+ * 明确**不**解析、不消费的：task 级 pipeline_override（本工具只合成 option 链，任务级写死的
+ * 覆盖要由 Client 应用）、i18n（languages 与 `$` 键——当前不输出人类标签）、group / setting /
+ * telemetry、resource.hash（v2.6.0 的一致性校验，未实现）。
  * 全过程不抛异常：问题进 problems[]，由调用方决定怎么呈现。
  */
 import { existsSync, readFileSync } from 'node:fs';
@@ -41,6 +46,7 @@ export function loadInterface(dir) {
         file,
         dir: file ? dirname(file) : null,
         version: null,
+        projectVersion: null,
         name: null,
         controllers: [],
         resources: [],
@@ -97,10 +103,20 @@ export function loadInterface(dir) {
         }
         const w = obj(c.win32);
         const g = obj(c.gamepad);
+        const mo = obj(c.macos);
+        const linuxDecl = obj(c.linux);
         controllers.push({
             name,
             type,
+            raw: c,
             display: Object.keys(display).length ? display : undefined,
+            macos: mo
+                ? {
+                    titleRegex: str(mo.title_regex),
+                    screencap: str(mo.screencap),
+                    input: str(mo.input),
+                }
+                : undefined,
             win32: w
                 ? {
                     classRegex: str(w.class_regex),
@@ -120,6 +136,17 @@ export function loadInterface(dir) {
                 : undefined,
             attachResourcePath: strList(c.attach_resource_path),
             option: strList(c.option),
+            ...(linuxDecl
+                ? {
+                    linux: {
+                        ...(linuxDecl.use_win32_vk_code === true ? { useWin32VkCode: true } : {}),
+                        ...(str(linuxDecl.screencap) ? { screencap: str(linuxDecl.screencap) } : {}),
+                        ...(str(linuxDecl.input) ? { input: str(linuxDecl.input) } : {}),
+                        ...(str(linuxDecl.pipewire_source) ? { pipewireSource: str(linuxDecl.pipewire_source) } : {}),
+                    },
+                }
+                : {}),
+            ...(c.permission_required === true ? { permissionRequired: true } : {}),
         });
     }
     if (!controllers.length)
@@ -133,7 +160,10 @@ export function loadInterface(dir) {
             problems.push({ message: 'resource 项缺少 name 或 path，已跳过' });
             continue;
         }
-        resources.push({ name, paths, controllers: strList(r.controller), option: strList(r.option) });
+        resources.push({
+            name, paths, controllers: strList(r.controller), option: strList(r.option),
+            ...(r.hash !== undefined ? { hash: str(r.hash) } : {}), raw: r,
+        });
     }
     const tasks = [];
     const options = {};
@@ -147,7 +177,7 @@ export function loadInterface(dir) {
             const exec = a ? str(a.child_exec) : undefined;
             if (!a || !exec)
                 continue;
-            agents.push({ exec, args: strList(a.child_args) });
+            agents.push({ exec, args: strList(a.child_args), ...(str(a.identifier) !== undefined ? { identifier: str(a.identifier) } : {}) });
         }
     };
     const readTasks = (list, src) => {
@@ -158,12 +188,14 @@ export function loadInterface(dir) {
                 problems.push({ message: 'task 项缺少 name，已跳过（' + src + '）' });
                 continue;
             }
+            const po = obj(t.pipeline_override);
             tasks.push({
                 name,
                 entry: str(t.entry),
                 controller: strList(t.controller),
                 resource: strList(t.resource),
                 option: strList(t.option),
+                ...(po ? { pipelineOverride: po } : {}),
             });
         }
     };
@@ -176,7 +208,10 @@ export function loadInterface(dir) {
         }
         for (const [key, val] of Object.entries(d)) {
             const v = obj(val);
-            if (!v || !str(v.type)) {
+            /* type 缺省按 select（上游 PI 文档与 Types.h:212 的默认）；仍记 problem，
+             * 因为它大概率是漏写而非有意缺省——警告可见，行为对齐上游。 */
+            const type = v ? (str(v.type) ?? 'select') : undefined;
+            if (!v || !type) {
                 problems.push({ message: 'option ' + key + ' 缺少 type，已跳过（' + src + '）' });
                 continue;
             }
@@ -193,13 +228,55 @@ export function loadInterface(dir) {
                     option: strList(c2.option),
                 });
             }
+            const tpl = obj(v.pipeline_override);
+            const inputs = [];
+            for (const it of Array.isArray(v.inputs) ? v.inputs : []) {
+                const f = obj(it);
+                const fname = f ? str(f.name) : undefined;
+                if (!f || !fname)
+                    continue;
+                const pwd = f.password === true;
+                inputs.push({
+                    name: fname,
+                    ...(str(f.default) !== undefined && !pwd ? { default: str(f.default) } : {}),
+                    ...(str(f.pipeline_type) !== undefined ? { pipelineType: str(f.pipeline_type) } : {}),
+                    ...(str(f.verify) !== undefined ? { verify: str(f.verify) } : {}),
+                    ...(pwd ? { password: true } : {}),
+                });
+                if (pwd && str(f.default) !== undefined) {
+                    problems.push({ message: 'option ' + key + ' 的输入字段 ' + fname + '：password=true 时规范禁止同时设 default，default 已忽略' });
+                }
+            }
+            const hotkeys = [];
+            for (const it of Array.isArray(v.hotkeys) ? v.hotkeys : []) {
+                const f = obj(it);
+                const fname = f ? str(f.name) : undefined;
+                if (!f || !fname)
+                    continue;
+                hotkeys.push({ name: fname, ...(str(f.default) !== undefined ? { default: str(f.default) } : {}) });
+            }
+            const minC = num(v.min_count);
+            const maxC = num(v.max_count);
+            if (type === 'checkbox') {
+                if (minC !== undefined && maxC !== undefined && minC > maxC) {
+                    problems.push({ message: 'option ' + key + '：min_count=' + minC + ' > max_count=' + maxC + '，约束自相矛盾' });
+                }
+                if (minC !== undefined && cases.length && minC > cases.length) {
+                    problems.push({ message: 'option ' + key + '：min_count=' + minC + ' 超过声明的 case 数 ' + cases.length + '，永远选不够' });
+                }
+            }
             options[key] = {
                 name: key,
-                type: String(v.type),
+                type,
                 cases,
+                ...(tpl ? { pipelineOverride: tpl } : {}),
+                ...(inputs.length ? { inputs } : {}),
+                ...(hotkeys.length ? { hotkeys } : {}),
                 ...(v.default_case !== undefined ? { defaultCase: v.default_case } : {}),
                 controller: strList(v.controller),
                 resource: strList(v.resource),
+                ...(type === 'checkbox' && minC !== undefined ? { minCount: minC } : {}),
+                ...(type === 'checkbox' && maxC !== undefined ? { maxCount: maxC } : {}),
             };
         }
     };
@@ -228,12 +305,28 @@ export function loadInterface(dir) {
     for (const g of strList(o.global_option))
         if (!globalOption.includes(g))
             globalOption.push(g);
-    const mainPretasks = Array.isArray(o.pretask) ? o.pretask : (o.pretask !== undefined ? [o.pretask] : []);
-    for (const pt of mainPretasks) {
-        const p2 = obj(pt);
-        if (p2)
-            pretask.push({ name: str(p2.name), exec: str(p2.exec) });
-    }
+    /* pretask：`exec` 必填；`args` / `option` / 过滤列表缺省为空。单条也可写成对象而不是数组。 */
+    const readPretasks = (list, src) => {
+        for (const pt of Array.isArray(list) ? list : (list !== undefined ? [list] : [])) {
+            const p2 = obj(pt);
+            const exec = p2 ? str(p2.exec) : undefined;
+            if (!p2)
+                continue;
+            if (!exec) {
+                problems.push({ message: 'pretask 缺少 exec，已跳过（' + src + '）' });
+                continue;
+            }
+            pretask.push({
+                ...(str(p2.name) !== undefined ? { name: str(p2.name) } : {}),
+                exec,
+                args: strList(p2.args),
+                option: strList(p2.option),
+                ...(strList(p2.controller).length ? { controller: strList(p2.controller) } : {}),
+                ...(strList(p2.resource).length ? { resource: strList(p2.resource) } : {}),
+            });
+        }
+    };
+    readPretasks(o.pretask, '主文件');
     /* import 合并（v2.2.0）：只合 task/option/preset/global_option/pretask（及 group/setting，本工具不消费）。
      * controller/resource 不可导入——子文件声明了也忽略并记 problems。循环导入用 visited 集合挡住。
      *
@@ -283,15 +376,12 @@ export function loadInterface(dir) {
         for (const g of strList(child.global_option))
             if (!globalOption.includes(g))
                 globalOption.push(g);
-        for (const pt of Array.isArray(child.pretask) ? child.pretask : []) {
-            const p2 = obj(pt);
-            if (p2)
-                pretask.push({ name: str(p2.name), exec: str(p2.exec) });
-        }
+        readPretasks(child.pretask, rel);
     }
     return {
         ...base,
         version: version ?? null,
+        projectVersion: str(o.version) ?? null,
         name: str(o.name) ?? null,
         controllers,
         resources,