ms-vite-plugin 1.5.12 → 1.5.13

package/docs/api/sqlite.md

@@ -0,0 +1,231 @@
+# SQLite 数据库模块 (SQLite)
+
+SQLite 模块提供本地数据库文件的打开、查询、执行和事务。可以同时打开多个库，每个库用 `open` 返回的句柄操作。
+
+## 功能概览
+
+- **多库句柄**: `open` 返回句柄，后续方法把句柄作为第一个参数
+- **数据查询**: 执行 SELECT 查询
+- **数据更新**: 执行 CREATE、INSERT、UPDATE、DELETE
+- **事务支持**: `beginTransaction` / `commit` / `rollback`
+- **参数绑定**: 使用 `?` 占位，防止 SQL 注入
+
+## 注意事项
+
+1. **文件路径**: 路径必须是绝对路径，与 `file` 模块相同。相对路径会打开失败。
+2. **内存库**: 路径传 `":memory:"` 打开内存数据库。
+3. **句柄**: 先 `open` 再查询；脚本结束会关闭本次运行打开的全部句柄，仍建议用完 `close`。
+4. **BLOB**: 第一版不把 BLOB 转成字符串，读到的该格为 `null`。
+5. **锁定等待**: 数据库被占用时最多等待 5 秒。
+
+## 类型定义
+
+### SqliteResult
+
+查询 / 执行结果。
+
+```typescript
+interface SqliteResult {
+  rows: Record<string, any>[];
+  affectedRows: number;
+  insertId: number | null;
+  success: boolean;
+  error: string | null;
+}
+```
+
+**数据类型说明:**
+
+| 参数名         | 类型                  | 是否必填 | 默认值 | 描述                                       |
+| -------------- | --------------------- | -------- | ------ | ------------------------------------------ |
+| `rows`         | Record<string, any>[] | 否       |        | 查询结果数据行                             |
+| `affectedRows` | number                | 否       |        | 受影响的行数                               |
+| `insertId`     | number \| null        | 否       |        | 本次连接最近一次插入的 rowid；没有插入时为 `null` |
+| `success`      | boolean               | 否       |        | 是否成功                                   |
+| `error`        | string \| null        | 否       |        | 错误信息；成功时为 `null`                  |
+
+## API 参考
+
+### 连接管理
+
+#### open - 打开数据库
+
+```typescript
+function open(path: string): string | undefined;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                      |
+| ------ | ------ | -------- | ------ | ----------------------------------------- |
+| `path` | string | 是       |        | 绝对路径，或 `":memory:"`                 |
+
+**返回值:**
+
+| 类型            | 描述                     |
+| --------------- | ------------------------ |
+| `string \| undefined` | 成功返回句柄，失败返回 `undefined` |
+
+**示例:**
+
+```javascript
+const path = file.getInternalDir("documents") + "/app.db";
+const db = sqlite.open(path);
+if (!db) {
+  loge("打开失败");
+}
+```
+
+#### close - 关闭数据库
+
+```typescript
+function close(handle: string): void;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                |
+| -------- | ------ | -------- | ------ | ------------------- |
+| `handle` | string | 是       |        | `open` 返回的句柄   |
+
+**示例:**
+
+```javascript
+sqlite.close(db);
+```
+
+#### isOpen - 检查句柄是否仍打开
+
+```typescript
+function isOpen(handle: string): boolean;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                |
+| -------- | ------ | -------- | ------ | ------------------- |
+| `handle` | string | 是       |        | `open` 返回的句柄   |
+
+**返回值:**
+
+| 类型      | 描述               |
+| --------- | ------------------ |
+| `boolean` | 仍打开返回 `true`  |
+
+**示例:**
+
+```javascript
+if (sqlite.isOpen(db)) {
+  logi("数据库已打开");
+}
+```
+
+### 数据操作
+
+#### query - 执行查询
+
+```typescript
+function query(handle: string, sql: string, params?: any[]): SqliteResult;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述              |
+| -------- | ------ | -------- | ------ | ----------------- |
+| `handle` | string | 是       |        | `open` 返回的句柄 |
+| `sql`    | string | 是       |        | SQL 语句          |
+| `params` | any[]  | 否       |        | 绑定参数          |
+
+**返回值:**
+
+| 类型           | 描述         |
+| -------------- | ------------ |
+| `SqliteResult` | 查询结果对象 |
+
+**示例:**
+
+```javascript
+const result = sqlite.query(db, "SELECT * FROM t WHERE id = ?", [1]);
+if (result.success) {
+  logi(`查询到 ${result.rows.length} 条记录`);
+} else {
+  loge(`查询失败: ${result.error}`);
+}
+```
+
+#### execute - 执行更新
+
+```typescript
+function execute(handle: string, sql: string, params?: any[]): SqliteResult;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述              |
+| -------- | ------ | -------- | ------ | ----------------- |
+| `handle` | string | 是       |        | `open` 返回的句柄 |
+| `sql`    | string | 是       |        | SQL 语句          |
+| `params` | any[]  | 否       |        | 绑定参数          |
+
+**返回值:**
+
+| 类型           | 描述         |
+| -------------- | ------------ |
+| `SqliteResult` | 执行结果对象 |
+
+**示例:**
+
+```javascript
+sqlite.execute(db, `
+  CREATE TABLE IF NOT EXISTS t (
+    id INTEGER PRIMARY KEY,
+    name TEXT
+  )
+`);
+const insertResult = sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["a"]);
+if (insertResult.success) {
+  logi(`插入 ID: ${insertResult.insertId}`);
+}
+```
+
+### 事务管理
+
+#### beginTransaction / commit / rollback
+
+```typescript
+function beginTransaction(handle: string): boolean;
+function commit(handle: string): boolean;
+function rollback(handle: string): boolean;
+```
+
+**示例:**
+
+```javascript
+if (sqlite.beginTransaction(db)) {
+  sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["a"]);
+  sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["b"]);
+  if (!sqlite.commit(db)) {
+    sqlite.rollback(db);
+  }
+}
+```
+
+## 完整使用示例
+
+```javascript
+const db = sqlite.open(file.getInternalDir("documents") + "/app.db");
+if (!db) {
+  loge("打开失败");
+} else {
+  sqlite.execute(
+    db,
+    "CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, name TEXT)",
+  );
+  sqlite.execute(db, "INSERT INTO t(name) VALUES (?)", ["a"]);
+  const r = sqlite.query(db, "SELECT * FROM t WHERE id = ?", [1]);
+  if (r.success) {
+    logi(JSON.stringify(r.rows));
+  }
+  sqlite.close(db);
+}
+```

package/docs/api/system.md

@@ -118,7 +118,7 @@ function activateAppInfo(): {
   bundleId: string;
   name: string;
   pid: number;
-} | null;
+} | undefined;
 ```
 
 **返回值:**

package/docs/api/thread.md

@@ -25,7 +25,7 @@
 启动一个新的线程来执行指定的 JS 文件。
 
 ```typescript
-function run(threadJsFileName: string, params?: Record<string, any>): Thread;
+function run(threadJsFileName: string, params?: Record<string, any>): Thread | undefined;
 ```
 
 **参数:**
@@ -39,7 +39,7 @@ function run(threadJsFileName: string, params?: Record<string, any>): Thread;
 
 | 类型     | 描述         |
 | -------- | ------------ |
-| `Thread` | 线程控制对象 |
+| `Thread \| undefined` | 线程控制对象；启动参数不是 Object 或启动失败时返回 undefined |
 
 **示例:**
 

package/docs/api/tomatoocr.md

@@ -30,7 +30,7 @@ function initializeWithConfig(
   message: string;
   status: string;
   versionName: string;
-} | null;
+} | undefined;
 ```
 
 **参数:**
@@ -43,7 +43,7 @@ function initializeWithConfig(
 
 **返回值:**
 
-- 成功时返回包含设备信息的对象，失败时返回 null
+- 成功时返回包含设备信息的对象，失败时返回 undefined
 
   | 参数名        | 类型   | 描述     |
   | ------------- | ------ | -------- |

package/docs/api/yolo.md

@@ -70,7 +70,7 @@ function load(
   nc?: number,
   version?: number,
   useGpu?: boolean
-): string | null;
+): string | undefined;
 ```
 
 **参数:**
@@ -87,7 +87,7 @@ function load(
 
 | 类型             | 描述                                      |
 | ---------------- | ----------------------------------------- |
-| `string \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+| `string \| undefined` | 加载成功返回模型 ID 字符串，失败返回 undefined |
 
 **示例:**
 

package/docs/api/yolocls.md

@@ -25,9 +25,9 @@ YOLO 分类概率结果，字段命名与 Ultralytics `Probs` 保持一致。
 ```typescript
 interface YoloClsProbs {
   data: number[]; // 所有类别概率，下标即类别 ID
-  top1: number | null; // 概率最高的类别 ID
+  top1: number | null; // 概率最高的类别 ID；分类失败时为 null
   top5: number[]; // 概率最高的 5 个类别 ID
-  top1conf: number | null; // top1 对应的概率
+  top1conf: number | null; // top1 对应的概率；分类失败时为 null
   top5conf: number[]; // top5 对应的概率
 }
 ```
@@ -37,9 +37,9 @@ interface YoloClsProbs {
 | 字段名     | 类型             | 描述                                                       |
 | ---------- | ---------------- | ---------------------------------------------------------- |
 | `data`     | `number[]`       | 所有类别概率数组，下标即类别 ID                            |
-| `top1`     | `number \| null` | 概率最高的类别 ID；分类失败时为 `null`                     |
+| `top1`     | `number \| null`      | 概率最高的类别 ID；分类失败时为 `null`                          |
 | `top5`     | `number[]`       | 概率最高的 5 个类别 ID，按概率从高到低排序                 |
-| `top1conf` | `number \| null` | `top1` 对应的概率；分类失败时为 `null`                     |
+| `top1conf` | `number \| null`      | `top1` 对应的概率；分类失败时为 `null`                          |
 | `top5conf` | `number[]`       | `top5` 对应的概率，顺序与 `top5` 一致                      |
 
 **结果说明:**
@@ -62,7 +62,7 @@ function load(
   binPath: string,
   nc?: number,
   useGpu?: boolean
-): string | null;
+): string | undefined;
 ```
 
 **参数:**
@@ -78,7 +78,7 @@ function load(
 
 | 类型             | 描述                                      |
 | ---------------- | ----------------------------------------- |
-| `string \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+| `string \| undefined` | 加载成功返回模型 ID 字符串，失败返回 undefined |
 
 **示例:**
 

package/docs/api/zipFile.md

@@ -0,0 +1,113 @@
+# ZIP 模块 (zipFile)
+
+路径必须是绝对路径。只压缩、解压 ZIP；`zip` 只接受目录，不接受文件。
+
+## API 参考
+
+### getFileList - 获取 ZIP 内部文件列表。
+
+```typescript
+function getFileList(path: string): string[];
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述             |
+| ------ | -------- | -------- | ------ | ---------------- |
+| `path` | `string` | 是       | -      | ZIP 文件绝对路径 |
+
+**返回值:**
+
+| 类型       | 描述                                                         |
+| ---------- | ------------------------------------------------------------ |
+| `string[]` | 包内文件路径；不含目录项。不是合法 ZIP 时返回空数组 |
+
+**示例:**
+
+```javascript
+const path = file.getInternalDir("documents") + "/a.zip";
+const names = zipFile.getFileList(path);
+```
+
+### isZip - 检查是否为合法 ZIP。
+
+```typescript
+function isZip(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述         |
+| ------ | -------- | -------- | ------ | ------------ |
+| `path` | `string` | 是       | -      | 文件绝对路径 |
+
+**返回值:**
+
+| 类型      | 描述                      |
+| --------- | ------------------------- |
+| `boolean` | 能作为 ZIP 打开为 `true` |
+
+**示例:**
+
+```javascript
+const path = file.getInternalDir("documents") + "/a.zip";
+if (zipFile.isZip(path)) {
+  logi("是 ZIP");
+}
+```
+
+### unzip - 解压到指定目录。
+
+目标目录不存在会创建。包内路径必须落在目标目录内，否则失败。
+
+```typescript
+function unzip(zipPath: string, destDir: string): boolean;
+```
+
+**参数:**
+
+| 参数名    | 类型     | 是否必填 | 默认值 | 描述                 |
+| --------- | -------- | -------- | ------ | -------------------- |
+| `zipPath` | `string` | 是       | -      | ZIP 文件绝对路径     |
+| `destDir` | `string` | 是       | -      | 解压目标目录绝对路径 |
+
+**返回值:**
+
+| 类型      | 描述              |
+| --------- | ----------------- |
+| `boolean` | 解压成功为 `true` |
+
+**示例:**
+
+```javascript
+const dir = file.getInternalDir("documents");
+zipFile.unzip(dir + "/a.zip", dir + "/out");
+```
+
+### zip - 压缩目录为 ZIP。
+
+包内根条目是该目录名。已有同名 ZIP 文件会先删再写。源路径必须是目录，不能是文件。输出 ZIP 不能落在源目录内。
+
+```typescript
+function zip(dirPath: string, zipPath: string): boolean;
+```
+
+**参数:**
+
+| 参数名    | 类型     | 是否必填 | 默认值 | 描述                                     |
+| --------- | -------- | -------- | ------ | ---------------------------------------- |
+| `dirPath` | `string` | 是       | -      | 要压缩的目录绝对路径                     |
+| `zipPath` | `string` | 是       | -      | 输出 ZIP 绝对路径，不能落在源目录内      |
+
+**返回值:**
+
+| 类型      | 描述              |
+| --------- | ----------------- |
+| `boolean` | 压缩成功为 `true` |
+
+**示例:**
+
+```javascript
+const dir = file.getInternalDir("documents");
+zipFile.zip(dir + "/out", dir + "/out.zip");
+```

package/docs/apicn/ai.md

@@ -12,7 +12,7 @@ AI 模块让脚本直接在手机上调用大模型：看图回答问题、做
 
 模型配置（地址、Key、模型名）直接写在脚本里，脚本开头 `$AI.设置模型` 一次即可；脚本停止后配置自动清空，不会存到手机上。
 
-所有方法同步阻塞，失败时返回 `null` / `false`，原因用 `$AI.获取错误()` 查看。
+所有方法同步阻塞，失败时返回 `undefined` / `false`，原因用 `$AI.获取错误()` 查看。
 
 ## 快速开始
 
@@ -149,7 +149,7 @@ interface 对话消息 {
 ### 设置模型
 
 ```typescript
-function 设置模型(配置: Partial<模型供应商>): 模型供应商 | null;
+function 设置模型(配置: Partial<模型供应商>): 模型供应商 | undefined;
 ```
 
 **参数：**
@@ -162,7 +162,7 @@ function 设置模型(配置: Partial<模型供应商>): 模型供应商 | null;
 
 | 类型         | 描述                                                                            |
 | ------------ | ------------------------------------------------------------------------------- |
-| `模型供应商` | 保存后的完整配置；`protocol` 不是三者之一或缺 `baseUrl` / `model` 时返回 `null` |
+| `模型供应商` | 保存后的完整配置；`protocol` 不是三者之一或缺 `baseUrl` / `model` 时返回 `undefined` |
 
 第一个登记的供应商自动成为默认；`isDefault: true` 会把默认切到它。
 
@@ -240,14 +240,14 @@ $AI.获取模型列表().forEach((p) => $打印信息日志(`${p.name} -> ${p.mo
 ### 获取默认模型
 
 ```typescript
-function 获取默认模型(): 模型供应商 | null;
+function 获取默认模型(): 模型供应商 | undefined;
 ```
 
 **返回值：**
 
 | 类型         | 描述                                  |
 | ------------ | ------------------------------------- |
-| `模型供应商` | 默认供应商；一个都没登记时返回 `null` |
+| `模型供应商` | 默认供应商；一个都没登记时返回 `undefined` |
 
 ### 设置默认模型
 
@@ -290,7 +290,7 @@ function 删除模型(id: 字符串): 布尔值;
 ### 提问
 
 ```typescript
-function 提问(问题: 字符串, 选项?: 调用选项): 字符串 | null;
+function 提问(问题: 字符串, 选项?: 调用选项): 字符串 | undefined;
 ```
 
 **参数：**
@@ -304,7 +304,7 @@ function 提问(问题: 字符串, 选项?: 调用选项): 字符串 | null;
 
 | 类型     | 描述                                                |
 | -------- | --------------------------------------------------- |
-| `字符串` | 模型回复文本；失败返回 `null`，原因看 `获取错误()` |
+| `字符串` | 模型回复文本；失败返回 `undefined`，原因看 `获取错误()` |
 
 **示例：**
 
@@ -364,7 +364,7 @@ while (!$AI.判断("顶部是否显示「首页」？", { image: "screen", x: 0,
 ### 提取
 
 ```typescript
-function 提取(要求: 字符串, 选项?: 调用选项): 任意类型 | null;
+function 提取(要求: 字符串, 选项?: 调用选项): 任意类型 | undefined;
 ```
 
 要求模型输出 JSON 并自动解析成对象或数组。`schema` 用来告诉模型你想要的结构。
@@ -380,7 +380,7 @@ function 提取(要求: 字符串, 选项?: 调用选项): 任意类型 | null;
 
 | 类型        | 描述                                                      |
 | ----------- | --------------------------------------------------------- |
-| `对象/数组` | 解析后的数据；模型没有输出合法 JSON 或请求失败返回 `null` |
+| `对象/数组` | 解析后的数据；模型没有输出合法 JSON 或请求失败返回 `undefined` |
 
 **示例：**
 
@@ -407,14 +407,14 @@ if (位置) $动作.点击(位置.x, 位置.y);
 ### 对话
 
 ```typescript
-function 对话(消息列表: 数组<对话消息 | 字符串>, 选项?: 调用选项): 字符串 | null;
+function 对话(消息列表: 数组<对话消息 | 字符串>, 选项?: 调用选项): 字符串 | undefined;
 ```
 
 自己维护完整对话历史时用它；`提问` 是它的单轮封装。模块不记会话，每次都要把到目前为止的消息整表传进来。
 
 图片写在**那一条 user 消息**上，不要用 `选项.image`。`选项.system` 也不生效，系统提示写成第一条 `{ role: "system", content: "..." }`。
 
-失败返回 `null`：不要把空回复推进历史，否则下一轮变成 `user → assistant(null) → user`，Anthropic 会 400。Anthropic 协议下模块会自动合并连续同角色、并在首条是 assistant 时垫一条占位 user；OpenAI 兼容口更宽松，不必为此改脚本。
+失败返回 `undefined`：不要把空回复推进历史，否则下一轮变成 `user → assistant(null) → user`，Anthropic 会 400。Anthropic 协议下模块会自动合并连续同角色、并在首条是 assistant 时垫一条占位 user；OpenAI 兼容口更宽松，不必为此改脚本。
 
 **参数：**
 
@@ -427,7 +427,7 @@ function 对话(消息列表: 数组<对话消息 | 字符串>, 选项?: 调用
 
 | 类型     | 描述                      |
 | -------- | ------------------------- |
-| `字符串` | 回复文本；失败返回 `null` |
+| `字符串` | 回复文本；失败返回 `undefined` |
 
 **示例：**
 
@@ -453,7 +453,7 @@ function 问(content, extra) {
 ### 解析JSON
 
 ```typescript
-function 解析JSON(文本: 字符串): 任意类型 | null;
+function 解析JSON(文本: 字符串): 任意类型 | undefined;
 ```
 
 自动剥掉 Markdown 代码块和前后的解释文字。`提取` 内部就是用它解析。
@@ -468,19 +468,19 @@ function 解析JSON(文本: 字符串): 任意类型 | null;
 
 | 类型        | 描述                      |
 | ----------- | ------------------------- |
-| `对象/数组` | 解析结果；失败返回 `null` |
+| `对象/数组` | 解析结果；失败返回 `undefined` |
 
 ### 获取错误
 
 ```typescript
-function 获取错误(): 字符串 | null;
+function 获取错误(): 字符串 | undefined;
 ```
 
 **返回值：**
 
 | 类型     | 描述                                  |
 | -------- | ------------------------------------- |
-| `字符串` | 错误文案；上一次调用成功时返回 `null` |
+| `字符串` | 错误文案；上一次调用成功时返回 `undefined` |
 
 常见错误：未登记供应商、Key 错误 / 余额不足（接口返回的原文）、模型不支持图片、图片无效或裁剪越界、超时、模型没有输出 JSON。
 

package/docs/apicn/config.md

@@ -93,7 +93,7 @@ if (是否更新成功1 && 是否更新成功2 && 是否更新成功3) {
 ### 获取
 
 ```typescript
-function 获取(配置键: 字符串): 任意类型 | null;
+function 获取(配置键: 字符串): 任意类型 | undefined;
 ```
 
 **参数:**
@@ -106,7 +106,7 @@ function 获取(配置键: 字符串): 任意类型 | null;
 
 | 类型               | 描述   |
 | ------------------ | ------ |
-| `任意类型 \| null` | 配置值 |
+| `任意类型 \| undefined` | 配置值 |
 
 **示例:**
 

package/docs/apicn/dotocr.md

@@ -64,7 +64,7 @@ interface OCR字符 {
 加载字库是使用点阵识别功能的前提。建议在脚本初始化时加载一次并保存字库 ID，后续识别时复用，不要每次识别都重新加载。
 
 ```typescript
-function 加载字库(字库资源路径: 字符串): 字符串 | null;
+function 加载字库(字库资源路径: 字符串): 字符串 | undefined;
 ```
 
 **参数:**
@@ -77,7 +77,7 @@ function 加载字库(字库资源路径: 字符串): 字符串 | null;
 
 | 类型           | 描述                                      |
 | -------------- | ----------------------------------------- |
-| `字符串 \| null` | 加载成功返回字库 ID 字符串，失败返回 null |
+| `字符串 \| undefined` | 加载成功返回字库 ID 字符串，失败返回 undefined |
 
 **示例:**