@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/protocol.js

@@ -0,0 +1,94 @@
+/** 信封结构版本。字段增删时递增，消费方可据此拒绝不认识的形状。 */
+export const SCHEMA_VERSION = 1;
+/**
+ * 退出码语义。
+ *
+ * 关键区分：`FAIL` 是「命令没跑成」，`FINDINGS` 是「跑成了，但发现了问题」。
+ * 技能与 CI 必须能分开这两种情况——reco 识别未命中不是执行失败，
+ * 但也不该返回 0 让调用方以为一切正常。
+ */
+export const EXIT = {
+    /** 命令正常完成，未发现问题 */
+    OK: 0,
+    /** 命令自身失败（未预期异常、IO 错误） */
+    FAIL: 1,
+    /** 参数 / 用法错误 */
+    USAGE: 2,
+    /** 命令正常跑完，但发现了问题（reco 未命中、run 调用级失败、观测类命令的警告等） */
+    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 {
+        schemaVersion: SCHEMA_VERSION,
+        command,
+        ok: r.exitCode === EXIT.OK || r.exitCode === EXIT.FINDINGS,
+        exitCode: r.exitCode,
+        root: r.root ?? null,
+        written: r.written ?? [],
+        removed: r.removed ?? [],
+        skipped: r.skipped ?? [],
+        pending: r.pending ?? [],
+        suggestedCommands: r.suggestedCommands ?? [],
+        warnings: r.warnings ?? [],
+        data: r.data ?? null,
+        error: r.error ?? null,
+    };
+}
+const ANSI = {
+    reset: '\u001b[0m',
+    dim: '\u001b[2m',
+    red: '\u001b[31m',
+    yellow: '\u001b[33m',
+    green: '\u001b[32m',
+    cyan: '\u001b[36m',
+};
+function paint(text, code, on) {
+    return on ? code + text + ANSI.reset : text;
+}
+/**
+ * 输出命令结果。
+ *
+ * --json 时只输出信封（stdout 保持纯 JSON，可被管道解析）；
+ * 否则输出命令自己的 human 渲染 + 警告 + 建议命令。
+ * 错误与警告一律走 stderr，避免污染 stdout 的 JSON。
+ */
+export function emit(command, r, o) {
+    if (o.json) {
+        process.stdout.write(JSON.stringify(toEnvelope(command, r), null, 2) + '\n');
+        return;
+    }
+    for (const line of r.human ?? [])
+        process.stdout.write(line + '\n');
+    for (const w of r.warnings ?? []) {
+        process.stderr.write(paint('warning: ', ANSI.yellow, o.color) + w + '\n');
+    }
+    if (r.error) {
+        process.stderr.write(paint('error: ', ANSI.red, o.color) + r.error.message +
+            paint(' [' + r.error.code + ']', ANSI.dim, o.color) + '\n');
+        if (r.error.hint) {
+            process.stderr.write(paint('  hint: ' + r.error.hint, ANSI.dim, o.color) + '\n');
+        }
+    }
+    if (r.pending?.length) {
+        process.stdout.write('\n待办：\n');
+        for (const p of r.pending)
+            process.stdout.write('  - ' + p + '\n');
+    }
+    if (r.suggestedCommands?.length) {
+        process.stdout.write('\n建议下一步：\n');
+        for (const c of r.suggestedCommands) {
+            process.stdout.write('  ' + paint(c, ANSI.cyan, o.color) + '\n');
+        }
+    }
+}
+/** 失败结果的快捷构造 */
+export function fail(code, message, hint, exitCode = EXIT.FAIL) {
+    return { exitCode, error: { code, message, ...(hint ? { hint } : {}) } };
+}
+//# sourceMappingURL=protocol.js.map

package/lib/runtime/actions.js

@@ -0,0 +1,225 @@
+/**
+ * 运行时动作层：把 daemon 的 JSON 行命令包成有类型、有超时、有默认值的函数。
+ *
+ * 命令（`src/commands/*`）与 `maafw-live repl` 都只调这一层——同一条链路上不允许出现第二份
+ * 参数拼装逻辑，否则 CLI 与 REPL 会各长出一套规则。项目（interface.json）驱动的连接与运行
+ * 也在这里收口，避免"手动连 vs 项目连"两条路径对资源与坐标系的解释分叉。
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { rmSync } from 'node:fs';
+import { computePipelineOverride, loadInterface, appendOverride, planController, resolveResourcePaths, } from '../interface/index.js';
+import { spawnDaemon } from '../client/daemon.js';
+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);
+    }
+    finally {
+        client.close();
+    }
+}
+/* ─────────────────────────── 直通命令 ─────────────────────────── */
+export const probe = (c) => c.call('probe', {}, 30000);
+export const deviceList = (c, kind = 'all') => c.call('device_list', { kind }, 40000);
+export const connect = (c, args) => c.call('connect', args, 40000);
+export const disconnect = (c) => c.call('disconnect', {}, 20000);
+export const screencap = (c, out) => c.call('screencap', out ? { out } : {}, 30000);
+/**
+ * 一次性命令的"先产生一次观测"：截一帧进 daemon 的 L0，然后**把临时文件删掉**。
+ *
+ * 为什么需要这一帧：L0 是进程态，一次性命令（`crop` / `annotate` / `color`）每次 spawn 自己的
+ * daemon，不先截一帧就没有原图可用。为什么必须删：daemon 收帧时就把像素读进缓冲了，
+ * 落盘那份只为喂它一次——不删就是每跑一次在系统临时目录留一张 720p 截图（实测攒到 42 张 / 54MB）。
+ * 失败不抛：没有观测时命令自己会报"先 screencap / stream"这类可行动的错。
+ */
+export async function seedObservation(c, prefix) {
+    const file = join(tmpdir(), 'maafw_' + prefix + '_' + Date.now() + '.png');
+    try {
+        await screencap(c, file).catch(() => null);
+    }
+    finally {
+        try {
+            rmSync(file, { force: true });
+        }
+        catch { /* ignore */ }
+    }
+}
+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);
+/** 两帧在若干 ROI 上的差分：回答"这一步改了哪几格"。 */
+export const frameDiff = (c, args) => c.call('frame_diff', args, 30000);
+export const colorProbe = (c, args) => c.call('color_probe', args, 15000);
+export const tplCrop = (c, args) => c.call('tpl_crop', args, 240000);
+export const annotate = (c, args) => c.call('annotate', args, 120000);
+export const calibrate = (c, args = {}) => c.call('calibrate', args, 120000);
+export const runStop = (c) => c.call('run_stop', {}, 10000);
+export const l0Status = (c) => c.call('l0_status', {}, 10000);
+export const kfPromote = (c, args) => c.call('kf_promote', args, 30000);
+export function run(c, args, timeoutMs = 30000) {
+    /* timeoutMs=0 = 不自动停（停止权交调用方）：客户端调用超时放到 24h 档。
+     * 不用 Infinity——Node 的 setTimeout 上限 2^31-1，超限会立即触发，反而误杀。 */
+    const t = Number(timeoutMs);
+    const budget = t === 0 ? 86400000 : Math.min(86400000, Math.max(500, t || 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);
+/** 截图能力探测（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];
+    const t = String(c?.type);
+    if (t === 'Adb')
+        return 'adb';
+    if (t === 'Win32' || t === 'Gamepad')
+        return 'win32';
+    return null;
+}
+/**
+ * 载入项目 → 扫设备 → 规划控制器 → 解析资源路径。
+ *
+ * 为什么不猜设备：interface.json 的 controller[] 已经声明了 Adb/Win32、窗口类名与标题正则、
+ * 截图与输入方法、以及识别缩放（display_short_side）——猜错不只是连错窗口，还会把 roi 与
+ * 模板的坐标系一起猜错。interface.json 的读法只有 src/interface/ 一份，别处不许再解析一遍。
+ */
+export async function planProject(c, dir, overrides = {}) {
+    const loaded = loadInterface(dir);
+    if (!loaded.file) {
+        return { loaded, plan: null, controllerName: null, resource: null, error: loaded.problems[0]?.message ?? '未找到 interface.json' };
+    }
+    const controllerName = overrides.controller ?? loaded.controllers[0]?.name ?? null;
+    const kind = deviceKindFor(loaded, controllerName);
+    let devices = [];
+    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 },
+        gamepad: { hwnd: overrides.gamepadHwnd ?? null },
+        adb: { address: overrides.address ?? null },
+        manualTarget: overrides.manualTarget ?? null,
+    }, devices);
+    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/keyframes.js

@@ -0,0 +1,73 @@
+/**
+ * 关键帧库的离线读侧：list / resolve 不依赖 daemon 存活（契约 §4.1）。
+ *
+ * manifest 格式与 daemon/framed.mjs 的写入侧一一对应：
+ *   { schema:1, libraryId, next, frames:[{ id, file, sha256, session, capturedAt,
+ *     captureSeq, ctrlW, ctrlH, smallW, smallH, scale, source, note }] }
+ * 写侧（升格）在 daemon；本模块只读，两个消费方（CLI kf、REPL kf）共用，不出现第二份解析。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const KF_SCHEMA = 1;
+export function defaultFramesDir() {
+    return join(homedir(), '.maafw-live', 'frames');
+}
+/** 读 manifest。坏文件/未知 schema 明确报错，不默认为当前版。 */
+export function loadManifest(dir) {
+    const file = join(dir, 'manifest.json');
+    if (!existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        return { error: 'manifest.json 损坏（非合法 JSON）：' + String(e.message) };
+    }
+    const m = raw;
+    if (!m || typeof m !== 'object' || !Array.isArray(m.frames)) {
+        return { error: 'manifest.json 结构不符（缺 frames 数组）' };
+    }
+    if (m.schema !== KF_SCHEMA) {
+        return { error: 'manifest schema=' + String(m.schema) + ' 不被当前版本支持（认识：' + KF_SCHEMA + '）' };
+    }
+    return { manifest: m };
+}
+/** 按完整 ID 帧解析：available 时给出经过完整性校验的路径；missing/corrupt/unsupported 各自可诊断。 */
+export function resolveFrame(dir, id) {
+    /* 非字符串 id（缺字段、拼错的调用方）也走"不可复核"这条路，而不是抛 TypeError——
+     * 解析函数的契约是**如实报状态**，不该给调用方一个异常。 */
+    if (typeof id !== 'string' || !id.startsWith('kf:')) {
+        return { status: 'missing', reason: '要完整 ID：kf:<库UUID>:<序号>（裸序号只可作展示简称，不能跨库引用）' };
+    }
+    const { manifest, error } = loadManifest(dir);
+    if (error)
+        return { status: 'unsupported', reason: error };
+    if (!manifest)
+        return { status: 'missing', reason: '库内无 manifest（本机不可复核，不代表历史从未观测）' };
+    const rec = manifest.frames.find((f) => f.id === id);
+    if (!rec)
+        return { status: 'missing', reason: 'manifest 无此 ID 记录' };
+    const abs = join(dir, ...rec.file.split('/'));
+    if (!existsSync(abs))
+        return { status: 'missing', record: rec, reason: 'L0 文件丢失' };
+    let sha = '';
+    try {
+        sha = createHash('sha256').update(readFileSync(abs)).digest('hex');
+    }
+    catch (e) {
+        return { status: 'corrupt', record: rec, reason: '读取失败：' + String(e.message) };
+    }
+    if (sha !== rec.sha256)
+        return { status: 'corrupt', record: rec, reason: 'sha256 不匹配（文件损坏或被改）' };
+    return { status: 'available', record: rec, path: abs };
+}
+/** list 用：一行人类可读摘要（与 --json 的 data 各自完整，不共用裁剪）。 */
+export function describeRecord(r) {
+    const dt = r.capturedAt ? r.capturedAt.replace('T', ' ').replace(/\.\d+Z$/, 'Z') : '?';
+    return r.id + '  seq=' + r.captureSeq + '  ' + r.ctrlW + 'x' + r.ctrlH + '  ' + dt + '  [' + r.source + ']' +
+        (r.note ? '  ' + r.note : '');
+}
+//# sourceMappingURL=keyframes.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