@windsland52/maafw-live 0.3.0 → 0.4.0

package/lib/commands/calibrate.js

@@ -13,7 +13,7 @@ export const calibrateCommand = {
         '       采集期间保持画面静止；结果给出可直接粘贴的 stream start 参数',
     options: { ...CONNECT_OPTIONS, frames: { type: 'string' }, interval: { type: 'string' } },
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         if (!o.project && !o.kind) {
             return fail('BAD_ARGUMENTS', '校准要设备：给 --project <dir>（推荐）或 --kind win32|adb|gamepad', undefined, EXIT.USAGE);
         }
@@ -26,7 +26,7 @@ export const calibrateCommand = {
             return fail('BAD_ARGUMENTS', '--interval 必须是毫秒数（默认 300）', undefined, EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const s = await ensureSession(client, o);
                 const r = await calibrate(client, {
                     ...(frames !== undefined ? { frames } : {}),
@@ -40,7 +40,7 @@ export const calibrateCommand = {
                 return {
                     exitCode: r.warn ? EXIT.FINDINGS : EXIT.OK,
                     human: [
-                        ...describeSession(s),
+                        ...describeSession(s, ctx.flags.verbose),
                         '校准 ' + String(r.frames) + ' 帧（分块亮度差 / 全局位差率的噪声分布）：',
                         '  分块差  p50=' + block.p50 + '  p99=' + block.p99 + '  max=' + block.max,
                         '  位差率  p50=' + global.p50 + '  p99=' + global.p99 + '  max=' + global.max,

package/lib/commands/color.js

@@ -15,7 +15,7 @@ export const colorCommand = {
         '       一次性命令先自动截一帧再测；REPL 里测缓冲最新帧（先 screencap / stream）',
     options: { ...CONNECT_OPTIONS, roi: { type: 'string' }, seq: { type: 'string' } },
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         if (!o.project && !o.kind) {
             return fail('BAD_ARGUMENTS', '要设备才能探色：给 --project <dir>（推荐）或 --kind win32|adb|gamepad', '多步操作用 maafw-live repl（连接一次后连续观测）', EXIT.USAGE);
         }
@@ -30,7 +30,7 @@ export const colorCommand = {
             return fail('BAD_ARGUMENTS', '--seq 必须是数字', undefined, EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const s = await ensureSession(client, o);
                 /* 一次性命令缓冲为空：先截一帧产生观测（screencap 现在进环，有捕获身份）。
                  * 截帧文件用完即删——它只是观测载体，既不落用户 cwd，也不留在临时目录。 */
@@ -50,7 +50,7 @@ export const colorCommand = {
                 return {
                     exitCode: EXIT.OK,
                     human: [
-                        ...describeSession(s),
+                        ...describeSession(s, ctx.flags.verbose),
                         '探色 seq=' + String(r.seq) + (roi ? '  roi=' + roi.join(',') : '  （整帧）'),
                         '  均值 RGB ' + mean.r + ',' + mean.g + ',' + mean.b + '  灰度 ' + mean.gray +
                             '  HSV ' + hsv.h + '°,' + hsv.s + '%,' + hsv.v + '%',

package/lib/commands/crop.js

@@ -18,7 +18,7 @@ import { defaultFramesDir, resolveFrame } from '../runtime/keyframes.js';
 import { EXIT, fail } from '../protocol.js';
 import { seedObservation, tplCrop, withDaemon } from '../runtime/actions.js';
 import { describeSession, ensureSession, offlineResource } from '../runtime/session.js';
-import { CONNECT_OPTIONS, daemonFail, sessionOptions } from './runtime.js';
+import { CONNECT_OPTIONS, daemonFail, argPath, sessionOptions } from './runtime.js';
 function nums(raw, count, what) {
     if (raw === undefined)
         return undefined;
@@ -70,7 +70,7 @@ export const cropCommand = {
         'keep-source': { type: 'boolean' },
     },
     async run(ctx) {
-        const o = sessionOptions(ctx.values);
+        const o = sessionOptions(ctx);
         let roi;
         let point;
         try {
@@ -91,7 +91,7 @@ export const cropCommand = {
         if (pad !== undefined && !Number.isFinite(pad)) {
             return fail('BAD_ARGUMENTS', '--pad 必须是数字（点→ROI 外扩半径，默认 24）', undefined, EXIT.USAGE);
         }
-        const out = typeof ctx.values.out === 'string' ? ctx.values.out : undefined;
+        const out = argPath(ctx, typeof ctx.values.out === 'string' ? ctx.values.out : undefined);
         const fromKf = typeof ctx.values['from-kf'] === 'string' ? ctx.values['from-kf'] : undefined;
         if (fromKf !== undefined && seq !== undefined) {
             return fail('BAD_ARGUMENTS', '--from-kf 与 --seq 互斥：前者从库内留存帧裁，后者从本会话 L0 热缓存裁', '取库里有哪些帧：maafw-live kf list', EXIT.USAGE);
@@ -103,7 +103,7 @@ export const cropCommand = {
          * 解析失败就在这一层如实报，不把不可复核的帧送进裁剪。 */
         let kfSource;
         if (fromKf !== undefined) {
-            const dir = typeof ctx.values['frames-dir'] === 'string' ? ctx.values['frames-dir'] : defaultFramesDir();
+            const dir = argPath(ctx, typeof ctx.values['frames-dir'] === 'string' ? ctx.values['frames-dir'] : undefined) ?? defaultFramesDir();
             const r = resolveFrame(dir, fromKf);
             if (r.status !== 'available' || !r.path || !r.record) {
                 const code = r.status === 'corrupt' ? 'KF_CORRUPT' : (r.status === 'unsupported' ? 'KF_UNSUPPORTED' : 'KF_MISSING');
@@ -118,14 +118,14 @@ export const cropCommand = {
             return fail('BAD_ARGUMENTS', '--cross 需要连接设备：给 --project <dir> 或 --kind', '不留 --cross 就是纯离线裁剪（留存帧的价值所在）', EXIT.USAGE);
         }
         try {
-            return await withDaemon(async (client) => {
+            return await withDaemon(ctx, async (client) => {
                 const s = offline ? { connected: false } : await ensureSession(client, o);
                 /* 自匹配要加载资源（模板走 override_image，不写项目目录）；项目模式用规划出的资源 */
-                let resourceDir = (typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined)
+                let resourceDir = argPath(ctx, typeof ctx.values['resource-dir'] === 'string' ? ctx.values['resource-dir'] : undefined)
                     ?? s.plan?.resource?.paths[0];
                 if (!resourceDir && offline && o.project) {
                     /* 离线：项目只是资源的来源，不是连接的对象——只读 interface.json，不扫设备 */
-                    const off = offlineResource(o.project, o.controller, o.resource);
+                    const off = offlineResource(o.project, o.controller, o.resource, ctx.cwd);
                     if (off.error) {
                         return fail('PLAN_FAILED', '离线解析项目资源失败：' + off.error, '也可以直接给 --resource-dir <dir>', EXIT.FINDINGS);
                     }
@@ -175,7 +175,7 @@ export const cropCommand = {
                     : '  空间核对：未连接设备，未与当前控制器尺寸比对（模板空间 = 源帧捕获时尺寸 ' +
                         String(r.ctrlW) + 'x' + String(r.ctrlH) + '）';
                 const human = [
-                    ...describeSession(s),
+                    ...describeSession(s, ctx.flags.verbose),
                     ...(offline ? ['离线裁剪：未连接设备（留存帧是本机持久文件，裁剪不需要设备）'] : []),
                     '模板 ' + String(r.w) + 'x' + String(r.h) + ' → ' + String(r.path),
                     '  ' + srcLine,

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

@@ -67,6 +67,118 @@ function resolveMaaNode(from) {
 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 快照版本。
  *
@@ -101,8 +213,10 @@ export const envCommand = {
         const deep = ctx.values.deep === true;
         const projectRoot = findProjectRoot(cwd);
         const dirs = projectRoot ? pipelineDirs(projectRoot) : [];
-        /* 运行时绑定是本包自己的依赖：按包自身解析即可；项目目录里的副本优先（项目可能 pin 了别的版本） */
-        const maaNode = resolveMaaNode(cwd) ?? resolveMaaNode(selfDir());
+        /* 运行时绑定是本包自己的依赖：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 }),
@@ -129,9 +243,84 @@ export const envCommand = {
         });
         items.push({
             key: 'maa-node',
-            status: maaNode ? 'ok' : 'missing',
-            detail: maaNode ? `${maaNode.version}  (${maaNode.path})` : '未安装（运行时命令不可用）',
+            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({
@@ -187,6 +376,7 @@ export const envCommand = {
         ];
         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,
@@ -196,11 +386,15 @@ export const envCommand = {
                 runtime: { node: process.version, platform: process.platform, arch: process.arch },
                 cwd,
                 project: { root: projectRoot, pipelineDirs: dirs },
-                maaNode,
+                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: maaNode?.version ?? null,
+                        native: self?.version ?? null,
                     }
                     : null,
                 tools: {

package/lib/commands/index.js

@@ -5,19 +5,25 @@ 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 自检。 */
+/** 展示顺序：探针 → 运行时/设备 → 输入 → 识别 → 验真 → 探色 → 裁剪 → 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,