@windsland52/maafw-live 0.0.0-stage → 0.3.0

package/lib/types/commands/repl.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from '../protocol.js';
+export declare const replCommand: Command;

package/lib/types/commands/runtime.d.ts

@@ -0,0 +1,48 @@
+import { type Command, type CommandResult } from '../protocol.js';
+import { type SessionOptions } from '../runtime/session.js';
+/** 连接类选项：凡是要设备的命令都接受同一组，保证"怎么连"只有一套说法。 */
+export declare const CONNECT_OPTIONS: {
+    project: {
+        type: "string";
+    };
+    controller: {
+        type: "string";
+    };
+    resource: {
+        type: "string";
+    };
+    hwnd: {
+        type: "string";
+    };
+    address: {
+        type: "string";
+    };
+    kind: {
+        type: "string";
+    };
+    target: {
+        type: "string";
+    };
+    'short-side': {
+        type: "string";
+    };
+    'long-side': {
+        type: "string";
+    };
+    raw: {
+        type: "boolean";
+    };
+};
+export declare function sessionOptions(values: Record<string, unknown>): SessionOptions;
+/** daemon 抛出的错误一律翻译成结构化失败，不让堆栈进模型上下文。 */
+export declare function daemonFail(e: unknown, hint?: string): CommandResult;
+export declare const probeCommand: Command;
+export declare const deviceCommand: Command;
+export declare const connectCommand: Command;
+export declare const disconnectCommand: Command;
+export declare const screencapCommand: Command;
+export declare const frameCommand: Command;
+export declare const waitCommand: Command;
+export declare const runCommand: Command;
+export declare const stopCommand: Command;
+export declare const RUNTIME_COMMANDS: Command[];

package/lib/types/commands/skill.d.ts

@@ -0,0 +1,17 @@
+import { type Command } from '../protocol.js';
+/** 包内 skill 目录：lib/commands/ → <包根>/skills/maafw-live（本地 checkout 同构） */
+export declare function skillPayloadDir(): string;
+export interface SkillFileStatus {
+    path: string;
+    status: 'same' | 'different' | 'missing' | 'extra';
+    /** different 时的成因提示；行尾差异常来自跨平台工具改写，值得单独指出 */
+    note?: string;
+    bytes?: number;
+    sha256?: string;
+}
+/**
+ * 逐文件比对（纯函数，单测直接喂两个目录）。只比字节：任何不同都是 different，
+ * 但在**仅行尾不同**（CRLF ↔ LF）时补一条 note——那不是内容分叉，是工具改写。
+ */
+export declare function compareSkillTrees(payload: string, target: string): SkillFileStatus[];
+export declare const skillCommand: Command;

package/lib/types/commands/timing.d.ts

@@ -0,0 +1,64 @@
+/**
+ * timing：从帧流与节点事件反推 pipeline 的 delay / timeout 建议值。
+ *
+ * 做法：自动开流 → 跑任务（--runs n 次采样）→ 对齐两类时间线——
+ *  - 节点时长（record.nodes）→ 节点级 timeout 建议（P95 × 1.5 余量）
+ *  - 节点完成后的画面稳定时间（完成事件到下一个 stable 事件的时距）→ post-delay /
+ *    wait_freezes 建议；下一节点先于 stable 开始则标"未稳定"（连续动画/识别窗口过紧）。
+ * 分布口径：建议值只取成功 run（失败 run 的时长是提前终止的，对 timeout 建议是误导）；
+ * 单次采样退化为 P50=P95=该值，与历史单次行为逐字段一致。
+ */
+import { type Command } from '../protocol.js';
+interface TimedNode {
+    name: string;
+    ms: number;
+    status: string;
+    settle: number | null;
+    nextBeforeStable: boolean;
+}
+/** 单次采样的产物：一次 run 的任务结果 + 该 run 事件区间内的对齐分析 */
+export interface RunSample {
+    index: number;
+    ok: boolean;
+    durationMs: number;
+    nodes: TimedNode[];
+    events: number;
+}
+export interface NodeStat {
+    name: string;
+    status: string;
+    /** 成功 run 中该节点出现的 run 数（少于成功总数 = 有分支/跳过） */
+    runs: number;
+    /** 总执行次数——同名节点在同一 run 内可能重复（重试/JumpBack/Next 环），
+     * 分布统计按全部出现算，丢掉重复会漏掉真正的慢样本 */
+    occurrences: number;
+    msP50: number;
+    msP95: number;
+    settleP50: number | null;
+    settleP95: number | null;
+    settleSamples: number;
+    nextBeforeStable: boolean;
+}
+export interface TimingAggregate {
+    successful: number;
+    failed: number;
+    durationP50: number;
+    durationP95: number;
+    /** 各 run 最长节点时长的 P95——建议值的基准（覆盖"最慢节点"这一任务级口径） */
+    maxNodeP95: number;
+    /** 各 run 最长稳定时间的 P95；全无 stable 样本时为 null */
+    maxSettleP95: number | null;
+    nodeStats: NodeStat[];
+    suggest: {
+        nodeTimeoutMs: number;
+        taskTimeoutMs: number;
+        postDelayMs: number | null;
+    };
+}
+/** 最近邻秩百分位：sorted 升序；n=1 时任意 p 返回该值，n 小时偏保守端（P95 取最大） */
+export declare function percentile(values: number[], p: number): number;
+/** 跨 run 聚合（纯函数，单测直断言）：节点统计与建议值都只算成功样本 */
+export declare function aggregateTiming(samples: RunSample[]): TimingAggregate;
+export declare const timingCommand: Command;
+export declare const TIMING_COMMANDS: Command[];
+export {};

package/lib/types/commands/version.d.ts

@@ -0,0 +1,3 @@
+/** `maafw-live version` —— CLI 与运行环境版本。技能用它做版本对齐；`--check` 对 registry 查有没有新版。 */
+import { type Command } from '../protocol.js';
+export declare const versionCommand: Command;

package/lib/types/exec.d.ts

@@ -0,0 +1,31 @@
+export interface ExecResult {
+    ok: boolean;
+    /** 进程退出码；被信号杀死或启动失败时为 null */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    /** 启动失败的原因（ENOENT 等） */
+    spawnError?: string;
+}
+export interface ExecOptions {
+    timeout?: number;
+    cwd?: string;
+    /** 传入 stdin 的内容 */
+    input?: string;
+    /** 内部用：把参数按原样交给子进程（实现 cmd 的引号规则时需要，见 run()） */
+    verbatim?: boolean;
+}
+/**
+ * 执行外部命令。
+ *
+ * Windows 上 `.cmd` / `.bat`（npm、npx、pnpm）不是可执行文件：execFile 直接跑会**同步抛 EINVAL**
+ * （Node 对 CVE-2024-27980 的修复，本模块曾因此让 `env` 在只缺 adb 的机器上整条失败），
+ * 所以先 `where` 解析出可执行路径，再经 `ComSpec` 执行。而 cmd 的引号规则有讲究：`/s` 会剥掉最外层
+ * 引号，所以命令串要**整体再包一层引号**并配 `windowsVerbatimArguments`——实测
+ * `cmd /d /s /c ""C:\Program Files\nodejs\npm.cmd" --version"` 是唯一能跑通的拼法。
+ * 不直接用 `shell: true`：给 shell 传参会触发 `DEP0190` 弃用警告，且"命令不存在"会退化成
+ * "cmd 跑起来了但退出 1"（本地化报错，判不准）。
+ */
+export declare function run(bin: string, args?: string[], opts?: ExecOptions): Promise<ExecResult>;
+/** 取首行有效输出，供「版本号探测」这类场景用 */
+export declare function firstLine(s: string): string;

package/lib/types/flags.d.ts

@@ -0,0 +1,58 @@
+export declare const GLOBAL_OPTIONS: {
+    json: {
+        type: "boolean";
+    };
+    'dry-run': {
+        type: "boolean";
+    };
+    yes: {
+        type: "boolean";
+    };
+    'no-interactive': {
+        type: "boolean";
+    };
+    'no-color': {
+        type: "boolean";
+    };
+    cwd: {
+        type: "string";
+    };
+    limit: {
+        type: "string";
+    };
+    verbose: {
+        type: "boolean";
+    };
+    help: {
+        type: "boolean";
+        short: string;
+    };
+    version: {
+        type: "boolean";
+        short: string;
+    };
+};
+export interface GlobalFlags {
+    json: boolean;
+    /** 预留位：当前没有"只计算不落盘"的实现，值不被消费 */
+    dryRun: boolean;
+    /** 预留授权位：当前版本没有确认步骤，值不被消费 */
+    yes: boolean;
+    /** 预留门控位：当前版本没有交互式提问，值不被消费 */
+    interactive: boolean;
+    color: boolean;
+    cwd: string;
+    /** 预留位：当前没有输出条数上限，值不被消费 */
+    limit: number;
+    /** 预留位：当前没有详细输出，值不被消费 */
+    verbose: boolean;
+    help: boolean;
+    version: boolean;
+}
+/**
+ * 从 parseArgs 的 values 推导全局标志。
+ *
+ * `--no-color` 只关闭颜色；未指定时按 TTY 自动判断（管道里自动无色）。
+ * 注意不能用 NO_COLOR 环境变量以外的方式覆盖显式传入的值。
+ */
+export declare function readGlobalFlags(values: Record<string, unknown>, cwd: string): GlobalFlags;

package/lib/types/image.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 纯 JS 图像工具：复用 daemon 里那套无依赖 PNG 编解码（不做第二份实现）。
+ *
+ * daemon（daemon/framed.mjs）本来就带 PNG 解码 / 缩放 / 编码 —— 它要在没有 native 依赖的
+ * 前提下处理帧 —— 但只在子进程里用。这里用非字面量说明符动态 import 取它的 __test 导出：
+ * 避免为一个 .mjs 引入声明文件、把构建链复杂化，同时用下面的接口把契约钉死。
+ *
+ * 与 daemon 帧流共用同一条降采样路径，因此"面板预览看到的缩放"和"识别用的缩放"不会分叉。
+ */
+/** PNG Buffer 的尺寸。 */
+export declare function pngSize(buf: Buffer): Promise<{
+    w: number;
+    h: number;
+}>;
+/** 按"长边不超过 maxSide"缩放 PNG（只缩不放，原图更小时原样返回）。 */
+export declare function scalePngLongSide(buf: Buffer, maxSide: number): Promise<Buffer>;
+/**
+ * 按矩形裁一块出来（控制器分辨率坐标系，越界自动夹紧）。
+ *
+ * 面板的"模板匹配即时校验"用它：把人框的这块裁成模板图，再交给识别去比对 —— 因此这一步
+ * 必须与帧流/识别走同一条解码路径，不能各自实现（否则裁出来的像素与识别看到的不是同一份）。
+ */
+export declare function cropPng(buf: Buffer, rect: [number, number, number, number]): Promise<Buffer>;
+/** data URL → PNG Buffer；非图片 data URL 返回 null。 */
+export declare function dataUrlToPng(dataUrl: string): Buffer | null;
+/** PNG Buffer → data URL（面板侧统一 data:image/png）。 */
+export declare function pngToDataUrl(buf: Buffer): string;

package/lib/types/index.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/lib/types/interface/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 项目声明（interface.json / ProjectInterface v2）的窄解析与连接规划。
+ *
+ * 这是"认识项目"的唯一一份实现：控制器声明 → daemon connect 参数、
+ * 资源声明 → resource 目录、task 声明 → run 入口解析、
+ * option/preset → pipeline_override 四级合并链。
+ */
+export { parseJsonc } from './jsonc.js';
+export { loadInterface, findInterfaceFile, type DisplayDecl, type GamepadDecl, type InterfaceController, type InterfaceOption, type InterfacePreset, type InterfaceProblem, type InterfaceResource, type InterfaceTask, type LoadedInterface, type OptionCase, type Win32Decl, } from './load.js';
+export { planController, resolveResourcePaths, type ControllerPlan, type DeviceLike, type PlanOverrides, type ResourcePlan, } from './plan.js';
+export { computePipelineOverride, mergeOverride, type OverrideInput, type OverrideResult } from './override.js';

package/lib/types/interface/jsonc.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 容错 JSON：真实项目的 interface.json 带 `//` 注释（官方解析器基于 meojson），
+ * strict JSON.parse 会直接拒绝，因此先做最小脱敏——字符串外的注释与尾随逗号去掉。
+ *
+ * 取舍：只做这两件**最小**的事，不做单引号 / 无引号键 / 多行字符串那类扩展——
+ * 越是"看起来像 JSON"的输入，越容易被静默改写成作者没写的意思。
+ * 另：开头的 BOM（Windows 记事本等会写）先剥掉，它会让 JSON.parse 报 "Unexpected token"。
+ */
+export declare function parseJsonc(text: string): unknown;

package/lib/types/interface/load.d.ts

@@ -0,0 +1,113 @@
+export interface InterfaceProblem {
+    message: string;
+}
+/** 控制器的显示声明；映射为 daemon connect 的 shortSide / longSide / rawSize。 */
+export interface DisplayDecl {
+    shortSide?: number;
+    longSide?: number;
+    raw?: boolean;
+    expand?: [number, number];
+}
+export interface Win32Decl {
+    classRegex?: string;
+    windowRegex?: string;
+    screencap?: string;
+    mouse?: string;
+    keyboard?: string;
+}
+export interface GamepadDecl {
+    classRegex?: string;
+    windowRegex?: string;
+    gamepadType?: string;
+    screencap?: string;
+}
+export interface InterfaceController {
+    name: string;
+    /** Adb / Win32 / Gamepad / MacOS / PlayCover / Linux */
+    type: string;
+    display?: DisplayDecl;
+    win32?: Win32Decl;
+    gamepad?: GamepadDecl;
+    /** v2.2.0：在 resource.path 之后追加加载的资源目录（相对 interface.json 所在目录） */
+    attachResourcePath: string[];
+    /** v2.3.0：控制器级配置项名单（override 链第三级） */
+    option?: string[];
+}
+export interface InterfaceResource {
+    name: string;
+    /** 资源根目录（含 pipeline / image / model），相对 interface.json 所在目录，声明顺序即加载顺序 */
+    paths: string[];
+    /** 只对这些控制器生效；空数组 = 全部 */
+    controllers: string[];
+    /** v2.3.0：资源级配置项名单（override 链第二级） */
+    option?: string[];
+}
+export interface InterfaceTask {
+    name: string;
+    /** pipeline 入口节点名；缺省时入口即任务名 */
+    entry?: string;
+    /** 只在这些控制器下可用（隐藏/禁用语义）；空 = 全部 */
+    controller?: string[];
+    /** 只在这些资源下可用；空 = 全部 */
+    resource?: string[];
+    /** 配置项键名（按展示顺序）；对应 InterfaceOption 字典的键 */
+    option?: string[];
+}
+/** option 字典条目：switch/select/checkbox 的 case 携带 pipeline_override。 */
+export interface OptionCase {
+    name: string;
+    pipelineOverride?: Record<string, unknown>;
+    /** 选中该 case 后生效的子配置项 */
+    option?: string[];
+}
+export interface InterfaceOption {
+    name: string;
+    type: string;
+    cases: OptionCase[];
+    /** 初始选中：switch/select 单 case 名；checkbox 为 case 名数组 */
+    defaultCase?: string | string[];
+    /** 适用性过滤（v2.3.1：不满足的 option 不得产生 pipeline_override） */
+    controller?: string[];
+    resource?: string[];
+}
+/** preset：任务与 option 取值的快照（v2.3.0），应用时覆盖 default_case。 */
+export interface InterfacePreset {
+    name: string;
+    task: Array<{
+        name: string;
+        enabled?: boolean;
+        option?: Record<string, unknown>;
+    }>;
+}
+/** PI `agent` 声明：宿主侧子进程（如 uv run python agent/main.py），经 agent 协议注册 custom
+ * action / recognition。maa-node 绑定未暴露 AgentClient 桥接——本工具只能诊断，不能 spawn。 */
+export interface InterfaceAgent {
+    exec: string;
+    args: string[];
+}
+export interface LoadedInterface {
+    /** interface.json 绝对路径；未找到为 null */
+    file: string | null;
+    /** 所在目录——resource.path 与 attach_resource_path 的相对基准 */
+    dir: string | null;
+    version: number | null;
+    name: string | null;
+    controllers: InterfaceController[];
+    resources: InterfaceResource[];
+    tasks: InterfaceTask[];
+    /** option 字典（主文件 + import 合并，后导入覆盖同名） */
+    options: Record<string, InterfaceOption>;
+    presets: InterfacePreset[];
+    /** 全局配置项键名（override 链最低级） */
+    globalOption: string[];
+    /** controller 启动前任务；CLI 不执行，仅用于警告 */
+    pretask: Array<{
+        name?: string;
+        exec?: string;
+    }>;
+    /** agent 子进程声明；CLI 未桥接（绑定无 AgentClient），仅用于警告与失败归因 */
+    agents: InterfaceAgent[];
+    problems: InterfaceProblem[];
+}
+export declare function findInterfaceFile(dir: string): string | null;
+export declare function loadInterface(dir: string): LoadedInterface;

package/lib/types/interface/override.d.ts

@@ -0,0 +1,33 @@
+/**
+ * pipeline_override 四级合并链（PI v2 v2.3.x）：global_option → resource.option →
+ * controller.option → task.option，后合并覆盖先合并；适用性过滤（option 自带的
+ * controller/resource 条件不满足时不产生 override）；checkbox 多选按 cases 声明序合并；
+ * 嵌套 option 在其父 case 之后合并。
+ *
+ * 取值解析顺序：preset 显式值 > default_case。两级都没有 → 警告并跳过（不猜）。
+ * 本 CLI 是无人值守消费面：不做交互选择，preset 是把 MaaPiCli 用户选择带进来的唯一通道。
+ */
+import type { LoadedInterface } from './load.js';
+export interface OverrideInput {
+    loaded: LoadedInterface;
+    controllerName: string | null;
+    resourceName: string | null;
+    taskName: string | null;
+    presetName?: string | null;
+}
+export interface OverrideResult {
+    override: Record<string, unknown>;
+    /** 需要人工注意的事项（选项无取值、preset 未找到等） */
+    warns: string[];
+    /** 人类可读的生效记录：option=值（级别） */
+    applied: string[];
+}
+/**
+ * 把一份 pipeline_override 并入累计结果：同节点字段替换（与协议"不深度合并"一致）。
+ *
+ * **唯一一份实现**：四级链、`run --override`、`timing --override` 都走这里。这三处曾经各写一份，
+ * 代价是同一个参数在不同命令里表现不同。非对象值必须**原样替换、不能展开**：字符串会被摊成
+ * `{0:'a',1:'b'}`，`null` / 数字会静默变成空对象——等于把用户写的节点悄悄丢掉。
+ */
+export declare function mergeOverride(acc: Record<string, unknown>, po: Record<string, unknown>): void;
+export declare function computePipelineOverride(input: OverrideInput): OverrideResult;

package/lib/types/interface/plan.d.ts

@@ -0,0 +1,47 @@
+import type { LoadedInterface } from './load.js';
+/** daemon device_list 的条目：adb 的 id 是 address，win32 的 id 是 hwnd。 */
+export interface DeviceLike {
+    kind?: string;
+    id?: string;
+    name?: string;
+    cls?: string;
+}
+export interface PlanOverrides {
+    controller?: string;
+    win32?: {
+        hwnd?: string | null;
+    };
+    gamepad?: {
+        hwnd?: string | null;
+    };
+    adb?: {
+        address?: string | null;
+    };
+    /** 手动 target（--target）：playcover=<address>/<uuid>；linux=<config JSON> */
+    manualTarget?: string | null;
+}
+export interface ControllerPlan {
+    ok: boolean;
+    code?: string;
+    error?: string;
+    controllerName: string | null;
+    /** 直接展开给 daemon 的 connect 参数 */
+    connect: Record<string, unknown>;
+    /** 失败时的候选设备，供调用方提示用户显式指定 */
+    candidates?: DeviceLike[];
+    notes?: string[];
+}
+export interface ResourcePlan {
+    paths: string[];
+    names: string[];
+    /** 本次实际选中的 resource 名（attach_resource_path 之外的来源条目） */
+    selected: string | null;
+}
+export declare function planController(loaded: LoadedInterface, overrides: PlanOverrides, devices: DeviceLike[]): ControllerPlan;
+/**
+ * 解析资源路径：resource[] 是互斥单选（Client 语义）——不传 override 时取第一个适用于
+ * 所选控制器的条目，条目自身多路径按声明顺序叠加（如"B 服"= base + bilibili）；
+ * attach_resource_path 在选中控制器后追加。override（--resource）先按资源名匹配，
+ * 匹配不上再按文件系统路径解释（原有行为）。
+ */
+export declare function resolveResourcePaths(loaded: LoadedInterface, controllerName?: string, override?: string): ResourcePlan;

package/lib/types/pkg.d.ts

@@ -0,0 +1,6 @@
+export interface PackageInfo {
+    name: string;
+    version: string;
+    description?: string;
+}
+export declare function cliPackage(): PackageInfo;

package/lib/types/protocol.d.ts

@@ -0,0 +1,108 @@
+/**
+ * CLI 协议层：统一 JSON 信封 + 命令契约 + 退出码语义。
+ *
+ * 信封结构抄 create-maa-project 的 `--report`——它已被真实消费方验证过，
+ * 属于本生态的既有事实标准。目的：让「技能 / 脚本 / CI / 人」消费同一份稳定结构，
+ * 不必各自解析文本输出，也不必各自发明字段名。
+ *
+ * 注意（这是本文件的唯一不变量）：信封字段只增不改。技能会按字段名读取，
+ * 改名等于静默破坏所有消费方。
+ */
+import type { ParseArgsOptionsConfig } from 'node:util';
+import type { GlobalFlags } from './flags.js';
+/** 信封结构版本。字段增删时递增，消费方可据此拒绝不认识的形状。 */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * 退出码语义。
+ *
+ * 关键区分：`FAIL` 是「命令没跑成」，`FINDINGS` 是「跑成了，但发现了问题」。
+ * 技能与 CI 必须能分开这两种情况——reco 识别未命中不是执行失败，
+ * 但也不该返回 0 让调用方以为一切正常。
+ */
+export declare const EXIT: {
+    /** 命令正常完成，未发现问题 */
+    readonly OK: 0;
+    /** 命令自身失败（未预期异常、IO 错误） */
+    readonly FAIL: 1;
+    /** 参数 / 用法错误 */
+    readonly USAGE: 2;
+    /** 命令正常跑完，但发现了问题（reco 未命中、run 调用级失败、观测类命令的警告等） */
+    readonly FINDINGS: 3;
+    /** 前置环境缺失（缺 maa-node / 缺 checkout / 缺设备） */
+    readonly ENV: 4;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export interface CliError {
+    message: string;
+    /** 稳定的机器可读标识，供技能分支判断；不要用 message 做判断 */
+    code: string;
+    hint?: string;
+}
+export interface Envelope {
+    schemaVersion: number;
+    command: string;
+    /** 命令本身是否执行成功。FINDINGS 仍算 ok=true——它跑成了，只是有发现 */
+    ok: boolean;
+    exitCode: number;
+    /** 本次操作的项目根，无法确定时为 null */
+    root: string | null;
+    written: string[];
+    removed: string[];
+    skipped: string[];
+    /** 需要人工跟进的事项（如「先跑 maa project sync」） */
+    pending: string[];
+    suggestedCommands: string[];
+    warnings: string[];
+    /** 命令特定载荷 */
+    data: unknown;
+    error: CliError | null;
+}
+/** 命令返回的结果。信封字段在此给默认值，命令只填关心的部分。 */
+export interface CommandResult {
+    exitCode: ExitCode;
+    data?: unknown;
+    /** 非 --json 时逐行打印的内容。命令自己决定怎么排版 */
+    human?: string[];
+    warnings?: string[];
+    written?: string[];
+    removed?: string[];
+    skipped?: string[];
+    pending?: string[];
+    suggestedCommands?: string[];
+    error?: CliError;
+    root?: string | null;
+}
+export interface CommandContext {
+    /** 命令名之后的位置参数 */
+    positionals: string[];
+    /** 已解析的全部选项（含全局选项） */
+    values: Record<string, unknown>;
+    flags: GlobalFlags;
+    /** 已解析并校验过存在性的工作目录（绝对路径） */
+    cwd: string;
+}
+export interface Command {
+    name: string;
+    /** 一行说明，用于顶层 help 列表 */
+    summary: string;
+    /** 完整用法行，如 `maafw-live env [--deep] [--maafw <dir>]` */
+    usage: string;
+    /** 命令私有选项；全局选项由入口自动合并 */
+    options?: ParseArgsOptionsConfig;
+    run(ctx: CommandContext): Promise<CommandResult>;
+}
+export declare function toEnvelope(command: string, r: CommandResult): Envelope;
+export interface EmitOptions {
+    json: boolean;
+    color: boolean;
+}
+/**
+ * 输出命令结果。
+ *
+ * --json 时只输出信封（stdout 保持纯 JSON，可被管道解析）；
+ * 否则输出命令自己的 human 渲染 + 警告 + 建议命令。
+ * 错误与警告一律走 stderr，避免污染 stdout 的 JSON。
+ */
+export declare function emit(command: string, r: CommandResult, o: EmitOptions): void;
+/** 失败结果的快捷构造 */
+export declare function fail(code: string, message: string, hint?: string, exitCode?: ExitCode): CommandResult;