@solazah/solazah-runtime 0.1.124 → 0.1.134

package/package.json

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

package/types/Plugin.d.ts

@@ -4,6 +4,11 @@ export interface PluginTool {
     cb: (args: any) => Promise<string> | string;
     description: string;
     schema: object | null;
+    timeoutMs?: number;
+}
+export interface PluginToolOptions {
+    /** 宿主等待回执的上限(毫秒),给执行耗时长的工具(如跑一段脚本)用 */
+    timeoutMs?: number;
 }
 export default class Plugin {
     private ipcRenderer;
@@ -15,14 +20,16 @@ export default class Plugin {
         name: string;
         description: string;
         schema: object | null;
+        timeoutMs: number | undefined;
     }[];
     /**
      * 给 Otta 注册 AI 工具。
      * schema 传 JSON Schema 对象(如 z.toJSONSchema(...) 的返回值),无参工具传 null;
      * cb 收到已按 schema 拆包的参数对象(无参工具收到 {}),返回字符串给 LLM(返回对象会被 JSON.stringify)。
+     * options.timeoutMs 是宿主等待回执的上限,执行耗时长的工具要显式给。
      * 同名重复注册为覆盖(HMR 安全)。
      */
-    tool: (name: string, description: string, schema: object | null, cb: (args: any) => Promise<string> | string) => (args: any) => Promise<string> | string;
+    tool: (name: string, description: string, schema: object | null, cb: (args: any) => Promise<string> | string, options?: PluginToolOptions) => (args: any) => Promise<string> | string;
     onSearch: (commandName: string, handler: any) => Promise<void>;
     onAction: (commandName: string, action: string, handler: any) => Promise<void>;
     /**

package/types/SystemMouse.d.ts

@@ -57,4 +57,26 @@ export default class SystemMouse {
      * @returns 操作完成后兑现的 Promise。
      */
     rightClickAt: (point: Point) => Promise<any>;
+    /**
+     * 按住鼠标从 from 拖到 to 再松开。
+     *
+     * @param from    起点屏幕坐标 `{x, y}`。
+     * @param to      终点屏幕坐标 `{x, y}`。
+     * @param options `{button?, smooth?, durationMs?}`;smooth 为真时按插值路径逐步移动,给靠 mousemove 判定拖拽的应用用。
+     * @returns 无返回。
+     */
+    drag: (from: Point, to: Point, options?: {
+        button?: "left" | "right" | "middle";
+        smooth?: boolean;
+        durationMs?: number;
+    }) => Promise<any>;
+    /**
+     * 滚动滚轮。
+     *
+     * @param dx 水平格数,正数向右。
+     * @param dy 垂直格数,正数向上。
+     * @param at 可选,先把鼠标移到此屏幕坐标再滚。
+     * @returns 无返回。
+     */
+    scroll: (dx: number, dy: number, at?: Point) => Promise<any>;
 }

package/types/SystemRecorder.d.ts

@@ -0,0 +1,60 @@
+import { default as IpcRenderer } from './IpcRenderer';
+export interface RecorderStartOptions {
+    /** 帧率,缺省 4 */
+    fps?: number;
+    /** 结束录制的键(虚拟键码),缺省 F12;这一下本身不进轨迹 */
+    stopKey?: number;
+    /** 时长上限,缺省 10 分钟 */
+    maxMs?: number;
+}
+export interface RecorderStatus {
+    supported: boolean;
+    active: boolean;
+    id: string | null;
+    elapsedMs: number;
+    events: number;
+    frames: number;
+    /** 运行中的反作弊进程名;有它在时低层钩子整体收不到输入 */
+    antiCheat: string[];
+}
+export interface RecorderResult {
+    id: string;
+    /** 轨迹目录绝对路径 */
+    dir: string;
+    /** 轨迹目录在工作空间「图片」目录下的相对路径:scripts/_recordings/<id> */
+    relPath: string;
+    events: number;
+    frames: number;
+    durationMs: number;
+    stoppedBy: "hotkey" | "api" | "timeout";
+}
+export default class SystemRecorder {
+    private transport;
+    constructor(transport?: IpcRenderer);
+    /**
+     * 开始录制用户操作:低层钩子收鼠标键盘、定时截主屏,每个按下/抬起/按键带上前后帧与那一刻的前台窗口。
+     * 只记事实,不做任何手势归并;录制期间每一拍向发起方视图推 `recorder.progress`(RecorderStatus)。
+     * 产物落在工作空间「图片」目录 scripts/_recordings/<id>/:trajectory.json + frames/*.png。
+     *
+     * @param options `{fps?, stopKey?, maxMs?}`,缺省 4 帧/秒、F12 结束、10 分钟上限。
+     * @returns `{id, dir, relPath, antiCheat}`;antiCheat 非空表示有反作弊进程在跑,钩子会整体收不到输入。
+     * @throws 平台不支持(目前仅 Windows)、已有录制在进行、钩子安装失败时抛错。
+     */
+    start: (options?: RecorderStartOptions) => Promise<{
+        id: string;
+        dir: string;
+        relPath: string;
+        antiCheat: string[];
+    }>;
+    /**
+     * 结束录制并写出轨迹。按 stopKey 结束的录制不必再调。
+     *
+     * @returns `{id, dir, relPath, events, frames, durationMs, stoppedBy}`。
+     * @throws 没有进行中的录制时抛错。
+     */
+    stop: () => Promise<RecorderResult>;
+    /**
+     * 录制状态:是否支持、是否进行中、已录事件数与帧数、运行中的反作弊进程。
+     */
+    status: () => Promise<RecorderStatus>;
+}

package/types/SystemScreen.d.ts

@@ -1,5 +1,33 @@
 import { default as IpcRenderer } from './IpcRenderer';
 import { Point } from '@computer-use/nut-js';
+/** 屏幕原生坐标系里的矩形。 */
+export interface ScreenRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FindImageOptions {
+    /** 匹配阈值 0..1,缺省 0.8 */
+    confidence?: number;
+    /** 只在此区域内找,结果仍是屏幕坐标 */
+    searchRegion?: ScreenRect;
+    /** 固定模板缩放;省略则按常见显示缩放自适应 */
+    scale?: number;
+    /** findAll 最多返回几个 */
+    maxResults?: number;
+}
+export interface WaitOptions {
+    /** 缺省 5000 */
+    timeoutMs?: number;
+    /** 缺省 500 */
+    intervalMs?: number;
+}
+export interface FindTextOptions {
+    searchRegion?: ScreenRect;
+    /** OCR 检测缩放比,小于 1 更快但更粗 */
+    detRatio?: number;
+}
 export default class SystemScreen {
     private transport;
     constructor(transport?: IpcRenderer);
@@ -35,33 +63,116 @@ export default class SystemScreen {
      */
     getCursorPoint: () => Promise<any>;
     /**
-     * 在当前屏幕中查找与给定模板图片匹配的区域,返回匹配区域中心坐标。
-     * 使用 nut-js 图像匹配引擎在屏幕中搜索模板。
+     * 在当前屏幕中查找与模板图片匹配的区域,返回屏幕原生坐标系里的矩形。
+     *
+     * @param base64String 模板图片的 Base64(支持 `data:image/...;base64,` 前缀)。
+     * @param options      `{confidence?, searchRegion?, scale?}`;scale 省略时按常见显示缩放自适应。
+     * @returns 匹配矩形 `{x, y, width, height}`。
+     * @throws 未达阈值时抛错,信息里带最佳候选分数与位置。
+     */
+    find: (base64String: string, options?: FindImageOptions) => Promise<ScreenRect>;
+    /**
+     * 找出屏幕上模板图片的所有命中,按匹配分数降序。
+     *
+     * @param base64String 模板图片的 Base64。
+     * @param options      `{confidence?, searchRegion?, scale?, maxResults?}`。
+     * @returns 匹配矩形数组,可能为空。
+     */
+    findAll: (base64String: string, options?: FindImageOptions) => Promise<ScreenRect[]>;
+    /**
+     * 轮询屏幕直到模板图片出现,返回其矩形。
+     *
+     * @param base64String 模板图片的 Base64。
+     * @param options      查找参数外加 `{timeoutMs?, intervalMs?}`,缺省 5000 / 500。
+     * @returns 匹配矩形 `{x, y, width, height}`。
+     * @throws 超时仍未出现时抛错。
+     */
+    waitFor: (base64String: string, options?: FindImageOptions & WaitOptions) => Promise<ScreenRect>;
+    /**
+     * 轮询屏幕直到模板图片消失。
+     *
+     * @param base64String 模板图片的 Base64。
+     * @param options      查找参数外加 `{timeoutMs?, intervalMs?}`。
+     * @returns 无返回。
+     * @throws 超时仍在屏幕上时抛错。
+     */
+    waitUntilGone: (base64String: string, options?: FindImageOptions & WaitOptions) => Promise<void>;
+    /**
+     * 用 OCR 在屏幕上找一段文字,返回该词的矩形。
+     *
+     * @param text    目标文字,整词匹配。
+     * @param options `{searchRegion?, detRatio?}`。
+     * @returns 文字矩形 `{x, y, width, height}`。
+     * @throws 未找到时抛错,信息里带当前屏幕可见的文字列表。
+     */
+    findText: (text: string, options?: FindTextOptions) => Promise<ScreenRect>;
+    /**
+     * 轮询屏幕直到指定文字出现,返回该词的矩形。
+     *
+     * @param text    目标文字,整词匹配。
+     * @param options `{searchRegion?, detRatio?, timeoutMs?, intervalMs?}`。
+     * @returns 文字矩形 `{x, y, width, height}`。
+     * @throws 超时仍未出现时抛错,信息里带当前屏幕可见的文字列表。
+     */
+    waitForText: (text: string, options?: FindTextOptions & WaitOptions) => Promise<ScreenRect>;
+    /**
+     * 对显示器(或其中一块区域)做 OCR,返回每段文字及其屏幕坐标矩形。
+     *
+     * @param options `{display?, region?}`,region 为该显示器物理像素坐标;缺省光标所在显示器整屏。
+     * @returns `[{text, score, x, y, width, height}]`,坐标已加上显示器原点。
+     */
+    recognizeText: (options?: {
+        display?: number;
+        region?: ScreenRect;
+    }) => Promise<Array<ScreenRect & {
+        text: string;
+        score: number;
+    }>>;
+    /**
+     * 对显示器(或其中一块区域)做候选控件切分,返回图标尺寸的连通块矩形(屏幕坐标)。
      *
-     * @param base64String 模板图片的 Base64 编码字符串(支持 `data:image/...;base64,` 前缀)。
-     * @returns 匹配区域中心在屏幕原生坐标系中的坐标 `{x, y}`。
-     * @throws 未找到匹配区域时抛错。
+     * @param options `{display?, region?, textBoxes?, minSide?, maxSide?}`;textBoxes 是屏幕坐标的文字框,用来剔除文字行。
+     * @returns `[{x, y, width, height, pixels}]`,按 y 再 x 排序。
      */
-    find: (base64String: string) => Promise<any>;
+    proposeElements: (options?: {
+        display?: number;
+        region?: ScreenRect;
+        textBoxes?: ScreenRect[];
+        minSide?: number;
+        maxSide?: number;
+    }) => Promise<Array<ScreenRect & {
+        pixels: number;
+    }>>;
     /**
-     * 持续监视屏幕,等待指定模板图片出现后返回其中心坐标。
-     * 会阻塞直到匹配成功或 nut-js 内部超时。推送而非直接返回 —— 匹配成功前调用方一直挂起。
+     * 在一张给定图片(而不是当前屏幕)里做模板匹配,给「用采集时的截图验证模板唯一性」用。
      *
-     * @param base64String 模板图片的 Base64 编码字符串(支持 `data:image/...;base64,` 前缀)。
-     * @returns 匹配区域中心在屏幕原生坐标系中的坐标 `{x, y}`。
-     * @throws 超时仍未匹配到图片时抛错。
+     * @param haystack 被搜索图片的 Base64。
+     * @param needle   模板图片的 Base64。
+     * @param options  `{maxResults?, scale?, minScore?, region?}`。
+     * @returns `[{x, y, width, height, score, scale}]`,按分数降序,第一个是全图最佳。
      */
-    waitFor: (base64String: any) => Promise<any>;
+    matchTemplate: (haystack: string, needle: string, options?: {
+        maxResults?: number;
+        scale?: number;
+        minScore?: number;
+        region?: ScreenRect;
+    }) => Promise<Array<ScreenRect & {
+        score: number;
+        scale: number;
+    }>>;
     /**
-     * 持续监视屏幕,等待指定文字出现后返回其中心坐标。
-     * 通过 OCR 识别屏幕文字后匹配,会阻塞直到匹配成功或超时。推送而非直接返回。
+     * 两张同尺寸截图的差异包围框。
      *
-     * @param text         要查找的目标文字(支持 OCR 识别的自然语言)。
-     * @param providerData 可选的 provider 特定搜索参数,如限定 OCR 识别区域。
-     * @returns 匹配文字区域中心在屏幕原生坐标系中的坐标 `{x, y}`。
-     * @throws 超时仍未匹配到文字时抛错。
+     * @param before  前一帧的 Base64。
+     * @param after   后一帧的 Base64。
+     * @param options `{threshold?}`,灰度差超过阈值算变化,缺省 24。
+     * @returns `{x, y, width, height, changed}`;没有变化返回 null。
      */
-    waitForText: (text: string) => Promise<any>;
+    diffRegion: (before: string, after: string, options?: {
+        threshold?: number;
+    }) => Promise<(ScreenRect & {
+        changed: number;
+    }) | null>;
     /**
      * 读取屏幕上指定坐标点的像素颜色(RGBA)。
      *

package/types/SystemShell.d.ts

@@ -46,4 +46,28 @@ export default class SystemShell {
         label: string;
         available: boolean;
     }>>;
+    /**
+     * 启动一个可执行文件,进程脱离宿主独立运行。
+     *
+     * @param path 可执行文件绝对路径。
+     * @param args 命令行参数。
+     * @param cwd  工作目录,缺省为可执行文件所在目录。
+     * @returns 新进程的 pid。
+     * @throws 文件不存在或无法启动时抛错。
+     */
+    launch: (path: string, args?: string[], cwd?: string) => Promise<number>;
+    /**
+     * 判断某个可执行文件名的进程是否在运行。
+     *
+     * @param name 进程名,如 `Code.exe`;大小写不敏感,可带或不带 .exe。
+     * @returns 在运行返回 true。
+     */
+    isProcessRunning: (name: string) => Promise<boolean>;
+    /**
+     * 结束所有同名进程。
+     *
+     * @param name 进程名,如 `notepad.exe`。
+     * @returns 结束了至少一个进程返回 true;没有同名进程返回 false。
+     */
+    terminateProcess: (name: string) => Promise<boolean>;
 }

package/types/SystemWindow.d.ts

@@ -78,4 +78,66 @@ export default class SystemWindow {
         defaultName?: string;
         filters?: Electron.FileFilter[];
     }) => Promise<string | null>;
+    /**
+     * 把匹配的外部应用窗口拉到前台并激活。优先按 execPath 精确匹配,其次按 title 模糊匹配;已在前台则不操作。
+     *
+     * @param title    窗口标题(模糊匹配)。
+     * @param execPath 可选的进程可执行文件路径(精确匹配)。
+     * @returns 成功返回 true;没有匹配窗口返回 false。
+     */
+    bringToFront: (title: string, execPath?: string) => Promise<boolean>;
+    /**
+     * 列出桌面上可见、有标题的顶层窗口,z 序自上而下。
+     *
+     * @returns `[{id, title, execPath, processId, x, y, width, height, active}]`,矩形为屏幕原生坐标。
+     */
+    listWindows: () => Promise<Array<{
+        id: number;
+        title: string;
+        execPath: string;
+        processId: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        active: boolean;
+    }>>;
+    /**
+     * 取匹配窗口此刻的矩形与状态。匹配逻辑同 bringToFront。
+     *
+     * @param title    窗口标题(模糊匹配)。
+     * @param execPath 可选的进程可执行文件路径(精确匹配)。
+     * @returns `{id, title, x, y, width, height, active, minimized}`;没有匹配窗口返回 null。
+     */
+    windowBounds: (title: string, execPath?: string) => Promise<{
+        id: number;
+        title: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        active: boolean;
+        minimized: boolean;
+    } | null>;
+    /**
+     * 轮询直到匹配窗口出现,返回其矩形与状态。
+     *
+     * @param title   窗口标题(模糊匹配)。
+     * @param options `{execPath?, timeoutMs?, intervalMs?}`,缺省 10000 / 300。
+     * @returns 同 windowBounds;超时返回 null。
+     */
+    waitForWindow: (title: string, options?: {
+        execPath?: string;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }) => Promise<{
+        id: number;
+        title: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        active: boolean;
+        minimized: boolean;
+    } | null>;
 }