ms-vite-plugin 1.5.8 → 1.5.10

package/docs/apilua/jbvpn.md

@@ -0,0 +1,233 @@
+# VPN 模块 (JBVPN)
+
+模块表是内置全局 `jbvpn`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbvpn`。
+
+管理系统 VPN 配置：创建、列出、读取当前选中、选中、删除、连接、断开，以及读取当前选中配置的状态。类型支持 `L2TP`、`IPSec`、`IKEv2`。
+
+`create` 必填显示名、类型和服务器。`select` / `remove` / `connect` 可传显示名，或 `list` 返回的 `id`。多条配置同名时不保证操作哪一条，精确操作请用 `id`。
+
+`connect` / `disconnect` 返回 `true` 只表示已经开始，不表示已经连上或已经断开。用 `status` 看 `connected`。没有选中配置时，`connect()`、`disconnect()`、`status()` 失败。
+
+## API 参考
+
+### create - 创建一条系统 VPN 配置。
+
+```lua
+---@param config table
+---@return boolean
+function create(config) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                  |
+| -------- | ------ | -------- | ------ | ------------------------------------- |
+| `config` | `table` | 是       | -      | 配置表。必填 `name`、`type`、`server` |
+
+`config` 字段：
+
+| 字段名            | 类型      | 是否必填 | 默认值 | 描述                            |
+| ----------------- | --------- | -------- | ------ | ------------------------------- |
+| `name`            | `string`  | 是       | -      | 显示名                          |
+| `type`            | `string`  | 是       | -      | `L2TP` / `IPSec` / `IKEv2`      |
+| `server`          | `string`  | 是       | -      | 服务器地址                      |
+| `account`         | `string`  | 否       | `""`   | 账号                            |
+| `password`        | `string`  | 否       | `""`   | 密码                            |
+| `secret`          | `string`  | 否       | `""`   | 共享密钥。L2TP / IPSec 常用     |
+| `group`           | `string`  | 否       | `""`   | 群组名称                        |
+| `sendAllTraffic`  | `boolean` | 否       | `true` | 是否发送所有流量                |
+| `encryptionLevel` | `integer` | 否       | `1`    | 加密级别                        |
+| `localId`         | `string`  | 否       | `""`   | 本端标识。IKEv2 可用            |
+| `remoteId`        | `string`  | 否       | `""`   | 对端标识。IKEv2 可用            |
+
+**返回值:**
+
+| 类型      | 描述            |
+| --------- | --------------- |
+| `boolean` | 成功为 `true`   |
+
+**示例:**
+
+```lua
+local ok = jbvpn.create({
+    name = "Demo",
+    type = "L2TP",
+    server = "vpn.example.com",
+    account = "user",
+    password = "pass",
+    secret = "psk",
+})
+```
+
+### list - 列出当前系统 VPN 配置。
+
+```lua
+---@return table|nil
+function list() end
+```
+
+**返回值:**
+
+| 类型           | 描述                        |
+| -------------- | --------------------------- |
+| `table \| nil` | 配置列表；读失败返回 `nil`  |
+
+没有配置时是空表。每项含 `name`、`id`。
+
+**示例:**
+
+```lua
+local items = jbvpn.list()
+if items then
+    for _, item in ipairs(items) do
+        print(item.name, item.id)
+    end
+end
+```
+
+### current - 读取当前选中的 VPN 配置。
+
+没有选中配置返回 `nil`。
+
+```lua
+---@return table|nil
+function current() end
+```
+
+**返回值:**
+
+| 类型           | 描述                                      |
+| -------------- | ----------------------------------------- |
+| `table \| nil` | 含 `name`、`id`；没有选中配置返回 `nil`   |
+
+**示例:**
+
+```lua
+local item = jbvpn.current()
+if item then
+    print(item.name, item.id)
+end
+```
+
+### select - 选中一条 VPN 配置。
+
+```lua
+---@param nameOrId string
+---@return boolean
+function select(nameOrId) end
+```
+
+**参数:**
+
+| 参数名      | 类型     | 是否必填 | 默认值 | 描述                    |
+| ----------- | -------- | -------- | ------ | ----------------------- |
+| `nameOrId`  | `string` | 是       | -      | 显示名或 `list` 的 `id` |
+
+**返回值:**
+
+| 类型      | 描述                  |
+| --------- | --------------------- |
+| `boolean` | 找到并选中为 `true`   |
+
+**示例:**
+
+```lua
+jbvpn.select("Demo")
+```
+
+### remove - 删除一条 VPN 配置。
+
+```lua
+---@param nameOrId string
+---@return boolean
+function remove(nameOrId) end
+```
+
+**参数:**
+
+| 参数名      | 类型     | 是否必填 | 默认值 | 描述                    |
+| ----------- | -------- | -------- | ------ | ----------------------- |
+| `nameOrId`  | `string` | 是       | -      | 显示名或 `list` 的 `id` |
+
+**返回值:**
+
+| 类型      | 描述                  |
+| --------- | --------------------- |
+| `boolean` | 找到并删除为 `true`   |
+
+**示例:**
+
+```lua
+jbvpn.remove("Demo")
+```
+
+### connect - 连接 VPN。
+
+传入显示名或 `id` 时先选中再连接；省略则连接当前选中的配置。
+
+```lua
+---@param nameOrId? string
+---@return boolean
+function connect(nameOrId) end
+```
+
+**参数:**
+
+| 参数名      | 类型     | 是否必填 | 默认值 | 描述                          |
+| ----------- | -------- | -------- | ------ | ----------------------------- |
+| `nameOrId`  | `string` | 否       | -      | 显示名或 `id`；省略用当前选中 |
+
+**返回值:**
+
+| 类型      | 描述                                    |
+| --------- | --------------------------------------- |
+| `boolean` | 开始连接为 `true`，不是已经连上         |
+
+**示例:**
+
+```lua
+jbvpn.connect("Demo")
+```
+
+### disconnect - 断开当前 VPN 连接。
+
+```lua
+---@return boolean
+function disconnect() end
+```
+
+**返回值:**
+
+| 类型      | 描述                                    |
+| --------- | --------------------------------------- |
+| `boolean` | 开始断开为 `true`，不是已经断开         |
+
+**示例:**
+
+```lua
+jbvpn.disconnect()
+```
+
+### status - 读取当前选中 VPN 的状态。
+
+```lua
+---@return table|nil
+function status() end
+```
+
+**返回值:**
+
+| 类型           | 描述                                          |
+| -------------- | --------------------------------------------- |
+| `table \| nil` | 含 `text`、`connected`；没有选中配置返回 `nil` |
+
+**示例:**
+
+```lua
+local st = jbvpn.status()
+if st and st.connected then
+    print(st.text)
+end
+```

package/docs/apilua/pip.md

@@ -2,14 +2,15 @@
 
 模块表是内置全局 `pip`，直接调用即可。不要 `require` 宿主模块。
 
-悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
+悬浮窗模块提供 iOS 悬浮窗能力。免越狱包使用系统画中画（Picture in Picture），可用于显示脚本日志、保活提示或脚本自定义文本。越狱包使用同一套 `pip` API 控制全局悬浮球：保活只显示图标，日志显示图标和日志窗口，自定义显示图标和自定义文本窗口。
 
 ## 功能特性
 
-- **显示模式**：支持日志、保活和自定义三种显示模式；首次安装默认保活
+- **显示模式**：支持日志、保活和自定义三种显示模式；首次安装默认关闭
 - **关闭控制**：支持主动关闭悬浮窗
 - **状态查询**：判断悬浮窗是否正在显示
-- **尺寸设置**：日志模式和自定义模式支持设置内容宽高比（实际显示尺寸由系统决定），并按模式分别持久化
+- **尺寸设置**：日志模式和自定义模式支持设置尺寸并分别持久化。系统画中画为宽高比（实际显示尺寸由系统决定）；越狱包为窗口宽高（像素）
+- **位置设置**：越狱包可用 `setPosition` 设置日志窗口和自定义文本窗口位置；保活模式不接受；系统画中画位置由 iOS 管理
 - **日志显示**：日志模式支持设置日志文字大小
 - **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
 
@@ -46,7 +47,7 @@ end
 function switchToLogMode() end
 ```
 
-切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示系统画中画时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。越狱包显示悬浮球图标和日志窗口。
 
 **返回值：**
 
@@ -69,7 +70,7 @@ pip.setLogFontSize(10)
 function switchToKeepAliveMode() end
 ```
 
-切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示系统画中画时 App 必须在前台。保活模式不接受脚本尺寸设置。越狱包只显示悬浮球图标。
 
 **返回值：**
 
@@ -91,7 +92,7 @@ local success = pip.switchToKeepAliveMode()
 function switchToCustomMode() end
 ```
 
-切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
+切换到自定义模式并显示脚本设置的自定义文本。首次显示系统画中画时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。越狱包显示悬浮球图标和自定义文本窗口。
 
 **返回值：**
 
@@ -139,14 +140,14 @@ local success = pip.closeWindow()
 function setContentSize(width, height) end
 ```
 
-设置日志模式或自定义模式的悬浮窗内容尺寸。传入的宽高表示宽高比，不是最终像素尺寸；悬浮窗实际显示的宽高由系统决定。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+设置日志模式或自定义模式的悬浮窗内容尺寸。系统画中画传入的宽高表示宽高比，不是最终像素尺寸，实际显示宽高由系统决定。越狱包传入的宽高是对应窗口的像素尺寸。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；关闭状态和保活模式不会生效。
 
 **参数：**
 
 | 参数     | 类型             | 必填 | 描述                                           |
 | -------- | ---------------- | ---- | ---------------------------------------------- |
-| `width`  | `number` | 是   | 宽度方向比例值（与 `height` 共同决定宽高比，不是像素） |
-| `height` | `number` | 是   | 高度方向比例值（与 `width` 共同决定宽高比，不是像素） |
+| `width`  | `number` | 是   | 宽度。系统画中画为比例值；越狱包为窗口宽度（像素） |
+| `height` | `number` | 是   | 高度。系统画中画为比例值；越狱包为窗口高度（像素） |
 
 **返回值：**
 
@@ -164,6 +165,37 @@ pip.switchToCustomMode()
 pip.setContentSize(120, 180)
 ```
 
+### setPosition - 设置位置
+
+```lua
+---@param x number
+---@param y number
+---@return boolean
+function setPosition(x, y) end
+```
+
+设置悬浮窗位置。仅越狱包生效；系统画中画由 iOS 管理位置，调用返回 `false`。只对日志窗口和自定义文本窗口生效；保活模式不接受设置位置。
+
+**参数：**
+
+| 参数 | 类型     | 必填 | 描述               |
+| ---- | -------- | ---- | ------------------ |
+| `x`  | `number` | 是   | 窗口左上角逻辑 X   |
+| `y`  | `number` | 是   | 窗口左上角逻辑 Y   |
+
+**返回值：**
+
+| 类型      | 描述                                                |
+| --------- | --------------------------------------------------- |
+| `boolean` | `true` 代表位置已提交；`false` 代表当前不能设置位置 |
+
+**示例：**
+
+```lua
+pip.switchToLogMode()
+pip.setPosition(24, 120)
+```
+
 ### setLogFontSize - 设置日志文字大小
 
 ```lua
@@ -328,9 +360,9 @@ pip.setContentSize(120, 180)
 
 ## 注意事项
 
-1. **前台限制**：首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
-2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+1. **前台限制**：系统画中画首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
+2. **设备兼容性**：系统画中画仅支持 iOS 15+ 且具备画中画功能的设备；越狱包全局悬浮球不依赖系统画中画
+3. **位置**：系统画中画位置由 iOS 管理；越狱包日志/自定义窗口可用 `setPosition`，保活模式不接受
 4. **尺寸持久化**：日志模式和自定义模式分别保存尺寸，互不共用；保活模式不接受脚本尺寸
 5. **日志字号**：日志字号只影响日志模式，保活模式和自定义模式不受影响
 6. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
@@ -339,11 +371,17 @@ pip.setContentSize(120, 180)
 
 ### 悬浮窗无法显示
 
-- 确认设备支持悬浮窗功能
-- 检查悬浮窗权限是否已开启
-- 确认应用当前在前台
+- 确认当前已切换到日志、保活或自定义模式，且不是关闭状态
+- 系统画中画：确认设备支持悬浮窗功能，并检查悬浮窗权限是否已开启
+- 系统画中画：确认应用当前在前台
 
 ### setContentSize 返回 false
 
 - 确认当前模式是日志模式或自定义模式
 - 确认宽度和高度都传入了有效数字
+
+### setPosition 返回 false
+
+- 确认当前是越狱包，且已切换到日志或自定义模式，对应窗口已打开
+- 保活模式不支持设置位置
+- 确认 x、y 都传入了有效数字

package/docs/apilua/plist.md

@@ -0,0 +1,153 @@
+# 属性列表模块 (Plist)
+
+模块表是内置全局 `plist`，直接调用即可。不要 `require` 宿主模块。路径必须是绝对路径。
+
+## API 参考
+
+### read - 读取整个 plist。
+
+```lua
+---@param path string
+---@return any|nil
+function read(path) end
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述         |
+| ------ | -------- | -------- | ------ | ------------ |
+| `path` | `string` | 是       | -      | 文件绝对路径 |
+
+**返回值:**
+
+| 类型           | 描述     |
+| -------------- | -------- |
+| `any` \| `nil` | 根对象   |
+
+**示例:**
+
+```lua
+local path = file.getInternalDir("documents") .. "/info.plist"
+local info = plist.read(path)
+```
+
+### write - 写成 plist。
+
+```lua
+---@param path string
+---@param value any
+---@param format string|nil
+---@return boolean
+function write(path, value, format) end
+```
+
+**参数:**
+
+| 参数名   | 类型              | 是否必填 | 默认值  | 描述                   |
+| -------- | ----------------- | -------- | ------- | ---------------------- |
+| `path`   | `string`          | 是       | -       | 文件绝对路径           |
+| `value`  | `any`             | 是       | -       | 表、字符串、数字或布尔 |
+| `format` | `string` \| `nil` | 否       | `"xml"` | `xml` 或 `binary`      |
+
+**返回值:**
+
+| 类型      | 描述              |
+| --------- | ----------------- |
+| `boolean` | 写入成功为 `true` |
+
+**示例:**
+
+```lua
+local path = file.getInternalDir("documents") .. "/info.plist"
+plist.write(path, { name = "kuaijs", count = 1 })
+plist.write(path, { name = "kuaijs" }, "binary")
+```
+
+### get - 按键读取。
+
+```lua
+---@param path string
+---@param key string|string[]
+---@return any|nil
+function get(path, key) end
+```
+
+**参数:**
+
+| 参数名 | 类型                   | 是否必填 | 默认值 | 描述               |
+| ------ | ---------------------- | -------- | ------ | ------------------ |
+| `path` | `string`               | 是       | -      | 文件绝对路径       |
+| `key`  | `string` \| `string[]` | 是       | -      | 键，或嵌套键数组表 |
+
+**返回值:**
+
+| 类型           | 描述     |
+| -------------- | -------- |
+| `any` \| `nil` | 该键的值 |
+
+**示例:**
+
+```lua
+plist.get(path, "name")
+plist.get(path, { "a", "b" })
+```
+
+### set - 按键写入。
+
+```lua
+---@param path string
+---@param key string|string[]
+---@param value any
+---@return boolean
+function set(path, key, value) end
+```
+
+**参数:**
+
+| 参数名  | 类型                   | 是否必填 | 默认值 | 描述               |
+| ------- | ---------------------- | -------- | ------ | ------------------ |
+| `path`  | `string`               | 是       | -      | 文件绝对路径       |
+| `key`   | `string` \| `string[]` | 是       | -      | 键，或嵌套键数组表 |
+| `value` | `any`                  | 是       | -      | 要写入的值         |
+
+**返回值:**
+
+| 类型      | 描述              |
+| --------- | ----------------- |
+| `boolean` | 写入成功为 `true` |
+
+**示例:**
+
+```lua
+plist.set(path, "name", "kuaijs")
+plist.set(path, { "a", "b" }, 1)
+```
+
+### remove - 按键删除。
+
+```lua
+---@param path string
+---@param key string|string[]
+---@return boolean
+function remove(path, key) end
+```
+
+**参数:**
+
+| 参数名 | 类型                   | 是否必填 | 默认值 | 描述               |
+| ------ | ---------------------- | -------- | ------ | ------------------ |
+| `path` | `string`               | 是       | -      | 文件绝对路径       |
+| `key`  | `string` \| `string[]` | 是       | -      | 键，或嵌套键数组表 |
+
+**返回值:**
+
+| 类型      | 描述              |
+| --------- | ----------------- |
+| `boolean` | 删除成功为 `true` |
+
+**示例:**
+
+```lua
+plist.remove(path, "name")
+plist.remove(path, { "a", "b" })
+```

package/docs/apilua/ui.md

@@ -104,6 +104,27 @@ function eval(code) end
 ui.eval("document.title = 'KuaiJS'")
 ```
 
+### evalFloatingWindow - 在越狱悬浮窗网页中执行 JavaScript
+
+```lua
+---@param code string
+function evalFloatingWindow(code) end
+```
+
+在悬浮窗网页中执行 JavaScript。主界面 WebView 不受影响。没有悬浮窗网页时无效果。
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                 |
+| ------ | ------ | -------- | ------ | -------------------- |
+| `code` | string | 是       | -      | JavaScript 代码字符串 |
+
+**示例：**
+
+```lua
+ui.evalFloatingWindow("console.log('float')")
+```
+
 ### onEvent - 设置事件回调函数
 
 ```lua
@@ -154,6 +175,29 @@ ui.call("loadData", {
 })
 ```
 
+### callFloatingWindow - 调用越狱悬浮窗网页中的 JavaScript 函数
+
+```lua
+---@param key string
+---@param data table
+function callFloatingWindow(key, data) end
+```
+
+调用悬浮窗网页里 `registerUIFunc` 注册的函数。主界面 WebView 不受影响。没有悬浮窗网页时无效果。
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                     |
+| ------ | ------ | -------- | ------ | ------------------------ |
+| `key`  | string | 是       |        | 悬浮窗页面 JavaScript 方法名 |
+| `data` | table  | 是       |        | 传递给方法的参数         |
+
+**示例：**
+
+```lua
+ui.callFloatingWindow("updateStatus", { status = "running", progress = 50 })
+```
+
 ### showToast - 显示 Toast 提示消息
 
 ```lua
@@ -693,6 +737,30 @@ ms.getDeviceID()
   });
 ```
 
+#### getOrientation - 获取屏幕方向
+
+```typescript
+declare function getOrientation(): Promise<"PORTRAIT" | "LANDSCAPE">;
+```
+
+**返回值：**
+
+| 类型                                        | 描述                                                         |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| `Promise<"PORTRAIT" \| "LANDSCAPE">` | `"PORTRAIT"` 竖屏，`"LANDSCAPE"` 横屏 |
+
+**说明：**
+
+获取当前屏幕方向。
+
+**网页端示例：**
+
+```javascript
+ms.getOrientation().then((orientation) => {
+  console.log(orientation);
+});
+```
+
 #### getAuthCardNo - 获取缓存的授权卡密
 
 ```typescript
@@ -757,6 +825,55 @@ ms.openURL("https://www.baidu.com")
   });
 ```
 
+#### setWebWindowSize - 设置网页窗口宽高
+
+```typescript
+declare function setWebWindowSize(size: {
+  portraitWidth: number;
+  portraitHeight: number;
+  landscapeWidth: number;
+  landscapeHeight: number;
+}): Promise<boolean>;
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                     |
+| ------ | ------ | -------- | ------ | ------------------------ |
+| `size` | object | 是       |        | 横竖屏网页窗口像素尺寸   |
+
+**`size` 字段：**
+
+| 字段名            | 类型   | 是否必填 | 默认值 | 描述                   |
+| ----------------- | ------ | -------- | ------ | ---------------------- |
+| `portraitWidth`   | number | 是       |        | 竖屏窗口宽度（像素）   |
+| `portraitHeight`  | number | 是       |        | 竖屏窗口高度（像素）   |
+| `landscapeWidth`  | number | 是       |        | 横屏窗口宽度（像素）   |
+| `landscapeHeight` | number | 是       |        | 横屏窗口高度（像素）   |
+
+**返回值：**
+
+| 类型               | 描述                                  |
+| ------------------ | ------------------------------------- |
+| `Promise<boolean>` | 如果设置成功返回 true，否则返回 false |
+
+**说明：**
+
+仅越狱包可用。一次同时设置竖屏和横屏的网页窗口像素尺寸。未调用过时，横竖屏都默认使用对应朝向屏幕宽高的 60%。免越狱包调用返回 `false`。
+
+**网页端示例：**
+
+```javascript
+ms.setWebWindowSize({
+  portraitWidth: 700,
+  portraitHeight: 1200,
+  landscapeWidth: 1200,
+  landscapeHeight: 700,
+}).then((ok) => {
+  console.log(ok);
+});
+```
+
 ### 完整示例
 
 **完整的控制面板示例：**

package/docs/apipython/device.md

@@ -69,21 +69,19 @@ print(f"剩余存储: {s.free}{s.unit}")
 
 ## 设备标识信息
 
-### getDeviceID - 获取设备唯一标识（Vendor ID）。
+### getDeviceID - 获取设备 ID。
+
+越狱包返回芯片生成的固定 ID，卸载重装不变；免越狱包返回 IDFV，卸载重装会改变。
 
 ```python
 def getDeviceID() -> str
 ```
 
-**注意事项:**
-
-- 卸载重装 APP 后会改变；更新 APP 后不会改变
-
 **返回值:**
 
-| 类型  | 描述        |
-| ----- | ----------- |
-| `str` | 设备唯一 ID |
+| 类型  | 描述    |
+| ----- | ------- |
+| `str` | 设备 ID |
 
 **示例:**
 

package/docs/apipython/g.md

@@ -12,7 +12,7 @@
 ## 常量
 
 - `runMode: str` 运行模式，"agent" 或 "hid"
-- `platform: str` 平台信息（"ios" 或 "android"）
+- `platform: str` 免越狱包为 `"ios"`，越狱包为 `"ios_jb"`
 - `appVersion: str` 应用版本号
 - `appBuildNumber: int` 应用构建号
 - `appName: str` 应用名称