@windsland52/maafw-live 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,166 @@
+import { resolveResourcePaths, type ControllerPlan, type DeviceLike, type LoadedInterface } from '../interface/index.js';
+import { type DaemonClient, type SpawnOptions } from '../client/daemon.js';
+/** 设备会话的连接参数（手动路径）。kind/target 之外全部来自 maafw 的控制器能力。 */
+export interface ManualConnect {
+    kind: 'adb' | 'win32' | 'gamepad';
+    target?: string;
+    /** 截图缩放覆盖（会改变 Tasker 识别图像的坐标系，模板/roi 随之变化） */
+    shortSide?: number;
+    longSide?: number;
+    rawSize?: boolean;
+    screencap?: string;
+    mouse?: string;
+    keyboard?: string;
+    gamepadType?: string;
+}
+export interface ConnectSession {
+    ok: boolean;
+    error?: string;
+    session?: Record<string, unknown> | null;
+    /** 本次连接重建了控制器、因而停掉了上一轮的帧流（需要看帧就重新 stream_start） */
+    streamStopped?: boolean;
+}
+/** 起一个 daemon、跑 fn、无论如何都收掉子进程。一次性命令用它，REPL 用长活客户端。 */
+export declare function withDaemon<T>(fn: (client: DaemonClient) => Promise<T>, options?: SpawnOptions): Promise<T>;
+export declare const probe: (c: DaemonClient) => Promise<Record<string, unknown>>;
+export declare const deviceList: (c: DaemonClient, kind?: "all" | "adb" | "win32") => Promise<DeviceLike[]>;
+export declare const connect: (c: DaemonClient, args: Record<string, unknown>) => Promise<ConnectSession>;
+export declare const disconnect: (c: DaemonClient) => Promise<{
+    ok: boolean;
+}>;
+export declare const screencap: (c: DaemonClient, out?: string) => Promise<Record<string, unknown>>;
+/**
+ * 一次性命令的"先产生一次观测"：截一帧进 daemon 的 L0，然后**把临时文件删掉**。
+ *
+ * 为什么需要这一帧：L0 是进程态，一次性命令（`crop` / `annotate` / `color`）每次 spawn 自己的
+ * daemon，不先截一帧就没有原图可用。为什么必须删：daemon 收帧时就把像素读进缓冲了，
+ * 落盘那份只为喂它一次——不删就是每跑一次在系统临时目录留一张 720p 截图（实测攒到 42 张 / 54MB）。
+ * 失败不抛：没有观测时命令自己会报"先 screencap / stream"这类可行动的错。
+ */
+export declare function seedObservation(c: DaemonClient, prefix: string): Promise<void>;
+export declare const streamStart: (c: DaemonClient, args?: {
+    fps?: number;
+    scale?: number;
+    maxFrames?: number;
+    l0Roll?: number;
+    l0Anchor?: number;
+    l0Bytes?: number;
+    blockThresh?: number;
+    changeGlobal?: number;
+}) => Promise<Record<string, unknown>>;
+export declare const streamStop: (c: DaemonClient) => Promise<{
+    ok: boolean;
+}>;
+export declare const streamStatus: (c: DaemonClient) => Promise<Record<string, unknown>>;
+export declare const frameGet: (c: DaemonClient, args: {
+    seq?: number;
+    roi?: number[];
+    out?: string;
+    src?: "auto" | "full" | "ring";
+}) => Promise<Record<string, unknown>>;
+/** 等状态谓词成立：stable=画面静下来 / change=画面动了。取代调用方硬睡时钟。 */
+export declare const waitState: (c: DaemonClient, args?: {
+    mode?: "stable" | "change";
+    timeout?: number;
+    quiet?: number;
+    roi?: number[];
+    threshold?: number;
+}) => Promise<Record<string, unknown>>;
+/** 两帧在若干 ROI 上的差分：回答"这一步改了哪几格"。 */
+export declare const frameDiff: (c: DaemonClient, args: {
+    a: number;
+    b: number;
+    rois: number[][];
+}) => Promise<Record<string, unknown>>;
+export declare const colorProbe: (c: DaemonClient, args: {
+    seq?: number;
+    roi?: number[];
+}) => Promise<Record<string, unknown>>;
+/** 裁剪源 = 关键帧库留存帧（离线解析出来的身份 + 路径；daemon 会复核 sha256 与像素尺寸）。 */
+export interface CropKfSource {
+    id: string;
+    path: string;
+    sha256: string;
+    ctrlW: number;
+    ctrlH: number;
+    captureSeq: number | null;
+    capturedAt: string | null;
+}
+export declare const tplCrop: (c: DaemonClient, args: {
+    seq?: number;
+    roi?: number[];
+    point?: number[];
+    pad?: number;
+    out?: string;
+    resourceDir?: string;
+    cross?: boolean;
+    kfSource?: CropKfSource;
+    prov?: boolean;
+    /** 出处侧车改写到该目录下（保持同名）；缺省写在模板旁 */
+    provOut?: string;
+    /** 热缓存路径下把本次实际用的那一帧升格进库，出处随即带上可复核的 `kf:` 身份 */
+    keepSource?: boolean;
+    /** snap 收紧阈值的**测量用覆盖**（定标 A/B）；缺省即生产常数 */
+    snapTol?: number;
+    snapFrac?: number;
+}) => Promise<Record<string, unknown>>;
+export declare const annotate: (c: DaemonClient, args: {
+    seq?: number;
+    out?: string;
+    resourceDir?: string;
+    kfSource?: CropKfSource;
+    /** 候选上限（缺省 30；截断按横向分带轮转，`mergedTotal` 才是去重后的真实规模） */
+    somLimit?: number;
+    /** 边缘源门槛的**测量用覆盖**（定标 A/B）；缺省即生产常数 */
+    somEdgeZ?: number;
+    somEdgeMin?: number;
+    /** 连通域合并 IoU 的测量用覆盖 */
+    somIoU?: number;
+    /** 巨框剔除阈值（画面面积比，缺省 0.12；OCR 框不参与）——背景/立绘/整屏变化区不该占表 */
+    somMaxAreaRatio?: number;
+    /** 只保留落在该区域（控制器空间）内的候选，且在**取上限之前**过滤：
+     * 区域内的候选只跟自己竞争。上限截断的正解是收小搜索面，不是把上限调大。 */
+    roi?: number[];
+    /** 检测面：full(缺省，有 L0 时用控制器分辨率原图) | small（强制降采样小图，快但小目标会漏） */
+    somScale?: "full" | "small";
+}) => Promise<Record<string, unknown>>;
+export declare const calibrate: (c: DaemonClient, args?: {
+    frames?: number;
+    interval?: number;
+}) => Promise<Record<string, unknown>>;
+export declare const runStop: (c: DaemonClient) => Promise<{
+    ok: boolean;
+}>;
+export declare const l0Status: (c: DaemonClient) => Promise<Record<string, unknown>>;
+export declare const kfPromote: (c: DaemonClient, args: {
+    seq?: number;
+    latest?: boolean;
+    note?: string;
+}) => Promise<Record<string, unknown>>;
+export declare function run(c: DaemonClient, args: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+export declare const input: (c: DaemonClient, payload: Record<string, unknown>, timeoutMs?: number) => Promise<Record<string, unknown>>;
+export declare const recoTest: (c: DaemonClient, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** 控制器类型 → 需要扫描的设备类型。控制器没声明时按第一个控制器推断。 */
+export declare function deviceKindFor(loaded: LoadedInterface, controllerName: string | null): 'adb' | 'win32';
+export interface ProjectPlan {
+    loaded: LoadedInterface;
+    plan: ControllerPlan | null;
+    controllerName: string | null;
+    resource: ReturnType<typeof resolveResourcePaths> | null;
+    error?: string;
+}
+/**
+ * 载入项目 → 扫设备 → 规划控制器 → 解析资源路径。
+ *
+ * 为什么不猜设备：interface.json 的 controller[] 已经声明了 Adb/Win32、窗口类名与标题正则、
+ * 截图与输入方法、以及识别缩放（display_short_side）——猜错不只是连错窗口，还会把 roi 与
+ * 模板的坐标系一起猜错。interface.json 的读法只有 src/interface/ 一份，别处不许再解析一遍。
+ */
+export declare function planProject(c: DaemonClient, dir: string, overrides?: {
+    controller?: string;
+    hwnd?: string;
+    gamepadHwnd?: string;
+    address?: string;
+    resource?: string;
+    manualTarget?: string;
+}): Promise<ProjectPlan>;

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

@@ -0,0 +1,43 @@
+export declare const KF_SCHEMA = 1;
+export interface KfRecord {
+    id: string;
+    file: string;
+    sha256: string;
+    session: {
+        daemon: string;
+        gen: number;
+        kind: string | null;
+        target: string | null;
+    };
+    capturedAt: string;
+    captureSeq: number;
+    ctrlW: number;
+    ctrlH: number;
+    smallW: number | null;
+    smallH: number | null;
+    scale: number | null;
+    source: string;
+    note: string | null;
+}
+export interface KfManifest {
+    schema: number;
+    libraryId: string;
+    next: number;
+    frames: KfRecord[];
+}
+export type KfResolveStatus = 'available' | 'missing' | 'corrupt' | 'unsupported';
+export declare function defaultFramesDir(): string;
+/** 读 manifest。坏文件/未知 schema 明确报错，不默认为当前版。 */
+export declare function loadManifest(dir: string): {
+    manifest?: KfManifest;
+    error?: string;
+};
+/** 按完整 ID 帧解析：available 时给出经过完整性校验的路径；missing/corrupt/unsupported 各自可诊断。 */
+export declare function resolveFrame(dir: string, id: string): {
+    status: KfResolveStatus;
+    record?: KfRecord;
+    path?: string;
+    reason?: string;
+};
+/** list 用：一行人类可读摘要（与 --json 的 data 各自完整，不共用裁剪）。 */
+export declare function describeRecord(r: KfRecord): string;

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

@@ -0,0 +1,53 @@
+/**
+ * 会话装配：一次性命令如何在同一个 daemon 里先连上设备、再干活、最后收尾。
+ *
+ * 为什么需要它：daemon 的连接是进程态——命令跑完进程就退出，连接随之消失。所以涉及设备的
+ * 命令（screencap / frame / run / click…）必须能在同一次调用里先完成连接，否则它们只会在
+ * REPL 里可用。传入 --project（推荐，走 interface.json 规划）或 --kind/--target（手动）
+ * 即可；两者都不给时交给命令自己处理。
+ */
+import type { DaemonClient } from '../client/daemon.js';
+import { type ProjectPlan } from './actions.js';
+export interface SessionOptions {
+    /** Maa 项目目录：按 interface.json 的 controller[] 规划连接 */
+    project?: string;
+    /** 项目模式下指定控制器名 */
+    controller?: string;
+    resource?: string;
+    /** 项目模式下的窗口 / adb 地址覆盖（持久化选择由面板负责，CLI 不做持久化） */
+    hwnd?: string;
+    address?: string;
+    /** 手动路径 */
+    kind?: string;
+    target?: string;
+    shortSide?: number;
+    longSide?: number;
+    rawSize?: boolean;
+}
+export interface SessionState {
+    connected: boolean;
+    plan?: ProjectPlan;
+    session?: Record<string, unknown> | null;
+    notes?: string[];
+    /** 本次连接重建了控制器、因而停掉了上一轮的帧流（daemon 回执 streamStopped）：调用方要接着看帧就重开流 */
+    streamStopped?: boolean;
+}
+export declare class SessionError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** 需要设备时连一次；项目模式下先规划控制器再连（拒绝猜设备）。 */
+export declare function ensureSession(client: DaemonClient, o: SessionOptions): Promise<SessionState>;
+/**
+ * 离线资源解析：只读 interface.json 拿资源目录，不扫设备、不连接。
+ *
+ * 为什么需要它：从关键帧库留存帧裁模板这条动线**不需要设备**（这正是"不可复现状态"的意义——
+ * 设备早已不在那个画面上）。但自匹配要加载资源，而资源声明在项目里。项目此刻只是资源的
+ * 来源，不是连接的对象，所以走 interface 的规划函数而不走 planProject（后者要扫设备）。
+ */
+export declare function offlineResource(project: string, controller?: string, resource?: string): {
+    paths: string[];
+    controllerName: string | null;
+    error?: string;
+};
+/** 连接结果的行渲染（human 输出与 --json 共用一份事实）。 */ export declare function describeSession(s: SessionState): string[];

package/lib/types/update-check.d.ts

@@ -0,0 +1,20 @@
+export interface UpdateState {
+    /** 上次成功查询的时间（epoch ms） */
+    checkedAt: number;
+    /** 上次查到的 latest */
+    latest: string;
+}
+export declare const UPDATE_TTL_MS: number;
+/** registry 的 packument URL：scoped 名只编码斜杠（`@scope` 保持字面） */
+export declare function packumentUrl(name: string): string;
+/** 语义化版本比较（只按 x.y.z 数值段；预发布标记按 semver 规则"有则更低"）。返回 a-b 的符号。 */
+export declare function compareVersions(a: string, b: string): number;
+/** 缓存是否还新鲜（没有缓存、或时间戳比 TTL 旧 → 该查） */
+export declare function shouldCheck(state: UpdateState | null, now: number, ttlMs?: number): boolean;
+export declare function statePath(runDir?: string): string;
+export declare function readState(file?: string): UpdateState | null;
+export declare function writeState(state: UpdateState, file?: string): void;
+/** 自动检查是否被环境变量关掉 */
+export declare function updateCheckDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** 查 registry 的 latest。任何失败都返回 null（静默）。 */
+export declare function fetchLatest(name: string, timeoutMs?: number): Promise<string | null>;

package/lib/types/usage.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from './protocol.js';
+export declare function topLevelUsage(): string[];
+export declare function commandUsage(cmd: Command): string[];

package/lib/update-check.js

@@ -0,0 +1,97 @@
+/**
+ * 更新检查：本机版本 vs registry 上的 latest。
+ *
+ * 设计取舍（刻意做成"只报不换"）：
+ *  - **不自动切换运行时**：agent 的长任务跑到一半换版本，比"晚一天升级"风险大得多。这里只提示。
+ *  - **只在交互终端自动查**：管道/agent 调用不为它付代价（`version --check` 是显式请求，不受此限）。
+ *  - **限频**：结果落盘缓存（默认 24h），不每次敲命令都打网络。
+ *  - **可关**：`MAAFW_LIVE_NO_UPDATE_CHECK=1`。
+ *  - **失败一律静默**：离线、代理、registry 抖动都不该影响 `version` 本身——它没有变得"失败"。
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { defaultRunDir } from './client/daemon.js';
+export const UPDATE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+/** registry 的 packument URL：scoped 名只编码斜杠（`@scope` 保持字面） */
+export function packumentUrl(name) {
+    return 'https://registry.npmjs.org/' + name.replace('/', '%2F');
+}
+/** 语义化版本比较（只按 x.y.z 数值段；预发布标记按 semver 规则"有则更低"）。返回 a-b 的符号。 */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core, ...rest] = String(v).trim().split('-');
+        const nums = core.split('.').map((x) => {
+            const n = Number(x);
+            return Number.isFinite(n) ? n : 0;
+        });
+        while (nums.length < 3)
+            nums.push(0);
+        return { nums: nums.slice(0, 3), pre: rest.length ? rest.join('-') : null };
+    };
+    const A = parse(a), B = parse(b);
+    for (let i = 0; i < 3; i++) {
+        if (A.nums[i] !== B.nums[i])
+            return A.nums[i] > B.nums[i] ? 1 : -1;
+    }
+    /* 主版本相同时：预发布低于正式版（1.0.0-rc < 1.0.0） */
+    if (A.pre === B.pre)
+        return 0;
+    if (A.pre === null)
+        return 1;
+    if (B.pre === null)
+        return -1;
+    return A.pre > B.pre ? 1 : -1;
+}
+/** 缓存是否还新鲜（没有缓存、或时间戳比 TTL 旧 → 该查） */
+export function shouldCheck(state, now, ttlMs = UPDATE_TTL_MS) {
+    if (!state || typeof state.checkedAt !== 'number' || !Number.isFinite(state.checkedAt))
+        return true;
+    if (typeof state.latest !== 'string' || state.latest === '')
+        return true;
+    return now - state.checkedAt >= ttlMs;
+}
+export function statePath(runDir = defaultRunDir()) {
+    return join(runDir, 'version-check.json');
+}
+export function readState(file = statePath()) {
+    try {
+        const j = JSON.parse(readFileSync(file, 'utf8'));
+        return j && typeof j.checkedAt === 'number' && typeof j.latest === 'string' ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(state, file = statePath()) {
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+    }
+    catch {
+        /* 缓存写不进去不影响任何事 */
+    }
+}
+/** 自动检查是否被环境变量关掉 */
+export function updateCheckDisabled(env = process.env) {
+    const v = String(env.MAAFW_LIVE_NO_UPDATE_CHECK ?? '').trim();
+    return v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+}
+/** 查 registry 的 latest。任何失败都返回 null（静默）。 */
+export async function fetchLatest(name, timeoutMs = FETCH_TIMEOUT_MS) {
+    try {
+        const res = await fetch(packumentUrl(name), {
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const j = (await res.json());
+        const latest = j['dist-tags']?.latest;
+        return typeof latest === 'string' && latest !== '' ? latest : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=update-check.js.map

package/lib/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"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"}

package/lib/usage.js

@@ -0,0 +1,50 @@
+/** 帮助文本。全局选项的说明集中在这里，命令只声明自己的选项。 */
+import { COMMANDS } from './commands/index.js';
+import { cliPackage } from './pkg.js';
+const GLOBAL_HELP = [
+    ['--json', '输出统一 JSON 信封（stdout 保持纯 JSON）'],
+    ['--yes', '授权标志（当前版本无确认步骤，照传）'],
+    ['--no-interactive', '防交互挂住自动化（当前版本无提问，照传）'],
+    ['--no-color', '关闭颜色（管道下自动关闭）'],
+    ['--cwd <dir>', '指定工作目录'],
+    ['--dry-run', '预留未实现：当前不改变行为，仍会落盘'],
+    ['--limit <n>', '预留未实现：当前不限制输出条数'],
+    ['--verbose', '预留未实现：当前无额外输出'],
+    ['-h, --help', '显示帮助'],
+    ['-V, --version', '显示版本'],
+];
+function pad(s, n) {
+    return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+export function topLevelUsage() {
+    const pkg = cliPackage();
+    const nameWidth = Math.max(...COMMANDS.map((c) => c.name.length), 7);
+    return [
+        `${pkg.name} ${pkg.version} — MaaFramework 设备运行时与观测底座`,
+        '',
+        '用法：',
+        '  maafw-live <command> [options]',
+        '',
+        '命令：',
+        ...COMMANDS.map((c) => `  ${pad(c.name, nameWidth + 2)}${c.summary}`),
+        '',
+        '全局选项：',
+        ...GLOBAL_HELP.map(([f, d]) => `  ${pad(f, 20)}${d}`),
+    ];
+}
+export function commandUsage(cmd) {
+    const lines = [cmd.summary, '', '用法：', '  ' + cmd.usage];
+    const own = Object.entries(cmd.options ?? {});
+    if (own.length > 0) {
+        lines.push('', '选项：');
+        for (const [flag, spec] of own) {
+            const isBool = spec.type === 'boolean';
+            lines.push(`  ${pad('--' + flag + (isBool ? '' : ' <value>'), 20)}`);
+        }
+    }
+    lines.push('', '全局选项：');
+    for (const [f, d] of GLOBAL_HELP)
+        lines.push(`  ${pad(f, 20)}${d}`);
+    return lines;
+}
+//# sourceMappingURL=usage.js.map

package/lib/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@windsland52/maafw-live",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "MaaFramework 设备交互与实时观测底座：常驻 daemon + 可复用客户端 + 确定性 CLI。不绑定宿主。",
+  "type": "module",
+  "bin": {
+    "maafw-live": "bin/maafw-live.mjs"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "files": [
+    "bin",
+    "lib",
+    "docs",
+    "skills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Windsland52/maafw-live.git"
+  },
+  "homepage": "https://github.com/Windsland52/maafw-live#readme",
+  "bugs": {
+    "url": "https://github.com/Windsland52/maafw-live/issues"
+  },
+  "keywords": [
+    "maaframework",
+    "maa",
+    "automation",
+    "agent",
+    "adb",
+    "win32",
+    "cli",
+    "daemon"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/daemon.d.ts",
+      "default": "./lib/client/daemon.js"
+    },
+    "./actions": {
+      "types": "./lib/types/runtime/actions.d.ts",
+      "default": "./lib/runtime/actions.js"
+    },
+    "./keyframes": {
+      "types": "./lib/types/runtime/keyframes.d.ts",
+      "default": "./lib/runtime/keyframes.js"
+    },
+    "./image": {
+      "types": "./lib/types/image.d.ts",
+      "default": "./lib/image.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-daemon.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify": "node scripts/verify-cli.mjs",
+    "test": "npm run build && node scripts/run-tests.mjs",
+    "accept:offline": "node scripts/accept-kf-offline.mjs",
+    "accept:crop": "node scripts/accept-crop-fromkf.mjs",
+    "survey:crop": "node scripts/survey-crop.mjs",
+    "survey:som": "node scripts/survey-som.mjs",
+    "accept": "node scripts/accept-emulator.mjs"
+  },
+  "dependencies": {
+    "@maaxyz/maa-node": "^5.14.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.0"
+  }
+}

package/skills/README.md

@@ -0,0 +1,51 @@
+# maafw-live Skills
+
+本目录是本仓随 npm 包一起发布的 Agent Skill。每个 skill 一个目录，含 `SKILL.md` 与可选的 `references/`。
+
+## 安装
+
+Skill 与 CLI 分开安装：装 CLI 不等于装 skill（反之亦然）。
+
+```bash
+# CLI（skill 里所有命令都要它；装 scoped 包名，敲裸命令名）
+npm install --global @windsland52/maafw-live@latest
+maafw-live version
+
+# skill（标准 skills CLI；列仓库里有哪些：--list）
+npx skills add https://github.com/Windsland52/maafw-live --list
+npx skills add https://github.com/Windsland52/maafw-live --skill maafw-live --global
+```
+
+本地开发时用 checkout 路径：`npx skills add . --skill maafw-live`（本地安装不跟随远端更新，改完重跑）。
+
+## Skill 与 CLI 的版本关系
+
+Skill 随包发布但**不写自己的版本号**——写死的版本每次发版都要改，而且从仓库装的副本仍然对不上。
+所以对齐用**比字节**，CLI 自带四条命令：
+
+```bash
+maafw-live skill                        # 包内 skill 位置与逐文件指纹
+maafw-live skill --check <安装根目录>    # 比对 <根>/maafw-live 与包内副本：same/different/missing/extra，有漂移退出 3
+maafw-live skill --install <根目录>      # 把包内副本逐字节写到 <根>/maafw-live（离线，不联网）
+maafw-live skill --print [--format json] # 输出包内副本内容（harness 自取，不想用 skills CLI 时）
+```
+
+`extra`（目标目录多出来的文件，例如 skills CLI 放进去的 agent 元数据）**不计漂移**；仅行尾不同（CRLF ↔ LF）
+仍算 `different`，但会标注成因，避免把工具改写误判成内容分叉。日常安装/更新仍推荐 skills CLI
+（它维护各 agent 的目录与符号链接），`--install` 是给"自己管一份副本"的 harness 用的。
+
+Skill 与文档冲突时，**以本仓 `docs/` 为准**：
+
+| 要知道什么 | 唯一出处 |
+| :--- | :--- |
+| daemon 命令、参数、返回字段 | [`docs/daemon-protocol.md`](../docs/daemon-protocol.md) |
+| 关键帧留存与引用语义（L0/L1/L2、升格、出处） | [`docs/keyframe-retention-contract-v0.md`](../docs/keyframe-retention-contract-v0.md) |
+| CLI 命令面、退出码、JSON 信封 | [`README.md`](../README.md) |
+| 字段/协议/版本的原始语义（不属于本工具） | MaaLLMWiki（版本锁定原文） |
+
+## 可用 Skill
+
+### `maafw-live`
+
+MaaFramework 应用的实时观测、识别实测、模板资产与状态证据留存。设备在线时给确定性观测；
+设备不在那个画面上（或根本没连）时，从关键帧库留存帧离线裁出带出处的模板。