@windsland52/maafw-live 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,117 @@
+import type { CommandResult } from '../protocol.js';
+/** 会话名白名单：字母数字与 `-` `_`，1..48 字符。要进管道名与文件路径，必须收紧。 */
+export declare function validSessionName(name: string): boolean;
+/** 会话目录：`~/.maafw-live/sessions/<name>/`（与 frames 同级，都是本工具的本地状态）。 */
+export declare function sessionDir(name: string): string;
+/** Windows 命名管道名；其它平台用 Unix domain socket 文件（同一份代码，两个平台都能跑）。
+ *
+ * ⚠️ 返回 Unix socket **路径**时会落在 `sessionDir(name)/sock` 下，所以调用方必须先确保
+ * 该目录存在（`ensureSessionDir`）——`listen()` 对不存在的父目录直接 ENOENT。
+ * Windows 命名管道在 `\\.\pipe\` 命名空间里，与文件系统无关，不需要建目录。 */
+export declare function sessionPipePath(name: string): string;
+/** 平台无关的"管道父目录就绪"：Windows 上是空操作（命名管道不走文件系统）。 */
+export declare function ensureSessionDir(name: string): void;
+export interface SessionMeta {
+    name: string;
+    pid: number;
+    pipe: string;
+    startedAt: string;
+    /** 起会话时给的连接参数，便于诊断"为什么这条会话连的是别的设备" */
+    connectArgs: Record<string, unknown>;
+    /** 起会话的 CLI 版本（npm test / npm install 升级后老会话仍跑旧 lib，版本钉进 meta 让"混版"可见） */
+    cliVersion?: string;
+}
+export declare function sessionMetaPath(name: string): string;
+export declare function readSessionMeta(name: string): SessionMeta | null;
+/** 进程还活着吗（`process.kill(pid, 0)` 不真发信号，只做存在性检查）。 */
+export declare function pidAlive(pid: number): boolean;
+/** 一条命令的请求/回执信封。`lines` 是 repl 该命令打出的全部输出行（按序）。
+ *
+ * 协议 v2：请求可以是 `line`（旧，走 REPL 行解释器）或 `exec`（argv，走 dispatchArgv
+ * 拿到结构化 CommandResult）——信封丢结构化结果（`--session` 下 `--json` 只剩 {name,pid}）
+ * 就是因为只有 line 这条路。 */
+export interface ServeRequest {
+    id: number;
+    /** 缺省按 line 处理（兼容旧调用方） */
+    kind?: 'line' | 'exec';
+    line?: string;
+    argv?: string[];
+}
+export interface ServeReply {
+    id: number;
+    ok: boolean;
+    lines: string[];
+    error?: string;
+    /** exec 请求的结构化结果（v2）；line 请求没有这个字段 */
+    result?: CommandResult;
+    /** `quit`/`exit` 之后常驻进程会自行收尾 */
+    closing?: boolean;
+}
+/** 常驻侧回执的**调用方可见部分**：`lines` 由服务端从已收集的输出填，调用方不必传
+ * （显式给 `lines: []` 也不报错——服务端一律以自己的缓冲为准，避免两处都以为自己说了算）。 */
+export interface ServeReplyInput {
+    ok: boolean;
+    lines?: string[];
+    error?: string;
+    /** exec 请求的结构化结果（v2） */
+    result?: CommandResult;
+    /** `quit`/`exit` 之后常驻进程会自行收尾 */
+    closing?: boolean;
+}
+/** 常驻侧：把 repl 的输出按"命令"切段回给调用方。 */
+export declare class SessionServer {
+    private readonly onLine;
+    private readonly onExec?;
+    private server;
+    private readonly sockets;
+    /** 串行队列：会话共用一条设备连接，命令必须一条条跑完再下一条 */
+    private readonly pending;
+    private buffer;
+    private current;
+    /**
+     * @param onLine  REPL 行解释器（旧 kind=line 路径）
+     * @param onExec  argv 分发器（kind=exec）：注入常驻 client 后走 dispatchArgv，
+     *                回执里带结构化 CommandResult——`--session` 下的 --json 信封靠它才存在。
+     *                不给时 exec 请求回 UNSUPPORTED（防"静默按 line 跑了别的命令"）。
+     */
+    constructor(onLine: (line: string, reply: (r: ServeReplyInput) => void) => void, onExec?: ((argv: string[], reply: (r: ServeReplyInput) => void) => void) | undefined);
+    /** 供 repl 循环调用：把一行输出归到当前命令的回执里。
+     *
+     * **没有当前命令时不是丢弃，而是挂到"待认领"队列**：`run` 这类命令是异步收尾的
+     * （提交后立刻返回，`run 完成…` 稍后才打），而回执在那之前就发出去了——丢掉的话
+     * 调用方永远看不到任务结果。挂起来随下一条命令的回执一起给，轮询式用法正好能拿到。
+     * 队列有上限：没人认领时不能无限涨（常驻会话可能几天没人问）。 */
+    pushOutput(line: string): void;
+    /** 连接横幅等：等价于"还没有命令时打的输出"，与异步收尾共用同一条待认领队列。 */
+    pushStartup(line: string): void;
+    private readonly unclaimed;
+    private reply;
+    listen(pipe: string): Promise<void>;
+    close(): void;
+}
+/** 调用侧：把一条命令送到已存在的会话，等它那条回执。 */
+export declare function sendToSession(meta: SessionMeta, line: string, timeoutMs: number): Promise<ServeReply>;
+/** 调用侧（v2）：把一条 argv 送到会话，等它那条带结构化 result 的回执。
+ * 与 sendToSession 共用同一条管道/协议，只是 kind/载荷不同。 */
+export declare function sendToSessionExec(meta: SessionMeta, argv: string[], timeoutMs: number): Promise<ServeReply>;
+/** 起一个脱离父进程的常驻会话（`--session-serve` 模式）。
+ *
+ * `stdio` 不能是 `'ignore'`：常驻进程起不来时（最典型的是 POSIX 上残留 socket 导致
+ * listen 失败），调用方只会看到"管道 20s 内不可连"，真因被吞掉——而 `listen` 的 EADDRINUSE
+ * 与"连接参数错"是完全不同的两件事。所以把它自己的 stdout/stderr 落到会话目录的
+ * `serve.log`，失败时读回来当诊断依据。 */
+export declare function spawnSessionServer(name: string, cliEntry: string, connectArgs: Record<string, unknown>): SessionMeta;
+/** 读常驻进程自己的日志尾部（诊断"为什么起不来"）。 */
+export declare function sessionServeLogTail(name: string, lines?: number): string[];
+/** 连接参数 → argv（会话常驻进程用同一套 CLI 旗标启动，不另造一套参数面）。
+ *  布尔值只发裸旗标：`--raw true` 里的 `true` 会被 parseArgs 当成位置参数（用法错误），
+ *  而且"false"是字符串真值，传成参数就把语义反了。 */
+export declare function connectArgsToArgv(a: Record<string, unknown>): string[];
+/** 等管道可连（常驻进程起来要时间；轮询到超时为止，不靠固定 sleep）。 */
+export declare function waitPipeReady(pipe: string, timeoutMs: number): Promise<boolean>;
+/** 收掉一条会话（清 meta 与目录，管道随进程退出消失）。
+ * 进程树：server → daemon → agent（uv → venv-python → uv-python）。process.kill 只打
+ * 第一层——daemon 来不及收摊就死，agent 树整体孤儿化（实测两层 python 残留）。
+ * taskkill /T 按父链整棵收；uv 重 exec 出的中层会脱离父链漏掉，再补一刀：命令行带
+ * agent/main.py 且父进程已死的全是孤儿（活会话的 agent 父链必健在，不会误伤）。 */
+export declare function stopSession(name: string): void;

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

@@ -0,0 +1,77 @@
+/**
+ * 会话装配：一次性命令如何在同一个 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;
+    /**
+     * 跑 interface.json 的 pretask。**显式开启**：只有"启动工作"类命令（run / 交互式与命名
+     * 会话的起连 / REPL connect project）该跑——观测与输入类命令（click / frame / wait / screencap）
+     * 经 ensureSession 隐式连接，跑一遍"重启游戏"类 pretask 会把正要观测的现场毁掉（设计审查 P0-2）。
+     * `false` 也显式关闭（`--no-pretask`）。未传 = 不跑。
+     */
+    pretask?: boolean;
+    /** run 的按次取值：pretask 的末位 JSON 也用这两份 */
+    optionCases?: Record<string, string | string[]>;
+    optionFields?: Record<string, Record<string, string>>;
+    /** CLI 的 --cwd：`--resource` 给相对路径时按它解析（不是 interface.json 目录、不是 process.cwd()） */
+    cwd?: string;
+}
+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（后者要扫设备）。
+ *
+ * 返回的是**整条链**（`resource.path[]` 按序叠加，末尾追加当前控制器的 `attach_resource_path`），
+ * 与在线规划同一份 `resolveResourcePaths`：只写 `resource.path` 会让 attach 进来的一段凭空消失。
+ */
+export declare function offlineResource(project: string, controller?: string, resource?: string, 
+/** `--resource` 相对路径的解析基准（CLI 的 --cwd） */
+cwd?: string): {
+    paths: string[];
+    names: string[];
+    selected: string | null;
+    controllerName: string | null;
+    error?: string;
+};
+/**
+ * 连接结果的行渲染（human 输出与 --json 共用一份事实）。
+ * `verbose=false` 时压制 `note:` 行（多资源选择、连接来源等建议性说明）——
+ * 一次性命令每条都打同一串 note 是噪音；事实行（已连接/分辨率/资源路径）不受门控。
+ */
+export declare function describeSession(s: SessionState, verbose?: boolean): string[];

package/lib/types/runtime/signal-guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * run 阻塞期信号处理（审计 #6/#9）：Ctrl-C / SIGTERM 时不许让 daemon 里的任务裸跑。
+ *
+ * 第一下：向 daemon 发 run_stop（post_stop），run 回执照常落盘，退出码走 128+signo
+ * （SIGINT=130 / SIGTERM=143）。第二下：直接退出——第一次没杀掉说明 daemon 已不应答，
+ * 再等没有现场可留（daemon 侧另有 onHostGone 兜底清 agent 树）。
+ *
+ * 为什么抽出来：Windows 没法跨进程投递 Ctrl-C，内联在命令里就没法测；
+ * process.emit('SIGINT') 会同步触发监听，单测只验"旗标立了、run_stop 发了"。
+ */
+import { type ExitCode } from '../protocol.js';
+export interface RunSignalGuard {
+    /** 当前命中的信号对应的退出码；0 = 没被打断 */
+    readonly code: ExitCode | 0;
+    /** 摘钩子并返回最终 code（run 回执渲染前调用） */
+    restore(): ExitCode | 0;
+}
+/** 挂载信号守卫；`runStop` 是"给 daemon 发停止"的那个异步调用。 */
+export declare function installRunSignalGuard(runStop: () => Promise<unknown>): RunSignalGuard;

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/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', '未实现：传了退 2（不接受假装生效）'],
+    ['--limit <n>', '未实现：传了退 2（events 有自己的 --limit）'],
+    ['--verbose', '未实现：传了退 2'],
+    ['-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/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@windsland52/maafw-live",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.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",
+    "!lib/**/*.map",
+    "skills",
+    "docs/daemon-protocol.md",
+    "docs/keyframe-retention-contract-v0.md",
+    "docs/session-unify-v0.md"
+  ],
+  "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"
+    },
+    "./reco-args": {
+      "types": "./lib/types/runtime/reco-args.d.ts",
+      "default": "./lib/runtime/reco-args.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",
+    "test:all": "npm run build && node scripts/run-tests.mjs --group all",
+    "test:device": "npm run build && node scripts/run-tests.mjs --group device",
+    "test:contract": "npm run build && node scripts/run-tests.mjs --group contract",
+    "skill:check": "node scripts/skill-check.mjs",
+    "accept:offline": "node scripts/accept-kf-offline.mjs",
+    "accept:crop": "node scripts/accept-crop-fromkf.mjs",
+    "accept:roi-compare": "node scripts/accept-roi-compare.mjs",
+    "accept:reco-node": "node scripts/accept-reco-node.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 应用的实时观测、识别实测、模板资产与状态证据留存。设备在线时给确定性观测；
+设备不在那个画面上（或根本没连）时，从关键帧库留存帧离线裁出带出处的模板。