ms-vite-plugin 1.5.9 → 1.5.11

package/docs/apilua/jbdylib.md

@@ -0,0 +1,231 @@
+# 动态库模块 (JBDylib)
+
+模块表是内置全局 `jbdylib`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbdylib`。
+
+把动态库放到脚本项目的 `res` 目录，用相对路径 `open`，再用 `define` / `defineAll` 绑定签名，之后按符号名调用。定义请用冒号 `lib:define(...)`，新符号才会挂到当前表上。同一进程重复打开同一路径会复用已加载的库。未 `define` 的符号不能调用。C 符号名不能与 `define` / `defineAll` / `call` / `symbol` 重名。
+
+## 类型
+
+`retType` / `argTypes` 使用下面的类型名：
+
+| 类型 | 说明 |
+| ---- | ---- |
+| `void` | 无返回值；调用成功时返回 `true` |
+| `bool` | 布尔 |
+| `int` | 32 位整数 |
+| `uint` | 32 位无符号整数 |
+| `int64` | 64 位整数 |
+| `uint64` | 64 位无符号整数 |
+| `float` | 32 位浮点 |
+| `double` | 64 位浮点 |
+| `string` | C 字符串 |
+| `pointer` | 指针 |
+
+只支持常见 C 标量类型。整数、指针、字符串参数合计最多 8 个，浮点参数最多 8 个。不支持结构体、C++ 方法和可变参数。指针用 `"0x..."` 字符串。
+
+`defineAll` / `open` 第二参数里，每个函数可以写成：
+
+| 写法 | 含义 |
+| ---- | ---- |
+| `"void"` 或 `{ "void" }` | 返回 `void`，无参数 |
+| `{ "int", { "int", "int" } }` | 返回 `int`，两个 `int` 参数 |
+| `{ "int", "int", "int" }` | 同上，参数类型也可以扁平写在返回类型后面 |
+
+## API 参考
+
+### open - 从 `res` 加载动态库，返回库对象。
+
+```lua
+---@param name string
+---@param defs table|nil
+---@return JbDylibLib|nil
+function open(name, defs) end
+```
+
+**参数:**
+
+| 参数名 | 类型      | 是否必填 | 默认值 | 描述                                                         |
+| ------ | --------- | -------- | ------ | ------------------------------------------------------------ |
+| `name` | string    | 是       | -      | 相对 `res` 的动态库路径，例如 `"mylib.dylib"` 或 `"libs/mylib.dylib"` |
+| `defs` | table\|nil | 否      | `nil`  | 打开后立刻批量绑定的函数表 |
+
+**返回值:**
+
+| 类型               | 描述                               |
+| ------------------ | ---------------------------------- |
+| `JbDylibLib\|nil`  | 加载成功返回库对象，失败返回 `nil` |
+
+**示例:**
+
+```lua
+local lib = jbdylib.open("mylib.dylib", {
+  mylib_add = { "int", { "int", "int" } },
+  mylib_get_name = { "string" },
+  mylib_touch = { "void" },
+})
+if lib then
+  print(lib.mylib_add(1, 2))
+end
+```
+
+### isLoaded - 查询动态库是否已加载。
+
+```lua
+---@param name string
+---@return boolean
+function isLoaded(name) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                     |
+| ------ | ------ | -------- | ------ | ------------------------ |
+| `name` | string | 是       | -      | 相对 `res` 的动态库路径 |
+
+**返回值:**
+
+| 类型      | 描述                         |
+| --------- | ---------------------------- |
+| `boolean` | 已加载为 `true`，否则 `false` |
+
+**示例:**
+
+```lua
+if not jbdylib.isLoaded("mylib.dylib") then
+  jbdylib.open("mylib.dylib")
+end
+```
+
+## 库对象
+
+`open` 返回的库对象。先定义签名，再按符号名调用。
+
+```lua
+---@class JbDylibLib
+---@field define fun(self, symbol: string, retType: string, argTypes?: string[]): boolean
+---@field defineAll fun(self, specs: table): boolean
+---@field call fun(self, symbol: string, ...): any
+---@field symbol fun(self, name: string): string|nil
+```
+
+### define - 绑定一个导出函数的签名。
+
+```lua
+---@param symbol string
+---@param retType string
+---@param argTypes string[]|nil
+---@return boolean
+function define(symbol, retType, argTypes) end
+```
+
+**参数:**
+
+| 参数名     | 类型          | 是否必填 | 默认值 | 描述                           |
+| ---------- | ------------- | -------- | ------ | ------------------------------ |
+| `symbol`   | string        | 是       | -      | 导出符号名，例如 `"mylib_add"` |
+| `retType`  | string        | 是       | -      | 返回类型                       |
+| `argTypes` | string[]\|nil | 否       | `{}`   | 每个参数的类型，无参数时可省略 |
+
+**返回值:**
+
+| 类型      | 描述                                     |
+| --------- | ---------------------------------------- |
+| `boolean` | 签名合法且符号存在为 `true`，否则 `false` |
+
+**示例:**
+
+```lua
+local lib = jbdylib.open("mylib.dylib")
+lib:define("mylib_add", "int", { "int", "int" })
+print(lib.mylib_add(1, 2))
+```
+
+### defineAll - 批量绑定导出函数。
+
+```lua
+---@param specs table
+---@return boolean
+function defineAll(specs) end
+```
+
+**参数:**
+
+| 参数名  | 类型  | 是否必填 | 默认值 | 描述                     |
+| ------- | ----- | -------- | ------ | ------------------------ |
+| `specs` | table | 是       | -      | 键为符号名，值为函数定义 |
+
+**返回值:**
+
+| 类型      | 描述                                           |
+| --------- | ---------------------------------------------- |
+| `boolean` | 全部成功为 `true`；失败项会跳过，其余仍会绑定 |
+
+**示例:**
+
+```lua
+lib:defineAll({
+  mylib_add = { "int", { "int", "int" } },
+  mylib_touch = { "void" },
+})
+```
+
+### call - 按已绑定签名调用导出函数。
+
+```lua
+---@param symbol string
+---@param ... any
+---@return any
+function call(symbol, ...) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                       |
+| -------- | ------ | -------- | ------ | -------------------------- |
+| `symbol` | string | 是       | -      | 已绑定的导出符号名         |
+| `...`    | any    | 否       | -      | 与定义时参数类型对应的实参 |
+
+**返回值:**
+
+| 类型  | 描述                                               |
+| ----- | -------------------------------------------------- |
+| `any` | 调用成功返回结果；`void` 成功返回 `true`；失败返回 `nil` |
+
+**示例:**
+
+```lua
+local sum = lib:call("mylib_add", 1, 2)
+print(sum)
+
+lib:define("mylib_touch", "void")
+lib:call("mylib_touch")
+```
+
+### symbol - 解析导出符号地址。
+
+```lua
+---@param name string
+---@return string|nil
+function symbol(name) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
+| ------ | ------ | -------- | ------ | ---------- |
+| `name` | string | 是       | -      | 导出符号名 |
+
+**返回值:**
+
+| 类型          | 描述                                   |
+| ------------- | -------------------------------------- |
+| `string\|nil` | 成功返回 `"0x..."` 地址，失败返回 `nil` |
+
+**示例:**
+
+```lua
+local addr = lib:symbol("mylib_add")
+print(addr)
+```

package/docs/apilua/jbshell.md

@@ -0,0 +1,63 @@
+# 终端模块 (JBShell)
+
+模块表是内置全局 `jbshell`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbshell`。
+
+用 `exec` 执行一条 shell 命令，同步等到结束或超时，返回 `code`、`stdout`、`stderr`。命令走 `sh -c`。`stdout` / `stderr` 各最多 8MB。
+
+## 类型
+
+```lua
+---@class JbShellResult
+---@field code integer
+---@field stdout string
+---@field stderr string
+```
+
+| 字段     | 类型    | 描述                                         |
+| -------- | ------- | -------------------------------------------- |
+| `code`   | integer | 退出码；超时为 `-1`；被信号结束后为 `128 + 信号` |
+| `stdout` | string  | 标准输出文本                                 |
+| `stderr` | string  | 标准错误文本                                 |
+
+## API 参考
+
+### exec - 执行一条 shell 命令，等到结束或超时。
+
+```lua
+---@param command string
+---@param timeoutMs integer|nil
+---@return JbShellResult|nil
+function exec(command, timeoutMs) end
+```
+
+**参数:**
+
+| 参数名      | 类型          | 是否必填 | 默认值  | 描述                                           |
+| ----------- | ------------- | -------- | ------- | ---------------------------------------------- |
+| `command`   | string        | 是       | -       | 交给 `sh -c` 的命令                       |
+| `timeoutMs` | integer\|nil  | 否       | `30000` | 等待上限毫秒；`<= 0` 时用默认值，最长 `3600000` |
+
+**返回值:**
+
+| 类型                    | 描述                                                         |
+| ----------------------- | ------------------------------------------------------------ |
+| `JbShellResult\|nil`    | 启动成功返回结果；空命令或启动失败返回 `nil`。超时仍返回已捕获输出，`code` 为 `-1` |
+
+**示例:**
+
+```lua
+local r = jbshell.exec("printf hello")
+if r then
+  logi(r.code)
+  logi(r.stdout)
+end
+
+local failed = jbshell.exec("printf boom 1>&2; exit 7")
+logi(failed.code)
+logi(failed.stderr)
+
+local timed = jbshell.exec("sleep 5", 300)
+logi(timed.code)
+```

package/docs/apilua/jbsystem.md

@@ -0,0 +1,225 @@
+# 系统模块 (JBSystem)
+
+模块表是内置全局 `jbsystem`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbsystem`。
+
+`respring` 重启 SpringBoard。`reboot` 重启用户空间，不是重启整机。这两项调用后当前 App 和脚本通常会被系统结束。`restartSelf` 重启当前 App 进程，调用后当前脚本会结束，App 随后会被重新拉起。
+
+还可读写「允许 App 请求跟踪」「个性化广告」和定位服务总开关。不同 iOS 版本中，这些设置项的名称或位置可能略有不同。
+
+## API 参考
+
+### respring - 重启 SpringBoard（Respring）。
+
+```lua
+---@return boolean
+function respring() end
+```
+
+**返回值:**
+
+| 类型      | 描述                     |
+| --------- | ------------------------ |
+| `boolean` | 成功为 `true`  |
+
+**示例:**
+
+```lua
+jbsystem.respring()
+```
+
+### reboot - 重启用户空间。
+
+不是重启整机。
+
+```lua
+---@return boolean
+function reboot() end
+```
+
+**返回值:**
+
+| 类型      | 描述                     |
+| --------- | ------------------------ |
+| `boolean` | 成功为 `true`  |
+
+**示例:**
+
+```lua
+jbsystem.reboot()
+```
+
+### restartSelf - 重启当前 App 进程。
+
+调用后当前脚本会结束，App 随后会被重新拉起。
+
+```lua
+---@return boolean
+function restartSelf() end
+```
+
+**返回值:**
+
+| 类型      | 描述                    |
+| --------- | ----------------------- |
+| `boolean` | 成功为 `true`           |
+
+**示例:**
+
+```lua
+jbsystem.restartSelf()
+```
+
+### getUserTracking - 读取「允许 App 请求跟踪」总开关。
+
+对应 `设置 > 隐私与安全性 > 跟踪 > 允许 App 请求跟踪`。
+
+```lua
+---@return boolean|nil
+function getUserTracking() end
+```
+
+**返回值:**
+
+| 类型             | 描述                           |
+| ---------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否允许；读失败返回 `nil` |
+
+**示例:**
+
+```lua
+local allow = jbsystem.getUserTracking()
+if type(allow) == "boolean" then
+    jbsystem.setUserTracking(false)
+    jbsystem.setUserTracking(allow)
+end
+```
+
+### setUserTracking - 设置「允许 App 请求跟踪」总开关。
+
+```lua
+---@param enabled boolean
+---@return boolean
+function setUserTracking(enabled) end
+```
+
+**参数:**
+
+| 参数名    | 类型      | 是否必填 | 默认值 | 描述                                       |
+| --------- | --------- | -------- | ------ | ------------------------------------------ |
+| `enabled` | `boolean` | 是       | -      | `true` 允许 App 弹跟踪请求，`false` 不允许 |
+
+**返回值:**
+
+| 类型      | 描述                    |
+| --------- | ----------------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbsystem.setUserTracking(false)
+```
+
+### getPersonalizedAdvertising - 读取「个性化广告」开关。
+
+对应 `设置 > 隐私与安全性 > Apple 广告 > 个性化广告`。
+
+```lua
+---@return boolean|nil
+function getPersonalizedAdvertising() end
+```
+
+**返回值:**
+
+| 类型             | 描述                           |
+| ---------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否允许；读失败返回 `nil` |
+
+**示例:**
+
+```lua
+local allow = jbsystem.getPersonalizedAdvertising()
+if type(allow) == "boolean" then
+    jbsystem.setPersonalizedAdvertising(false)
+    jbsystem.setPersonalizedAdvertising(allow)
+end
+```
+
+### setPersonalizedAdvertising - 设置「个性化广告」开关。
+
+```lua
+---@param enabled boolean
+---@return boolean
+function setPersonalizedAdvertising(enabled) end
+```
+
+**参数:**
+
+| 参数名    | 类型      | 是否必填 | 默认值 | 描述                                 |
+| --------- | --------- | -------- | ------ | ------------------------------------ |
+| `enabled` | `boolean` | 是       | -      | `true` 允许个性化广告，`false` 不允许 |
+
+**返回值:**
+
+| 类型      | 描述                    |
+| --------- | ----------------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbsystem.setPersonalizedAdvertising(false)
+```
+
+### getLocationServices - 读取定位服务总开关。
+
+对应 `设置 > 隐私与安全性 > 定位服务` 总开关。
+
+```lua
+---@return boolean|nil
+function getLocationServices() end
+```
+
+**返回值:**
+
+| 类型             | 描述                           |
+| ---------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否开启；读失败返回 `nil` |
+
+**示例:**
+
+```lua
+local enabled = jbsystem.getLocationServices()
+if type(enabled) == "boolean" then
+    jbsystem.setLocationServices(false)
+    jbsystem.setLocationServices(enabled)
+end
+```
+
+### setLocationServices - 设置定位服务总开关。
+
+```lua
+---@param enabled boolean
+---@return boolean
+function setLocationServices(enabled) end
+```
+
+**参数:**
+
+| 参数名    | 类型      | 是否必填 | 默认值 | 描述                             |
+| --------- | --------- | -------- | ------ | -------------------------------- |
+| `enabled` | `boolean` | 是       | -      | `true` 开启定位服务，`false` 关闭 |
+
+**返回值:**
+
+| 类型      | 描述                    |
+| --------- | ----------------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbsystem.setLocationServices(false)
+```