@solazah/solazah-runtime 0.2.62 → 0.2.64

package/package.json

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

package/types/Copilot.d.ts

@@ -169,6 +169,15 @@ export interface CopilotRoundRefusal {
  * 执行端能干什么。本机界面与远程对端问到的是同一份，界面据此隐藏用不了的入口、提示用不上的输入。
  * 镜像在 solazah-plugin-copilot 的 `ExecutorCapabilities`（src/renderer/runtime/CopilotClient.ts），改字段两处一起改。
  */
+/** 执行端机器上的一层文件夹。path 为 null 时是起点那一屏（主目录、盘符），parent 为 null 时没有上一级 */
+export interface CopilotDirectoryListing {
+    path: string | null;
+    parent: string | null;
+    directories: {
+        name: string;
+        path: string;
+    }[];
+}
 export interface CopilotExecutorCapabilities {
     kind: "local" | "remote" | "cloud";
     /** 电脑控制类工具（鼠标、键盘、截屏） */
@@ -195,6 +204,16 @@ export interface CopilotUsageStat {
     history_rewrites: number;
 }
 export default class Copilot {
+    /** 将内容交付到当前宿主工具调用所属对话。 */
+    present: (content: {
+        kind: "file" | "image" | "widget";
+        items?: {
+            path: string;
+            caption?: string;
+        }[];
+        code?: string;
+        title?: string;
+    }) => Promise<any>;
     ipcRenderer: IpcRenderer;
     constructor();
     /**

package/types/Plugin.d.ts

@@ -21,7 +21,13 @@ export interface PluginTool {
     schema: object | null;
     timeoutMs?: number;
     resident?: boolean;
+    requires?: PluginToolCapability[];
 }
+/**
+ * 工具可以声明依赖的宿主能力。「数据」类(插件设置、对话、工作空间文件、网络)每台执行端都有,不必声明。
+ * - ui:插件窗口与命令(打开命令、切到某条对话)。没有界面的执行端(solazah-cli serve)没有
+ */
+export type PluginToolCapability = "ui";
 /**
  * 宿主自身的信息，随 `plugin.info()` 一起给到插件。
  *
@@ -41,12 +47,25 @@ export interface PluginToolOptions {
      * 且在插件里**固定不变**(按需增删会让整段历史前缀失配)。
      */
     resident?: boolean;
+    /** 工具要用到的宿主能力(见 PluginToolCapability)。执行端提供不了时这个工具不进模型的工具表 */
+    requires?: PluginToolCapability[];
 }
+/** 页面方法:工具入口里 requires ui 的工具经 `callPage` 交给本插件页面执行的那段实现 */
+export type PluginPageHandler = (args: any) => Promise<unknown> | unknown;
 export default class Plugin {
     private ipcRenderer;
+    /** 调用本插件独立入口，不接受调用方提供的线程身份。 */
+    callTool: (name: string, args?: unknown) => Promise<any>;
+    /**
+     * 工具入口调用本插件页面登记的方法(见 handle),宿主按需拉起页面、等回执。
+     * 只给声明了 requires ui 的工具用:没有插件页面的执行端没有这条通道。
+     */
+    callPage: (name: string, args?: unknown, timeoutMs?: number) => Promise<any>;
     private readonly onSearchHandlers;
     private readonly onActionHandlers;
     private readonly tools;
+    /** plugin.onCall 按名字找的处理函数:入口里是 tool 注册的工具,页面里是 handle 登记的方法 */
+    private readonly callHandlers;
     /** 用 Solazah 账号登录插件，见 PluginAccount */
     readonly account: PluginAccount;
     constructor(ipcRenderer?: IpcRenderer);
@@ -56,16 +75,20 @@ export default class Plugin {
         schema: object | null;
         timeoutMs: number | undefined;
         resident: boolean | undefined;
+        requires: "ui"[] | undefined;
     }[];
     /**
-     * 给 Otta 注册 AI 工具。
+     * 给 Otta 注册 AI 工具。只在工具入口(src/tools/index.mjs)里调用,宿主只从入口收工具。
      * schema 传 JSON Schema 对象(如 z.toJSONSchema(...) 的返回值),无参工具传 null;
      * cb 收到已按 schema 拆包的参数对象(无参工具收到 {}),返回字符串给 LLM(返回对象会被 JSON.stringify);
      * 第二个参数是调用上下文(见 PluginToolContext)。
      * options.timeoutMs 是宿主等待回执的上限,执行耗时长的工具要显式给。
+     * options.requires 声明工具要用到的宿主能力,执行端提供不了时这个工具不进工具表。
      * 同名重复注册为覆盖(HMR 安全)。
      */
     tool: (name: string, description: string, schema: object | null, cb: (args: any, context: PluginToolContext) => Promise<string> | string, options?: PluginToolOptions) => (args: any, context: PluginToolContext) => Promise<string> | string;
+    /** 在插件页面登记一个供工具入口 callPage 调用的方法。同名重复登记为覆盖(HMR 安全)。 */
+    handle: (name: string, handler: PluginPageHandler) => void;
     onSearch: (commandName: string, handler: any) => Promise<void>;
     onAction: (commandName: string, action: string, handler: any) => Promise<void>;
     /**

package/types/PluginSettings.d.ts

@@ -64,4 +64,11 @@ export default class PluginSettings {
      * @returns 无返回。无法定位发起方插件时不执行任何操作。
      */
     removeItem: (collection: string, id: string) => Promise<void>;
+    /**
+     * 本插件的设置可能变了:助理的工具写了设置(工具跑在另一个进程里)、或从别的设备同步来了变更。
+     * 界面据此重读自己关心的数据。同一时刻只保留最后一次订阅的监听器。
+     *
+     * @param listener 变更时被调用,不带参数。
+     */
+    onChanged: (listener: () => void) => Promise<void>;
 }

package/types/PreloadApi.d.ts

@@ -0,0 +1,68 @@
+import { default as Notifications } from './Notifications';
+import { default as IpcRenderer } from './IpcRenderer';
+import { default as Copilot } from './Copilot';
+import { default as CopilotSubAgent } from './CopilotSubAgent';
+import { default as CopilotThread } from './CopilotThread';
+import { default as CopilotMcpServer } from './CopilotMcpServer';
+import { default as CopilotModel } from './CopilotModel';
+import { default as Plugin } from './Plugin';
+import { default as PluginCommand } from './PluginCommand';
+import { default as PluginSettings } from './PluginSettings';
+import { default as System } from './System';
+import { default as SystemClipboard } from './SystemClipboard';
+import { default as SystemKeyboard } from './SystemKeyboard';
+import { default as SystemMouse } from './SystemMouse';
+import { default as SystemOCR } from './SystemOCR';
+import { default as SystemSetting } from './SystemSetting';
+import { default as SystemShell } from './SystemShell';
+import { default as SystemBrowser } from './SystemBrowser';
+import { default as SystemShortcut } from './SystemShortcut';
+import { default as SystemAudio } from './SystemAudio';
+import { default as SystemWindow } from './SystemWindow';
+import { default as SystemRecorder } from './SystemRecorder';
+import { default as SystemElevation } from './SystemElevation';
+import { default as SystemNotification } from './SystemNotification';
+import { default as Account } from './Account';
+import { default as Workspace } from './Workspace';
+import { default as File } from './File';
+import { default as Http } from './Http';
+import { default as Kb } from './Kb';
+import { default as Mail } from './Mail';
+import { default as Sync } from './Sync';
+/**
+ * 宿主给插件的 API 对象,即 `window` 上的那一组:插件页面由 preload 经 contextBridge 暴露,
+ * 插件工具入口进程(src/scripts/PluginAgent.ts)直接挂在它的 window 上。两边是同一份清单。
+ */
+export declare function createPreloadApi(): {
+    notifications: Notifications;
+    ipcRenderer: IpcRenderer;
+    copilot: Copilot;
+    copilotSubagent: CopilotSubAgent;
+    copilotThread: CopilotThread;
+    copilotMcpServer: CopilotMcpServer;
+    copilotModel: CopilotModel;
+    plugin: Plugin;
+    pluginCommand: PluginCommand;
+    pluginSettings: PluginSettings;
+    system: System;
+    systemClipboard: SystemClipboard;
+    systemKeyboard: SystemKeyboard;
+    systemMouse: SystemMouse;
+    systemOCR: SystemOCR;
+    systemSetting: SystemSetting;
+    systemShell: SystemShell;
+    systemBrowser: SystemBrowser;
+    systemShortcut: SystemShortcut;
+    systemAudio: SystemAudio;
+    systemWindow: SystemWindow;
+    systemRecorder: SystemRecorder;
+    systemElevation: SystemElevation;
+    systemNotification: SystemNotification;
+    account: Account;
+    workspace: Workspace;
+    file: File;
+    http: Http;
+    kb: Kb;
+    mail: Mail;
+    sync: Sync;
+};