ms-vite-plugin 1.5.12 → 1.5.14

package/docs/apilua/sqlite.md

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

package/docs/apilua/zipFile.md

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

package/docs/apipython/jbdraw.md

@@ -0,0 +1,147 @@
+# 绘制模块 (JBDraw)
+
+仅越狱包可用。免越狱包没有 `jbdraw`。
+
+在屏幕上画矩形和文字。每画一次返回一个 id，可用 `clear` 去掉这一条，或 `clearAll` 全部去掉。坐标为像素坐标。
+
+颜色只接受 `#RRGGBB` 和 `#RRGGBBAA`。需要字加底时先画填充矩形，再画文字。
+
+## 类型
+
+```python
+from typing import Optional, TypedDict
+
+class JbDrawRectOptions(TypedDict, total=False):
+    color: str
+    lineWidth: float
+    fill: str
+
+class JbDrawTextOptions(TypedDict, total=False):
+    color: str
+    fontSize: float
+```
+
+| 字段        | 类型  | 描述                                                         |
+| ----------- | ----- | ------------------------------------------------------------ |
+| `color`     | str   | `#RRGGBB` 或 `#RRGGBBAA`。矩形默认 `#FF0000`，文字默认 `#FFFFFF` |
+| `lineWidth` | float | 边框宽度。省略为 `2`。`<= 0` 不画边框                         |
+| `fill`      | str   | 填充颜色，同 `color` 格式。省略不填充                         |
+| `fontSize`  | float | 系统字号。省略为 `16`。`<= 0` 时画字失败                      |
+
+## API 参考
+
+### rect - 在屏幕上画矩形。
+
+需要字加底时先画填充矩形，再 `text`。
+
+```python
+def rect(
+    x: float,
+    y: float,
+    width: float,
+    height: float,
+    options: Optional[JbDrawRectOptions] = None,
+) -> int
+```
+
+**参数:**
+
+| 参数名    | 类型              | 是否必填 | 默认值 | 描述                               |
+| --------- | ----------------- | -------- | ------ | ---------------------------------- |
+| `x`       | float             | 是       | -      | 左上角 x，像素坐标                 |
+| `y`       | float             | 是       | -      | 左上角 y，像素坐标                 |
+| `width`   | float             | 是       | -      | 宽度，必须大于 0                   |
+| `height`  | float             | 是       | -      | 高度，必须大于 0                   |
+| `options` | JbDrawRectOptions | 否       | -      | 颜色、边框、填充                   |
+
+**返回值:**
+
+| 类型 | 描述                           |
+| ---- | ------------------------------ |
+| `int` | 成功为 id（从 1 起）；失败为 `0` |
+
+**示例:**
+
+```python
+from kuaijs import jbdraw
+
+box = jbdraw.rect(20, 80, 200, 40, {"fill": "#000000AA", "lineWidth": 0})
+frame = jbdraw.rect(20, 140, 120, 80, {"color": "#FF0000", "lineWidth": 2})
+```
+
+### text - 在屏幕上画文字。
+
+左上角对齐，没有背景。
+
+```python
+def text(
+    x: float,
+    y: float,
+    text: str,
+    options: Optional[JbDrawTextOptions] = None,
+) -> int
+```
+
+**参数:**
+
+| 参数名    | 类型              | 是否必填 | 默认值 | 描述                               |
+| --------- | ----------------- | -------- | ------ | ---------------------------------- |
+| `x`       | float             | 是       | -      | 文字左上角 x，像素坐标             |
+| `y`       | float             | 是       | -      | 文字左上角 y，像素坐标             |
+| `text`    | str               | 是       | -      | 要画的字符串                       |
+| `options` | JbDrawTextOptions | 否       | -      | 颜色和字号                         |
+
+**返回值:**
+
+| 类型 | 描述                           |
+| ---- | ------------------------------ |
+| `int` | 成功为 id（从 1 起）；失败为 `0` |
+
+**示例:**
+
+```python
+from kuaijs import jbdraw
+
+box = jbdraw.rect(20, 80, 200, 40, {"fill": "#000000AA", "lineWidth": 0})
+label = jbdraw.text(28, 88, "hello", {"color": "#FFFFFF", "fontSize": 18})
+```
+
+### clear - 去掉一个图形。
+
+```python
+def clear(id: int) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                     |
+| ------ | ---- | -------- | ------ | ------------------------ |
+| `id`   | int  | 是       | -      | `rect` / `text` 返回的 id |
+
+**返回值:**
+
+| 类型 | 描述                |
+| ---- | ------------------- |
+| `bool` | 找到并移除为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import jbdraw
+
+jbdraw.clear(label)
+```
+
+### clearAll - 去掉当前全部图形。
+
+```python
+def clearAll() -> None
+```
+
+**示例:**
+
+```python
+from kuaijs import jbdraw
+
+jbdraw.clearAll()
+```

package/docs/apipython/jbpower.md

@@ -0,0 +1,133 @@
+# 电源模块 (JBPower)
+
+仅越狱包可用。免越狱包没有 `jbpower`。
+
+`info` 读取电量百分比、电流、电压和充电状态。`stopCharging` 停止充电并保持，直到调用 `startCharging`。`setSmartCharging` 到上限停止充电，降到下限再充，中间保持。
+
+电流单位是毫安，正数表示正在进电。电压单位是毫伏。
+
+## API 参考
+
+### info - 读取当前电源信息。
+
+```python
+def info() -> Optional[PowerInfo]
+```
+
+**返回值:**
+
+| 类型                  | 描述                 |
+| --------------------- | -------------------- |
+| `PowerInfo`           | 读到电池时的电源信息 |
+| `None`                | 读不到电池           |
+
+`PowerInfo` 字段：
+
+| 字段                 | 类型   | 描述                                              |
+| -------------------- | ------ | ------------------------------------------------- |
+| `percentage`         | `int`  | 电量百分比                                        |
+| `amperage`           | `int`  | 电流，单位毫安，正数表示正在进电                  |
+| `voltage`            | `int`  | 电压，单位毫伏                                    |
+| `charging`           | `bool` | 系统是否认为正在充电                              |
+| `plugged`            | `bool` | 电源状态是否为交流电                              |
+| `powerState`         | `str`  | `AC Power` 或 `Battery Power`                     |
+| `rawExternal`        | `bool` | 发布出去的外接位                                  |
+| `showChargingUI`     | `bool` | 主屏是否显示充电                                  |
+| `appleRawExternal`   | `bool` | 硬件是否还认这根线                                |
+| `chargeOverride`     | `bool` | 系统自己的停充覆盖                                |
+| `adapterWatts`       | `int`  | 适配器功率，单位瓦，读不到时为 0                  |
+
+**示例:**
+
+```python
+power = jbpower.info()
+if power:
+    logd(power.percentage, power.amperage)
+```
+
+### stopCharging - 停止充电。
+
+停止后会保持，直到 `startCharging`。
+
+```python
+def stopCharging() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 写入成功为 `True` |
+
+**示例:**
+
+```python
+jbpower.stopCharging()
+```
+
+### startCharging - 恢复充电。
+
+```python
+def startCharging() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 写入成功为 `True` |
+
+**示例:**
+
+```python
+jbpower.startCharging()
+```
+
+### setSmartCharging - 打开智能充电。
+
+电量到 `max` 停止充电，降到 `min` 再充。窗口中间保持上次的决定，不会在停充和充电之间来回切。
+
+上限会收到 2 到 100，下限至少为 1，并且必须小于上限。
+
+```python
+def setSmartCharging(min: int, max: int) -> bool
+```
+
+**参数:**
+
+| 参数  | 类型  | 描述             |
+| ----- | ----- | ---------------- |
+| `min` | `int` | 再充下限，百分比 |
+| `max` | `int` | 停充上限，百分比 |
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 保存成功为 `True` |
+
+**示例:**
+
+```python
+jbpower.setSmartCharging(20, 80)
+```
+
+### clearSmartCharging - 关掉智能充电。
+
+如果当前正按窗口停充，会恢复充电。
+
+```python
+def clearSmartCharging() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 保存成功为 `True` |
+
+**示例:**
+
+```python
+jbpower.clearSmartCharging()
+```

package/docs/apipython/netCard.md

@@ -1,17 +1,16 @@
 # 卡密模块 (NetCard)
 
-卡密模块提供了卡密验证、备注设置以及键值对存储功能，用于管理网络卡密相关的操作。
+卡密模块提供了卡密验证和备注设置功能，用于管理网络卡密相关的操作。
 
 ## 功能概览
 
 - **卡密验证**: 验证卡密的有效性
 - **备注管理**: 设置和管理卡密备注信息
-- **云变量存储**: 提供键值对形式的数据存储和读取功能
 
 ## 注意事项
 
 1. **卡密安全**: 卡密信息应当妥善保管，避免在日志中明文输出
-2. **普通卡密模式**: 需要先调用 `netcard.verify(cardNo)` 验证卡密，验证通过后才能调用获取卡密信息、备注和云变量等接口
+2. **普通卡密模式**: 需要先调用 `netcard.verify(cardNo)` 验证卡密，验证通过后才能调用获取卡密信息和备注等接口
 3. **授权卡密模式**: App 打开加密 UI 或运行脚本前会完成授权和卡密验证，脚本中不需要重复让用户输入卡密，也不需要重复调用 `netcard.verify`
 4. **兼容旧脚本**: 授权卡密模式下调用 `netcard.verify` 会直接返回 `True`，用于兼容原来已经写了 `verify` 的脚本
 
@@ -74,7 +73,7 @@ def verify(cardNo: str) -> bool
 
 **说明：**
 
-普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息、备注和云变量相关能力。
+普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息和备注相关能力。
 
 授权卡密模式下，App 层已经完成授权和卡密验证，脚本侧不需要重复调用该方法；如果旧脚本仍然调用，方法会直接返回 `True`。
 
@@ -186,73 +185,3 @@ if success:
 else:
     logger.error("备注设置失败")
 ```
-
-### 云变量
-
-#### setValue - 设置键值对
-
-```python
-def setValue(key: str, value: str) -> str
-```
-
-**参数说明：**
-
-| 参数名  | 类型 | 是否必填 | 默认值 | 描述       |
-| ------- | ---- | -------- | ------ | ---------- |
-| `key`   | str  | 是       |        | 存储的键名 |
-| `value` | str  | 是       |        | 存储的值   |
-
-**返回值：**
-
-| 类型  | 描述                                          |
-| ----- | --------------------------------------------- |
-| `str` | 成功时返回设置的 value 值，失败时返回空字符串 |
-
-**示例：**
-
-```python
-from kuaijs import netcard, logger
-
-# 设置键值对
-key = "userConfig"
-value = "enableNotification"
-result = netcard.setValue(key, value)
-
-if result == value:
-    logger.info(f"成功设置 {key}: {value}")
-else:
-    logger.error("设置失败")
-```
-
-#### getValue - 获取键值对
-
-```python
-def getValue(key: str) -> str
-```
-
-**参数说明：**
-
-| 参数名 | 类型 | 是否必填 | 默认值 | 描述         |
-| ------ | ---- | -------- | ------ | ------------ |
-| `key`  | str  | 是       |        | 要获取的键名 |
-
-**返回值：**
-
-| 类型  | 描述                                             |
-| ----- | ------------------------------------------------ |
-| `str` | 成功时返回对应的值，失败或键不存在时返回空字符串 |
-
-**示例：**
-
-```python
-from kuaijs import netcard, logger
-
-# 获取键值对
-key = "userConfig"
-value = netcard.getValue(key)
-
-if value:
-    logger.info(f"获取到配置: {key} = {value}")
-else:
-    logger.warn(f"配置 {key} 不存在或获取失败")
-```