@solazah/solazah-runtime 0.0.156 → 0.0.158

package/types/SystemShell.d.ts

@@ -2,7 +2,25 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemShell {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 用系统默认程序打开一个外部 URL（通常是浏览器打开 http/https 链接）。
+     *
+     * 直接委托 Electron {@link shell.openExternal}；可选地通过 options 控制激活行为。
+     *
+     * @param url     要打开的 URL，协议不限（如 `http:`、`https:`、`mailto:`）。
+     * @param options 打开选项，例如 `{ activate: true }` 是否将目标窗口前置。
+     * @returns 操作完成（`Promise<void>`，无业务返回值）。
+     */
     openExternal: (url: string, options?: Electron.OpenExternalOptions) => Promise<any>;
+    /**
+     * 用系统默认关联程序打开本地文件或目录（例如 .pdf 用 PDF 阅读器、文件夹用资源管理器）。
+     *
+     * 直接委托 Electron {@link shell.openPath}；底层返回空字符串表示成功，非空字符串为错误描述。
+     * 当前实现不向上传递该结果字符串，调用方只能通过有无异常判断成败。
+     *
+     * @param path 本地文件或目录的绝对路径。
+     * @returns 操作完成（`Promise<void>`）；返回值被丢弃，异常直接传播给调用方。
+     */
     openPath: (path: string) => Promise<any>;
     /** 在资源管理器/Finder 中显示并选中该文件(或文件夹) */
     showItemInFolder: (path: string) => Promise<any>;

package/types/SystemShortcut.d.ts

@@ -2,7 +2,26 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemShortcut {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 列出全部已保存的快捷键绑定记录。
+     *
+     * @returns 系统中所有已持久化的快捷键实体列表(系统快捷键配置数组),无记录时为空数组。
+     */
     getShortcuts: () => Promise<any>;
+    /**
+     * 解除并删除指定命令的全局快捷键绑定。该命令无绑定时为不做任何操作,不报错。
+     *
+     * @param commandName 要解除快捷键的命令名称。
+     * @returns 无返回(绑定不存在时静默跳过)。
+     */
     removeShortcut: (commandName: string) => Promise<any>;
+    /**
+     * 为指定命令设置全局快捷键。传入空 shortcut 时解除该命令的绑定并删除记录;
+     * 非空时先抢占式解除占用同一快捷键的其他命令,再注册新绑定并持久化。
+     *
+     * @param name     命令名称。
+     * @param shortcut 要绑定的快捷键字符串(如 `"Ctrl+Shift+A"`);为空或解绑(不传键位)则解绑并删除。
+     * @returns ok 表示操作是否成功;replaced 列出被抢占覆盖的命令名;error 在命令不存在/已禁用/注册失败时给出原因。
+     */
     setShortcut: (name: string, shortcut?: string) => Promise<any>;
 }

package/types/SystemWindow.d.ts

@@ -2,12 +2,78 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemWindow {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 在屏幕底部弹出轻量 toast 通知窗口,3 秒后自动消失。
+     *
+     * 窗口为透明容器、鼠标事件穿透,内容由渲染层 `#/toast` 页面渲染。
+     * 连续调用时上一 toast 的隐藏计时器会被重置,避免旧定时器提前关掉新 toast。
+     *
+     * @param type 通知类型:`info` / `success` / `warn` / `error`,影响渲染层展示样式。
+     * @param text 通知文本内容。
+     * @returns 无返回。
+     */
     toast: (type: "info" | "success" | "warn" | "error", text: string) => Promise<any>;
+    /**
+     * 收起主窗口(通过平台原生 cloak/hide 策略)。
+     *
+     * 先取消 alwaysOnTop,再委托 SystemWindowVisibility.dismiss() 执行收起;
+     * 收起成功后通知渲染层 `window.visibleChanged`。
+     *
+     * @returns 无返回。
+     */
     hide: () => Promise<any>;
+    /**
+     * 设置主窗口高度,宽度保持不变。
+     *
+     * 高度低于默认值(60px)时会被强制钳位到默认值。
+     * 当前高度与目标高度相同时跳过,避免无效的 setSize 调用。
+     *
+     * @param height 目标高度(px),小于 60 时自动取 60。
+     * @returns 无返回。
+     */
     setHeight: (height: number) => Promise<any>;
+    /**
+     * 将主窗口导航回首页(搜索框),移除所有子视图,复位到默认尺寸(800×60)。
+     *
+     * 既是 IPC handler 也是事件监听器。操作流程:取消 alwaysOnTop →
+     * 以 remount 模式重新加载首页 → 清除所有 contentView 子视图 →
+     * 聚焦 webContents → 复位 bounds 到默认值。
+     *
+     * @returns 无返回。
+     */
     goHome: () => Promise<any>;
+    /**
+     * 在新浏览器窗口中打开指定 URL。
+     *
+     * 窗口创建后自动注入 CSS:顶部 28px 拖拽区(用作自定义标题栏)和隐藏滚动条。
+     * 窗口类型为 `browser`,通过 SystemWindowProvider 创建,加载完成后调用 toggle 显示。
+     *
+     * @param url  要加载的目标 URL。
+     * @param options 可选的窗口创建选项,透传给 SystemWindowProvider.create()。
+     * @returns 无返回。
+     */
     open: (url: string, options?: any) => Promise<any>;
+    /**
+     * 弹出系统原生"选择文件夹"对话框,返回用户选中的第一个文件夹路径。
+     *
+     * 默认属性包含 `openDirectory`,调用方可通过 options 追加其它属性。
+     * 以当前聚焦窗口为父窗口,拿不到时回退到主窗口。
+     *
+     * @param options 可选的 Electron OpenDialogOptions,会与默认属性 `{properties: ["openDirectory"]}` 合并。
+     * @returns 选中文件夹的绝对路径;取消或无选择时返回 null。
+     */
     showOpenDialog: (options?: Electron.OpenDialogOptions) => Promise<any>;
+    /**
+     * 弹出系统"另存为"对话框,将文本内容以 UTF-8 编码写入用户指定路径。
+     *
+     * 以当前聚焦窗口为父窗口,拿不到时回退到主窗口。
+     *
+     * @param content 要保存的文本内容。
+     * @param options 可选的保存配置对象。
+     * @param options.defaultName 默认文件名。
+     * @param options.filters     文件类型过滤器(如 `[{name:"文本文件", extensions:["txt"]}]`)。
+     * @returns 保存成功返回实际文件路径;用户取消返回 null。
+     */
     saveText: (content: string, options?: {
         defaultName?: string;
         filters?: Electron.FileFilter[];

package/types/Workspace.d.ts

@@ -36,9 +36,35 @@ export interface RegisterWorkspaceInputDto {
 export default class Workspace {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 列出全部工作空间,按最近使用时间降序排列。
+     *
+     * @returns 工作空间数组,每项的 path 已被覆写为本机有效路径(本地覆盖优先于同步值)。空列表表示尚无工作空间。
+     */
     list: () => Promise<WorkspaceDto[]>;
+    /**
+     * 按 id 获取单个工作空间。
+     *
+     * @param id 工作空间唯一标识。
+     * @returns 工作空间对象(path 已覆写为本机有效路径),不存在时返回 null。
+     */
     get: (id: string) => Promise<WorkspaceDto | null>;
+    /**
+     * 注册一个新的本地工作空间。
+     *
+     * @param input 注册参数。`path` 必填(绝对路径,目录须已在磁盘上存在);`name` 可选(缺省取路径末尾目录名);`includeGlobs`/`excludeGlobs` 可选(排除规则默认包含 .git/node_modules 等敏感目录);`indexFlags` 可选(filename 默认开、content 默认关)。
+     * @returns 新建并持久化的工作空间对象。
+     * @throws 路径在磁盘上不存在时抛错。
+     * @throws 该路径已被其他工作空间注册时抛错。
+     */
     register: (input: RegisterWorkspaceInputDto) => Promise<WorkspaceDto>;
+    /**
+     * 更新工作空间的元数据(名称、包含/排除规则、索引开关、embedding 模型),不涉及路径。
+     *
+     * @param id 目标工作空间唯一标识。
+     * @param patch 要更新的字段,可含 `name` / `includeGlobs` / `excludeGlobs` / `indexFlags` / `embedModel`,未传的字段保持不变。不允许通过此接口改 `path`,路径变动请用 `relocate`。
+     * @returns 更新后的工作空间对象,id 不存在时返回 null。
+     */
     update: (id: string, patch: Partial<WorkspaceDto>) => Promise<WorkspaceDto | null>;
     /** 目录被移动/改名后重定位:只换路径,索引数据原封不动。 */
     relocate: (id: string, newPath: string) => Promise<WorkspaceDto | null>;