@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/runtime/actions.js

@@ -8,10 +8,17 @@
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { rmSync } from 'node:fs';
-import { loadInterface, planController, resolveResourcePaths, } from '../interface/index.js';
+import { computePipelineOverride, loadInterface, appendOverride, planController, resolveResourcePaths, } from '../interface/index.js';
 import { spawnDaemon } from '../client/daemon.js';
-/** 起一个 daemon、跑 fn、无论如何都收掉子进程。一次性命令用它，REPL 用长活客户端。 */
-export async function withDaemon(fn, options = {}) {
+import { buildAgentEnv } from './pi-env.js';
+/**
+ * 给命令一个 daemon 客户端：ctx.client 有就借用（REPL / 命名会话，**不关**——
+ * 会话的生命周期不归命令管）；没有才 spawn 一次性的，跑完即关。
+ * 统一入口的意义：命令只需写一遍，`--session` 转发与 REPL 复用走的是同一份实现。
+ */
+export async function withDaemon(ctx, fn, options = {}) {
+    if (ctx.client)
+        return await fn(ctx.client);
     const client = spawnDaemon(options);
     try {
         return await fn(client);
@@ -49,6 +56,8 @@ export async function seedObservation(c, prefix) {
 export const streamStart = (c, args = {}) => c.call('stream_start', args, 15000);
 export const streamStop = (c) => c.call('stream_stop', {}, 10000);
 export const streamStatus = (c) => c.call('stream_status', {}, 10000);
+/** 事件环查询：一次性 CLI 用。事件环活在 daemon 里，跨进程只能现查（REPL 另有本地副本）。 */
+export const eventsList = (c, args = {}) => c.call('events_list', args, 10000);
 export const frameGet = (c, args) => c.call('frame_get', args, 30000);
 /** 等状态谓词成立：stable=画面静下来 / change=画面动了。取代调用方硬睡时钟。 */
 export const waitState = (c, args = {}) => c.call('wait', args, Math.min(120000, Number(args.timeout ?? 10000)) + 5000);
@@ -69,12 +78,25 @@ export function run(c, args, timeoutMs = 30000) {
     return c.call('run', { ...args, timeoutMs: t === 0 ? 0 : budget }, budget + 15000);
 }
 export const input = (c, payload, timeoutMs = 20000) => c.call('input', payload, timeoutMs);
-export const recoTest = (c, args) => c.call('reco_test', args, 90000);
+/** 截图能力探测（A 路前提）：两次 post_screencap 间隔比 hash/亮度。timeout 给 interval+10s。 */
+export const screencapProbe = (c, intervalMs = 3000, occluded) => c.call('screencap_probe', { intervalMs, ...(occluded !== undefined ? { occluded } : {}) }, intervalMs + 15000);
+/** 识别单测。`timeoutMs` 供**多候选**调用方放宽（候选逐例串行，耗时随候选数线性增长：
+ * daemon 侧的子进程预算也跟着用例数放宽，见 framed.mjs 的 recoChildBudget）。 */
+export const recoTest = (c, args, timeoutMs = 90000) => c.call('reco_test', args, timeoutMs);
 /* ─────────────────────── 项目（interface.json）驱动 ─────────────────────── */
-/** 控制器类型 → 需要扫描的设备类型。控制器没声明时按第一个控制器推断。 */
+/**
+ * 控制器类型 → 需要扫描的设备类型；**无设备可枚举的类型返回 null**（调用方跳过扫描）。
+ * daemon 的 device_list 只枚举 adb/win32——PlayCover/MacOS/Linux 给 'win32' 会白白发起
+ * 一次必然失败的扫描（曾经就是这样，把无关窗口列表塞进计划错误里）。
+ */
 export function deviceKindFor(loaded, controllerName) {
     const c = controllerName ? loaded.controllers.find((x) => x.name === controllerName) : loaded.controllers[0];
-    return String(c?.type) === 'Adb' ? 'adb' : 'win32';
+    const t = String(c?.type);
+    if (t === 'Adb')
+        return 'adb';
+    if (t === 'Win32' || t === 'Gamepad')
+        return 'win32';
+    return null;
 }
 /**
  * 载入项目 → 扫设备 → 规划控制器 → 解析资源路径。
@@ -91,12 +113,15 @@ export async function planProject(c, dir, overrides = {}) {
     const controllerName = overrides.controller ?? loaded.controllers[0]?.name ?? null;
     const kind = deviceKindFor(loaded, controllerName);
     let devices = [];
-    try {
-        devices = await deviceList(c, kind);
-    }
-    catch (e) {
-        return { loaded, plan: null, controllerName, resource: null, error: '扫描设备失败：' + String(e.message || e) };
+    if (kind) {
+        try {
+            devices = await deviceList(c, kind);
+        }
+        catch (e) {
+            return { loaded, plan: null, controllerName, resource: null, error: '扫描设备失败：' + String(e.message || e) };
+        }
     }
+    /* kind=null（playcover/macos/linux）：没有可枚举设备，planController 走 --target 分支 */
     const plan = planController(loaded, {
         controller: controllerName ?? undefined,
         win32: { hwnd: overrides.hwnd ?? null },
@@ -104,7 +129,97 @@ export async function planProject(c, dir, overrides = {}) {
         adb: { address: overrides.address ?? null },
         manualTarget: overrides.manualTarget ?? null,
     }, devices);
-    const resource = resolveResourcePaths(loaded, controllerName ?? undefined, overrides.resource);
+    const resource = resolveResourcePaths(loaded, controllerName ?? undefined, overrides.resource, overrides.cwd);
     return { loaded, plan, controllerName, resource };
 }
+/**
+ * 项目模式 run 的唯一装配点：一次性 CLI 与 REPL `run` 都走这里。
+ *
+ * 为什么必须共享：REPL 曾经只吃 `--override`、不叠 interface 的四级链，同一项目同一入口
+ * 在 REPL 里 option / preset / default_case 全部不生效——agent 主路径与一次性命令跑出两套
+ * 行为，而且不报错。入口解析、task 适用性、pretask/agent 警示也一并收口，避免第二份规则。
+ */
+export function prepareProjectRun(input) {
+    const { project, entry } = input;
+    const { loaded } = project;
+    const warns = [];
+    const paths = project.resource?.paths ?? [];
+    if (!paths.length) {
+        return {
+            ok: false,
+            code: 'RESOURCE_NOT_FOUND',
+            error: '项目里没有解析出资源路径：检查 interface.json 的 resource[] 声明',
+            warns,
+        };
+    }
+    const task = loaded.tasks.find((t) => t.name === entry || t.entry === entry);
+    const resolvedEntry = task?.entry ?? entry;
+    const ctrlName = project.controllerName ?? null;
+    const resName = project.resource?.selected ?? null;
+    /* task 适用性（task.controller / task.resource 声明） */
+    if (task?.controller?.length && ctrlName && !task.controller.includes(ctrlName)) {
+        return {
+            ok: false,
+            code: 'TASK_NOT_APPLICABLE',
+            error: '任务 ' + task.name + ' 不支持当前控制器 ' + ctrlName + '（声明：' + task.controller.join(' / ') + '）',
+            hint: '换控制器（CLI 用 --controller <名>，REPL 重新 connect project）或选别的任务',
+            warns,
+        };
+    }
+    if (task?.resource?.length && resName && !task.resource.includes(resName)) {
+        warns.push('任务 ' + task.name + ' 声明资源 ' + task.resource.join(' / ') + '，当前选中的是 ' + resName);
+    }
+    /* 多个资源条目都适用时 resource[] 只能选一个：plan 侧记下"选了哪个、还有谁适用"，
+     * 在这里升成 warning——human 的 note 行机器消费面（--json）读不到。 */
+    for (const n of project.resource?.notes ?? [])
+        warns.push(n);
+    /* pipeline_override 四级合并链（preset > default_case 取值） + 用户 --override 最后覆盖 */
+    const chain = computePipelineOverride({
+        loaded,
+        controllerName: ctrlName,
+        resourceName: resName,
+        taskName: task?.name ?? null,
+        presetName: input.presetName ?? null,
+        ...(input.optionCases ? { optionCases: input.optionCases } : {}),
+        ...(input.optionFields ? { optionFields: input.optionFields } : {}),
+    });
+    warns.push(...chain.warns);
+    const agents = loaded.agents;
+    /* agent 子进程要的环境：PI_* 按 interface.json 的**当前选择**生成（控制器 / 资源 / 项目版本）。
+     * 不注入时 agent 不会报错，只会落到自带默认值——这是最安静的一种"跑的不是同一个配置"。 */
+    const agentEnv = buildAgentEnv({ loaded, controllerName: ctrlName, resourceName: resName });
+    if (agents.length) {
+        const injected = Object.keys(agentEnv);
+        warns.push('项目声明了 ' + agents.length + ' 个 agent 子进程（' +
+            agents.map((a) => [a.exec, ...a.args].join(' ')).join(' ; ') +
+            '），run 时自动 spawn 并桥接' +
+            (injected.length ? '（注入 ' + injected.join(' / ') + '）' : '') +
+            '——注意 maa-node 与 agent 侧 maa 库须同版本（协议握手要求）');
+    }
+    /* 分层 override：四级链已按层序排好（task 基底 + 各 option 层），用户 --override
+     * 追加到尾部=最高优先级。别在这里摊平——框架的层间字段继承（recognition/param 同
+     * type 按键继承）只有数组形态能保住层边界（上游 @8061d5b 已核）。 */
+    const override = [...chain.override];
+    if (input.override)
+        appendOverride(override, input.override);
+    return {
+        ok: true,
+        args: {
+            resourceDirs: paths,
+            /* v2.6 资源完整性：只在加载完 path[] 后读 hash（attach 不能算进去），
+             * 两段在 resolveResourcePaths 已经分好 */
+            ...(project.resource?.hashCheck ? { resourceHashCheck: project.resource.hashCheck } : {}),
+            entry: resolvedEntry,
+            override,
+            /* agent 桥接：daemon spawn 子进程（identifier 追加为末参）并 bind/connect 到本次 Resource */
+            agents: agents.map((a) => ({ exec: a.exec, args: a.args })),
+            agentCwd: loaded.dir ?? undefined,
+            agentEnv,
+        },
+        entry: resolvedEntry,
+        taskName: task?.name ?? null,
+        applied: chain.applied,
+        warns,
+    };
+}
 //# sourceMappingURL=actions.js.map

package/lib/runtime/log-watch.js

@@ -0,0 +1,160 @@
+/**
+ * 运行期日志跟随：run 这类长任务在执行中不产出任何可观测信号（daemon 的帧流被框架
+ * 截图链路占住，events 环为空），唯一还在更新的只有**项目 agent 自己写的日志**。
+ * 所以「跑的时候能不能看见正在发生什么」这件事，实现上就是「跟着 tail 那几份日志」。
+ *
+ * 本模块只做跟随与筛选，不解释日志内容 —— 判读规则属于项目（每个项目的日志格式不同）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+/* 条目 → 当下实际要跟随的文件集合（每 tick 重算，覆盖日更轮转与 glob） */
+function resolveEntryPaths(entry) {
+    if (/[*?\[\]]/.test(entry)) {
+        try {
+            return fs.globSync(entry);
+        }
+        catch {
+            return [];
+        }
+    }
+    try {
+        if (fs.statSync(entry).isDirectory()) {
+            const hits = fs.readdirSync(entry)
+                .map((f) => { try {
+                const p = path.join(entry, f);
+                return { p, m: fs.statSync(p).mtimeMs };
+            }
+            catch {
+                return null;
+            } })
+                .filter((x) => x !== null);
+            hits.sort((a, b) => b.m - a.m);
+            return hits.slice(0, 1).map((x) => x.p);
+        }
+    }
+    catch { /* 不存在也是合法状态（等它出现） */ }
+    return [entry];
+}
+export function watchLogs(opts, onFlush) {
+    const intervalMs = opts.intervalMs ?? 1500;
+    const maxLines = opts.maxLinesPerFlush ?? 40;
+    const sources = opts.entries ?? opts.paths ?? [];
+    /* FileState 挂在「条目→文件」的映射上：同一条目解析出新文件时重置 offset 重读
+     * （日更轮转 = 条目解析到另一个文件名），解析回原文件时保持原 offset。 */
+    const byEntry = new Map();
+    const resolveStates = () => {
+        const out = [];
+        for (const entry of sources) {
+            const prev = byEntry.get(entry) ?? [];
+            const prevByPath = new Map(prev.map((s) => [s.path, s]));
+            const states = resolveEntryPaths(entry).map((p) => {
+                const seen = prevByPath.get(p);
+                if (seen)
+                    return seen;
+                /* 新解析出来的文件保持"从尾部开始"的首次跟随语义（等价于 run 启动时只关心之后的事）。
+                 * 从 0 起读会把该文件的整份历史一次倒出来（目录条目首跑就踩这个）。 */
+                let size = 0;
+                try {
+                    size = fs.statSync(p).size;
+                }
+                catch { /* 还没出现：0 起读等它长出来 */ }
+                return { path: p, offset: size, lastSize: size };
+            });
+            byEntry.set(entry, states);
+            out.push(...states);
+        }
+        return out;
+    };
+    /* resolveStates 已为每个条目 seed 好"新文件=尾部起读"，不需要再单独扫一遍。
+     * 首次跟随语义（只关心从现在起的事）由 FileState 的 offset=statSync.size 体现。 */
+    resolveStates();
+    const stats = { lines: 0, pushed: 0, files: [] };
+    let buffer = [];
+    let stopped = false;
+    const readNew = () => {
+        /* 每 tick 重解析条目：文件在启动后新建、日更轮转（跨午夜换文件名）、目录里出现
+         * 更新的文件都能跟上——这是 4.1 那次 `--watch log_20261110.txt` 跨午夜跟丢的修法。
+         * 新解析出的文件 seed 到尾部起读（resolveStates），同一条目换文件不整份倒历史。 */
+        for (const st of resolveStates()) {
+            let s;
+            try {
+                s = fs.statSync(st.path);
+            }
+            catch {
+                continue;
+            }
+            if (!stats.files.includes(st.path))
+                stats.files.push(st.path);
+            /* 轮转或截断：回到 0 重读 */
+            if (s.size < st.offset) {
+                st.offset = 0;
+            }
+            if (s.size === st.offset) {
+                st.lastSize = s.size;
+                continue;
+            }
+            const len = s.size - st.offset;
+            const buf = Buffer.alloc(len);
+            let fd;
+            try {
+                fd = fs.openSync(st.path, "r");
+                fs.readSync(fd, buf, 0, len, st.offset);
+            }
+            catch {
+                continue;
+            }
+            finally {
+                if (fd !== undefined) {
+                    try {
+                        fs.closeSync(fd);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+            st.offset = s.size;
+            st.lastSize = s.size;
+            const text = buf.toString("utf8");
+            for (const line of text.split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                stats.lines += 1;
+                if (opts.include?.length && !opts.include.some((re) => re.test(line)))
+                    continue;
+                if (opts.exclude?.length && opts.exclude.some((re) => re.test(line)))
+                    continue;
+                buffer.push(line);
+            }
+        }
+    };
+    const timer = setInterval(() => {
+        if (stopped)
+            return;
+        readNew();
+        if (!buffer.length)
+            return;
+        const took = buffer.slice(0, maxLines);
+        const rest = buffer.length - took.length;
+        buffer = [];
+        stats.pushed += took.length;
+        onFlush(rest > 0 ? [...took, "… 还有 " + String(rest) + " 行未显示"] : took);
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        stop() {
+            stopped = true;
+            clearInterval(timer);
+            /* 收尾时把剩余行补推一次，避免最后几行丢在缓冲里 */
+            readNew();
+            if (buffer.length) {
+                const rest = buffer;
+                buffer = [];
+                stats.pushed += rest.length;
+                onFlush(rest.slice(0, maxLines));
+            }
+            return stats;
+        },
+    };
+}
+//# sourceMappingURL=log-watch.js.map

package/lib/runtime/node-source.js

@@ -0,0 +1,100 @@
+/**
+ * reco 的文件参数：`--node-file` / `--param-file`（`-` = stdin，两个 flag 对称支持）。
+ *
+ * 为什么要有文件通道：整节点 JSON 只能走 argv，而 Windows 上 bash → `cmd.exe`(npm shim) → node
+ * 会把 `^` 当转义符吃掉——`expected: "^解锁"` 到进程时已变成 `"解锁"`，三种正则给出相同结果，
+ * 一度被误判成"工具不应用 expected 过滤"。文件绕开的是**参数被 shell 改写**，不是 JSON 解析。
+ *
+ * 为什么按 JSONC 解析：pipeline 常带 `//` 注释，strict `JSON.parse` 会误伤真实文件；解析器复用
+ * interface 那一份（`parseJsonc`），不在这里再写一遍脱敏逻辑。
+ *
+ * 为什么不用 `@a.json`：PowerShell 里 `@` 是 splat 前缀，会再踩一次"被 shell 破坏的参数"，
+ * 与"不在工具里猜测/修复被破坏参数"的纪律冲突。
+ */
+import { readFileSync } from 'node:fs';
+import { parseJsonc } from '../interface/jsonc.js';
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** 读 `--xxx-file <path>`：`-` 读 stdin（一次性命令才有意义，REPL 里 stdin 是命令流） */
+export function readJsoncArg(spec, flag) {
+    let text;
+    if (spec === '-') {
+        try {
+            text = readFileSync(0, 'utf8');
+        }
+        catch (e) {
+            return { error: flag + ' - 从 stdin 读取失败：' + message(e) };
+        }
+    }
+    else {
+        try {
+            text = readFileSync(spec, 'utf8');
+        }
+        catch (e) {
+            return { error: flag + ' 读不到文件：' + spec + '（' + message(e) + '）' };
+        }
+    }
+    try {
+        return { value: parseJsonc(text) };
+    }
+    catch (e) {
+        return { error: flag + ' 不是合法 JSON/JSONC：' + message(e) };
+    }
+}
+/**
+ * 节点表识别：文件里是 `{ "<节点名>": {…}, … }` 而不是一个节点。
+ *
+ * 判据：**单节点必有 `recognition`**（V1 字符串或 V2 对象），且节点表的每个值都是对象、
+ * 至少有一个带 `recognition`。要求"至少一个带 recognition"是为了把 `{"action":{…}}` 这种
+ * **缺 recognition 的单节点**留给"缺字段"的报错——它看起来也像"所有值都是对象"。
+ * 这条只服务于报错文案（提示去用 `--node-name`），不构成"pipeline 文件"能力，也不改变执行路径。
+ */
+export function isNodeTable(value) {
+    if (value.recognition !== undefined)
+        return false;
+    const keys = Object.keys(value);
+    if (keys.length === 0)
+        return false;
+    const allObjects = keys.every((k) => {
+        const v = value[k];
+        return v !== null && typeof v === 'object' && !Array.isArray(v);
+    });
+    if (!allObjects)
+        return false;
+    return keys.some((k) => value[k].recognition !== undefined);
+}
+/** `--node-file` → 单个节点 */
+export function readNodeFile(spec) {
+    const j = readJsoncArg(spec, '--node-file');
+    if (j.error)
+        return { error: j.error };
+    const v = j.value;
+    if (!v || typeof v !== 'object' || Array.isArray(v)) {
+        return { error: '--node-file 里必须是单个节点对象（pipeline 节点）' };
+    }
+    const node = v;
+    if (isNodeTable(node)) {
+        return {
+            error: '--node-file 拿到的是节点表（多节点），不是单个节点',
+            hint: '这是 pipeline 文件的形状：按原名跑用 --node-name <节点名>（配 --project 或 --resource-dir），' +
+                '只测其中一节就从文件里摘出那个节点',
+        };
+    }
+    if (node.recognition === undefined) {
+        return { error: '--node-file 的节点缺少 recognition 字段（V1 字符串或 V2 {type,param}）' };
+    }
+    return { node };
+}
+/** `--param-file` → recognition.param 那一层参数对象 */
+export function readParamFile(spec) {
+    const j = readJsoncArg(spec, '--param-file');
+    if (j.error)
+        return { error: j.error };
+    const v = j.value;
+    if (!v || typeof v !== 'object' || Array.isArray(v)) {
+        return { error: '--param-file 里必须是参数对象（recognition.param 那一层，形如 {"template":"a.png"}）' };
+    }
+    return { param: v };
+}
+//# sourceMappingURL=node-source.js.map

package/lib/runtime/ocr-model.js

@@ -0,0 +1,45 @@
+/**
+ * OCR 模型是否在资源链里：只回答"链上有没有框架会去读的那几个文件"。
+ *
+ * 为什么需要它：OCR 的 miss 与模板匹配不同——**模型没加载时框架不报错**，只回一个空结果
+ * （`detail.all: []`、`hit:false`、约 200ms），与"roi 里真的没有字"完全同形（实测：一个不带
+ * `model/` 的资源目录跑 `--type OCR` 就是这个签名）。不做这条判断，`describeMisses` 会把
+ * "没加载 OCR 模型"报成"roi 内无文字"——正是本提案要清掉的那类误诊。
+ *
+ * 依据（MaaFramework 5.11.2 pinned source；本机运行时 5.14.2，相差一个小版本，
+ * 相关实现见 `Resource/ResourceMgr.cpp::load_bundle` 与 `Resource/OCRResMgr.cpp`
+ * 的 `lazy_load` / `load_deter` / `load_recer`）：
+ *  - `load_bundle` 对每个 bundle 调一次 `lazy_load(<bundle>/model/ocr)`，把该目录登记进
+ *    roots 列表（后加载的在后），目录不存在就不登记；
+ *  - `load_deter(name)` 遍历 roots，取第一个存在 `<root>/<name>/det.onnx` 的 root；
+ *    `load_recer(name)` 遍历 roots，取第一个 `<root>/<name>/rec.onnx` 与
+ *    `<root>/<name>/keys.txt` **同时**存在的 root；
+ *  - `load_ocrer(name)` 要求 deter 与 recer 都拿到，所以判据是**合并**的：det 与 rec 允许
+ *    来自不同 root（base 放 det、overlay 放 rec+keys 是齐的），但 rec 与 keys 必须同属一个
+ *    root——它们是 load_recer 同一次调用里的两项，不会被拆开拼；
+ *  - `<name>` 来自节点参数 `model`，缺省空串 = 直接放在 `model/ocr/` 下；
+ *  - 缺任一项 → 拿不到 ocrer，`OCRer::predict` 只是记日志并回空结果，**不抛错**。
+ *
+ * 因此这里不能把"某一段目录三件套齐全"当判据：那会把"det 在 base、rec+keys 在 overlay"
+ * 误报成 missing，而它其实完全可用——误报会把人引去补模型，真正该看的 roi 反而被略过。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const DET = 'det.onnx';
+/** recer 的两项必须同目录同时存在：对应 `load_recer` 同一次调用里的两个文件。 */
+const RECER = ['rec.onnx', 'keys.txt'];
+/**
+ * 资源链上是否能找到 OCR 模型。`modelName` 是节点/参数里声明的模型名（缺省空串）。
+ *
+ * 只查文件存在性、不解析 onnx：判断的是"框架会不会找到它"，不是"模型能不能跑"。
+ * 按框架的合并规则判：det 与 rec 可以来自不同段，rec 与 keys 必须同段。
+ */
+export function ocrModelStatus(resourceDirs, modelName) {
+    const name = typeof modelName === 'string' ? modelName.trim() : '';
+    // 每段一个候选目录，顺序与框架扫 roots 的顺序一致（这里不需要顺序，只在同段内成组）。
+    const folders = resourceDirs.map((dir) => name === '' ? join(dir, 'model', 'ocr') : join(dir, 'model', 'ocr', name));
+    if (!folders.some((folder) => existsSync(join(folder, DET))))
+        return 'missing';
+    return folders.some((folder) => RECER.every((f) => existsSync(join(folder, f)))) ? 'present' : 'missing';
+}
+//# sourceMappingURL=ocr-model.js.map

package/lib/runtime/pi-env.js

@@ -0,0 +1,34 @@
+import { cliPackage, maaNodeVersion } from '../pkg.js';
+/**
+ * 本工具**实际兑现**的 PI 能力版本。
+ *
+ * 不写"最新"：这个值给 agent 判特性用，谎报会让它以为没实现的行为存在。
+ * 当前兑现到 v2.7.0：option 四级链 / preset / import / `attach_resource_path` /
+ * option 适用性过滤 / `resource.hash` 完整性校验（v2.6，warn-only）/ pretask（v2.7）。
+ */
+const PI_INTERFACE_VERSION = 'v2.7.0';
+/** 本 CLI 的人类输出固定中文、没有 UI 语言切换——按协议示例的 `zh_cn` 形态如实报。 */
+const PI_CLIENT_LANGUAGE = 'zh_cn';
+/** 生成要注入 agent 子进程的环境变量；返回空对象表示本次没有可注入的项。 */
+export function buildAgentEnv(i) {
+    const env = {
+        PI_INTERFACE_VERSION,
+        PI_CLIENT_NAME: 'maafw-live',
+        PI_CLIENT_VERSION: cliPackage().version,
+        PI_CLIENT_LANGUAGE,
+    };
+    const maafw = maaNodeVersion();
+    if (maafw)
+        env.PI_CLIENT_MAAFW_VERSION = maafw;
+    /* 顶层 version 是**项目**版本（不是 interface_version=2） */
+    if (i.loaded.projectVersion)
+        env.PI_VERSION = i.loaded.projectVersion;
+    const c = i.controllerName ? i.loaded.controllers.find((x) => x.name === i.controllerName) : undefined;
+    if (c && c.raw !== undefined)
+        env.PI_CONTROLLER = JSON.stringify(c.raw);
+    const r = i.resourceName ? i.loaded.resources.find((x) => x.name === i.resourceName) : undefined;
+    if (r && r.raw !== undefined)
+        env.PI_RESOURCE = JSON.stringify(r.raw);
+    return env;
+}
+//# sourceMappingURL=pi-env.js.map