@solazah/solazah-runtime 0.0.156 → 0.0.158

package/types/Mail.d.ts

@@ -29,27 +29,152 @@ export default class Mail {
     private transport;
     constructor(transport?: IpcRenderer);
     accounts: {
+        /**
+         * 列出所有已配置的邮箱账户(不含密码)。
+         *
+         * @returns 账户信息数组(MailAccountDto[]),各账户的 password 字段不返回。
+         */
         list: () => Promise<any>;
+        /**
+         * 按 id 取单个账户信息(不含密码)。
+         *
+         * @param id 账户唯一标识。
+         * @returns 账户信息(MailAccountDto);不存在返回 null。
+         */
         get: (id: string) => Promise<any>;
+        /**
+         * 新增邮箱账户,返回落库后的账户信息(含生成的 id)。
+         * 明文密码不入库,单独存本机 safeStorage 密钥库(不同步、不绑 Solazah 账号)。
+         *
+         * @param input 账户配置;email / password / imapHost / imapPort / smtpHost / smtpPort 为必填项,
+         *              displayName 缺省取 email,imapSecure / smtpSecure 缺省 true。
+         * @returns 落库后的账户信息(MailAccountDto,不含密码)。
+         * @throws 必填项缺失报 MAIL_BAD_INPUT(400)。
+         */
         add: (input: MailAccountInput) => Promise<any>;
+        /**
+         * 局部更新账户;patch 只需带要改的字段,返回更新后的账户信息。
+         * 带 password 时同步刷新本机密钥库;任何改动都会丢弃该账户的现有 IMAP/SMTP 连接。
+         *
+         * @param id    账户唯一标识。
+         * @param patch 要更新的字段(Partial<MailAccountInput>),只传要改的字段即可。
+         * @returns 更新后的账户信息(MailAccountDto,不含密码)。
+         * @throws 账户不存在报 MAIL_ACCOUNT_NOT_FOUND(404)。
+         */
         update: (id: string, patch: Partial<MailAccountInput>) => Promise<any>;
+        /**
+         * 删除账户:断开 IMAP/SMTP 连接、清本机密钥库里的密码、删库记录。
+         *
+         * @param id 账户唯一标识;账户不存在也视为成功。
+         * @returns 始终返回 true。
+         */
         remove: (id: string) => Promise<any>;
+        /**
+         * 用入参临时建连,测试 IMAP + SMTP 是否可连可鉴权(不落库)。
+         *
+         * @param input 账户配置;必填项同 addAccount。
+         * @returns 通过返回 {ok:true, imap:true, smtp:true};失败返回 {ok:false, error} 供配置界面提示。
+         * @throws 必填项缺失报 MAIL_BAD_INPUT(400)。
+         */
         test: (input: MailAccountInput) => Promise<any>;
     };
     folders: {
+        /**
+         * 列出账户的邮箱文件夹(收件/已发/草稿/垃圾/归档等逻辑文件夹到真实路径的映射)。
+         *
+         * @param accountId 账户唯一标识。
+         * @returns 逻辑文件夹列表(MailFolderDto[]),含 id / path / name。
+         * @throws 账户不存在报 MAIL_ACCOUNT_NOT_FOUND(404)。
+         */
         list: (accountId: string) => Promise<any>;
     };
     messages: {
+        /**
+         * 拉取指定文件夹的邮件头列表(不含正文),按逻辑文件夹寻址。
+         * 会顺带刷新账户的 lastSyncAt。
+         *
+         * @param accountId  账户唯一标识。
+         * @param folder     逻辑文件夹:`inbox` / `sent` / `drafts` / `trash` / `junk` / `archive`。
+         * @param limit      返回条数上限,缺省 50。
+         * @param unseenOnly 为 true 时只返回未读邮件,缺省 false。
+         * @returns 邮件头列表(MailHeaderDto[]),不含正文。
+         * @throws 账户不存在报 MAIL_ACCOUNT_NOT_FOUND(404)。
+         */
         list: (accountId: string, folder: MailFolderId, limit?: number, unseenOnly?: boolean) => Promise<any>;
+        /**
+         * 读取单封邮件的完整正文(text/html、收发人、附件元信息)。
+         *
+         * @param accountId 账户唯一标识。
+         * @param folder    邮件所在逻辑文件夹。
+         * @param uid       邮件唯一标识(IMAP UID)。
+         * @returns 邮件完整正文(MailBodyDto),含 text / html / 收发人 / 附件元信息。
+         * @throws 账户不存在或 uid 无对应邮件时抛错。
+         */
         read: (accountId: string, folder: MailFolderId, uid: string) => Promise<any>;
+        /**
+         * 设置邮件的已读(seen)/星标(flagged)标记,只传要改的位。
+         *
+         * @param accountId 账户唯一标识。
+         * @param folder    邮件所在逻辑文件夹。
+         * @param uid       邮件唯一标识(IMAP UID)。
+         * @param flags     要修改的标记:`seen` 已读,`flagged` 星标;只传要改的字段即可。
+         * @returns 成功返回 true。
+         * @throws 账户不存在或 IMAP 操作失败时抛错。
+         */
         flag: (accountId: string, folder: MailFolderId, uid: string, flags: {
             seen?: boolean;
             flagged?: boolean;
         }) => Promise<any>;
+        /**
+         * 把邮件从当前文件夹移动到目标文件夹。
+         *
+         * @param accountId 账户唯一标识。
+         * @param folder    邮件当前所在的逻辑文件夹。
+         * @param uid       邮件唯一标识(IMAP UID)。
+         * @param target    目标逻辑文件夹。
+         * @returns 成功返回 true。
+         * @throws 账户不存在或 IMAP 操作失败时抛错。
+         */
         move: (accountId: string, folder: MailFolderId, uid: string, target: MailFolderId) => Promise<any>;
+        /**
+         * 删除指定文件夹里的一封邮件。
+         *
+         * @param accountId 账户唯一标识。
+         * @param folder    邮件所在逻辑文件夹。
+         * @param uid       邮件唯一标识(IMAP UID)。
+         * @returns 成功返回 true。
+         * @throws 账户不存在或 IMAP 操作失败时抛错。
+         */
         delete: (accountId: string, folder: MailFolderId, uid: string) => Promise<any>;
     };
+    /**
+     * 通过账户的 SMTP 发送一封邮件。
+     * 投递成功后会尽力把副本追加到「已发送」文件夹(追加失败不影响发信结果)。
+     *
+     * @param accountId 账户唯一标识。
+     * @param input     发信参数:to / subject 必填,cc / bcc / text / html / inReplyTo 可选。
+     * @returns 发送结果,含 `messageId`(SMTP 返回的 message-id)。
+     * @throws 账户不存在或 SMTP 投递失败时抛错。
+     */
     send: (accountId: string, input: SendMailInput) => Promise<any>;
+    /**
+     * 把邮件存到账户的「草稿箱」文件夹。
+     * 传相同 draftKey 会先清掉该 key 的旧草稿再存新的(实现同一草稿的覆盖更新)。
+     *
+     * @param accountId 账户唯一标识。
+     * @param input     邮件内容(SendMailInput)。
+     * @param draftKey  草稿标识;传相同值实现覆盖更新,省略则新建草稿。
+     * @returns `{ok: true, uid?: string}`,uid 为草稿邮件的 IMAP UID(新建时有值)。
+     * @throws 账户不存在或账户没有草稿箱时报错。
+     */
     saveDraft: (accountId: string, input: SendMailInput, draftKey?: string) => Promise<any>;
+    /**
+     * 按 draftKey 从草稿箱删除对应草稿。
+     *
+     * @param accountId 账户唯一标识。
+     * @param key       草稿标识(draftKey);草稿不存在也视为成功。
+     * @returns 始终返回 true。
+     * @throws 账户不存在报 MAIL_ACCOUNT_NOT_FOUND(404)。
+     */
     discardDraft: (accountId: string, key: string) => Promise<any>;
 }

package/types/Plugin.d.ts

@@ -20,13 +20,74 @@ export default class Plugin {
     tool: (name: string, description: string, schema: string, cb: any) => any;
     onSearch: (commandName: string, handler: any) => Promise<void>;
     onAction: (commandName: string, action: string, handler: any) => Promise<void>;
+    /**
+     * 切换发起方插件窗口的开发者工具(DevTools)显示/隐藏。
+     * 操作发起方 webContents,不传任何参数;已打开则关闭,已关闭则打开。
+     *
+     * @returns 无返回。
+     */
     toggleDevTools: () => Promise<any>;
+    /**
+     * 把发起方插件窗口的高度设为指定像素值,宽度不变。
+     *
+     * @param height 目标高度(像素)。
+     * @returns 无返回。窗口不存在时静默忽略。
+     */
     setHeight: (height: number) => Promise<any>;
+    /**
+     * 把发起方插件的当前视图移入一个浮动窗口(floating)承载并显示到前台。
+     * 浮窗按插件名(带当前视图 hash)缓存复用;插件视图未加载时不做任何操作。
+     *
+     * @param options 浮动窗口配置对象,可选字段:width/height/x/y/minWidth/minHeight/aspectRatio/alwaysOnTop/resizable。
+     * @returns 无返回。
+     */
     floating: (options?: any) => Promise<any>;
+    /**
+     * 收起发起方插件窗口。发起方是主窗口时回到启动器主页;
+     * floating 浮窗做 cloak(不驱逐渲染表面,再唤起不白屏),普通窗口真正 hide()。
+     *
+     * @returns 无返回。
+     */
     hide: () => Promise<any>;
+    /**
+     * 切换发起方窗口的置顶状态(screen-saver 级),返回切换后的状态。
+     * 同时向发起方视图广播 plugin.alwaysOnTopChanged 事件,便于渲染层同步回显。
+     *
+     * @returns 切换后的置顶状态(boolean)。
+     */
     toggleAlwaysOnTop: () => Promise<any>;
+    /**
+     * 取发起方插件自身的完整信息。
+     * 通过 webContents 逆向定位插件,返回插件实体字段 + 其全部命令(commands 数组)+
+     * 键值对形式的设置(settings 对象)。
+     *
+     * @returns 包含插件字段、commands 数组和 settings 键值对的对象;无法定位发起方插件时返回 undefined。
+     */
     info: () => Promise<any>;
+    /**
+     * 按命令名批量注销发起方插件的运行时命令,从启动器移除。
+     * 按命令名(name)和插件名(pluginName)联合匹配删除;仅删运行时命令,manifest 命令不受影响。
+     *
+     * @param commands 要注销的命令名数组。
+     * @returns 无返回。无法定位发起方插件时静默返回 null。
+     */
     unregisterCommands: (commands: string[]) => Promise<any>;
+    /**
+     * 为发起方插件增量注册运行时命令。
+     * 按确定性主键 upsert(同名覆盖),不删除任何已有命令,不影响 manifest 命令。
+     * 命令先通过 PluginCommand.parseCommands 解析为 PluginCommand 实体再入库。
+     *
+     * @param commandItems 命令项数组,每项包含 name/awaken/keyword 等字段。
+     * @returns 无返回。无法定位发起方插件时静默返回 null。
+     */
     registerCommands: (commandItems: any[]) => Promise<any>;
+    /**
+     * 用传入集全量覆盖发起方插件的运行时命令。
+     * 不在集内的运行时命令会被删除,manifest 命令(fromManifest===true)完全不受波及。
+     * 命令先通过 PluginCommand.parseCommands 解析为 PluginCommand 实体再入库。
+     *
+     * @param commandItems 命令项数组,每项包含 name/awaken/keyword 等字段。
+     * @returns 无返回。无法定位发起方插件时静默返回 null。
+     */
     setCommands: (commandItems: any[]) => Promise<any>;
 }

package/types/PluginCommand.d.ts

@@ -2,9 +2,47 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class PluginCommand {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 按命令名打开对应插件命令：先查找命令，记录一次使用，然后委托 PluginRunner 打开。
+     *
+     * @param commandName 命令名称。
+     * @param payload 进入参数，透传给 PluginRunner。
+     * @returns PluginRunner.open 的执行结果；命令或其所属插件不存在时返回 undefined。
+     */
     open: (commandName?: string, payload?: any) => Promise<any>;
+    /**
+     * 向一个已打开的命令视图再次投递 plugin.onEnter 事件，委托 PluginRunner 执行。
+     *
+     * @param commandName 命令名称。
+     * @param payload 进入参数，透传给 PluginRunner.onEnter。
+     * @returns 无返回。
+     */
     enter: (commandName?: string, payload?: any) => Promise<any>;
+    /**
+     * 按关键字搜索启动器可用命令。
+     * 仅取已启用插件下未隐藏、已启用的命令：先按 keyword 模糊匹配 keyword 类命令，
+     * 再加上所有 anyText 命令与正则匹配的 regexp 命令，
+     * 按完全匹配 → 使用频率 → 前缀匹配 → 包含匹配等综合排序后返回；
+     * 返回结果中缺图标的命令会回填所属插件的图标。
+     *
+     * @param keyword 搜索关键字，传入后转为小写进行模糊匹配。
+     * @returns 排序后的 PluginCommand 数组，含回填图标。
+     */
     search: (keyword: string) => Promise<any>;
+    /**
+     * 设置某条命令的别名列表，并据此重建其搜索关键字。
+     *
+     * @param name 命令名称。
+     * @param alias 新的别名列表，全量替换原有别名；别名会与命令名一起被 KeywordBuilder 合成为搜索关键字。
+     * @returns 无返回。
+     */
     setAlias: (name: string, alias: string[]) => Promise<any>;
+    /**
+     * 启用或停用某条命令，并广播命令变更事件。停用后该命令不再出现在搜索结果中。
+     *
+     * @param name 命令名称。
+     * @param enabled true 启用，false 停用。
+     * @returns 无返回。
+     */
     setEnabled: (name: string, enabled: boolean) => Promise<any>;
 }

package/types/PluginManager.d.ts

@@ -2,11 +2,58 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class Plugin {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 切换指定插件所有视图的开发者工具开关。
+     *
+     * @param pluginId 插件 ID。
+     * @returns 无返回
+     */
     toggleDevTools: (pluginId?: string) => Promise<any>;
+    /**
+     * 关闭指定插件的所有视图(卸载 WebContentsView),不销毁已创建的窗口。
+     *
+     * @param pluginId 插件 ID。
+     * @returns Promise<void>
+     */
     closePlugin: (pluginId?: string) => Promise<any>;
+    /**
+     * 获取插件完整信息:合并 DB 中的插件实体、manifest 里的 preferences(含环境变量占位符展开)、
+     * 命令列表、当前所有设置项键值对,以及从 manifest 磁盘文件读取的 AI 能力声明(tools / skills)。
+     *
+     * @param pluginId 插件 ID。
+     * @returns 包含插件基础字段、preferences、commands、settings 键值对和 aiDeclaration 的聚合对象;
+     *          插件不存在时返回 undefined。
+     */
     getPluginInfo: (pluginId?: string) => Promise<any>;
+    /**
+     * 启用或禁用指定插件:更新 DB 中的 enabled 字段,并发布 PluginUpdatedEvent 通知外部消费者。
+     *
+     * @param pluginId 插件 ID。
+     * @param enabled  true 启用,false 禁用。
+     * @returns 插件不存在时返回 null;成功时返回 undefined。
+     */
     setEnabled: () => Promise<any>;
+    /**
+     * 获取所有已安装插件的列表。
+     *
+     * @returns Plugin[] 全部插件实体数组。
+     */
     getPlugins: () => Promise<any>;
+    /**
+     * 重载指定插件的所有视图和窗口:先记录当前窗口状态(可见性、位置),
+     * 销毁视图和窗口后重新加载启动视图,并恢复此前可见的窗口。
+     *
+     * @param pluginId 插件 ID。
+     * @returns Promise<void>。
+     */
     reloadPlugin: (pluginId: string) => Promise<any>;
+    /**
+     * 安装指定插件。先执行 npm install,再解析 manifest.json 写入 DB 并注册命令;
+     * 若插件已安装则仅同步最新的 manifest 字段到 DB,并发布 PluginUpdatedEvent。
+     *
+     * @param name 插件名称(npm 包名)或本地开发目录的绝对路径。
+     * @returns Promise<void>。
+     * @throws 未直接抛错;npm install 失败或 manifest.json 缺失时记录错误并静默返回。
+     */
     installPlugin: (name: string) => Promise<any>;
 }

package/types/PluginSettings.d.ts

@@ -2,8 +2,32 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class PluginSettings {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 获取发起方插件的全部设置项，以键值对形式返回。
+     *
+     * @returns 包含该插件所有设置 key→value 的键值对象（Record<string, any>）；无法定位发起方插件时返回 undefined。
+     */
     getSettings: () => Promise<any>;
+    /**
+     * 获取发起方插件中指定 key 的设置值。
+     *
+     * @param key 设置的键名。
+     * @returns 该 key 对应的值；key 不存在或值为 null/undefined 时返回 null，false/0/"" 视为合法值原样返回。无法定位发起方插件时返回 undefined。
+     */
     getSetting: (key: string) => Promise<any>;
+    /**
+     * 写入（新增或覆盖）发起方插件中指定 key 的设置值。key 已存在则更新，不存在则新建。
+     *
+     * @param key   设置的键名；可选。
+     * @param value 设置值，可为任意 JSON 可序列化的值；可选。
+     * @returns 无返回。无法定位发起方插件时不执行任何操作。
+     */
     saveSetting: (key: string, value: any) => Promise<any>;
+    /**
+     * 删除发起方插件中指定 key 的设置项。
+     *
+     * @param key 要删除的设置的键名；可选。
+     * @returns 无返回。无法定位发起方插件或该 key 对应的设置不存在时不执行任何操作。
+     */
     removeSetting: (key: string) => Promise<any>;
 }

package/types/Sync.d.ts

@@ -41,6 +41,11 @@ export default class Sync {
     private readonly appliedCallbacks;
     private appliedBound;
     constructor(transport?: IpcRenderer);
+    /**
+     * 获取当前同步模块的完整运行状态。
+     *
+     * @returns 同步状态对象,包含 enabled(开关)、configured(传输层是否就绪)、transport(传输方式描述)、loggedIn(是否登录)、running(是否正在同步)、lastSyncAt(上次完成时间戳)、lastError(上次错误)、pushedSeq(本端已推最大版本号)、namespace(账号命名空间)等字段。
+     */
     getStatus: () => Promise<SyncStatusDto>;
     /** 改配置(开关 / 传输方式 / 本地目录 / 端到端口令),返回最新状态。 */
     configure: (patch: SyncConfigPatch) => Promise<SyncStatusDto>;

package/types/System.d.ts

@@ -2,35 +2,97 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class System {
     private transport;
     constructor(transport?: IpcRenderer);
+    /** 返回当前运行平台标识("win32" / "darwin" / "linux" 等,同 Node process.platform)。
+     * @returns 平台标识字符串 */
     getPlatform: () => Promise<any>;
+    /** 显示并聚焦 Solazah 主窗口(搜索框);主窗口不存在时不做任何事。
+     * @returns 无返回 */
     openMainApp: () => Promise<any>;
+    /** 弹出「关于 Solazah Desktop」对话框,展示版本号、Electron/V8/Node.js 版本和操作系统信息;等待用户点确认后返回。
+     * @returns 无返回 */
     showAbout: () => Promise<any>;
+    /** 打开 Solazah 设置界面(触发内置设置插件的 Solazah Settings 命令);设置插件/命令缺失时静默不打开。
+     * @returns 无返回 */
     openSettings: () => Promise<any>;
+    /** 主动检查应用更新;此路径会向用户提示检查结果(无新版本也会告知)。
+     * @returns 无返回 */
     checkUpdates: () => Promise<any>;
+    /** 立即重启整个应用(当前进程退出后重新拉起)。
+     * @returns 无返回 */
     restartApp: () => Promise<any>;
+    /** 退出整个应用,关闭所有窗口并结束进程。
+     * @returns 无返回 */
     quitApp: () => Promise<any>;
     keepAwake: {
+        /**
+         * 启动系统唤醒锁定，阻止显示器关闭与系统自动锁屏。
+         *
+         * 使用 Electron powerSaveBlocker 的 prevent-display-sleep 模式，
+         * 在 macOS 与 Windows 上行为一致：同时阻止熄屏与系统锁屏。
+         * 若已处于激活状态，则仅更新锁定原因(reason)并返回当前状态，不会重复启动。
+         *
+         * @param options 可选配置对象。
+         * @param options.reason 锁定原因说明，用于日志记录与状态追踪。
+         * @returns 锁定状态对象，包含 active(是否已激活)与 reason(锁定原因)。
+         */
         enable: (options?: {
             reason?: string;
         }) => Promise<{
             active: boolean;
             reason: string | null;
         }>;
+        /**
+         * 停止系统唤醒锁定，恢复正常的显示器关闭与系统锁屏行为。
+         *
+         * 若当前无活跃的唤醒锁定，调用此方法也会将内部状态重置为未激活，不会抛错。
+         *
+         * @returns 状态对象，active 固定为 false 表示锁定已解除。
+         */
         disable: () => Promise<{
             active: boolean;
         }>;
+        /**
+         * 切换系统唤醒锁定状态：当前已激活则关闭锁定，未激活则开启锁定。
+         *
+         * 先查询当前状态再决定操作方向，两次调用之间状态可能被其他 renderer 改变，
+         * 因此结果以实际执行后的返回值为准。
+         *
+         * @param options 可选配置对象，仅在从未激活切换为激活时生效。
+         * @param options.reason 锁定原因说明。
+         * @returns 切换后的锁定状态对象。
+         */
         toggle: (options?: {
             reason?: string;
         }) => Promise<{
             active: boolean;
             reason?: string | null;
         }>;
+        /**
+         * 查询当前系统唤醒锁定的激活状态与锁定原因。
+         *
+         * @returns 状态对象，包含 active(是否已激活)与 reason(锁定原因，未激活时为 null)。
+         */
         status: () => Promise<{
             active: boolean;
             reason: string | null;
         }>;
     };
     scheduledTask: {
+        /**
+         * 创建一个新的定时任务并持久化；若 enabled 为 true 则立即注册到 cron 调度引擎。
+         *
+         * @param input 创建参数：
+         *   - name     任务名称。
+         *   - cron     cron 表达式字符串；必须通过 node-cron 校验。
+         *   - action   动作描述对象；至少包含 `type` 字段，用于在 ScheduledActionRegistry 中定位 handler；其余字段由 handler 自行解释。
+         *   - kind     `"recurring"`(默认，按 cron 周期重复) 或 `"once"`(触发一次后自动停用)。
+         *   - enabled  是否启用；省略默认 true。
+         *   - timezone 可选时区；传给 node-cron 的调度选项。
+         *   - expiresAt 可选过期时间；到期后任务自动作废(停 job + 禁用 + 留痕)。
+         * @returns 持久化后的 ScheduledTask 实体。
+         * @throws cron 表达式无效时抛 `invalid cron expression: ...`。
+         * @throws action.type 未在 ScheduledActionRegistry 注册时抛 `unknown scheduled action type: ...`。
+         */
         create: (input: {
             name: string;
             cron: string;
@@ -38,13 +100,57 @@ export default class System {
             enabled?: boolean;
             timezone?: string;
         }) => Promise<any>;
+        /**
+         * 部分更新已有定时任务：先停旧 cron job，应用 patch 后再按新 enabled 状态决定是否重新调度。
+         *
+         * @param id    目标任务 id。
+         * @param patch 部分字段更新；可包含 cron / action / name / enabled / kind / timezone / expiresAt 等任意 ScheduledTask 字段的子集。
+         *              若提供 cron 则须通过 node-cron 校验；若提供 action 则其 type 须已注册。
+         * @returns 更新后的 ScheduledTask 实体；任务不存在时返回 null。
+         * @throws 提供的 cron 表达式无效时抛 `invalid cron expression: ...`。
+         * @throws 提供的 action.type 未注册时抛 `unknown scheduled action type: ...`。
+         */
         update: (id: string, patch: any) => Promise<any>;
+        /**
+         * 删除指定定时任务，同时取消其 cron job 调度。
+         *
+         * @param id 目标任务 id。
+         * @returns true 表示至少删除了一条记录；false 表示目标不存在。
+         */
         delete: (id: string) => Promise<any>;
+        /**
+         * 列出所有定时任务，按创建时间倒序排列。
+         *
+         * @returns ScheduledTask 数组；无任务时为空数组。
+         */
         list: (filter?: {
             pluginName?: string;
         }) => Promise<any>;
+        /**
+         * 启用或禁用指定定时任务。内部委托 update({enabled})，因此同样会停/启 cron job。
+         *
+         * @param id      目标任务 id。
+         * @param enabled true 启用，false 禁用。
+         * @returns 更新后的 ScheduledTask 实体；任务不存在时返回 null。
+         */
         toggle: (id: string, enabled: boolean) => Promise<any>;
+        /**
+         * 立即手动触发一次指定任务，不影响原有 cron 排期。
+         * 触发过程包含：过期作废检查、重叠保护(上次 run 未结束则跳过)、
+         * handler 路由与执行、状态回写(lastRunAt / lastStatus / lastError)，
+         * 以及 once 类型触发后自动停调度的逻辑。
+         *
+         * @param id 目标任务 id。
+         * @returns `{ok: boolean; error?: string}`；ok 为 true 表示触发成功进入执行，
+         *          ok 为 false 时 error 说明原因(如 "task not found" / "task disabled" / "expired" / "previous run still in flight")。
+         */
         runNow: (id: string) => Promise<any>;
+        /**
+         * 校验 cron 表达式合法性(委托 node-cron 的 validate)。
+         *
+         * @param expr cron 表达式字符串。
+         * @returns true 表示表达式合法可调度；false 表示无效。
+         */
         validateCron: (expr: string) => Promise<boolean>;
     };
 }

package/types/SystemAudio.d.ts

@@ -2,7 +2,29 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class SystemAudio {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 播放内置音效目录下的指定音频文件。
+     * 同一时刻只能播放一个音效，新播放会自动中断当前正在播放的音效。
+     * macOS 上通过系统 afplay 子进程播放，其余平台通过原生 addon 播放。
+     *
+     * @param soundName 音效文件名，不含扩展名时自动补 `.wav`。
+     * @returns 无返回值（播放是异步副作用）。
+     * @throws 文件不存在时抛错，错误消息格式为 `Sound file not found: <soundName>`。
+     */
     play: (soundName: string) => Promise<any>;
+    /**
+     * 停止当前正在播放的音效。
+     * macOS 上终止 afplay 子进程，其余平台通过原生 addon 停止。
+     * 若无音效在播则不执行任何操作。
+     *
+     * @returns 无返回值。
+     */
     stop: () => Promise<any>;
+    /**
+     * 列出内置音效目录下所有可播放的音频文件名（含扩展名）。
+     * 仅筛选 `.wav`、`.mp3`、`.ogg` 三种格式（不区分大小写）。
+     *
+     * @returns 音频文件名数组；音效目录不存在时返回空数组 `[]`。
+     */
     list: () => Promise<string[]>;
 }