@solazah/solazah-runtime 0.2.27 → 0.2.30

package/package.json

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

package/types/Account.d.ts

@@ -34,4 +34,12 @@ export default class Account {
      *          未登录或 HTTP 请求失败时返回 null。
      */
     getUserInfo: () => Promise<any>;
+    /**
+     * 在系统浏览器里打开账号中心的某一页，进去就是当前登录的账号：点击这一刻向账号服务签一张
+     * 一次性登录票据，拼进链接的 # 段，网页拿它换成会话。本机没登录时打开登录页，登完回到这一页。
+     *
+     * @param page 账号中心的站内页面（hash 路由），如 `/account`、`/orders`。
+     * @returns 无返回。签发票据失败时抛出带原因的异常。
+     */
+    openCenter: (page: string) => Promise<any>;
 }

package/types/Copilot.d.ts

@@ -59,8 +59,8 @@ export interface CopilotChatOptions extends CopilotBaseOptions {
     onRunFinished?: () => void;
 }
 /**
- * 随用户一句话附上的一张图：`url` 是 data URL；`path` 是执行端这台机器上的图片文件，
- * 由执行端读出并缩到长边 1280 再交给模型。
+ * 随用户一句话附上的一张图：`path` 是执行端这台机器上的图片文件（对话附件）；`url` 是发起方内存里的图（base64 的 data URL）。
+ * 两种都由执行端认格式、缩到长边 1280、编码，再按这一轮的模型看不看得了图决定附不附（见 CopilotHumanContent）。
  */
 export type CopilotInputImage = {
     url: string;
@@ -156,6 +156,25 @@ export interface CopilotRoundRefusal {
     code: string;
     message: string;
 }
+/**
+ * 执行端能干什么。本机界面与远程对端问到的是同一份，界面据此隐藏用不了的入口、提示用不上的输入。
+ * 镜像在 solazah-plugin-copilot 的 `ExecutorCapabilities`（src/renderer/runtime/CopilotClient.ts），改字段两处一起改。
+ */
+export interface CopilotExecutorCapabilities {
+    kind: "local" | "remote" | "cloud";
+    /** 电脑控制类工具（鼠标、键盘、截屏） */
+    computerControl: boolean;
+    /** 本机文件读写 */
+    localFiles: boolean;
+    /** 浏览器扩展桥此刻连着 */
+    browserBridge: boolean;
+    /** 执行端当前可用的 AI 插件 name */
+    plugins: string[];
+    /** 单张附图的字节上限：超过的图执行端不读，模型看不到 */
+    maxImageBytes: number;
+    /** 远程协议版本 */
+    protocolVersion: number;
+}
 /** 一行 = 某个模型某一天的 token 统计。model_name 是模型 id,显示名要另去模型清单里换。 */
 export interface CopilotUsageStat {
     model_name: string;
@@ -214,6 +233,12 @@ export default class Copilot {
     abort: (requestId: string) => Promise<any>;
     /** 最近 days 天的 token 用量,按 (模型, 日期) 聚合,新到旧。用量看板用。 */
     usage(days?: number): Promise<CopilotUsageStat[]>;
+    /**
+     * 这台执行端能干什么，与远程对端问到的是同一份。附图时按 maxImageBytes 判断模型看不看得到这张图。
+     *
+     * @returns 执行端能力，见 {@link CopilotExecutorCapabilities}。
+     */
+    capabilities: () => Promise<CopilotExecutorCapabilities>;
     /**
      * 生成途中插一句话:排进待注入队列,模型下一个决策点领走,不中止当前回合。
      *

package/types/CopilotModel.d.ts

@@ -29,7 +29,8 @@ export default class CopilotModel {
     remove: (modelId: string) => Promise<any>;
     /**
      * 返回全部模型,并给每条附加计算属性:isEmbedded(是否内置、前端据此标记「不可移除」)、
-     * acceptedEfforts(模型接受的思考档位 none/low/medium/high,界面据此只放出这些档)。
+     * acceptedEfforts(模型接受的思考档位 none/low/medium/high,界面据此只放出这些档)、
+     * vision(执行端判定的这个模型看不看得了图,附图交不交给它按的就是这一判定)。
      *
      * @returns 模型列表数组,每项包含 isEmbedded 等计算属性
      */

package/types/SystemBrowser.d.ts

@@ -17,6 +17,20 @@ export interface SystemBrowserTab {
     incognito: boolean;
     groupId?: number;
 }
+export type SystemBrowserWindowState = "normal" | "minimized" | "maximized" | "fullscreen" | "locked-fullscreen";
+export interface SystemBrowserWindow {
+    id: number;
+    /** 是否是当前拿着焦点的窗口 */
+    focused: boolean;
+    state: SystemBrowserWindowState;
+    type: "normal" | "popup" | "panel" | "app" | "devtools";
+    incognito: boolean;
+    alwaysOnTop: boolean;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+}
 export interface SystemBrowserCookie {
     name: string;
     value: string;
@@ -50,6 +64,13 @@ export interface SystemBrowserHttpResponse {
     body: string;
 }
 export type SystemBrowserKind = "chrome" | "edge" | "unknown";
+/** call 的选项：交给哪个浏览器、等多久。主进程 BrowserBridgeProtocol 的 BridgeCallOptions 与它同形。 */
+export interface SystemBrowserCallOptions {
+    /** 交给哪个已连接的浏览器；不传按 system.preferredBrowser 选，再退到最近连上的那个 */
+    browser?: SystemBrowserKind;
+    /** 宿主等扩展回包的上限（毫秒），不传为 30 秒 */
+    timeoutMs?: number;
+}
 export type SystemBrowserEventName = "browser.tab.created" | "browser.tab.updated" | "browser.tab.removed" | "browser.tab.activated" | "browser.bookmark.created" | "browser.bookmark.changed" | "browser.bookmark.removed" | "browser.bookmark.moved" | "browser.bridge.hello" | "browser.bridge.status";
 export interface SystemBrowserEventEnvelope<T = any> {
     event: SystemBrowserEventName | string;
@@ -59,14 +80,25 @@ export interface SystemBrowserEventEnvelope<T = any> {
 /**
  * 暴露给所有 renderer（含 plugin view）的浏览器桥接 API。
  *
- * 设计原则：
- *   - 命名跟 main 侧 IPC 通道一一对应，零运行时翻译，方便排查
- *   - on/off 监听器走 ipcRenderer 直连而不是 mitt eventBus，因为 plugin view
- *     的 preload 都是同一份 contextBridge，每个 view 自己监听自己想要的事件
+ * 扩展的方法一律经 call 走宿主的 browser.call 通道，下面各组是它们的带类型包装；
+ * bridge.status 是宿主自己记的连接状态，不经扩展；tabs.activate 切完标签页再经宿主的 window.bringToFront 把浏览器提到前台。
+ * 事件监听走 ipcRenderer 直连，每个 view 自己监听自己想要的事件。
  */
 export default class SystemBrowser {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 按方法名调用浏览器扩展：方法名与参数原样交给扩展，扩展的返回值原样交回。
+     * 下面各组带类型的方法都经这里；扩展新加的方法不必等宿主更新，直接用它调。
+     *
+     * @param method  扩展的方法名，如 "tabs.list"、"windows.update"；扩展支持哪些，看 bridge.ping() 交回的 methods。
+     * @param params  交给该方法的参数，原样转发。
+     * @param options browser 指定浏览器(chrome/edge)，timeoutMs 是宿主等回包的上限，见 SystemBrowserCallOptions。
+     * @returns 扩展该方法的返回值。
+     * @throws 扩展未连接、等回包超时、扩展执行失败或没有这个方法时抛错。页面拿到的 Error 只带 message；
+     *   要分支的情形先用结构化结果判断：扩展连没连上看 bridge.status() 的 connected，支不支持某方法看 bridge.ping() 的 methods。
+     */
+    call: <T = any>(method: string, params?: object, options?: SystemBrowserCallOptions) => Promise<T>;
     bridge: {
         /**
          * 返回浏览器桥接的连接状态。
@@ -85,12 +117,13 @@ export default class SystemBrowser {
         /**
          * 向扩展发一次 ping 探活。
          *
-         * @returns {pong: true, ts} 探活响应。
+         * @returns {pong: true, ts, methods}：methods 是扩展支持的全部方法名，0.3.9 之前的扩展不带这个字段。
          * @throws 未连接扩展时抛错。
          */
         ping: () => Promise<{
             pong: boolean;
             ts: number;
+            methods?: string[];
         }>;
     };
     tabs: {
@@ -169,7 +202,9 @@ export default class SystemBrowser {
             removed: number[];
         }>;
         /**
-         * 激活（切到前台）指定标签页，并把浏览器 OS 窗口提到最前（绕过 Windows 防偷焦点）。
+         * 在浏览器里切到指定标签页，并把浏览器窗口提到系统最前。
+         * 浏览器不在前台时它自己抢焦点会被 Windows 拦下，提前台走宿主的通用窗口能力 window.bringToFront。
+         * 只切标签页、不动系统窗口的，用 call("tabs.activate", {tabId})。
          *
          * @param tabId 标签页 ID。
          * @returns {tab} 激活的标签页。
@@ -217,13 +252,43 @@ export default class SystemBrowser {
             tab: SystemBrowserTab;
         }>;
     };
+    windows: {
+        /**
+         * 取浏览器窗口此刻的状态。0.3.9 之前的扩展没有这个方法，用前看 bridge.ping() 的 methods。
+         *
+         * @param params.windowId 浏览器窗口 ID（即标签页的 windowId）。
+         * @returns {window} 窗口状态，focused 为它是否正拿着焦点，state 为 normal / minimized / maximized / fullscreen。
+         * @throws 窗口不存在、浏览器扩展未连接或调用超时时抛错。
+         */
+        get: (params: {
+            windowId: number;
+        }) => Promise<{
+            window: SystemBrowserWindow;
+        }>;
+        /**
+         * 改浏览器窗口的状态，如最小化、最大化、聚焦。0.3.9 之前的扩展没有这个方法，用前看 bridge.ping() 的 methods。
+         *
+         * @param params.windowId 浏览器窗口 ID。
+         * @param params.state    目标状态；minimized 不能与 focused: true 同时给。
+         * @param params.focused  true 让浏览器把这个窗口提到最前并聚焦，false 让它让出焦点。
+         * @returns {window} 改完后的窗口状态。
+         * @throws 窗口不存在、参数组合不合法、浏览器扩展未连接或调用超时时抛错。
+         */
+        update: (params: {
+            windowId: number;
+            state?: SystemBrowserWindowState;
+            focused?: boolean;
+        }) => Promise<{
+            window: SystemBrowserWindow;
+        }>;
+    };
     scripting: {
         /**
          * 在指定标签页里对一段 JavaScript 表达式求值并返回结果。
          *
          * @param params.tabId      标签页 ID。
          * @param params.expression 要执行的 JavaScript 表达式。
-         * @param params.world      执行世界：MAIN（页面主世界）或 ISOLATED（扩展隔离世界），默认 ISOLATED。
+         * @param params.world      执行世界：MAIN（页面主世界）或 ISOLATED（扩展隔离世界），默认 MAIN。
          * @param params.allFrames  为 true 则在所有 iframe 里执行。
          * @returns 表达式求值结果。
          * @throws 浏览器扩展未连接或调用超时时抛错。
@@ -240,7 +305,7 @@ export default class SystemBrowser {
          * @param params.tabId     标签页 ID。
          * @param params.code      要执行的函数体代码。
          * @param params.args      传入函数的参数数组。
-         * @param params.world     执行世界：MAIN 或 ISOLATED，默认 ISOLATED。
+         * @param params.world     执行世界：MAIN 或 ISOLATED，默认 MAIN。
          * @param params.allFrames 为 true 则在所有 iframe 里执行。
          * @returns 函数返回值。
          * @throws 浏览器扩展未连接或调用超时时抛错。
@@ -368,7 +433,7 @@ export default class SystemBrowser {
          * @param params.headers     自定义请求头。
          * @param params.body        请求体。
          * @param params.credentials Cookie 策略：include、same-origin 或 omit，默认 include。
-         * @param params.timeoutMs   超时毫秒，默认 30000。
+         * @param params.timeoutMs   超时毫秒，默认 30000；宿主等回包也按它。
          * @returns {status, statusText, ok, url, redirected, headers, body} HTTP 响应。
          * @throws 浏览器扩展未连接或调用超时时抛错。
          */
@@ -500,6 +565,8 @@ export default class SystemBrowser {
          */
         removeTree: (id: string) => Promise<void>;
     };
+    /** 把连着的浏览器在系统里的窗口提到最前；没有认得出种类的浏览器连着时不动。 */
+    private bringBrowserToFront;
     /**
      * 订阅扩展事件（tab/bookmark 生命周期 + 桥接连接状态）。返回反订阅函数。
      *

package/types/SystemScreen.d.ts

@@ -1,5 +1,13 @@
 import { default as IpcRenderer } from './IpcRenderer';
 import { Point } from '@computer-use/nut-js';
+/** 原始位图:BGRA、自顶向下、每像素 4 字节,与截图流 raw 帧同一格式。手里已经是像素时直接给它,省掉编码与解码。 */
+export interface RawImage {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** 一张图:Data URL、本机绝对路径,或原始位图。 */
+export type ImageSource = string | RawImage;
 /** 屏幕原生坐标系里的矩形。 */
 export interface ScreenRect {
     x: number;
@@ -364,12 +372,12 @@ export default class SystemScreen {
     /**
      * 在一张给定图片(而不是当前屏幕)里做模板匹配,给「用采集时的截图验证模板唯一性」用。
      *
-     * @param haystack 被搜索图片的 Base64。
-     * @param needle   模板图片的 Base64。
+     * @param haystack 被搜索的图片:Data URL、本机绝对路径或原始位图。
+     * @param needle   模板图片:Data URL、本机绝对路径或原始位图。
      * @param options  `{maxResults?, scale?, minScore?, region?}`。
      * @returns `[{x, y, width, height, score, scale}]`,按分数降序,第一个是全图最佳。
      */
-    matchTemplate: (haystack: string, needle: string, options?: {
+    matchTemplate: (haystack: ImageSource, needle: ImageSource, options?: {
         maxResults?: number;
         scale?: number;
         minScore?: number;
@@ -382,15 +390,16 @@ export default class SystemScreen {
      * 对一帧给定图片做一批分析:若干模板各自匹配、若干区域各自 OCR,图片只解码一次,同一区域只 OCR 一次。
      * 每一拍截一帧、拿这一帧判断全部条件的循环靠它把 IPC 压到每拍一次。
      *
-     * @param frame   被分析图片的 Base64(整个显示器的截图)。
+     * @param frame   被分析的图片(通常是一帧截图)。
      * @param request `{templates?: [{id, image, region?, scale?, minScore?, maxResults?}], texts?: [{id, region?, detRatio?, zoom?}]}`,region 相对图片左上角。
-     *   frame 与 templates[].image 都可以给 Data URL 或本机绝对路径;反复分析同一批图时给路径,同一张只解码一次。
+     *   frame 与 templates[].image 都可以给 Data URL、本机绝对路径或原始位图;反复分析同一批图时给路径,同一张只解码一次;
+     *   手里已经是像素的(截图流 raw 帧)给原始位图。
      * @returns `{templates: {id: [{x, y, width, height, score, scale}]}, texts: {id: [{text, score, x, y, width, height}]}}`,坐标相对图片左上角。
      */
-    analyzeFrame: (frame: string, request?: {
+    analyzeFrame: (frame: ImageSource, request?: {
         templates?: Array<{
             id: string;
-            image: string;
+            image: ImageSource;
             region?: ScreenRect;
             scale?: number;
             minScore?: number;