@solazah/solazah-runtime 0.0.156 → 0.0.157

package/package.json

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

package/types/Account.d.ts

@@ -2,8 +2,36 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class Account {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 发起 OAuth2 PKCE 登录流程:生成 code_verifier / code_challenge / state,
+     * 在系统浏览器中打开授权页。登录结果经协议回调(solazah://oauth2/callback
+     * 或本地 HTTP 回调)异步完成,不通过本调用返回。
+     *
+     * @returns 无返回。
+     */
     login: () => Promise<any>;
+    /**
+     * 登出当前账号:清除本地缓存的令牌、用户信息与刷新定时器;
+     * 若当前会话持有 id_token,在系统浏览器中打开远端注销页结束服务端会话。
+     *
+     * @returns 无返回。
+     */
     logout: () => Promise<any>;
+    /**
+     * 查询当前登录状态。若已存储的 access_token 过期(距 expires_at 不足 60 秒),
+     * 先尝试用 refresh_token 静默刷新;刷新成功返回已登录及缓存用户信息,
+     * 刷新失败(如 refresh_token 也失效)则按未登录返回。
+     *
+     * @returns 登录状态对象 `{ isLoggedIn: boolean; user: any | null }`;
+     *          isLoggedIn 为 true 时 user 为缓存的最新用户信息,否则为 null。
+     */
     getState: () => Promise<any>;
+    /**
+     * 用当前 access_token 向 userinfo 端点(OpenID Connect)拉取最新用户信息并缓存。
+     * 不触发令牌刷新:若本地无令牌则直接返回 null。
+     *
+     * @returns 用户信息 JSON 对象(内容取决于服务端 userinfo 响应);
+     *          未登录或 HTTP 请求失败时返回 null。
+     */
     getUserInfo: () => Promise<any>;
 }

package/types/Copilot.d.ts

@@ -88,9 +88,26 @@ export default class Copilot {
     ipcRenderer: IpcRenderer;
     private seq;
     constructor();
+    /**
+     * 单轮补全:按 options.model(缺省用默认补全模型)一次性生成并直接返回完整文本,
+     * 不流式、不落对话历史。
+     *
+     * @param input   补全的提示词文本。
+     * @param options 补全选项。model 缺省时使用系统设置的默认补全模型;
+     *                也支持 temperature / timeout / messages / enableThinking / reasoningEffort。
+     * @returns 生成的完整文本内容。
+     * @throws 模型不存在或 provider 不支持时抛错;流式错误后配额已退还再抛原错。
+     */
     completion: (input: string, options: any) => Promise<any>;
     chat: (input: string, options: CopilotRunOptions) => Promise<AsyncIterableIterator<any>>;
     run: (input: string, options: CopilotRunOptions) => Promise<AsyncIterableIterator<any>>;
+    /**
+     * 按 requestId 中止正在进行的 chat/run/resume 流式执行:
+     * 触发对应 AbortController 并向 provider 发出中止信号。
+     *
+     * @param requestId 要中止的请求 ID,对应 chat/run/resume 传入的 requestId。
+     * @returns 无返回;requestId 无对应在跑运行时静默无操作。
+     */
     abort: (requestId: string) => Promise<any>;
     resume: (response: any, options: CopilotRunOptions) => Promise<AsyncIterableIterator<any>>;
     private invokeStream;

package/types/CopilotMcpServer.d.ts

@@ -9,11 +9,49 @@ export interface CopilotMcpInstalledMessage {
 export default class CopilotMcpServer {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 列出当前可用的 MCP server:用户自建的(pluginName 为空)加上归属于已启用插件的;归属已禁用插件的会被排除。
+     *
+     * @returns 所有可用的 MCP server 实体数组。
+     */
     getServers: () => Promise<any>;
+    /**
+     * 新增一个 MCP server 配置,返回落库后的完整实体(含自动生成的 id)。
+     *
+     * @param data MCP server 的部分字段,name/transport/command/url 等按需传入;未填字段取实体默认值。
+     * @returns 落库后的完整 CopilotMcpServer 实体(含自动生成的 id、created_at、updated_at)。
+     */
     addServer: (data: any) => Promise<any>;
+    /**
+     * 按 id 局部更新一个 MCP server 配置:只覆盖 data 中传入的字段,id/created_at/updated_at 等只读字段不会被覆盖。
+     *
+     * @param id   目标 MCP server 的 id。
+     * @param data 要合并进现有记录的字段(undefined 的字段会被置为 null)。
+     * @returns 更新后的完整 CopilotMcpServer 实体;id 不存在返回 null。
+     */
     updateServer: (id: string, data: any) => Promise<any>;
+    /**
+     * 按 id 删除一个 MCP server 配置。
+     *
+     * @param id 目标 MCP server 的 id。
+     * @returns TypeORM DeleteResult,可通过 affected 属性判断实际删除条数(0 或 1)。
+     */
     removeServer: (id: string) => Promise<any>;
+    /**
+     * 按 id 切换某个 MCP server 的启用/禁用状态。
+     *
+     * @param id      目标 MCP server 的 id。
+     * @param enabled true 启用,false 禁用。
+     * @returns TypeORM UpdateResult,可通过 affected 属性判断是否更新成功(0 表示 id 不存在)。
+     */
     toggleServer: (id: string, enabled: boolean) => Promise<any>;
+    /**
+     * 按名称测试一个已保存的 MCP server 能否成功连接。
+     * 先在库中按 name 查找;插件自带的 server(pluginName 非空)直接视为通过,不做实际连接测试。
+     *
+     * @param server MCP server 的名称(name 字段,非 id)。
+     * @returns true 表示连接成功或插件 server 跳过测试;false 表示 server 不存在或连接失败。
+     */
     testConnect: (server: string) => Promise<any>;
     /**
      * 订阅"agent 在对话里装好了一台 MCP server"通知。渲染层据此刷新列表、把新 server 并入

package/types/CopilotModel.d.ts

@@ -2,16 +2,95 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class CopilotModel {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 新增一个模型配置并入库,随后广播 copilot.model.changed 通知各渲染层刷新模型列表。
+     *
+     * @param model 要新增的模型配置对象,包含 name/provider/apiHost/apiKey 等字段;id 由 BeforeInsert 自动生成。
+     * @returns 无返回。
+     */
     add: (model: any) => Promise<any>;
+    /**
+     * 按 id 局部更新模型配置并广播刷新。
+     *
+     * @param modelId 目标模型的 id。
+     * @param model   包含要更新字段的模型对象;仅覆盖非只读字段,id/created_at/updated_at 不会被覆盖。
+     * @returns 模型不存在时静默返回;更新成功后无返回。
+     */
     update: (modelId: string, model: any) => Promise<any>;
+    /**
+     * 按 id 删除模型并广播刷新;模型不存在则静默返回。
+     * 内置免费模型、以及当前被设为默认对话/补全/GUI 的模型不允许删,会抛
+     * COPILOT_MODEL_REMOVE_BLOCKED(需先在设置里切换默认再删)。
+     *
+     * @param modelId 目标模型的 id
+     * @returns 无返回
+     * @throws IpcMainException COPILOT_MODEL_REMOVE_BLOCKED 当尝试删除内置模型或被设为默认的模型时
+     */
     remove: (modelId: string) => Promise<any>;
+    /**
+     * 返回全部模型,并给每条附加计算属性:isEmbedded(是否内置、前端据此标记「不可移除」)、
+     * purpose(用途,如 "gui" 表示 GUI 专用、不能拿去对话)。
+     *
+     * @returns 模型列表数组,每项包含 isEmbedded/purpose 等计算属性
+     */
     getModels: () => Promise<any>;
+    /**
+     * 把指定本地 llama 模型加载进内存,供后续本地推理。若当前已有其他模型加载,会先卸载再加载。
+     *
+     * @param model 模型文件名,对应 COPILOT_MODEL_PATH/models 下的文件。
+     * @returns 模型文件不存在时静默返回(不 resolve 也不 reject);加载成功后返回 true。
+     * @throws 模型进程异常退出或加载过程中收到 error 事件时抛错。
+     */
     load: (model: string) => Promise<any>;
+    /**
+     * 卸载当前已加载的本地 llama 模型,终止其 utility process 并释放占用的内存。
+     *
+     * @param model 模型名称;当前实现未使用该参数,直接卸载当前已加载的进程(与参数无关)。
+     * @returns 进程终止结果(boolean)。
+     */
     eject: (model: string) => Promise<any>;
+    /**
+     * 列出所有本地 llama 模型的下载任务状态。
+     *
+     * @returns 模型任务数组,每项包含 downloaded(是否已下载到本地)、name(模型名称)、downloadTask(当前下载任务对象,含 downloadId/status/progress/url 等字段;无任务时为 undefined)。
+     */
     getTasks: () => Promise<any>;
+    /**
+     * 开始下载指定本地 llama 模型文件到模型目录。
+     * 进度/开始/完成/取消通过 model.downloadProgress / downloadStarted / downloadCompleted /
+     * downloadCancelled 频道回推给发起方 WebContents;模型不存在则静默返回。
+     *
+     * @param model 模型名,对应 COPILOT_MODEL_PATH/models 下的文件
+     * @returns 无返回
+     */
     download: (model: string) => Promise<any>;
+    /**
+     * 取消指定模型进行中的下载任务,并将任务状态重置为 idle。
+     *
+     * @param model 模型名称,用于在内存任务表中查找对应的下载任务。
+     * @returns 无对应任务时静默返回;取消成功后无返回。
+     */
     cancelDownload: (model: string) => Promise<any>;
+    /**
+     * 暂停指定模型进行中的下载任务,任务状态变更为 downloadPaused。
+     *
+     * @param model 模型名称,用于在内存任务表中查找对应的下载任务。
+     * @returns 无对应任务时静默返回;暂停成功后无返回。
+     */
     pauseDownload: (model: string) => Promise<any>;
+    /**
+     * 恢复指定模型已暂停的下载任务,任务状态变更为 downloading。
+     *
+     * @param model 模型名称,用于在内存任务表中查找对应的下载任务。
+     * @returns 无对应任务时静默返回;恢复成功后无返回。
+     */
     resumeDownload: (model: string) => Promise<any>;
+    /**
+     * 查询内置免费模型的当日额度状态,返回 {model, used, limit, remaining}。
+     * modelName 缺省取默认内置对话模型;非限额模型/查不到时回退为 limit 0 的占位。
+     *
+     * @param modelName 可选,模型名称;缺省使用默认内置对话模型
+     * @returns 额度状态对象 {model, used, limit, remaining}
+     */
     getEmbeddedQuota: () => Promise<any>;
 }

package/types/CopilotProvider.d.ts

@@ -2,8 +2,38 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class CopilotProvider {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 获取所有已注册的模型服务提供商列表。
+     *
+     * @returns 所有 CopilotProvider 实体数组；无任何 provider 时返回空数组。
+     */
     getProviders: () => Promise<any>;
+    /**
+     * 新增一个模型服务提供商。
+     *
+     * @param provider 提供商数据，不含 id（id 由 BeforeInsert 自动生成）。
+     * @returns 保存后的 CopilotProvider 实体，含系统生成的 id。
+     */
     add: (provider: any) => Promise<any>;
+    /**
+     * 更新指定模型服务提供商的配置信息。
+     *
+     * 从数据库查找目标 provider，将传入的 patch 数据与现有记录合并后写回；
+     * id、created_at、updated_at 等只读字段不会被覆盖。
+     * providerId 对应的记录不存在时静默返回，不做任何操作。
+     *
+     * @param providerId 目标提供商的唯一标识。
+     * @param provider   要合并的字段（部分属性即可，未传字段保持原值）。
+     * @returns 无返回。
+     */
     update: (providerId: string, provider: any) => Promise<any>;
+    /**
+     * 删除指定模型服务提供商。
+     *
+     * providerId 对应的记录不存在时静默返回，不做任何操作。
+     *
+     * @param providerId 要删除的提供商的唯一标识。
+     * @returns 无返回。
+     */
     remove: (providerId: string) => Promise<any>;
 }

package/types/CopilotSubAgent.d.ts

@@ -45,21 +45,76 @@ export interface CopilotAsyncTaskFinishedMessage {
 export default class CopilotSubAgent {
     private readonly ipcRenderer;
     constructor();
+    /**
+     * 分页拉取最近的 subagent 运行记录,按创建时间倒序排列,用于运行记录列表。
+     *
+     * @param limit  每页条数,缺省 50。
+     * @param offset 偏移量,缺省 0。
+     * @returns 运行记录列表(CopilotSubAgentRun[]),按 created_at 降序。
+     */
     list: (limit?: number, offset?: number) => Promise<CopilotSubAgentRunDto[]>;
+    /**
+     * 列出某个对话下发起的全部 subagent 运行记录,按创建时间倒序。
+     *
+     * @param threadId 主对话线程 ID,对应 CopilotSubAgentRun.threadId。
+     * @returns 该对话下的运行记录列表(CopilotSubAgentRun[]),按 created_at 降序。
+     */
     listByThread: (threadId: string) => Promise<CopilotSubAgentRunDto[]>;
+    /**
+     * 列出某个定时任务触发的全部 subagent 运行记录,按创建时间倒序。
+     * 通过 metadata 中的 scheduledTaskId 字段(JSON 提取)匹配。
+     *
+     * @param scheduledTaskId 定时任务 ID,对应 run.metadata.scheduledTaskId。
+     * @returns 该定时任务触发的运行记录列表(CopilotSubAgentRun[]),按 created_at 降序。
+     */
     listByScheduledTask: (scheduledTaskId: string) => Promise<CopilotSubAgentRunDto[]>;
+    /**
+     * 按 runId 取单条 subagent 运行记录的完整信息(类型、目标、状态、结果、错误信息、时间戳等)。
+     *
+     * @param runId subagent 运行 ID。
+     * @returns 运行记录(CopilotSubAgentRun);不存在时返回 null。
+     */
     get: (runId: string) => Promise<CopilotSubAgentRunDto | null>;
+    /**
+     * 列出某个 run 产出的所有 artifact 元信息(kind/label/相对路径/mime/大小等),按创建时间升序。
+     * 仅返回元数据,不含文件内容;取内容用 readArtifact。
+     *
+     * @param runId subagent 运行 ID。
+     * @returns artifact 元信息列表(CopilotSubAgentArtifact[]),按 created_at 升序。
+     */
     getArtifacts: (runId: string) => Promise<CopilotSubAgentArtifactDto[]>;
+    /**
+     * 按 artifactId 读取单个产物文件的内容,以 Base64 编码返回。
+     * 先查 artifact 元数据拿到 runId 与 relPath,再通过 run 的 threadId 定位落盘目录读取文件。
+     *
+     * @param artifactId 产物 ID,对应 CopilotSubAgentArtifact.id。
+     * @returns `{ mime, base64 }` 对象(mime 可能为 null);artifactId 不存在时返回 null。
+     * @throws 产物元数据存在但落盘文件缺失或不可读时抛错。
+     */
     readArtifact: (artifactId: string) => Promise<{
         mime: string | null;
         base64: string;
     } | null>;
+    /**
+     * 取该 run 的最新内部 LangGraph state(反序列化后的 channel_values)。
+     * runId 被用作 checkpoint 的 thread_id 进行查询;结构与 subagent 类型强相关,调用方按 type 解析。
+     *
+     * @param runId subagent 运行 ID,同时作为 LangGraph checkpoint 的 thread_id。
+     * @returns 反序列化后的 channel_values 对象;无 checkpoint 时返回 null。
+     */
     getState: (runId: string) => Promise<unknown | null>;
     /**
      * 历史 run 回放:返回完整事件流(从 events.jsonl 读),前端按时间顺序消费一次即可。
      * 跟 subscribe 互补 —— 用于 toolFinished 的旧 task 详情抽屉。
      */
     replay: (runId: string) => Promise<any[]>;
+    /**
+     * 中止指定 run:触发其内部的 AbortController,使正在执行的 handler 抛出 AbortError 并标记为 aborted 状态。
+     * runId 对应的 run 不存在或已结束时静默无操作,不报错。
+     *
+     * @param runId subagent 运行 ID。
+     * @returns 总是返回 `{ ok: true }`(仅表示指令已发出,不代表 run 已成功中止)。
+     */
     abort: (runId: string) => Promise<{
         ok: boolean;
     }>;

package/types/CopilotThread.d.ts

@@ -2,11 +2,51 @@ import { default as IpcRenderer } from './IpcRenderer';
 export default class CopilotThread {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 分页查询对话线程列表,钉住线程永远排在最前,其余按更新时间倒序。
+     *
+     * @param limit  返回条数上限,默认 15。
+     * @param offset 跳过的条数,默认 0,配合 limit 实现分页。
+     * @returns CopilotThread 数组,按 pinned DESC → updated_at DESC 排序。
+     */
     getThreads: (limit?: number, offset?: number) => Promise<any>;
+    /**
+     * 查询指定线程下的全部消息,按发送时间升序排列,同毫秒内按插入顺序。
+     *
+     * @param threadId 目标线程 ID。
+     * @returns CopilotMessage 数组,按 created_at ASC → rowid ASC 排序。
+     */
     getMessages: (threadId: string) => Promise<any>;
+    /**
+     * 创建一条新的对话线程,自动生成唯一 ID 并持久化到 SQLite。
+     *
+     * @param thread 线程属性(Partial<CopilotThread>),可包含 title、projectDir、pinned 等;传 null/undefined 时使用默认值。
+     * @returns 已持久化的 CopilotThread 实体,含自动生成的 id。
+     */
     add: (thread: any) => Promise<any>;
+    /**
+     * 更新指定线程的属性,将传入字段合并到已有实体后写回;更新完成后重新查询并返回最新数据。
+     *
+     * @param id     要更新的线程 ID。
+     * @param thread 要合并的字段(Partial<CopilotThread>),仅传入的字段会被覆盖。
+     * @returns 更新后的 CopilotThread 实体(刷新自数据库)。
+     * @throws THREAD_NOT_FOUND 当线程不存在时抛出 IpcMainException。
+     */
     update: (id: string, thread: any) => Promise<any>;
+    /**
+     * 级联删除指定线程:先删其全部消息、附件元数据与磁盘文件目录,再清空 LangGraph checkpoint/writes,
+     * 最后删除线程自身。文件目录删除失败不阻断流程(best-effort)。
+     *
+     * @param id 要删除的线程 ID。
+     * @returns 无返回值(Promise<void>)。
+     */
     remove: (id: string) => Promise<any>;
+    /**
+     * 清空全部对话数据:删除所有消息、附件元数据、LangGraph checkpoint/writes、全部线程,
+     * 并删除整个 threads 文件目录(best-effort,失败仅 warning 不阻断流程)。
+     *
+     * @returns 无返回值(Promise<void>)。
+     */
     removeAll: () => Promise<any>;
     generateThreadTitle: (id: string) => Promise<any>;
 }

package/types/CopilotWechatBridge.d.ts

@@ -29,15 +29,58 @@ export interface WechatChannelStatus {
 export default class CopilotWechatBridge {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 发起微信扫码登录流程，向微信 API 请求登录二维码并返回给渲染进程展示。
+     *
+     * @param params 可选参数对象。
+     * @param params.force 是否强制重新获取二维码；`false` 或省略时，若存在未过期的有效二维码则直接复用。
+     * @returns 包含二维码图片 URL、本次登录的 `sessionKey` 及提示文本的启动结果。
+     * @throws 微信 API 返回的二维码响应不完整（缺少 qrcode 或 qrcodeUrl 字段）时抛错。
+     */
     startLogin: (params?: {
         force?: boolean;
     }) => Promise<WechatLoginStartResult>;
+    /**
+     * 轮询等待用户手机微信扫码并确认登录。以 1 秒间隔轮询二维码状态，
+     * 直到用户确认、二维码过期或超时。登录确认后自动保存账号凭证到本地数据库，
+     * 若为新连接（非此前已绑定）则自动启动微信消息桥接通道。
+     *
+     * @param params 登录等待参数。
+     * @param params.sessionKey 由 `startLogin` 返回的会话标识，用于关联本次扫码流程。
+     * @param params.timeoutMs 等待超时毫秒数，默认 480_000（8 分钟），实际取值最小为 1_000。
+     * @returns 登录结果：`connected` 表示是否连接成功；`alreadyConnected` 为 `true` 表示该设备此前已绑定，
+     *          无需重新扫码即恢复连接；失败时 `message` 携带原因描述。
+     */
     waitForLogin: (params: {
         sessionKey: string;
         timeoutMs?: number;
     }) => Promise<WechatLoginResult>;
+    /**
+     * 登出微信：先停止消息桥接通道（终止长轮询），再清除本地数据库中的账号凭证。
+     *
+     * @returns 无返回。
+     */
     logout: () => Promise<void>;
+    /**
+     * 查询当前微信桥接的运行状态及已登录的账号信息。
+     *
+     * @returns 包含两个字段的对象：`running` 表示消息监听循环是否正在运行；
+     *          `account` 为当前账号配置详情，包含 `configured`（是否有 token）、
+     *          `enabled`（是否启用）、`accountId`、`userId` 等字段。
+     */
     status: () => Promise<WechatChannelStatus>;
+    /**
+     * 启动微信消息桥接通道，开始长轮询监听微信消息。
+     * 仅在系统设置 `copilot.bridge.wechat.enabled` 为 `true` 且当前账号已配置并启用时才会实际启动；
+     * 任一条件不满足则主动停止已有的监听循环。
+     *
+     * @returns 无返回。
+     */
     channelStart: () => Promise<void>;
+    /**
+     * 停止微信消息桥接通道，终止长轮询监听循环并释放相关资源。
+     *
+     * @returns 无返回。
+     */
     channelStop: () => Promise<void>;
 }

package/types/File.d.ts

@@ -30,18 +30,151 @@ export default class File {
     private transport;
     private seq;
     constructor(transport?: IpcRenderer);
+    /**
+     * 读取分类目录下某个文本文件的全部内容(UTF-8)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 文件的 UTF-8 文本内容。
+     * @throws 文件不存在、路径越界、分类未知或工作空间不可达时抛错。
+     */
     read: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<string>;
+    /**
+     * 把文本内容写入分类目录下的相对路径，父目录不存在则自动创建(UTF-8 覆盖写)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param content      要写入的 UTF-8 文本内容。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 无返回。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     write: (category: WorkspaceCategory, relPath: string, content: string, workspaceId?: string | null) => Promise<void>;
+    /**
+     * 读取分类目录下某个文件的二进制内容。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 文件的二进制内容(Buffer)。
+     * @throws 文件不存在、路径越界、分类未知或工作空间不可达时抛错。
+     */
     readBinary: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<Uint8Array>;
+    /**
+     * 把二进制数据写入分类目录下的相对路径，父目录不存在则自动创建(覆盖写)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param data         要写入的二进制数据(Uint8Array)。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 无返回。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     writeBinary: (category: WorkspaceCategory, relPath: string, data: Uint8Array, workspaceId?: string | null) => Promise<void>;
+    /**
+     * 列出分类目录(或其下子目录)的直接子项；软链会被跳过。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的子目录路径，`/` 分隔；默认 `""` 即分类根目录。越界会被拦截。
+     * @param options      可选配置：`recursive` 为 `true` 时深度展开所有后代；`workspaceId` 指定工作空间。
+     * @returns 子项列表(FileEntry[])，目录不存在时返回空数组。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     list: (category: WorkspaceCategory, relPath?: string, options?: FileListOptions) => Promise<FileEntry[]>;
+    /**
+     * 取某个文件或目录的元信息(是否目录、大小、修改时间、创建时间)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 文件元信息(FileStat)；文件/目录不存在时返回 `null`。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     stat: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<FileStat | null>;
+    /**
+     * 判断分类目录下的文件或目录是否存在。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 存在返回 `true`，否则返回 `false`。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     exists: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<boolean>;
+    /**
+     * 在分类目录下创建目录(递归创建缺失的父级)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 无返回。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     mkdir: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<void>;
+    /**
+     * 删除分类目录下的文件或目录(递归、强制)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；**不能为空**，否则拒绝删除分类根目录。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 无返回。
+     * @throws relPath 为空时抛 `FILE_BAD_PATH`(400)；路径越界、分类未知或工作空间不可达时抛错。
+     */
     remove: (category: WorkspaceCategory, relPath: string, workspaceId?: string | null) => Promise<void>;
+    /**
+     * 在同一分类目录内把文件或目录从 fromRel 移至 toRel(自动创建目标父目录)。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param fromRel      源路径，相对该分类目录，`/` 分隔；越界会被拦截。
+     * @param toRel        目标路径，相对该分类目录，`/` 分隔；越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 无返回。
+     * @throws 源/目标路径越界、分类未知或工作空间不可达时抛错。
+     */
     rename: (category: WorkspaceCategory, fromRel: string, toRel: string, workspaceId?: string | null) => Promise<void>;
+    /**
+     * 把「分类 + 相对路径」解析成宿主机上的绝对路径。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；默认 `""` 即分类根目录。越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 宿主机绝对路径。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     resolve: (category: WorkspaceCategory, relPath?: string, workspaceId?: string | null) => Promise<string>;
+    /**
+     * 把「分类 + 相对路径」解析成 `file://` URL，供 `<img>` / `<video>` 等直接引用。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param relPath      相对该分类目录的路径，`/` 分隔；默认 `""` 即分类根目录。越界会被拦截。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns `file://` 协议 URL 字符串。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     fileUrl: (category: WorkspaceCategory, relPath?: string, workspaceId?: string | null) => Promise<string>;
+    /**
+     * 计算从 fromRel(目录)到 toRel 的相对路径(`/` 分隔)，跨分类可用——用于笔记内引用附件算可移植的相对引用。
+     *
+     * @param fromCategory  源分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param fromRel       源路径(目录)，相对 fromCategory，`/` 分隔；越界会被拦截。
+     * @param toCategory    目标分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param toRel         目标路径，相对 toCategory，`/` 分隔；越界会被拦截。
+     * @param workspaceId   目标工作空间；省略则用当前默认工作空间。
+     * @returns `/` 分隔的相对路径字符串。
+     * @throws 路径越界、分类未知或工作空间不可达时抛错。
+     */
     relativePath: (fromCategory: WorkspaceCategory, fromRel: string, toCategory: WorkspaceCategory, toRel: string, workspaceId?: string | null) => Promise<string>;
+    /**
+     * 订阅分类目录的文件变更通知(流式推送而非直接返回)。
+     * 建立订阅后，目录内任何文件/子目录的增删改都会通过 IPC 频道 `file.watch.<watchId>` 推送给调用方所在渲染进程；
+     * 同一 watchId 重复订阅时先关闭旧 watcher。渲染进程销毁时自动关闭其所有 watcher。
+     *
+     * @param category     分类目录：`document` / `image` / `audio` / `video` / `resource`。
+     * @param watchId      订阅标识，用于后续 `file.unwatch` 取消订阅；也作为推送频道名的一部分。
+     * @param workspaceId  目标工作空间；省略则用当前默认工作空间。
+     * @returns 无返回(Promise  resolve 表示订阅已建立)。
+     * @throws 分类未知或工作空间不可达时抛错。
+     */
     watch: (category: WorkspaceCategory, onChange: (change: FileChange) => void, workspaceId?: string | null) => (() => void);
 }

package/types/Http.d.ts

@@ -21,5 +21,19 @@ export interface HttpResponse {
 export default class Http {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 发起一次 http(s) 请求（绕过渲染层 CORS 限制，在主进程侧代理）。
+     *
+     * 仅放行 http/https 协议；发送前对请求 URL 做 DNS 解析，拦截解析到环回/内网/链路本地地址的请求；
+     * 请求自动跟随重定向（redirect: "follow"），重定向目标同样经过 DNS 内网校验。
+     * 响应体按指定上限截断（默认 5 MiB），超限部分丢弃；超时默认 15 秒。
+     *
+     * @param url 目标 URL，必须是合法的 http 或 https 地址。
+     * @param request 可选请求配置：method（默认 GET）、headers、body、timeoutMs（默认 15000）、maxBytes（默认 5 MiB）。
+     * @returns 包含 ok、status、statusText、headers、finalUrl（最终重定向地址）与 body（UTF-8 文本）的响应对象。
+     * @throws 若 URL 不可解析或格式非法，抛 HTTP_BAD_URL 错误。
+     * @throws 若协议不是 http 或 https，抛 HTTP_BAD_PROTOCOL 错误（状态码 400）。
+     * @throws 若域名解析到环回/内网/链路本地地址（含重定向目标），抛 HTTP_BLOCKED_ADDRESS 错误（状态码 403）。
+     */
     fetch: (url: string, request?: HttpRequest) => Promise<HttpResponse>;
 }

package/types/Kb.d.ts

@@ -9,7 +9,21 @@ export interface KbSearchHit {
 export default class Kb {
     private transport;
     constructor(transport?: IpcRenderer);
+    /**
+     * 在工作空间「文档」目录的笔记(.md)中执行语义检索,返回与查询最相关的 k 条片段。
+     *
+     * @param query 检索关键词或自然语言查询文本。
+     * @param k     返回结果条数,缺省 8。
+     * @returns 按向量距离升序排列的相关片段列表,每条包含 path(文件相对路径)、title(笔记标题)、chunk(正文片段)、distance(向量距离)。
+     */
     search: (query: string, k?: number) => Promise<KbSearchHit[]>;
+    /**
+     * 重建或增量同步笔记向量索引。
+     * force 缺省为 true(整体重建);传 false 则只做按 mtime 的增量同步。
+     *
+     * @param force 是否强制整体重建,缺省 true。false 时仅增量同步变更文件。
+     * @returns 固定返回 `{ ok: true }` 表示索引操作已完成。
+     */
     reindex: (force?: boolean) => Promise<{
         ok: boolean;
     }>;