@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/commands/skill.js

@@ -0,0 +1,169 @@
+/**
+ * `maafw-live skill` —— 随包发布的 agent skill 与"装在 agent 里的那一份"如何对齐。
+ *
+ * 为什么不写版本号：skill 讲的是本工具的命令与判据，跟包走才不会各说各话；但写进文件的版本号
+ * 每次发版都要改，而且从仓库装的副本仍然对不上。所以对齐用**比字节**：逐文件 same / different /
+ * missing / extra（extra 是目标目录多出来的文件，例如 skills CLI 放进来的 agent 元数据，不算漂移）。
+ *
+ * 与本仓 docs/ 的分工：docs/ 是字段与协议的唯一出处，skill 只写动线与判据——两者都随包发布，
+ * 区别在消费者（人读 docs，agent 装 skill），因此这里只做"是不是同一份字节"，不解释内容。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXIT, fail } from '../protocol.js';
+const SKILL_NAME = 'maafw-live';
+/** 包内 skill 目录：lib/commands/ → <包根>/skills/maafw-live（本地 checkout 同构） */
+export function skillPayloadDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills', SKILL_NAME);
+}
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+/** 目录内全部文件的相对路径（'/' 分隔、排序稳定），供比对与安装共用。 */
+function listFiles(dir) {
+    const out = [];
+    const walk = (cur) => {
+        for (const e of readdirSync(cur, { withFileTypes: true })) {
+            const abs = join(cur, e.name);
+            if (e.isDirectory())
+                walk(abs);
+            else if (e.isFile())
+                out.push(relative(dir, abs).split(sep).join('/'));
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+/**
+ * 逐文件比对（纯函数，单测直接喂两个目录）。只比字节：任何不同都是 different，
+ * 但在**仅行尾不同**（CRLF ↔ LF）时补一条 note——那不是内容分叉，是工具改写。
+ */
+export function compareSkillTrees(payload, target) {
+    const files = listFiles(payload);
+    const rows = [];
+    for (const rel of files) {
+        const pb = readFileSync(join(payload, ...rel.split('/')));
+        const ta = join(target, ...rel.split('/'));
+        const base = { path: rel, bytes: pb.length, sha256: sha256(pb) };
+        if (!existsSync(ta)) {
+            rows.push({ ...base, status: 'missing' });
+            continue;
+        }
+        const tb = readFileSync(ta);
+        if (pb.equals(tb)) {
+            rows.push({ ...base, status: 'same' });
+            continue;
+        }
+        const eolOnly = pb.toString('utf8').replace(/\r\n/g, '\n') === tb.toString('utf8').replace(/\r\n/g, '\n');
+        rows.push({ ...base, status: 'different', ...(eolOnly ? { note: '仅行尾不同（CRLF/LF）' } : {}) });
+    }
+    for (const rel of listFiles(target)) {
+        if (!files.includes(rel))
+            rows.push({ path: rel, status: 'extra' });
+    }
+    return rows;
+}
+const driftOf = (rows) => rows.some((r) => r.status !== 'same' && r.status !== 'extra');
+function readPayload(dir) {
+    return listFiles(dir).map((rel) => {
+        const buf = readFileSync(join(dir, ...rel.split('/')));
+        return { path: rel, bytes: buf.length, sha256: sha256(buf), text: buf.toString('utf8') };
+    });
+}
+export const skillCommand = {
+    name: 'skill',
+    summary: '随包 skill：看包内副本与文件指纹、比对已装副本（same/different/missing/extra）、字节精确安装',
+    usage: 'maafw-live skill                                包内 skill 位置与文件指纹\n' +
+        '       maafw-live skill --check <dir>                 比对 <dir>/maafw-live 与包内副本（有漂移退出 3）\n' +
+        '       maafw-live skill --install <dir>               把包内副本逐字节写到 <dir>/maafw-live\n' +
+        '       maafw-live skill --print [--format json]       输出包内副本内容（harness 自取）',
+    options: {
+        check: { type: 'string' },
+        install: { type: 'string' },
+        print: { type: 'boolean' },
+        format: { type: 'string' },
+    },
+    async run(ctx) {
+        const payload = skillPayloadDir();
+        if (!existsSync(payload)) {
+            return fail('SKILL_NOT_FOUND', '包内未找到 skill 目录：' + payload, '本版本应随包发布 skills/maafw-live；从仓库运行时确认 skills/ 没有被删', EXIT.ENV);
+        }
+        const files = listFiles(payload);
+        const checkDir = typeof ctx.values.check === 'string' ? ctx.values.check : undefined;
+        if (checkDir !== undefined) {
+            const target = join(checkDir, SKILL_NAME);
+            if (!existsSync(target)) {
+                return fail('SKILL_DIR_NOT_FOUND', '目标目录下没有 ' + SKILL_NAME + ' skill：' + target, '给的是**安装根目录**（里面应当有 ' + SKILL_NAME + '/SKILL.md），例如 --global 装的 ~/.claude/skills', EXIT.ENV);
+            }
+            const rows = compareSkillTrees(payload, target);
+            const drifted = driftOf(rows);
+            const extra = rows.filter((r) => r.status === 'extra');
+            const mark = (s) => s === 'same' ? 'same     ' : (s === 'different' ? 'different' : (s === 'missing' ? 'missing  ' : 'extra    '));
+            const human = [
+                '包内副本 ' + payload,
+                '已装副本 ' + target,
+                ...rows.map((r) => '  ' + mark(r.status) + ' ' + r.path + (r.note ? '（' + r.note + '）' : '')),
+                drifted
+                    ? '结论：有漂移——用 --install <dir> 覆盖，或用 skills CLI 重新安装'
+                    : '结论：逐字节一致' + (extra.length ? '（' + extra.length + ' 个多余文件不计漂移）' : ''),
+            ];
+            return {
+                exitCode: drifted ? EXIT.FINDINGS : EXIT.OK,
+                human,
+                data: { payload, target, drift: drifted, files: rows },
+                ...(drifted ? { warnings: ['skill 与包内副本不一致：已装副本可能对应旧版本 CLI'] } : {}),
+            };
+        }
+        const installDir = typeof ctx.values.install === 'string' ? ctx.values.install : undefined;
+        if (installDir !== undefined) {
+            const target = join(installDir, SKILL_NAME);
+            const written = [];
+            for (const rel of files) {
+                const dst = join(target, ...rel.split('/'));
+                mkdirSync(dirname(dst), { recursive: true });
+                writeFileSync(dst, readFileSync(join(payload, ...rel.split('/'))));
+                written.push(dst);
+            }
+            return {
+                exitCode: EXIT.OK,
+                human: [
+                    '已写出 ' + files.length + ' 个文件 → ' + target,
+                    ...written.map((w) => '  ' + w),
+                    '注：本命令只做逐字节复制；要 agent 自动更新请用 skills CLI（npx skills add …）',
+                ],
+                data: { payload, target, files: written },
+                written,
+            };
+        }
+        if (ctx.values.print === true) {
+            const rows = readPayload(payload);
+            const asJson = ctx.values.format === 'json';
+            if (asJson) {
+                return {
+                    exitCode: EXIT.OK,
+                    data: { payload, files: rows },
+                };
+            }
+            const human = [];
+            for (const f of rows) {
+                human.push('===== ' + f.path + ' =====');
+                human.push(...f.text.replace(/\r\n/g, '\n').replace(/\n$/, '').split('\n'));
+                human.push('');
+            }
+            return { exitCode: EXIT.OK, human, data: { payload, files: rows.map(({ text, ...rest }) => rest) } };
+        }
+        const rows = readPayload(payload);
+        const total = rows.reduce((a, f) => a + f.bytes, 0);
+        return {
+            exitCode: EXIT.OK,
+            human: [
+                '包内 skill：' + payload,
+                '文件 ' + rows.length + ' 个，共 ' + total + ' 字节（skill 不写自己的版本号——对齐用比字节）',
+                ...rows.map((f) => '  ' + f.sha256.slice(0, 12) + '  ' + String(f.bytes).padStart(6) + '  ' + f.path),
+                '下一步：maafw-live skill --check <安装根目录> 比对已装副本；--install <目录> 逐字节写出',
+            ],
+            data: { payload, files: rows.map(({ text, ...rest }) => rest) },
+        };
+    },
+};
+//# sourceMappingURL=skill.js.map

package/lib/commands/timing.js

@@ -0,0 +1,247 @@
+/**
+ * timing：从帧流与节点事件反推 pipeline 的 delay / timeout 建议值。
+ *
+ * 做法：自动开流 → 跑任务（--runs n 次采样）→ 对齐两类时间线——
+ *  - 节点时长（record.nodes）→ 节点级 timeout 建议（P95 × 1.5 余量）
+ *  - 节点完成后的画面稳定时间（完成事件到下一个 stable 事件的时距）→ post-delay /
+ *    wait_freezes 建议；下一节点先于 stable 开始则标"未稳定"（连续动画/识别窗口过紧）。
+ * 分布口径：建议值只取成功 run（失败 run 的时长是提前终止的，对 timeout 建议是误导）；
+ * 单次采样退化为 P50=P95=该值，与历史单次行为逐字段一致。
+ */
+import { EXIT, fail } from '../protocol.js';
+import { computePipelineOverride, appendOverride } from '../interface/index.js';
+import { buildAgentEnv } from '../runtime/pi-env.js';
+import { parseOptionArgs } from '../option-args.js';
+import * as act from '../runtime/actions.js';
+import { withDaemon } from '../runtime/actions.js';
+import { describeSession, ensureSession } from '../runtime/session.js';
+import { CONNECT_OPTIONS, daemonFail, argPath, sessionOptions } from './runtime.js';
+/** 最近邻秩百分位：sorted 升序；n=1 时任意 p 返回该值，n 小时偏保守端（P95 取最大） */
+export function percentile(values, p) {
+    if (!values.length)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx];
+}
+/** 跨 run 聚合（纯函数，单测直断言）：节点统计与建议值都只算成功样本 */
+export function aggregateTiming(samples) {
+    const ok = samples.filter((s) => s.ok);
+    const failed = samples.length - ok.length;
+    const durations = ok.map((s) => s.durationMs);
+    const maxNodeP95 = ok.length ? percentile(ok.map((s) => Math.max(0, ...s.nodes.map((n) => n.ms))), 95) : 0;
+    const settleSamples = ok.map((s) => {
+        const ss = s.nodes.filter((n) => n.settle !== null).map((n) => n.settle);
+        return ss.length ? Math.max(...ss) : null;
+    });
+    const settles = settleSamples.filter((v) => v !== null);
+    const names = [...new Set(ok.flatMap((s) => s.nodes.map((n) => n.name)))];
+    const nodeStats = names.map((name) => {
+        /* 全部出现都算：同名节点 run 内重复执行时，慢的往往是第二次（首跑等动画） */
+        const per = ok.flatMap((s) => s.nodes.filter((n) => n.name === name));
+        const ms = per.map((n) => n.ms);
+        const st = per.filter((n) => n.settle !== null).map((n) => n.settle);
+        return {
+            name,
+            status: per.at(-1)?.status ?? 'unknown',
+            runs: ok.filter((s) => s.nodes.some((n) => n.name === name)).length,
+            occurrences: per.length,
+            msP50: percentile(ms, 50),
+            msP95: percentile(ms, 95),
+            settleP50: st.length ? percentile(st, 50) : null,
+            settleP95: st.length ? percentile(st, 95) : null,
+            settleSamples: st.length,
+            nextBeforeStable: per.some((n) => n.nextBeforeStable),
+        };
+    });
+    return {
+        successful: ok.length, failed,
+        durationP50: percentile(durations, 50),
+        durationP95: percentile(durations, 95),
+        maxNodeP95,
+        maxSettleP95: settles.length ? percentile(settles, 95) : null,
+        nodeStats,
+        suggest: {
+            nodeTimeoutMs: Math.ceil((maxNodeP95 * 1.5) / 100) * 100,
+            taskTimeoutMs: Math.ceil((percentile(durations, 95) * 2) / 1000) * 1000,
+            postDelayMs: settles.length ? Math.ceil((percentile(settles, 95) * 1.2) / 50) * 50 : null,
+        },
+    };
+}
+export const timingCommand = {
+    name: 'timing',
+    summary: '跑任务并反推 timing 建议：节点时长 → timeout，动作后稳定时间 → wait_freezes 兜底参考；--runs n 取 P50/P95 分布',
+    usage: 'maafw-live timing --entry <task> --project <dir> [--timeout <ms>] [--runs <n>] [--preset <name>] [--override <json>]\n' +
+        '       自动开流（帧流与节点事件对齐是分析前提）；单次采样是下界，--runs 3-5 取分布再定稿',
+    options: {
+        ...CONNECT_OPTIONS,
+        entry: { type: 'string' },
+        'resource-dir': { type: 'string' },
+        timeout: { type: 'string' },
+        runs: { type: 'string' },
+        override: { type: 'string' },
+        preset: { type: 'string' },
+        /* 与 run 同一取值通道：timing 测的就是 run 那条路，option 进不去会让
+         * "时长分布"测的是一个根本不该跑的配置（P1-#4）。 */
+        option: { type: 'string', multiple: true },
+    },
+    async run(ctx) {
+        const o = sessionOptions(ctx);
+        const entry = (typeof ctx.values.entry === 'string' ? ctx.values.entry : ctx.positionals[0]) ?? undefined;
+        const resourceDir = argPath(ctx, typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined);
+        if (!entry)
+            return fail('BAD_ARGUMENTS', '缺少入口任务名：--entry <task>', undefined, EXIT.USAGE);
+        if (!o.project && !resourceDir) {
+            return fail('BAD_ARGUMENTS', '要么给 --project <dir>，要么给 --resource-dir <dir>', undefined, EXIT.USAGE);
+        }
+        const timeoutMs = typeof ctx.values.timeout === 'string' ? Number(ctx.values.timeout) : 120000;
+        if (!Number.isFinite(timeoutMs))
+            return fail('BAD_ARGUMENTS', '--timeout 必须是毫秒数', undefined, EXIT.USAGE);
+        const runs = typeof ctx.values.runs === 'string' ? Number(ctx.values.runs) : 1;
+        if (!Number.isInteger(runs) || runs < 1 || runs > 10) {
+            return fail('BAD_ARGUMENTS', '--runs 需为 1-10 的整数（真机动作采样，别当压测跑）', undefined, EXIT.USAGE);
+        }
+        let override = {};
+        if (typeof ctx.values.override === 'string') {
+            try {
+                override = JSON.parse(ctx.values.override);
+            }
+            catch (e) {
+                return fail('BAD_ARGUMENTS', '--override 不是合法 JSON', undefined, EXIT.USAGE);
+            }
+        }
+        /* --option 与 run 同一取值通道（CLI > preset > default_case 由 computePipelineOverride 判） */
+        const parsedOptions = parseOptionArgs(ctx.values.option);
+        if (parsedOptions.error) {
+            return fail('BAD_ARGUMENTS', parsedOptions.error, '例：--option taskOpt=b  --option 章节数.章节号=4', EXIT.USAGE);
+        }
+        try {
+            return await withDaemon(ctx, async (client) => {
+                const s = await ensureSession(client, o);
+                let args;
+                if (o.project) {
+                    const paths = s.plan?.resource?.paths ?? [];
+                    if (!paths.length) {
+                        return fail('RESOURCE_NOT_FOUND', '项目里没有解析出资源路径：检查 interface.json 的 resource[] 声明', undefined, EXIT.FINDINGS);
+                    }
+                    const task = s.plan?.loaded.tasks.find((t) => t.name === entry || t.entry === entry);
+                    const chain = computePipelineOverride({
+                        loaded: s.plan.loaded,
+                        controllerName: s.plan?.controllerName ?? null,
+                        resourceName: s.plan?.resource?.selected ?? null,
+                        taskName: task?.name ?? null,
+                        presetName: typeof ctx.values.preset === 'string' ? ctx.values.preset : null,
+                        ...(Object.keys(parsedOptions.cases).length ? { optionCases: parsedOptions.cases } : {}),
+                        ...(Object.keys(parsedOptions.fields).length ? { optionFields: parsedOptions.fields } : {}),
+                    });
+                    /* 用户 --override 追加到链尾 = 最高优先级：**与 run 共用同一份追加实现**。
+                     * 分层数组交给框架逐层继承；不在这里预合并（层间 type 边界会被摊平毁掉）。 */
+                    appendOverride(chain.override, override);
+                    args = {
+                        resourceDirs: paths, entry: task?.entry ?? entry,
+                        override: chain.override, timeoutMs,
+                        agents: s.plan.loaded.agents.map((a) => ({ exec: a.exec, args: a.args })),
+                        agentCwd: s.plan.loaded.dir ?? undefined,
+                        /* agent 子进程的环境变量声明按"当前 controller/resource 选择"生成——
+                         * 此前 timing 不带 env，agent 拿到的配置与 run 跑的不是同一套（P1-#4）。 */
+                        agentEnv: buildAgentEnv({
+                            loaded: s.plan.loaded,
+                            controllerName: s.plan?.controllerName ?? null,
+                            resourceName: s.plan?.resource?.selected ?? null,
+                        }),
+                    };
+                }
+                else {
+                    args = { resourceDir, entry, override, timeoutMs };
+                }
+                /* 帧流是分析前提：开流 → 跑 n 次 → 停流；每 run 切自己的事件区间对齐。
+                 * 末节点可能把下一 run 开头的 stable 算作自己的稳定点——语义上仍是
+                 * "该节点之后画面何时静默"，可接受。 */
+                await act.streamStart(client, { fps: 8 }).catch(() => null);
+                const samples = [];
+                try {
+                    for (let i = 1; i <= runs; i++) {
+                        const eventsBefore = client.events.events.length;
+                        const r = await act.run(client, args, timeoutMs);
+                        const evs = client.events.events.slice(eventsBefore);
+                        if (r.ok === false || !r.record) {
+                            return fail('TIMING_RUN', '任务没跑起来：' + String(r.error ?? '?'), undefined, EXIT.FINDINGS);
+                        }
+                        const rec = r.record;
+                        /* 时间线对齐：run 类事件带节点名与消息；stable 是画面静默点 */
+                        const runEvs = evs.filter((e) => e.type === 'run' && e.node);
+                        const stables = evs.filter((e) => e.type === 'stable').map((e) => Number(e.t));
+                        const nodes = rec.nodes.map((n) => {
+                            const done = runEvs.filter((e) => e.node === n.name && /Succeeded$/.test(e.msg)).at(-1)
+                                ?? runEvs.filter((e) => e.node === n.name && /Failed$/.test(e.msg)).at(-1);
+                            if (!done)
+                                return { name: n.name, ms: n.ms, status: n.status, settle: null, nextBeforeStable: false };
+                            const nextNode = runEvs.find((e) => e.t > done.t && e.node !== n.name);
+                            const stable = stables.find((t) => t > done.t);
+                            const settle = stable !== undefined ? stable - done.t : null;
+                            return {
+                                name: n.name, ms: n.ms, status: n.status,
+                                settle,
+                                nextBeforeStable: nextNode !== undefined && (stable === undefined || nextNode.t < stable),
+                            };
+                        });
+                        samples.push({ index: i, ok: rec.ok, durationMs: rec.durationMs, nodes, events: evs.length });
+                    }
+                }
+                finally {
+                    await act.streamStop(client).catch(() => null);
+                }
+                const agg = aggregateTiming(samples);
+                if (!agg.successful) {
+                    return fail('TIMING_RUN', runs + ' 次采样全部未成功——没有可用于建议的成功样本', undefined, EXIT.FINDINGS);
+                }
+                const unsettled = agg.nodeStats.filter((n) => n.nextBeforeStable);
+                const last = samples.at(-1);
+                const human = [
+                    ...describeSession(s, ctx.flags.verbose),
+                    'timing 采样 x' + runs + '（' + agg.successful + ' 成功' + (agg.failed ? ' / ' + agg.failed + ' 失败' : '') + '）：',
+                    ...samples.map((smp) => '  #' + smp.index + ' ' + (smp.ok ? '成功' : '失败（不计入建议）') + '  ' + smp.durationMs + 'ms  ' + smp.nodes.length + ' 节点'),
+                    '节点时长分布（成功样本，P50 / P95）：',
+                    ...agg.nodeStats.map((n) => '  [' + n.status + '] ' + n.name + '  ' + n.msP50 + ' / ' + n.msP95 + 'ms' +
+                        (n.settleP50 !== null ? '  稳定 +' + n.settleP50 + ' / +' + n.settleP95 + 'ms' : '') +
+                        (n.occurrences > n.runs ? '  （重复执行 ' + n.occurrences + ' 次 / ' + n.runs + ' run——重试或 Next 环）' : '') +
+                        (n.runs < agg.successful ? '  （' + n.runs + '/' + agg.successful + ' run 出现——分支或跳过）' : '') +
+                        (n.nextBeforeStable ? '  （下一节点先于画面稳定开始——识别窗口紧或连续动画）' : '')),
+                    '建议（P95 × 余量，n=' + agg.successful + ' 成功采样；界面切换优先用 next 等待节点表达，delay 尽量保持缺省）：',
+                    '  节点 timeout ≥ ' + agg.suggest.nodeTimeoutMs + 'ms（各 run 最长节点 P95 ' + agg.maxNodeP95 + 'ms × 1.5）',
+                    '  任务 timeout ≥ ' + agg.suggest.taskTimeoutMs + 'ms（任务时长 P95 ' + agg.durationP95 + 'ms × 2）',
+                    agg.suggest.postDelayMs !== null
+                        ? '  动作后稳定参考 ' + agg.suggest.postDelayMs + 'ms（各 run 最长稳定 P95 ' + agg.maxSettleP95 + 'ms × 1.2）——优先由 next 等待节点的 timeout 覆盖该时长；确需兜底用 post_wait_freezes，post_delay 是最后手段'
+                        : '  动作后稳定时间：无 stable 事件可参考（画面持续变化或流太短）',
+                ];
+                if (agg.failed)
+                    human.push('  注意：' + agg.failed + ' 个失败 run 未计入建议；失败原因与时长见 data.runs');
+                if (unsettled.length) {
+                    human.push('  注意：' + unsettled.map((n) => n.name).join(' , ') + ' 未等画面稳定就进入下一节点');
+                }
+                return {
+                    exitCode: EXIT.OK,
+                    human,
+                    data: {
+                        runs: samples, distribution: agg, suggest: agg.suggest,
+                        /* 兼容字段：单次消费方读 record / nodes 的形状不变 */
+                        record: { ok: last.ok, durationMs: last.durationMs, nodes: last.nodes },
+                        nodes: last.nodes,
+                        sampledEvents: samples.reduce((a, smp) => a + smp.events, 0),
+                    },
+                    warnings: [
+                        ...(agg.failed ? [agg.failed + ' 个失败 run 未计入建议'] : []),
+                        ...samples.filter((smp) => !smp.ok).map((smp) => 'run #' + smp.index + ' 未成功——该样本已排除'),
+                        ...(unsettled.length ? [unsettled.length + ' 个节点未等画面稳定即进入下一节点：' + unsettled.map((n) => n.name).join(' , ')] : []),
+                        ...(runs === 1 ? ['单次采样=下界：加 --runs 3-5 取分布再定稿'] : []),
+                    ],
+                };
+            });
+        }
+        catch (e) {
+            return daemonFail(e);
+        }
+    },
+};
+export const TIMING_COMMANDS = [timingCommand];
+//# sourceMappingURL=timing.js.map

package/lib/commands/version.js

@@ -0,0 +1,66 @@
+/** `maafw-live version` —— CLI 与运行环境版本。技能用它做版本对齐；`--check` 对 registry 查有没有新版。 */
+import { EXIT, fail } from '../protocol.js';
+import { cliPackage } from '../pkg.js';
+import { compareVersions, fetchLatest, readState, shouldCheck, updateCheckDisabled, writeState, } from '../update-check.js';
+export const versionCommand = {
+    name: 'version',
+    summary: '打印 maafw-live CLI 及依赖的版本；--check 顺带对 registry 查有没有新版',
+    usage: 'maafw-live version [--check]',
+    options: { check: { type: 'boolean' } },
+    async run(ctx) {
+        const pkg = cliPackage();
+        const human = [
+            `${pkg.name} ${pkg.version}`,
+            // 装的是带 scope 的包名，敲的是裸名——同一个词的两种形态，这里显式给出敲的那个
+            `  command    maafw-live`,
+            `  node       ${process.version}`,
+            `  platform   ${process.platform} ${process.arch}`,
+        ];
+        const data = {
+            name: pkg.name,
+            version: pkg.version,
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        };
+        const explicit = ctx.values.check === true;
+        /* 显式请求：不受 TTY/限频约束，查不到要如实说。自动路径：只在交互终端、限频、失败静默。 */
+        const auto = !explicit && !updateCheckDisabled() && process.stdout.isTTY === true;
+        if (explicit || auto) {
+            let latest = auto ? readState()?.latest ?? null : null;
+            let fresh = false;
+            const cached = readState();
+            if (explicit || shouldCheck(cached, Date.now())) {
+                const fetched = await fetchLatest(pkg.name);
+                if (fetched) {
+                    latest = fetched;
+                    writeState({ checkedAt: Date.now(), latest: fetched });
+                    fresh = true;
+                }
+                else if (explicit) {
+                    return fail('UPDATE_CHECK_FAILED', '查询 registry 失败（离线 / 代理 / registry 抖动）', '加 --check 才需要联网；不带它 version 完全离线可用', EXIT.ENV);
+                }
+            }
+            else if (cached) {
+                latest = cached.latest;
+            }
+            if (latest) {
+                const cmp = compareVersions(latest, pkg.version);
+                data.latest = latest;
+                data.updateAvailable = cmp > 0;
+                data.source = fresh ? 'registry' : 'cache';
+                if (cmp > 0) {
+                    human.push(`  新版       ${latest}（当前 ${pkg.version}）`, `  升级       npm install --global ${pkg.name}@latest`);
+                    /* 自动提示不改退出码：版本旧不是"这次调用发现的问题" */
+                    return { exitCode: explicit ? EXIT.FINDINGS : EXIT.OK, human, data };
+                }
+                human.push(`  最新       ${latest}（已是最新）`);
+            }
+            else if (explicit) {
+                human.push('  最新       查询不到（registry 不可达）');
+            }
+        }
+        return { exitCode: EXIT.OK, human, data };
+    },
+};
+//# sourceMappingURL=version.js.map