@solazah/solazah-runtime 0.0.156 → 0.0.157

package/types/SystemBrowser.d.ts

@@ -68,25 +68,60 @@ export default class SystemBrowser {
     private transport;
     constructor(transport?: IpcRenderer);
     bridge: {
+        /**
+         * 返回浏览器桥接的连接状态。
+         *
+         * @returns {connected 是否有扩展连着, clients 连进来的客户端数, browsers 已连接的浏览器种类列表(chrome/edge/unknown)}。
+         */
         status: () => Promise<{
             connected: boolean;
             clients: number;
             browsers: SystemBrowserKind[];
         }>;
+        /**
+         * 向扩展发一次 ping 探活。
+         *
+         * @returns {pong: true, ts} 探活响应。
+         * @throws 未连接扩展时抛错。
+         */
         ping: () => Promise<{
             pong: boolean;
             ts: number;
         }>;
     };
     tabs: {
+        /**
+         * 列出浏览器标签页。
+         *
+         * @param query chrome.tabs.QueryInfo（如 {active, currentWindow}）过滤条件；可另带 browser 字段（chrome/edge）指定目标浏览器，不传走默认浏览器。
+         * @returns {tabs} 标签页列表。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         list: (query?: chrome.tabs.QueryInfo & {
             browser?: SystemBrowserKind;
         }) => Promise<{
             tabs: SystemBrowserTab[];
         }>;
+        /**
+         * 按 tabId 取单个标签页详情。
+         *
+         * @param tabId 标签页 ID。
+         * @returns {tab} 标签页详情。
+         * @throws 标签不存在时抛错。
+         */
         get: (tabId: number) => Promise<{
             tab: SystemBrowserTab;
         }>;
+        /**
+         * 新建标签页。
+         *
+         * @param params.url      新标签页的 URL。
+         * @param params.active   是否激活新标签页，默认 true。
+         * @param params.windowId 目标窗口 ID。
+         * @param params.pinned   是否固定标签页。
+         * @returns {tab} 新建的标签页。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         create: (params: {
             url?: string;
             active?: boolean;
@@ -95,6 +130,17 @@ export default class SystemBrowser {
         }) => Promise<{
             tab: SystemBrowserTab;
         }>;
+        /**
+         * 更新指定标签页。
+         *
+         * @param params.tabId  要更新的标签页 ID。
+         * @param params.url    新 URL。
+         * @param params.active 激活状态。
+         * @param params.pinned 是否固定。
+         * @param params.muted  是否静音。
+         * @returns {tab} 更新后的标签页。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         update: (params: {
             tabId: number;
             url?: string;
@@ -104,22 +150,61 @@ export default class SystemBrowser {
         }) => Promise<{
             tab: SystemBrowserTab;
         }>;
+        /**
+         * 关闭标签页。
+         *
+         * @param params.tabId  单个标签页 ID。
+         * @param params.tabIds 批量标签页 ID 列表。
+         * @returns {removed} 已关闭的标签页 ID 列表。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         remove: (params: {
             tabId?: number;
             tabIds?: number[];
         }) => Promise<{
             removed: number[];
         }>;
+        /**
+         * 激活（切到前台）指定标签页，并把浏览器 OS 窗口提到最前（绕过 Windows 防偷焦点）。
+         *
+         * @param tabId 标签页 ID。
+         * @returns {tab} 激活的标签页。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         activate: (tabId: number) => Promise<{
             tab: SystemBrowserTab;
         }>;
+        /**
+         * 重新加载标签页。
+         *
+         * @param params.tabId       标签页 ID。
+         * @param params.bypassCache 为 true 时强制忽略缓存刷新。
+         * @returns 无返回。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         reload: (params: {
             tabId: number;
             bypassCache?: boolean;
         }) => Promise<void>;
+        /**
+         * 复制指定标签页。
+         *
+         * @param tabId 标签页 ID。
+         * @returns {tab} 新标签页（失败为 null）。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         duplicate: (tabId: number) => Promise<{
             tab: SystemBrowserTab | null;
         }>;
+        /**
+         * 把标签页移到目标位置。
+         *
+         * @param params.tabId    标签页 ID。
+         * @param params.index    目标位置索引。
+         * @param params.windowId 目标窗口 ID，传了则跨窗口移动。
+         * @returns {tab} 移动后的标签页。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         move: (params: {
             tabId: number;
             index: number;
@@ -129,12 +214,33 @@ export default class SystemBrowser {
         }>;
     };
     scripting: {
+        /**
+         * 在指定标签页里对一段 JavaScript 表达式求值并返回结果。
+         *
+         * @param params.tabId      标签页 ID。
+         * @param params.expression 要执行的 JavaScript 表达式。
+         * @param params.world      执行世界：MAIN（页面主世界）或 ISOLATED（扩展隔离世界），默认 ISOLATED。
+         * @param params.allFrames  为 true 则在所有 iframe 里执行。
+         * @returns 表达式求值结果。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         eval: (params: {
             tabId: number;
             expression: string;
             world?: "MAIN" | "ISOLATED";
             allFrames?: boolean;
         }) => Promise<any>;
+        /**
+         * 在指定标签页里执行一段函数体并返回其返回值。
+         *
+         * @param params.tabId     标签页 ID。
+         * @param params.code      要执行的函数体代码。
+         * @param params.args      传入函数的参数数组。
+         * @param params.world     执行世界：MAIN 或 ISOLATED，默认 ISOLATED。
+         * @param params.allFrames 为 true 则在所有 iframe 里执行。
+         * @returns 函数返回值。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         execute: (params: {
             tabId: number;
             code: string;
@@ -142,11 +248,29 @@ export default class SystemBrowser {
             allFrames?: boolean;
             args?: any[];
         }) => Promise<any>;
+        /**
+         * 向指定标签页注入一段 CSS。
+         *
+         * @param params.tabId     标签页 ID。
+         * @param params.css       要注入的 CSS 字符串。
+         * @param params.allFrames 为 true 则注入到所有 iframe。
+         * @returns 无返回。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         insertCSS: (params: {
             tabId: number;
             css: string;
             allFrames?: boolean;
         }) => Promise<void>;
+        /**
+         * 移除此前注入到标签页的 CSS。
+         *
+         * @param params.tabId     标签页 ID。
+         * @param params.css       要移除的 CSS 字符串（需与注入时一致）。
+         * @param params.allFrames 为 true 则从所有 iframe 移除。
+         * @returns 无返回。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         removeCSS: (params: {
             tabId: number;
             css: string;
@@ -154,16 +278,44 @@ export default class SystemBrowser {
         }) => Promise<void>;
     };
     page: {
+        /**
+         * 提取标签页里元素的文本。
+         *
+         * @param params.tabId     标签页 ID。
+         * @param params.selector  可选 CSS 选择器，不传则取整页文本。
+         * @param params.allFrames 为 true 则涵盖所有 iframe。
+         * @returns 页面/元素文本。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         text: (params: {
             tabId: number;
             selector?: string;
             allFrames?: boolean;
         }) => Promise<any>;
+        /**
+         * 点击标签页里 selector 匹配的元素。
+         *
+         * @param params.tabId     标签页 ID。
+         * @param params.selector  目标元素的 CSS 选择器。
+         * @param params.allFrames 为 true 则在所有 iframe 里查找并点击。
+         * @returns 无返回。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         click: (params: {
             tabId: number;
             selector: string;
             allFrames?: boolean;
         }) => Promise<any>;
+        /**
+         * 把值填入标签页里 selector 匹配的输入元素。
+         *
+         * @param params.tabId     标签页 ID。
+         * @param params.selector  目标输入元素的 CSS 选择器。
+         * @param params.value     要填入的值。
+         * @param params.allFrames 为 true 则在所有 iframe 里查找并填充。
+         * @returns 无返回。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         fill: (params: {
             tabId: number;
             selector: string;
@@ -172,12 +324,29 @@ export default class SystemBrowser {
         }) => Promise<any>;
     };
     cookies: {
+        /**
+         * 从浏览器读取单条 cookie。
+         *
+         * @param params.url  cookie 所属 URL。
+         * @param params.name cookie 名称。
+         * @returns {cookie} 单条 cookie（不存在为 null）。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         get: (params: {
             url: string;
             name: string;
         }) => Promise<{
             cookie: SystemBrowserCookie | null;
         }>;
+        /**
+         * 批量读取浏览器 cookie。
+         *
+         * @param params.url    按 URL 过滤。
+         * @param params.domain 按域名过滤。
+         * @param params.name   按名称过滤。
+         * @returns {cookies} cookie 列表。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         getAll: (params?: {
             url?: string;
             domain?: string;
@@ -187,6 +356,18 @@ export default class SystemBrowser {
         }>;
     };
     http: {
+        /**
+         * 在浏览器扩展上下文里发 HTTP 请求（自动复用浏览器登录态/cookie）。
+         *
+         * @param params.url         目标 URL。
+         * @param params.method      HTTP 方法，默认 GET。
+         * @param params.headers     自定义请求头。
+         * @param params.body        请求体。
+         * @param params.credentials Cookie 策略：include、same-origin 或 omit，默认 include。
+         * @param params.timeoutMs   超时毫秒，默认 30000。
+         * @returns {status, statusText, ok, url, redirected, headers, body} HTTP 响应。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         fetch: (params: {
             url: string;
             method?: string;
@@ -197,20 +378,49 @@ export default class SystemBrowser {
         }) => Promise<SystemBrowserHttpResponse>;
     };
     bookmarks: {
+        /**
+         * 取完整书签树。
+         *
+         * @param params.browser 浏览器种类（chrome/edge），不传走默认浏览器。
+         * @returns {tree} 书签树（嵌套结构，children 为子节点）。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         tree: (params?: {
             browser?: SystemBrowserKind;
         }) => Promise<{
             tree: SystemBrowserBookmark[];
         }>;
+        /**
+         * 列出某个书签文件夹的直接子项。
+         *
+         * @param params.parentId 父文件夹 ID。
+         * @param params.browser  浏览器种类（chrome/edge），不传走默认浏览器。
+         * @returns {items} 书签列表。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         list: (params?: {
             parentId?: string;
             browser?: SystemBrowserKind;
         }) => Promise<{
             items: SystemBrowserBookmark[];
         }>;
+        /**
+         * 按 id 取单个书签节点。
+         *
+         * @param id 书签 ID。
+         * @returns {item} 书签节点（不存在为 null）。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         get: (id: string) => Promise<{
             item: SystemBrowserBookmark | null;
         }>;
+        /**
+         * 搜索书签。
+         *
+         * @param query 关键词字符串，或 {query, url, title, browser} 条件对象（browser 字段可指定浏览器）。
+         * @returns {items} 搜索结果列表。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         search: (query: string | {
             query?: string;
             url?: string;
@@ -219,6 +429,16 @@ export default class SystemBrowser {
         }) => Promise<{
             items: SystemBrowserBookmark[];
         }>;
+        /**
+         * 在浏览器中创建一个书签或文件夹。不传 url 则创建的是文件夹。
+         *
+         * @param params.parentId 父文件夹 ID；省略则创建在"其他书签"根目录。
+         * @param params.title    书签/文件夹标题；省略则用页面标题或 URL 作为标题。
+         * @param params.url      书签指向的 URL；不传则创建文件夹。
+         * @param params.index    在父文件夹中的插入位置（0 起始）；不传则追加到末尾。
+         * @returns 包含新创建书签/文件夹节点的 {item} 对象。
+         * @throws 浏览器扩展未连接或调用超时时抛错。
+         */
         create: (params: {
             parentId?: string;
             title?: string;
@@ -227,6 +447,15 @@ export default class SystemBrowser {
         }) => Promise<{
             item: SystemBrowserBookmark;
         }>;
+        /**
+         * 更新指定书签的标题和/或 URL。
+         *
+         * @param params.id    要更新的书签 ID。
+         * @param params.title 新标题；省略则保持原标题不变。
+         * @param params.url   新 URL；省略则保持原 URL 不变。
+         * @returns 包含更新后书签节点的 {item} 对象。
+         * @throws 书签不存在、浏览器扩展未连接或调用超时时抛错。
+         */
         update: (params: {
             id: string;
             title?: string;
@@ -234,6 +463,15 @@ export default class SystemBrowser {
         }) => Promise<{
             item: SystemBrowserBookmark;
         }>;
+        /**
+         * 将书签移动到指定父文件夹的指定位置。
+         *
+         * @param params.id       要移动的书签 ID。
+         * @param params.parentId 目标父文件夹 ID；省略则留在当前文件夹内仅调整位置。
+         * @param params.index    目标位置索引（0 起始）；省略则追加到文件夹末尾。
+         * @returns 包含移动后书签节点的 {item} 对象。
+         * @throws 书签不存在、浏览器扩展未连接或调用超时时抛错。
+         */
         move: (params: {
             id: string;
             parentId?: string;
@@ -241,7 +479,21 @@ export default class SystemBrowser {
         }) => Promise<{
             item: SystemBrowserBookmark;
         }>;
+        /**
+         * 删除指定书签或空文件夹。非空文件夹请用 removeTree 递归删除。
+         *
+         * @param id 要删除的书签或空文件夹的 ID。
+         * @returns 无返回。
+         * @throws 文件夹非空、书签不存在、浏览器扩展未连接或调用超时时抛错。
+         */
         remove: (id: string) => Promise<void>;
+        /**
+         * 递归删除指定文件夹及其包含的所有子书签和子文件夹。
+         *
+         * @param id 要递归删除的文件夹 ID。
+         * @returns 无返回。
+         * @throws 书签不存在、浏览器扩展未连接或调用超时时抛错。
+         */
         removeTree: (id: string) => Promise<void>;
     };
     /**

package/types/SystemClipboard.d.ts

@@ -2,7 +2,23 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemClipboard {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 读取系统剪贴板当前内容,按 text → image → fileName → fileUrl 顺序依次探测,返回第一个命中的结果或 null。
+     *
+     * @returns 剪贴板数据对象 `{type, content}`;图片以 dataURL 字符串返回;无任何内容时返回 null。
+     */
     read: () => Promise<any>;
+    /**
+     * 将内容写入系统剪贴板。content 为空时不做任何操作。
+     *
+     * @param content 剪贴板数据对象 `{type, content}`,type 支持 `text` / `image` / `fileName`。
+     * @returns 无返回
+     */
     write: (content: any) => Promise<any>;
+    /**
+     * 清空系统剪贴板全部内容。
+     *
+     * @returns 无返回
+     */
     clear: () => Promise<any>;
 }

package/types/SystemKeyboard.d.ts

@@ -2,6 +2,18 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemKeyboard {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 向当前前台窗口焦点处合成键入文本,走 Unicode 注入,绕过键盘布局与输入法,CJK/emoji 可直接输入。
+     *
+     * @param text 要键入的文本字符串。
+     * @returns 无返回
+     */
     type: (text: string) => Promise<any>;
+    /**
+     * 抓取当前选区内容。优先用系统无障碍接口直读焦点元素选区(不动剪贴板);
+     * 直读拿不到时兜底:暂存原剪贴板 → 模拟复制键 → 轮询读取新内容 → 还原原剪贴板。
+     *
+     * @returns 选区内容对象 {type, content},type 为 text/image/fileName/fileUrl 之一;无内容时返回 null。
+     */
     copy: () => Promise<any>;
 }

package/types/SystemMouse.d.ts

@@ -3,11 +3,58 @@ import { Point } from '@computer-use/nut-js';
 export default class SystemMouse {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 通过 OCR 文字识别在屏幕上定位指定文本,将鼠标移至其中心并左键单击一次。
+     *
+     * @param text         要查找的文本内容,由底层 OCR 引擎在屏幕上逐词匹配。
+     * @param providerData 透传给 OCR 识别器的可选附加数据(如语言、区域等)。
+     * @returns 操作完成后兑现的 Promise。
+     * @throws 屏幕上未找到指定文本时抛错。
+     */
     clickText: (text: string) => Promise<any>;
+    /**
+     * 将 base64 图像作为模板在屏幕上等待匹配,定位后左键单击其中心。
+     * 若 base64String 为空则直接返回,不执行任何操作。
+     *
+     * @param base64String 截图模板的 base64 编码字符串,可选 data URI 前缀。
+     * @returns 操作完成后兑现的 Promise;base64String 为空时返回 undefined。
+     * @throws 屏幕上等待超时仍未匹配到图像时抛错。
+     */
     click: (base64String: string) => Promise<any>;
+    /**
+     * 在指定屏幕坐标处左键单击一次。
+     *
+     * @param point 屏幕坐标 `{x, y}`,原点为屏幕左上角。
+     * @returns 操作完成后兑现的 Promise。
+     */
     clickAt: (point: Point) => Promise<any>;
+    /**
+     * 将 base64 图像作为模板在屏幕上等待匹配,定位后将鼠标移至其中心,不点击。
+     *
+     * @param base64String 截图模板的 base64 编码字符串,可选 data URI 前缀。
+     * @returns 操作完成后兑现的 Promise。
+     * @throws 屏幕上等待超时仍未匹配到图像时抛错。
+     */
     move: (base64String: string) => Promise<any>;
+    /**
+     * 将鼠标移至指定屏幕坐标,不点击。
+     *
+     * @param point 屏幕坐标 `{x, y}`,原点为屏幕左上角。
+     * @returns 操作完成后兑现的 Promise。
+     */
     moveTo: (point: Point) => Promise<any>;
+    /**
+     * 在指定屏幕坐标处左键双击。
+     *
+     * @param point 屏幕坐标 `{x, y}`,原点为屏幕左上角。
+     * @returns 操作完成后兑现的 Promise。
+     */
     doubleClickAt: (point: Point) => Promise<any>;
+    /**
+     * 在指定屏幕坐标处右键单击一次。
+     *
+     * @param point 屏幕坐标 `{x, y}`,原点为屏幕左上角。
+     * @returns 操作完成后兑现的 Promise。
+     */
     rightClickAt: (point: Point) => Promise<any>;
 }

package/types/SystemNotification.d.ts

@@ -10,8 +10,30 @@ export interface SystemNotificationOptions {
 export default class SystemNotification {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 检测当前平台是否支持系统原生通知。
+     *
+     * @returns 支持返回 true,不支持返回 false。
+     */
     isSupported: () => Promise<boolean>;
+    /**
+     * 显示一条系统原生通知,并向调用方 webContents 推送后续的点击/关闭事件。
+     *
+     * 平台不支持时静默返回 null,不抛错。
+     * 通知被点击时向调用方 webContents 发送 "notification.clicked",
+     * 被关闭时发送 "notification.closed",参数均为该通知 id。
+     * 同时也会在主进程事件总线上发布同名事件供其他组件订阅。
+     *
+     * @param options 通知配置:title 必填;body/silent/subtitle 可选(subtitle 仅 macOS 生效)。
+     * @returns 通知 id(UUID 字符串);平台不支持通知时返回 null。
+     */
     show: (options: SystemNotificationOptions) => Promise<string | null>;
+    /**
+     * 按 id 关闭一条已显示的系统通知。
+     *
+     * @param id 通知 id(由 show 方法返回的 UUID 字符串)。
+     * @returns 命中并成功关闭返回 true;对应 id 不存在返回 false。
+     */
     close: (id: string) => Promise<boolean>;
     onClicked: (handler: (id: string) => void) => Promise<Electron.IpcRenderer>;
     onClosed: (handler: (id: string) => void) => Promise<Electron.IpcRenderer>;

package/types/SystemOCR.d.ts

@@ -2,5 +2,12 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemOCR {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 调用本地 OCR 引擎识别图片并返回文本块数组。
+     *
+     * @param base64String Base64 编码的图片数据。
+     * @returns 文本块数组。
+     * @throws 图片解码失败或 OCR 引擎未就绪时抛错。
+     */
     recognize: (base64String: string) => Promise<any>;
 }

package/types/SystemScreen.d.ts

@@ -3,12 +3,69 @@ import { Point } from '@computer-use/nut-js';
 export default class SystemScreen {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 冻结光标所在显示器的截图底图,收集该屏上的窗口分数矩形与光标 CSS 坐标,打包为采集场景数据。
+     * 纯数据通道,不显示浮层;插件拿到数据后自行渲染全屏浮层,底图中不会包含浮层自身。
+     * 若当前已有进行中的采集会话且存在已冻结场景,直接复用上次场景(避免把当前浮层抓进新底图)。
+     *
+     * @returns 采集场景数据 `CaptureSource`,含底图 Data URL (`image`)、屏幕边界 (`bounds`)、
+     *          窗口分数矩形列表 (`windows`,各矩形以屏幕宽高归一化为 0~1 浮点数)、
+     *          光标在该屏内的 CSS 坐标 (`cursor`);截图失败时返回 null。
+     */
     captureScene: () => Promise<any>;
+    /**
+     * 截取指定显示器(或光标所在显示器)的完整画面,返回 Data URL。
+     * 截图尺寸按物理像素(display.size × scaleFactor),保证 retina/高分屏清晰度。
+     *
+     * @param displayId 目标显示器 id;省略则截取光标当前所在的显示器。
+     * @returns 截图的 JPEG Data URL;未找到显示器或截图源时返回 null。
+     */
     captureDisplay: (displayId?: number) => Promise<any>;
+    /**
+     * 列出当前所有显示器信息,包含 id、逻辑像素边界、缩放因子、是否主屏。
+     *
+     * @returns 显示器信息数组 `DisplayInfo[]`,每项含 `id`、`bounds`、`scaleFactor`、`primary`。
+     */
     listDisplays: () => Promise<any>;
+    /**
+     * 获取当前鼠标光标在屏幕原生坐标系中的位置。
+     *
+     * @returns 光标坐标 `{x, y}`,原点为所有显示器拼接后的左上角。
+     */
     getCursorPoint: () => Promise<any>;
+    /**
+     * 在当前屏幕中查找与给定模板图片匹配的区域,返回匹配区域中心坐标。
+     * 使用 nut-js 图像匹配引擎在屏幕中搜索模板。
+     *
+     * @param base64String 模板图片的 Base64 编码字符串(支持 `data:image/...;base64,` 前缀)。
+     * @returns 匹配区域中心在屏幕原生坐标系中的坐标 `{x, y}`。
+     * @throws 未找到匹配区域时抛错。
+     */
     find: (base64String: string) => Promise<any>;
+    /**
+     * 持续监视屏幕,等待指定模板图片出现后返回其中心坐标。
+     * 会阻塞直到匹配成功或 nut-js 内部超时。推送而非直接返回 —— 匹配成功前调用方一直挂起。
+     *
+     * @param base64String 模板图片的 Base64 编码字符串(支持 `data:image/...;base64,` 前缀)。
+     * @returns 匹配区域中心在屏幕原生坐标系中的坐标 `{x, y}`。
+     * @throws 超时仍未匹配到图片时抛错。
+     */
     waitFor: (base64String: any) => Promise<any>;
+    /**
+     * 持续监视屏幕,等待指定文字出现后返回其中心坐标。
+     * 通过 OCR 识别屏幕文字后匹配,会阻塞直到匹配成功或超时。推送而非直接返回。
+     *
+     * @param text         要查找的目标文字(支持 OCR 识别的自然语言)。
+     * @param providerData 可选的 provider 特定搜索参数,如限定 OCR 识别区域。
+     * @returns 匹配文字区域中心在屏幕原生坐标系中的坐标 `{x, y}`。
+     * @throws 超时仍未匹配到文字时抛错。
+     */
     waitForText: (text: string) => Promise<any>;
+    /**
+     * 读取屏幕上指定坐标点的像素颜色(RGBA)。
+     *
+     * @param point 屏幕原生坐标系中的坐标 `{x, y}`。
+     * @returns 该点的 RGBA 颜色值 `{R, G, B, A}`,各通道 0–255。
+     */
     colorAt: (point: Point) => Promise<any>;
 }

package/types/SystemSetting.d.ts

@@ -2,10 +2,39 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemSetting {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 获取合并后的全部系统设置键值表。合并顺序:打包默认(DEFAULT_SETTINGS) → 文件(开发环境 settings.local.json,生产环境 ~/.solazah/settings.json) → 数据库;
+     * 开发环境中文件覆盖数据库,生产环境中数据库覆盖文件,保证用户运行时的改动优先。
+     *
+     * @returns 合并后的设置键值表,键为设置 key、值为对应值。
+     * @throws 数据库读取或文件 I/O 失败时抛错。
+     */
     getSettings: () => Promise<any>;
+    /**
+     * 按 key 取单个设置项的值。从 getSettings 合并后的设置表中查找,未命中返回 undefined。
+     *
+     * @param key 设置项的键名,如 `system.theme`、`system.autoStart`。
+     * @returns 该 key 对应的值;key 不存在时返回 undefined。
+     * @throws 数据库读取或文件 I/O 失败时抛错。
+     */
     getSettingValue: (key: string) => Promise<any>;
+    /**
+     * 批量保存多个设置项。逐条写入数据库(已有同 key 记录则更新、无则新建),每条落库后广播 {@link SystemSettingChangedEvent},
+     * 使开机自启/主题/浏览器/copilot 等监听者即时应用变更。
+     *
+     * @param values 键值对对象,键为设置 key、值为要保存的值。各条 enabled 默认 true,除非显式传 false。
+     * @returns 无返回
+     * @throws 数据库写入失败时抛错(已成功写入的条目不会回滚)。
+     */
     saveSettings: (values: {
         [x: string]: any;
     }) => Promise<any>;
+    /**
+     * 保存单个设置项。数据库已有同 key 记录则更新、无则新建,落库后广播 {@link SystemSettingChangedEvent}。
+     *
+     * @param settingInput 包含 `key`(设置键名)、`value`(设置值)、`enabled`(是否启用,可选;undefined 或 truthy 视为 true,仅显式传 false 才禁用)的对象。
+     * @returns 无返回
+     * @throws 数据库写入失败时抛错。
+     */
     saveSetting: (settingInput: any) => Promise<any>;
 }