@solazah/solazah-runtime 0.1.136 → 0.1.140

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solazah/solazah-runtime",
-  "version": "0.1.136",
+  "version": "0.1.140",
   "main": "index.cjs",
   "module": "index.js",
   "types": "types/index.d.ts",

package/types/Copilot.d.ts

@@ -64,6 +64,8 @@ export interface CopilotOptions extends CopilotChatOptions {
     tools?: any[];
     skills?: string[];
     chatModel?: any;
+    /** 本轮模型看得了图:主进程按模型标签定,决定要不要给 agent 装 view_image */
+    vision?: boolean;
     toolCallId?: string;
     /**
      * 编辑历史消息后重新生成：

package/types/File.d.ts

@@ -1,5 +1,13 @@
 import { default as IpcRenderer } from './IpcRenderer';
-export type WorkspaceCategory = "document" | "image" | "audio" | "video" | "blob";
+/**
+ * 文件分类。前五个是工作空间下的分类目录(文档/图片/音频/视频/.blob):**工作空间就是会同步的那一份**,
+ * 也会进知识库索引。`devicespace` 是账号目录下与工作空间同级的设备空间,不同步、不进索引、不跟人换机,
+ * 放只属于这台设备的东西(桌面录制、整屏采集、执行记录、本机缓存),成品仍放工作空间分类。
+ *
+ * 设备空间按插件分格,你只给格子内的相对路径 —— 插件名由宿主按调用方视图反查后自己拼,
+ * 所以既看不到别的插件的东西,也不必自己拼命名空间;卸载插件时宿主整格删掉。
+ */
+export type FileCategory = "document" | "image" | "audio" | "video" | "blob" | "devicespace";
 export interface FileEntry {
     name: string;
     path: string;
@@ -22,7 +30,7 @@ export interface FileListOptions {
     workspaceId?: string | null;
 }
 /**
- * window.file —— 工作空间分类目录(文档/图片/音频/视频/.blob)内的通用文件读写。
+ * window.file —— 分类目录内的通用文件读写:工作空间的文档/图片/音频/视频/.blob,外加设备空间 devicespace。
  * 寻址按「分类 + 相对路径」,主进程把路径钉死在分类目录内。watch 用每订阅独立频道接收变更,
  * 返回退订闭包(off 跨 contextBridge 失效,清理一律调返回值)。
  */
@@ -33,148 +41,148 @@ export default class File {
     /**
      * 读取分类目录下某个文本文件的全部内容(UTF-8)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 文件的 UTF-8 文本内容。
      * @throws 文件不存在、路径越界、分类未知或工作空间不可达时抛错。
      */
-    read: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<string>;
+    read: (category: FileCategory, relPath: string, workspaceId?: string | null) => Promise<string>;
     /**
      * 把文本内容写入分类目录下的相对路径，父目录不存在则自动创建(UTF-8 覆盖写)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
      * @param content      要写入的 UTF-8 文本内容。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 无返回。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    write: (category: WorkspaceCategory, relPath: string, content: string, workspaceId?: string | null) => Promise<void>;
+    write: (category: FileCategory, relPath: string, content: string, workspaceId?: string | null) => Promise<void>;
     /**
      * 读取分类目录下某个文件的二进制内容。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 文件的二进制内容(Buffer)。
      * @throws 文件不存在、路径越界、分类未知或工作空间不可达时抛错。
      */
-    readBinary: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<Uint8Array>;
+    readBinary: (category: FileCategory, relPath: string, workspaceId?: string | null) => Promise<Uint8Array>;
     /**
      * 把二进制数据写入分类目录下的相对路径，父目录不存在则自动创建(覆盖写)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
      * @param data         要写入的二进制数据(Uint8Array)。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 无返回。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    writeBinary: (category: WorkspaceCategory, relPath: string, data: Uint8Array, workspaceId?: string | null) => Promise<void>;
+    writeBinary: (category: FileCategory, relPath: string, data: Uint8Array, workspaceId?: string | null) => Promise<void>;
     /**
      * 列出分类目录(或其下子目录)的直接子项；软链会被跳过。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的子目录路径，`/` 分隔；默认 `""` 即分类根目录。越界会被拦截。
      * @param options      可选配置：`recursive` 为 `true` 时深度展开所有后代；`workspaceId` 指定工作空间。
      * @returns 子项列表(FileEntry[])，目录不存在时返回空数组。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    list: (category: WorkspaceCategory, relPath?: string, options?: FileListOptions) => Promise<FileEntry[]>;
+    list: (category: FileCategory, relPath?: string, options?: FileListOptions) => Promise<FileEntry[]>;
     /**
      * 取某个文件或目录的元信息(是否目录、大小、修改时间、创建时间)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 文件元信息(FileStat)；文件/目录不存在时返回 `null`。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    stat: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<FileStat | null>;
+    stat: (category: FileCategory, relPath: string, workspaceId?: string | null) => Promise<FileStat | null>;
     /**
      * 判断分类目录下的文件或目录是否存在。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 存在返回 `true`，否则返回 `false`。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    exists: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<boolean>;
+    exists: (category: FileCategory, relPath: string, workspaceId?: string | null) => Promise<boolean>;
     /**
      * 在分类目录下创建目录(递归创建缺失的父级)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 无返回。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    mkdir: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<void>;
+    mkdir: (category: FileCategory, relPath: string, workspaceId?: string | null) => Promise<void>;
     /**
      * 删除分类目录下的文件或目录(递归、强制)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；**不能为空**，否则拒绝删除分类根目录。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 无返回。
      * @throws relPath 为空时抛 `FILE_BAD_PATH`(400)；路径越界、分类未知或工作空间不可达时抛错。
      */
-    remove: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<void>;
+    remove: (category: FileCategory, relPath: string, workspaceId?: string | null) => Promise<void>;
     /**
      * 在同一分类目录内把文件或目录从 fromRel 移至 toRel(自动创建目标父目录)。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param fromRel      源路径，相对该分类目录，`/` 分隔；越界会被拦截。
      * @param toRel        目标路径，相对该分类目录，`/` 分隔；越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 无返回。
      * @throws 源/目标路径越界、分类未知或工作空间不可达时抛错。
      */
-    rename: (category: WorkspaceCategory, fromRel: string, toRel: string, workspaceId?: string | null) => Promise<void>;
+    rename: (category: FileCategory, fromRel: string, toRel: string, workspaceId?: string | null) => Promise<void>;
     /**
      * 把「分类 + 相对路径」解析成宿主机上的绝对路径。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；默认 `""` 即分类根目录。越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 宿主机绝对路径。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    resolve: (category: WorkspaceCategory, relPath?: string, workspaceId?: string | null) => Promise<string>;
+    resolve: (category: FileCategory, relPath?: string, workspaceId?: string | null) => Promise<string>;
     /**
      * 把「分类 + 相对路径」解析成 `file://` URL，供 `<img>` / `<video>` 等直接引用。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param relPath      相对该分类目录的路径，`/` 分隔；默认 `""` 即分类根目录。越界会被拦截。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns `file://` 协议 URL 字符串。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    fileUrl: (category: WorkspaceCategory, relPath?: string, workspaceId?: string | null) => Promise<string>;
+    fileUrl: (category: FileCategory, relPath?: string, workspaceId?: string | null) => Promise<string>;
     /**
      * 计算从 fromRel(目录)到 toRel 的相对路径(`/` 分隔)，跨分类可用——用于笔记内引用附件算可移植的相对引用。
      *
-     * @param fromCategory  源分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param fromCategory  源分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param fromRel       源路径(目录)，相对 fromCategory，`/` 分隔；越界会被拦截。
-     * @param toCategory    目标分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param toCategory    目标分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param toRel         目标路径，相对 toCategory，`/` 分隔；越界会被拦截。
-     * @param workspaceId   目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId   目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns `/` 分隔的相对路径字符串。
      * @throws 路径越界、分类未知或工作空间不可达时抛错。
      */
-    relativePath: (fromCategory: WorkspaceCategory, fromRel: string, toCategory: WorkspaceCategory, toRel: string, workspaceId?: string | null) => Promise<string>;
+    relativePath: (fromCategory: FileCategory, fromRel: string, toCategory: FileCategory, toRel: string, workspaceId?: string | null) => Promise<string>;
     /**
      * 订阅分类目录的文件变更通知(流式推送而非直接返回)。
      * 建立订阅后，目录内任何文件/子目录的增删改都会通过 IPC 频道 `file.watch.<watchId>` 推送给调用方所在渲染进程；
      * 同一 watchId 重复订阅时先关闭旧 watcher。渲染进程销毁时自动关闭其所有 watcher。
      *
-     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`。
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `blob`，或设备空间 `devicespace`。
      * @param watchId      订阅标识，用于后续 `file.unwatch` 取消订阅；也作为推送频道名的一部分。
-     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。`devicespace` 忽略它。
      * @returns 无返回(Promise  resolve 表示订阅已建立)。
      * @throws 分类未知或工作空间不可达时抛错。
      */
-    watch: (category: WorkspaceCategory, onChange: (change: FileChange) => void, workspaceId?: string | null) => (() => void);
+    watch: (category: FileCategory, onChange: (change: FileChange) => void, workspaceId?: string | null) => (() => void);
 }

package/types/Plugin.d.ts

@@ -79,6 +79,31 @@ export default class Plugin {
      * @returns 无返回。
      */
     floating: (options?: any) => Promise<any>;
+    /**
+     * 注册全局快捷键:系统级热键,焦点在别的程序上也触发;按下时本视图收到 `plugin.onShortcut` 事件
+     * (`window.ipcRenderer.on("plugin.onShortcut", (_e, id) => …)`),参数是这里给的 id。
+     * 同一 id 重复注册是覆盖;视图销毁时全部注销。被别的程序或宿主占着的键注册不上,返回值里对应 false。
+     *
+     * @param items `[{id, accelerator}]`,accelerator 用 Electron 写法(F10、CommandOrControl+Shift+K)。
+     * @returns `{id: 是否注册成功}`。
+     */
+    registerShortcuts: (items: Array<{
+        id: string;
+        accelerator: string;
+    }>) => Promise<Record<string, boolean>>;
+    /**
+     * 声明发起方窗口正忙(在录制、在执行任务):收起期间不被「收起超时自动关」回收,
+     * 否则藏在后台干活的视图会连窗口一起被关掉,活也就没了。忙完调 false 解除;窗口关掉时自动解除。
+     *
+     * @param busy 忙还是不忙。
+     */
+    setBusy: (busy: boolean) => Promise<void>;
+    /**
+     * 注销本视图注册的全局快捷键;不给 ids 就全部注销。
+     *
+     * @param ids 要注销的快捷键 id。
+     */
+    unregisterShortcuts: (ids?: string[]) => Promise<void>;
     /**
      * 收起发起方插件窗口。发起方是主窗口时回到启动器主页;
      * floating 浮窗做 cloak(不驱逐渲染表面,再唤起不白屏),普通窗口真正 hide()。
@@ -93,6 +118,13 @@ export default class Plugin {
      * @returns 切换后的置顶状态(boolean)。
      */
     toggleAlwaysOnTop: () => Promise<any>;
+    /**
+     * 把插件自己的窗口从截屏、录屏里排除(Windows 的 WDA_EXCLUDEFROMCAPTURE):屏幕上照常可见,
+     * 截图与录制帧里没有它。录自己的操作时开,免得录制页盖住画面、OCR 读到一堆自己的字。
+     *
+     * @param enabled 开或关。
+     */
+    setContentProtection: (enabled: boolean) => Promise<void>;
     /**
      * 取发起方插件自身的完整信息。
      * 通过 webContents 逆向定位插件,返回插件实体字段 + 其全部命令(commands 数组)+

package/types/PluginCommand.d.ts

@@ -4,6 +4,9 @@ export default class PluginCommand {
     constructor(transport?: IpcRenderer);
     /**
      * 按命令名打开对应插件命令：先查找命令，记录一次使用，然后委托 PluginRunner 打开。
+     * standard 窗口默认是开合切换(已可见且聚焦时再打开即收起);payload 里两个宿主认的字段改这个行为:
+     * `reveal: true` 一律唤起并聚焦(把收起的窗口叫回来用它),`showInactive: true` 唤起但不抢焦点
+     * (别的窗口正在被自动化操作时用)。其余字段原样送到 plugin.onEnter。
      *
      * @param commandName 命令名称。
      * @param payload 进入参数，透传给 PluginRunner。

package/types/SystemElevation.d.ts

@@ -0,0 +1,31 @@
+import { default as IpcRenderer } from './IpcRenderer';
+export interface ElevationStatus {
+    /** 此刻发出的输入与截屏带管理员权限:宿主自己提权,或提权助手活着 */
+    elevated: boolean;
+    /** 提权助手进程活着 */
+    helper: boolean;
+    /** 宿主进程本身就带管理员权限 */
+    hostElevated: boolean;
+}
+export default class SystemElevation {
+    private transport;
+    constructor(transport?: IpcRenderer);
+    /**
+     * 让接下来的输入注入、截屏、找图找字、窗口唤起、起进程都带管理员权限。
+     * 宿主自己提权就直接返回;否则拉起提权助手进程,第一次弹系统授权框(UAC),之后整个会话都不再问。
+     * 以管理员身份运行的程序(游戏平台、游戏客户端、任务管理器等)只认同级或更高权限发来的输入与截屏,
+     * 录制、回放它们之前先调这个。
+     *
+     * @returns `{elevated, helper, hostElevated}`。
+     * @throws 用户在授权框上取消、助手起不来时抛错。
+     */
+    ensure: () => Promise<ElevationStatus>;
+    /**
+     * 此刻的权限状态,不会弹授权框。
+     */
+    status: () => Promise<ElevationStatus>;
+    /**
+     * 让提权助手退出;之后的输入与截屏回到宿主自己执行,下一次 ensure 会再弹一次授权框。
+     */
+    release: () => Promise<void>;
+}

package/types/SystemRecorder.d.ts

@@ -6,6 +6,8 @@ export interface RecorderStartOptions {
     stopKey?: number;
     /** 时长上限,缺省 10 分钟 */
     maxMs?: number;
+    /** 以管理员身份录制:经 UAC 拉起助手进程,能录到提权程序(游戏等)的画面与操作;用户在授权框上取消就抛错 */
+    elevated?: boolean;
 }
 export interface RecorderStatus {
     supported: boolean;
@@ -14,47 +16,63 @@ export interface RecorderStatus {
     elapsedMs: number;
     events: number;
     frames: number;
-    /** 运行中的反作弊进程名;有它在时低层钩子整体收不到输入 */
-    antiCheat: string[];
+    /** 这次录制带管理员权限 */
+    elevated: boolean;
+}
+export interface RecorderCapabilities {
+    supported: boolean;
+    /** 宿主自己就带管理员权限,不需要再授权 */
+    elevated: boolean;
+    /** 此刻以管理员身份运行的窗口标题:不授权就录不到它们 */
+    elevatedWindows: string[];
 }
 export interface RecorderResult {
     id: string;
     /** 轨迹目录绝对路径 */
     dir: string;
-    /** 轨迹目录在工作空间「图片」目录下的相对路径:scripts/_recordings/<id> */
+    /** 轨迹目录在本插件设备空间下的相对路径:recordings/<id> */
     relPath: string;
     events: number;
     frames: number;
     durationMs: number;
     stoppedBy: "hotkey" | "api" | "timeout";
+    elevated: boolean;
 }
 export default class SystemRecorder {
     private transport;
     constructor(transport?: IpcRenderer);
     /**
      * 开始录制用户操作:低层钩子收鼠标键盘、定时截主屏,每个按下/抬起/按键带上前后帧与那一刻的前台窗口。
-     * 只记事实,不做任何手势归并;录制期间每一拍向发起方视图推 `recorder.progress`(RecorderStatus)。
-     * 产物落在工作空间「图片」目录 scripts/_recordings/<id>/:trajectory.json + frames/*.png。
+     * 只记事实,不做任何手势归并;录制期间每一拍向发起方视图推 `recorder.progress`(RecorderStatus),
+     * 收尾(F12、超时、stop)写完轨迹后推一次 `recorder.stopped`(RecorderResult),用 ipcRenderer.on 接;
+     * 录制没有产物就中断了(管理员助手退出)只推一次 active=false 的 `recorder.progress`。
+     * 产物落在**本插件的设备空间**里 recordings/<id>/:trajectory.json + frames/*.jpg —— 录到的是整屏画面
+     * 与窗口标题,只属于这台设备,不进工作空间;用 window.file 的 `devicespace` 分类按同样的相对路径读写。
      *
-     * @param options `{fps?, stopKey?, maxMs?}`,缺省 4 帧/秒、F12 结束、10 分钟上限。
-     * @returns `{id, dir, relPath, antiCheat}`;antiCheat 非空表示有反作弊进程在跑,钩子会整体收不到输入。
-     * @throws 平台不支持(目前仅 Windows)、已有录制在进行、钩子安装失败时抛错。
+     * @param options `{fps?, stopKey?, maxMs?, elevated?}`,缺省 4 帧/秒、F12 结束、10 分钟上限;
+     *   elevated 为真时经 UAC 申请管理员权限,先用 capabilities() 看要不要。
+     * @returns `{id, dir, relPath, elevated}`。
+     * @throws 平台不支持(目前仅 Windows)、已有录制在进行、钩子安装失败、用户在授权框上取消时抛错。
      */
     start: (options?: RecorderStartOptions) => Promise<{
         id: string;
         dir: string;
         relPath: string;
-        antiCheat: string[];
+        elevated: boolean;
     }>;
     /**
      * 结束录制并写出轨迹。按 stopKey 结束的录制不必再调。
      *
-     * @returns `{id, dir, relPath, events, frames, durationMs, stoppedBy}`。
+     * @returns `{id, dir, relPath, events, frames, durationMs, stoppedBy, elevated}`。
      * @throws 没有进行中的录制时抛错。
      */
     stop: () => Promise<RecorderResult>;
     /**
-     * 录制状态:是否支持、是否进行中、已录事件数与帧数、运行中的反作弊进程。
+     * 录制状态:是否支持、是否进行中、已录事件数与帧数、是否带管理员权限。
      */
     status: () => Promise<RecorderStatus>;
+    /**
+     * 开录前问一次:宿主是否已带管理员权限、此刻有哪些以管理员身份运行的窗口(游戏等,不授权就录不到它们)。
+     */
+    capabilities: () => Promise<RecorderCapabilities>;
 }

package/types/SystemScreen.d.ts

@@ -22,11 +22,46 @@ export interface WaitOptions {
     timeoutMs?: number;
     /** 缺省 500 */
     intervalMs?: number;
+    /** 取消记号:中途调 cancelWait(token) 就以 cancelled 收尾,不再等到超时;同一记号可盖住一次任务里的全部等待 */
+    token?: string;
 }
 export interface FindTextOptions {
     searchRegion?: ScreenRect;
     /** OCR 检测缩放比,小于 1 更快但更粗 */
     detRatio?: number;
+    /** OCR 前把画面放大几倍:字高不到 14 像素时 1.5 能把认错的字认回来,代价三成时间 */
+    zoom?: number;
+}
+/**
+ * 找图的结果。找不到不是异常:found 为假时 best 是搜索区域里最像的那块与它的分数,对着 threshold 看是阈值太严还是模板过时;
+ * 区域比模板还小时 best 为 null。attempts 是查了几次(找一次就是 1),cancelled 说明是被取消记号中断的。
+ */
+export interface ImageSearch {
+    found: boolean;
+    rect: ScreenRect | null;
+    best: (ScreenRect & {
+        score: number;
+    }) | null;
+    threshold: number;
+    attempts: number;
+    timeoutMs: number | null;
+    cancelled: boolean;
+}
+/** 找字的结果。found 为假时 visibleTexts 是这次 OCR 认到的全部文字,据此改目标词而不是盲试。 */
+export interface TextSearch {
+    found: boolean;
+    rect: ScreenRect | null;
+    visibleTexts: string[];
+    attempts: number;
+    timeoutMs: number | null;
+    cancelled: boolean;
+}
+/** 等图像消失的结果。 */
+export interface GoneWait {
+    gone: boolean;
+    attempts: number;
+    timeoutMs: number;
+    cancelled: boolean;
 }
 export default class SystemScreen {
     private transport;
@@ -63,14 +98,13 @@ export default class SystemScreen {
      */
     getCursorPoint: () => Promise<any>;
     /**
-     * 在当前屏幕中查找与模板图片匹配的区域,返回屏幕原生坐标系里的矩形。
+     * 在当前屏幕中找一次模板图片。
      *
      * @param base64String 模板图片的 Base64(支持 `data:image/...;base64,` 前缀)。
      * @param options      `{confidence?, searchRegion?, scale?}`;scale 省略时按常见显示缩放自适应。
-     * @returns 匹配矩形 `{x, y, width, height}`。
-     * @throws 未达阈值时抛错,信息里带最佳候选分数与位置。
+     * @returns 结果对象;找不到不是异常,看 found 与 best。
      */
-    find: (base64String: string, options?: FindImageOptions) => Promise<ScreenRect>;
+    find: (base64String: string, options?: FindImageOptions) => Promise<ImageSearch>;
     /**
      * 找出屏幕上模板图片的所有命中,按匹配分数降序。
      *
@@ -80,50 +114,53 @@ export default class SystemScreen {
      */
     findAll: (base64String: string, options?: FindImageOptions) => Promise<ScreenRect[]>;
     /**
-     * 轮询屏幕直到模板图片出现,返回其矩形。
+     * 轮询屏幕直到模板图片出现。
      *
      * @param base64String 模板图片的 Base64。
-     * @param options      查找参数外加 `{timeoutMs?, intervalMs?}`,缺省 5000 / 500。
-     * @returns 匹配矩形 `{x, y, width, height}`。
-     * @throws 超时仍未出现时抛错。
+     * @param options      查找参数外加 `{timeoutMs?, intervalMs?, token?}`,缺省 5000 / 500。
+     * @returns 同 find;超时或被取消时 found 为假,attempts 是查了几次。
      */
-    waitFor: (base64String: string, options?: FindImageOptions & WaitOptions) => Promise<ScreenRect>;
+    waitFor: (base64String: string, options?: FindImageOptions & WaitOptions) => Promise<ImageSearch>;
     /**
      * 轮询屏幕直到模板图片消失。
      *
      * @param base64String 模板图片的 Base64。
-     * @param options      查找参数外加 `{timeoutMs?, intervalMs?}`。
-     * @returns 无返回。
-     * @throws 超时仍在屏幕上时抛错。
+     * @param options      查找参数外加 `{timeoutMs?, intervalMs?, token?}`。
+     * @returns `{gone, attempts, timeoutMs, cancelled}`;超时仍在屏幕上时 gone 为假,不抛错。
      */
-    waitUntilGone: (base64String: string, options?: FindImageOptions & WaitOptions) => Promise<void>;
+    waitUntilGone: (base64String: string, options?: FindImageOptions & WaitOptions) => Promise<GoneWait>;
     /**
-     * 用 OCR 在屏幕上找一段文字,返回该词的矩形。
+     * 用 OCR 在屏幕上找一次文字。
      *
      * @param text    目标文字,整词匹配。
-     * @param options `{searchRegion?, detRatio?}`。
-     * @returns 文字矩形 `{x, y, width, height}`。
-     * @throws 未找到时抛错,信息里带当前屏幕可见的文字列表。
+     * @param options `{searchRegion?, detRatio?, zoom?}`。
+     * @returns 结果对象;找不到不是异常,visibleTexts 是这次认到的全部文字。
      */
-    findText: (text: string, options?: FindTextOptions) => Promise<ScreenRect>;
+    findText: (text: string, options?: FindTextOptions) => Promise<TextSearch>;
     /**
-     * 轮询屏幕直到指定文字出现,返回该词的矩形。
+     * 轮询屏幕直到指定文字出现。
      *
      * @param text    目标文字,整词匹配。
-     * @param options `{searchRegion?, detRatio?, timeoutMs?, intervalMs?}`。
-     * @returns 文字矩形 `{x, y, width, height}`。
-     * @throws 超时仍未出现时抛错,信息里带当前屏幕可见的文字列表。
+     * @param options `{searchRegion?, detRatio?, zoom?, timeoutMs?, intervalMs?, token?}`。
+     * @returns 同 findText;超时或被取消时 found 为假,visibleTexts 是最后一次认到的文字。
      */
-    waitForText: (text: string, options?: FindTextOptions & WaitOptions) => Promise<ScreenRect>;
+    waitForText: (text: string, options?: FindTextOptions & WaitOptions) => Promise<TextSearch>;
+    /**
+     * 取消带该记号的等待(等图、等文字、等窗口、等图像消失):它们下一拍就以 cancelled(等窗口是 null)收尾,不再等到超时。
+     * 记号是调用方在 WaitOptions.token 里给的字符串,同一个记号可以盖住一次任务执行里的全部等待。
+     */
+    cancelWait: (token: string) => Promise<void>;
     /**
      * 对显示器(或其中一块区域)做 OCR,返回每段文字及其屏幕坐标矩形。
      *
-     * @param options `{display?, region?}`,region 为该显示器物理像素坐标;缺省光标所在显示器整屏。
+     * @param options `{display?, region?, image?, zoom?}`,region 为该显示器物理像素坐标;缺省光标所在显示器整屏;zoom 大于 1 先放大再认。
      * @returns `[{text, score, x, y, width, height}]`,坐标已加上显示器原点。
      */
     recognizeText: (options?: {
         display?: number;
         region?: ScreenRect;
+        image?: string;
+        zoom?: number;
     }) => Promise<Array<ScreenRect & {
         text: string;
         score: number;
@@ -140,6 +177,7 @@ export default class SystemScreen {
         textBoxes?: ScreenRect[];
         minSide?: number;
         maxSide?: number;
+        image?: string;
     }) => Promise<Array<ScreenRect & {
         pixels: number;
     }>>;
@@ -160,6 +198,39 @@ export default class SystemScreen {
         score: number;
         scale: number;
     }>>;
+    /**
+     * 对一帧给定图片做一批分析:若干模板各自匹配、若干区域各自 OCR,图片只解码一次,同一区域只 OCR 一次。
+     * 每一拍截一帧、拿这一帧判断全部条件的循环靠它把 IPC 压到每拍一次。
+     *
+     * @param frame   被分析图片的 Base64(整个显示器的截图)。
+     * @param request `{templates?: [{id, image, region?, scale?, minScore?, maxResults?}], texts?: [{id, region?, detRatio?, zoom?}]}`,region 相对图片左上角。
+     * @returns `{templates: {id: [{x, y, width, height, score, scale}]}, texts: {id: [{text, score, x, y, width, height}]}}`,坐标相对图片左上角。
+     */
+    analyzeFrame: (frame: string, request?: {
+        templates?: Array<{
+            id: string;
+            image: string;
+            region?: ScreenRect;
+            scale?: number;
+            minScore?: number;
+            maxResults?: number;
+        }>;
+        texts?: Array<{
+            id: string;
+            region?: ScreenRect;
+            detRatio?: number;
+            zoom?: number;
+        }>;
+    }) => Promise<{
+        templates: Record<string, Array<ScreenRect & {
+            score: number;
+            scale: number;
+        }>>;
+        texts: Record<string, Array<ScreenRect & {
+            text: string;
+            score: number;
+        }>>;
+    }>;
     /**
      * 两张同尺寸截图的差异包围框。
      *

package/types/SystemWindow.d.ts

@@ -130,6 +130,7 @@ export default class SystemWindow {
         execPath?: string;
         timeoutMs?: number;
         intervalMs?: number;
+        token?: string;
     }) => Promise<{
         id: number;
         title: string;