@solazah/solazah-runtime 0.2.36 → 0.2.38

package/package.json

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

package/types/Copilot.d.ts

@@ -72,6 +72,8 @@ export type CopilotInputImage = {
 /** 待投递给主 agent 的一条内容：notice = 后台任务完成通知，interject = 用户在生成途中插的话。 */
 export interface CopilotPendingInjection {
     kind: "notice" | "interject";
+    /** 通知的执行端 subAgentType；插话不带。 */
+    source?: string;
     /** 注入时用作消息 id(落库切片按 id 去重),同时是撤回的凭据。 */
     id: string;
     /** 投给模型看的整段文案。两条投递路径共用同一份,保证模型在轮中和轮间看到的内容一致。 */

package/types/Mail.d.ts

@@ -19,7 +19,10 @@ export interface SendMailInput {
     subject: string;
     text?: string;
     html?: string;
+    /** 回复时填原信的 Message-ID。 */
     inReplyTo?: string;
+    /** 回复时填原信的 References 链 + 原信 Message-ID,收件方据此归到同一会话。 */
+    references?: string[];
 }
 /**
  * window.mail —— 经主进程的 IMAP(收)/ SMTP(发)。渲染层无裸 socket,协议封在主进程。
@@ -101,12 +104,23 @@ export default class Mail {
          */
         list: (accountId: string, folder: MailFolderId, limit?: number, unseenOnly?: boolean) => Promise<any>;
         /**
-         * 读取单封邮件的完整正文(text/html、收发人、附件元信息)。
+         * 在服务器端搜索一个文件夹:主题 / 发件人 / 收件人 / 正文任一包含关键词即命中,整个文件夹都搜。
+         *
+         * @param accountId 账户唯一标识。
+         * @param folder    逻辑文件夹:`inbox` / `sent` / `drafts` / `trash` / `junk` / `archive`。
+         * @param query     关键词;空串返回空数组。
+         * @param limit     返回条数上限,缺省 20,取最新的那几封。
+         * @returns 命中的邮件头列表(MailHeaderDto[]),最新在前。
+         * @throws 账户不存在报 MAIL_ACCOUNT_NOT_FOUND(404)。
+         */
+        search: (accountId: string, folder: MailFolderId, query: string, limit?: number) => Promise<any>;
+        /**
+         * 读取单封邮件的完整正文(text/html、收发人、附件元信息)。不改变已读状态,标已读用 flag。
          *
          * @param accountId 账户唯一标识。
          * @param folder    邮件所在逻辑文件夹。
          * @param uid       邮件唯一标识(IMAP UID)。
-         * @returns 邮件完整正文(MailBodyDto),含 text / html / 收发人 / 附件元信息。
+         * @returns 邮件完整正文(MailBodyDto),含 text / html / 收发人 / Reply-To / Message-ID 与 References / 附件元信息。
          * @throws 账户不存在或 uid 无对应邮件时抛错。
          */
         read: (accountId: string, folder: MailFolderId, uid: string) => Promise<any>;
@@ -151,8 +165,8 @@ export default class Mail {
      * 投递成功后会尽力把副本追加到「已发送」文件夹(追加失败不影响发信结果)。
      *
      * @param accountId 账户唯一标识。
-     * @param input     发信参数:to / subject 必填,cc / bcc / text / html / inReplyTo 可选。
-     * @returns 发送结果,含 `messageId`(SMTP 返回的 message-id)。
+     * @param input     发信参数:to / subject 必填,cc / bcc / text / html / inReplyTo / references 可选。
+     * @returns 发送结果:`messageId`(SMTP 返回的 message-id)与 `appendedToSent`(false 表示已发出但没能存进「已发送」)。
      * @throws 账户不存在或 SMTP 投递失败时抛错。
      */
     send: (accountId: string, input: SendMailInput) => Promise<any>;

package/types/System.d.ts

@@ -8,6 +8,18 @@ export default class System {
     /** Solazah 在用户家目录下的**本渠道**根目录绝对路径(机器级:日志、缓存、运行时;账号的东西在 accounts/<账号>/ 下)。
      * @returns 形如 `C:\Users\<用户>\.solazah` 的绝对路径 */
     getSolazahHome: () => Promise<string>;
+    /** 当前用户常用目录的绝对路径,取自操作系统登记的位置(已跟随 OneDrive 等重定向)。
+     * 自己拼「家目录 + Desktop」在桌面被重定向时会指错地方,要用这里的值。
+     * @returns `{home, desktop, downloads, documents, pictures, music, videos}`,各为绝对路径;系统没登记的那一项为 null */
+    getUserFolders: () => Promise<{
+        home: string | null;
+        desktop: string | null;
+        downloads: string | null;
+        documents: string | null;
+        pictures: string | null;
+        music: string | null;
+        videos: string | null;
+    }>;
     /** 显示并聚焦 Solazah 主窗口(搜索框);主窗口不存在时不做任何事。
      * @returns 无返回 */
     openMainApp: () => Promise<any>;

package/types/SystemAudio.d.ts

@@ -5,7 +5,7 @@ export default class SystemAudio {
     /**
      * 播放内置音效目录下的指定音频文件。
      * 同一时刻只能播放一个音效，新播放会自动中断当前正在播放的音效。
-     * macOS 上通过系统 afplay 子进程播放，其余平台通过原生 addon 播放。
+     * 通过原生 addon 播放：Windows PlaySound / macOS NSSound。
      *
      * @param soundName 音效文件名，不含扩展名时自动补 `.wav`。
      * @returns 无返回值（播放是异步副作用）。
@@ -14,7 +14,7 @@ export default class SystemAudio {
     play: (soundName: string) => Promise<any>;
     /**
      * 停止当前正在播放的音效。
-     * macOS 上终止 afplay 子进程，其余平台通过原生 addon 停止。
+     * 停止当前由原生 addon 播放的音效。
      * 若无音效在播则不执行任何操作。
      *
      * @returns 无返回值。

package/types/SystemMouse.d.ts

@@ -1,5 +1,8 @@
 import { default as IpcRenderer } from './IpcRenderer';
-import { Point } from '@computer-use/nut-js';
+export interface Point {
+    x: number;
+    y: number;
+}
 export default class SystemMouse {
     private transport;
     constructor(transport?: IpcRenderer);

package/types/SystemScreen.d.ts

@@ -1,5 +1,8 @@
 import { default as IpcRenderer } from './IpcRenderer';
-import { Point } from '@computer-use/nut-js';
+export interface Point {
+    x: number;
+    y: number;
+}
 /** 原始位图:BGRA、自顶向下、每像素 4 字节,与截图流 raw 帧同一格式。手里已经是像素时直接给它,省掉编码与解码。 */
 export interface RawImage {
     width: number;
@@ -151,6 +154,54 @@ export type BlobSource = string | {
     region?: ScreenRect;
     image?: string;
 };
+/** findFlicker 的参数：在哪块截、截多久、多快，以及闪光判据。坐标都是显示器物理像素、相对显示器左上角。 */
+export interface FlickerOptions {
+    /** 目标显示器 id；省略取光标所在显示器 */
+    displayId?: number;
+    /** 只看这一块；省略整屏。聊天框这类会滚字的界面要排除在外 */
+    region?: ScreenRect;
+    /** 连截多久，缺省 4000 */
+    durationMs?: number;
+    /** 每秒截几帧，1..30，缺省 4 */
+    fps?: number;
+    /** 和前后各几帧比，缺省 4 */
+    halfWindow?: number;
+    /** 亮度要比前后帧的中位数高出多少才算闪，0..255，缺省 45 */
+    lift?: number;
+    /** 闪光像素的最低亮度（三通道最大值），缺省 140 */
+    minValue?: number;
+    /** 闪光的色相范围（角度），缺省 45..85，即偏黄绿的星光 */
+    hueLow?: number;
+    hueHigh?: number;
+    /** 闪光的最低饱和度 0..1，缺省 0.25 */
+    minSaturation?: number;
+    /** 一个光点的像素数范围，缺省 4..40 */
+    minSize?: number;
+    maxSize?: number;
+    /** 同一帧里多近的闪光像素合成一个光点，缺省 6 */
+    groupRadius?: number;
+    /** 多近的光点算同一处，缺省 50 */
+    clusterRadius?: number;
+    /** 最多返回几处，缺省 10 */
+    maxResults?: number;
+    /** 取消记号，同 WaitOptions.token */
+    token?: string;
+}
+/** 反复冒光点的一处：中心（屏幕物理像素）、冒过光点的帧数、光点总数。 */
+export interface FlickerCluster {
+    x: number;
+    y: number;
+    frames: number;
+    spots: number;
+}
+/** 按冒过光点的帧数降序；unstableFrames 是画面整体在动、被跳过的帧数。 */
+export interface FlickerResult {
+    clusters: FlickerCluster[];
+    frames: number;
+    unstableFrames: number;
+    durationMs: number;
+    cancelled: boolean;
+}
 export interface RecordStartOptions {
     /** 目标显示器 id；省略取光标所在显示器 */
     displayId?: number;
@@ -476,6 +527,14 @@ export default class SystemScreen {
      * @returns `[{x, y, width, height, area, cx, cy}]`；给图片时坐标相对图片左上角，截屏时是屏幕物理像素坐标。找不到是空数组。
      */
     findBlobs: (source: BlobSource, options: ColorBlobOptions) => Promise<ColorBlob[]>;
+    /**
+     * 闪烁光点：在显示器的一块区域上连截一段，找反复冒小光点的地方——游戏里可采集物冒出的星光、界面上闪的提示点。
+     * 静止的东西每帧一样亮，只有闪的才比前后帧亮出来；同一处反复冒光点的排在前面。截帧期间视角要保持不动。
+     *
+     * @param options `{displayId?, region?, durationMs?, fps?, hueLow?, hueHigh?, …, token?}`，见 FlickerOptions。
+     * @returns `{clusters: [{x, y, frames, spots}], frames, unstableFrames, durationMs, cancelled}`，坐标是屏幕物理像素；找不到 clusters 为空。
+     */
+    findFlicker: (options?: FlickerOptions) => Promise<FlickerResult>;
     /**
      * 屏幕录制：采集与编码全在宿主的原生线程（mac ScreenCaptureKit + VideoToolbox 硬件 H.264，Windows WGC + Media Foundation），
      * mp4 或 gif 直接写到给定路径，页面不经手任何帧。同一时刻只有一个会话；本视图销毁、到了 maxSeconds 都会自动停。

package/types/Workspace.d.ts

@@ -42,6 +42,14 @@ export default class Workspace {
      * @returns 工作空间数组,每项的 path 已被覆写为本机有效路径(本地覆盖优先于同步值)。空列表表示尚无工作空间。
      */
     list: () => Promise<WorkspaceDto[]>;
+    /**
+     * 宿主默认的排除规则(敏感文件 + 大型生成目录),注册工作空间不指定 excludeGlobs 时用的就是它。
+     * 插件扫描工作空间以外的目录时用这一份,不要自带名单;匹配语义:以 `/` 结尾的匹配任一层目录名,
+     * 其余按简化 glob(`*` 不跨目录、`**` 跨目录、`?` 单字符)匹配相对路径或文件名。
+     *
+     * @returns glob 数组。
+     */
+    defaultExcludeGlobs: () => Promise<string[]>;
     /**
      * 按 id 获取单个工作空间。
      *