@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/interface/override.js

@@ -1,25 +1,93 @@
+import { hotkeyTableFor, resolveHotkeyTokens } from './hotkey.js';
 /**
- * 把一份 pipeline_override 并入累计结果：同节点字段替换（与协议"不深度合并"一致）。
+ * 把调用方的覆盖（`--override`）追加到分层数组尾部 = 最高优先级。
+ * 对象 = 一层；数组 = 逐层（框架本来就接受数组，逐层继承，别在这里预合并）。
+ * 四级链、`run --override`、`timing --override` 共用这一个追加口——三处曾经各写一份，
+ * 代价是同一个参数在不同命令里表现不同。
+ */
+export function appendOverride(layers, ov) {
+    if (!ov)
+        return;
+    const list = Array.isArray(ov) ? ov : [ov];
+    for (const layer of list)
+        if (layer && typeof layer === 'object' && Object.keys(layer).length)
+            layers.push(layer);
+}
+const PLACEHOLDER = /\{([^{}]+)\}/g;
+/**
+ * 按 `pipeline_type` 转型。枚举只有 `string` / `int` / `bool`（没有 float）。
+ *
+ * 协议只写了"会根据该类型进行类型转换"，**没规定** int 遇到 `abc`、bool 接受哪些字面量 ——
+ * 这里的规则是本地约定，宁可转不了就整条模板放弃，也不猜一个值写进 pipeline。
+ */
+function convert(raw, type) {
+    if (type === 'int')
+        return /^-?\d+$/.test(raw.trim()) ? Number(raw.trim()) : undefined;
+    if (type === 'bool') {
+        const s = raw.trim().toLowerCase();
+        if (s === 'true' || s === '1')
+            return true;
+        if (s === 'false' || s === '0')
+            return false;
+        return undefined;
+    }
+    return raw;
+}
+/**
+ * 解析一个 option 的当前取值（**唯一一份实现**）：pipeline_override 合成与 pretask 的末位 JSON
+ * 都走这里，两边各写一套迟早会在"preset 的 input 值是对象还是字符串"上分叉。
  *
- * **唯一一份实现**：四级链、`run --override`、`timing --override` 都走这里。这三处曾经各写一份，
- * 代价是同一个参数在不同命令里表现不同。非对象值必须**原样替换、不能展开**：字符串会被摊成
- * `{0:'a',1:'b'}`，`null` / 数字会静默变成空对象——等于把用户写的节点悄悄丢掉。
+ * 优先级（协议未规定，本地约定）：CLI > preset > 声明里的初始值（`default_case` / `inputs[].default`）。
  */
-export function mergeOverride(acc, po) {
-    for (const [node, fields] of Object.entries(po)) {
-        if (fields && typeof fields === 'object' && !Array.isArray(fields)) {
-            acc[node] = { ...(acc[node] ?? {}), ...fields };
+export function resolveOptionValue(o, ctx) {
+    if (o.type === 'input' || o.type === 'hotkey') {
+        const fields = {};
+        let via = 'declared';
+        for (const f of [...(o.inputs ?? []), ...(o.hotkeys ?? [])]) {
+            if (f.default !== undefined)
+                fields[f.name] = f.default;
+        }
+        const pv = ctx.presetTask?.option?.[o.name];
+        if (pv && typeof pv === 'object' && !Array.isArray(pv)) {
+            for (const [k, v] of Object.entries(pv))
+                fields[k] = String(v);
+            if (Object.keys(pv).length)
+                via = 'preset';
         }
-        else {
-            acc[node] = fields;
+        const cli = ctx.optionFields?.[o.name];
+        if (cli) {
+            for (const [k, v] of Object.entries(cli))
+                fields[k] = v;
+            if (Object.keys(cli).length)
+                via = 'cli';
         }
+        return { kind: 'fields', fields, via };
     }
+    const cli = ctx.optionCases?.[o.name];
+    if (cli !== undefined) {
+        return { kind: 'cases', cases: Array.isArray(cli) ? cli.map(String) : [String(cli)], via: 'cli' };
+    }
+    const pv = ctx.presetTask?.option?.[o.name];
+    /* preset 里 input 的值是对象——这里只处理 case 型，对象值留给出上面的分支 */
+    if (pv !== undefined && !(pv && typeof pv === 'object' && !Array.isArray(pv))) {
+        return { kind: 'cases', cases: Array.isArray(pv) ? pv.map(String) : [String(pv)], via: 'preset' };
+    }
+    if (o.defaultCase !== undefined) {
+        return {
+            kind: 'cases',
+            cases: Array.isArray(o.defaultCase) ? o.defaultCase.map(String) : [String(o.defaultCase)],
+            via: 'default',
+        };
+    }
+    return null;
 }
 export function computePipelineOverride(input) {
     const { loaded, controllerName, resourceName, taskName, presetName } = input;
     const warns = [];
     const applied = [];
-    const acc = {};
+    /** 进过链的 option 键：用来抓"--option 给了值但没有任何级别引用它"这种静默失联 */
+    const reached = new Set();
+    const layers = [];
     const preset = presetName ? loaded.presets.find((p) => p.name === presetName) : undefined;
     if (presetName && !preset)
         warns.push('preset ' + presetName + ' 不存在（可用：' + loaded.presets.map((p) => p.name).join(' / ') + '或无）');
@@ -31,21 +99,47 @@ export function computePipelineOverride(input) {
             return false;
         return true;
     };
-    /** 解析一个 option 的当前取值：preset > default_case；返回 case 名（单个或数组）。 */
-    const valueOf = (name) => {
-        const o = loaded.options[name];
-        if (!o) {
-            warns.push('option ' + name + ' 未在 interface 中定义，已跳过');
-            return null;
-        }
-        const pv = presetTask?.option?.[name];
-        if (pv !== undefined) {
-            return { cases: Array.isArray(pv) ? pv.map(String) : [String(pv)], via: 'preset' };
-        }
-        if (o.defaultCase !== undefined) {
-            return { cases: Array.isArray(o.defaultCase) ? o.defaultCase.map(String) : [String(o.defaultCase)], via: 'default' };
-        }
-        return null;
+    const valueCtx = {
+        ...(presetTask ? { presetTask } : {}),
+        ...(input.optionCases ? { optionCases: input.optionCases } : {}),
+        ...(input.optionFields ? { optionFields: input.optionFields } : {}),
+    };
+    /**
+     * 把模板里的 `{字段名}` 换成取值：整串是占位时用转型后的值（int → 数字），
+     * 出现在片段里时用它的文本形态（如 `MainChapter_{章节号}`）。
+     * 有任何一个占位取不到值就整条模板放弃——写一半的 override 比不写更难查。
+     */
+    const substitute = (tpl, tokens) => {
+        const missing = [];
+        const one = (name) => {
+            if (!(name in tokens)) {
+                if (!missing.includes(name))
+                    missing.push(name);
+                return undefined;
+            }
+            return tokens[name];
+        };
+        const walk = (n) => {
+            if (typeof n === 'string') {
+                const whole = /^\{([^{}]+)\}$/.exec(n);
+                if (whole)
+                    return one(whole[1]);
+                return n.replace(PLACEHOLDER, (_m, name) => {
+                    const v = one(name);
+                    return v === undefined ? '' : String(v);
+                });
+            }
+            if (Array.isArray(n))
+                return n.map(walk);
+            if (n && typeof n === 'object') {
+                const out = {};
+                for (const [k, v] of Object.entries(n))
+                    out[k] = walk(v);
+                return out;
+            }
+            return n;
+        };
+        return { value: walk(tpl), missing };
     };
     const mergeOption = (name, level, chain = []) => {
         /* 嵌套 option 是"case 里再列 option"，A → B → A 这类自引用会让递归停不下来：
@@ -55,17 +149,95 @@ export function computePipelineOverride(input) {
             return;
         }
         const o = loaded.options[name];
-        if (o && !applicable(o))
+        if (!o) {
+            warns.push('option ' + name + ' 未在 interface 中定义，已跳过');
             return;
-        const v = valueOf(name);
-        if (!o)
+        }
+        reached.add(name);
+        if (!applicable(o)) {
+            if (input.optionCases?.[name] !== undefined || input.optionFields?.[name] !== undefined) {
+                warns.push('option ' + name + ' 不适用于当前控制器/资源（适用性过滤），--option 给的取值未生效');
+            }
+            return;
+        }
+        if (o.type === 'input' || o.type === 'hotkey') {
+            const tpl = o.pipelineOverride;
+            if (!tpl || !Object.keys(tpl).length) {
+                /* 没有模板 = 没有东西可丢。但如果有人专门给它传了 --option，那是一次静默失联，要说。 */
+                if (input.optionFields?.[o.name] !== undefined) {
+                    warns.push('option ' + o.name + ' 声明为 ' + o.type + ' 但没有 pipeline_override 模板，--option 给的字段不参与覆盖');
+                }
+                return;
+            }
+            const resolved = resolveOptionValue(o, valueCtx);
+            const fields = resolved && resolved.kind === 'fields' ? resolved.fields : {};
+            const tokens = {};
+            if (o.type === 'hotkey') {
+                /* 占位符产出的是**当前控制器 type 的虚拟按键码整数**（Win32 VK / Android KeyEvent /
+                 * Carbon kVK / evdev）。没有表的控制器类型直接跳过并说明——按 Win32 猜等于写错键。 */
+                const decl = controllerName ? loaded.controllers.find((x) => x.name === controllerName) : undefined;
+                const table = hotkeyTableFor(decl?.type ?? null, decl?.linux?.useWin32VkCode === true);
+                if (!table) {
+                    warns.push('option ' + name + '（' + level + '）是 hotkey：当前控制器' +
+                        (decl ? '类型 ' + decl.type + ' 没有键码映射表' : '未确定（没选中控制器）') +
+                        '，这一层覆盖已跳过');
+                    return;
+                }
+                for (const f of o.hotkeys ?? []) {
+                    const raw = fields[f.name];
+                    if (raw === undefined || raw === '')
+                        continue; // 缺值交给下面的 missing 统一报
+                    const hk = resolveHotkeyTokens(f.name, raw, table);
+                    if (hk.error) {
+                        warns.push('option ' + name + '（' + level + '）的 hotkey 字段 ' + f.name + ' 解析失败：' + hk.error + '——整条覆盖已跳过');
+                        return;
+                    }
+                    Object.assign(tokens, hk.tokens);
+                }
+            }
+            else {
+                const bad = [];
+                for (const [k, raw] of Object.entries(fields)) {
+                    const t = convert(raw, o.inputs?.find((f) => f.name === k)?.pipelineType);
+                    if (t === undefined)
+                        bad.push(k + '=' + raw);
+                    else
+                        tokens[k] = t;
+                }
+                if (bad.length) {
+                    warns.push('option ' + name + '（' + level + '）的输入值按 pipeline_type 转不了型：' + bad.join(' / ') + '——整条覆盖已跳过');
+                    return;
+                }
+            }
+            const r = substitute(tpl, tokens);
+            if (r.missing.length) {
+                warns.push('option ' + name + '（' + level + '）的 pipeline_override 模板里这些占位没有取值：' +
+                    r.missing.join(' / ') + '——整条覆盖已跳过（用 --option ' + name + '.<字段>=<值> 给值）');
+                return;
+            }
+            layers.push(r.value);
+            /* password 字段（v2.10.0）回显掩码——值该进 tokens/pipeline_override，不进输出与日志。 */
+            const pwdNames = new Set((o.inputs ?? []).filter((f) => f.password).map((f) => f.name));
+            const shown = Object.entries(fields).map(([k, v]) => k + '=' + (pwdNames.has(k) ? '•••' : v)).join('，');
+            applied.push(name + '=（' + o.type + (shown ? '：' + shown : '') + '，' + level + '）');
             return;
-        if (!v) {
-            if (o.type === 'input' || o.type === 'hotkey')
-                return; // 输入类不产生 pipeline_override，不算异常
+        }
+        const v = resolveOptionValue(o, valueCtx);
+        if (!v || v.kind !== 'cases') {
             warns.push('option ' + name + '（' + level + '）无 preset/default_case 取值，跳过其 pipeline_override');
             return;
         }
+        /* checkbox 的 min_count / max_count（v2.10.1）：取值数量违反约束只警告不阻断——
+         * 声明的问题修在 interface.json，跑坏比选对来得早。 */
+        if (o.type === 'checkbox') {
+            const n = v.cases.length;
+            if (o.minCount !== undefined && n < o.minCount) {
+                warns.push('option ' + name + '（checkbox）：选中 ' + n + ' 项 < min_count=' + o.minCount);
+            }
+            if (o.maxCount !== undefined && n > o.maxCount) {
+                warns.push('option ' + name + '（checkbox）：选中 ' + n + ' 项 > max_count=' + o.maxCount);
+            }
+        }
         for (const cname of v.cases) {
             const c = o.cases.find((x) => x.name === cname);
             if (!c) {
@@ -73,7 +245,7 @@ export function computePipelineOverride(input) {
                 continue;
             }
             if (c.pipelineOverride && Object.keys(c.pipelineOverride).length) {
-                mergeOverride(acc, c.pipelineOverride);
+                layers.push(c.pipelineOverride);
                 applied.push(name + '=' + cname + '（' + level + '，via ' + v.via + '）');
             }
             /* 嵌套子 option：父 case 生效后按声明顺序合并（更具体，晚于父级） */
@@ -81,6 +253,12 @@ export function computePipelineOverride(input) {
                 mergeOption(child, level + ' > ' + name, [...chain, name]);
         }
     };
+    /* task 级覆盖是基底：协议只规定 option 四级顺序，没说它插在哪一级——这里按"先应用"处理。 */
+    const taskDecl = taskName ? loaded.tasks.find((x) => x.name === taskName) : undefined;
+    if (taskDecl?.pipelineOverride && Object.keys(taskDecl.pipelineOverride).length) {
+        layers.push(taskDecl.pipelineOverride);
+        applied.push('task.pipeline_override（task 级基底）');
+    }
     for (const name of loaded.globalOption)
         mergeOption(name, 'global_option');
     if (resourceName) {
@@ -98,6 +276,12 @@ export function computePipelineOverride(input) {
         for (const name of t?.option ?? [])
             mergeOption(name, 'task.option');
     }
-    return { override: acc, warns, applied };
+    /* --option 的键必须有级别引用过它，否则用户以为改了、其实没进链 */
+    for (const key of [...Object.keys(input.optionCases ?? {}), ...Object.keys(input.optionFields ?? {})]) {
+        if (!reached.has(key)) {
+            warns.push('--option 里的 ' + key + ' 没有被任何级别引用（global/resource/controller/task 都没列它），取值未生效');
+        }
+    }
+    return { override: layers, warns, applied };
 }
 //# sourceMappingURL=override.js.map

package/lib/interface/plan.js

@@ -4,8 +4,24 @@
  *
  * 为什么不猜设备：猜错不只是连错窗口，还会把 roi 与模板的坐标系一起猜错。
  */
+import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
-const KIND_BY_TYPE = { Adb: 'adb', Win32: 'win32', Gamepad: 'gamepad', PlayCover: 'playcover', Linux: 'linux' };
+function isDirectory(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+const KIND_BY_TYPE = { Adb: 'adb', Win32: 'win32', Gamepad: 'gamepad', PlayCover: 'playcover', MacOS: 'macos', Linux: 'linux' };
+/** 没有可枚举设备发现、且没有声明式入口的控制器：必须显式给 --target，工具不猜会话形态。
+ *  PlayCover 有缺省（localhost:1717 / maa.playcover）、Linux 可由 interface.json linux{} 组装，
+ *  都不在此列。 */
+const TARGET_REQUIRED = {
+    macos: 'MacOS 需要 --target <窗口 id 或标题子串>，或在 interface.json 的 macos.title_regex 声明匹配规则',
+    linux: 'Linux 需要 --target <config JSON>，或在 interface.json linux{} 里声明 screencap/input 等字段（Wlr 方法还需 wlr_socket_path，属用户配置、声明给不了）',
+};
 function safeRegExp(pattern) {
     try {
         return new RegExp(pattern);
@@ -41,10 +57,13 @@ export function planController(loaded, overrides, devices) {
             controllerName: c.name,
             connect: {},
             candidates: [],
-            error: '控制器 ' + c.name + ' 的类型 ' + c.type + ' 暂不受支持（本 CLI 支持 Adb / Win32 / Gamepad / PlayCover / Linux；MacOS 走手动 --kind macos）',
+            error: '控制器 ' + c.name + ' 的类型 ' + c.type + ' 暂不受支持（本 CLI 支持 Adb / Win32 / Gamepad / PlayCover / MacOS / Linux）',
         };
     }
     const notes = ['控制器 ' + c.name + '（来自 interface.json）'];
+    if (c.permissionRequired === true) {
+        notes.push('permission_required=true：该控制器需要管理员/root 权限运行，连接失败先查权限');
+    }
     const connect = { kind };
     if (c.display?.shortSide !== undefined)
         connect.shortSide = c.display.shortSide;
@@ -53,16 +72,56 @@ export function planController(loaded, overrides, devices) {
     if (c.display?.raw)
         connect.rawSize = true;
     if (c.display?.expand)
-        notes.push('display_expand 暂不生效（daemon 未接入），已忽略');
-    if (kind === 'playcover' || kind === 'linux') {
-        /* 两类控制器没有可枚举的设备发现：必须显式给 target（playcover=<address>/<uuid>，
-           linux=<config JSON>），工具不猜会话形态。 */
+        connect.expand = c.display.expand;
+    /* PlayCover：全缺省可构造（maa-support 同款缺省 localhost:1717 / maa.playcover）。
+       声明或显式给了就带，没给交给 daemon 兜底。 */
+    if (kind === 'playcover') {
+        const t = overrides.manualTarget ?? null;
+        if (t)
+            connect.target = t;
+        else
+            notes.push('PlayCover 未给 target：按缺省 localhost:1717 / maa.playcover 构造');
+        return { ok: true, controllerName: c.name, connect, notes };
+    }
+    /* Linux：interface.json linux{} 交给 daemon 组装 config JSON（maa-support/MXU 同款规则）。
+       用户 config JSON（--target）优先，其次声明式组装；Wlr 必填 wlr_socket_path，属用户配置，
+       interface 给不了——给不了时 daemon 侧如实报错。 */
+    if (kind === 'linux') {
+        const t = overrides.manualTarget ?? null;
+        if (c.linux)
+            connect.linuxDecl = c.linux;
+        if (t)
+            connect.target = t;
+        else if (!c.linux?.screencap && !c.linux?.input) {
+            return fail(c, 'TARGET_REQUIRED', TARGET_REQUIRED.linux, [], connect, notes);
+        }
+        else
+            notes.push('Linux 按 interface.json linux{} 组装 config（缺省 Wlr/Wlr）');
+        return { ok: true, controllerName: c.name, connect, notes };
+    }
+    const targetHint = TARGET_REQUIRED[kind];
+    if (targetHint) {
+        /* PlayCover / Linux 没有可枚举的设备发现，必须显式给 target，工具不猜会话形态。
+           MacOS 窗口能枚举但不在本工具的设备扫描通道里：按 PI 的 macos.title_regex 交给
+           daemon 侧 MacOSController.find() 匹配（不在这条通道枚举），没给 regex 仍要 target。 */
         const t = overrides.manualTarget ?? null;
-        if (!t) {
-            return fail(c, 'TARGET_REQUIRED', kind === 'playcover'
-                ? 'PlayCover 需要 --target <address>/<uuid>（PlayCover 设置里可见）'
-                : 'Linux 需要 --target <config JSON>（含 screencap_method / input_method 等必填字段）', [], connect, notes);
+        if (kind === 'macos') {
+            if (t)
+                connect.target = t;
+            else if (c.macos?.titleRegex)
+                connect.macosTitleRegex = c.macos.titleRegex;
+            else
+                return fail(c, 'TARGET_REQUIRED', targetHint, [], connect, notes);
+            if (c.macos?.screencap)
+                connect.screencap = c.macos.screencap;
+            if (c.macos?.input)
+                connect.input = c.macos.input;
+            if (c.macos?.titleRegex && !t)
+                notes.push('窗口：按 title_regex 匹配——' + c.macos.titleRegex);
+            return { ok: true, controllerName: c.name, connect, notes };
         }
+        if (!t)
+            return fail(c, 'TARGET_REQUIRED', targetHint, [], connect, notes);
         connect.target = t;
         return { ok: true, controllerName: c.name, connect, notes };
     }
@@ -150,39 +209,71 @@ export function planController(loaded, overrides, devices) {
  * 所选控制器的条目，条目自身多路径按声明顺序叠加（如"B 服"= base + bilibili）；
  * attach_resource_path 在选中控制器后追加。override（--resource）先按资源名匹配，
  * 匹配不上再按文件系统路径解释（原有行为）。
+ *
+ * 有多个条目都适用时，选中的那个与备选一起进 notes——"取第一个"是语义，但静默取第一个
+ * 会让用错资源包的人查不出原因。
  */
-export function resolveResourcePaths(loaded, controllerName, override) {
+export function resolveResourcePaths(loaded, controllerName, override, 
+/** `--resource` 当目录路径时的解析基准（CLI 的 ctx.cwd；缺省 = process.cwd()） */
+cwd) {
     const dir = loaded.dir;
     /**
      * 追加控制器声明的 attach_resource_path（v2.2.0："在 resource.path 加载完成后，额外加载"）。
      * 它是**控制器的属性**，所以 `--resource` 走哪条分支都要追加——曾经两条提前 return 把它丢了。
      */
-    const withAttach = (paths, names, selected) => {
+    const withAttach = (paths, names, selected, notes = [], expected) => {
         const out = [...paths];
+        const attachDirs = [];
         if (dir && controllerName) {
             const c = loaded.controllers.find((x) => x.name === controllerName);
             for (const p of c?.attachResourcePath ?? [])
-                out.push(resolve(dir, p));
+                attachDirs.push(resolve(dir, p));
         }
-        return { paths: [...new Set(out)], names, selected };
+        out.push(...attachDirs);
+        const hashCheck = expected && selected
+            ? { resourceName: selected, expected, pathDirs: [...paths], attachDirs }
+            : undefined;
+        return { paths: [...new Set(out)], names, selected, ...(notes.length ? { notes } : {}), ...(hashCheck ? { hashCheck } : {}) };
     };
     if (override) {
         const byName = loaded.resources.find((r) => r.name === override);
         if (byName && dir) {
-            return withAttach(byName.paths.map((p) => resolve(dir, p)), [byName.name], byName.name);
+            return withAttach(byName.paths.map((p) => resolve(dir, p)), [byName.name], byName.name, [], byName.hash);
         }
-        return withAttach([resolve(override)], ['(--resource)'], null);
+        /* 名字没匹配上时允许当目录路径（老行为），但必须真的存在——打错一个字的资源名
+         * 会被静默接受成路径，selected=null 让所有资源级过滤（option 适用性、pretask、
+         * hash 校验）跳过，比拒绝启动更难查。基准是调用方的 cwd（CLI 的 --cwd），
+         * 不是 interface.json 所在目录。 */
+        if (!isDirectory(resolve(cwd ?? '', override))) {
+            return {
+                paths: [], names: [], selected: null,
+                error: '--resource ' + JSON.stringify(override) + ' 不是资源名也不是存在的目录' +
+                    (loaded.resources.length ? '（可用：' + loaded.resources.map((r) => r.name).join(' / ') + '）' : ''),
+            };
+        }
+        return withAttach([resolve(cwd ?? '', override)], ['(--resource)'], null);
     }
     if (!dir)
         return { paths: [], names: [], selected: null };
     const applicable = loaded.resources.filter((r) => !controllerName || !r.controllers.length || r.controllers.includes(controllerName));
     const paths = [];
     let selected = null;
+    const notes = [];
     if (applicable.length) {
         selected = applicable[0].name;
         for (const p of applicable[0].paths)
             paths.push(resolve(dir, p));
+        /* resource[] 是互斥单选：多个条目都适用时没有"都对"的答案，按声明序取第一个就是 Client 语义。
+         * 但用户/agent 看不到"其实还有别的可选"——用错资源包（中/英资产、多语言模型）会静默跑错，
+         * 所以把这次的选择和备选摆到台面上。 */
+        /* 候选 >5 时折叠全名列表（9 服全摆出来是噪音不是信息；--json 里 names 全量在）。
+         * 互斥单选的选择语义的说明保留——"已选哪份"正是 agent 要的。 */
+        if (applicable.length > 1) {
+            const names = applicable.map((r) => r.name);
+            const list = names.length <= 5 ? names.join(' / ') : names.slice(0, 3).join(' / ') + ' …共 ' + names.length + ' 个';
+            notes.push('当前控制器适用 ' + applicable.length + ' 个资源（' + list + '），已选 ' + selected + '——要换用 --resource <名>');
+        }
     }
-    return withAttach(paths, selected ? [selected] : [], selected);
+    return withAttach(paths, selected ? [selected] : [], selected, notes, applicable[0]?.hash);
 }
 //# sourceMappingURL=plan.js.map

package/lib/option-args.js

@@ -0,0 +1,29 @@
+export function parseOptionArgs(list) {
+    const out = { cases: {}, fields: {} };
+    const items = Array.isArray(list) ? list : list === undefined ? [] : [list];
+    for (const item of items) {
+        const s = typeof item === 'string' ? item : '';
+        const eq = s.indexOf('=');
+        const lhs = eq > 0 ? s.slice(0, eq).trim() : '';
+        if (!lhs) {
+            out.error = '--option 要写成 <键>=<值> 或 <键>.<字段>=<值>：' + JSON.stringify(item);
+            return out;
+        }
+        const rhs = s.slice(eq + 1);
+        const dot = lhs.indexOf('.');
+        if (dot > 0) {
+            const key = lhs.slice(0, dot);
+            const field = lhs.slice(dot + 1);
+            if (!field) {
+                out.error = '--option 的字段名不能为空：' + JSON.stringify(item);
+                return out;
+            }
+            out.fields[key] = { ...(out.fields[key] ?? {}), [field]: rhs };
+        }
+        else {
+            out.cases[lhs] = rhs.includes(',') ? rhs.split(',').map((x) => x.trim()).filter(Boolean) : rhs;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=option-args.js.map

package/lib/pkg.js

@@ -1,5 +1,7 @@
 /** 读取 CLI 自身包信息。src 与 lib 都在包根下一层，故 `../package.json` 两种运行方式都成立。 */
 import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 let cached = null;
 export function cliPackage() {
@@ -15,4 +17,38 @@ export function cliPackage() {
     }
     return cached;
 }
+let maaNodeCached = null;
+/**
+ * 运行中**实际加载**的 maa-node 版本（PI_CLIENT_MAAFW_VERSION）。
+ *
+ * 为什么不用 package.json 的声明值：那里写的是范围（^5.14.2），而 agent 侧拿这个变量是要判协议
+ * 兼容的——报范围等于没报。maa-node 不导出 `version`，也不保证导出 package.json，
+ * 所以从入口向上找包根。拿不到返回空串（调用方据此不注入，而不是编一个）。
+ */
+export function maaNodeVersion() {
+    if (maaNodeCached !== null)
+        return maaNodeCached;
+    maaNodeCached = '';
+    try {
+        const req = createRequire(import.meta.url);
+        let dir = dirname(req.resolve('@maaxyz/maa-node'));
+        for (let i = 0; i < 6; i++) {
+            const p = join(dir, 'package.json');
+            try {
+                const j = JSON.parse(readFileSync(p, 'utf8'));
+                if (j.name === '@maaxyz/maa-node' && j.version) {
+                    maaNodeCached = j.version;
+                    break;
+                }
+            }
+            catch { /* 继续向上找 */ }
+            const up = dirname(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    catch { /* 解析不到就留空 */ }
+    return maaNodeCached;
+}
 //# sourceMappingURL=pkg.js.map

package/lib/protocol.js

@@ -18,6 +18,10 @@ export const EXIT = {
     FINDINGS: 3,
     /** 前置环境缺失（缺 maa-node / 缺 checkout / 缺设备） */
     ENV: 4,
+    /** 被 SIGINT（Ctrl-C）中断：128+2 */
+    SIGINT: 130,
+    /** 被 SIGTERM 中断：128+15 */
+    SIGTERM: 143,
 };
 export function toEnvelope(command, r) {
     return {