@windsland52/maafw-live 0.0.0-stage → 0.4.0

package/lib/commands/dispatch.js

@@ -0,0 +1,121 @@
+/**
+ * 命令分发的唯一实现：argv → CommandResult。
+ *
+ * 为什么单列一个模块：一次性 CLI（index.ts）与命名会话常驻进程（repl --session-serve）
+ * 必须把 argv 走**同一条**解析→闸门→run 路径——会话里再写一份 switch 就必然漂移
+ *（设计审查 P0-3：REPL 的 connect project 选不了 controller、run 不吃 --option，就是这么来的）。
+ *
+ * 与入口（index.ts main）的分工：这里只做"argv 落到哪个命令、给它什么 ctx、拿回什么结果"；
+ * 顶层 help/version/建议、--session 转发、emit 输出是入口的事，不在这里。
+ */
+import { parseArgs } from 'node:util';
+import { statSync } from 'node:fs';
+import { GLOBAL_OPTIONS, readGlobalFlags } from '../flags.js';
+import { EXIT, fail } from '../protocol.js';
+/* 命令注册表延迟 import：commands/index 会把全部命令模块求值一遍（含 repl.ts——
+ * 而 repl.ts 又 import 本模块）。顶层静态 import 就是"谁先进来谁炸"的循环
+ * （Cannot access before initialization）。函数体里第一次调用时才加载注册表，
+ * 此时模块图早已稳定；同一条 import 只付一次。 */
+let registryPromise = null;
+function registry() {
+    registryPromise ??= import('./index.js');
+    return registryPromise;
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * 分发一条 argv（含命令名，即 `argv[0]` 是命令名）。
+ * 永不抛异常：BAD_ARGUMENTS / UNKNOWN_COMMAND / SESSION_REQUIRED / UNEXPECTED 都收敛成
+ * CommandResult——会话常驻进程不能因为一条坏命令挂掉。
+ */
+export async function dispatchArgv(argv, env) {
+    const { findCommand, suggestCommand } = await registry();
+    const head = argv[0] ?? '';
+    const cmd = findCommand(head);
+    if (!cmd) {
+        const suggestion = suggestCommand(head);
+        return {
+            cmd: null,
+            flags: readGlobalFlags({}, env.cwd),
+            result: {
+                exitCode: EXIT.USAGE,
+                error: {
+                    code: 'UNKNOWN_COMMAND',
+                    message: `未知命令：${head}`,
+                    ...(suggestion ? { hint: `是否想执行 ${suggestion}？` } : {}),
+                },
+            },
+        };
+    }
+    const options = { ...GLOBAL_OPTIONS, ...(cmd.options ?? {}) };
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv.slice(1),
+            options,
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (e) {
+        return { cmd, flags: readGlobalFlags({}, env.cwd), result: fail('BAD_ARGUMENTS', message(e), `用法：${cmd.usage}`, EXIT.USAGE) };
+    }
+    const flags = readGlobalFlags(parsed.values, env.cwd);
+    /* 预留旗标没有消费者：传了就退 2 而不是静默吞掉——"以为在试跑其实已经落盘"
+     * 是 agent 最坏的失败模式。`--limit`/`--verbose` 例外：events 自己消费同名列；
+     * verbose 已接 describeSession 的 note 行门控。 */
+    const unimpl = [];
+    if (flags.dryRun)
+        unimpl.push('--dry-run');
+    if (parsed.values.limit !== undefined && !(cmd.options && 'limit' in cmd.options))
+        unimpl.push('--limit');
+    if (unimpl.length > 0) {
+        return {
+            cmd, flags,
+            result: fail('FLAG_NOT_IMPLEMENTED', `未实现的旗标：${unimpl.join(' ')}（接受但不生效是最坏的失败模式，所以直接报错）`, '要"只校验不落盘"用 validate；要截断输出用命令自己的分页参数', EXIT.USAGE),
+        };
+    }
+    if (flags.help) {
+        /* usage.ts 也 import commands/index（顶层 usage 列表）：同一条环，同样延迟到
+         * 真用到才求值（只有 --help 才需要）。 */
+        const { commandUsage } = await import('../usage.js');
+        return { cmd, flags, result: { exitCode: EXIT.OK, human: commandUsage(cmd) } };
+    }
+    const ctx = {
+        positionals: parsed.positionals,
+        values: parsed.values,
+        flags,
+        cwd: env.cwd,
+        ...(env.client ? { client: env.client } : {}),
+    };
+    /* requiresSession 闸门：一次性形态（env.client 为空）下跑的是刚起的空 daemon，
+     * 这类命令只能给出假信号（stop 停空 daemon 回 ok、frame get 恒 NO_FRAME）——
+     * 退 2 + 指路，比"看起来成功了"安全得多。会话内（env.client 已注入）天然放行。 */
+    const needsSession = !env.client &&
+        (typeof cmd.requiresSession === 'function' ? cmd.requiresSession(ctx) : cmd.requiresSession === true);
+    if (needsSession) {
+        return {
+            cmd, flags,
+            result: fail('SESSION_REQUIRED', cmd.name + ' 需要会话态（一次性命令的 daemon 用完即关，这条命令依赖的会话内状态不存在）', '先起会话：maafw-live repl --session <name> --project <dir>，然后 ' + cmd.name + ' --session <name>（或直接在 REPL 里用）', EXIT.USAGE),
+        };
+    }
+    try {
+        return { cmd, flags, result: await cmd.run(ctx) };
+    }
+    catch (e) {
+        return {
+            cmd, flags,
+            result: fail('UNEXPECTED', message(e), '这是未预期异常，请把 --json 输出一并反馈', EXIT.FAIL),
+        };
+    }
+}
+export function isDirectory(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/lib/commands/env.js

@@ -0,0 +1,409 @@
+/**
+ * `maafw-live env` —— 环境与能力探针。
+ *
+ * 这是整个 CLI 的前置命令：技能在动手前先问它「现在有什么」，而不是各自写一遍检测。
+ * 因此它有一条硬要求：**它本身永远不能因为环境残缺而失败**。缺 adb、缺 python、
+ * 缺框架源码都是「探测结果」，不是错误。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXIT } from '../protocol.js';
+import { firstLine, run } from '../exec.js';
+import { loadInterface, resolveResourcePaths } from '../interface/index.js';
+/** 向上找 Maa 项目根：interface.json / maa-project.json 是可靠边界 */
+function findProjectRoot(start) {
+    let dir = resolve(start);
+    for (let i = 0; i < 12; i++) {
+        if (existsSync(join(dir, 'interface.json')) || existsSync(join(dir, 'maa-project.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/** 从 interface.json 的 resource 声明推导 pipeline 目录；找不到时退回常见目录 */
+function pipelineDirs(root) {
+    const out = new Set();
+    for (const p of resolveResourcePaths(loadInterface(root)).paths) {
+        const dir = join(p, 'pipeline');
+        if (existsSync(dir))
+            out.add(dir);
+    }
+    for (const f of ['resource/base/pipeline', 'resource/pipeline', 'pipeline']) {
+        const dir = join(root, f);
+        if (existsSync(dir))
+            out.add(dir);
+    }
+    return [...out];
+}
+/** 解析 @maaxyz/maa-node。它可能没导出 package.json，故从入口向上找包根 */
+function resolveMaaNode(from) {
+    try {
+        const req = createRequire(join(from, '__maa_cli_probe__.js'));
+        const entry = req.resolve('@maaxyz/maa-node');
+        let dir = dirname(entry);
+        for (let i = 0; i < 6; i++) {
+            const pkgPath = join(dir, 'package.json');
+            if (existsSync(pkgPath)) {
+                const j = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                return { version: j.version ?? 'unknown', path: dir };
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        /* 未安装 */
+    }
+    return null;
+}
+/** 本包自身所在目录：把运行时绑定当依赖解析，而不是指望调用方目录里恰好有它 */
+function selfDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+/**
+ * 精确版本判定：`5.14.2` / `=5.14.2` / `==5.14.2` / `v5.14.2`，以及 PEP 440 的
+ * 预发布/后发布后缀（`5.15.0a1`、`5.15.0b1`、`5.15.0rc1`、`5.15.0.dev1`、`5.15.0.post1`）
+ * 才算「就是这个版本」。
+ *
+ * 后缀不改变「唯一确定」这一点：Python 绑定发布的正是 `MaaFW==5.15.0b1` 这种写法，
+ * 判成范围就等于对真正要防的那个不一致视而不见。
+ *
+ * `^5.14.2`、`>=5.14` 这类范围要 semver 解析才能判等，本工具不替 npm/pip 做这件事：
+ * 判错了比不判更坏，调用方会据此去改依赖。
+ */
+function exactVersion(spec) {
+    const m = /^(?:==|=)?\s*v?(\d+\.\d+\.\d+(?:[-+.][0-9A-Za-z.-]+|(?:a|b|c|rc|alpha|beta|pre|preview|post|dev)\d*)?)$/i.exec(spec.trim());
+    return m ? m[1] : null;
+}
+/**
+ * qualifier 归一化：同一个 pre-release 在两个生态里写法不同，比较前先落到同一形态。
+ *   `-beta.1` / `beta.1` / `beta1` / `b1` → `b1`；`alpha` → `a`；`rc` / `pre` / `preview` → `rc`；
+ *   `.dev1` → `dev1`；`.post1` → `post1`；没有后缀 → 空串（正式版）。
+ * 认不出的后缀原样保留：宁可把它判成不一致，也不要凭猜测把两个不相干的后缀当同一个。
+ */
+export function normalizeQualifier(qualifier) {
+    const body = qualifier.trim().toLowerCase().replace(/^[-+_.]/, '');
+    if (body === '')
+        return '';
+    const m = /^(alpha|beta|pre|preview|rc|a|b|c|post|dev)\.?(\d*)$/.exec(body);
+    if (!m)
+        return body;
+    const kind = m[1];
+    const num = m[2] ?? '';
+    const canon = kind === 'alpha' ? 'a'
+        : kind === 'beta' ? 'b'
+            : kind === 'pre' || kind === 'preview' ? 'rc'
+                : kind;
+    return canon + num;
+}
+/**
+ * 把精确版本拆成 release 线与**归一化后的** qualifier：`5.15.0b1` → `5.15.0` + `b1`，
+ * `5.15.0-beta.1` 同样落到 `5.15.0` + `b1`。
+ *
+ * 对账要分别看两段：release 线不同是换了个版本；release 相同而 qualifier 不同是**同一条线上的
+ * 另一份构建**（正式版 vs 预发布、b1 vs rc1 都是）。只比字符串会把两种拼写当不一致；
+ * 只比 release 又会把正式版与预发布报成一致——两头都错。
+ */
+export function splitRelease(version) {
+    const m = /^(\d+\.\d+\.\d+)(.*)$/.exec(version.trim());
+    return m ? { release: m[1], qualifier: normalizeQualifier(m[2] ?? '') } : null;
+}
+function pinFromPackageJson(root) {
+    const file = join(root, 'package.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        const j = JSON.parse(readFileSync(file, 'utf8'));
+        for (const field of ['dependencies', 'devDependencies']) {
+            const group = j[field];
+            if (!group || typeof group !== 'object')
+                continue;
+            const v = group['@maaxyz/maa-node'];
+            if (typeof v === 'string' && v.trim()) {
+                return { source: 'package.json', declared: v.trim(), exact: exactVersion(v) };
+            }
+        }
+    }
+    catch {
+        /* package.json 坏了就当这个源没有 pin：探针不因环境残缺而失败 */
+    }
+    return null;
+}
+function pinFromRequirements(root) {
+    const file = join(root, 'requirements.txt');
+    if (!existsSync(file))
+        return null;
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    for (const raw of text.split(/\r?\n/)) {
+        /* 注释与 environment marker 都是环境噪音，只看「包名 + 版本声明」这一截。
+           PyPI 上的绑定包名是 `MaaFW`，老项目写成 `maa`，两种都是同一个包，大小写不敏感；
+           负向前瞻保证只认独立的包名：maa-evidence-kit、maa_x、maafw2 是别的包。 */
+        const body = (raw.split('#')[0] ?? '').split(';')[0].trim();
+        const m = /^(?:maafw|maa)(?![\w.-])(?:\[[^\]]*\])?\s*(===|==|>=|<=|~=|!=|>|<|=)?\s*([^\s;#]*)$/i.exec(body);
+        if (!m)
+            continue;
+        return { source: 'requirements.txt', declared: body, exact: exactVersion((m[1] ?? '') + (m[2] ?? '')) };
+    }
+    return null;
+}
+function readMaaNodePin(root) {
+    const pkg = pinFromPackageJson(root);
+    const req = pinFromRequirements(root);
+    /* 两处都读：范围声明回答不了「跑的是不是同一版」这个等式，只能回答「落没落在区间里」，
+       精确声明才能。所以按 package.json 精确 → requirements.txt 精确 → package.json 范围 →
+       requirements.txt 范围取第一个；见到 package.json 的任何声明就收工，会把另一处的精确 pin
+       顶掉，而不一致正是靠那个精确 pin 才发现的。 */
+    for (const candidate of [pkg?.exact ? pkg : null, req?.exact ? req : null, pkg, req]) {
+        if (candidate)
+            return candidate;
+    }
+    /* 两个声明源都拿不到才记 uv.lock：它只说明「求解过」，不产生 warning */
+    return existsSync(join(root, 'uv.lock')) ? { source: 'uv.lock', declared: '', exact: null } : null;
+}
+/** Windows 的路径大小写不敏感：同一份依赖不该因为盘符/目录大小写而被报成两份 */
+function samePath(a, b) {
+    const na = resolve(a);
+    const nb = resolve(b);
+    return process.platform === 'win32' ? na.toLowerCase() === nb.toLowerCase() : na === nb;
+}
+/**
+ * 取 checkout 的 schema 快照版本。
+ *
+ * checkout 的版本快照用 git describe 取；取不到就是空串——探针不因环境残缺而失败。
+ */
+async function checkoutVersion(checkout, gitBin) {
+    const r = await run(gitBin, ['-C', checkout, 'describe', '--tags'], { timeout: 5000 });
+    return r.ok ? firstLine(r.stdout) : '';
+}
+function mark(status) {
+    return status === 'ok' ? '[ ok ]' : status === 'warn' ? '[warn]' : '[ -- ]';
+}
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+export const envCommand = {
+    name: 'env',
+    summary: '探测环境与能力：项目、运行时绑定、外部工具（框架源码对账见 --checkout）',
+    usage: 'maafw-live env [--checkout <MaaFramework 源码目录>] [--git <bin>] [--deep]',
+    options: {
+        checkout: { type: 'string' },
+        maafw: { type: 'string' }, // 兼容别名：等价于 --checkout
+        git: { type: 'string' },
+        deep: { type: 'boolean' },
+    },
+    async run(ctx) {
+        const cwd = ctx.cwd;
+        /* 框架源码只服务于「版本对账」这一件事，只有框架开发与静态校验才需要它——写 Maa 应用的
+           人不该被要求 clone MaaFramework，所以不传就完全不出现这一项。--maafw 保留为兼容别名。 */
+        const maafw = String(ctx.values.checkout ?? ctx.values.maafw ?? process.env.MAAFW_CHECKOUT ?? process.env.MAAFW_DIR ?? '');
+        const gitBin = String(ctx.values.git ?? 'git');
+        const deep = ctx.values.deep === true;
+        const projectRoot = findProjectRoot(cwd);
+        const dirs = projectRoot ? pipelineDirs(projectRoot) : [];
+        /* 运行时绑定是本包自己的依赖：self 才是 CLI 真正会 require 到的那份。
+           cwd 的副本只用来对照「项目可能 pin 了别的版本」，它不决定本 CLI 加载什么。 */
+        const self = resolveMaaNode(selfDir());
+        const cwdCopy = resolveMaaNode(cwd);
+        const [checkoutVer, gitV, adbV, pyV] = await Promise.all([
+            existsSync(maafw) ? checkoutVersion(maafw, gitBin) : Promise.resolve(''),
+            run(gitBin, ['--version'], { timeout: 5000 }),
+            run('adb', ['version'], { timeout: 5000 }),
+            run('python', ['--version'], { timeout: 5000 }),
+        ]);
+        const items = [];
+        items.push({
+            key: 'runtime',
+            status: 'ok',
+            detail: `node ${process.version} · ${process.platform} ${process.arch}`,
+        });
+        items.push({
+            key: 'cwd',
+            status: 'ok',
+            detail: cwd,
+        });
+        items.push({
+            key: 'project',
+            status: projectRoot ? 'ok' : 'warn',
+            detail: projectRoot
+                ? `${projectRoot}${dirs.length ? '  (pipeline: ' + dirs.join(', ') + ')' : '  (未发现 pipeline 目录)'}`
+                : '未找到 interface.json / maa-project.json（当前目录不在 Maa 项目内）',
+        });
+        items.push({
+            key: 'maa-node',
+            status: self ? 'ok' : 'missing',
+            detail: self ? `${self.version}  (${self.path})` : '未安装（运行时命令不可用）',
+        });
+        /* 并列而不是覆盖：全局安装时 cwd 的那份不会被加载，报成同一个版本会误导排查 */
+        if (cwdCopy && (!self || !samePath(self.path, cwdCopy.path))) {
+            items.push({
+                key: 'maa-node(cwd)',
+                status: 'warn',
+                detail: `${cwdCopy.version}  (${cwdCopy.path})  — 项目目录里的副本，本 CLI 不加载它`,
+            });
+        }
+        /* 项目 pin 只与 self 对账：比的是「正在运行的那份」，不是项目里躺着的那份 */
+        const pin = projectRoot ? readMaaNodePin(projectRoot) : null;
+        const pinWarnings = [];
+        if (pin && pin.source !== 'uv.lock') {
+            if (pin.exact === null) {
+                items.push({
+                    key: 'maa-node pin',
+                    status: 'ok',
+                    detail: `${pin.declared}（${pin.source}）—— 范围声明，不比对`,
+                });
+            }
+            else if (!self) {
+                items.push({
+                    key: 'maa-node pin',
+                    status: 'warn',
+                    detail: `${pin.declared}（${pin.source}）—— CLI 实际加载的 maa-node 未安装，无法比对`,
+                });
+            }
+            else {
+                /* 两段都比、且 qualifier 先归一化：`5.15.0b1` 与 `5.15.0-beta.1` 是同一份构建的两种
+                   生态写法（不算不一致）；而正式版 `5.14.2` 与预发布 `5.14.2b1` 是同一条线上的两份
+                   不同构建（要报）。只比字符串会把前者误报、只比 release 会把后者漏报。 */
+                const pinV = splitRelease(pin.exact);
+                const runV = splitRelease(self.version);
+                const mismatch = () => {
+                    const detail = `项目 pin ${pin.declared}（${pin.source}），CLI 实际加载 ${self.version}`;
+                    items.push({ key: 'maa-node pin', status: 'warn', detail });
+                    pinWarnings.push(`maa-node 版本不一致：${detail}`);
+                };
+                if (!pinV || !runV) {
+                    /* 有一边不是 x.y.z 形态（自定义构建号之类）：没有 release 线可比，只能退回整串 */
+                    if (pin.exact === self.version) {
+                        items.push({
+                            key: 'maa-node pin',
+                            status: 'ok',
+                            detail: `${pin.exact}（${pin.source}）与 CLI 实际加载一致`,
+                        });
+                    }
+                    else {
+                        mismatch();
+                    }
+                }
+                else if (pinV.release !== runV.release) {
+                    mismatch();
+                }
+                else if (pinV.qualifier !== runV.qualifier) {
+                    /* 同 release 线但 qualifier 不同 = 同一条线上的另一份构建（正式版 vs b1、b1 vs rc1），
+                     * 仍然是"跑的不是 pin 的那份"，要报。归一化只抹平两个生态的拼写（b1 / beta.1）。 */
+                    mismatch();
+                }
+                else if (pin.exact === self.version) {
+                    items.push({
+                        key: 'maa-node pin',
+                        status: 'ok',
+                        detail: `${pin.exact}（${pin.source}）与 CLI 实际加载一致`,
+                    });
+                }
+                else {
+                    items.push({
+                        key: 'maa-node pin',
+                        status: 'ok',
+                        detail: `同版本 ${pinV.release}${pinV.qualifier ? '-' + pinV.qualifier : ''}：` +
+                            `声明 ${pin.exact} / 实际 ${self.version}（两种拼写指向同一份构建）`,
+                    });
+                }
+            }
+        }
+        /* 显式给了源码目录才出现：应用开发者的机器上不该看到一个「缺一项」 */
+        if (maafw)
+            items.push({
+                key: 'framework',
+                status: !existsSync(maafw) ? 'missing' : checkoutVer ? 'ok' : 'warn',
+                /* 进到这里 maafw 必然非空，"未提供源码目录"那一支是死的（曾经留着） */
+                detail: !existsSync(maafw)
+                    ? `checkout 不存在：${maafw}`
+                    : checkoutVer
+                        ? `${checkoutVer}  (${maafw})`
+                        : `存在但 git describe 失败：${maafw}`,
+            });
+        items.push({
+            key: 'git',
+            status: gitV.ok ? 'ok' : 'warn',
+            detail: gitV.ok ? firstLine(gitV.stdout || gitV.stderr) : '不可用（仅版本对账与迁移脚本需要）',
+        });
+        // adb 与 python 是「按需」依赖：只有设备类命令和 v5 迁移脚本需要，
+        // 缺失不影响其余功能，因此记 warn 而不是 missing（不拉高退出码）。
+        items.push({
+            key: 'adb',
+            status: adbV.ok ? 'ok' : 'warn',
+            detail: adbV.ok ? firstLine(adbV.stdout || adbV.stderr) : '不可用（设备类命令需要它）',
+        });
+        items.push({
+            key: 'python',
+            status: pyV.ok ? 'ok' : 'warn',
+            detail: pyV.ok
+                ? firstLine(pyV.stdout || pyV.stderr)
+                : '不可用（migrate_pipeline_v5.py 需要它）',
+        });
+        if (deep) {
+            const npm = await run('npm', ['--version'], { timeout: 8000 });
+            items.push({
+                key: 'npm',
+                status: npm.ok ? 'ok' : 'missing',
+                detail: npm.ok ? `npm ${firstLine(npm.stdout)}` : '不可用',
+            });
+            for (const pkg of ['maa-evidence-kit', 'create-maa-project']) {
+                const r = await run('npm', ['ls', '-g', '--depth=0', pkg], { timeout: 15000 });
+                const installed = r.ok && r.stdout.includes(pkg);
+                items.push({
+                    key: pkg,
+                    status: installed ? 'ok' : 'warn',
+                    detail: installed ? '已全局安装' : '未全局安装',
+                });
+            }
+        }
+        const width = Math.max(...items.map((i) => i.key.length));
+        const human = [
+            'maafw-live env',
+            ...items.map((i) => `  ${mark(i.status)} ${pad(i.key, width)}  ${i.detail}`),
+        ];
+        const missing = items.filter((i) => i.status === 'missing');
+        const warnings = missing.map((i) => `${i.key}: ${i.detail}`);
+        warnings.push(...pinWarnings);
+        return {
+            exitCode: missing.length > 0 ? EXIT.ENV : EXIT.OK,
+            root: projectRoot,
+            human,
+            warnings,
+            data: {
+                runtime: { node: process.version, platform: process.platform, arch: process.arch },
+                cwd,
+                project: { root: projectRoot, pipelineDirs: dirs },
+                maaNode: self,
+                /** cwd 那份副本，仅作对照：它不是 CLI 实际加载的那份 */
+                maaNodeCwd: cwdCopy,
+                /** 项目声明的 pin：只用 package.json / requirements.txt 下结论，uv.lock 仅记来源 */
+                maaNodePin: pin,
+                framework: maafw
+                    ? {
+                        checkout: { path: maafw, found: existsSync(maafw), version: checkoutVer },
+                        native: self?.version ?? null,
+                    }
+                    : null,
+                tools: {
+                    git: { available: gitV.ok, version: gitV.ok ? firstLine(gitV.stdout || gitV.stderr) : '' },
+                    adb: { available: adbV.ok, version: adbV.ok ? firstLine(adbV.stdout || adbV.stderr) : '' },
+                    python: { available: pyV.ok, version: pyV.ok ? firstLine(pyV.stdout || pyV.stderr) : '' },
+                },
+            },
+        };
+    },
+};
+//# sourceMappingURL=env.js.map

package/lib/commands/index.js

@@ -0,0 +1,70 @@
+import { ANNOTATE_COMMANDS } from './annotate.js';
+import { CALIBRATE_COMMANDS } from './calibrate.js';
+import { COLOR_COMMANDS } from './color.js';
+import { CROP_COMMANDS } from './crop.js';
+import { envCommand } from './env.js';
+import { INPUT_COMMANDS } from './input.js';
+import { KF_COMMANDS } from './kf.js';
+import { screencapProbeCommand } from './probe.js';
+import { RECO_COMMANDS } from './reco.js';
+import { replCommand } from './repl.js';
+import { ROI_CHECK_COMMANDS } from './roi-check.js';
+import { ROI_COMPARE_COMMANDS } from './roi-compare.js';
+import { RUNTIME_COMMANDS } from './runtime.js';
+import { skillCommand } from './skill.js';
+import { TIMING_COMMANDS } from './timing.js';
+import { versionCommand } from './version.js';
+/** 展示顺序：探针 → 运行时/设备 → 输入 → 识别 → 验真 → 探色 → 裁剪 → SoM → 校准 → 关键帧 → timing → 会话 → skill 自检。 */
+export const COMMANDS = [
+    envCommand,
+    versionCommand,
+    ...RUNTIME_COMMANDS,
+    screencapProbeCommand,
+    ...INPUT_COMMANDS,
+    ...RECO_COMMANDS,
+    ...ROI_COMPARE_COMMANDS,
+    ...ROI_CHECK_COMMANDS,
+    ...COLOR_COMMANDS,
+    ...CROP_COMMANDS,
+    ...ANNOTATE_COMMANDS,
+    ...CALIBRATE_COMMANDS,
+    ...KF_COMMANDS,
+    ...TIMING_COMMANDS,
+    replCommand,
+    skillCommand,
+];
+export function findCommand(name) {
+    return COMMANDS.find((c) => c.name === name);
+}
+/** 未知命令时给出「最接近的名字」建议（编辑距离），避免用户猜 */
+export function suggestCommand(name, maxDistance = 3) {
+    let best;
+    let bestDist = maxDistance + 1;
+    for (const c of COMMANDS) {
+        const d = distance(name, c.name);
+        if (d < bestDist) {
+            bestDist = d;
+            best = c.name;
+        }
+    }
+    return bestDist <= maxDistance ? best : undefined;
+}
+function distance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = cur;
+    }
+    return prev[n];
+}
+//# sourceMappingURL=index.js.map