# Sflang 内置函数参考（738 个）

本文件由 `cargo run -p sflang --example dump_builtins` 从二进制内嵌的函数文档自动生成，
与运行时的 `help("函数名")` 输出同源。

运行时自省：`help()` 全部分类一览，`help("分类")` 浏览分类，`help("函数名")` 查详情；
`sf --list-builtins [分类]` 从命令行列出。

## array（13 个）

### `appendArray`

- 签名：`appendArray(arr, items) -> array`
- 简介：批量追加到数组末尾（原地修改）：items 为数组则展开追加，否则作单个元素追加。
- 参数：
  - `arr`：目标数组（原地修改）
  - `items`：数组：展开追加每个元素；其他值：作为单个元素追加
- 返回：array：修改后的同一数组
- 示例：
  - `appendArray([1,2], [3,4])   → [1, 2, 3, 4]（展开）`
  - `appendArray([1,2], 9)       → [1, 2, 9]（单值）`
- 常见错误：
  - 与 push 的区别：push 仅追加单个元素，appendArray 会展开数组批量追加

### `concat`

- 签名：`concat(arr1, arr2, ...) -> array`
- 简介：拼接多个数组为一个新数组（原数组不变）。
- 参数：
  - `arr1, arr2, ...`：至少一个数组；所有参数都必须是数组
- 返回：array：拼接后的新数组
- 示例：
  - `concat([1,2], [3,4])        → [1, 2, 3, 4]`
  - `concat([1], [2], [3])       → [1, 2, 3]`
  - `concat([1,2])               → [1, 2]`
- 常见错误：
  - 每个参数都必须是数组（不会自动展开非数组值）

### `contains`

- 签名：`contains(arr, x) -> bool | contains(str, sub) -> bool`
- 简介：数组判断是否含某元素（按值相等）；字符串判断是否含子串。
- 参数：
  - `arr`：数组（元素匹配）或字符串（子串匹配）
  - `x`：数组：要查找的元素；字符串：要查找的子串
- 返回：bool：存在返回 true
- 示例：
  - `contains([1, 2, 3], 2)   → true`
  - `contains([1, 2, 3], 9)   → false`
  - `contains("hello", "ell") → true`
- 常见错误：
  - 第一个参数必须是 array 或 string

### `indexOf`

- 签名：`indexOf(arr, x) -> int`
- 简介：查找元素首次出现的索引；未找到返回 -1。
- 参数：
  - `arr`：待搜索的数组
  - `x`：要查找的元素
- 返回：int：首次出现的索引（从 0 起）；未找到返回 -1
- 示例：
  - `indexOf(["a", "b", "a"], "a") → 0`
  - `indexOf([1, 2, 3], 9)             → -1`
- 常见错误：
  - 第一个参数必须是数组

### `insert`

- 签名：`insert(arr, idx, val) -> array`
- 简介：在指定索引处插入元素（原地修改），返回数组本身。
- 参数：
  - `arr`：待插入的数组
  - `idx`：插入位置；负数按距末端计算（-1 表示追加到末尾）
  - `val`：要插入的值
- 返回：array：插入后的同一数组（原地修改）
- 示例：
  - `insert([1,2,3], 1, 9)   → [1, 9, 2, 3]`
  - `insert([1,2,3], -1, 9)  → [1, 2, 3, 9]（-1 追加）`
- 常见错误：
  - 越界索引会自动截断为有效位置（追加到末尾），不报错

### `remove`

- 签名：`remove(arr, idx) -> value`
- 简介：移除指定索引处的元素并返回它（原地修改）。
- 参数：
  - `arr`：待移除元素的数组
  - `idx`：要移除的索引；负数表示距末端
- 返回：被移除的元素值
- 示例：
  - `a := [1, 2, 3]; remove(a, 1)  → 2（a 变为 [1, 3]）`
  - `a := [1, 2, 3]; remove(a, -1) → 3（a 变为 [1, 2]）`
- 常见错误：
  - 索引越界（含负索引超出范围）返回 error

### `removeItems`

- 签名：`removeItems(arr, start, count) -> array`
- 简介：从 start 索引开始移除 count 个元素（原地修改），返回数组本身。
- 参数：
  - `arr`：目标数组（原地修改）
  - `start`：起始索引；负数按距末端计算
  - `count`：要移除的元素个数；超过可移除范围自动截断
- 返回：array：修改后的同一数组
- 示例：
  - `removeItems([1,2,3,4,5], 1, 2)  → [1, 4, 5]`
  - `removeItems([1,2,3,4,5], -2, 2) → [1, 2, 3]`
- 常见错误：
  - count 不能为负数（参数顺序为 arr, start, count）
  - start 越界时静默不移除（不报错）

### `reverse`

- 签名：`reverse(arr) -> array | reverse(str) -> string`
- 简介：数组原地反转（返回本身）；字符串返回反转后的副本。
- 参数：
  - `arr`：数组（原地反转）或字符串（返回新串）
- 返回：array 数组本身；或 string 反转后的新字符串
- 示例：
  - `reverse([1, 2, 3])    → [3, 2, 1]`
  - `reverse("abc")        → "cba"`
- 常见错误：
  - 参数必须是 array 或 string

### `shuffle`

- 签名：`shuffle(arr) -> array`
- 简介：原地用 Fisher-Yates 算法随机打乱数组，返回数组本身。
- 参数：
  - `arr`：待打乱的数组（原地修改）
- 返回：array：打乱后的同一数组
- 示例：
  - `shuffle([1, 2, 3, 4, 5])  → 顺序随机（元素不变）`
- 常见错误：
  - 第一个参数必须是数组

### `slice`

- 签名：`slice(arr, start, end?) -> array`
- 简介：返回子切片副本 [start, end)；end 省略取到末尾，负索引按距末端解释。
- 参数：
  - `arr`：数组或 byteArray（类型一致返回）
  - `start`：起始索引（含），负数表示距末端
  - `end`：结束索引（不含），省略取到末尾，负数表示距末端
- 返回：array 或 byteArray：切片副本（类型与输入一致）；空范围为空集合
- 示例：
  - `slice([1,2,3,4], 1, 3)  → [2, 3]`
  - `slice([1,2,3,4], 2)     → [3, 4]`
  - `slice([1,2,3,4], -2)    → [3, 4]`
- 常见错误：
  - 索引越界会自动截断到有效范围，不报错

### `sort`

- 签名：`sort(arr, descending?) -> array`
- 简介：原地按自然序排序（数字按数值、字符串按字典序；混合时数字在前），返回数组本身。
- 参数：
  - `arr`：待排序的数组
  - `descending`：可选 bool：true 表示降序（默认升序）
- 返回：array：排序后的同一数组（原地修改）
- 示例：
  - `sort([3, 1, 2])           → [1, 2, 3]`
  - `sort([3, 1, 2], true)     → [3, 2, 1]（降序）`
  - `sort(["b", "a"])       → ["a", "b"]`
- 常见错误：
  - 第一个参数必须是数组

### `sortByFunc`

- 签名：`sortByFunc(arr, cmpFn) -> array`
- 简介：用自定义比较函数原地排序，返回数组本身。
- 参数：
  - `arr`：待排序的数组
  - `cmpFn`：比较函数 (a, b) -> int：负数 a 在前、0 相等、正数 a 在后
- 返回：array：排序后的同一数组（原地修改）
- 示例：
  - `sortByFunc([3,1,2], func(a,b){ return a - b })  → [1,2,3]（升序）`
  - `sortByFunc([3,1,2], func(a,b){ return b - a })  → [3,2,1]（降序）`
- 常见错误：
  - 比较函数返回值必须可转为 int（负/零/正）
  - 比较函数在排序期间被逐对调用，避免在其中修改原数组

### `strContains`

- 签名：`strContains(str, sub) -> bool`
- 简介：判断字符串是否包含子串（contains 的 str 前缀别名，命名一致性）。
- 参数：
  - `str`：被搜索的字符串
  - `sub`：要查找的子串
- 返回：bool：包含返回 true
- 示例：
  - `strContains("hello", "ell") → true`
  - `strContains("hello", "xyz") → false`
- 常见错误：
  - 等价于 contains(str, sub)

## bigint（7 个）

### `bigFloat`

- 签名：`bigFloat(s[, scale]) -> bigFloat`
- 简介：创建任意精度十进制浮点数。指定 scale 时字符串视为纯整数尾数，scale 需在 0..=10000。
- 参数：
  - `s`：数字字符串或数值
  - `scale`：可选。小数位数（0..=10000）
- 返回：bigFloat
- 示例：
  - `bigFloat("0.1")`
  - `bigFloat("123", 2)  // 1.23`
- 常见错误：
  - scale 超出 0..=10000 返回 error

### `bigFloatDiv`

- 签名：`bigFloatDiv(a, b[, scale]) -> bigFloat`
- 简介：bigFloat 精确除法（可选小数位数）。
- 参数：
  - `a`：被除数
  - `b`：除数
  - `scale`：可选。小数位数（0..=10000）
- 返回：bigFloat
- 示例：
  - `bigFloatDiv(a, b, 10)`
- 常见错误：
  - 除零返回 error
  - scale 超出 0..=10000 返回 error

### `bigInt`

- 签名：`bigInt(s) -> bigInt`
- 简介：从字符串创建任意精度整数。
- 参数：
  - `s`：数字字符串或 int
- 返回：bigInt
- 示例：
  - `bigInt("99999999999999999999")`
  - `bigInt(42)`

### `isBigFloat`

- 签名：`isBigFloat(v) -> bool`
- 简介：判断是否为 bigFloat 类型。
- 参数：
  - `v`：任意值
- 返回：bool
- 示例：
  - `isBigFloat(bigFloat("1.0"))`

### `isBigInt`

- 签名：`isBigInt(v) -> bool`
- 简介：判断是否为 bigInt 类型。
- 参数：
  - `v`：任意值
- 返回：bool
- 示例：
  - `isBigInt(bigInt("1"))`

### `toBigFloat`

- 签名：`toBigFloat(v) -> bigFloat`
- 简介：将数值转为 bigFloat。
- 参数：
  - `v`：int/float/string
- 返回：bigFloat
- 示例：
  - `toBigFloat(3.14)`

### `toBigInt`

- 签名：`toBigInt(v) -> bigInt`
- 简介：将 int/string 转为 bigInt。
- 参数：
  - `v`：int 或 string
- 返回：bigInt
- 示例：
  - `toBigInt(42)`

## bytes（15 个）

### `arrayFromByteArray`

- 签名：`arrayFromByteArray(b) -> array<int>`
- 简介：将 byteArray/bytes 转为 array<int>（每字节一个 int 0-255）。
- 参数：
  - `b`：byteArray 或 bytes
- 返回：array<int>：每字节一个 int（0-255）
- 示例：
  - `arrayFromByteArray(bytes("AB"))  → [65, 66]`
- 常见错误：
  - 参数应为 byteArray 或 bytes

### `byteArray`

- 签名：`byteArray(n, fill?) -> byteArray`
- 简介：创建 n 字节的可变 byteArray，默认全填 0 或指定填充值。
- 参数：
  - `n`：字节数（int，非负）
  - `fill`：可选 int 0-255：填充值，默认 0
- 返回：byteArray：长度为 n 的可变字节序列
- 示例：
  - `byteArray(4)         → [0x00, 0x00, 0x00, 0x00]`
  - `byteArray(3, 255)    → [0xFF, 0xFF, 0xFF]`
- 常见错误：
  - n 不能为负；fill 须在 0-255 范围内

### `byteArrayFromArray`

- 签名：`byteArrayFromArray(arr) -> byteArray`
- 简介：从 array<int> 创建可变 byteArray（每个元素作为一字节）。
- 参数：
  - `arr`：array<int>：每个元素须为 0-255 的 int
- 返回：byteArray：元素值组成的可变字节序列
- 示例：
  - `byteArrayFromArray([65, 66, 67])  → [0x41, 0x42, 0x43]`
- 常见错误：
  - 数组元素须为 0-255 的 int，越界报错并附元素索引

### `byteArrayFromBytes`

- 签名：`byteArrayFromBytes(v) -> byteArray`
- 简介：从 bytes 创建可变 byteArray（拷贝）；也接受 byteArray/string。
- 参数：
  - `v`：bytes / byteArray / string（UTF-8 字节）
- 返回：byteArray：内容相同的可变副本
- 示例：
  - `byteArrayFromBytes(bytes("AB"))   → [0x41, 0x42]`
  - `byteArrayFromBytes("AB")          → [0x41, 0x42]`
- 常见错误：
  - 参数应为 bytes/byteArray/string

### `bytes`

- 签名：`bytes(v) -> bytes`
- 简介：转为不可变 bytes：string→UTF-8 字节、byteArray→只读快照、array<int>→字节。
- 参数：
  - `v`：string（UTF-8 字节）/ byteArray（拷贝快照）/ array<int>（每个元素 0-255）
- 返回：bytes：不可变字节序列
- 示例：
  - `bytes("AB")           → [0x41, 0x42]`
  - `bytes([65, 66])       → [0x41, 0x42]`
- 常见错误：
  - array<int> 模式下每个元素须为 0-255 的 int
  - 参数应为 string/byteArray/array<int>，其他类型报错

### `bytesFromHex`

- 签名：`bytesFromHex(hex) -> bytes`
- 简介：将十六进制字符串转为 bytes（自动忽略空格/冒号/横线等分隔符）。
- 参数：
  - `hex`：十六进制字符串；有效字符需成对（偶数个）
- 返回：bytes：解码后的字节序列
- 示例：
  - `bytesFromHex("4142")       → bytes([0x41, 0x42])`
  - `bytesFromHex("41:42")      → bytes([0x41, 0x42])（忽略冒号）`
- 常见错误：
  - 有效十六进制字符数必须为偶数

### `bytesHex`

- 签名：`bytesHex(b) -> string`
- 简介：将 bytes/byteArray 转为小写十六进制字符串。
- 参数：
  - `b`：bytes 或 byteArray
- 返回：string：每字节两位小写十六进制
- 示例：
  - `bytesHex(bytes("AB"))  → "4142"`
  - `bytesHex(bytes([255]))  → "ff"`
- 常见错误：
  - 参数应为 bytes 或 byteArray

### `bytesJoin`

- 签名：`bytesJoin(parts, sep?) -> bytes`
- 简介：把 bytes/byteArray/string 组成的数组拼接为一个 bytes，可选分隔字节序列。
- 参数：
  - `parts`：数组，元素可为 bytes / byteArray / string（string 按 UTF-8 编码）
  - `sep`：可选分隔符，bytes / byteArray / string
- 返回：bytes：拼接结果
- 示例：
  - `bytesJoin([bytes([0x00, 0x10]), bytes([0xAB])])  → [0x00,0x10,0xAB]`
  - `bytesJoin(["A", "B"], "-")  → [0x41,0x2D,0x42]`
  - `bytesJoin([hdr, body])  // 拼接协议帧：长度头 + 数据体`
- 常见错误：
  - bytesJoin() 第一参数应为数组 (可能原因：直接传了 bytes，应包成数组 [bytes])
  - bytesJoin() 数组元素 #N 应为 bytes/byteArray/string，得到 X (可能原因：混入了 int 等其他类型，可用 bytes([...]) 先转换)

### `bytesToData`

- 签名：`bytesToData(data[, "-endian=B|L"]) -> int|bigInt`
- 简介：将字节序列按指定字节序解读为无符号整数（1-16 字节）。
- 参数：
  - `data`：bytes/byteArray，长度 1-16 字节
  - `-endian=B|L`：可选。B=大端（默认，网络序），L=小端
- 返回：int（能放入 i64 时）或 bigInt（更大时）；空输入报错
- 示例：
  - `bytesToData(bytesFromHex("00000000000007FF"), "-endian=B")   // 2047`
  - `bytesToData(bytesFromHex("FF01"), "-endian=L")               // 511`
- 常见错误：
  - 空字节序列或超过 16 字节报错
  - 参数应为 bytes/byteArray，其他类型报错
  - -endian= 只接受 B/L 开头的值

### `copy`

- 签名：`copy(dst, src, dstStart?) -> int`
- 简介：批量复制字节到 byteArray（类似 Go copy），返回实际复制字节数。
- 参数：
  - `dst`：目标 byteArray（可变，原地修改）
  - `src`：源 bytes/byteArray/string
  - `dstStart`：可选 int：dst 写入起始位置，默认 0
- 返回：int：实际复制字节数 = min(len(src), len(dst) - dstStart)
- 示例：
  - `dst := byteArray(4); copy(dst, bytes("AB"))   → 2（dst=[0x41,0x42,0,0]）`
  - `dst := byteArray(4); copy(dst, bytes("AB"), 2) → 2（dst=[0,0,0x41,0x42]）`
- 常见错误：
  - dst 必须是 byteArray（参数顺序：dst 在前、src 在后）
  - dstStart 不能为负，且不能超过 dst 长度

### `dataToBytes`

- 签名：`dataToBytes(v[, "-endian=B|L"[, "-size=N"]]) -> bytes`
- 简介：将非负整数转为定长字节序列（默认 8 字节，对标 uint64）。
- 参数：
  - `v`：非负 int 或 bigInt
  - `-endian=B|L`：可选。B=大端（默认，网络序），L=小端
  - `-size=N`：可选。输出字节数 1-16，默认 8
- 返回：bytes：定长字节序列（高位补 0）
- 示例：
  - `dataToBytes(2047, "-endian=B")                    // 8 字节大端 00000000000007FF`
  - `dataToBytes(2047, "-endian=B", "-size=2")        // 2 字节大端 07FF`
- 常见错误：
  - 负数报错；值超出 N 字节可表示范围报错
  - size 不在 1-16 范围报错
  - 参数应为 int/bigInt，其他类型报错

### `hexDecode`

- 签名：`hexDecode(hex) -> bytes`
- 简介：十六进制字符串解码为 bytes（hexDecode 是 bytesFromHex 的语义化别名）。
- 参数：
  - `hex`：十六进制字符串；有效字符需成对（偶数个）
- 返回：bytes：解码后的字节序列
- 示例：
  - `hexDecode("4142")  → bytes([0x41, 0x42])`
- 常见错误：
  - 有效十六进制字符数必须为偶数

### `hexEncode`

- 签名：`hexEncode(v) -> string`
- 简介：将 string/bytes/byteArray 编码为小写十六进制字符串。
- 参数：
  - `v`：string（UTF-8 字节）/ bytes / byteArray
- 返回：string：每字节两位小写十六进制
- 示例：
  - `hexEncode("AB")   → "4142"`
  - `hexEncode([0xFF])  → "ff"`
- 常见错误：
  - 参数应为 string/bytes/byteArray

### `hexToStr`

- 签名：`hexToStr(hex) -> string`
- 简介：将十六进制字符串解码为 UTF-8 字符串（先解码字节再按 UTF-8 解释）。
- 参数：
  - `hex`：十六进制字符串，前后空白会被忽略
- 返回：string：解码后的字符串（非法 UTF-8 字节替换为 U+FFFD）
- 示例：
  - `hexToStr("4142")      → "AB"`
  - `hexToStr("e4bda0e5a5bd") → "你好"`
- 常见错误：
  - hex 字符串长度必须为偶数；非法 hex 字符报错

### `strFromBytes`

- 签名：`strFromBytes(b, encoding?) -> string`
- 简介：将字节序列按指定编码解码为字符串（默认 utf8）。
- 参数：
  - `b`：bytes 或 byteArray
  - `encoding`：可选 "utf8"(默认) / "latin1" / "hex"
- 返回：string：解码后的字符串
- 示例：
  - `strFromBytes(bytes("你好"))          → "你好"`
  - `strFromBytes(bytes([0x41,0x42]), "latin1") → "AB"`
  - `strFromBytes(bytes([0x41]), "hex")   → "41"`
- 常见错误：
  - utf8 非法字节会被替换为 U+FFFD（不报错）
  - encoding 仅支持 utf8/latin1/hex

## clipboard（2 个）

### `getClipText`

- 签名：`getClipText() -> string`
- 简介：读取系统剪贴板文本。
- 返回：string 剪贴板内容
- 示例：
  - `var t = getClipText()`
- 常见错误：
  - Linux 下需要 xclip/xsel

### `setClipText`

- 签名：`setClipText(s) -> undefined`
- 简介：设置系统剪贴板文本。
- 参数：
  - `s`：要设置的文本
- 返回：undefined
- 示例：
  - `setClipText("hello")`

## concurrency（29 个）

### `chanRecv`

- 签名：`chanRecv(ch) -> value`
- 简介：从通道接收值（无数据时挂起等待：任务内挂起不占 OS 线程，主线程内阻塞）。
- 参数：
  - `ch`：channel 对象
- 返回：接收到的值；通道关闭后返回 undefined
- 示例：
  - `var v = chanRecv(ch)`

### `chanSend`

- 签名：`chanSend(ch, val) -> undefined`
- 简介：向通道发送值。有等待的接收者时直接交接唤醒（值不经队列）；否则入队等待接收。永不阻塞（通道无界）。
- 参数：
  - `ch`：channel 对象
  - `val`：要发送的值
- 返回：undefined
- 示例：
  - `chanSend(ch, 42)`
- 常见错误：
  - ch 参数应为 channel 类型

### `chanTryRecv`

- 签名：`chanTryRecv(ch) -> value|undefined`
- 简介：非阻塞接收：暂无数据或通道已关闭（发送端全部丢弃）均返回 undefined，两者不区分；需要区分时请由发送方在协议上约定结束标记。
- 参数：
  - `ch`：channel 对象
- 返回：值或 undefined（暂无数据或已关闭时）
- 示例：
  - `var v = chanTryRecv(ch); if v != undefined { pln(v) }`

### `deleteProcessVar`

- 签名：`deleteProcessVar(key) -> undefined`
- 简介：删除进程级共享变量。
- 参数：
  - `key`：变量名（string）
- 返回：undefined（删除不存在的变量不报错）
- 示例：
  - `deleteProcessVar("cache:123")`
- 常见错误：
  - deleteProcessVar() 需要至少 1 个参数
  - deleteProcessVar() 第 1 个参数应为 string

### `getProcessVar`

- 签名：`getProcessVar(key[, defaultValue]) -> value`
- 简介：读取进程级共享变量；未设置时返回 defaultValue（未提供则返回 undefined）。
- 参数：
  - `key`：变量名（string）
  - `defaultValue`：可选，变量不存在时的返回值
- 返回：value 变量值（对象/数组为共享引用，跨 VM 修改互相可见）
- 示例：
  - `getProcessVar("visitCount")            // 未设置返回 undefined`
  - `getProcessVar("lang", "zh-CN")        // 未设置返回 "zh-CN"`
  - `var c = getProcessVar("n", 0) + 1       // 常见计数器模式`
  - `setProcessVar("n", c)`
- 常见错误：
  - getProcessVar() 需要至少 1 个参数
  - getProcessVar() 第 1 个参数应为 string

### `lock`

- 签名：`lock(m) -> undefined`
- 简介：加锁（锁被占时等待：任务内挂起，主线程内阻塞）。解锁时所有权直接交接给被唤醒的等待者。
- 参数：
  - `m`：mutex 对象
- 返回：undefined
- 示例：
  - `lock(m)`

### `newChannel`

- 签名：`newChannel() -> channel`
- 简介：创建无缓冲通道（mpsc），用于任务/线程间通信。配合 run 和 chanSend/chanRecv 使用。接收方可挂起等待，不占 OS 线程。
- 返回：channel 通道对象
- 示例：
  - `var ch = newChannel()`
  - `run sender()       // 子任务 chanSend(ch, 42)`
  - `var v = chanRecv(ch) // 主线程接收`

### `newMutex`

- 签名：`newMutex() -> mutex`
- 简介：创建互斥锁，用于保护共享数据的并发访问。锁等待在任务内挂起（不占 OS 线程）。
- 返回：mutex 锁对象
- 示例：
  - `var m = newMutex()`
  - `lock(m); count++; unlock(m)`

### `newOnce`

- 签名：`newOnce() -> once`
- 简介：创建 Once 对象，保证初始化代码只执行一次。
- 返回：once 对象
- 示例：
  - `var o = newOnce()`
  - `onceDo(o, func() { pln("只执行一次") })`

### `newRWMutex`

- 签名：`newRWMutex() -> rwmutex`
- 简介：创建读写锁：允许多个读锁或一个写锁。有写者排队时新读者排队（防写者饥饿）。
- 返回：rwmutex 读写锁对象
- 示例：
  - `var rw = newRWMutex()`

### `newSemaphore`

- 签名：`newSemaphore(n) -> semaphore`
- 简介：创建信号量，限制同时访问的并发数。
- 参数：
  - `n`：最大并发数（正整数，缺省为 1）
- 返回：semaphore 对象
- 示例：
  - `var sem = newSemaphore(5)  // 最多 5 个并发`
- 常见错误：
  - 参数非整数（如字符串、undefined）时返回错误
  - 参数 <= 0 时返回错误（合法范围 >= 1）

### `newWaitGroup`

- 签名：`newWaitGroup() -> waitGroup`
- 简介：创建 WaitGroup，用于等待一组并发任务完成。
- 返回：waitGroup 对象
- 示例：
  - `var wg = newWaitGroup()`
  - `wgAdd(wg, 3); for i := 0; i < 3; i++ { run worker(wg) }`
  - `wgWait(wg)  // 等待 3 个任务完成`

### `onceDo`

- 签名：`onceDo(o, fn) -> value`
- 简介：保证 fn 只在第一次调用时执行（并发安全）。返回首次执行的结果；fn 出错时该错误会返回给所有调用方（不吞掉）。并发调用方挂起等待首次执行完成并直接取得其结果。
- 参数：
  - `o`：once 对象
  - `fn`：要执行的函数
- 返回：首次执行的返回值（后续调用返回同一结果）
- 示例：
  - `onceDo(o, initFunc)`
- 常见错误：
  - fn 执行出错时返回该错误
  - 回调内递归调用同一 once 时返回错误（而不是永久阻塞）
  - 回调内不允许再挂起当前任务（回调经 call_function_value 执行，挂起被禁用并返回明确错误）

### `poolRun`

- 签名：`poolRun(fn, workers, items) -> array`
- 简介：有界并发执行：启动 workers 个工作线程，并发处理 items 中的每一项（对每项调用 fn(item)）。阻塞直到全部完成，返回与 items 等长的结果数组（顺序与 items 一一对应）。fn 抛异常时对应位置返回 error 值，不影响其余项。workers 大于 items 数量时按 items 数量启动（不启多余线程）。
- 参数：
  - `fn`：处理函数，接收一个 item，返回结果
  - `workers`：工作线程数（整数，1..=1024）
  - `items`：待处理项数组
- 返回：array 结果数组，results[i] 为 fn(items[i]) 的返回值（异常时为 error 值）
- 示例：
  - `var urls = ["http://a", "http://b", "http://c"]`
  - `var bodies = poolRun(func(u) { return getWeb(u) }, 8, urls)`
  - `for i in range(len(bodies)) { pln(urls[i], "->", len(bodies[i])) }`
- 常见错误：
  - fn 不是函数值时返回错误
  - workers 非整数或超出 1..=1024 范围时返回错误
  - items 不是数组时返回错误
  - items 为空数组时直接返回空数组（不启动线程）
  - fn 对某项抛异常时该项结果为 error 值（用 isErr 判断），整体不中断

### `rlock`

- 签名：`rlock(rw) -> undefined`
- 简介：获取读锁（共享，多读者并发；有写者持有或排队时等待）。
- 参数：
  - `rw`：rwmutex 对象
- 返回：undefined
- 示例：
  - `rlock(rw); ... runlock(rw)`

### `runAsync`

- 签名：`runAsync(fn, args...) -> int`
- 简介：在后台线程执行函数，返回任务 ID。结果通过 runAsyncResults() 或 GUI 事件循环回调获取。
- 参数：
  - `fn`：要执行的函数值
  - `args...`：传递给函数的参数
- 返回：int 任务 ID（用于标识结果）
- 示例：
  - `runAsync(func(host, path) { return sshListDetail(host, path) }, "--host=1.2.3.4", "--remotePath=/")`
- 常见错误：
  - fn 不是函数值会抛异常
  - isError 判定规则：fn 抛异常 → isError=true；fn 返回 error 值（如 sshRun 失败时 Ok(error_value)）→ isError=true；其他 → isError=false
  - 工作线程独立 VM，共享 globals；任务结果通过全局队列异步取回

### `runAsyncResults`

- 签名：`runAsyncResults() -> array<map{id, result, isError}>`
- 简介：检查已完成的后台任务结果。每次调用返回并清除已完成的结果。
- 返回：array<map{id:int, result:value, isError:bool}> 空数组表示无已完成任务
- 示例：
  - `var results = runAsyncResults()`
- 常见错误：
  - isError=true 时 result 是 error 值（用 getErrStr 取消息）；isError=false 时 result 是函数返回值
  - GUI 事件循环每 20ms 自动调用 drain，前端 window.onAsyncResult(id, json, isError) 接收

### `runlock`

- 签名：`runlock(rw) -> undefined`
- 简介：释放读锁。读者归零时按队列顺序放行等待者（连续读者一并放行，写者需无读者）。
- 参数：
  - `rw`：rwmutex 对象
- 返回：undefined
- 示例：
  - `runlock(rw)`

### `semAcquire`

- 签名：`semAcquire(sem) -> undefined`
- 简介：获取信号量（无空位时挂起等待；唤醒后重查空位，仍无则继续等）。
- 参数：
  - `sem`：semaphore 对象
- 返回：undefined
- 示例：
  - `semAcquire(sem)`

### `semRelease`

- 签名：`semRelease(sem) -> undefined`
- 简介：释放信号量（空位加 1，唤醒一个等待者；唤醒后由其重查空位）。
- 参数：
  - `sem`：semaphore 对象
- 返回：undefined
- 示例：
  - `semRelease(sem)`

### `setProcessVar`

- 签名：`setProcessVar(key, value) -> value`
- 简介：设置进程级共享变量（整个进程内所有 VM/请求/任务共享，进程存活期内有效）。
- 参数：
  - `key`：变量名（string）
  - `value`：任意值
- 返回：value 返回设置的值（便于链式使用）
- 示例：
  - `setProcessVar("visitCount", 0)`
  - `setProcessVar("cache:" + id, data)   // 服务器模式下跨请求共享的内存缓存`
- 常见错误：
  - setProcessVar() 需要至少 2 个参数
  - setProcessVar() 第 1 个参数应为 string

### `threadRun`

- 签名：`threadRun(fn, args...) -> undefined`
- 简介：在独立 OS 线程中执行函数（threadRun 逃生门）。与 run（调度器任务）的区别：threadRun 每次创建真线程（~17µs、~8MB 栈预留），适合单个长时 CPU 密集任务独占一个核；一般并发请用 run（任务，~µs 级、万级可行）。与旧版 run 线程语义一致：共享 globals、异常打印不传播。
- 参数：
  - `fn`：要执行的函数值
  - `args...`：传递给函数的参数
- 返回：undefined
- 示例：
  - `threadRun(func(n) { var s = heavyCompute(n) ; pln(s) }, 1000000)`
- 常见错误：
  - fn 不是函数值时打印启动失败提示
  - 函数内异常打印 [threadRun 线程异常]，不传播

### `tryLock`

- 签名：`tryLock(m) -> bool`
- 简介：尝试加锁（非阻塞）：成功返回 true，锁被占用返回 false。
- 参数：
  - `m`：mutex 对象
- 返回：bool 是否成功获取锁
- 示例：
  - `if tryLock(m) { ... unlock(m) }`

### `unlock`

- 签名：`unlock(m) -> undefined`
- 简介：释放锁。有任务等待时所有权直接交接（held 保持 true）；否则置空闲并唤醒线程等待者。不校验属主（Go 语义宽松）；未持锁时为幂等空操作。
- 参数：
  - `m`：mutex 对象
- 返回：undefined
- 示例：
  - `unlock(m)`

### `wgAdd`

- 签名：`wgAdd(wg, n) -> undefined`
- 简介：增加等待计数 n（可为负，对应批量 Done）。
- 参数：
  - `wg`：waitGroup 对象
  - `n`：增加的计数（int）
- 返回：undefined
- 示例：
  - `wgAdd(wg, 3)`
- 常见错误：
  - 计数溢出 int 范围时返回错误
  - 计数变负时返回错误（Done 次数超过 Add）

### `wgDone`

- 签名：`wgDone(wg) -> undefined`
- 简介：标记一个任务完成（计数减 1）。计数归零时唤醒全部等待者（唤醒后重查计数）。
- 参数：
  - `wg`：waitGroup 对象
- 返回：undefined
- 示例：
  - `wgDone(wg)`
- 常见错误：
  - 计数减为负数报错（Done 次数超过 Add）

### `wgWait`

- 签名：`wgWait(wg) -> undefined`
- 简介：等待计数归零（所有任务完成）。计数非零时挂起等待（任务内不占 OS 线程）；唤醒后重查计数，仍非零则继续等。
- 参数：
  - `wg`：waitGroup 对象
- 返回：undefined
- 示例：
  - `wgWait(wg)`

### `wlock`

- 签名：`wlock(rw) -> undefined`
- 简介：获取写锁（排他；有读者或写者时等待，等待期间新读者排队防写者饥饿）。
- 参数：
  - `rw`：rwmutex 对象
- 返回：undefined
- 示例：
  - `wlock(rw); ... wunlock(rw)`

### `wunlock`

- 签名：`wunlock(rw) -> undefined`
- 简介：释放写锁并放行等待者（按队列顺序：连续读者或单个写者）。
- 参数：
  - `rw`：rwmutex 对象
- 返回：undefined
- 示例：
  - `wunlock(rw)`

## config（4 个）

### `getCfgStr`

- 签名：`getCfgStr(key[, default]) -> string`
- 简介：读取配置项（持久化键值存储）。
- 参数：
  - `key`：配置键
  - `default`：可选。默认值
- 返回：string 配置值；不存在返回 default 或 undefined
- 示例：
  - `var v = getCfgStr("theme")`

### `getCfgStrAll`

- 签名：`getCfgStrAll() -> object`
- 简介：读取所有配置项。
- 返回：object 键值映射

### `removeCfgStr`

- 签名：`removeCfgStr(key) -> undefined`
- 简介：删除配置项。
- 参数：
  - `key`：配置键
- 返回：undefined

### `setCfgStr`

- 签名：`setCfgStr(key, val) -> undefined`
- 简介：写入配置项。
- 参数：
  - `key`：配置键
  - `val`：配置值
- 返回：undefined
- 示例：
  - `setCfgStr("theme", "dark")`

## containers（12 个）

### `newQueue`

- 签名：`newQueue() -> queue`
- 简介：创建队列（先进先出 FIFO）。
- 返回：queue 对象
- 示例：
  - `var q = newQueue()`

### `newStack`

- 签名：`newStack() -> stack`
- 简介：创建栈（后进先出 LIFO）。
- 返回：stack 对象
- 示例：
  - `var s = newStack()`

### `queueClear`

- 签名：`queueClear(q) -> undefined`
- 简介：清空队列。
- 参数：
  - `q`：queue 对象
- 返回：undefined
- 示例：
  - `queueClear(q)`

### `queueLen`

- 签名：`queueLen(q) -> int`
- 简介：返回队列元素数。
- 参数：
  - `q`：queue 对象
- 返回：int
- 示例：
  - `queueLen(q)`

### `queuePeek`

- 签名：`queuePeek(q) -> value`
- 简介：查看队首（不出队）。
- 参数：
  - `q`：queue 对象
- 返回：队首值
- 示例：
  - `queuePeek(q)`

### `queuePop`

- 签名：`queuePop(q) -> value`
- 简介：出队（弹出队首元素）。
- 参数：
  - `q`：queue 对象
- 返回：队首值
- 示例：
  - `var v = queuePop(q)`

### `queuePush`

- 签名：`queuePush(q, val) -> undefined`
- 简介：入队。
- 参数：
  - `q`：queue 对象
  - `val`：值
- 返回：undefined
- 示例：
  - `queuePush(q, 1)`

### `stackClear`

- 签名：`stackClear(s) -> undefined`
- 简介：清空栈。
- 参数：
  - `s`：stack 对象
- 返回：undefined
- 示例：
  - `stackClear(s)`

### `stackLen`

- 签名：`stackLen(s) -> int`
- 简介：返回栈元素数。
- 参数：
  - `s`：stack 对象
- 返回：int
- 示例：
  - `stackLen(s)`

### `stackPeek`

- 签名：`stackPeek(s) -> value`
- 简介：查看栈顶（不出栈）。
- 参数：
  - `s`：stack 对象
- 返回：栈顶值
- 示例：
  - `var v = stackPeek(s)`

### `stackPop`

- 签名：`stackPop(s) -> value`
- 简介：出栈（弹出栈顶元素）。
- 参数：
  - `s`：stack 对象
- 返回：栈顶值
- 示例：
  - `var v = stackPop(s)`
- 常见错误：
  - 空栈 pop 会返回 undefined 或报错

### `stackPush`

- 签名：`stackPush(s, val) -> undefined`
- 简介：入栈。
- 参数：
  - `s`：stack 对象
  - `val`：要压入的值
- 返回：undefined
- 示例：
  - `stackPush(s, 42)`

## core（89 个）

### `adjustFloat`

- 签名：`adjustFloat(x[, prec]) -> float`
- 简介：消除浮点计算精度误差，按指定精度四舍五入（默认 10 位）。
- 参数：
  - `x`：浮点数
  - `prec`：可选。小数位数，默认 10，范围 0..1000
- 返回：float 调整后的浮点数
- 示例：
  - `adjustFloat(0.1 + 0.2)       // 0.3（消除精度误差）`
  - `adjustFloat(3.14159, 2)      // 3.14`
- 常见错误：
  - 解析失败返回错误
  - 精度参数超出 0..1000 返回错误

### `assert`

- 签名：`assert(cond[, msg]) -> undefined`
- 简介：断言：cond 为 false 时抛异常。
- 参数：
  - `cond`：条件（truthy 通过，falsy 抛异常）
  - `msg`：可选。失败时的错误信息
- 返回：undefined（通过时）
- 示例：
  - `assert(x > 0)`
  - `assert(x > 0, "x 必须为正数")`
- 常见错误：
  - 断言失败时抛异常（不是返回 error 值）

### `byte`

- 签名：`byte(n) -> byte`
- 简介：构造 byte 值（0-255）。超出范围报错。
- 参数：
  - `n`：0-255 的整数
- 返回：byte 字节值
- 示例：
  - `byte(65)  // Byte(65)`
- 常见错误：
  - 值超出 0-255 范围

### `bytesXor`

- 签名：`bytesXor(data, key) -> bytes`
- 简介：批量 XOR：data 的每个字节与 key 的对应字节异或（key 循环复用），返回新 bytes。
- 参数：
  - `data`：bytes/byteArray/string：被异或的数据
  - `key`：bytes/byteArray/string/int(byte)：异或密钥
- 返回：bytes 异或后的新字节串（不可变）
- 示例：
  - `bytesXor("abc", "x")  // 与单字节密钥异或的新 bytes`
- 常见错误：
  - key 不能为空

### `bytesXorInPlace`

- 签名：`bytesXorInPlace(byteArray, key) -> byteArray`
- 简介：原地 XOR（直接修改 byteArray，不创建新对象）。返回原 byteArray。
- 参数：
  - `byteArray`：可变的 byteArray 容器（原地修改）
  - `key`：bytes/byteArray/string/int(byte)：异或密钥
- 返回：传入的 byteArray（已就地修改）
- 示例：
  - `var b = byteArray("abc"); bytesXorInPlace(b, "x")`
- 常见错误：
  - key 不能为空
  - 第一个参数须为 byteArray

### `callMethod`

- 签名：`callMethod(obj, methodName[, args]) -> value`
- 简介：调用对象方法（沿原型链查找 methodName），obj 作为隐式 self 传入。
- 参数：
  - `obj`：object 实例
  - `methodName`：方法名字符串（沿原型链查找）
  - `args`：可选。参数数组或单个值，作为方法后续参数
- 返回：方法返回值
- 示例：
  - `callMethod(o, "greet")               // 无参调用`
  - `callMethod(o, "add", [1, 2])          // 带参调用`
- 常见错误：
  - 对象上找不到方法返回错误
  - 第一个参数应为 object

### `checkErr`

- 签名：`checkErr(v[, "-format=..."]) -> value`
- 简介：若 v 是错误样值则打印错误并退出进程（退出码 1）；非错误原样返回。
- 参数：
  - `v`：要检查的值
  - `-format=`：可选。自定义输出格式，默认 "Error: %v\n"
- 返回：v 非错误时原样返回
- 示例：
  - `var r = checkErr(loadFile("x.txt"))  // 加载失败则退出`
  - `checkErr(r, "-format=fatal: %v\n")`
- 常见错误：
  - v 为错误时直接 exit(1)

### `checkErrX`

- 签名：`checkErrX(v[, "-format=..."]) -> value`
- 简介：checkErr 的 Charlang 兼容别名。
- 参数：
  - `v`：要检查的值
  - `-format=`：可选。自定义输出格式
- 返回：v 非错误时原样返回
- 示例：
  - `checkErrX(error("x"))  // 打印并退出`
- 常见错误：
  - v 为错误时直接 exit(1)

### `clear`

- 签名：`clear(c) -> undefined`
- 简介：清空容器内容（不释放内存）。支持 stringBuilder/array/byteArray/map/ring。
- 参数：
  - `c`：stringBuilder/array/byteArray/map/ring 之一
- 返回：undefined
- 示例：
  - `var sb = newStringBuilder("hi"); clear(sb)  // sb 内容清空`
  - `var a = [1,2]; clear(a)                      // a 变为 []`
- 常见错误：
  - 参数类型不支持

### `compile`

- 签名：`compile(src) -> code|error`
- 简介：编译源码字符串为 Code 对象（可被 runCode 执行）。编译错误以 error 值返回（不抛出）。
- 参数：
  - `src`：Sflang 源码字符串
- 返回：code 编译后的代码对象；失败返回 error 值（用 isErr 检查）
- 示例：
  - `var c = compile("return 1+2")`
  - `if isErr(c) { println(c) } else { println(runCode(c)) }`
- 常见错误：
  - 语法错误返回 error 值（不是抛出异常）

### `dataKeys`

- 签名：`dataKeys(obj) -> array<string>`
- 简介：返回 object/map 的非函数键名（过滤掉方法）。
- 参数：
  - `obj`：object 或 map
- 返回：array<string> 键名数组
- 示例：
  - `dataKeys({"a":1, "b":2})  // ["a", "b"]（顺序不保证）`
- 常见错误：
  - 参数应为 object 或 map

### `dataValues`

- 签名：`dataValues(obj) -> array`
- 简介：返回 object/map 的非函数值（过滤掉方法）。
- 参数：
  - `obj`：object 或 map
- 返回：array 值数组
- 示例：
  - `dataValues({"a":1, "b":2})  // [1, 2]`
- 常见错误：
  - 参数应为 object 或 map

### `deepClone`

- 签名：`deepClone(v) -> value`
- 简介：深拷贝值（递归克隆 array/object/map 及其嵌套结构，保留 object 的原型链）。
- 参数：
  - `v`：要拷贝的值
- 返回：深拷贝后的新值（与原值不共享引用；原型 proto 按引用共享）
- 示例：
  - `var a = [1, [2, 3]]`
  - `var b = deepClone(a)    // 修改 b 不影响 a`
- 常见错误：
  - 嵌套深度超过 200 层返回错误（可能存在自引用/循环引用）

### `defaultUndef`

- 签名：`defaultUndef(x, d) -> value`
- 简介：严格空合并：仅当 x 为 undefined 时返回 d，否则返回 x（等价于 x ?? d）。
- 参数：
  - `x`：原值
  - `d`：兜底值
- 返回：x 非 undefined 时返回 x，否则返回 d
- 示例：
  - `defaultUndef(undefined, 99)  → 99`
  - `defaultUndef(0, 99)          → 0（0 不触发兜底）`
  - `defaultUndef("", 99)         → ""（空串不触发兜底）`

### `defaultVal`

- 签名：`defaultVal(x, d) -> value`
- 简介：宽松兜底：x 为 falsy 时返回 d，否则返回 x（等价于 x || d）。
- 参数：
  - `x`：原值
  - `d`：兜底值
- 返回：x 为 truthy 时返回 x，否则返回 d
- 示例：
  - `defaultVal(undefined, 99)  → 99`
  - `defaultVal(0, 99)          → 99（0 也是 falsy）`
  - `defaultVal("hi", "x")     → "hi"`
- 常见错误：
  - 若只需对 undefined 兜底（不触发 0/""），用 defaultUndef 或 ?? 运算符

### `dumpVar`

- 签名：`dumpVar(v) -> string`
- 简介：转储变量详细信息（类型名、类型码、值摘要），返回多行诊断字符串。
- 参数：
  - `v`：任意值
- 返回：string 多行诊断信息（type/typeCode/value）
- 示例：
  - `println(dumpVar(42))`
  - `// type: int`
  - `// typeCode: 1`
  - `// value: 42`

### `entries`

- 签名：`entries(obj) -> array<[key, value]>`
- 简介：返回 object/map 的键值对数组（每对为 [key, value]），过滤掉函数成员。
- 参数：
  - `obj`：object 或 map
- 返回：array，元素为 [key, value] 二元数组
- 示例：
  - `entries({"a":1, "b":2})  // [["a", 1], ["b", 2]]（顺序不保证）`
- 常见错误：
  - 参数应为 object 或 map

### `errStrf`

- 签名：`errStrf(fmt, args...) -> string`
- 简介：格式化生成 "TXERROR:" 前缀的错误字符串（创建字符串形式错误的便捷方式）。
- 参数：
  - `fmt`：格式字符串（同 sprintf）
  - `args`：对应占位符的参数（可变）
- 返回：string "TXERROR:" + 格式化结果
- 示例：
  - `errStrf("%s 失败", "加载")  // "TXERROR:加载 失败"`

### `errToEmpty`

- 签名：`errToEmpty(v) -> value`
- 简介：若 v 是错误样值则转为空字符串，否则原样返回（安全处理可能错误值）。
- 参数：
  - `v`：任意值
- 返回：错误时返回空字符串，非错误时返回原值
- 示例：
  - `errToEmpty(error("x"))   // ""`
  - `errToEmpty("hi")          // "hi"`

### `errf`

- 签名：`errf(fmt, args...) -> string`
- 简介：errStrf 的 Charlang 兼容别名：格式化生成 TXERROR 错误字符串。
- 参数：
  - `fmt`：格式字符串
  - `args`：对应占位符的参数（可变）
- 返回：string "TXERROR:" + 格式化结果
- 示例：
  - `errf("boom")  // "TXERROR:boom"`

### `error`

- 签名：`error(msg) -> error`
- 简介：创建错误值（用于返回错误，不抛异常）。
- 参数：
  - `msg`：错误信息字符串
- 返回：error 错误值
- 示例：
  - `func divide(a, b) { if b == 0 { return error("除零") }; return a / b }`

### `explainUndef`

- 签名：`explainUndef(name) -> string`
- 简介：返回某名字为何为 undefined 的诊断字符串（含是否预定义、相似名字提示，AI 友好）。
- 参数：
  - `name`：变量名字符串
- 返回：string 多行诊断信息
- 示例：
  - `explainUndef("printl")`
  - `// 提示：未定义，相似名字：println`

### `fatalf`

- 签名：`fatalf(fmt, args...) -> !`
- 简介：格式化输出错误信息到 stderr 并以退出码 1 终止进程。
- 参数：
  - `fmt`：格式字符串（占位符同 printf）
  - `args`：对应占位符的参数（可变）
- 返回：不返回（进程以退出码 1 终止）
- 示例：
  - `fatalf("invalid token")`
  - `fatalf("failed to remove [%v] %v: %v", i, path, err)`
- 常见错误：
  - 信息会输出到 stderr（而非 stdout），便于与正常输出分流
  - 面向 AI 排错：格式串中尽量带上相关参数值与上下文

### `filter`

- 签名：`filter(arr, fn) -> array`
- 简介：用谓词函数过滤数组，返回新数组（仅保留 fn(x) 为 truthy 的元素）。
- 参数：
  - `arr`：原数组（不修改）
  - `fn`：谓词函数 fn(x) -> truthy/falsy
- 返回：array 过滤后的新数组
- 示例：
  - `filter([1,2,3,4], func(x) { return x > 2 })  // [3, 4]`
- 常见错误：
  - 第一个参数应为 array

### `find`

- 签名：`find(arr, fn) -> value|undefined`
- 简介：查找数组中第一个满足谓词的元素，返回该元素；无则 undefined。
- 参数：
  - `arr`：原数组
  - `fn`：谓词函数 fn(x) -> truthy/falsy
- 返回：第一个匹配元素，无匹配返回 undefined
- 示例：
  - `find([1,2,3,4], func(x) { return x > 2 })  // 3`
- 常见错误：
  - 第一个参数应为 array

### `float`

- 签名：`float(x) -> float`
- 简介：转浮点。支持 int/float/bool/byte/string/bigInt/bigFloat。
- 参数：
  - `x`：要转换的值
- 返回：float 浮点值
- 示例：
  - `float(3)        // 3.0`
  - `float("3.14")   // 3.14`
- 常见错误：
  - 字符串无法解析为浮点返回错误
  - BigInt 超出 i64 范围返回错误

### `fpr`

- 签名：`fpr(fmt, args...) -> undefined`
- 简介：printf 的别名：按格式字符串打印（不换行）。
- 参数：
  - `fmt`：格式字符串
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `fpr("x=%d", 1)  // 输出 x=1（不换行）`

### `getAllSwitches`

- 签名：`getAllSwitches(args, key) -> array<string>`
- 简介：从参数数组提取所有匹配 "--key=value" 的值（可多个同名），返回数组。
- 参数：
  - `args`：参数数组（如 argsG）
  - `key`：前缀字符串，含前缀和等号
- 返回：array<string> 所有匹配值；无匹配返回空数组
- 示例：
  - `getAllSwitches(argsG, "--attach=")  // ["file1.pdf", "file2.xlsx"]`

### `getErrStr`

- 签名：`getErrStr(v) -> string`
- 简介：提取错误信息字符串：Error 取 message，TXERROR 字符串去前缀，其他取 to_str。
- 参数：
  - `v`：任意值
- 返回：string 错误信息或字符串表示
- 示例：
  - `getErrStr(error("bad"))        // "bad"`
  - `getErrStr("TXERROR:boom")      // "boom"`

### `getErrStrX`

- 签名：`getErrStrX(v) -> string`
- 简介：getErrStr 的 Charlang 兼容别名。
- 参数：
  - `v`：任意值
- 返回：string 错误信息字符串
- 示例：
  - `getErrStrX("TXERROR:x")  // "x"`

### `getMember`

- 签名：`getMember(obj, key) -> value`
- 简介：反射式读取 object/map 的成员。Object 沿原型链查找；不存在返回 undefined。
- 参数：
  - `obj`：object 或 map
  - `key`：成员名字符串
- 返回：成员值；不存在返回 undefined
- 示例：
  - `getMember({"a":1}, "a")  // 1`
  - `getMember(obj, "method")  // 沿原型链查找`
- 常见错误：
  - 第一个参数应为 object 或 map

### `getParam`

- 签名：`getParam(args, index[, default]) -> value`
- 简介：从参数数组取第 index 个元素，不存在则返回 default（或 undefined）。
- 参数：
  - `args`：参数数组（如 argsG）
  - `index`：位置索引（int，从 0 开始，不能为负）
  - `default`：可选。缺省时返回的默认值
- 返回：对应位置参数；不存在返回 default 或 undefined
- 示例：
  - `getParam(argsG, 0)               // 第一个参数`
  - `getParam(argsG, 2, "fallback")    // 越界返回 "fallback"`
- 常见错误：
  - index 为负数返回错误

### `getSwitch`

- 签名：`getSwitch(args, key[, default]) -> string`
- 简介：从参数数组按 "--key=value" 前缀提取开关值；无匹配返回 default。
- 参数：
  - `args`：参数数组（如 argsG）
  - `key`：前缀字符串，含前缀和等号，如 "--host="
  - `default`：可选。无匹配时的默认值
- 返回：匹配项的等号右侧值；无匹配返回 default
- 示例：
  - `getSwitch(argsG, "--host=", "localhost")  // 匹配 --host=x 返回 x`

### `getValueByRef`

- 签名：`getValueByRef(ref) -> value`
- 简介：读取引用容器内的值。
- 参数：
  - `ref`：newRef 创建的引用对象
- 返回：引用内当前值
- 示例：
  - `getValueByRef(newRef(5))  // 5`
- 常见错误：
  - 参数不是引用对象（需用 newRef 创建）

### `globals`

- 签名：`globals() -> array<string>`
- 简介：列出所有全局变量名（用于反射与调试）。
- 返回：array<string> 全局变量名数组
- 示例：
  - `var names = globals()  // 当前所有全局变量名`

### `hasKey`

- 签名：`hasKey(obj, key) -> bool`
- 简介：判断 object/map 是否包含某键。
- 参数：
  - `obj`：object 或 map
  - `key`：键名字符串
- 返回：bool：存在返回 true
- 示例：
  - `hasKey({"a":1}, "a")  // true`
  - `hasKey({"a":1}, "b")  // false`
- 常见错误：
  - 第一个参数应为 object 或 map

### `help`

- 签名：`help([name]) -> string`
- 简介：查阅内置函数文档。无参列出全部分类，有参返回函数详情或分类函数列表。
- 参数：
  - `name`：可选。函数名（如 "regFind"）或分类名（如 "regex"）
- 返回：string 多行文档或分类列表
- 示例：
  - `help()             → 列出所有内置函数分类`
  - `help("regFind")    → regFind 的签名/参数/示例/常见错误`
  - `help("regex")      → 列出 regex 分类下所有函数`
- 常见错误：
  - 函数名拼写错误时返回错误；help() 会自动给出相似函数建议

### `ifSwitchExists`

- 签名：`ifSwitchExists(args, key) -> bool`
- 简介：检查参数数组中是否存在某个布尔型开关（无值，如 "--verbose"）。
- 参数：
  - `args`：参数数组（如 argsG）
  - `key`：开关名字符串，如 "--verbose" 或 "-v"
- 返回：bool：存在返回 true
- 示例：
  - `ifSwitchExists(argsG, "--verbose")  // true/false`

### `int`

- 签名：`int(x) -> int`
- 简介：转整数。支持 int/float/bool/byte/string/bigInt（字符串需为有效整数）。
- 参数：
  - `x`：要转换的值（int/float/bool/byte/string/bigInt）
- 返回：int 整数值
- 示例：
  - `int(3.9)        // 3（截断）`
  - `int(true)       // 1`
  - `int("42")      // 42`
- 常见错误：
  - 字符串不是有效整数返回错误
  - BigInt 超出 i64 范围返回错误

### `isErr`

- 签名：`isErr(v) -> bool`
- 简介：判断是否为错误样值（Error 对象或 "TXERROR:" 开头的字符串）。
- 参数：
  - `v`：任意值
- 返回：bool：是错误样值返回 true
- 示例：
  - `isErr(error("x"))          // true`
  - `isErr("TXERROR:boom")      // true`
  - `isErr(42)                   // false`

### `isErrStr`

- 签名：`isErrStr(v) -> bool`
- 简介：判断是否为 "TXERROR:" 开头的字符串（仅识别字符串形式错误）。
- 参数：
  - `v`：任意值
- 返回：bool：是 TXERROR 字符串返回 true
- 示例：
  - `isErrStr("TXERROR:boom")  // true`
  - `isErrStr(error("x"))       // false（Error 对象不是字符串）`

### `isErrX`

- 签名：`isErrX(v) -> bool`
- 简介：isErr 的 Charlang 兼容别名。
- 参数：
  - `v`：任意值
- 返回：bool：是错误样值返回 true
- 示例：
  - `isErrX(error("x"))  // true`

### `isError`

- 签名：`isError(v) -> bool`
- 简介：判断值是否为 error 类型。
- 参数：
  - `v`：任意值
- 返回：bool：是 error 返回 true
- 示例：
  - `isError(error("x"))   → true`
  - `isError(42)             → false`

### `isType`

- 签名：`isType(v, typeName) -> bool`
- 简介：按类型名（大小写不敏感）判断值类型。支持基础类型与 native 细分（如 ring/regex）。
- 参数：
  - `v`：任意值
  - `typeName`：类型名字符串（与 typeName 返回一致）
- 返回：bool：类型匹配返回 true
- 示例：
  - `isType(42, "int")        // true`
  - `isType("hi", "string")   // true`

### `isTypeCode`

- 签名：`isTypeCode(v, code) -> bool`
- 简介：按类型数字编码判断值类型（编码见 typeCode，0-22）。
- 参数：
  - `v`：任意值
  - `code`：类型编码整数（详见 typeCode）
- 返回：bool：编码匹配返回 true
- 示例：
  - `isTypeCode(42, 1)        // true（1 = int）`
  - `isTypeCode("hi", 4)      // true（4 = string）`

### `isUndefined`

- 签名：`isUndefined([v]) -> bool`
- 简介：判断是否为 undefined。缺参时返回 true（便于链式判空 isUndefined(m["k"])）。
- 参数：
  - `v`：可选。任意值，省略时视为 undefined
- 返回：bool：是 undefined 或缺参返回 true
- 示例：
  - `isUndefined(undefined)  // true`
  - `isUndefined(42)         // false`
  - `isUndefined()           // true（缺参）`

### `keys`

- 签名：`keys(obj) -> array`
- 简介：返回 object/map 的所有键（无序）。array 返回索引数组，string 返回码点位置数组。
- 参数：
  - `obj`：object 或 map（array/string 亦可）
- 返回：array 键名数组（array 入参时为 array<int> 索引）
- 示例：
  - `keys({"a":1, "b":2})  → ["a", "b"]（顺序不保证）`
  - `keys([10, 20])        → [0, 1]`
- 常见错误：
  - 对非 object/map/array/string 类型会返回错误

### `len`

- 签名：`len(x) -> int`
- 简介：返回容器或字符串的长度/元素数。
- 参数：
  - `x`：string（字符数）/ array / object / map / bytes（字节数）
- 返回：int 长度值
- 示例：
  - `len("hello")        → 5`
  - `len([1,2,3])         → 3`
  - `len({"a":1,"b":2}) → 2`
- 常见错误：
  - 对不可计长度的类型（如 int）会返回错误

### `map`

- 签名：`map(arr, fn) -> array`
- 简介：用函数映射数组每个元素，返回新数组 [fn(a[0]), fn(a[1]), ...]。
- 参数：
  - `arr`：原数组（不修改）
  - `fn`：映射函数 fn(x) -> y
- 返回：array 映射后的新数组
- 示例：
  - `map([1,2,3], func(x) { return x * 2 })  // [2, 4, 6]`
- 常见错误：
  - 第一个参数应为 array

### `newMap`

- 签名：`newMap() -> map`
- 简介：创建空有序 Map（纯数据容器，按插入顺序遍历）。
- 返回：map 空有序映射
- 示例：
  - `var m = newMap(); setMember(m, "k", 1)`

### `newObject`

- 签名：`newObject(proto) -> object`
- 简介：创建以 proto 为原型的空 object（暴露原型链，用于方法共享）。
- 参数：
  - `proto`：原型对象（方法挂在其上）
- 返回：object 以 proto 为原型的新对象
- 示例：
  - `var proto = { greet: func() { return "hi" } }`
  - `var o = newObject(proto)`
  - `o.greet()  // "hi"（继承自原型）`
- 常见错误：
  - 第一个参数应为 object

### `newRef`

- 签名：`newRef(value) -> ref`
- 简介：创建引用容器，包装一个初始值。引用是独立可变容器，便于函数传参后修改。
- 参数：
  - `value`：初始值
- 返回：ref 引用容器（用 getValueByRef/setValueByRef 读写）
- 示例：
  - `var r = newRef(10)`
  - `getValueByRef(r)  // 10`
  - `setValueByRef(r, 20)`

### `newStringBuilder`

- 签名：`newStringBuilder([initial]) -> stringBuilder`
- 简介：创建 StringBuilder（高效字符串构建器），可选初始内容。
- 参数：
  - `initial`：可选。初始字符串内容，默认为空
- 返回：stringBuilder 对象，可用 writeStr/len/toStr/clear/reset 操作
- 示例：
  - `var sb = newStringBuilder()`
  - `var sb2 = newStringBuilder("init")`

### `pass`

- 签名：`pass(...) -> undefined`
- 简介：空操作占位符（no-op），忽略所有参数，返回 undefined。
- 参数：
  - `...`：任意参数，全部忽略
- 返回：undefined
- 示例：
  - `pass()  // 什么都不做`

### `pl`

- 签名：`pl(fmt, args...) -> undefined`
- 简介：printfln 的简写别名：格式化打印并换行。
- 参数：
  - `fmt`：格式字符串
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `pl("hello %d", 42)  // 输出 hello 42 并换行`

### `plErr`

- 签名：`plErr(fmt, args...) -> undefined`
- 简介：格式化输出一行到 stderr（进程级，不受 set_output 重定向影响，自动换行）。
- 参数：
  - `fmt`：格式字符串（占位符同 printf）
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `plErr("invalid token")`
  - `plErr("failed to remove [%v] %v: %v", i, path, err)`
- 常见错误：
  - 与 pl 的区别：直写进程 stderr 而非 VM 输出通道——服务管理器（systemd/journald）
  - 会捕获到标准服务日志；需要与正常输出分流、或主输出被重定向时使用

### `plNow`

- 签名：`plNow(fmt, args...) -> undefined`
- 简介：带本地时间戳的格式化打印：输出 "[yyyy-MM-dd HH:mm:ss] " 前缀 + 格式化内容并换行（对标 charlang 的 plNow）。
- 参数：
  - `fmt`：格式字符串（Go 风格占位符，与 pl 相同）
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `plNow("Daily checking...")       // [2026-09-03 13:41:40] Daily checking...`
  - `plNow("Processing %v...", name)  // [2026-09-03 13:41:40] Processing xxx...`
- 常见错误：
  - 时间戳取自本地时区（与 getNowStr 一致）

### `pln`

- 签名：`pln(...) -> undefined`
- 简介：println 的简写别名：参数按默认格式（空格分隔）打印并换行，不做 printf 格式化（与 charlang 的 pln 一致）。
- 参数：
  - `...`：任意类型，自动转为字符串，多个参数用空格分隔
- 返回：undefined
- 示例：
  - `pln("hello")          // 输出 hello 并换行`
  - `pln("count:", 5)     // 输出 count: 5`
- 常见错误：
  - 需要 printf 风格格式化打印请用 pl（格式化 + 换行）或 printf（格式化不换行）

### `plt`

- 签名：`plt(...) -> undefined`
- 简介：打印每个参数的类型与值，格式 (类型名)值，每行一个（调试用）。
- 参数：
  - `...`：任意类型，逐个输出类型与值
- 返回：undefined
- 示例：
  - `plt(42, "hi")`
  - `// 输出：`
  - `// (int) 42`
  - `// (string) "hi"`

### `pop`

- 签名：`pop(arr) -> value`
- 简介：弹出数组末尾元素并返回（原地修改）。
- 参数：
  - `arr`：目标数组（原地修改）
- 返回：数组末尾元素
- 示例：
  - `var a = [1, 2, 3]; var x = pop(a)  // x == 3; a 变为 [1, 2]`
- 常见错误：
  - 空数组弹出返回错误
  - 第一个参数应为 array

### `pr`

- 签名：`pr(...) -> undefined`
- 简介：print 的简写别名：打印参数（空格分隔）不换行。
- 参数：
  - `...`：任意类型，自动转为字符串
- 返回：undefined
- 示例：
  - `pr("hello")  // 输出 hello（不换行）`

### `prf`

- 签名：`prf(fmt, args...) -> undefined`
- 简介：printf 的简写别名：按格式字符串打印（不换行）。
- 参数：
  - `fmt`：格式字符串
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `prf("%d+%d=%d\n", 1, 2, 3)  // 输出 1+2=3 并换行`

### `print`

- 签名：`print(...) -> undefined`
- 简介：打印参数（空格分隔）不换行，不做 printf 格式化。
- 参数：
  - `...`：任意类型，自动转为字符串（多个用空格分隔）
- 返回：undefined（无返回值）
- 示例：
  - `print("hello")              // 输出 hello（不换行）`
  - `print("a", 1, true)         // 输出 a 1 true`

### `printf`

- 签名：`printf(fmt, args...) -> undefined`
- 简介：按格式字符串打印（不换行），Go 风格占位符（%v %d %s %f %t %x %%）。
- 参数：
  - `fmt`：格式字符串，含 %v %d %s %f %t %x %%
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `printf("%s=%d\n", "count", 42)   // 输出 count=42 并换行`
  - `printf("%.2f", 3.14159)            // 输出 3.14`
- 常见错误：
  - 占位符数量与参数数量不匹配会返回错误

### `printfln`

- 签名：`printfln(fmt, args...) -> undefined`
- 简介：格式化打印并换行（语义 = printf + "\n"）。
- 参数：
  - `fmt`：格式字符串
  - `args`：对应占位符的参数（可变）
- 返回：undefined
- 示例：
  - `printfln("%s=%d", "count", 42)  // 输出 count=42 并换行`

### `println`

- 签名：`println(...) -> undefined`
- 简介：打印参数（空格分隔）并换行，输出到标准输出。
- 参数：
  - `...`：任意类型，自动转为字符串（多个用空格分隔）
- 返回：undefined（无返回值）
- 示例：
  - `println("hello")              → hello`
  - `println("a", 1, true)         → a 1 true`
  - `println(1 + 2)                 → 3`

### `push`

- 签名：`push(arr, val) -> array`
- 简介：向数组末尾添加元素（原地修改），返回该数组本身（同一引用，便于链式调用）。
- 参数：
  - `arr`：目标数组（原地修改）
  - `val`：要添加的值
- 返回：array 添加元素后的原数组（与 arr 为同一引用，不是新数组）
- 示例：
  - `var a = [1, 2]; push(a, 3)      // a 变为 [1, 2, 3]，返回值即 a`
  - `push(push([1], 2), 3)           // [1, 2, 3]（链式调用）`
- 常见错误：
  - 第一个参数应为 array

### `randomStr`

- 签名：`randomStr(n) -> string`
- 简介：生成长度为 n 的随机字母数字字符串（大小写字母 + 数字）。
- 参数：
  - `n`：长度（int，非负）
- 返回：string 随机字母数字串
- 示例：
  - `randomStr(8)  // 如 "aB3xK9mN"`
- 常见错误：
  - 长度为负或超过 1000000 返回错误

### `range`

- 签名：`range(start, end[, step]) -> array<int>`
- 简介：生成整数数组（含 start 不含 end）。step 默认 1，可为负数。
- 参数：
  - `start`：起始值（含）
  - `end`：结束值（不含）
  - `step`：可选。步长，默认 1；负数用于递减
- 返回：array<int> 整数数组
- 示例：
  - `range(1, 5)          → [1, 2, 3, 4]`
  - `range(0, 10, 2)      → [0, 2, 4, 6, 8]`
  - `range(5, 0, -1)      → [5, 4, 3, 2, 1]`
- 常见错误：
  - step 为 0 返回错误
  - 元素数量超过 1000000 上限返回错误（请减少跨度或使用步长）

### `reset`

- 签名：`reset(c) -> undefined`
- 简介：清空容器并释放内存（对 stringBuilder 效果最明显）。支持 stringBuilder/array/byteArray。
- 参数：
  - `c`：stringBuilder/array/byteArray 之一
- 返回：undefined
- 示例：
  - `var sb = newStringBuilder("hi"); reset(sb)  // sb 清空并释放内存`
- 常见错误：
  - 参数类型不支持

### `runCode`

- 签名：`runCode(code) -> value|error`
- 简介：执行 compile() 返回的 Code 对象。运行错误以 error 值返回（不抛出）。
- 参数：
  - `code`：compile() 的返回值
- 返回：执行结果；运行出错返回 error 值（用 isErr 检查）
- 示例：
  - `var c = compile("return fib(10)")`
  - `var r = runCode(c)`
  - `if isErr(r) { println("错误:", r) } else { println("结果:", r) }`
- 常见错误：
  - 参数不是 code 对象返回 error；运行时错误也返回 error 值

### `setMember`

- 签名：`setMember(obj, key, value) -> undefined`
- 简介：反射式设置 object/map 的成员值（原地修改，仅写入自身，与 obj.key = v 一致）。
- 参数：
  - `obj`：object 或 map
  - `key`：成员名字符串
  - `value`：新值
- 返回：undefined
- 示例：
  - `var o = {}; setMember(o, "k", 1)  // o 变为 {"k":1}`
- 常见错误：
  - 第一个参数应为 object 或 map

### `setValueByRef`

- 签名：`setValueByRef(ref, newValue) -> undefined`
- 简介：设置引用容器内的值（原地修改）。
- 参数：
  - `ref`：newRef 创建的引用对象
  - `newValue`：新值
- 返回：undefined
- 示例：
  - `var r = newRef(1); setValueByRef(r, 99); getValueByRef(r)  // 99`
- 常见错误：
  - 第一个参数不是引用对象

### `showTable`

- 签名：`showTable(data[, opts]) -> string`
- 简介：将二维数组渲染为对齐的 ASCII 表格字符串（首行默认为表头）。
- 参数：
  - `data`：array<array>，每行是一维数组
  - `opts`：可选。map/object，支持 header(bool,默认true) 和 sep(string,默认"|")
- 返回：string 表格字符串（含边框，不直接打印）
- 示例：
  - `println(showTable([["姓名","年龄"],["张三",20],["李四",25]]))`
  - `// +------+----+`
  - `// | 姓名 | 年龄 |`
  - `// +------+----+`
  - `// | 张三 | 20  |`
  - `// | 李四 | 25  |`
  - `// +------+----+`
- 常见错误：
  - 每行必须是一维数组

### `sleep`

- 签名：`sleep(seconds) -> undefined`
- 简介：休眠指定秒数（支持小数，如 0.5）。上限一年。
- 参数：
  - `seconds`：休眠时长（秒，float 或 int，需为 0..31536000 的有限数字）
- 返回：undefined
- 示例：
  - `sleep(1)     // 休眠 1 秒`
  - `sleep(0.5)   // 休眠 500 毫秒`
- 常见错误：
  - 参数为负数、NaN、inf 或超过一年上限时返回错误

### `sleepMs`

- 签名：`sleepMs(ms) -> undefined`
- 简介：休眠指定毫秒数（整数）。
- 参数：
  - `ms`：毫秒数（int）
- 返回：undefined
- 示例：
  - `sleepMs(500)  // 休眠 500 毫秒`

### `spr`

- 签名：`spr(fmt, args...) -> string`
- 简介：sprintf 的简写别名：格式化字符串并返回（不打印）。
- 参数：
  - `fmt`：格式字符串
  - `args`：对应占位符的参数（可变）
- 返回：string 格式化后的字符串
- 示例：
  - `var s = spr("%s=%d", "count", 42)  // s == "count=42"`

### `sprintf`

- 签名：`sprintf(fmt, args...) -> string`
- 简介：格式化字符串（Go 风格占位符：%v %d %s %f %t %x %%）。
- 参数：
  - `fmt`：格式字符串，含 %v(通用) %d(整数) %s(字符串) %f(浮点) %t(布尔) %x(十六进制) %%(字面%)
  - `args`：对应占位符的参数（可变）
- 返回：string 格式化后的字符串
- 示例：
  - `sprintf("%s=%d", "count", 42)   → "count=42"`
  - `sprintf("%.2f", 3.14159)         → "3.14"`
- 常见错误：
  - 参数不足时对应占位符按字面输出（不报错）；多余参数忽略
  - %d/%f/%x 等类型不符返回错误
  - 格式化宽度超过 1000000 返回错误

### `string`

- 签名：`string([x]) -> string`
- 简介：转字符串。无参返回空串；有参返回参数的字符串表示。
- 参数：
  - `x`：可选。要转换的值，省略时返回空串
- 返回：string 字符串表示
- 示例：
  - `string(42)       // "42"`
  - `string(3.14)     // "3.14"`
  - `string()         // ""`

### `toFloat`

- 签名：`toFloat(x) -> float`
- 简介：float 的别名：转浮点。
- 参数：
  - `x`：要转换的值
- 返回：float 浮点值
- 示例：
  - `toFloat("3.14")  // 3.14`
- 常见错误：
  - 字符串无法解析返回错误

### `toInt`

- 签名：`toInt(x) -> int`
- 简介：int 的别名：转整数。
- 参数：
  - `x`：要转换的值
- 返回：int 整数值
- 示例：
  - `toInt("42")  // 42`
- 常见错误：
  - 字符串不是有效整数返回错误

### `toKMG`

- 签名：`toKMG(n[, decimals]) -> string`
- 简介：将数字转为带单位的易读字符串（K/M/G/T/P，1024 进制），默认 2 位小数。
- 参数：
  - `n`：数字（int 或 float）
  - `decimals`：可选。小数位数，默认 2
- 返回：string 带 K/M/G/T/P 单位的字符串
- 示例：
  - `toKMG(1536)        // "1.50K"`
  - `toKMG(1048576)     // "1.00M"`
  - `toKMG(0, 0)        // "0"`

### `toStr`

- 签名：`toStr([x]) -> string`
- 简介：string 的别名：转字符串。无参返回空串。
- 参数：
  - `x`：可选。要转换的值
- 返回：string 字符串表示
- 示例：
  - `toStr(42)  // "42"`

### `trimErr`

- 签名：`trimErr(v[, cutset...]) -> string|value`
- 简介：若 v 是错误样值则原样返回（不丢失错误），否则去空白。可指定 cutset 字符集。
- 参数：
  - `v`：要处理的值
  - `cutset`：可选。要去除的字符（多个字符串参数）
- 返回：错误样值原样返回；否则返回去空白后的字符串
- 示例：
  - `trimErr("  hi  ")            // "hi"`
  - `trimErr(error("x"))          // 原样返回错误`
  - `trimErr("##hi##", "#")       // "hi"`

### `typeCode`

- 签名：`typeCode(x) -> int`
- 简介：返回值的固定类型编码（数字），用于快速类型判断。
- 参数：
  - `x`：任意值
- 返回：int 类型编码：0=undefined 1=int 2=float 3=bool 4=string 5=bytes 6=array 7=object 8=function 9=builtin 10=error 11=native 12=byteArray 13=bigInt 14=bigFloat 15=datetime 16=file 17=byte 18=map 19=stringBuilder 20=httpReq 21=httpResp 22=webSocket
- 示例：
  - `typeCode(42)         → 1`
  - `typeCode("hi")      → 4`
  - `typeCode(undefined)  → 0`

### `typeName`

- 签名：`typeName(x) -> string`
- 简介：返回值的类型名字符串（如 "int"、"string"、"array"）。
- 参数：
  - `x`：任意值
- 返回：string 类型名
- 示例：
  - `typeName(42)         → int`
  - `typeName("hi")      → string`
  - `typeName([1,2])      → array`

### `undefToEmpty`

- 签名：`undefToEmpty(v) -> string`
- 简介：将 undefined（或缺参）转为空字符串，其余值转为 to_str（对标 Charlang nilToEmpty）。
- 参数：
  - `v`：任意值
- 返回：undefined 返回空串，其余返回 to_str
- 示例：
  - `undefToEmpty(undefined)  // ""`
  - `undefToEmpty(42)          // "42"`

### `uuid`

- 签名：`uuid() -> string`
- 简介：生成随机 UUID 字符串（v4 格式，36 字符含连字符）。
- 返回：string UUID，如 "550e8400-e29b-41d4-a716-446655440000"
- 示例：
  - `var id = uuid()   // 每次不同`

### `values`

- 签名：`values(obj) -> array`
- 简介：返回 object/map 的所有值（无序）。传 array 时返回元素快照拷贝。
- 参数：
  - `obj`：object 或 map（array 亦可，返回其元素快照）
- 返回：array 值数组
- 示例：
  - `values({"a":1, "b":2})  → [1, 2]`
  - `len(values(newMap()))     → 0（map 支持）`
- 常见错误：
  - 对非 object/map/array 类型会返回错误

## crypto（31 个）

### `aesDecrypt`

- 签名：`aesDecrypt(data, key) -> bytes`
- 简介：AES-CBC 解密，输入须为 [16 字节 IV][密文] 格式。
- 参数：
  - `data`：string/bytes/byteArray：[16 字节 IV][密文]（即 aesEncrypt 的输出）
  - `key`：string/bytes：密钥（须与加密时相同，长度 16/24/32）
- 返回：bytes：解密后的明文字节；密钥错误或数据损坏返回 error
- 示例：
  - `pt := aesDecrypt(aesEncrypt("hello", "0123456789abcdef"), "0123456789abcdef") → bytes("hello")`
- 常见错误：
  - data 至少 16 字节（IV 段），否则返回 error
  - key 与加密时不一致或填充损坏时返回 error（不 panic）

### `aesDecryptStr`

- 签名：`aesDecryptStr(base64, key) -> string`
- 简介：便捷字符串解密：输入 aesEncryptStr 产生的 base64，返回 UTF-8 字符串。
- 参数：
  - `base64`：string：aesEncryptStr 的输出（base64）
  - `key`：string/bytes：密钥（须与加密时相同）
- 返回：string：解密后的明文（按 UTF-8 解释）；失败返回 error
- 示例：
  - `aesDecryptStr(aesEncryptStr("hello", "0123456789abcdef"), "0123456789abcdef") → "hello"`
- 常见错误：
  - base64 解码后数据短于 16 字节返回 error
  - 密钥错误或填充损坏返回 error（不 panic）

### `aesEncrypt`

- 签名：`aesEncrypt(data, key) -> bytes`
- 简介：AES-CBC 加密（PKCS7 填充），返回 [16 字节 IV][密文] 的 bytes。
- 参数：
  - `data`：string/bytes/byteArray：明文
  - `key`：string/bytes：密钥，长度 16/24/32（对应 AES-128/192/256）
- 返回：bytes：[16 字节随机 IV][密文]，每次调用 IV 不同
- 示例：
  - `ct := aesEncrypt("hello", "0123456789abcdef")  → 32 字节 bytes（16 IV + 16 密文）`
- 常见错误：
  - key 长度必须为 16/24/32（对应 AES-128/192/256）
  - 输出含随机 IV，每次结果不同；用 aesDecrypt 解密

### `aesEncryptStr`

- 签名：`aesEncryptStr(text, key) -> string`
- 简介：便捷字符串加密：UTF-8 字节加密后输出 base64 字符串。
- 参数：
  - `text`：string：明文（UTF-8 编码）
  - `key`：string/bytes：密钥，长度 16/24/32
- 返回：string：标准 base64（含 IV），可直接传输/存储
- 示例：
  - `ct := aesEncryptStr("hello", "0123456789abcdef")  → base64 字符串`
- 常见错误：
  - 输出含随机 IV，每次结果不同
  - 等价于 base64(aesEncrypt(text, key))

### `decryptBytes`

- 签名：`decryptBytes(data[, code]) -> bytes|error`
- 简介：decryptData 的别名：用 TXDEF 算法解密数据。
- 参数：
  - `data`：encryptData/encryptBytes 的输出
  - `code`：可选。密码字符串
- 返回：bytes 解密后的数据；失败返回 error 值
- 示例：
  - `decryptBytes(encryptBytes("x"))`

### `decryptData`

- 签名：`decryptData(data[, code]) -> bytes|error`
- 简介：用 TXDEF 算法解密数据（自动识别并去除 //TXDEF# 头）。
- 参数：
  - `data`：encryptData 输出的 bytes/string/byteArray
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：bytes 解密后的原始数据；失败返回 error 值
- 示例：
  - `decryptData(encryptData("x"))   // 还原 "x" 的 bytes`
- 常见错误：
  - 密码错误或数据损坏返回 error

### `decryptDataByTXDEE`

- 签名：`decryptDataByTXDEE(data[, code]) -> bytes|error`
- 简介：用 TXDEE 算法解密数据（需与加密时同一密码）。
- 参数：
  - `data`：encryptDataByTXDEE 输出的 bytes/string/byteArray
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：bytes 解密后的原始数据；解密失败返回 error 值
- 示例：
  - `decryptDataByTXDEE(encryptDataByTXDEE("x"))   // 还原 "x" 的 bytes`
- 常见错误：
  - 密码错误或数据损坏时返回 error 值（数据长度 < 4）

### `decryptDataByTXDEM`

- 签名：`decryptDataByTXDEM(data[, codeA]) -> bytes|error`
- 简介：用 TXDEM 解密数据。提供 codeA 或 codeB 任一即可（自动尝试两个盐槽）。
- 参数：
  - `data`：encryptDataByTXDEM 的输出（string/bytes/byteArray）
  - `codeA`：可选。密码 A 或 B，省略时默认 "topxeq"
- 返回：bytes 解密后的数据；两个密码都不匹配返回 error 值
- 示例：
  - `decryptDataByTXDEM(encryptDataByTXDEM("x", "pw1", "pw2"), "pw1")  // 还原 "x"`
- 常见错误：
  - 两个密码都不正确时返回 error 值

### `decryptStr`

- 签名：`decryptStr(hex[, code]) -> string|error`
- 简介：decryptText 的别名：解密 TXDEF 文本密文。
- 参数：
  - `hex`：encryptText/encryptStr 输出的 hex 字符串
  - `code`：可选。密码字符串
- 返回：string 解密后的原文；失败返回 error 值
- 示例：
  - `decryptStr(encryptStr("hi"))`

### `decryptText`

- 签名：`decryptText(hex[, code]) -> string|error`
- 简介：解密 encryptText 生成的 hex 字符串（兼容 //TXDEF# 和 740404 前缀）。
- 参数：
  - `hex`：encryptText 输出的 hex 字符串
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：string 解密后的原文；失败返回 error 值
- 示例：
  - `decryptText(encryptText("hi", "pw"), "pw")   // "hi"`
- 常见错误：
  - hex 解码失败或解密失败返回 error

### `decryptTextByTXDEE`

- 签名：`decryptTextByTXDEE(hex[, code]) -> string`
- 简介：解密 encryptTextByTXDEE 生成的 hex 字符串（兼容 740404 前缀）。
- 参数：
  - `hex`：encryptTextByTXDEE 输出的 hex 字符串
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：string 解密后的原文；失败返回 error 值
- 示例：
  - `decryptTextByTXDEE(encryptTextByTXDEE("hi", "pw"), "pw")   // "hi"`
- 常见错误：
  - hex 解码失败返回 error
  - 解密失败（密码错误/数据损坏）返回 error

### `decryptTextByTXDEM`

- 签名：`decryptTextByTXDEM(hex[, codeA]) -> string|error`
- 简介：解密 encryptTextByTXDEM 的 hex 字符串（兼容 //TXDEM# 和 740405 前缀）。
- 参数：
  - `hex`：encryptTextByTXDEM 输出的 hex 字符串
  - `codeA`：可选。密码 A 或 B，省略时默认 "topxeq"
- 返回：string 解密后的原文；失败返回 error 值
- 示例：
  - `decryptTextByTXDEM(encryptTextByTXDEM("hi", "pw"), "pw")   // "hi"`
- 常见错误：
  - hex 解码失败返回 error
  - 密码不正确或数据损坏返回 error

### `decryptTextByTXTE`

- 签名：`decryptTextByTXTE(hex[, code]) -> string`
- 简介：用 TXTE 算法解密文本（输入 hex 字符串，需与加密时同一密码）。
- 参数：
  - `hex`：encryptTextByTXTE 输出的 hex 字符串
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：string 解密后的原文（空输入或 hex 解码失败返回空串）
- 示例：
  - `decryptTextByTXTE(encryptTextByTXTE("hi"))     // "hi"`
- 常见错误：
  - 密码不匹配时返回乱码（不报错）

### `encryptBytes`

- 签名：`encryptBytes(data[, code[, "-addHead"]]) -> bytes`
- 简介：encryptData 的别名：用 TXDEF 算法加密数据。
- 参数：
  - `data`：要加密的数据（string/bytes/byteArray）
  - `code`：可选。密码字符串
  - `-addHead`：可选。字符串 "-addHead"，添加 //TXDEF# 头
- 返回：bytes 加密后的数据
- 示例：
  - `var b = encryptBytes("data", "pw")`

### `encryptData`

- 签名：`encryptData(data[, code[, "-addHead"]]) -> bytes`
- 简介：用 TXDEF 默认算法加密数据（key 派生盐长度）。可选添加 //TXDEF# 头。
- 参数：
  - `data`：要加密的数据（string/bytes/byteArray）
  - `code`：可选。密码字符串，省略时默认 "topxeq"
  - `-addHead`：可选。字符串字面量 "-addHead"，添加 //TXDEF# 头
- 返回：bytes 加密后的数据
- 示例：
  - `var b = encryptData("data")`
  - `var b2 = encryptData("data", "pw", "-addHead")   // 带 //TXDEF# 头`
- 常见错误：
  - 参数类型应为 string/bytes/byteArray

### `encryptDataByTXDEE`

- 签名：`encryptDataByTXDEE(data[, code]) -> bytes`
- 简介：用 TXDEE 算法加密数据（4 字节随机盐帧混淆）。返回二进制 bytes。
- 参数：
  - `data`：要加密的数据（string/bytes/byteArray）
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：bytes 加密后的二进制数据（长度 = 原长度 + 4）
- 示例：
  - `var b = encryptDataByTXDEE("data")`
  - `var b2 = encryptDataByTXDEE("data", "pw")`
- 常见错误：
  - 参数类型应为 string/bytes/byteArray

### `encryptDataByTXDEM`

- 签名：`encryptDataByTXDEM(data[, codeA[, codeB]]) -> bytes`
- 简介：用 TXDEM 双密码流密码加密数据（任一密码正确均可解密）。
- 参数：
  - `data`：要加密的数据（string/bytes/byteArray）
  - `codeA`：可选。密码 A，省略时默认 "topxeq"
  - `codeB`：可选。密码 B，省略时默认 "txdem"
- 返回：bytes 加密后的数据（含双盐槽 + 校验和 + 密文）
- 示例：
  - `var b = encryptDataByTXDEM("data", "pw1", "pw2")`
- 常见错误：
  - 参数类型应为 string/bytes/byteArray

### `encryptStr`

- 签名：`encryptStr(text[, code]) -> string`
- 简介：encryptText 的别名：用 TXDEF 加密文本输出 hex 字符串。
- 参数：
  - `text`：要加密的字符串
  - `code`：可选。密码字符串
- 返回：string hex 编码的密文
- 示例：
  - `encryptStr("hello", "pw")`

### `encryptText`

- 签名：`encryptText(text[, code]) -> string`
- 简介：用 TXDEF 加密文本，输出 hex 字符串（不带 //TXDEF# 头）。
- 参数：
  - `text`：要加密的字符串
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：string hex 编码的密文
- 示例：
  - `var s = encryptText("hello", "pw")`

### `encryptTextByTXDEE`

- 签名：`encryptTextByTXDEE(text[, code]) -> string`
- 简介：用 TXDEE 加密文本，输出 hex 字符串（对 TXDEE 二进制结果做 hex 编码）。
- 参数：
  - `text`：要加密的字符串
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：string hex 编码的密文
- 示例：
  - `var s = encryptTextByTXDEE("hello", "pw")`

### `encryptTextByTXDEM`

- 签名：`encryptTextByTXDEM(text[, codeA[, codeB]]) -> string`
- 简介：用 TXDEM 双密码流密码加密文本，输出 hex 字符串。
- 参数：
  - `text`：要加密的字符串
  - `codeA`：可选。密码 A，省略时默认 "topxeq"
  - `codeB`：可选。密码 B，省略时默认 "txdem"
- 返回：string hex 编码的密文
- 示例：
  - `var s = encryptTextByTXDEM("hello", "pw1", "pw2")`

### `encryptTextByTXTE`

- 签名：`encryptTextByTXTE(text[, code]) -> string`
- 简介：用 TXTE 算法加密文本（加法混淆 + hex 编码输出）。
- 参数：
  - `text`：要加密的字符串
  - `code`：可选。密码字符串，省略时默认 "topxeq"
- 返回：string 加密后的 hex 字符串（空输入返回空串）
- 示例：
  - `var s = encryptTextByTXTE("hello")            // 默认密码`
  - `var s2 = encryptTextByTXTE("hello", "mykey")    // 指定密码`

### `genJwtToken`

- 签名：`genJwtToken(payload, key, alg?) -> string`
- 简介：生成 JWT 令牌（header.payload.signature），默认 HS256，可选 RS256。
- 参数：
  - `payload`：map/object：自定义声明数据（自动 JSON 编码）
  - `key`：HS256：对称密钥字符串；RS256：PEM 格式 RSA 私钥字符串
  - `alg`：可选 "HS256"(默认) 或 "RS256"
- 返回：string：标准 JWT 令牌（base64url 无填充编码）
- 示例：
  - `genJwtToken({user: "alice"}, "secret")              → HS256 令牌`
  - `genJwtToken({user: "alice"}, privateKeyPem, "RS256") → RS256 令牌`
- 常见错误：
  - payload 必须是 map/object
  - alg 仅支持 HS256 或 RS256
  - RS256 私钥须为合法 PEM（PKCS#8 或 PKCS#1 格式）

### `isEncrypted`

- 签名：`isEncrypted(v) -> bool`
- 简介：检测值是否为已加密格式：string 检查 //TXDEF# 或 //TXDEM# 前缀，bytes 检查 magic bytes。
- 参数：
  - `v`：string 或 bytes
- 返回：bool：识别为加密格式返回 true
- 示例：
  - `isEncrypted("//TXDEF#xxxx")        // true`
  - `isEncrypted(encryptData("x"))        // 视情况`
- 常见错误：
  - 非 string/bytes 类型返回 false

### `parseJwtToken`

- 签名：`parseJwtToken(token, key) -> map`
- 简介：解析并验证 JWT 令牌（自动识别 HS256/RS256 算法），成功返回 payload map。
- 参数：
  - `token`：string：标准 JWT 令牌（3 段 header.payload.signature）
  - `key`：HS256：对称密钥字符串；RS256：PEM 格式 RSA 公钥字符串
- 返回：map：令牌的 payload 声明（已验证签名）
- 示例：
  - `tok := genJwtToken({user: "alice"}, "secret")`
  - `parseJwtToken(tok, "secret")            → {user: "alice"}（HS256）`
  - `parseJwtToken(tok, publicKeyPem)         → payload（RS256 用公钥验证）`
- 常见错误：
  - 令牌必须为 3 段（用 . 分隔）
  - 算法由 header 自动识别，须为 HS256 或 RS256
  - 签名验证失败（密钥错误/被篡改）返回 error

### `rsaEncrypt`

- 签名：`rsaEncrypt(plaintext, hexModulus, hexExponent) -> string`
- 简介：PKCS#1 v1.5 填充的 RSA 加密，输出定宽（密钥字节数）小写 hex。
- 参数：
  - `plaintext`：明文字符串（UTF-8 字节，长度不得超过 密钥字节数-11）
  - `hexModulus`：模数 n 的 hex 字符串
  - `hexExponent`：指数 e 的 hex 字符串（须为不超过 u64 的整数，常见为 10001）
- 返回：string 密文的 hex 编码（定宽，前导零保留）
- 示例：
  - `rsaEncrypt(password, moduleHex, "10001")`
- 常见错误：
  - hex 含非法字符报错
  - 指数超过 u64 范围报错（标准公钥指数 65537 合法）
  - 明文过长（超过 密钥字节数-11）报错

### `rsaEncryptRaw`

- 签名：`rsaEncryptRaw(plaintext, hexModulus, hexExponent) -> string`
- 简介：无填充原始 RSA 加密：明文字节反转后作大整数算 m^e mod n，输出最小宽度小写 hex。
- 参数：
  - `plaintext`：明文字符串（UTF-8 字节参与运算）
  - `hexModulus`：模数 n 的 hex 字符串（奇数长度自动左补 0）
  - `hexExponent`：指数 e 的 hex 字符串
- 返回：string 密文的 hex 编码（无前导零，最小宽度）
- 示例：
  - `rsaEncryptRaw(password, moduleHex, "10001")`
- 常见错误：
  - hex 含非法字符报错（仅允许 0-9a-fA-F）
  - 空模数/空指数报错；明文反转后必须小于模数

### `sm4Decrypt`

- 签名：`sm4Decrypt(data, key) -> bytes`
- 简介：国密 SM4-CBC 解密（输入 sm4Encrypt 的 [IV][密文] 输出）。
- 参数：
  - `data`：bytes/byteArray：sm4Encrypt 的输出（[16 字节 IV][密文]）
  - `key`：string/bytes：密钥（须与加密时相同）
- 返回：bytes：解密后的明文；失败返回 error
- 示例：
  - `sm4Decrypt(sm4Encrypt("hello", key), key) → bytes("hello")`
- 常见错误：
  - 数据短于 16 字节（IV）或非 16 倍数返回 error
  - 密钥错误或填充损坏返回 error（不 panic）

### `sm4DecryptStr`

- 签名：`sm4DecryptStr(base64, key) -> string`
- 简介：便捷字符串解密：输入 sm4EncryptStr 产生的 base64，返回 UTF-8 字符串。
- 参数：
  - `base64`：string：sm4EncryptStr 的输出（base64）
  - `key`：string/bytes：密钥（须与加密时相同）
- 返回：string：解密后的明文（按 UTF-8 解释）；失败返回 error
- 示例：
  - `sm4DecryptStr(sm4EncryptStr("hello", key), key) → "hello"`
- 常见错误：
  - base64 解码后数据短于 16 字节返回 error
  - 密钥错误或填充损坏返回 error（不 panic）

### `sm4Encrypt`

- 签名：`sm4Encrypt(data, key) -> bytes`
- 简介：国密 SM4-CBC 加密（GB/T 32907-2016，PKCS7 填充），返回 [16 字节 IV][密文] 的 bytes。
- 参数：
  - `data`：string/bytes/byteArray：明文
  - `key`：string/bytes：密钥，固定 16 字节（SM4 密钥 128 位）
- 返回：bytes：[16 字节随机 IV][密文]，每次调用 IV 不同
- 示例：
  - `ct := sm4Encrypt("hello", "0123456789abcdef")  → 32 字节 bytes（16 IV + 16 密文）`
- 常见错误：
  - key 长度必须为 16 字节
  - 输出含随机 IV，每次结果不同；用 sm4Decrypt 解密

### `sm4EncryptStr`

- 签名：`sm4EncryptStr(text, key) -> string`
- 简介：便捷字符串加密：UTF-8 字节 SM4 加密后输出 base64 字符串。
- 参数：
  - `text`：string：明文（UTF-8 编码）
  - `key`：string/bytes：密钥，固定 16 字节
- 返回：string：标准 base64（含 IV），可直接传输/存储
- 示例：
  - `ct := sm4EncryptStr("hello", "0123456789abcdef")  → base64 字符串`
- 常见错误：
  - 等价于 base64(sm4Encrypt(text, key))

## csv（6 个）

### `csvEncode`

- 签名：`csvEncode(rows[, delim]) -> string`
- 简介：将二维数组编码为 CSV 文本（UTF-8 无 BOM、LF 行尾，自动转义）。
- 参数：
  - `rows`：二维数组（每个元素自动 toStr 转换）
  - `delim`：可选。分隔符，默认逗号；单个字符，如 "|"、"\t"
- 返回：string CSV 文本，每行以 \n 结束
- 示例：
  - `var s = csvEncode([["name","age"], ["Alice",30]])  // "name,age\nAlice,30\n"`
  - `writeFile("out.csv", "\uFEFF" + csvEncode(rows))  // 写带 BOM 的 CSV（Excel 友好）`
- 常见错误：
  - rows 不是二维数组、delim 非法返回 error

### `csvRead`

- 签名：`readCsv(path[, delim]) -> array`
- 简介：readCsv 的别名。
- 参数：
  - `path`：CSV 文件路径
  - `delim`：可选。分隔符
- 返回：array
- 示例：
  - `csvRead("data.csv")`

### `csvWrite`

- 签名：`writeCsv(data, path[, delim]) -> undefined`
- 简介：writeCsv 的别名。
- 参数：
  - `data`：二维数组
  - `path`：输出路径
  - `delim`：可选。分隔符
- 返回：undefined
- 示例：
  - `csvWrite(rows, "out.csv")`

### `readCsv`

- 签名：`readCsv(path[, delim]) -> array`
- 简介：从文件读取 CSV 为二维数组（全字符串），自动剥离 UTF-8 BOM。
- 参数：
  - `path`：CSV 文件路径
  - `delim`：可选。分隔符，默认逗号；单个字符，如 "|"、"\t"
- 返回：array 行列数据
- 示例：
  - `var rows = readCsv("data.csv")`
  - `var rows = readCsv("data.tsv", "\t")`
- 常见错误：
  - 文件不存在或编码非 UTF-8 返回 error
  - delim 不是单个字符或为引号/换行返回 error

### `readCsvFromStr`

- 签名：`readCsvFromStr(s[, delim]) -> array`
- 简介：从字符串读取 CSV，自动剥离行首 UTF-8 BOM。
- 参数：
  - `s`：CSV 格式字符串
  - `delim`：可选。分隔符，默认逗号；单个字符
- 返回：array
- 示例：
  - `var rows = readCsvFromStr("a,b\n1,2\n")`
- 常见错误：
  - delim 不是单个字符或为引号/换行返回 error

### `writeCsv`

- 签名：`writeCsv(data, path[, delim]) -> undefined`
- 简介：将二维数组写入 CSV 文件（UTF-8 无 BOM、LF 行尾，自动转义）。
- 参数：
  - `data`：二维数组（每个元素自动 toStr 转换）
  - `path`：输出路径
  - `delim`：可选。分隔符，默认逗号；单个字符，如 "|"、"\t"
- 返回：undefined
- 示例：
  - `writeCsv(rows, "out.csv")`
  - `writeCsv(rows, "out.tsv", "\t")`
- 常见错误：
  - data 不是二维数组、path 类型错误、delim 非法返回 error

## datetime（19 个）

### `clock`

- 签名：`clock() -> int`
- 简介：返回程序运行时间（微秒，int，单调时钟）。计算耗时请用两次调用差值。
- 返回：int 自解释器启动以来的微秒数

### `datetime`

- 签名：`datetime(millis) | datetime(y,m,d[,tz]) | datetime(y,m,d,H,M,S[,tz]) -> datetime`
- 简介：构造 datetime。1 参=毫秒(UTC)；3/4 参=年月日[+时区]；6/7 参=年月日时分秒[+时区]。
- 参数：
  - `millis | y`：1参为 Unix 毫秒；否则为年份（如 2026）
  - `m`：月份 1-12（多参形式）
  - `d`：日 1-31
  - `H/M/S`：时分秒，可选（6/7 参形式）
  - `tz`：最后可选参数：时区偏移分钟（int）
- 返回：datetime；非法日期返回 error
- 示例：
  - `datetime(1720000000000)`
  - `datetime(2026, 7, 14)`
  - `datetime(2026, 7, 14, 12, 30, 0)`
- 常见错误：
  - 参数数须为 1/3/4/6/7，其他数量报错
  - 非法日期（如 2 月 30 日、月份越界）返回 error
  - 年份须在 1-9999，越界返回 error

### `datetimeFromMillis`

- 签名：`datetimeFromMillis(ms) -> datetime`
- 简介：将 Unix 毫秒时间戳转为 datetime（本地时区，与 nowDT 一致；适合文件时间等转本地墙钟显示）。
- 参数：
  - `ms`：Unix 毫秒时间戳（int）
- 返回：datetime 本地时间；需要 UTC 表示时用 datetime(ms)
- 示例：
  - `datetimeFromMillis(now())`
  - `formatTime(datetimeFromMillis(getFileInfo("a.txt").modified * 1000), "20060102150405")`

### `datetimeParse`

- 签名：`datetimeParse(s, fmt) -> datetime`
- 简介：按 Go 风格参考时间格式 fmt 解析字符串为 datetime。
- 参数：
  - `s`：待解析的时间字符串
  - `fmt`：Go 风格布局，如 "2006-01-02 15:04:05"
- 返回：datetime；解析失败返回 error
- 示例：
  - `datetimeParse("2026-07-14", "2006-01-02")`
  - `datetimeParse("2026-07-14 12:00:00", "2006-01-02 15:04:05")`
- 常见错误：
  - 参数顺序：s 在前，fmt 在后（最易搞反）
  - fmt 用 Go 风格参考时间（2006/01/02/15/04/05），不是 strftime 的 %Y%m%d
  - 字符串与格式不匹配返回 error

### `dtAddDays`

- 签名：`dtAddDays(dt, n) -> datetime`
- 简介：datetime 加 n 天，返回新 datetime（原对象不可变）。
- 参数：
  - `dt`：datetime 对象
  - `n`：天数（int，可为负）
- 返回：datetime 加减天数后的新对象
- 示例：
  - `dtAddDays(nowDT(), 7)   // 一周后`
  - `dtAddDays(dt, -1)       // 昨天`
- 常见错误：
  - 第 1 个参数须为 datetime，类型不匹配报错

### `dtAddMillis`

- 签名：`dtAddMillis(dt, n) -> datetime`
- 简介：日期时间加 n 毫秒。
- 参数：
  - `dt`：datetime
  - `n`：毫秒数
- 返回：datetime

### `dtAddSeconds`

- 签名：`dtAddSeconds(dt, n) -> datetime`
- 简介：日期时间加 n 秒。
- 参数：
  - `dt`：datetime
  - `n`：秒数
- 返回：datetime

### `dtFormat`

- 签名：`dtFormat(dt, fmt) -> string`
- 简介：按 Go 风格参考时间格式 fmt 格式化 datetime 为字符串。
- 参数：
  - `dt`：datetime 对象
  - `fmt`：Go 风格布局，如 "2006-01-02 15:04:05"
- 返回：string 格式化结果
- 示例：
  - `dtFormat(nowDT(), "2006-01-02")     → "2026-07-14"`
  - `dtFormat(dt, "15:04:05")           → "12:30:00"`
- 常见错误：
  - 参数顺序：dt 在前，fmt 在后
  - 第 1 个参数须为 datetime；fmt 为 Go 风格布局（非 strftime）

### `dtToMillis`

- 签名：`dtToMillis(dt) -> int`
- 简介：datetime 转 Unix 毫秒时间戳。
- 参数：
  - `dt`：datetime
- 返回：int

### `formatTime`

- 签名：`formatTime(dt, fmt) -> string`
- 简介：格式化 datetime 为字符串（dtFormat 的语义化别名，行为完全相同）。
- 参数：
  - `dt`：datetime 对象
  - `fmt`：Go 风格布局，如 "2006-01-02 15:04:05"
- 返回：string 格式化结果
- 示例：
  - `formatTime(nowDT(), "2006-01-02 15:04:05")`
- 常见错误：
  - 与 dtFormat 完全等价；fmt 用 Go 风格参考时间

### `getNowStr`

- 签名：`getNowStr([fmt]) -> string`
- 简介：返回当前本地时间格式化字符串（按系统时区换算；需要 UTC 表示时用 dtFormat(datetime(now()), fmt)）。
- 参数：
  - `fmt`：可选。Go 风格格式
- 返回：string 当前本地时间的格式化结果
- 示例：
  - `getNowStr()                  → "2026-09-02 15:47:20"`
  - `getNowStr("2006-01-02")     → "2026-09-02"`

### `getNowTimeStamp`

- 签名：`getNowTimeStamp() -> int`
- 简介：返回当前 Unix 时间戳（秒）。需要毫秒请用 now()。
- 返回：int 秒级 Unix 时间戳（等效 nowSec()）

### `isDatetime`

- 签名：`isDatetime(v) -> bool`
- 简介：判断是否为 datetime 类型。
- 参数：
  - `v`：任意值
- 返回：bool

### `now`

- 签名：`now() -> int`
- 简介：返回自 Unix epoch（1970-01-01 UTC）以来的毫秒数。
- 返回：int 当前时间毫秒时间戳
- 示例：
  - `now()   → 1720000000000`
  - `// 计算耗时：var t = now(); ...; println(now() - t)`
- 常见错误：
  - 本函数返回毫秒；需要秒请用 nowSec

### `nowDT`

- 签名：`nowDT() -> datetime`
- 简介：返回当前时间的 datetime 对象（本地时区：Windows 用系统时区 API，Linux/macOS 读 /etc/localtime）。
- 返回：datetime 当前本地时间
- 示例：
  - `var dt = nowDT()`
  - `dtFormat(dt, "2006-01-02 15:04:05")`

### `nowSec`

- 签名：`nowSec() -> int`
- 简介：返回当前 Unix 时间戳（秒）。
- 返回：int

### `runTicker`

- 签名：`runTicker(fn, intervalMs) -> ticker`
- 简介：启动独立线程，每 intervalMs 毫秒调用一次 fn()（首次立即执行），返回 ticker 句柄。
- 参数：
  - `fn`：无参函数（func 定义或内置函数），每周期调用一次
  - `intervalMs`：周期毫秒数（正整数）
- 返回：ticker 句柄（传给 stopTicker 停止）
- 示例：
  - `var t = runTicker(func() { println(now()) }, 1000)`
  - `// 1 秒打印一次时间`
- 常见错误：
  - 第 1 个参数须为 function（func/Builtin），其他类型报错
  - intervalMs 必须为正整数，否则报错
  - 子线程异常静默打印不中断；共享主线程 globals/output

### `stopTicker`

- 签名：`stopTicker(handle) -> undefined`
- 简介：停止 runTicker 启动的周期任务（子线程在当前周期结束后退出，最长 intervalMs）。
- 参数：
  - `handle`：runTicker 返回的 ticker 句柄
- 返回：undefined
- 示例：
  - `var t = runTicker(fn, 1000)`
  - `// ...`
  - `stopTicker(t)   // 停止周期任务`
- 常见错误：
  - 参数须为 runTicker 返回的 ticker 句柄，其他类型报错
  - 幂等：对已停止的 ticker 调用无副作用

### `timeAddDate`

- 签名：`timeAddDate(dt, years, months, days) -> datetime`
- 简介：日期加减年月日。
- 参数：
  - `dt`：datetime
  - `years`：年
  - `months`：月
  - `days`：日
- 返回：datetime

## db（15 个）

### `dbClose`

- 签名：`dbClose(db) -> undefined`
- 简介：关闭数据库连接（连接对象由 GC 自动释放，此函数为显式释放占位）。
- 参数：
  - `db`：dbConnect 返回的连接对象
- 返回：undefined（连接对象的实际关闭由引用计数 / drop 管理）
- 示例：
  - `var db = dbConnect("sqlite3", "test.db")`
  - `dbExec(db, "...")`
  - `dbClose(db)  // 显式标记不再使用`
- 常见错误：
  - 第一个参数不是 db 连接对象
  - 重复关闭不会报错（幂等）

### `dbConnect`

- 签名：`dbConnect(driver, connStr[, autoCommit]) -> dbConn`
- 简介：连接数据库，返回连接对象（连接失败返回 error）。Oracle 默认自动提交，可选第三参数 false 关闭。
- 参数：
  - `driver`：驱动名："sqlite3"/"sqlite"、"mysql"、"postgres"/"postgresql"/"pg"、"mssql"/"sqlserver"、"oracle"
  - `connStr`：连接字符串（格式因驱动而异，见 examples）
  - `autoCommit`：可选。bool，默认 true（每条 DML 执行即提交）；false=显式事务（脚本自行 COMMIT/ROLLBACK）。当前 Oracle 后端支持
- 返回：dbConn 数据库连接对象；失败返回 error 对象（用 isErr 检查）
- 示例：
  - `dbConnect("sqlite3", "test.db")                              // 打开本地 SQLite 文件`
  - `dbConnect("sqlite3", ":memory:")                              // 内存数据库`
  - `dbConnect("mysql", "mysql://user:pass@host:3306/db")         // MySQL`
  - `dbConnect("postgres", "postgresql://user:pass@host:5432/db") // PostgreSQL`
  - `dbConnect("mssql", "mssql://sa:pass@host:1433/db")           // SQL Server`
  - `dbConnect("oracle", "oracle://user:pass@host:1521/ORCL")     // Oracle（默认自动提交）`
  - `dbConnect("oracle", dsn, false)                                // Oracle 显式事务模式（批量导入用）`
- 常见错误：
  - 连接失败：网络不通 / 认证失败 / 数据库不存在（返回 error 而非抛异常）
  - 不支持的 driver 名称（检查拼写）
  - MySQL 密码含特殊字符时连接串解析失败，已自动回退手动解析

### `dbExec`

- 签名：`dbExec(db, sql, params...) -> int`
- 简介：执行非查询 SQL（INSERT/UPDATE/DELETE/CREATE/DROP 等），返回影响行数。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：SQL 语句，参数用 ? 占位（PostgreSQL 也用 ?，内部自动转 $N）
  - `params...`：可选的可变参数，按顺序绑定到 SQL 的 ? 占位符
- 返回：int 影响的行数；执行失败返回 error
- 示例：
  - `dbExec(db, "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")  // → 0`
  - `dbExec(db, "INSERT INTO users (id, name) VALUES (?, ?)", 1, "Alice") // → 1`
  - `dbExec(db, "UPDATE users SET name = ? WHERE id = ?", "Bob", 1)        // → 1`
- 常见错误：
  - 第一个参数不是 db 连接对象（未用 dbConnect 创建 / 参数顺序错误）
  - SQL 执行失败：语法错误 / 表不存在 / 约束冲突
  - 占位符数量与参数不匹配

### `dbExecBatch`

- 签名：`dbExecBatch(db, sql, rows2D) -> int`
- 简介：批量执行同一 DML 语句（数组绑定，一批一次网络往返），返回总影响行数。提交行为随连接的 autoCommit 设置。当前仅 Oracle 后端支持。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：DML 语句，占位符与 dbExec 相同（? 自动转 :N）
  - `rows2D`：二维数组，每个内层元素是一行的绑定参数值列表
- 返回：int 总影响行数；失败返回 error 对象
- 示例：
  - `n := dbExecBatch(db, "INSERT INTO t VALUES (?, ?)", [[1, "a"], [2, "b"]])`
  - `dbExecBatch(db, "UPDATE t SET note = ? WHERE id = ?", [["x", 1]])`
- 常见错误：
  - rows2D 不是二维数组返回 error
  - SQL 执行失败返回 error（含原始数据库错误信息）
  - 当前仅 Oracle 后端支持；其他后端返回说明性 error（按需再补）
  - 提交行为随连接的 autoCommit 字段（dbConnect 第三参数初始值，dbSetAutoCommit 可运行时切换）

### `dbQuery`

- 签名：`dbQuery(db, sql, params...) -> array<map>`
- 简介：执行查询，返回行数组（每行为列名→值的 map）。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：SELECT 查询语句，参数用 ? 占位
  - `params...`：可选的可变参数，按顺序绑定到 ? 占位符
- 返回：array<map>：每行为 {列名: 值}；NULL 列值为 undefined；失败返回 error
- 示例：
  - `dbQuery(db, "SELECT id, name FROM users")                          // → [{"id":1,"name":"Alice"}, ...]`
  - `dbQuery(db, "SELECT * FROM users WHERE age > ?", 18)               // 带参数`
  - `dbQuery(db, "SELECT id, name FROM users")[0]["name"]              // 取第一行 name`
- 常见错误：
  - 第一个参数不是 db 连接对象
  - SQL 查询失败：语法错误 / 表或列不存在
  - NULL 值统一转为 undefined（而非 nil/null 字符串）

### `dbQueryCount`

- 签名：`dbQueryCount(db, sql, params...) -> int`
- 简介：查询单值并转为 int（典型用于 COUNT），空结果返回 0。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：返回单个数值的查询，如 SELECT COUNT(*) FROM ...
  - `params...`：可选的可变参数
- 返回：int：取第一行第一列的值转为整数；空结果返回 0
- 示例：
  - `dbQueryCount(db, "SELECT COUNT(*) FROM users WHERE age > ?", 18)  // → 3`
  - `dbQueryCount(db, "SELECT COUNT(*) FROM orders")                  // → 1520`
- 常见错误：
  - 第一个参数不是 db 连接对象
  - 结果非数值时会回退为 0（无法解析的字符串）
  - SQL 查询失败返回 error

### `dbQueryFloat`

- 签名：`dbQueryFloat(db, sql, params...) -> float`
- 简介：查询单值并转为 float（典型用于 AVG/SUM），空结果返回 0.0。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：返回单个数值的查询，如 SELECT AVG(score) FROM ...
  - `params...`：可选的可变参数
- 返回：float：取第一行第一列的值转为浮点数；空结果返回 0.0
- 示例：
  - `dbQueryFloat(db, "SELECT AVG(score) FROM students WHERE class = ?", "A")  // → 87.5`
  - `dbQueryFloat(db, "SELECT SUM(amount) FROM orders")                          // → 12345.67`
- 常见错误：
  - 第一个参数不是 db 连接对象
  - 整数结果会自动转为浮点数（如 5 → 5.0）
  - SQL 查询失败返回 error

### `dbQueryMap`

- 签名：`dbQueryMap(db, keyColumn, sql, params...) -> map`
- 简介：查询并按 keyColumn 的值组织成 map（一对一，后行覆盖前行）。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `keyColumn`：用作 key 的列名（字符串）
  - `sql`：SELECT 查询语句，参数用 ? 占位
  - `params...`：可选的可变参数（绑定到 sql 的占位符）
- 返回：map：{keyValue: rowMap, ...}，每行为完整记录；keyColumn 重复时后者覆盖前者
- 示例：
  - `dbQueryMap(db, "id", "SELECT id, name, age FROM users")`
  - `// → {"1": {"id":1,"name":"Alice","age":30}, "2": {"id":2,"name":"Bob","age":25}}`
  - `dbQueryMap(db, "dept", "SELECT dept, name FROM emp WHERE dept=?", "销售")["销售"]`
- 常见错误：
  - 参数顺序：dbQueryMap(db, keyColumn, sql, ...) — keyColumn 在 sql 之前
  - keyColumn 必须在 SELECT 列表中，否则对应行被跳过
  - 第一个参数不是 db 连接对象

### `dbQueryMapArray`

- 签名：`dbQueryMapArray(db, keyColumn, sql, params...) -> map<string, array>`
- 简介：查询并按 keyColumn 分组组织成 map（一对多，值为行数组）。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `keyColumn`：用作分组 key 的列名
  - `sql`：SELECT 查询语句，参数用 ? 占位
  - `params...`：可选的可变参数
- 返回：map<string, array>：{keyValue: [row1, row2, ...], ...}
- 示例：
  - `dbQueryMapArray(db, "dept", "SELECT dept, name FROM employees")`
  - `// → {"销售部": [{"dept":"销售部","name":"张三"}], "技术部": [...]}`
- 常见错误：
  - 与 dbQueryMap 区别：MapArray 值为数组（一对多），Map 值为单个记录（一对一）
  - keyColumn 必须在 SELECT 列表中，否则对应行被跳过
  - 第一个参数不是 db 连接对象

### `dbQueryOrdered`

- 签名：`dbQueryOrdered(db, sql, orderByCol, order, params...) -> array<map>`
- 简介：查询并追加 ORDER BY 子句（返回与 dbQuery 相同的 map 数组）。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：SELECT 查询语句（不带 ORDER BY）
  - `orderByCol`：排序依据的列名（自动双引号包裹，内部 " 转义防注入）
  - `order`：排序方向："ASC" 升序 或 "DESC" 降序（不区分大小写）
  - `params...`：可选的可变参数（绑定到 sql 占位符）
- 返回：array<map>：与 dbQuery 同格式；order 非法时返回 error
- 示例：
  - `dbQueryOrdered(db, "SELECT id, name FROM users", "name", "ASC")  // 按名升序`
  - `dbQueryOrdered(db, "SELECT * FROM orders", "created_at", "DESC") // 按时间倒序`
  - `dbQueryOrdered(db, "SELECT * FROM t WHERE dept=?", "id", "ASC", "dev")  // 带参数`
- 常见错误：
  - 参数顺序：dbQueryOrdered(db, sql, orderByCol, order, ...) — 注意 order 在 orderByCol 之后
  - order 必须为 'ASC' 或 'DESC'（不区分大小写），其他值返回 error
  - orderByCol 含特殊字符会被双引号包裹并转义内部双引号

### `dbQueryRecs`

- 签名：`dbQueryRecs(db, sql, params...) -> array<array>`
- 简介：执行查询，返回二维数组（第一行为列名，后续为数据行）。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：SELECT 查询语句，参数用 ? 占位
  - `params...`：可选的可变参数
- 返回：array<array>：第一行是列名数组，其后每行是按列序的值数组；空结果仅返回 []
- 示例：
  - `dbQueryRecs(db, "SELECT id, name FROM users")  // → [["id","name"],[1,"Alice"],[2,"Bob"]]`
  - `dbQueryRecs(db, "SELECT * FROM t WHERE id=?", 5)[1][0]  // 取第一数据行的第一列`
- 常见错误：
  - 与 dbQuery 的区别：dbQuery 返回 map 数组，dbQueryRecs 返回二维数组（首行列名）
  - 第一个参数不是 db 连接对象
  - SQL 查询失败

### `dbQueryStr`

- 签名：`dbQueryString(db, sql, params...) -> string`
- 简介：查询单值并转为字符串（典型用于取名称），空结果返回空串。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：返回单个值的查询，如 SELECT name FROM ... WHERE id = ?
  - `params...`：可选的可变参数
- 返回：string：取第一行第一列的值转为字符串；空结果返回空串 ""
- 示例：
  - `dbQueryString(db, "SELECT name FROM users WHERE id = ?", 1)  // → "Alice"`
  - `dbQueryString(db, "SELECT title FROM articles LIMIT 1")      // → "Hello"`
- 常见错误：
  - dbQueryStr 是 dbQueryString 的兼容别名（同一函数）
  - 第一个参数不是 db 连接对象
  - NULL 值会转为 "undefined" 字符串，空结果返回空串

### `dbQueryString`

- 签名：`dbQueryString(db, sql, params...) -> string`
- 简介：查询单值并转为字符串（典型用于取名称），空结果返回空串。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `sql`：返回单个值的查询，如 SELECT name FROM ... WHERE id = ?
  - `params...`：可选的可变参数
- 返回：string：取第一行第一列的值转为字符串；空结果返回空串 ""
- 示例：
  - `dbQueryString(db, "SELECT name FROM users WHERE id = ?", 1)  // → "Alice"`
  - `dbQueryString(db, "SELECT title FROM articles LIMIT 1")      // → "Hello"`
- 常见错误：
  - dbQueryStr 是 dbQueryString 的兼容别名（同一函数）
  - 第一个参数不是 db 连接对象
  - NULL 值会转为 "undefined" 字符串，空结果返回空串

### `dbSetAutoCommit`

- 签名：`dbSetAutoCommit(db[, autoCommit]) -> bool`
- 简介：读取或切换连接的自动提交标志（连接级字段，当前仅 Oracle 后端支持）。
- 参数：
  - `db`：dbConnect 返回的连接对象
  - `autoCommit`：可选。bool：true=后续每条 DML 执行即提交（默认）；false=显式事务（脚本自行 COMMIT/ROLLBACK）。省略则只读当前值
- 返回：bool 切换后的（或当前的）自动提交标志值
- 示例：
  - `dbSetAutoCommit(db, false)   // 切到显式事务，返回 false`
  - `dbSetAutoCommit(db, true)    // 切回自动提交`
  - `dbSetAutoCommit(db)          // 只读当前值`
- 常见错误：
  - 第二参数不是 bool 返回 error
  - 非 Oracle 后端返回说明性 error（这些后端恒自动提交）
  - 注意：切换只影响后续语句，不提交也不回滚切换前未提交的数据

### `formatSqlValue`

- 签名：`formatSqlValue(v) -> string`
- 简介：将 Sflang 值转为 SQL 字面量字符串（用于手工拼接 SQL）。
- 参数：
  - `v`：要格式化的值：int/byte/float/bigint 直接转数字串，string 单引号包裹并转义，bool 转 TRUE/FALSE，undefined 转 NULL
- 返回：string：可直接拼入 SQL 的字面量（如 42、3.14、'O''Brien'、TRUE、NULL）
- 示例：
  - `formatSqlValue(42)        // → "42"`
  - `formatSqlValue(3.14)      // → "3.14"`
  - `formatSqlValue("a'b")     // → "'a''b'"（内部 ' 转义为 ''）`
  - `formatSqlValue(true)      // → "TRUE"`
  - `formatSqlValue(undefined) // → "NULL"`
- 常见错误：
  - 直接拼接 SQL 字面量存在 SQL 注入风险，生产环境推荐用 dbExec/dbQuery 的参数化查询
  - string 内部单引号自动转义为两个单引号（SQL 标准）
  - 主要用于 DDL 生成 / 调试场景

## dialog（4 个）

### `msgBox`

- 签名：`msgBox(text[, title[, type]]) -> int`
- 简介：弹出系统消息框。type 可为 "info"/"warning"/"error"/"question"。返回按钮编号（1=确定, 2=取消）。
- 参数：
  - `text`：消息文本
  - `title`：可选。标题，默认 "提示"
  - `type`：可选。消息类型：info/warning/error/question，默认 info
- 返回：int 按钮编号（1=确定, 2=取消）
- 示例：
  - `msgBox("操作完成")`
  - `if msgBox("确认删除？", "确认", "question") == 1 { ... }`

### `openFileDialog`

- 签名：`openFileDialog([filter[, initialDir]]) -> string|undefined`
- 简介：弹出系统文件打开对话框，返回选定文件路径。取消返回 undefined。
- 参数：
  - `filter`：可选。文件过滤器，如 ".sf,.txt" 或 "Sflang|*.sf|All|*.*"
  - `initialDir`：可选。初始目录路径
- 返回：string 文件路径；用户取消返回 undefined
- 示例：
  - `var path = openFileDialog()`
  - `var path = openFileDialog(".sf,.txt")`
- 常见错误：
  - Linux 下需要 zenity 或 kdialog

### `saveFileDialog`

- 签名：`saveFileDialog([defaultName[, initialDir]]) -> string|undefined`
- 简介：弹出系统文件保存对话框，返回选定保存路径。取消返回 undefined。
- 参数：
  - `defaultName`：可选。默认文件名
  - `initialDir`：可选。初始目录路径
- 返回：string 保存路径；用户取消返回 undefined
- 示例：
  - `var path = saveFileDialog("untitled.sf")`
- 常见错误：
  - Linux 下需要 zenity 或 kdialog

### `selectFolder`

- 签名：`selectFolder([initialDir]) -> string|undefined`
- 简介：弹出系统目录选择对话框，返回选定目录路径。取消返回 undefined。
- 参数：
  - `initialDir`：可选。初始目录路径
- 返回：string 目录路径；用户取消返回 undefined
- 示例：
  - `var dir = selectFolder()`
- 常见错误：
  - Linux 下需要 zenity 或 kdialog

## docx（3 个）

### `docxGetPlaceholders`

- 签名：`docxGetPlaceholders(path_or_bytes) -> array<string>`
- 简介：提取 docx 中花括号包裹的占位符（如 {name}、{{name}}，去重）。
- 参数：
  - `path_or_bytes`：docx 文件路径（string）或文件字节（bytes）
- 返回：array<string>：占位符列表（去重，保留 {name} 形式）；失败返回 error
- 示例：
  - `var phs = docxGetPlaceholders("./template.docx")  // → ["{name}", "{date}", "{company}"]`
  - `var phs = docxGetPlaceholders(fileReadBytes("./tpl.docx"))`
  - `for (var ph in phs) { println(ph) }  // 遍历所有占位符`
- 常见错误：
  - 占位符格式：花括号 {xxx} 包裹的文本（含 {{xxx}}）
  - 自动去重；过滤含 < > 的花括号文本（避免 XML 残留误判）
  - 读取文件 / docx 解压失败返回 error
  - 常与 docxReplace 配合：先提取占位符，再批量替换填充

### `docxReplace`

- 签名：`docxReplace(bytes, [old1, new1, old2, new2, ...]) -> bytes`
- 简介：批量替换 docx 中的文本（模板填充），返回新的 docx bytes。
- 参数：
  - `bytes`：原始 docx 文件字节（bytes）
  - `pairs`：扁平数组：[旧值1, 新值1, 旧值2, 新值2, ...]（两两配对）
- 返回：bytes：替换后的新 docx 字节；失败返回 error
- 示例：
  - `var tpl = fileReadBytes("./template.docx")`
  - `var out = docxReplace(tpl, ["{name}", "张三", "{date}", "2024-01-01"])`
  - `fileWriteBytes("./filled.docx", out)`
- 常见错误：
  - 第一个参数必须为 bytes（不是路径）
  - 第二个参数为数组，两两配对（奇数个时最后一个被忽略）
  - 替换在 <w:t> 文本节点内进行，自动处理 XML 实体编码
  - docx 解压 / 压缩失败返回 error

### `docxToStrs`

- 签名：`docxToStrs(path_or_bytes) -> array<string>`
- 简介：提取 docx 文档的段落文本为字符串数组（每个 <w:p> 段落一项）。
- 参数：
  - `path_or_bytes`：docx 文件路径（string）或文件字节（bytes）
- 返回：array<string>：段落文本数组（按文档顺序，空段落为空串）；失败返回 error
- 示例：
  - `var paras = docxToStrs("./report.docx")           // → ["标题", "第一段内容", ""]`
  - `var paras = docxToStrs(fileReadBytes("./report.docx"))  // 从字节读取`
  - `for (var p in paras) { if (p != "") println(p) }`
- 常见错误：
  - 读取文件失败：路径不存在（仅 path 模式）
  - docx 解压失败：不是有效的 docx 文件（docx 本质是 ZIP）
  - 未找到 word/document.xml：不是标准的 .docx 文件
  - XML 实体（&amp; &lt; 等）自动解码为原始字符

## email（1 个）

### `sendMail`

- 签名：`sendMail(--host=, --port=, --user=, --password=, --from=, --to=, --subject=, --body=, [--html], [--ssl], [--starttls], [--attach=path]) -> undefined`
- 简介：通过 SMTP 发送邮件，支持纯文本/HTML、明文/TLS/STARTTLS、多附件。
- 参数：
  - `--host`：SMTP 服务器地址，如 smtp.example.com
  - `--port`：端口号，默认 587（--ssl 常用 465，--starttls 常用 587）
  - `--user`：SMTP 认证用户名（留空则不认证）
  - `--password`：SMTP 认证密码
  - `--from`：发件人地址
  - `--to`：收件人地址
  - `--subject`：邮件主题，默认 (No Subject)
  - `--body`：邮件正文
  - `--html`：可选开关，正文按 HTML 解析
  - `--ssl`：可选开关，使用隐式 TLS（端口 465）
  - `--starttls`：可选开关，使用 STARTTLS（端口 587）
  - `--attach`：可选附件路径，可重复多个
- 返回：undefined（发送成功），失败返回 error 对象
- 示例：
  - `sendMail("--host=smtp.example.com", "--port=465", "--user=me@x.com", "--password=secret", "--from=me@x.com", "--to=you@y.com", "--subject=Hi", "--body=Hello", "--ssl")  // 发送一封 TLS 邮件`
  - `sendMail("--host=smtp.example.com", "--port=587", "--user=me@x.com", "--password=secret", "--from=me@x.com", "--to=you@y.com", "--subject=Report", "--body=<b>HTML</b>", "--html", "--starttls", "--attach=/tmp/report.pdf")  // 带 HTML 正文与附件的 STARTTLS 邮件`
- 常见错误：
  - sendMail() 至少需要 --host, --from, --to 参数
  - sendMail() 创建 TLS 连接失败 / 创建 STARTTLS 连接失败（可能原因：网络不通）
  - sendMail() 发送失败（可能原因：认证失败、网络问题、收件人地址错误）
  - sendMail() 读取附件 'xxx' 失败：路径不存在或无读权限

## encode（10 个）

### `base64Decode`

- 签名：`base64Decode(s) -> bytes`
- 简介：将标准 base64 字符串解码为 bytes（自动忽略空白，长度须为 4 的倍数）。
- 参数：
  - `s`：base64 字符串，空白字符（空格/换行/制表）自动过滤
- 返回：bytes 解码后的字节；非法输入返回 error
- 示例：
  - `base64Decode("YWJj")          → bytes(b"abc")`
  - `base64Decode(base64Encode(x))  → 原始字节`
- 常见错误：
  - 输入长度（去空白后）须为 4 的倍数，否则报错
  - 含 + / 之外的非法字符会报错；URL-safe 变体请用 base64UrlDecode
  - 填充字符 = 只允许出现在末尾 1-2 位，出现在中间会报错

### `base64Encode`

- 签名：`base64Encode(data) -> string`
- 简介：将字节序列编码为标准 base64 字符串（含 + / = 与 = 填充）。
- 参数：
  - `data`：待编码数据，可为 string/bytes/byteArray（string 取 UTF-8 字节）
- 返回：string base64 编码结果
- 示例：
  - `base64Encode("abc")          → "YWJj"`
  - `base64Encode("a")             → "YQ=="`
- 常见错误：
  - 参数须为 string/bytes/byteArray，其他类型报错
  - 标准 base64 含 + 与 /，不能直接放 URL（用 base64UrlEncode）

### `base64UrlDecode`

- 签名：`base64UrlDecode(s) -> bytes`
- 简介：解码 URL-safe base64 字符串（- _ 与标准变体等价，支持有无 = 填充）。
- 参数：
  - `s`：URL-safe base64 字符串，= 与空白自动忽略
- 返回：bytes 解码后的字节；非法字符返回 error
- 示例：
  - `base64UrlDecode("-_8")        → bytes(b"\xfb\xff")`
  - `base64UrlDecode(base64UrlEncode(x)) → 原始字节`
- 常见错误：
  - 含 - _ 以外的非法字符会报错；标准 base64 含 + /，请用 base64Decode
  - 去除空白/填充后长度除 4 余 1 会报错（可能数据被截断或损坏）

### `base64UrlEncode`

- 签名：`base64UrlEncode(data) -> string`
- 简介：编码为 URL-safe base64（用 - 和 _ 替代 + 和 /，无 = 填充）。
- 参数：
  - `data`：待编码数据，可为 string/bytes/byteArray
- 返回：string URL-safe base64，无填充字符
- 示例：
  - `base64UrlEncode(bytes(b"\xfb\xff")) → "-_8"`
  - `// 适合放进 URL / JWT / 文件名`
- 常见错误：
  - 参数须为 string/bytes/byteArray，其他类型报错
  - 本变体无 = 填充，与标准 base64 不互通

### `htmlDecode`

- 签名：`htmlDecode(s) -> string`
- 简介：将 HTML 实体解码回原字符：支持命名实体（amp/lt/gt/quot/apos/nbsp）与数字实体。
- 参数：
  - `s`：含 HTML 实体的字符串
- 返回：string 解码后的字符串；无法识别的 & 序列原样保留
- 示例：
  - `htmlDecode("&lt;a&gt;")   → "<a>"`
  - `htmlDecode("&#65;")       → "A"`
  - `htmlDecode(htmlEncode(x)) → x`
- 常见错误：
  - 仅识别常见命名实体与数字实体 &#NN; / &#xNN;，其他原样保留

### `htmlEncode`

- 签名：`htmlEncode(s) -> string`
- 简介：将 HTML 特殊字符转义为实体：& < > " ' → &amp; &lt; &gt; &quot; &#39;。
- 参数：
  - `s`：待转义的字符串
- 返回：string 转义后的字符串，可安全嵌入 HTML 文本
- 示例：
  - `htmlEncode("<a>")        → "&lt;a&gt;"`
  - `htmlEncode("a & b")       → "a &amp; b"`
- 常见错误：
  - 仅转义 5 个 HTML 特殊字符，不做全量实体编码
  - 用于防 XSS；属性值场景同样适用（' 转为 &#39;）

### `urlDecode`

- 签名：`urlDecode(s) -> string`
- 简介：RFC 3986 百分号解码：%XX 解码为字节，+ 保持原样不转空格。
- 参数：
  - `s`：待解码字符串
- 返回：string 解码结果（按 UTF-8 容错解码）
- 示例：
  - `urlDecode("a%20b%2Fc") → "a b/c"`
  - `urlDecode(urlEncode(x)) → x（严格往返）`
- 常见错误：
  - + 保持原样（不转空格）；表单编码请用 urlFormDecode
  - 非法 %XX 序列保留原字符，不报错

### `urlEncode`

- 签名：`urlEncode(s) -> string`
- 简介：RFC 3986 百分号编码：空格→%20，+ 保留不编码，仅字母数字与 -_.~ 不编码。
- 参数：
  - `s`：待编码字符串，按字节编码（含 UTF-8 多字节）
- 返回：string 百分号编码结果
- 示例：
  - `urlEncode("a b/c")    → "a%20b%2Fc"`
  - `urlEncode("中文")      → "%E4%B8%AD%E6%96%87"`
- 常见错误：
  - 本函数把空格编为 %20（非 +）；HTML 表单请用 urlFormEncode
  - + 不会被转义（与表单编码不同）

### `urlFormDecode`

- 签名：`urlFormDecode(s) -> string`
- 简介：表单解码：+ 转空格，%XX 解码。与 urlFormEncode 严格往返。
- 参数：
  - `s`：待解码字符串
- 返回：string 解码结果
- 示例：
  - `urlFormDecode("a+b%2Bc") → "a b+c"`
  - `urlFormDecode(urlFormEncode(x)) → x`
- 常见错误：
  - + 解码为空格（与 urlDecode 不同，后者保留 +）

### `urlFormEncode`

- 签名：`urlFormEncode(s) -> string`
- 简介：application/x-www-form-urlencoded 编码：空格→+，+→%2B，其余非保留字符外 %XX。
- 参数：
  - `s`：待编码字符串
- 返回：string 表单编码结果
- 示例：
  - `urlFormEncode("a b+c")  → "a+b%2Bc"`
  - `// 适合 HTML 表单提交 / query string 参数`
- 常见错误：
  - 空格编为 +（非 %20），与 urlEncode 不同
  - + 自身需编码为 %2B，否则解码时会误判

## excel（14 个）

### `excelClose`

- 签名：`excelClose(wb) -> undefined`
- 简介：关闭工作簿（语义占位；rust_xlsxwriter 在 GC 时自动释放）。
- 参数：
  - `wb`：excelNew/excelOpen 返回的工作簿
- 返回：undefined（不做实际清理，仅校验类型）
- 示例：
  - `var wb = excelNew()`
  - `excelSaveAs(wb, "./out.xlsx")`
  - `excelClose(wb)  // 显式标记不再使用`
- 常见错误：
  - 无实际资源需释放（Workbook 在 Drop 时自动回收）
  - 传入非 workbook 类型返回 error（仅做类型校验）

### `excelGetColumnNameByIndex`

- 签名：`excelGetColumnNameByIndex(idx_or_name) -> string|int`
- 简介：列号(0-based)↔列名(A,B,...,Z,AA,...) 双向互转。
- 参数：
  - `idx_or_name`：int 列号（0-based → 列名）或 string 列名（→ 0-based 列号）
- 返回：传 int 返回列名 string（如 "AA"）；传 string 返回列号 int（如 26）
- 示例：
  - `excelGetColumnNameByIndex(0)      // → "A"`
  - `excelGetColumnNameByIndex(25)     // → "Z"`
  - `excelGetColumnNameByIndex(26)     // → "AA"`
  - `excelGetColumnNameByIndex("AB")   // → 27`
  - `excelGetColumnNameByIndex("a")    // → 0（大小写不敏感）`
- 常见错误：
  - 传 int 时列号不能为负
  - 传 string 时应为 A-Z 字母组合（如 "A"/"AB"），否则返回 error
  - 列名大小写不敏感（内部转大写处理）

### `excelGetSheetList`

- 签名：`excelGetSheetList(wb_or_path) -> array<string>`
- 简介：获取 sheet 名称列表（支持工作簿对象或文件路径）。
- 参数：
  - `wb_or_path`：工作簿对象（excelNew 创建）或 Excel 文件路径（string）
- 返回：array<string>：sheet 名称列表（按顺序）
- 示例：
  - `var names = excelGetSheetList("./in.xlsx")  // → ["Sheet1","Sheet2"]`
  - `var wb = excelNew()`
  - `excelNewSheet(wb, "数据")`
  - `excelGetSheetList(wb)  // → ["数据"]`
- 常见错误：
  - 参数应为 workbook 或 string 路径
  - 打开文件失败：路径不存在 / 不是有效 Excel 文件

### `excelNew`

- 签名：`excelNew() -> workbook`
- 简介：创建空 Excel 工作簿（用于写入，rust_xlsxwriter 后端）。
- 返回：workbook 工作簿对象（传给 excelWriteSheet/excelSaveAs 等）
- 示例：
  - `var wb = excelNew()`
  - `excelWriteSheet(wb, 0, [["姓名","分数"],["Alice",90]])`
  - `excelSaveAs(wb, "./out.xlsx")`
- 常见错误：
  - 无参数，不会失败
  - 工作簿默认无 sheet，首次 excelWriteSheet 到索引 0 会自动创建

### `excelNewSheet`

- 签名：`excelNewSheet(wb, name) -> int`
- 简介：在工作簿中新建 sheet，返回新 sheet 的索引。
- 参数：
  - `wb`：excelNew/excelOpen 返回的工作簿
  - `name`：新 sheet 的名称
- 返回：int：新 sheet 的 0-based 索引；失败返回 error
- 示例：
  - `var idx = excelNewSheet(wb, "汇总")  // → 0（第一个新建的 sheet）`
- 常见错误：
  - 设置名称失败（含非法字符）返回 error
  - 返回索引为当前 sheet 总数减一（新 sheet 在末尾）

### `excelOpen`

- 签名：`excelOpen(path) -> workbook`
- 简介：创建新工作簿（占位函数；rust_xlsxwriter 不支持打开已有文件编辑）。
- 参数：
  - `path`：路径参数（兼容性保留，实际忽略 — 等价于 excelNew()）
- 返回：workbook 空工作簿对象
- 示例：
  - `var wb = excelOpen("./template.xlsx")  // 实际创建新工作簿`
- 常见错误：
  - rust_xlsxwriter 只能写不能读已有文件，此函数实际返回新工作簿
  - 如需读取已有文件内容请用 excelReadSheet / excelReadAll / excelReadCell

### `excelOpenFromBytes`

- 签名：`excelOpenFromBytes(bytes) -> map<string, array<array>>`
- 简介：从字节读取 Excel（不落盘），返回所有 sheet 的 {名: 二维数组}。
- 参数：
  - `bytes`：Excel 文件字节内容：bytes / byteArray / string
- 返回：map<string, array<array>>：键为 sheet 名，值为二维数组
- 示例：
  - `var b = fileReadBytes("./in.xlsx")`
  - `var sheets = excelOpenFromBytes(b)`
  - `// 也可直接处理 HTTP 下载 / S3 获取的 Excel 字节`
- 常见错误：
  - 第一个参数应为 bytes/byteArray/string（不是文件路径）
  - 解析失败：字节流不是有效 Excel 文件或格式不支持
  - calamine 只读，返回的是数据而非 workbook 对象（不能用于写入）

### `excelReadAll`

- 签名：`excelReadAll(path) -> map<string, array<array>>`
- 简介：读取 Excel 文件所有 sheets，返回 {sheet名: 二维数组}。
- 参数：
  - `path`：Excel 文件路径
- 返回：map<string, array<array>>：键为 sheet 名，值为二维数组
- 示例：
  - `var all = excelReadAll("./in.xlsx")`
  - `var sheet1 = all["Sheet1"]  // 取名为 Sheet1 的二维数组`
  - `for (var name in keys(all)) { println(name, len(all[name])) }`
- 常见错误：
  - 打开文件失败：文件不存在 / 不是有效 Excel 文件
  - 与 excelReadSheet 区别：本函数返回所有 sheet（map），后者返回单个（二维数组）

### `excelReadCell`

- 签名：`excelReadCell(path, sheet, row, col) -> value`
- 简介：读取 Excel 文件中指定单个单元格的值。
- 参数：
  - `path`：Excel 文件路径
  - `sheet`：sheet 索引（0-based int）或名称（string）
  - `row`：行号（0-based，非负整数）
  - `col`：列号（0-based，非负整数）
- 返回：value：单元格值（int/float/string/bool）；越界返回空串
- 示例：
  - `var v = excelReadCell("./in.xlsx", 0, 0, 0)            // 第一个 sheet 的 A1`
  - `var v = excelReadCell("./in.xlsx", "Sheet1", 2, 1)     // 第三行第二列`
- 常见错误：
  - row/col 不能为负（应为 0-based 非负整数）
  - sheet 索引超出范围 / 名称不存在
  - 打开文件失败；越界单元格返回空串而非 error

### `excelReadSheet`

- 签名：`excelReadSheet(path, sheet?) -> array<array>`
- 简介：从 Excel 文件读取指定 sheet 为二维数组（支持 xlsx/xls/xlsb/ods）。
- 参数：
  - `path`：Excel 文件路径
  - `sheet`：可选：sheet 索引（0-based int）或名称（string），默认第一个 sheet
- 返回：array<array>：二维数组（每行每列的值，空单元格为空串，日期转为字符串）
- 示例：
  - `var data = excelReadSheet("./in.xlsx")               // 第一个 sheet`
  - `var data = excelReadSheet("./in.xlsx", 1)             // 第二个 sheet（0-based）`
  - `var data = excelReadSheet("./in.xlsx", "Sheet2")     // 按名称`
  - `var name = data[0][0]  // 第一行第一列`
- 常见错误：
  - 打开文件失败：文件不存在 / 不是有效 Excel 文件
  - sheet 索引超出范围 / 名称不存在
  - 数字保真为 int/float，bool 保真，空单元格为空串

### `excelSaveAs`

- 签名：`excelSaveAs(wb, path) -> undefined`
- 简介：保存工作簿到 xlsx 文件。
- 参数：
  - `wb`：excelNew / excelOpen 返回的工作簿
  - `path`：目标 xlsx 文件路径
- 返回：undefined：保存成功；失败返回 error
- 示例：
  - `var wb = excelNew()`
  - `excelWriteSheet(wb, 0, [[1,2],[3,4]])`
  - `excelSaveAs(wb, "./result.xlsx")  // 落盘`
- 常见错误：
  - 第一个参数不是 workbook（未用 excelNew/excelOpen 创建）
  - 保存失败：路径无效 / 权限不足 / 磁盘满
  - 也可用 excelWriteToBytes 获取字节而不落盘

### `excelWriteCell`

- 签名：`excelWriteCell(wb, sheet, row, col, value) -> undefined`
- 简介：写入单个单元格到工作簿（按值类型自动写入）。
- 参数：
  - `wb`：excelNew/excelOpen 返回的工作簿
  - `sheet`：sheet 索引（0-based int）或名称（不存在则创建）
  - `row`：行号（0-based，非负整数）
  - `col`：列号（0-based，非负整数）
  - `value`：要写入的值：int/float/string/bool 等
- 返回：undefined：写入成功；失败返回 error
- 示例：
  - `excelWriteCell(wb, 0, 0, 0, "标题")        // A1`
  - `excelWriteCell(wb, "Sheet1", 1, 2, 95.5)   // 第三列第二行`
  - `excelWriteCell(wb, 0, 5, 0, true)           // 写布尔值`
- 常见错误：
  - 需要 5 个参数 (wb, sheet, row, col, value)
  - row/col 不能为负
  - sheet 索引超出当前范围会自动创建缺失的 sheet

### `excelWriteSheet`

- 签名：`excelWriteSheet(wb, sheet, data) -> undefined`
- 简介：将二维数组写入工作簿的指定 sheet（自动按值类型写入）。
- 参数：
  - `wb`：excelNew/excelOpen 返回的工作簿
  - `sheet`：目标 sheet：int 索引（0-based）或 string 名称（不存在则创建）
  - `data`：二维数组：每行是 array，元素可为 int/float/string/bool 等
- 返回：undefined：写入成功；失败返回 error
- 示例：
  - `excelWriteSheet(wb, 0, [["id","name"],[1,"Alice"],[2,"Bob"]])`
  - `excelWriteSheet(wb, "数据", [[1,2.5,true],["x","y",false]])  // 按名称，自动创建`
- 常见错误：
  - data 必须为二维数组
  - sheet 参数应为 int 或 string
  - int/float 写为数字，bool 写为布尔，bigint/其他转字符串

### `excelWriteToBytes`

- 签名：`excelWriteToBytes(wb) -> bytes`
- 简介：将工作簿序列化为 xlsx 字节（不落盘）。
- 参数：
  - `wb`：excelNew/excelOpen 返回的工作簿
- 返回：bytes：完整的 xlsx 文件字节内容；失败返回 error
- 示例：
  - `var wb = excelNew()`
  - `excelWriteSheet(wb, 0, [["a",1],["b",2]])`
  - `var data = excelWriteToBytes(wb)  // → xlsx 字节`
  - `fileWriteBytes("./out.xlsx", data)  // 可写入文件或上传 S3`
- 常见错误：
  - 第一个参数不是 workbook
  - 序列化失败：工作簿未正确初始化或含非法状态

## file（32 个）

### `appendFile`

- 签名：`appendFile(path, content) -> undefined`
- 简介：将字符串追加到文件末尾（不存在则创建）。
- 参数：
  - `path`：文件路径
  - `content`：要追加的字符串
- 返回：undefined
- 示例：
  - `appendFile("log.txt", "new line\n")`
  - `// 多次追加累积内容，不会清空已有数据`
- 常见错误：
  - 参数顺序：path 在前，content 在后
  - 目录不存在或权限不足返回 error

### `close`

- 签名：`close(f) -> undefined`
- 简介：关闭文件句柄。
- 参数：
  - `f`：file 对象
- 返回：undefined

### `closeFile`

- 签名：`closeFile(f) -> undefined`
- 简介：关闭 file 句柄（建议用 defer closeFile(f) 保证释放）。
- 参数：
  - `f`：openFile 返回的 file 句柄
- 返回：undefined
- 示例：
  - `defer closeFile(f)`
  - `// 通用关闭：close(f) 可关 file/mutex/ticker 等`
- 常见错误：
  - 参数须为 file 句柄，其他类型报错

### `copyFile`

- 签名：`copyFile(src, dst) -> undefined`
- 简介：复制文件（覆盖目标，目标目录须存在）。
- 参数：
  - `src`：源文件路径（须为文件）
  - `dst`：目标路径（目录须存在，存在同名文件会被覆盖）
- 返回：undefined
- 示例：
  - `copyFile("a.txt", "backup/a.txt")`
- 常见错误：
  - 参数顺序：src 在前，dst 在后
  - 源文件不存在或目标目录不存在返回 error；不支持复制目录

### `createTempDir`

- 签名：`createTempDir([dir]) -> string`
- 简介：创建临时目录，返回路径。
- 参数：
  - `dir`：可选。父目录
- 返回：string 临时目录路径

### `createTempFile`

- 签名：`createTempFile([dir]) -> file`
- 简介：创建临时文件。
- 参数：
  - `dir`：可选。目录
- 返回：file 句柄

### `deleteFile`

- 签名：`deleteFile(path) -> undefined`
- 简介：删除文件（不存在则报错）。删除目录请用 removeDir。
- 参数：
  - `path`：要删除的文件路径
- 返回：undefined
- 示例：
  - `deleteFile("tmp.txt")`
- 常见错误：
  - 文件不存在返回 error（不静默成功）
  - 删除目录会失败，目录请用 removeDir

### `fileExists`

- 签名：`fileExists(path) -> bool`
- 简介：判断路径是否存在（文件或目录均可）。
- 参数：
  - `path`：待检查路径
- 返回：bool 路径存在返回 true
- 示例：
  - `fileExists("data.txt")  → true`
  - `fileExists("/no/such")    → false`
- 常见错误：
  - 不区分文件/目录；需明确类型请用 isFile / isDir
  - 权限不足无法访问时返回 false（与不存在难以区分）

### `getFileInfo`

- 签名：`getFileInfo(path) -> map`
- 简介：获取文件元信息，返回含 size/modified/isDir/isFile/isReadOnly 的 map。
- 参数：
  - `path`：文件或目录路径
- 返回：map：size(字节) / modified(Unix秒) / isDir(bool) / isFile(bool) / isReadOnly(bool)
- 示例：
  - `var info = getFileInfo("a.txt")`
  - `info.size    // 文件字节数`
  - `info.modified // 修改时间戳（秒）`
- 常见错误：
  - 文件不存在或权限不足返回 error

### `getFileList`

- 签名：`getFileList(pattern[, "-minSize=N"[, "-maxSize=N"]]) -> array<string>`
- 简介：按通配符列出文件，可按文件大小（字节）过滤。
- 参数：
  - `pattern`：通配符路径，如 *.txt / src/*.rs / src/**/*.rs（** 表示递归子目录）
  - `-minSize=N`：可选。最小字节数（含边界）
  - `-maxSize=N`：可选。最大字节数（含边界）
- 返回：array<string> 匹配的文件路径
- 示例：
  - `getFileList("src/**/*.rs", "-minSize=1", "-maxSize=2000")`
- 常见错误：
  - -minSize=/-maxSize= 后应为非负整数（字节）

### `getFileRel`

- 签名：`getFileRel(base, target) -> string`
- 简介：计算从 base 到 target 的相对路径。
- 参数：
  - `base`：基准路径
  - `target`：目标路径
- 返回：string 相对路径

### `getFileSize`

- 签名：`getFileSize(path) -> int`
- 简介：获取文件大小（字节数）。
- 参数：
  - `path`：文件路径
- 返回：int 文件字节数
- 示例：
  - `getFileSize("a.txt")  → 1024`
- 常见错误：
  - 文件不存在或权限不足返回 error

### `isDir`

- 签名：`isDir(path) -> bool`
- 简介：判断路径是否为目录（不存在返回 false）。
- 参数：
  - `path`：待检查路径
- 返回：bool 路径存在且为目录返回 true
- 示例：
  - `isDir("/tmp")        → true`
  - `isDir("data.txt")    → false`

### `isFile`

- 签名：`isFile(path) -> bool`
- 简介：判断路径是否为文件（不存在返回 false）。
- 参数：
  - `path`：待检查路径
- 返回：bool 路径存在且为文件返回 true
- 示例：
  - `isFile("data.txt")   → true`
  - `isFile("/some/dir")    → false`

### `loadBytesFromFileLimit`

- 签名：`loadBytesFromFileLimit(path, maxLen) -> bytes|error`
- 简介：读取文件前 maxLen 字节。
- 参数：
  - `path`：文件路径
  - `maxLen`：最大字节数
- 返回：bytes；超过限制返回 error

### `openFile`

- 签名：`openFile(path, mode="r") -> file`
- 简介：打开文件返回 file 句柄。mode：r(只读) / w(只写,创建覆盖) / a(追加) / r+(读写)。
- 参数：
  - `path`：文件路径
  - `mode`：打开模式，可选，默认 "r"：r/w/a/r+
- 返回：file 句柄，配合 readLine/readAll/writeStr/seek 等使用
- 示例：
  - `var f = openFile("a.txt", "r")`
  - `var g = openFile("out.log", "w")`
- 常见错误：
  - mode 必须为 r/w/a/r+ 之一，其他值报错
  - r 模式打开不存在文件返回 error；用完应 closeFile

### `readAll`

- 签名：`readAll(f) -> bytes`
- 简介：从当前位置读取 file 句柄剩余全部内容为 bytes。
- 参数：
  - `f`：openFile 返回的 file 句柄（须可读）
- 返回：bytes 从当前位置到末尾的字节
- 示例：
  - `var f = openFile("a.bin")`
  - `defer closeFile(f)`
  - `var b = readAll(f)   // 一次读完`
- 常见错误：
  - 参数须为 file 句柄
  - 返回 bytes，需要 string 请 readStr(f) 或自行 UTF-8 解码

### `readBytes`

- 签名：`readBytes(f) -> bytes`
- 简介：读取文件全部内容为字节。
- 参数：
  - `f`：file 对象
- 返回：bytes

### `readChars`

- 签名：`readChars(f, n) -> string`
- 简介：读取 n 个字符（同 readN）。
- 参数：
  - `f`：file 对象
  - `n`：字符数
- 返回：string

### `readFile`

- 签名：`readFile(path) -> string`
- 简介：读取整个文件为 UTF-8 字符串。适合小文件一次性读取。
- 参数：
  - `path`：文件路径（相对/绝对）
- 返回：string 文件内容（UTF-8 解码）
- 示例：
  - `readFile("data.txt")   → "hello\nworld"`
  - `// 大文件或二进制文件请用 readFileBytes / openFile`
- 常见错误：
  - 文件不存在或权限不足返回 error（错误信息含可能原因）
  - 非 UTF-8 文件解码会替换非法字节，二进制请用 readFileBytes

### `readFileBytes`

- 签名：`readFileBytes(path) -> bytes`
- 简介：读取整个文件为 bytes（不经 UTF-8 解码，适合二进制文件）。
- 参数：
  - `path`：文件路径
- 返回：bytes 文件全部字节
- 示例：
  - `var b = readFileBytes("img.png")`
  - `// 与 readFile 区别：本函数返回 bytes，可读任意二进制`
- 常见错误：
  - 文件不存在返回 error
  - 需要可变字节用 byteArrayFromBytes 转换

### `readLine`

- 签名：`readLine(f) -> string|undefined`
- 简介：从 file 句柄读一行（到 \n，不含换行符；兼容 \r\n）。
- 参数：
  - `f`：openFile 返回的 file 句柄（须可读）
- 返回：string 当前行；EOF 返回 undefined
- 示例：
  - `var f = openFile("a.txt")`
  - `defer closeFile(f)`
  - `var line = readLine(f)  // 读一行`
- 常见错误：
  - 参数须为 file 句柄；EOF 时返回 undefined（需判空）
  - mode 为 w/a 时读取会失败

### `readLines`

- 签名：`readLines(path) -> array<string>`
- 简介：按行读取文件为数组（兼容 \n 与 \r\n，去掉每行换行符）。
- 参数：
  - `path`：文本文件路径
- 返回：array<string> 行数组（空文件返回空数组）
- 示例：
  - `readLines("a.txt")    → ["line1", "line2"]`
  - `var xs = readLines(f)  // 逐行处理`
- 常见错误：
  - 文件不存在返回 error
  - 末尾换行不产生额外空行；\n 单独成行视为一个空串

### `readN`

- 签名：`readN(f, n) -> string`
- 简介：从文件读取 n 个字符。
- 参数：
  - `f`：file 对象
  - `n`：字符数
- 返回：string

### `readStr`

- 签名：`readStr(f) -> string`
- 简介：读取文件全部内容为字符串。
- 参数：
  - `f`：file 对象
- 返回：string

### `seek`

- 签名：`seek(f, pos[, whence]) -> error|undefined`
- 简介：移动文件读写位置。
- 参数：
  - `f`：file 对象
  - `pos`：位置
  - `whence`：可选。0=起/1=当前/2=末
- 返回：undefined

### `tell`

- 签名：`tell(f) -> int`
- 简介：返回当前读写位置。
- 参数：
  - `f`：file 对象
- 返回：int

### `writeBytes`

- 签名：`writeBytes(f, b) -> error|undefined`
- 简介：向文件写入字节。
- 参数：
  - `f`：file 对象
  - `b`：bytes
- 返回：undefined

### `writeFile`

- 签名：`writeFile(path, content) -> undefined`
- 简介：将字符串覆盖写入文件（不存在则创建，存在则清空重写）。
- 参数：
  - `path`：文件路径
  - `content`：要写入的字符串（按 UTF-8 编码）
- 返回：undefined
- 示例：
  - `writeFile("out.txt", "hello")`
  - `writeFile("log", data)   // 清空后写入`
- 常见错误：
  - 参数顺序：path 在前，content 在后
  - 目录不存在或权限不足返回 error；会清空旧内容

### `writeFileBytes`

- 签名：`writeFileBytes(path, b) -> error|undefined`
- 简介：写入字节数据到文件。
- 参数：
  - `path`：文件路径
  - `b`：bytes/byteArray
- 返回：undefined；失败返回 error

### `writeLine`

- 签名：`writeLine(f, s) -> error|undefined`
- 简介：写入一行（追加换行）。
- 参数：
  - `f`：file 对象
  - `s`：字符串
- 返回：undefined

### `writeStr`

- 签名：`writeStr(f, s) -> error|undefined`
- 简介：向文件写入字符串。
- 参数：
  - `f`：file 对象
  - `s`：字符串
- 返回：undefined；失败返回 error

## ftp（9 个）

### `ftpCreateDir`

- 签名：`ftpCreateDir("--host=...", "--user=...", "--password=...", "--remotePath=/dir") -> undefined`
- 简介：在 FTP 远程主机创建单个目录（非递归，父目录须存在）。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要创建的远程目录路径（必填）
- 返回：undefined：创建成功；失败返回 error
- 示例：
  - `ftpCreateDir("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/newdir")`
- 常见错误：
  - FTP 创建目录失败：父目录不存在 / 权限不足 / 目录已存在
  - 缺少 --remotePath 参数

### `ftpCreateFile`

- 签名：`ftpCreateFile("--host=...", "--user=...", "--password=...", "--remotePath=/f", "--content=...") -> undefined`
- 简介：在 FTP 远程主机创建文件并写入指定内容。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程目标文件路径（必填）
  - `--content`：文件内容字符串（默认空串，创建空文件）
- 返回：undefined：创建成功；失败返回 error
- 示例：
  - `ftpCreateFile("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/readme.txt", "--content=Hello FTP")`
  - `ftpCreateFile("--host=h", "--user=u", "--password=p", "--remotePath=/pub/empty", "--content=")  // 空文件`
- 常见错误：
  - FTP 创建文件失败：远程父目录不存在 / 权限不足 / 磁盘满
  - 缺少 --remotePath 参数

### `ftpDownload`

- 签名：`ftpDownload("--host=...", "--user=...", "--password=...", "--remotePath=...", "--localPath=...") -> undefined`
- 简介：将 FTP 远程文件下载到本地磁盘。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程源文件路径（必填）
  - `--localPath`：本地目标文件路径（必填）
- 返回：undefined：下载成功；失败返回 error
- 示例：
  - `ftpDownload("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/data.csv", "--localPath=./data.csv")`
- 常见错误：
  - FTP 下载失败：远程文件不存在 / 权限不足
  - 写入本地文件失败：路径不可写 / 磁盘满
  - 缺少 --remotePath 或 --localPath 参数

### `ftpDownloadBytes`

- 签名：`ftpDownloadBytes("--host=...", "--user=...", "--password=...", "--remotePath=/f") -> bytes`
- 简介：将 FTP 远程文件下载到内存 bytes（不落本地磁盘）。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程源文件路径（必填）
- 返回：bytes：文件全部内容；失败返回 error
- 示例：
  - `var data = ftpDownloadBytes("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/data.bin")`
  - `fileWriteBytes("./local.bin", ftpDownloadBytes("--host=h", "--user=u", "--password=p", "--remotePath=/tmp/x"))`
- 常见错误：
  - FTP 下载失败：远程文件不存在 / 权限不足
  - 缺少 --remotePath 参数

### `ftpList`

- 签名：`ftpList("--host=...", "--user=...", "--password=...", "--remotePath=/dir") -> array<string>`
- 简介：列出 FTP 远程目录内容（返回原始 LIST 命令输出行）。
- 参数：
  - `--host`：FTP 服务器地址（必填）
  - `--port`：FTP 端口，默认 21
  - `--user`：登录用户名，默认 anonymous
  - `--password`：登录密码（匿名可留空；支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要列出的远程目录，默认 /
- 返回：array<string>：LIST 命令返回的每行（含权限、大小、文件名等原始格式）；失败返回 error
- 示例：
  - `ftpList("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub")`
  - `// → ["-rw-r--r-- 1 owner group 1024 Jan 01 file.txt", "drwxr-xr-x 2 owner group 4096 Jan 01 subdir"]`
  - `ftpList("--host=ftp.example.com", "--remotePath=/incoming")  // 匿名登录`
- 常见错误：
  - FTP 连接失败：网络不通 / 端口错误
  - FTP 登录失败：用户名或密码错误
  - 列目录失败：路径不存在 / 权限不足

### `ftpRemoveFile`

- 签名：`ftpRemoveFile("--host=...", "--user=...", "--password=...", "--remotePath=/f") -> undefined`
- 简介：删除 FTP 远程文件（DELE 命令，仅文件不能删目录）。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要删除的远程文件路径（必填）
- 返回：undefined：删除成功；失败返回 error
- 示例：
  - `ftpRemoveFile("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/old.log")`
- 常见错误：
  - FTP 删除失败：文件不存在 / 权限不足 / 路径是目录（用 RMD 删目录需自行扩展）
  - 缺少 --remotePath 参数

### `ftpSize`

- 签名：`ftpSize("--host=...", "--user=...", "--password=...", "--remotePath=/f") -> int`
- 简介：获取 FTP 远程文件大小（字节，SIZE 命令）。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程文件路径（必填）
- 返回：int：文件字节数；失败返回 error
- 示例：
  - `var sz = ftpSize("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/data.tar.gz")  // → 1048576`
- 常见错误：
  - FTP 获取大小失败：文件不存在 / 权限不足 / 路径是目录
  - 部分老 FTP 服务器不支持 SIZE 命令
  - 缺少 --remotePath 参数

### `ftpUpload`

- 签名：`ftpUpload("--host=...", "--user=...", "--password=...", "--localPath=...", "--remotePath=...") -> undefined`
- 简介：将本地文件上传到 FTP 远程主机。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--localPath`：本地源文件路径（必填）
  - `--remotePath`：远程目标文件路径（必填）
- 返回：undefined：上传成功；失败返回 error
- 示例：
  - `ftpUpload("--host=ftp.example.com", "--user=u", "--password=p", "--localPath=./report.pdf", "--remotePath=/pub/report.pdf")`
- 常见错误：
  - 读取本地文件失败：路径不存在 / 权限不足
  - FTP 上传失败：远程父目录不存在 / 权限不足 / 磁盘满
  - 缺少 --localPath 或 --remotePath 参数

### `ftpUploadBytes`

- 签名：`ftpUploadBytes("--host=...", "--user=...", "--password=...", "--remotePath=/f", dataBytes) -> undefined`
- 简介：将 bytes/byteArray 内存数据上传到 FTP 远程文件。
- 参数：
  - `--host/--port/--user/--password`：连接与认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程目标文件路径（必填）
  - `dataBytes`：要上传的 bytes 或 byteArray（最后一个非 -- 开头的参数）
- 返回：undefined：上传成功；失败返回 error
- 示例：
  - `ftpUploadBytes("--host=ftp.example.com", "--user=u", "--password=p", "--remotePath=/pub/data.bin", fileReadBytes("./local.bin"))`
- 常见错误：
  - 缺少 bytes/byteArray 参数（最后一个非 -- 开头的参数）
  - FTP 上传失败：远程路径无效 / 权限不足
  - 缺少 --remotePath 参数

## gui（8 个）

### `guiClose`

- 签名：`guiClose(win) -> undefined`
- 简介：请求关闭窗口（用于在 handler 中程序化关闭）。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
- 返回：undefined（事件循环检测到标志后退出）
- 示例：
  - `guiSetHandler(w, func(msg) { if (msg == "quit") { guiClose(w) } })`
- 常见错误：
  - win 必须是 guiNewWindow 创建的 window 对象
  - 仅在 guiShow 事件循环运行期间有效

### `guiEval`

- 签名：`guiEval(win, jsCode) -> undefined`
- 简介：在 WebView 中排队执行 JavaScript 代码。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
  - `jsCode`：要执行的 JavaScript 代码字符串
- 返回：undefined（JS 执行结果不回传到 Sflang）
- 示例：
  - `guiEval(w, "document.body.style.background='red'")`
- 常见错误：
  - 必须在 guiShow 之前或 handler 内调用，事件循环每 20ms 刷新队列
  - JS 代码错误不会抛回 Sflang，仅在 WebView 控制台报错

### `guiNewWindow`

- 签名：`guiNewWindow(switches...) -> window`
- 简介：创建 GUI 窗口配置对象（不显示）。
- 参数：
  - `...switches`：--key=value 形式的开关，支持 --title/--width/--height
- 返回：window 窗口对象，传给 guiSetHtml/guiSetUrl/guiSetHandler/guiShow 等
- 示例：
  - `var w = guiNewWindow("--title=My App", "--width=1024", "--height=768")`
- 常见错误：
  - switches 为可变参数，未传时使用默认值 title=Sflang width=800 height=600

### `guiSetHandler`

- 签名：`guiSetHandler(win, func) -> window`
- 简介：设置 IPC 消息处理函数。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
  - `func`：处理函数，接收 JS 通过 window.ipc.postMessage(msg) 发来的字符串
- 返回：window 返回传入的窗口对象（便于链式调用）
- 示例：
  - `guiSetHandler(w, func(msg) { println(msg) })`
- 常见错误：
  - func 必须是可调用对象（函数/闭包），接收单个字符串参数
  - handler 在 guiShow 事件循环线程内同步执行，可安全重入 VM

### `guiSetHtml`

- 签名：`guiSetHtml(win, html) -> window`
- 简介：设置窗口要加载的 HTML 内容。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
  - `html`：HTML 字符串
- 返回：window 返回传入的窗口对象（便于链式调用）
- 示例：
  - `guiSetHtml(w, "<h1>Hello</h1>")`
- 常见错误：
  - win 必须是 guiNewWindow 创建的 window 对象
  - html 与 url 互斥，guiShow 优先使用 html

### `guiSetTitle`

- 签名：`guiSetTitle(win, title) -> window`
- 简介：设置窗口标题。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
  - `title`：标题字符串
- 返回：window 返回传入的窗口对象（便于链式调用）
- 示例：
  - `guiSetTitle(w, "My App")`
- 常见错误：
  - win 必须是 guiNewWindow 创建的 window 对象

### `guiSetUrl`

- 签名：`guiSetUrl(win, url) -> window`
- 简介：设置窗口要加载的 URL。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
  - `url`：URL 字符串（http/https/file 等）
- 返回：window 返回传入的窗口对象（便于链式调用）
- 示例：
  - `guiSetUrl(w, "https://example.com")`
- 常见错误：
  - win 必须是 guiNewWindow 创建的 window 对象
  - html 与 url 互斥，guiShow 优先使用 html

### `guiShow`

- 签名：`guiShow(win) -> !`
- 简介：显示窗口并进入事件循环（阻塞当前线程）。
- 参数：
  - `win`：guiNewWindow 返回的窗口对象
- 返回：永不返回（事件循环阻塞，直到窗口关闭）
- 示例：
  - `guiShow(w)  // 阻塞直到用户关闭窗口`
- 常见错误：
  - win 必须是 guiNewWindow 创建的 window 对象
  - 创建窗口/WebView 失败会抛错（如平台不支持）
  - 未设置 html/url/handler 时显示默认占位 HTML

## hash（16 个）

### `checkOtpCode`

- 签名：`checkOtpCode(secret, code, timestamp?) -> bool`
- 简介：验证 TOTP 码是否匹配（比较前会 trim code），返回 bool。
- 参数：
  - `secret`：Base32 编码的密钥字符串（字母表 A-Z, 2-7）
  - `code`：用户输入的 6 位字符串（前后空白会被 trim）
  - `timestamp`：可选 int：Unix 秒；省略则用当前系统时间
- 返回：bool：code 与该时间窗口的预期值一致返回 true
- 示例：
  - `checkOtpCode("JBSWY3DPEHPK3PXP", getOtpCode("JBSWY3DPEHPK3PXP")) → true`
- 常见错误：
  - TOTP 有 30 秒时间窗口，时钟漂移可能误判
  - secret 必须是合法 Base32，否则返回 error

### `genOtpCode`

- 签名：`genOtpCode(secret, timestamp?) -> string`
- 简介：getOtpCode 的 Charlang 兼容别名：生成 TOTP（RFC 6238）6 位验证码。
- 参数：
  - `secret`：Base32 编码的密钥字符串（字母表 A-Z, 2-7）
  - `timestamp`：可选 int：Unix 秒；省略则用当前系统时间
- 返回：string：6 位数字验证码（左侧补零）
- 示例：
  - `genOtpCode(`JBSWY3DPEHPK3PXP`)            → 用当前时间的 6 位码`
  - `genOtpCode("JBSWY3DPEHPK3PXP", 1234567890) → 固定 6 位码`
- 常见错误：
  - secret 必须是合法 Base32（A-Z, 2-7），空格和 = 填充会被忽略
  - 解码后密钥为空时返回 error

### `getOtpCode`

- 签名：`getOtpCode(secret, timestamp?) -> string`
- 简介：生成 TOTP（RFC 6238）6 位验证码，左侧补零。
- 参数：
  - `secret`：Base32 编码的密钥字符串（字母表 A-Z, 2-7）
  - `timestamp`：可选 int：Unix 秒；省略则用当前系统时间
- 返回：string：6 位数字验证码（左侧补零）
- 示例：
  - `getOtpCode("JBSWY3DPEHPK3PXP", 1234567890) → 固定 6 位码`
  - `getOtpCode("JBSWY3DPEHPK3PXP")            → 用当前时间的 6 位码`
- 常见错误：
  - secret 必须是合法 Base32（A-Z, 2-7），空格和 = 填充会被忽略
  - 解码后密钥为空时返回 error

### `hmacSha256`

- 签名：`hmacSha256(key, message) -> bytes`
- 简介：计算 HMAC-SHA256（RFC 2104），返回 32 字节 bytes。
- 参数：
  - `key`：string/bytes/byteArray：HMAC 密钥
  - `message`：string/bytes/byteArray：待认证的消息
- 返回：bytes：32 字节 HMAC-SHA256 摘要
- 示例：
  - `bytesHex(hmacSha256("key", "The quick brown fox jumps over the lazy dog")) → "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8"`
- 常见错误：
  - 参数顺序为 key 在前、message 在后

### `hmacSha256Hex`

- 签名：`hmacSha256Hex(key, message) -> string`
- 简介：计算 HMAC-SHA256 并返回 64 字符小写十六进制字符串。
- 参数：
  - `key`：string/bytes/byteArray：HMAC 密钥
  - `message`：string/bytes/byteArray：待认证的消息
- 返回：string：64 字符小写十六进制 HMAC-SHA256 摘要
- 示例：
  - `hmacSha256Hex("key", "The quick brown fox jumps over the lazy dog") → "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8"`
- 常见错误：
  - 参数顺序为 key 在前、message 在后

### `hmacSm3`

- 签名：`hmacSm3(key, message) -> bytes`
- 简介：计算 HMAC-SM3（RFC 2104 构造），返回 32 字节 bytes。
- 参数：
  - `key`：string/bytes/byteArray：HMAC 密钥
  - `message`：string/bytes/byteArray：待认证的消息
- 返回：bytes：32 字节 HMAC-SM3 摘要
- 示例：
  - `bytesHex(hmacSm3("key", "message"))`
- 常见错误：
  - 参数顺序为 key 在前、message 在后

### `hmacSm3Hex`

- 签名：`hmacSm3Hex(key, message) -> string`
- 简介：计算 HMAC-SM3 并返回 64 字符小写十六进制字符串。
- 参数：
  - `key`：string/bytes/byteArray：HMAC 密钥
  - `message`：string/bytes/byteArray：待认证的消息
- 返回：string：64 字符小写 hex
- 示例：
  - `hmacSm3Hex("key", "message")`

### `md5`

- 签名：`md5(data) -> bytes`
- 简介：计算 MD5 哈希，返回 16 字节 bytes。
- 参数：
  - `data`：string/bytes/byteArray：待哈希的数据（string 取 UTF-8 字节）
- 返回：bytes：16 字节 MD5 摘要
- 示例：
  - `md5("abc")          → 16 字节 bytes`
  - `bytesHex(md5("abc")) → "900150983cd24fb0d6963f7d28e17f72"`
- 常见错误：
  - MD5 不再安全，勿用于密码存储；仅用于校验和/去重

### `md5Hex`

- 签名：`md5Hex(data) -> string`
- 简介：计算 MD5 哈希并返回 32 字符小写十六进制字符串。
- 参数：
  - `data`：string/bytes/byteArray：待哈希的数据（string 取 UTF-8 字节）
- 返回：string：32 字符小写十六进制摘要
- 示例：
  - `md5Hex("abc") → "900150983cd24fb0d6963f7d28e17f72"`
- 常见错误：
  - 等价于 bytesHex(md5(data))；MD5 非安全算法

### `randomHex`

- 签名：`randomHex(n) -> string`
- 简介：生成 n 个随机字节的小写十六进制字符串（长度 2n）。
- 参数：
  - `n`：字节数（int，非负），输出长度为 2n 个十六进制字符
- 返回：string：2n 字符小写十六进制随机串
- 示例：
  - `randomHex(16)  // 如 "9f86d081884c7d659a2feaa0c55ad015"（32 字符）`
  - `randomHex(4)   // 如 "3b7a1cf0"，适合做临时文件后缀、请求 ID 等`
- 常见错误：
  - randomHex() 需要至少 1 个参数
  - randomHex() 长度不能为负
  - randomHex() 长度超过上限 1000000（可能原因：误传了过大的字节数）

### `sha1`

- 签名：`sha1(data) -> bytes`
- 简介：计算 SHA-1 哈希，返回 20 字节 bytes。
- 参数：
  - `data`：string/bytes/byteArray：待哈希的数据（string 取 UTF-8 字节）
- 返回：bytes：20 字节 SHA-1 摘要
- 示例：
  - `sha1("abc")          → 20 字节 bytes`
  - `bytesHex(sha1("abc")) → "a9993e364706816aba3e25717850c26c9cd0d89d"`
- 常见错误：
  - SHA-1 已不推荐用于安全场景；新代码建议用 sha256

### `sha1Hex`

- 签名：`sha1Hex(data) -> string`
- 简介：计算 SHA-1 哈希并返回 40 字符小写十六进制字符串。
- 参数：
  - `data`：string/bytes/byteArray：待哈希的数据（string 取 UTF-8 字节）
- 返回：string：40 字符小写十六进制摘要
- 示例：
  - `sha1Hex("abc") → "a9993e364706816aba3e25717850c26c9cd0d89d"`
- 常见错误：
  - 等价于 bytesHex(sha1(data))

### `sha256`

- 签名：`sha256(data) -> bytes`
- 简介：计算 SHA-256 哈希，返回 32 字节 bytes。
- 参数：
  - `data`：string/bytes/byteArray：待哈希的数据（string 取 UTF-8 字节）
- 返回：bytes：32 字节 SHA-256 摘要
- 示例：
  - `sha256("abc")          → 32 字节 bytes`
  - `bytesHex(sha256("abc")) → "ba7816bf...20015ad"（64 位十六进制）`
- 常见错误：
  - 参数须为 string/bytes/byteArray

### `sha256Hex`

- 签名：`sha256Hex(data) -> string`
- 简介：计算 SHA-256 哈希并返回 64 字符小写十六进制字符串。
- 参数：
  - `data`：string/bytes/byteArray：待哈希的数据（string 取 UTF-8 字节）
- 返回：string：64 字符小写十六进制摘要
- 示例：
  - `sha256Hex("abc") → "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"`
- 常见错误：
  - 等价于 bytesHex(sha256(data))

### `sm3`

- 签名：`sm3(data) -> bytes`
- 简介：计算 SM3 密码杂凑（GB/T 32905-2016 国密标准），返回 32 字节 bytes。
- 参数：
  - `data`：string/bytes/byteArray：待杂凑的数据
- 返回：bytes：32 字节 SM3 摘要
- 示例：
  - `bytesHex(sm3("abc")) → "66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0"`

### `sm3Hex`

- 签名：`sm3Hex(data) -> string`
- 简介：计算 SM3 并返回 64 字符小写十六进制字符串。
- 参数：
  - `data`：string/bytes/byteArray：待杂凑的数据
- 返回：string：64 字符小写 hex
- 示例：
  - `sm3Hex("abc")`

## http（60 个）

### `downloadFile`

- 签名：`downloadFile(url, savePath [, "--timeout=N", "--proxy=URL", "--retry=N", "--insecure", "Header: value"]) -> int`
- 简介：下载远程文件到本地路径，成功返回写入的字节数。
- 参数：
  - `url`：目标 URL
  - `savePath`：本地保存路径
  - `--timeout`：可选超时秒数，默认 30
  - `--proxy`：可选代理 URL，如 http://host:port 或 socks5://host:port
  - `--retry`：可选重试次数，默认 0 不重试
  - `--insecure`：可选开关，跳过 TLS 证书校验（自签名证书 / 内网 HTTPS 测试场景）
  - `header`：可选附加 header
- 返回：int 写入字节数（失败时返回 error 对象）
- 示例：
  - `size := downloadFile("https://example.com/big.zip", "/tmp/big.zip", "--timeout=120")`
- 常见错误：
  - downloadFile() 需要至少 2 个参数 (URL, savePath)
  - downloadFile() 服务器返回错误状态（可能原因：文件不存在、权限不足）
  - downloadFile() 写入文件 'xxx' 失败（可能原因：目录不存在、权限不足）
  - downloadFile() 下载失败（可能原因：URL 格式错误、网络不通、DNS 解析失败、TLS 证书验证失败、代理配置错误、服务器超时）

### `flushResp`

- 签名：`flushResp(resp) -> undefined`
- 简介：刷新 HTTP 响应缓冲区（当前实现为 no-op，因响应在 handler 返回后才写出；保留用于 API 兼容）。
- 参数：
  - `resp`：handler 中的响应对象
- 返回：undefined
- 示例：
  - `flushResp(resp)  // 当前为空操作`

### `genJsonResp`

- 签名：`genJsonResp(resp, status, msg) -> undefined`
- 简介：生成标准 JSON 响应 {"status":..., "msg":...}，自动设 Content-Type 为 application/json。
- 参数：
  - `resp`：handler 中的响应对象
  - `status`：状态字段值（string/int/bool，undefined 时为 null）
  - `msg`：消息字段（undefined 时为 null）
- 返回：undefined
- 示例：
  - `genJsonResp(resp, "ok", "created")  // {"status": "ok", "msg": "created"}`

### `getMimeType`

- 签名：`getMimeType(filenameOrExt) -> string`
- 简介：按文件扩展名返回 MIME 类型，未知扩展名返回 application/octet-stream。
- 参数：
  - `filenameOrExt`：文件名或扩展名（自动取最后一个 . 之后并转小写）
- 返回：string MIME 类型
- 示例：
  - `getMimeType("a.png")  // "image/png"`
  - `getMimeType(".JSON")  // "application/json"`
- 常见错误：
  - getMimeType() 第 1 个参数应为 string (文件名)

### `getReqBody`

- 签名：`getReqBody(req) -> string`
- 简介：返回请求体（UTF-8 lossy 转字符串）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：string 请求体
- 示例：
  - `body := getReqBody(req)  // 表单或 JSON 文本`
- 常见错误：
  - getReqBody() 参数不是请求对象

### `getReqBodyBytes`

- 签名：`getReqBodyBytes(req) -> bytes`
- 简介：返回请求体（原始字节，适合二进制内容）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：bytes 请求体
- 示例：
  - `raw := getReqBodyBytes(req)  // 二进制数据`
- 常见错误：
  - getReqBodyBytes() 参数不是请求对象

### `getReqCookie`

- 签名：`getReqCookie(req, name) -> string|undefined`
- 简介：从请求 Cookie 头中取指定名称的值，不存在返回 undefined。
- 参数：
  - `req`：handler 中的请求对象
  - `name`：cookie 名称
- 返回：string 值，不存在时 undefined
- 示例：
  - `sid := getReqCookie(req, "sessionId")`
- 常见错误：
  - getReqCookie() 需要 2 个参数 (req, name)
  - getReqCookie() 第 2 个参数应为 string (cookie 名)

### `getReqCookies`

- 签名：`getReqCookies(req) -> map`
- 简介：返回所有 Cookie（Map 对象）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：Map{cookieName: value}
- 示例：
  - `cks := getReqCookies(req)  // {"sessionId": "abc", "theme": "dark"}`
- 常见错误：
  - getReqCookies() 需要 1 个参数 (req)

### `getReqField`

- 签名：`getReqField(req, fieldName) -> string`
- 简介：读取请求的任意字段（通用键值）。支持 method/path/uri/query/remoteAddr/body；HTTP 头请用 getReqHeader。
- 参数：
  - `req`：handler 中的请求对象
  - `fieldName`：字段名（大小写不敏感）：method/path/uri/query/remoteAddr/body
- 返回：string 字段值，取不到时为空串
- 示例：
  - `ip := getReqField(req, "remoteAddr")  // 直连取 TCP 对端 IP（客户端真实 IP）`
  - `ip := getReqHeader(req, "X-Forwarded-For")  // 反代取真实 IP`
  - `m := getReqField(req, "method")  // "GET"/"POST"...`
- 常见错误：
  - getReqField() 参数不是请求对象 / 字段名非字符串 / 未知字段名

### `getReqHeader`

- 签名：`getReqHeader(req, name) -> string|undefined`
- 简介：返回指定请求头的值，不存在时返回 undefined。
- 参数：
  - `req`：handler 中的请求对象
  - `name`：header 名（大小写不敏感）
- 返回：string 值，不存在时 undefined
- 示例：
  - `ct := getReqHeader(req, "Content-Type")  // "application/json" 或 undefined`
- 常见错误：
  - getReqHeader() 第 2 个参数应为 string (header 名称)
  - getReqHeader() 参数不是请求对象

### `getReqHeaders`

- 签名：`getReqHeaders(req) -> map`
- 简介：返回所有请求头（Map 对象，键为 header 名）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：Map{headerName: value}
- 示例：
  - `hs := getReqHeaders(req)  // {"Content-Type": "application/json", ...}`
- 常见错误：
  - getReqHeaders() 参数不是请求对象

### `getReqMethod`

- 签名：`getReqMethod(req) -> string`
- 简介：返回请求方法（GET/POST/PUT/DELETE 等）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：string 方法名（大写）
- 示例：
  - `m := getReqMethod(req)  // 如 "GET"`
- 常见错误：
  - getReqMethod() 需要至少 1 个参数
  - getReqMethod() 参数不是请求对象

### `getReqParam`

- 签名：`getReqParam(req, key) -> string|undefined`
- 简介：返回指定请求参数的值（URL 查询参数与 POST/PUT/PATCH 表单参数合并，同名查询串优先），不存在时返回 undefined。
- 参数：
  - `req`：handler 中的请求对象
  - `key`：参数名
- 返回：string 值，不存在时 undefined
- 示例：
  - `page := getReqParam(req, "page")  // "1" 或 undefined`
- 常见错误：
  - getReqParam() 第 2 个参数应为 string (参数名)
  - getReqParam() 参数不是请求对象

### `getReqParams`

- 签名：`getReqParams(req) -> map`
- 简介：返回所有请求参数（Map 对象；URL 查询参数与 POST/PUT/PATCH 表单参数合并，urlencoded 及 multipart 非文件字段，同名取首个）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：Map{key: value}
- 示例：
  - `ps := getReqParams(req)  // {"page": "1", "size": "10"}`
- 常见错误：
  - getReqParams() 参数不是请求对象

### `getReqPath`

- 签名：`getReqPath(req) -> string`
- 简介：返回请求路径（不含 query）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：string 路径，如 "/api/users"
- 示例：
  - `p := getReqPath(req)  // "/api/users"`
- 常见错误：
  - getReqPath() 参数不是请求对象

### `getReqQuery`

- 签名：`getReqQuery(req) -> string`
- 简介：返回查询串（不含前导 ?）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：string query 串
- 示例：
  - `q := getReqQuery(req)  // "page=1&size=10"`
- 常见错误：
  - getReqQuery() 参数不是请求对象

### `getReqUri`

- 签名：`getReqUri(req) -> string`
- 简介：返回完整 URI（含路径和 query）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：string 完整 URI
- 示例：
  - `u := getReqUri(req)  // "/api/list?page=1"`
- 常见错误：
  - getReqUri() 参数不是请求对象

### `getWeb`

- 签名：`getWeb(url [, "--method=M", "--body=TEXT", "--bodyFile=PATH", "-post={json}", Map表单, bytes体, "--contentType=CT", "--headers={json}", "--timeout=N", "--proxy=URL", "--retry=N", "--insecure", "--bytes", "--object", "--returnAny", "--withResp", "--saveTo=PATH", "--encoding=ENC|auto", "--maxSize=N", "--maxRedirects=N", "--noRedirect", session对象, progressFn, "Header: value"]) -> string|bytes|map|int`
- 简介：全能 Web 请求（对齐 charlang getWeb）：默认 GET 返回响应体字符串；可通过开关/参数表达任意方法、表单、原始体、文件体、字节返回、JSON 解析、存盘、编码转换。
- 参数：
  - `url`：目标 URL
  - `--method=M`：可选 HTTP 方法（GET/POST/PUT/DELETE/HEAD/PATCH）；未指定且有请求体时自动 POST
  - `Map 参数`：可选，Map/Object{name: value} → urlencoded 表单体（同 postForm 的 valuesMap）
  - `bytes 参数`：可选，Bytes/ByteArray → 原始请求体（如手工拼装的 multipart）
  - `-post={json}`：可选，JSON 对象字符串 → urlencoded 表单体（charlang 兼容写法）
  - `--body=TEXT`：可选，原始请求体（等价 charlang -postBody=）
  - `--bodyFile=PATH`：可选，以文件内容为请求体（等价 charlang -postFile=）
  - `--contentType=CT`：可选，显式 Content-Type；表单体自动补 urlencoded
  - `--headers={json}`：可选，JSON 对象形式的 header 表（charlang 兼容）；也可用 "Name: value" 参数
  - `--timeout=N`：可选超时秒数，默认 30
  - `--proxy=URL`：可选代理 URL，如 http://host:port 或 socks5://host:port
  - `--retry=N`：可选重试次数，默认 0；仅网络错误/超时/5xx/429 重试，指数退避
  - `--insecure`：可选开关，跳过 TLS 证书校验（自签名证书 / 内网测试）
  - `--bytes`：可选开关，返回 bytes 而非 string
  - `--object`：可选开关，响应按 JSON 解析为对象（失败返回 error 对象）
  - `--returnAny`：可选开关，非 200 时返回 Map{respCode, respBody(bytes)} 而非响应体
  - `--saveTo=PATH`：可选，响应体流式存盘（不占内存），返回写入字节数（覆盖 downloadFile 场景）
  - `--encoding=ENC`：可选，响应按指定编码转 UTF-8（gbk/gb2312/big5/shift_jis/latin1 等）；auto=按响应头/HTML meta 自动嗅探
  - `--withResp`：可选开关，返回响应对象 Map{status, contentType, finalUrl, elapsedMs, headers, setCookies, body(bytes)}
  - `--maxSize=N`：可选，响应体大小上限（字节），超限报错，防止意外 OOM
  - `--maxRedirects=N`：可选，重定向跟随次数上限（默认 10）
  - `--noRedirect`：可选开关，不跟随重定向（3xx 原样返回，配合 --withResp 可取 Location）
  - `session 位置参数`：可选，httpSession() 创建的会话对象：自动携带与存储 Cookie
  - `progressFn 位置参数`：可选，进度回调函数 func(receivedBytes, totalBytes)，每 64KB 调用一次，总长未知时 totalBytes 为 -1
  - `header`：可选附加 header，如 "Authorization: Bearer x"；支持多行或多参数
- 返回：默认 string 响应体；--bytes → bytes；--object → 对象；--saveTo → int 字节数；--returnAny 非 200 → Map{respCode, respBody}。网络层失败返回 error 对象；4xx/5xx 不算失败（--returnAny 可感知状态码）
- 示例：
  - `body := getWeb("https://example.com")  // 简单 GET`
  - `resp := getWeb(spr("https://host/japi?src=%v", "q"), {"req": "next", "sc": "abc"})  // query+表单混合 POST`
  - `resp := getWeb(url, bodyBytes, "--contentType=multipart/form-data; boundary=x")  // 手工 multipart`
  - `obj := getWeb("https://api.x.com/data", "--object", "--timeout=10")  // 直接拿对象`
  - `n := getWeb("https://x.com/f.zip", "--saveTo=../temp/f.zip")  // 下载到文件`
  - `r := getWeb(url, "--returnAny")  // 非 200 → r.respCode / r.respBody`
  - `r := getWeb(url, "--withResp")  // 完整响应对象：r.status / r.headers / r.body / r.finalUrl`
  - `sess := httpSession(); getWeb(loginUrl, {user:a, pwd:b}, sess); page := getWeb(meUrl, sess)  // Cookie 会话`
  - `n := getWeb(bigFileUrl, "--saveTo=../temp/f.iso", func(rec, total) { plNow("%v/%v", rec, total) })  // 流式下载+进度`
  - `s := getWeb("http://old-site.com/x", "--encoding=auto")  // 自动嗅探 GBK 等编码`
  - `body := getWeb("https://flaky.api.com", "--retry=3")  // 失败自动重试`
- 常见错误：
  - getWeb() 第 1 个参数应为 string (URL)
  - getWeb() 出现了多个 Map/bytes 参数（可能原因：表单/请求体只能有一个来源）
  - getWeb() -headers=/-post= 应为合法 JSON 对象字符串
  - getWeb() 读取请求体文件失败（可能原因：--bodyFile= 路径不存在）
  - getWeb() --encoding= 不支持的编码（常用 gbk/gb2312/big5/shift_jis/latin1）
  - getWeb() --object 解析失败（可能原因：响应不是合法 JSON）
  - getWeb() 保存响应体失败（可能原因：--saveTo= 目录不存在或无写入权限）
  - getWeb() 请求失败（可能原因：URL 格式错误、网络不通、DNS 解析失败、TLS 证书验证失败、代理配置错误、服务器超时）

### `getWebBytes`

- 签名：`getWebBytes(url [, "--timeout=N", "--proxy=URL", "--retry=N", "--insecure", "Header: value"]) -> bytes`
- 简介：发送 HTTP GET，返回响应体原始字节（适合二进制内容如图片、压缩包）。
- 参数：
  - `url`：目标 URL
  - `--timeout`：可选超时秒数，默认 30
  - `--proxy`：可选代理 URL，如 http://host:port 或 socks5://host:port
  - `--retry`：可选重试次数，默认 0 不重试
  - `--insecure`：可选开关，跳过 TLS 证书校验（自签名证书 / 内网 HTTPS 测试场景）
  - `header`：可选附加 header
- 返回：bytes 响应体（失败时返回 error 对象）
- 示例：
  - `img := getWebBytes("https://example.com/logo.png")`
- 常见错误：
  - getWebBytes() 第 1 个参数应为 string (URL)
  - getWebBytes() 请求失败（可能原因：URL 格式错误、网络不通、DNS 解析失败、TLS 证书验证失败、代理配置错误、服务器超时）

### `getWebBytesWithHeaders`

- 签名：`getWebBytesWithHeaders(url, headers [, "--timeout=N", "--proxy=URL", "--retry=N", "--insecure"]) -> bytes`
- 简介：带 header 字典的 HTTP GET，返回响应体字节（用于需要鉴权等场景）。
- 参数：
  - `url`：目标 URL
  - `headers`：Map/Object{key: value}，如 {"Authorization": "Bearer xxx"}
  - `--timeout`：可选超时秒数，默认 30
  - `--proxy`：可选代理 URL，如 http://host:port 或 socks5://host:port
  - `--retry`：可选重试次数，默认 0 不重试
  - `--insecure`：可选开关，跳过 TLS 证书校验（自签名证书 / 内网 HTTPS 测试场景）
- 返回：bytes 响应体（失败时返回 error 对象）
- 示例：
  - `data := getWebBytesWithHeaders("https://api.x.com/data", {"Authorization": "Bearer xxx", "Accept": "application/json"})`
- 常见错误：
  - getWebBytesWithHeaders() 第 1 个参数应为 string (URL)（可能原因：参数顺序错误）
  - headers 参数应为 map/object（可能原因：参数类型错误或顺序错误）
  - getWebBytesWithHeaders() 请求失败（可能原因：URL 格式错误、网络不通、TLS 证书验证失败、代理配置错误、header 格式错误）

### `httpServer`

- 签名：`httpServer("--port=N", "--host=H", "--verbose", "--certDir=D", "--adminToken=T") -> server`
- 简介：创建 HTTP/HTTPS 服务器实例（尚未监听，需配合 serverSetHandler + serverStart）。
- 参数：
  - `--port`：监听端口，默认 8080
  - `--host`：监听地址，默认 0.0.0.0
  - `--verbose`：可选开关，打印请求日志
  - `--certDir`：可选 TLS 证书目录（含 server.crt + server.key），设置则启用 HTTPS
  - `--adminToken`：管理端点令牌，默认 sflang
- 返回：SfHttpServer 对象
- 示例：
  - `srv := httpServer("--port=8080")  // 默认 0.0.0.0:8080`
  - `srv := httpServer("--port=443", "--certDir=./certs", "--verbose")  // HTTPS`
- 常见错误：
  - serverStart() 加载 TLS 证书失败（可能原因：certDir 下缺少 server.crt 或 server.key；文件格式非 PEM）

### `httpSession`

- 签名：`httpSession() -> session`
- 简介：创建 Cookie 会话对象（跨请求共享 Cookie Jar），作为位置参数传入 getWeb/postWeb/postForm 即可自动携带与存储 Cookie。
- 返回：session 会话对象
- 示例：
  - `sess := httpSession()`
  - `getWeb(loginUrl, {"user":"a", "pwd":"b"}, sess)   // 登录，Set-Cookie 自动入 Jar`
  - `page := getWeb(protectedUrl, sess)                      // 后续请求自动带 Cookie`
  - `httpSessionDump(sess)                                    // 查看当前 Cookie`

### `httpSessionClear`

- 签名：`httpSessionClear(session) -> undefined`
- 简介：清空会话的 Cookie Jar（例如注销登录后）。
- 参数：
  - `session`：httpSession() 创建的会话对象
- 返回：undefined
- 示例：
  - `httpSessionClear(sess)`
- 常见错误：
  - httpSessionClear() 参数应为 httpSession() 创建的会话对象

### `httpSessionDump`

- 签名：`httpSessionDump(session) -> array`
- 简介：返回会话当前 Cookie 快照（数组，元素为 {domain, path, name, value, expires, secure}），用于调试。
- 参数：
  - `session`：httpSession() 创建的会话对象
- 返回：array of Map{domain, path, name, value, expires, secure}；expires 为过期 Unix 秒，会话 Cookie 为 undefined
- 示例：
  - `plt(httpSessionDump(sess))`
- 常见错误：
  - httpSessionDump() 参数应为 httpSession() 创建的会话对象

### `httpStats`

- 签名：`httpStats() -> object`
- 简介：获取 HTTP 客户端统计快照（自进程启动或上次 resetHttpStats 以来的累计值）。
- 返回：object{totalRequests, successCount, failureCount, retryAttempts, agentPoolSize}（字段可用 .xxx 访问）
- 示例：
  - `stats := httpStats()`
  - `println("总请求:", stats.totalRequests, "成功:", stats.successCount, "失败:", stats.failureCount)`
  - `if stats.failureCount > 0 { println("警告：存在失败请求") }`

### `joinUrlPath`

- 签名：`joinUrlPath(base, path) -> string`
- 简介：拼接 URL 路径，自动避免重复或缺失斜杠。
- 参数：
  - `base`：基础 URL/路径
  - `path`：要追加的路径
- 返回：string 拼接后的路径
- 示例：
  - `joinUrlPath("http://example.com/", "/api/v1")  // "http://example.com/api/v1"`
  - `joinUrlPath("http://example.com", "api/v1")  // "http://example.com/api/v1"`
  - `joinUrlPath("base/", "sub/")  // "base/sub/"`
- 常见错误：
  - joinUrlPath() 需要 2 个参数 (base, path)
  - joinUrlPath() 第 1/2 个参数应为 string

### `parseQuery`

- 签名：`parseQuery(query) -> map`
- 简介：解析 query string（如 a=1&b=2&c=hello%20world）为 Map，支持 + 和 %XX 解码。
- 参数：
  - `query`：query string（不含前导 ?）
- 返回：Map{key: value}
- 示例：
  - `m := parseQuery("a=1&b=2&c=hello%20world")  // {a:"1", b:"2", c:"hello world"}`
- 常见错误：
  - parseQuery() 第 1 个参数应为 string (query string)（可能原因：参数顺序错误）

### `parseReqForm`

- 签名：`parseReqForm(req) -> map`
- 简介：解析表单请求体（application/x-www-form-urlencoded 或 multipart/form-data）。
- 参数：
  - `req`：handler 中的请求对象
- 返回：Map{字段名: value}，文件字段为 object {fileName, size, content(bytes)}
- 示例：
  - `form := parseReqForm(req)  // 普通字段为 string，文件字段为 {fileName, size, content}`
- 常见错误：
  - parseReqForm() 参数不是请求对象
  - parseReqForm() multipart 表单缺少 boundary

### `parseUrl`

- 签名：`parseUrl(url) -> object`
- 简介：解析 URL，返回 {scheme, host, port, path, query, fragment} 对象。
- 参数：
  - `url`：URL 字符串
- 返回：object{scheme, host, port(int), path, query, fragment}（缺失部分为空串，端口为 0）
- 示例：
  - `p := parseUrl("https://a.com:8443/api/x?q=1#top")  // {scheme:"https", host:"a.com", port:8443, path:"/api/x", query:"q=1", fragment:"top"}`
- 常见错误：
  - parseUrl() 第 1 个参数应为 string (URL)

### `postForm`

- 签名：`postForm(url, valuesMap [, filesMap] [, "--timeout=N", "--proxy=URL", "--retry=N", "--insecure", "Header: value"]) -> string`
- 简介：表单 POST：普通字段自动编码为 urlencoded；给出 filesMap 时自动升级为 multipart/form-data 并携带文件；query 参数写在 URL 上即可混合提交。
- 参数：
  - `url`：目标 URL（查询串直接写在 URL 上，如 https://host/japi?src=query）
  - `valuesMap`：Map/Object{name: value}，普通表单字段
  - `filesMap`：可选，Map/Object{fieldName: 值}；值为文件路径 string、object{fileName, content} 或 bytes
  - `--timeout=N`：可选超时秒数，默认 30
  - `--proxy=URL`：可选代理 URL，如 http://host:port 或 socks5://host:port
  - `--retry=N`：可选重试次数，默认 0 不重试
  - `--insecure`：可选开关，跳过 TLS 证书校验
  - `header`：可选附加 header
- 返回：string 响应体（失败时返回 error 对象；4xx/5xx 不算失败）
- 示例：
  - `resp := postForm("https://host/japi?src=query", {"req": "next", "sc": "abc"})  // query + 表单混合`
  - `resp := postForm("https://host/upload", {"title": "照片"}, {"avatar": "C:/pic.jpg"})  // 带文件 → multipart`
  - `resp := postForm("https://host/upload", {}, {"blob": {"fileName": "a.bin", "content": dataBytes}})  // 内存字节`
- 常见错误：
  - postForm() 需要至少 2 个参数 (url, valuesMap)
  - postForm() 出现了多个 Map 参数（可能原因：filesMap 应为第 3 个参数）
  - postForm() 读取文件失败（可能原因：路径不存在或无读取权限）
  - postForm() 请求失败（可能原因：URL 格式错误、网络不通、TLS 证书验证失败、代理配置错误、服务器拒绝）

### `postJson`

- 签名：`postJson(url, jsonBody [, "--timeout=N", "--proxy=URL", "--retry=N", "Header: value"]) -> string`
- 简介：发送 JSON POST（postWeb 的便捷封装，Content-Type 固定为 application/json）。
- 参数：
  - `url`：目标 URL
  - `jsonBody`：JSON 字符串请求体
  - `options`：可选，同 postWeb 的其余参数
- 返回：string 响应体（失败时返回 error 对象）
- 示例：
  - `postJson("https://api.example.com/login", "{\"account\":\"a\",\"pwd\":\"b\"}")`
- 常见错误：
  - 网络失败或非 2xx 返回 error 对象（同 postWeb）

### `postWeb`

- 签名：`postWeb(url, body, contentType [, "--timeout=N", "--proxy=URL", "--retry=N", "--insecure", "Header: value"]) -> string`
- 简介：发送 HTTP POST，返回响应体字符串。
- 参数：
  - `url`：目标 URL
  - `body`：请求体（string/bytes/byteArray 或可转字符串的值）
  - `contentType`：Content-Type，如 application/json
  - `--timeout`：可选超时秒数，默认 30
  - `--proxy`：可选代理 URL，如 http://host:port 或 socks5://host:port
  - `--retry`：可选重试次数，默认 0 不重试；4xx（除 429）不重试
  - `--insecure`：可选开关，跳过 TLS 证书校验（自签名证书 / 内网 HTTPS 测试场景）
  - `header`：可选附加 header
- 返回：string 响应体（失败时返回 error 对象）
- 示例：
  - `resp := postWeb("https://api.x.com", jsonEncode({a:1}), "application/json")`
  - `resp := postWeb("https://api.x.com", body, "application/json", "--retry=2")  // 重试 2 次`
- 常见错误：
  - postWeb() 需要至少 3 个参数 (URL, body, contentType)
  - postWeb() 第 3 个参数应为 string (Content-Type)
  - postWeb() 请求失败（可能原因：URL 格式错误、网络不通、TLS 证书验证失败、代理配置错误、服务器拒绝、Content-Type 不匹配）

### `prepareMultiPartFieldFromBytes`

- 签名：`prepareMultiPartFieldFromBytes(fieldName, fileName, data, contentType) -> bytes`
- 简介：构建 multipart/form-data 的一个字段字节块（使用固定 boundary）。调用方需用相同 boundary 拼接多字段并设置 Content-Type。
- 参数：
  - `fieldName`：表单字段名
  - `fileName`：上传文件名
  - `data`：字段内容 bytes/byteArray/string
  - `contentType`：该字段的 Content-Type
- 返回：bytes 该字段的完整 multipart 字节（含分隔符和头）
- 示例：
  - `b := prepareMultiPartFieldFromBytes("file", "a.txt", fileBytes, "text/plain")`
- 常见错误：
  - prepareMultiPartFieldFromBytes() 需要 4 个参数 (fieldName, fileName, bytes, contentType)
  - prepareMultiPartFieldFromBytes() 第 1 个参数应为 string (字段名)（可能原因：参数顺序错误）
  - prepareMultiPartFieldFromBytes() 第 3 个参数应为 bytes/byteArray/string

### `redirectResp`

- 签名：`redirectResp(resp, url [, code]) -> undefined`
- 简介：设置重定向响应，默认状态码 302。
- 参数：
  - `resp`：handler 中的响应对象
  - `url`：目标 URL
  - `code`：可选状态码，默认 302（int/float）
- 返回：undefined
- 示例：
  - `redirectResp(resp, "https://example.com")  // 302 跳转`
  - `redirectResp(resp, "/login", 301)  // 永久重定向`
- 常见错误：
  - redirectResp() 第 2 个参数应为 string (URL)

### `resetHttpStats`

- 签名：`resetHttpStats() -> undefined`
- 简介：重置 HTTP 客户端统计计数器（不影响 Agent 池）。
- 返回：undefined
- 示例：
  - `resetHttpStats()  // 重置后 httpStats() 从 0 开始计数`

### `saveFileUploads`

- 签名：`saveFileUploads(req, destDir [, "--fieldName=name"]) -> map`
- 简介：将 multipart 表单中的文件字段保存到磁盘，返回字段名 -> {fileName, savedPath, size}。
- 参数：
  - `req`：handler 中的请求对象，必须为 multipart/form-data
  - `destDir`：目标目录（不存在则自动创建）
  - `--fieldName`：可选只保存指定字段名
- 返回：Map{字段名: {fileName, savedPath, size}}（非文件字段和空文件名被跳过）
- 示例：
  - `saved := saveFileUploads(req, "/tmp/uploads", "--fieldName=avatar")  // 只保存 avatar 字段`
- 常见错误：
  - saveFileUploads() 要求 multipart/form-data 请求（可能原因：未设置 enctype 或未使用 multipart 表单）
  - saveFileUploads() multipart 表单缺少 boundary
  - saveFileUploads() 创建目录失败
  - saveFileUploads() 写入文件失败（可能原因：磁盘空间不足或权限不足）

### `serveFile`

- 签名：`serveFile(resp, filePath) -> undefined`
- 简介：将本地文件作为响应输出，自动按扩展名设置 Content-Type（未设置时）。
- 参数：
  - `resp`：handler 中的响应对象
  - `filePath`：本地文件路径
- 返回：undefined（失败时返回 error 对象）
- 示例：
  - `serveFile(resp, "/var/www/logo.png")  // 自动设 Content-Type 为 image/png`
- 常见错误：
  - serveFile() 读取文件 'xxx' 失败（可能原因：文件不存在或权限不足）
  - serveFile() 第 2 个参数应为 string (文件路径)

### `serverAddr`

- 签名：`serverAddr(server) -> string`
- 简介：返回服务器的监听地址（host:port）。
- 参数：
  - `server`：httpServer 返回的对象
- 返回：string，如 "0.0.0.0:8080"
- 示例：
  - `addr := serverAddr(srv)  // "0.0.0.0:8080"`
- 常见错误：
  - serverAddr() 参数不是 HTTP 服务器对象

### `serverSetHandler`

- 签名：`serverSetHandler(server, path, handler) -> undefined`
- 简介：注册路由处理器，路径可含 :param 参数（如 /api/users/:id），自动注入 routeParamsG。
- 参数：
  - `server`：httpServer 返回的对象
  - `path`：路径模式，以 / 结尾为前缀匹配，否则精确匹配；支持 :param
  - `handler`：func(req, resp) 处理函数
- 返回：undefined
- 示例：
  - `serverSetHandler(srv, "/hello", func(req, resp) { return "Hello!" })  // 精确匹配`
  - `serverSetHandler(srv, "/api/users/:id", func(req, resp) { return getGlobal("routeParamsG")["id"] })  // 参数路由`
- 常见错误：
  - serverSetHandler() 第 2 个参数应为 string (路径)
  - serverSetHandler() 第 3 个参数应为 function（可能原因：未传入 func 或函数名拼写错误）

### `serverSetStatic`

- 签名：`serverSetStatic(server, dirPath) -> undefined`
- 简介：设置静态文件根目录，未命中路由的请求会从该目录读取文件。
- 参数：
  - `server`：httpServer 返回的对象
  - `dirPath`：静态文件根目录路径
- 返回：undefined
- 示例：
  - `serverSetStatic(srv, "./public")  // ./public 下文件可被直接访问`
- 常见错误：
  - serverSetStatic() 第 2 个参数应为 string (目录路径)

### `serverStart`

- 签名：`serverStart(server [, "--thread"]) -> undefined`
- 简介：启动服务器，默认阻塞当前线程，加 --thread/--go 在后台线程运行。
- 参数：
  - `server`：httpServer 返回的对象
  - `--thread/--go`：可选开关，后台线程运行而非阻塞
- 返回：undefined（阻塞模式下服务器停止后返回）
- 示例：
  - `serverStart(srv)  // 阻塞当前线程`
  - `serverStart(srv, "--thread")  // 后台运行，主线程可继续`
- 常见错误：
  - serverStart() 服务器已在运行
  - serverStart() 加载 TLS 证书失败（可能原因：certDir 下缺少 server.crt 或 server.key；文件格式非 PEM）

### `serverStop`

- 签名：`serverStop(server) -> undefined`
- 简介：停止服务器，设置停止信号使 accept 循环退出。
- 参数：
  - `server`：httpServer 返回的对象
- 返回：undefined
- 示例：
  - `serverStop(srv)  // 停止监听`
- 常见错误：
  - serverStop() 参数不是 HTTP 服务器对象（可能原因：传入了错误类型）

### `setCorsHeaders`

- 签名：`setCorsHeaders(resp, origin) -> undefined`
- 简介：设置全套 CORS 响应头（Allow-Origin/Methods/Headers/Credentials/Max-Age）。
- 参数：
  - `resp`：handler 中的响应对象
  - `origin`：允许的来源，"*" 表示所有
- 返回：undefined
- 示例：
  - `setCorsHeaders(resp, "https://example.com")  // 单一来源`
  - `setCorsHeaders(resp, "*")  // 允许所有来源`
- 常见错误：
  - setCorsHeaders() 需要 2 个参数 (resp, origin)
  - setCorsHeaders() 第 2 个参数应为 string (origin)

### `setRespContentType`

- 签名：`setRespContentType(resp, contentType) -> undefined`
- 简介：设置 Content-Type 响应头（setRespHeader 的便捷封装）。
- 参数：
  - `resp`：handler 中的响应对象
  - `contentType`：MIME 类型，如 application/json
- 返回：undefined
- 示例：
  - `setRespContentType(resp, "application/json; charset=utf-8")`
- 常见错误：
  - setRespContentType() 第 2 个参数应为 string

### `setRespCookie`

- 签名：`setRespCookie(resp, name, value [, --path=, --domain=, --maxAge=, --expires=, --httpOnly, --secure, --sameSite=]) -> undefined`
- 简介：设置响应的 Set-Cookie 头，支持 Path/Domain/MaxAge/Expires/HttpOnly/Secure/SameSite 属性。
- 参数：
  - `resp`：handler 中的响应对象
  - `name`：cookie 名称
  - `value`：cookie 值
  - `--path`：可选 Path 属性
  - `--domain`：可选 Domain 属性
  - `--maxAge`：可选 Max-Age 秒数
  - `--expires`：可选 Expires（RFC1123 日期）
  - `--httpOnly`：可选开关，加 HttpOnly 标志
  - `--secure`：可选开关，加 Secure 标志
  - `--sameSite`：可选 Strict/Lax/None
- 返回：undefined
- 示例：
  - `setRespCookie(resp, "token", "abc", "--path=/", "--maxAge=3600", "--httpOnly", "--secure", "--sameSite=strict")`
- 常见错误：
  - setRespCookie() 至少需要 3 个参数 (resp, name, value)
  - setRespCookie() 第 2 个参数应为 string (cookie 名)

### `setRespHeader`

- 签名：`setRespHeader(resp, key, value) -> undefined`
- 简介：设置响应头。
- 参数：
  - `resp`：handler 中的响应对象
  - `key`：header 名
  - `value`：header 值（string 或可转字符串的值）
- 返回：undefined
- 示例：
  - `setRespHeader(resp, "Content-Type", "application/json")`
- 常见错误：
  - setRespHeader() 第 2 个参数应为 string (header 名)

### `setRespStatus`

- 签名：`setRespStatus(resp, status) -> undefined`
- 简介：设置响应状态码。
- 参数：
  - `resp`：handler 中的响应对象
  - `status`：HTTP 状态码（int/float）
- 返回：undefined
- 示例：
  - `setRespStatus(resp, 404)`
- 常见错误：
  - setRespStatus() 第 2 个参数应为 int (状态码)

### `urlExists`

- 签名：`urlExists(url) -> bool`
- 简介：检查 URL 是否可访问（状态码 < 400 视为存在，超时 10 秒）。
- 参数：
  - `url`：目标 URL
- 返回：bool：true 表示状态码 < 400，请求失败返回 false
- 示例：
  - `if urlExists("https://example.com") { ... }`
- 常见错误：
  - urlExists() 第 1 个参数应为 string (URL)

### `webSocket`

- 签名：`webSocket(url) -> ws`
- 简介：以客户端模式连接到远程 WebSocket 服务器（ws://host:port/path）。
- 参数：
  - `url`：ws:// 协议的 URL
- 返回：WebSocket 对象（服务端模式暂不支持在 handler 内升级）
- 示例：
  - `ws := webSocket("ws://echo.example.com:9001/ws")  // 连接 echo 服务器`
- 常见错误：
  - webSocket() URL 解析失败（可能原因：URL 格式应为 ws://host:port/path）
  - webSocket() TCP 连接失败（可能原因：服务器未启动、网络不通、防火墙拦截）
  - webSocket() 握手失败（可能原因：服务器不支持 WebSocket、路径错误）

### `writeResp`

- 签名：`writeResp(resp, content) -> undefined`
- 简介：写入响应体（string 或任意会转字符串的值），自动设为响应内容。
- 参数：
  - `resp`：handler 中的响应对象
  - `content`：响应内容（string 或其他会转字符串的类型）
- 返回：undefined
- 示例：
  - `writeResp(resp, "<h1>Hi</h1>")`
- 常见错误：
  - writeResp() 参数不是响应对象

### `writeRespBytes`

- 签名：`writeRespBytes(resp, data) -> undefined`
- 简介：写入二进制响应体（bytes/byteArray/string）。
- 参数：
  - `resp`：handler 中的响应对象
  - `data`：bytes / byteArray / string
- 返回：undefined
- 示例：
  - `writeRespBytes(resp, fileBytes)`
- 常见错误：
  - writeRespBytes() 第 2 个参数应为 bytes/byteArray/string

### `writeRespHeader`

- 签名：`writeRespHeader(resp, status) -> undefined`
- 简介：设置响应状态码（兼容 Charlang 函数名，等价于 setRespStatus）。
- 参数：
  - `resp`：handler 中的响应对象
  - `status`：HTTP 状态码（int/float）
- 返回：undefined
- 示例：
  - `writeRespHeader(resp, 200)`
- 常见错误：
  - writeRespHeader() 第 2 个参数应为 int (状态码)

### `wsClose`

- 签名：`wsClose(ws) -> undefined`
- 简介：关闭 WebSocket 连接（发送 Close 帧并关闭底层流）。
- 参数：
  - `ws`：webSocket 返回的对象
- 返回：undefined
- 示例：
  - `wsClose(ws)`
- 常见错误：
  - 参数应为 webSocket 对象

### `wsLocalAddr`

- 签名：`wsLocalAddr(ws) -> undefined`
- 简介：返回本地地址（当前实现固定返回 undefined，仅做接口兼容）。
- 参数：
  - `ws`：webSocket 返回的对象
- 返回：undefined
- 示例：
  - `addr := wsLocalAddr(ws)  // 当前恒为 undefined`
- 常见错误：
  - 参数应为 webSocket 对象

### `wsReadBin`

- 签名：`wsReadBin(ws) -> bytes|undefined`
- 简介：读取下一条二进制消息（跳过 Ping/Pong/Text），连接关闭返回 undefined。
- 参数：
  - `ws`：webSocket 返回的对象
- 返回：bytes 二进制消息，关闭时 undefined
- 示例：
  - `b := wsReadBin(ws)`
- 常见错误：
  - wsReadBin() 读取失败（可能原因：连接已关闭）
  - 参数应为 webSocket 对象

### `wsReadMsg`

- 签名：`wsReadMsg(ws) -> [type, data]`
- 简介：读取一条 WebSocket 消息，返回 [type, data]，type 为 1=文本/2=二进制/0=关闭。
- 参数：
  - `ws`：webSocket 返回的对象
- 返回：array [type(int), data(string|bytes)]，关闭帧返回 [0, "closed"]
- 示例：
  - `msg := wsReadMsg(ws)  // [1, "hello"] 或 [2, bytes]`
- 常见错误：
  - wsReadMsg() 读取失败（可能原因：连接已关闭、网络中断）
  - 参数应为 webSocket 对象（可能原因：未先调用 webSocket() 建立连接）

### `wsReadText`

- 签名：`wsReadText(ws) -> string|undefined`
- 简介：读取下一条文本消息（跳过 Ping/Pong/Binary），连接关闭返回 undefined。
- 参数：
  - `ws`：webSocket 返回的对象
- 返回：string 文本消息，关闭时 undefined
- 示例：
  - `t := wsReadText(ws)  // 读取一行文本`
- 常见错误：
  - wsReadText() 读取失败（可能原因：连接已关闭）
  - 参数应为 webSocket 对象

### `wsWriteBin`

- 签名：`wsWriteBin(ws, data) -> undefined`
- 简介：发送一条二进制消息。
- 参数：
  - `ws`：webSocket 返回的对象
  - `data`：bytes / byteArray / string
- 返回：undefined
- 示例：
  - `wsWriteBin(ws, fileBytes)`
- 常见错误：
  - wsWriteBin() 第 2 个参数应为 bytes/byteArray/string
  - wsWriteBin() 发送失败（可能原因：连接已关闭）

### `wsWriteMsg`

- 签名：`wsWriteMsg(ws, type, data) -> undefined`
- 简介：发送一条消息（手动指定类型），type=1 文本、2 二进制。
- 参数：
  - `ws`：webSocket 返回的对象
  - `type`：1=文本，2=二进制
  - `data`：文本或二进制数据
- 返回：undefined
- 示例：
  - `wsWriteMsg(ws, 1, "ping")  // 发文本`
- 常见错误：
  - wsWriteMsg() 第 2 个参数应为 int (类型: 1=文本, 2=二进制)
  - wsWriteMsg() 类型码 N 无效 (1=文本, 2=二进制)
  - wsWriteMsg() 二进制消息需要 bytes/string

### `wsWriteText`

- 签名：`wsWriteText(ws, text) -> undefined`
- 简介：发送一条文本消息。
- 参数：
  - `ws`：webSocket 返回的对象
  - `text`：要发送的文本（string 或可转字符串的值）
- 返回：undefined
- 示例：
  - `wsWriteText(ws, "hello")`
- 常见错误：
  - wsWriteText() 发送失败（可能原因：连接已关闭）
  - 参数应为 webSocket 对象

## image（62 个）

### `canvasClear`

- 签名：`canvasClear(canvas, color?) -> undefined`
- 简介：清空画布（默认清为透明，可指定颜色）。
- 参数：
  - `canvas`：canvas 画布对象
  - `color`：可选清空颜色，缺省透明 [0,0,0,0]
- 返回：undefined
- 示例：
  - `canvasClear(c)  // 透明`
  - `canvasClear(c, [255,255,255,255])  // 白色`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasDrawCircle`

- 签名：`canvasDrawCircle(canvas, cx, cy, radius, color) -> undefined`
- 简介：画圆边框（中点画圆算法）。
- 参数：
  - `canvas`：canvas 画布对象
  - `cx, cy`：圆心坐标
  - `radius`：半径
  - `color`：边框颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawCircle(c, 50, 50, 30, [255,0,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasDrawEllipse`

- 签名：`canvasDrawEllipse(canvas, cx, cy, rx, ry, color) -> undefined`
- 简介：画椭圆边框。
- 参数：
  - `canvas`：canvas 画布对象
  - `cx, cy`：中心坐标
  - `rx`：水平半径
  - `ry`：垂直半径
  - `color`：边框颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawEllipse(c, 50, 50, 40, 20, [0,0,255,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误
  - rx/ry <= 0 时不绘制

### `canvasDrawGradient`

- 签名：`canvasDrawGradient(canvas, x, y, w, h, color1, color2, direction) -> undefined`
- 简介：画线性渐变矩形。
- 参数：
  - `canvas`：canvas 画布对象
  - `x, y`：左上角坐标
  - `w`：宽度
  - `h`：高度
  - `color1`：起始颜色 [r,g,b,a]
  - `color2`：结束颜色 [r,g,b,a]
  - `direction`："h" 水平渐变 或 "v" 垂直渐变
- 返回：undefined
- 示例：
  - `canvasDrawGradient(c, 0, 0, 100, 100, [255,0,0,255], [0,0,255,255], "h")`
- 常见错误：
  - canvas 不是画布对象
  - direction 必须是 "h" 或 "v"

### `canvasDrawImage`

- 签名：`canvasDrawImage(canvas, img, x, y) -> undefined`
- 简介：在画布上绘制图片（透明像素跳过）。
- 参数：
  - `canvas`：canvas 画布对象
  - `img`：要绘制的 image 对象
  - `x, y`：绘制左上角坐标
- 返回：undefined
- 示例：
  - `canvasDrawImage(c, sprite, 10, 10)`
- 常见错误：
  - canvas 不是画布对象
  - img 不是 image 对象

### `canvasDrawLine`

- 签名：`canvasDrawLine(canvas, x1, y1, x2, y2, color) -> undefined`
- 简介：画线段（Bresenham 算法，单像素宽）。
- 参数：
  - `canvas`：canvas 画布对象
  - `x1, y1`：起点坐标
  - `x2, y2`：终点坐标
  - `color`：线条颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawLine(c, 0, 0, 100, 100, [255,0,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误
  - 越界坐标自动跳过

### `canvasDrawLineW`

- 签名：`canvasDrawLineW(canvas, x1, y1, x2, y2, width, color) -> undefined`
- 简介：画带宽度的线段（圆刷模拟笔触）。
- 参数：
  - `canvas`：canvas 画布对象
  - `x1, y1`：起点坐标
  - `x2, y2`：终点坐标
  - `width`：线条宽度（像素）
  - `color`：线条颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawLineW(c, 0, 0, 100, 100, 3, [0,0,255,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasDrawRect`

- 签名：`canvasDrawRect(canvas, x, y, width, height, color) -> undefined`
- 简介：画矩形边框。
- 参数：
  - `canvas`：canvas 画布对象
  - `x, y`：左上角坐标
  - `width`：矩形宽度
  - `height`：矩形高度
  - `color`：边框颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawRect(c, 10, 10, 80, 40, [255,0,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasDrawRoundRect`

- 签名：`canvasDrawRoundRect(canvas, x, y, width, height, radius, color) -> undefined`
- 简介：画圆角矩形边框。
- 参数：
  - `canvas`：canvas 画布对象
  - `x, y`：左上角坐标
  - `width`：矩形宽度
  - `height`：矩形高度
  - `radius`：圆角半径（自动限制为不超过宽高的一半）
  - `color`：边框颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawRoundRect(c, 10, 10, 80, 40, 8, [0,0,255,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasDrawText`

- 签名：`canvasDrawText(canvas, x, y, text, color, fontSize?, font?) -> undefined`
- 简介：在画布上绘制文字（抗锯齿）。
- 参数：
  - `canvas`：canvas 画布对象
  - `x, y`：文字基线左上角坐标
  - `text`：要绘制的字符串
  - `color`：文字颜色 [r,g,b,a]
  - `fontSize`：可选字号（默认 16）
  - `font`：可选 loadFont 返回的字体对象，缺省用系统字体
- 返回：undefined
- 示例：
  - `canvasDrawText(c, 10, 10, "Hello", [0,0,0,255])`
  - `canvasDrawText(c, 10, 10, "大字", [255,0,0,255], 32)`
  - `var f = loadFont("arial.ttf")`
  - `canvasDrawText(c, 10, 10, "Hi", [0,0,0,255], 20, f)`
- 常见错误：
  - canvas 不是画布对象
  - 未找到系统默认字体时需用 loadFont 加载后作为第 7 参数传入
  - 字体文件不存在或损坏

### `canvasDrawTriangle`

- 签名：`canvasDrawTriangle(canvas, x1, y1, x2, y2, x3, y3, color) -> undefined`
- 简介：画三角形边框（连接三个顶点）。
- 参数：
  - `canvas`：canvas 画布对象
  - `x1, y1`：顶点 1
  - `x2, y2`：顶点 2
  - `x3, y3`：顶点 3
  - `color`：边框颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasDrawTriangle(c, 50,0, 0,100, 100,100, [255,0,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasFill`

- 签名：`canvasFill(canvas, color) -> undefined`
- 简介：用指定颜色填充整个画布。
- 参数：
  - `canvas`：canvas 画布对象
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasFill(c, [255,255,255,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasFillCircle`

- 签名：`canvasFillCircle(canvas, cx, cy, radius, color) -> undefined`
- 简介：填充实心圆。
- 参数：
  - `canvas`：canvas 画布对象
  - `cx, cy`：圆心坐标
  - `radius`：半径
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasFillCircle(c, 50, 50, 30, [0,255,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasFillEllipse`

- 签名：`canvasFillEllipse(canvas, cx, cy, rx, ry, color) -> undefined`
- 简介：填充实心椭圆。
- 参数：
  - `canvas`：canvas 画布对象
  - `cx, cy`：中心坐标
  - `rx`：水平半径
  - `ry`：垂直半径
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasFillEllipse(c, 50, 50, 40, 20, [255,0,255,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误
  - rx/ry <= 0 时不绘制

### `canvasFillRect`

- 签名：`canvasFillRect(canvas, x, y, width, height, color) -> undefined`
- 简介：填充矩形。
- 参数：
  - `canvas`：canvas 画布对象
  - `x, y`：左上角坐标
  - `width`：矩形宽度
  - `height`：矩形高度
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasFillRect(c, 10, 10, 80, 40, [0,255,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasFillRoundRect`

- 签名：`canvasFillRoundRect(canvas, x, y, width, height, radius, color) -> undefined`
- 简介：填充圆角矩形。
- 参数：
  - `canvas`：canvas 画布对象
  - `x, y`：左上角坐标
  - `width`：矩形宽度
  - `height`：矩形高度
  - `radius`：圆角半径（自动限制为不超过宽高的一半）
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasFillRoundRect(c, 10, 10, 80, 40, 8, [255,128,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误

### `canvasFillTriangle`

- 签名：`canvasFillTriangle(canvas, x1, y1, x2, y2, x3, y3, color) -> undefined`
- 简介：填充三角形（重心坐标法）。
- 参数：
  - `canvas`：canvas 画布对象
  - `x1, y1`：顶点 1
  - `x2, y2`：顶点 2
  - `x3, y3`：顶点 3
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasFillTriangle(c, 50,0, 0,100, 100,100, [0,255,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - color 格式错误
  - 三点共线时不绘制

### `canvasFromImage`

- 签名：`canvasFromImage(img) -> canvas`
- 简介：从图片创建画布（拷贝像素数据以便绘图）。
- 参数：
  - `img`：image 图片对象
- 返回：canvas 与原图相同像素的画布
- 示例：
  - `c := canvasFromImage(img)`
- 常见错误：
  - img 不是 image 对象

### `canvasGetHeight`

- 签名：`canvasGetHeight(canvas) -> int`
- 简介：获取画布高度。
- 参数：
  - `canvas`：canvas 画布对象
- 返回：int 像素高度
- 示例：
  - `var h = canvasGetHeight(c)`
- 常见错误：
  - canvas 不是画布对象

### `canvasGetPixel`

- 签名：`canvasGetPixel(canvas, x, y) -> [r,g,b,a]`
- 简介：获取画布指定坐标的像素颜色。
- 参数：
  - `canvas`：canvas 画布对象
  - `x`：X 坐标（从 0 开始）
  - `y`：Y 坐标（从 0 开始）
- 返回：[r,g,b,a] 颜色数组
- 示例：
  - `var px = canvasGetPixel(c, 5, 5)`
- 常见错误：
  - canvas 不是画布对象
  - 坐标超出画布范围

### `canvasGetWidth`

- 签名：`canvasGetWidth(canvas) -> int`
- 简介：获取画布宽度。
- 参数：
  - `canvas`：canvas 画布对象
- 返回：int 像素宽度
- 示例：
  - `var w = canvasGetWidth(c)`
- 常见错误：
  - canvas 不是画布对象

### `canvasMeasureText`

- 签名：`canvasMeasureText(text, fontSize?, font?) -> [width, height]`
- 简介：测量文字尺寸（不实际绘制）。
- 参数：
  - `text`：要测量的字符串
  - `fontSize`：可选字号（默认 16）
  - `font`：可选 loadFont 返回的字体对象，缺省用系统字体
- 返回：[width, height] 文字宽高（像素）
- 示例：
  - `var size = canvasMeasureText("Hello", 20)`
  - `var w = size[0]  // 文字宽度`
- 常见错误：
  - 未找到系统默认字体时需用 loadFont 加载后作为第 3 参数传入
  - 字体文件不存在或损坏

### `canvasNew`

- 签名：`canvasNew(width, height, bgColor?) -> canvas`
- 简介：创建新画布（纯色填充）。
- 参数：
  - `width`：宽度（像素，>0）
  - `height`：高度（像素，>0）
  - `bgColor`：可选背景色 [r,g,b,a]，缺省透明
- 返回：canvas 画布对象（用于绘图）
- 示例：
  - `c := canvasNew(200, 200, [0,0,0,255])`
- 常见错误：
  - width/height 不能为 0

### `canvasSetPixel`

- 签名：`canvasSetPixel(canvas, x, y, color) -> undefined`
- 简介：设置画布指定坐标的像素颜色。
- 参数：
  - `canvas`：canvas 画布对象
  - `x`：X 坐标（从 0 开始）
  - `y`：Y 坐标（从 0 开始）
  - `color`：颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `canvasSetPixel(c, 5, 5, [255,0,0,255])`
- 常见错误：
  - canvas 不是画布对象
  - 坐标超出画布范围
  - color 格式错误

### `canvasToImage`

- 签名：`canvasToImage(canvas) -> image`
- 简介：画布转图片（用于保存/滤镜）。
- 参数：
  - `canvas`：canvas 画布对象
- 返回：image 与画布相同像素的图片
- 示例：
  - `img := canvasToImage(c)`
- 常见错误：
  - canvas 不是画布对象

### `colorBlend`

- 签名：`colorBlend(color1, color2, ratio) -> [r,g,b,a]`
- 简介：按比例混合两种颜色。
- 参数：
  - `color1`：第一个颜色 [r,g,b,a]
  - `color2`：第二个颜色 [r,g,b,a]
  - `ratio`：混合比例（0.0 完全用 color1，1.0 完全用 color2）
- 返回：[r,g,b,a] 混合后的颜色
- 示例：
  - `colorBlend([0,0,0,255], [255,255,255,255], 0.5)  // 中灰色`
- 常见错误：
  - color1/color2 不是颜色数组
  - ratio 超出 [0,1] 自动截断

### `colorFromHex`

- 签名：`colorFromHex(hex) -> [r,g,b,a]`
- 简介：从十六进制字符串创建颜色。
- 参数：
  - `hex`：十六进制颜色字符串，支持 "#rrggbb"/"rrggbb"/"#rrggbbaa"
- 返回：[r,g,b,a] 颜色数组
- 示例：
  - `colorFromHex("#ff0000")  // [255,0,0,255]`
  - `colorFromHex("ff0000")  // 同上，# 可省`
  - `colorFromHex("#ff000080")  // [255,0,0,128] 半透明`
- 常见错误：
  - 格式必须为 #rrggbb 或 #rrggbbaa（6 或 8 位十六进制）

### `colorNew`

- 签名：`colorNew(r, g, b, a?) -> [r,g,b,a]`
- 简介：创建颜色数组（各分量限制到 0-255）。
- 参数：
  - `r`：红色 0-255
  - `g`：绿色 0-255
  - `b`：蓝色 0-255
  - `a`：可选 alpha 0-255（默认 255）
- 返回：[r,g,b,a] 颜色数组
- 示例：
  - `colorNew(255, 0, 0)  // [255,0,0,255]`
  - `colorNew(255, 0, 0, 128)  // 半透明红`
- 常见错误：
  - r/g/b/a 应为数字（超出范围自动截断）

### `colorToHex`

- 签名：`colorToHex(color) -> string`
- 简介：颜色转十六进制字符串。
- 参数：
  - `color`：颜色 [r,g,b] 或 [r,g,b,a]
- 返回：string 形如 "#rrggbbaa" 的十六进制字符串
- 示例：
  - `var s = colorToHex([255,0,0,255])  // "#ff0000ff"`
- 常见错误：
  - color 不是数组或长度不足 3

### `imageBlend`

- 签名：`imageBlend(baseImg, overlayImg, x, y) -> image`
- 简介：将叠加图绘制到基础图上（alpha 混合）。
- 参数：
  - `baseImg`：基础 image 对象
  - `overlayImg`：叠加 image 对象
  - `x`：叠加左上角 X
  - `y`：叠加左上角 Y
- 返回：image 混合后的新图片（半透明像素自动 alpha 混合）
- 示例：
  - `result := imageBlend(bg, logo, 10, 10)`
- 常见错误：
  - 参数不是 image 对象

### `imageBlur`

- 签名：`imageBlur(img, sigma) -> image`
- 简介：高斯模糊。
- 参数：
  - `img`：image 图片对象
  - `sigma`：模糊半径，越大越模糊（通常 1.0-10.0，>=0）
- 返回：image 模糊后的新图片
- 示例：
  - `blurry := imageBlur(img, 3.0)`
- 常见错误：
  - img 不是 image 对象
  - sigma 不能为负数

### `imageBrightness`

- 签名：`imageBrightness(img, factor) -> image`
- 简介：调整亮度。
- 参数：
  - `img`：image 图片对象
  - `factor`：亮度增量（-255 到 255，正值变亮，负值变暗）
- 返回：image 调整后的新图片
- 示例：
  - `bright := imageBrightness(img, 50)`
  - `dark := imageBrightness(img, -50)`
- 常见错误：
  - img 不是 image 对象

### `imageClone`

- 签名：`imageClone(img) -> image`
- 简介：深拷贝图片（返回独立副本）。
- 参数：
  - `img`：image 图片对象
- 返回：image 与原图互不影响的新图片
- 示例：
  - `var copy = imageClone(img)`
- 常见错误：
  - img 不是 image 对象

### `imageContrast`

- 签名：`imageContrast(img, factor) -> image`
- 简介：调整对比度。
- 参数：
  - `img`：image 图片对象
  - `factor`：对比度系数（float，正值增加对比度，负值降低）
- 返回：image 调整后的新图片
- 示例：
  - `result := imageContrast(img, 1.5)`
- 常见错误：
  - img 不是 image 对象

### `imageConvolve3x3`

- 签名：`imageConvolve3x3(img, kernel) -> image`
- 简介：自定义 3x3 卷积核滤镜。
- 参数：
  - `img`：image 图片对象
  - `kernel`：9 个数字的数组 [k0..k8]，对应 3x3 矩阵，自动归一化
- 返回：image 卷积后的新图片
- 示例：
  - `// 模糊核`
  - `blurry := imageConvolve3x3(img, [1,1,1, 1,1,1, 1,1,1])`
- 常见错误：
  - img 不是 image 对象
  - kernel 必须为恰好 9 元素的数字数组

### `imageCrop`

- 签名：`imageCrop(img, x, y, width, height) -> image`
- 简介：裁剪图片。
- 参数：
  - `img`：image 图片对象
  - `x`：裁剪区左上角 X
  - `y`：裁剪区左上角 Y
  - `width`：裁剪区宽度
  - `height`：裁剪区高度
- 返回：image 裁剪后的新图片
- 示例：
  - `sub := imageCrop(img, 10, 10, 100, 100)`
- 常见错误：
  - img 不是 image 对象
  - 裁剪区域超出图片范围

### `imageEdgeDetect`

- 签名：`imageEdgeDetect(img) -> image`
- 简介：边缘检测（Sobel 算子）。
- 参数：
  - `img`：image 图片对象
- 返回：image 边缘高亮的灰度图片
- 示例：
  - `edges := imageEdgeDetect(img)`
- 常见错误：
  - img 不是 image 对象
  - 图片小于 3x3 时返回灰度原图

### `imageFill`

- 签名：`imageFill(img, color) -> undefined`
- 简介：用指定颜色填充整个图片。
- 参数：
  - `img`：image 图片对象
  - `color`：填充颜色 [r,g,b,a]
- 返回：undefined
- 示例：
  - `imageFill(img, [0,0,0,255])`
- 常见错误：
  - img 不是 image 对象
  - color 格式错误

### `imageFlipH`

- 签名：`imageFlipH(img) -> image`
- 简介：水平翻转图片（左右镜像）。
- 参数：
  - `img`：image 图片对象
- 返回：image 翻转后的新图片
- 示例：
  - `mirrored := imageFlipH(img)`
- 常见错误：
  - img 不是 image 对象

### `imageFlipV`

- 签名：`imageFlipV(img) -> image`
- 简介：垂直翻转图片（上下镜像）。
- 参数：
  - `img`：image 图片对象
- 返回：image 翻转后的新图片
- 示例：
  - `mirrored := imageFlipV(img)`
- 常见错误：
  - img 不是 image 对象

### `imageGamma`

- 签名：`imageGamma(img, gamma) -> image`
- 简介：伽马校正。
- 参数：
  - `img`：image 图片对象
  - `gamma`：伽马值（>0，>1 变亮，<1 变暗，1 不变）
- 返回：image 校正后的新图片
- 示例：
  - `bright := imageGamma(img, 2.0)`
  - `dark := imageGamma(img, 0.5)`
- 常见错误：
  - img 不是 image 对象
  - gamma 必须 > 0

### `imageGetHeight`

- 签名：`imageGetHeight(img) -> int`
- 简介：获取图片高度。
- 参数：
  - `img`：image 图片对象
- 返回：int 像素高度
- 示例：
  - `var h = imageGetHeight(img)`
- 常见错误：
  - img 不是 image 对象（应先用 imageLoad/imageNew 创建）

### `imageGetPixel`

- 签名：`imageGetPixel(img, x, y) -> [r,g,b,a]`
- 简介：获取指定坐标的像素颜色。
- 参数：
  - `img`：image 图片对象
  - `x`：X 坐标（从 0 开始）
  - `y`：Y 坐标（从 0 开始）
- 返回：[r,g,b,a] 颜色数组（每分量 0-255）
- 示例：
  - `var px = imageGetPixel(img, 10, 20)  // 如 [255,0,0,255]`
- 常见错误：
  - img 不是 image 对象
  - 坐标超出图片范围

### `imageGetWidth`

- 签名：`imageGetWidth(img) -> int`
- 简介：获取图片宽度。
- 参数：
  - `img`：image 图片对象
- 返回：int 像素宽度
- 示例：
  - `var w = imageGetWidth(img)`
- 常见错误：
  - img 不是 image 对象（应先用 imageLoad/imageNew 创建）

### `imageGray`

- 签名：`imageGray(img) -> image`
- 简介：灰度化图片。
- 参数：
  - `img`：image 图片对象
- 返回：image 灰度图片
- 示例：
  - `gray := imageGray(img)`
- 常见错误：
  - img 不是 image 对象

### `imageHistogram`

- 签名：`imageHistogram(img) -> [rHist, gHist, bHist, aHist]`
- 简介：获取图片直方图（RGBA 四通道）。
- 参数：
  - `img`：image 图片对象
- 返回：4 个数组的数组，每个是 256 元素的该亮度像素计数
- 示例：
  - `var h = imageHistogram(img)`
  - `var redHist = h[0]  // redHist[i] = 红色分量为 i 的像素数`
- 常见错误：
  - img 不是 image 对象

### `imageInvert`

- 签名：`imageInvert(img) -> undefined`
- 简介：反色图片（就地修改）。
- 参数：
  - `img`：image 图片对象
- 返回：undefined（就地修改 img）
- 示例：
  - `imageInvert(img)`
- 常见错误：
  - img 不是 image 对象

### `imageLoad`

- 签名：`imageLoad(path) -> image`
- 简介：从文件加载图片（自动识别格式）。
- 参数：
  - `path`：图片文件路径（支持 png/jpg/gif/bmp/webp）
- 返回：image 图片对象
- 示例：
  - `img := imageLoad("photo.png")`
- 常见错误：
  - 文件不存在或不是支持的图片格式

### `imageLoadFromBytes`

- 签名：`imageLoadFromBytes(bytes, format?) -> image`
- 简介：从字节数据加载图片。
- 参数：
  - `bytes`：图片字节数据（bytes/byteArray）
  - `format`：可选格式 "png"/"jpg"/"gif"/"bmp"/"webp"，缺省自动识别
- 返回：image 图片对象
- 示例：
  - `var data = readFileBin("a.png")`
  - `img := imageLoadFromBytes(data)`
  - `img := imageLoadFromBytes(data, "png")  // 指定格式更快`
- 常见错误：
  - 数据损坏、格式不匹配或不支持

### `imageNew`

- 签名：`imageNew(width, height, bgColor?) -> image`
- 简介：创建新图片（纯色填充）。
- 参数：
  - `width`：宽度（像素，>0）
  - `height`：高度（像素，>0）
  - `bgColor`：可选背景色 [r,g,b,a]，缺省透明 [0,0,0,0]
- 返回：image 新建图片对象
- 示例：
  - `img := imageNew(100, 100)  // 透明`
  - `img := imageNew(100, 100, [255,0,0,255])  // 红色背景`
- 常见错误：
  - width/height 不能为 0

### `imageOpacity`

- 签名：`imageOpacity(img, factor) -> image`
- 简介：调整图片透明度。
- 参数：
  - `img`：image 图片对象
  - `factor`：透明度系数（0.0 全透明，1.0 不变，>1 增强，按 0-255 截断）
- 返回：image 调整 alpha 后的新图片
- 示例：
  - `semi := imageOpacity(img, 0.5)  // 半透明`
- 常见错误：
  - img 不是 image 对象

### `imageResize`

- 签名：`imageResize(img, width, height, filter?) -> image`
- 简介：缩放图片。
- 参数：
  - `img`：image 图片对象
  - `width`：目标宽度（>0）
  - `height`：目标高度（>0）
  - `filter`：可选采样滤镜 "nearest"/"triangle"/"catmullrom"/"gaussian"/"lanczos3"，默认 lanczos3
- 返回：image 缩放后的新图片
- 示例：
  - `small := imageResize(img, 50, 50)`
  - `small := imageResize(img, 50, 50, "nearest")  // 像素风`
- 常见错误：
  - img 不是 image 对象
  - 目标尺寸不能为 0

### `imageRotate`

- 签名：`imageRotate(img, degrees) -> image`
- 简介：旋转图片（仅支持 90/180/270 度，正值顺时针）。
- 参数：
  - `img`：image 图片对象
  - `degrees`：角度 90/180/270（正值顺时针，负值逆时针）
- 返回：image 旋转后的新图片
- 示例：
  - `rotated := imageRotate(img, 90)`
- 常见错误：
  - img 不是 image 对象
  - 仅支持 90/180/270 度，任意角度请用 imageRotateFree

### `imageRotateFree`

- 签名：`imageRotateFree(img, degrees, bgColor?) -> image`
- 简介：任意角度旋转图片（正值逆时针）。
- 参数：
  - `img`：image 图片对象
  - `degrees`：任意角度（float，正值逆时针）
  - `bgColor`：可选空白区域填充色，默认透明 [0,0,0,0]
- 返回：image 旋转后的新图片（画布自动扩大以容纳全部内容）
- 示例：
  - `rotated := imageRotateFree(img, 45)`
  - `rotated := imageRotateFree(img, 30, [255,255,255,255])  // 白底`
- 常见错误：
  - img 不是 image 对象

### `imageSave`

- 签名：`imageSave(img, path, format [, "-quality=N"]) -> undefined`
- 简介：保存图片到文件（JPEG 可用 -quality=1-100 指定质量，默认 75）。
- 参数：
  - `img`：image 图片对象
  - `path`：输出文件路径
  - `format`：格式 "png"/"jpg"/"gif"/"bmp"/"webp"
  - `-quality=N`：可选，JPEG 编码质量（1-100，仅对 jpg/jpeg 生效）
- 返回：undefined
- 示例：
  - `imageSave(img, "out.png", "png")`
  - `imageSave(img, "out.jpg", "jpg", "-quality=90")`
- 常见错误：
  - img 不是 image 对象
  - 路径不可写或磁盘空间不足
  - 格式拼写错误
  - -quality 值超出 1-100 范围

### `imageSaveToBytes`

- 签名：`imageSaveToBytes(img, format [, "-quality=N"]) -> bytes`
- 简介：将图片编码为字节（JPEG 可用 -quality=1-100 指定质量，默认 75）。
- 参数：
  - `img`：image 图片对象
  - `format`：格式 "png"/"jpg"/"gif"/"bmp"/"webp"
  - `-quality=N`：可选，JPEG 编码质量（1-100，仅对 jpg/jpeg 生效）
- 返回：bytes 编码后的图片字节
- 示例：
  - `var b = imageSaveToBytes(img, "png")`
  - `writeFileBin("out.png", b)`
  - `var j = imageSaveToBytes(img, "jpg", "-quality=90")`
- 常见错误：
  - img 不是 image 对象
  - 图片数据无效
  - 格式拼写错误
  - -quality 值超出 1-100 范围

### `imageSepia`

- 签名：`imageSepia(img) -> image`
- 简介：棕褐色滤镜（复古效果）。
- 参数：
  - `img`：image 图片对象
- 返回：image 棕褐色复古风格的新图片
- 示例：
  - `vintage := imageSepia(img)`
- 常见错误：
  - img 不是 image 对象

### `imageSetPixel`

- 签名：`imageSetPixel(img, x, y, color) -> undefined`
- 简介：设置指定坐标的像素颜色。
- 参数：
  - `img`：image 图片对象
  - `x`：X 坐标（从 0 开始）
  - `y`：Y 坐标（从 0 开始）
  - `color`：颜色 [r,g,b] 或 [r,g,b,a]
- 返回：undefined
- 示例：
  - `imageSetPixel(img, 10, 20, [255,255,255,255])`
- 常见错误：
  - img 不是 image 对象
  - 坐标超出图片范围
  - color 不是数组或长度不足 3

### `imageSharpen`

- 签名：`imageSharpen(img) -> image`
- 简介：锐化图片（拉普拉斯卷积核）。
- 参数：
  - `img`：image 图片对象
- 返回：image 锐化后的新图片
- 示例：
  - `sharp := imageSharpen(img)`
- 常见错误：
  - img 不是 image 对象

### `imageThreshold`

- 签名：`imageThreshold(img, threshold) -> image`
- 简介：二值化阈值（灰度 > threshold 变白，否则变黑）。
- 参数：
  - `img`：image 图片对象
  - `threshold`：阈值 0-255
- 返回：image 黑白二值图片
- 示例：
  - `bw := imageThreshold(img, 128)`
- 常见错误：
  - img 不是 image 对象

### `imageTint`

- 签名：`imageTint(img, color) -> image`
- 简介：用指定颜色着色（保留亮度，替换色调）。
- 参数：
  - `img`：image 图片对象
  - `color`：着色目标颜色 [r,g,b,a]
- 返回：image 着色后的新图片
- 示例：
  - `tinted := imageTint(img, [255,0,0,255])  // 红色调`
- 常见错误：
  - img 不是 image 对象
  - color 格式错误

### `loadFont`

- 签名：`loadFont(fontPath) -> font`
- 简介：从文件加载 TrueType/OpenType 字体。
- 参数：
  - `fontPath`：字体文件路径（.ttf/.otf/.ttc）
- 返回：font 字体对象，用于 canvasDrawText/canvasMeasureText
- 示例：
  - `var f = loadFont("C:\\Windows\\Fonts\\arial.ttf")`
  - `canvasDrawText(c, 10, 10, "Hi", [0,0,0,255], 20, f)`
- 常见错误：
  - 文件不存在或无权限
  - 文件不是有效的 TrueType/OpenType 字体

## imageGen（20 个）

### `imageGenChecker`

- 签名：`imageGenChecker(width, height, cellSize?, color1?, color2?) -> image`
- 简介：生成棋盘格图案。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `cellSize`：可选格子大小（默认 16，>=1）
  - `color1`：可选浅色（默认白色 [255,255,255,255]）
  - `color2`：可选深色（默认黑色 [0,0,0,255]）
- 返回：image 棋盘格图案
- 示例：
  - `imageGenChecker(256, 256)`
  - `imageGenChecker(256, 256, 32, colorFromHex("#ff0000"), colorFromHex("#00ff00"))`
- 常见错误：
  - width/height 必须 > 0

### `imageGenCircles`

- 签名：`imageGenCircles(width, height, count?, seed?) -> image`
- 简介：生成随机彩色圆形图案。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `count`：可选圆形数量（默认 30，>=1）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 深色背景上的随机彩色实心圆图案
- 示例：
  - `imageGenCircles(256, 256, 30, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenClouds`

- 签名：`imageGenClouds(width, height, scale?, seed?) -> image`
- 简介：生成云彩纹理（FBM + 对比度增强，灰度）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `scale`：可选噪声粒度（默认 0.02）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 灰度云彩纹理
- 示例：
  - `imageGenClouds(256, 256, 0.02, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenConic`

- 签名：`imageGenConic(width, height, [cx, cy,] color1, color2) -> image`
- 简介：生成锥形（角度）渐变图片。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `cx, cy`：可选渐变中心坐标（缺省居中，传则需 6 参数）
  - `color1`：起始颜色 [r,g,b,a]
  - `color2`：结束颜色 [r,g,b,a]
- 返回：image 绕中心旋转一周从 color1 到 color2 的锥形渐变
- 示例：
  - `imageGenConic(256, 256, [255,0,0,255], [0,0,255,255])`
  - `imageGenConic(256, 256, 128, 128, [255,0,0,255], [0,0,255,255])`
- 常见错误：
  - width/height 必须 > 0
  - 支持 (w,h,c1,c2) 或 (w,h,cx,cy,c1,c2) 两种参数顺序

### `imageGenFBM`

- 签名：`imageGenFBM(width, height, octaves?, scale?, seed?) -> image`
- 简介：生成分形布朗运动（FBM）噪声图片（多倍频叠加 Perlin）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `octaves`：可选倍频数，控制细节层次（默认 4，范围 1-8）
  - `scale`：可选噪声粒度（默认 0.05，>0）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 灰度 FBM 噪声图片（octaves 越多细节越丰富）
- 示例：
  - `imageGenFBM(256, 256, 6, 0.05, 42)`
- 常见错误：
  - width/height 必须 > 0
  - scale 必须 > 0

### `imageGenJulia`

- 签名：`imageGenJulia(width, height, cr, ci, maxIter?, zoom?) -> image`
- 简介：生成朱利亚集合分形图（按迭代次数 HSL 着色）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `cr`：复常数实部（float）
  - `ci`：复常数虚部（float）
  - `maxIter`：可选最大迭代次数（默认 100，>=10）
  - `zoom`：可选缩放（默认 1.0，>0）
- 返回：image 朱利亚集合分形图
- 示例：
  - `imageGenJulia(256, 256, -0.7, 0.27)`
  - `imageGenJulia(256, 256, -0.4, 0.6, 100, 1.0)`
  - `imageGenJulia(256, 256, 0.285, 0.01)  // 常用漂亮参数`
- 常见错误：
  - width/height 必须 > 0
  - cr/ci 必须为数字

### `imageGenLinear`

- 签名：`imageGenLinear(width, height, color1, color2, direction?) -> image`
- 简介：生成线性渐变图片。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `color1`：起始颜色 [r,g,b] 或 [r,g,b,a]
  - `color2`：结束颜色 [r,g,b] 或 [r,g,b,a]
  - `direction`：可选方向 "h" 水平(默认)/"v" 垂直/"d" 对角
- 返回：image 从 color1 到 color2 的线性渐变
- 示例：
  - `imageGenLinear(256, 256, [0,0,0,255], [255,255,255,255])`
  - `imageGenLinear(256, 256, colorFromHex("#ff0000"), colorFromHex("#0000ff"), "d")`
- 常见错误：
  - width/height 必须 > 0
  - direction 必须是 "h"/"v"/"d" 之一

### `imageGenLines`

- 签名：`imageGenLines(width, height, count?, seed?) -> image`
- 简介：生成随机彩色线条图案（Bresenham 算法）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `count`：可选线条数量（默认 20，>=1）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 深色背景上的随机彩色线条图案
- 示例：
  - `imageGenLines(256, 256, 20, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenMandelbrot`

- 签名：`imageGenMandelbrot(width, height, maxIter?, zoom?, centerX?, centerY?) -> image`
- 简介：生成曼德博集合分形图（含平滑着色）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `maxIter`：可选最大迭代次数（默认 100，>=10，越大细节越多）
  - `zoom`：可选缩放（默认 1.0，>0，越大放得越近）
  - `centerX`：可选中心 X 坐标（默认 -0.5）
  - `centerY`：可选中心 Y 坐标（默认 0.0）
- 返回：image 曼德博集合分形图（集合内黑色，外部按迭代次数 HSL 着色）
- 示例：
  - `imageGenMandelbrot(256, 256)`
  - `imageGenMandelbrot(512, 512, 256, 4.0, -0.7, 0.0)  // 放大特定区域`
- 常见错误：
  - width/height 必须 > 0

### `imageGenMarble`

- 签名：`imageGenMarble(width, height, scale?, seed?) -> image`
- 简介：生成大理石纹理（噪声扰动正弦波，灰度）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `scale`：可选噪声粒度（默认 0.05）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 灰度大理石纹理
- 示例：
  - `imageGenMarble(256, 256, 0.05, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenMaze`

- 签名：`imageGenMaze(width, height, cellSize?, seed?) -> image`
- 简介：生成迷宫图案（DFS 递归回溯算法）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `cellSize`：可选格子大小（默认 10，>=2）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 白底黑墙迷宫图案
- 示例：
  - `imageGenMaze(256, 256, 8, 42)`
- 常见错误：
  - width/height 必须 > 0
  - cellSize 太大导致网格 <2x2 时返回纯黑图

### `imageGenNoise`

- 签名：`imageGenNoise(width, height, seed?) -> image`
- 简介：生成白噪声（随机雪花）图片。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `seed`：可选随机种子（int/float，缺省用系统时间）
- 返回：image 灰度白噪声图片
- 示例：
  - `imageGenNoise(256, 256, 42)  // 同种子可重现`
- 常见错误：
  - width/height 必须 > 0

### `imageGenParticles`

- 签名：`imageGenParticles(width, height, count?, seed?) -> image`
- 简介：生成粒子发散图案（从中心向外发散的彩色拖尾粒子）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `count`：可选粒子数量（默认 50，>=1）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 黑底彩色粒子发散图案
- 示例：
  - `imageGenParticles(256, 256, 80, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenPerlin`

- 签名：`imageGenPerlin(width, height, scale?, seed?) -> image`
- 简介：生成 Perlin 噪声图片（平滑渐变噪声）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `scale`：可选噪声粒度，越大越粗糙（默认 0.05，>0）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 灰度 Perlin 噪声图片
- 示例：
  - `imageGenPerlin(256, 256, 0.05, 42)`
  - `imageGenPerlin(256, 256)  // 用默认 scale 和随机种子`
- 常见错误：
  - width/height 必须 > 0
  - scale 必须 > 0

### `imageGenPlasma`

- 签名：`imageGenPlasma(width, height, scale?, seed?) -> image`
- 简介：生成等离子体效果（正弦波叠加 Perlin 噪声，彩色）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `scale`：可选噪声粒度（默认 0.05）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 彩色等离子体图案
- 示例：
  - `imageGenPlasma(256, 256, 0.05, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenRadial`

- 签名：`imageGenRadial(width, height, [cx, cy,] color1, color2) -> image`
- 简介：生成径向渐变图片（从中心向外扩散）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `cx, cy`：可选渐变中心坐标（缺省居中，传则需 6 参数）
  - `color1`：中心颜色 [r,g,b,a]
  - `color2`：边缘颜色 [r,g,b,a]
- 返回：image 从中心 color1 到边缘 color2 的径向渐变
- 示例：
  - `imageGenRadial(256, 256, [255,0,0,255], [0,0,255,255])  // 居中`
  - `imageGenRadial(256, 256, 64, 64, [255,0,0,255], [0,0,255,255])  // 指定中心`
- 常见错误：
  - width/height 必须 > 0
  - 支持 (w,h,c1,c2) 或 (w,h,cx,cy,c1,c2) 两种参数顺序

### `imageGenStars`

- 签名：`imageGenStars(width, height, count?, seed?) -> image`
- 简介：生成星空图案（深色背景上的随机亮点，大星带光晕）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `count`：可选星星数量（默认 100，>=0）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 星空图案（背景 [10,10,30]）
- 示例：
  - `imageGenStars(256, 256, 200, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenVoronoi`

- 签名：`imageGenVoronoi(width, height, count?, seed?) -> image`
- 简介：生成 Voronoi 图（彩色细胞，每个区域取最近特征点颜色）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `count`：可选特征点数量（默认 50，>=2）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 彩色 Voronoi 图（HSL 随机配色）
- 示例：
  - `imageGenVoronoi(256, 256, 30, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenWood`

- 签名：`imageGenWood(width, height, scale?, seed?) -> image`
- 简介：生成木纹纹理（同心圆 + 噪声扰动模拟年轮）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `scale`：可选噪声粒度（默认 0.05）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 棕色调木纹纹理
- 示例：
  - `imageGenWood(256, 256, 0.05, 42)`
- 常见错误：
  - width/height 必须 > 0

### `imageGenWorley`

- 签名：`imageGenWorley(width, height, cellSize?, seed?) -> image`
- 简介：生成 Worley 噪声图片（细胞状图案）。
- 参数：
  - `width`：图片宽度（像素，>0）
  - `height`：图片高度（像素，>0）
  - `cellSize`：可选特征点网格大小（默认 32，>=4）
  - `seed`：可选随机种子（默认用系统时间）
- 返回：image 灰度 Worley 噪声图片（基于最近特征点距离）
- 示例：
  - `imageGenWorley(256, 256, 32, 42)`
- 常见错误：
  - width/height 必须 > 0

## json（9 个）

### `compactJson`

- 签名：`compactJson(v) -> string`
- 简介：压缩 JSON（无空白）。
- 参数：
  - `v`：任意值
- 返回：string 紧凑 JSON

### `formatJson`

- 签名：`formatJson(v) -> string`
- 简介：格式化 JSON（带缩进）。
- 参数：
  - `v`：任意值
- 返回：string 缩进的 JSON
- 示例：
  - `formatJson({"a":1})  // {\n  "a": 1\n}`

### `fromJson`

- 签名：`jsonDecode(s) -> value|error`
- 简介：将 JSON 字符串解码为 Sflang 值。别名 fromJson。
- 参数：
  - `s`：JSON 文本字符串
- 返回：value（object/array/string/number/bool/undefined）；解析失败返回 error
- 示例：
  - `jsonDecode("{\"a\":1}")  → {"a": 1}`
  - `jsonDecode("[1,2,3]")       → [1, 2, 3]`
- 常见错误：
  - JSON 语法错误返回 error 对象（用 isErr 检查）
  - JSON 的 null 解码为 undefined

### `getJsonNode`

- 签名：`getJsonNode(json, path) -> value|undefined`
- 简介：按路径提取 JSON 节点（保留类型）。
- 参数：
  - `json`：JSON 字符串或 object
  - `path`：点号路径
- 返回：value；未找到 undefined

### `getJsonNodeStr`

- 签名：`getJsonNodeStr(json, path) -> string|undefined`
- 简介：按点号路径提取 JSON 节点文本。
- 参数：
  - `json`：JSON 字符串或 object
  - `path`：点号路径，如 a.b.c
- 返回：string；未找到 undefined
- 示例：
  - `getJsonNodeStr(j, "user.name")`

### `getJsonNodeStrs`

- 签名：`getJsonNodeStrs(json, paths) -> array<string>`
- 简介：批量提取多个路径。
- 参数：
  - `json`：JSON 字符串或 object
  - `paths`：路径数组
- 返回：array<string>

### `jsonDecode`

- 签名：`jsonDecode(s) -> value|error`
- 简介：将 JSON 字符串解码为 Sflang 值。别名 fromJson。
- 参数：
  - `s`：JSON 文本字符串
- 返回：value（object/array/string/number/bool/undefined）；解析失败返回 error
- 示例：
  - `jsonDecode("{\"a\":1}")  → {"a": 1}`
  - `jsonDecode("[1,2,3]")       → [1, 2, 3]`
- 常见错误：
  - JSON 语法错误返回 error 对象（用 isErr 检查）
  - JSON 的 null 解码为 undefined

### `jsonEncode`

- 签名：`jsonEncode(v) -> string`
- 简介：将 Sflang 值编码为 JSON 字符串。别名 toJson。
- 参数：
  - `v`：任意值（undefined→null, bool/number/string/array/object 可编码）
- 返回：string JSON 文本
- 示例：
  - `jsonEncode({"a": 1, "b": [2,3]})  → {"a":1,"b":[2,3]}`
  - `jsonEncode(undefined)                → null`

### `toJson`

- 签名：`jsonEncode(v) -> string`
- 简介：将 Sflang 值编码为 JSON 字符串。别名 toJson。
- 参数：
  - `v`：任意值（undefined→null, bool/number/string/array/object 可编码）
- 返回：string JSON 文本
- 示例：
  - `jsonEncode({"a": 1, "b": [2,3]})  → {"a":1,"b":[2,3]}`
  - `jsonEncode(undefined)                → null`

## le（29 个）

### `leAppendFromFile`

- 签名：`leAppendFromFile(e, path) -> error|undefined`
- 简介：追加文件内容。
- 参数：
  - `e`：le 对象
  - `path`：文件路径
- 返回：undefined；失败返回 error

### `leAppendFromStr`

- 签名：`leAppendFromStr(e, s) -> undefined`
- 简介：追加字符串内容（按行拆分）。
- 参数：
  - `e`：le 对象
  - `s`：文本
- 返回：undefined

### `leAppendLine`

- 签名：`leAppendLine(e, line) -> undefined`
- 简介：追加一行。
- 参数：
  - `e`：le 对象
  - `line`：要追加的行
- 返回：undefined
- 示例：
  - `leAppendLine(e, "new line")`

### `leAppendToFile`

- 签名：`leAppendToFile(e, path) -> error|undefined`
- 简介：将内容追加到文件末尾。
- 参数：
  - `e`：le 对象
  - `path`：文件路径
- 返回：undefined；失败返回 error

### `leClear`

- 签名：`leClear(e) -> undefined`
- 简介：清空所有行。
- 参数：
  - `e`：le 对象
- 返回：undefined

### `leFind`

- 签名：`leFind(e, sub) -> int`
- 简介：查找包含子串的行号。
- 参数：
  - `e`：le 对象
  - `sub`：搜索子串
- 返回：int 行号；未找到返回 -1

### `leFindAll`

- 签名：`leFindAll(e, sub) -> array<int>`
- 简介：查找所有匹配行号。
- 参数：
  - `e`：le 对象
  - `sub`：搜索子串
- 返回：array<int>

### `leFindLines`

- 签名：`leFindLines(e, sub) -> array<string>`
- 简介：查找所有匹配行内容。
- 参数：
  - `e`：le 对象
  - `sub`：搜索子串
- 返回：array<string>

### `leGetLine`

- 签名：`leGetLine(e, idx) -> string`
- 简介：获取指定行内容。
- 参数：
  - `e`：le 对象
  - `idx`：行号
- 返回：string

### `leGetList`

- 签名：`leGetList(e) -> array<string>`
- 简介：获取所有行为数组。
- 参数：
  - `e`：le 对象
- 返回：array<string>

### `leInfo`

- 签名：`leInfo(e) -> string`
- 简介：返回行编辑器统计信息。
- 参数：
  - `e`：le 对象
- 返回：string

### `leInsertLine`

- 签名：`leInsertLine(e, idx, line) -> undefined`
- 简介：在指定行号插入一行。
- 参数：
  - `e`：le 对象
  - `idx`：行号（0-based）
  - `line`：内容
- 返回：undefined
- 示例：
  - `leInsertLine(e, 0, "first")`

### `leLoadFromFile`

- 签名：`leLoadFromFile(path) -> le|error`
- 简介：从文件创建行编辑器。
- 参数：
  - `path`：文件路径
- 返回：le 对象；失败返回 error
- 示例：
  - `var e = leLoadFromFile("data.txt")`
- 常见错误：
  - 文件不存在返回 error

### `leLoadFromSsh`

- 签名：`leLoadFromSsh(sshConn, path) -> le|error`
- 简介：从 SSH 远程文件创建行编辑器。
- 参数：
  - `sshConn`：SSH 连接
  - `path`：远程文件路径
- 返回：le 对象；失败返回 error
- 示例：
  - `var e = leLoadFromSsh(conn, "/etc/hosts")`

### `leLoadFromStr`

- 签名：`leLoadFromStr(s) -> le`
- 简介：从字符串创建行编辑器。
- 参数：
  - `s`：多行文本
- 返回：le 行编辑器对象
- 示例：
  - `var e = leLoadFromStr(text)`

### `lePrint`

- 签名：`lePrint(e) -> undefined`
- 简介：打印行编辑器内容。
- 参数：
  - `e`：le 对象
- 返回：undefined
- 示例：
  - `lePrint(e)`

### `leRemoveLine`

- 签名：`leRemoveLine(e, idx) -> undefined`
- 简介：删除指定行。
- 参数：
  - `e`：le 对象
  - `idx`：行号
- 返回：undefined

### `leRemoveLines`

- 签名：`leRemoveLines(e, start, end) -> undefined`
- 简介：删除指定范围的行。
- 参数：
  - `e`：le 对象
  - `start`：起始行号
  - `end`：结束行号
- 返回：undefined

### `leReplace`

- 签名：`leReplace(e, old, new) -> int`
- 简介：全局替换子串，返回替换次数。
- 参数：
  - `e`：le 对象
  - `old`：旧子串
  - `new`：新子串
- 返回：int 替换次数

### `leSaveToFile`

- 签名：`leSaveToFile(e, path) -> error|undefined`
- 简介：保存到本地文件。
- 参数：
  - `e`：le 对象
  - `path`：文件路径
- 返回：undefined；失败返回 error
- 示例：
  - `leSaveToFile(e, "out.txt")`

### `leSaveToSsh`

- 签名：`leSaveToSsh(e, sshConn, path) -> error|undefined`
- 简介：保存到 SSH 远程文件。
- 参数：
  - `e`：le 对象
  - `sshConn`：SSH 连接
  - `path`：远程路径
- 返回：undefined；失败返回 error

### `leSaveToStr`

- 签名：`leSaveToStr(e) -> string`
- 简介：将行编辑器内容转为字符串。
- 参数：
  - `e`：le 对象
- 返回：string
- 示例：
  - `var s = leSaveToStr(e)`

### `leSetLine`

- 签名：`leSetLine(e, idx, line) -> undefined`
- 简介：替换指定行。
- 参数：
  - `e`：le 对象
  - `idx`：行号
  - `line`：新内容
- 返回：undefined

### `leSetLines`

- 签名：`leSetLines(e, lines) -> undefined`
- 简介：用数组替换所有行。
- 参数：
  - `e`：le 对象
  - `lines`：字符串数组
- 返回：undefined

### `leSort`

- 签名：`leSort(e[, byFunc]) -> undefined`
- 简介：对所有行排序（可选自定义比较函数）。
- 参数：
  - `e`：le 对象
  - `byFunc`：可选。比较函数
- 返回：undefined

### `leToStr`

- 签名：`leToStr(e) -> string`
- 简介：leSaveToStr 的别名。
- 参数：
  - `e`：le 对象
- 返回：string

### `leViewAll`

- 签名：`leViewAll(e) -> string`
- 简介：查看全部（带行号）。
- 参数：
  - `e`：le 对象
- 返回：string

### `leViewLine`

- 签名：`leViewLine(e, idx) -> string`
- 简介：查看指定行（带行号前缀）。
- 参数：
  - `e`：le 对象
  - `idx`：行号
- 返回：string

### `leViewLines`

- 签名：`leViewLines(e, start, end) -> string`
- 简介：查看指定范围（带行号）。
- 参数：
  - `e`：le 对象
  - `start`：起始
  - `end`：结束
- 返回：string

## math（24 个）

### `abs`

- 签名：`abs(x) -> int|float`
- 简介：返回数值的绝对值。Int 返回 int，Float 返回 float。
- 参数：
  - `x`：数值（int/float）
- 返回：int|float 绝对值
- 示例：
  - `abs(-5) → 5`
  - `abs(-3.14) → 3.14`

### `atan`

- 签名：`atan(x) -> float`
- 简介：反正切（弧度）。
- 参数：
  - `x`：数值
- 返回：float

### `atan2`

- 签名：`atan2(y, x) -> float`
- 简介：双参数反正切。
- 参数：
  - `y`：y 坐标
  - `x`：x 坐标
- 返回：float 弧度

### `calDistanceOfLatLon`

- 签名：`calDistanceOfLatLon(lat1, lon1, lat2, lon2) -> float`
- 简介：计算两个经纬度坐标间的距离（米）。
- 参数：
  - `lat1`：纬度1
  - `lon1`：经度1
  - `lat2`：纬度2
  - `lon2`：经度2
- 返回：float 距离（米）
- 示例：
  - `calDistanceOfLatLon(39.9, 116.4, 31.2, 121.5)  // 北京到上海`

### `ceil`

- 签名：`ceil(x) -> int`
- 简介：向上取整（返回不小于 x 的最小整数）。
- 参数：
  - `x`：数值（int/float）
- 返回：int
- 示例：
  - `ceil(3.2) → 4`
  - `ceil(-1.8) → -1`

### `cos`

- 签名：`cos(x) -> float`
- 简介：余弦（弧度）。
- 参数：
  - `x`：弧度
- 返回：float

### `e`

- 签名：`e() -> float`
- 简介：返回自然对数底 e（也作为全局 eG 暴露）。
- 返回：float 2.71828...

### `exp`

- 签名：`exp(x) -> float`
- 简介：自然指数 e^x。
- 参数：
  - `x`：指数
- 返回：float

### `flexEval`

- 签名：`flexEval(expr) -> float|error`
- 简介：求值数学表达式字符串。
- 参数：
  - `expr`：数学表达式，如 "1+2*3"
- 返回：float 结果；语法错误返回 error
- 示例：
  - `flexEval("sin(0.5) + 1")  // 1.479...`
- 常见错误：
  - 表达式语法错误返回 error

### `floor`

- 签名：`floor(x) -> int`
- 简介：向下取整（返回不大于 x 的最大整数）。
- 参数：
  - `x`：数值（int/float）
- 返回：int
- 示例：
  - `floor(3.7) → 3`
  - `floor(-1.2) → -2`

### `log`

- 签名：`log(x) -> float`
- 简介：自然对数 ln(x)。
- 参数：
  - `x`：数值（>0）
- 返回：float
- 常见错误：
  - x<=0 返回错误

### `log10`

- 签名：`log10(x) -> float`
- 简介：以 10 为底对数。
- 参数：
  - `x`：数值（>0）
- 返回：float

### `log2`

- 签名：`log2(x) -> float`
- 简介：以 2 为底对数。
- 参数：
  - `x`：数值（>0）
- 返回：float

### `max`

- 签名：`max(a, b, ...) / max(arr) -> value`
- 简介：返回最大值。支持可变参数或单个数组。
- 参数：
  - `a, b, ...`：两个以上数值，或一个数值数组
- 返回：最大值（类型与输入一致）
- 示例：
  - `max(3, 1, 2) → 3`
  - `max([5, 2, 8]) → 8`

### `min`

- 签名：`min(a, b, ...) / min(arr) -> value`
- 简介：返回最小值。支持可变参数或单个数组。
- 参数：
  - `a, b, ...`：两个以上数值，或一个数值数组
- 返回：最小值（类型与输入一致）
- 示例：
  - `min(3, 1, 2) → 1`
  - `min([5, 2, 8]) → 2`

### `pi`

- 签名：`pi() -> float`
- 简介：返回圆周率 pi（也作为全局 piG 暴露）。
- 返回：float 3.14159...
- 示例：
  - `pi()  // 3.141592653589793`

### `pow`

- 签名：`pow(base, exp) -> float`
- 简介：返回 base 的 exp 次方。
- 参数：
  - `base`：底数（int/float）
  - `exp`：指数（int/float）
- 返回：float base^exp
- 示例：
  - `pow(2, 10) → 1024`
  - `pow(9, 0.5) → 3`

### `randInt`

- 签名：`randInt(lo, hi) -> int`
- 简介：返回 [lo, hi] 区间的伪随机整数（含两端）。
- 参数：
  - `lo`：下界（含）
  - `hi`：上界（含）
- 返回：int [lo, hi] 闭区间内的随机整数
- 示例：
  - `randInt(1, 6) → 1~6（模拟骰子）`

### `random`

- 签名：`random() -> float`
- 简介：返回 [0, 1) 区间的伪随机浮点数。
- 返回：float [0, 1)
- 示例：
  - `random() → 0.7231...（每次不同）`

### `round`

- 签名：`round(x) -> int`
- 简介：四舍五入到 nearest 整数（.5 远离零）。
- 参数：
  - `x`：数值（int/float）
- 返回：int
- 示例：
  - `round(3.5) → 4`
  - `round(2.4) → 2`

### `sign`

- 签名：`sign(x) -> int`
- 简介：返回符号：正数 1，负数 -1，零 0。
- 参数：
  - `x`：数值
- 返回：int -1/0/1
- 示例：
  - `sign(-5)  // -1`

### `sin`

- 签名：`sin(x) -> float`
- 简介：正弦（弧度）。
- 参数：
  - `x`：弧度
- 返回：float

### `sqrt`

- 签名：`sqrt(x) -> float`
- 简介：返回平方根。
- 参数：
  - `x`：数值（int/float，≥0）
- 返回：float 平方根
- 示例：
  - `sqrt(9) → 3`
  - `sqrt(2) → 1.4142135623730951`
- 常见错误：
  - 负数返回 error

### `tan`

- 签名：`tan(x) -> float`
- 简介：正切（弧度）。
- 参数：
  - `x`：弧度
- 返回：float

## pinyin（2 个）

### `toPinYin`

- 签名：`toPinYin(s) -> string`
- 简介：将中文字符串转为拼音（带声调标记）。
- 参数：
  - `s`：中文字符串
- 返回：string 拼音
- 示例：
  - `toPinYin("你好")  // nihao`

### `toPinYinInitial`

- 签名：`toPinYinInitial(s) -> string`
- 简介：提取中文拼音首字母。
- 参数：
  - `s`：中文字符串
- 返回：string 首字母串
- 示例：
  - `toPinYinInitial("你好")  // nh`

## process（6 个）

### `procExitCode`

- 签名：`procExitCode(p) -> int|undefined`
- 简介：子进程退出码；仍在运行时返回 undefined。
- 参数：
  - `p`：进程句柄
- 返回：int 退出码（正常退出 0；被 kill 的进程码依平台而定）；运行中 undefined
- 示例：
  - `if !procIsRunning(p) { pln("exit: " + toStr(procExitCode(p))) }`

### `procIsRunning`

- 签名：`procIsRunning(p) -> bool`
- 简介：子进程是否仍在运行。
- 参数：
  - `p`：进程句柄
- 返回：bool true=运行中
- 示例：
  - `while procIsRunning(p) { procRead(p); sleepMs(50) }`

### `procKill`

- 签名：`procKill(p) -> undefined`
- 简介：强制终止子进程。
- 参数：
  - `p`：进程句柄
- 返回：undefined
- 示例：
  - `procKill(p)`
- 常见错误：
  - 强杀不等待清理：子进程的子进程（孙进程）可能残留，属平台行为
  - 已退出的进程再 kill 为无操作（不报错）

### `procRead`

- 签名：`procRead(p) -> string`
- 简介：非阻塞读取子进程当前已产生的输出（stdout+stderr 合并，按产生顺序近似），不等待。
- 参数：
  - `p`：procStart 返回的进程句柄
- 返回：string 本次新产生的输出（无新输出为空串；UTF-8 多字节截断部分留待下次）
- 示例：
  - `var chunk = procRead(p); if chunk != "" { pl(chunk) }   // 轮询模式`
  - `while procIsRunning(p) { var c = procRead(p); sleepMs(50) }  // 典型循环`
- 常见错误：
  - 非阻塞：进程无新输出立即返回空串，不会挂起
  - 多字节字符被管道截断时，残缺尾部留缓冲，下次凑齐再输出（不丢字节、不产生乱码）

### `procStart`

- 签名：`procStart(cmd[, arg...]) -> process`
- 简介：启动子进程（不等待），stdout/stderr 分别由后台线程收集，返回进程句柄。
- 参数：
  - `cmd`：可执行程序路径（不经 shell 解析，参数分开传）
  - `arg...`：可选追加参数（string，逐个传给程序）
- 返回：process 进程句柄（配合 procRead/procIsRunning/procKill 等使用）
- 示例：
  - `procStart("sf")                 // 直接启动（错误返回 error 对象，如程序不存在）`
  - `procStart(sfExe, scriptPath)     // 带参数启动（推荐，避免 shell 转义问题）`
- 常见错误：
  - 程序不存在/无执行权限返回 error（含系统错误信息）
  - 不经 shell：通配符、管道等 shell 语法不会被解析；需要 shell 时用 procStart("cmd", "/C", "...")

### `procWait`

- 签名：`procWait(p) -> int`
- 简介：阻塞等待子进程退出，返回退出码。
- 参数：
  - `p`：进程句柄
- 返回：int 退出码
- 示例：
  - `var code = procWait(p)`
- 常见错误：
  - 阻塞当前执行体：GUI/并发场景请在 run 任务中调用
  - 进程已被 kill 时返回平台的终止码（Windows 负数/Unix 信号语义）

## proxy（4 个）

### `portForward`

- 签名：`portForward(listenAddr, targetAddr) -> forwardServer`
- 简介：启动端口转发，将监听端口收到的连接全部透传到目标地址。
- 参数：
  - `listenAddr`：监听地址，如 "0.0.0.0:8080"
  - `targetAddr`：目标地址，如 "127.0.0.1:80"
- 返回：forwardServer 对象，传给 portForwardStop 停止
- 示例：
  - `pf := portForward("0.0.0.0:8080", "127.0.0.1:80")  // 转发 8080 到本地 80 端口`
- 常见错误：
  - portForward() 绑定 'xxx' 失败（可能原因：地址被占用或权限不足）
  - 连接目标 xxx 失败（目标未启动或防火墙拦截，仅记录日志不中断转发器）

### `portForwardStop`

- 签名：`portForwardStop(server) -> undefined`
- 简介：停止 portForward 启动的端口转发。
- 参数：
  - `server`：portForward 返回的 forwardServer 对象
- 返回：undefined
- 示例：
  - `portForwardStop(pf)  // 停止转发`
- 常见错误：
  - portForwardStop() 参数不是转发服务器（可能原因：传入了错误类型，应使用 portForward 的返回值）
  - portForwardStop() 参数应为转发服务器，得到 X（可能原因：参数类型不匹配）

### `proxyListen`

- 签名：`proxyListen(addr [, handler]) -> proxyServer`
- 简介：启动 SOCKS5/HTTP 二合一代理服务器，自动识别客户端协议。
- 参数：
  - `addr`：监听地址，如 "0.0.0.0:1080" 或 "127.0.0.1:1080"
  - `handler`：可选 func(targetAddr, proto, clientAddr) -> bool，返回 true 允许、false 拒绝连接；省略则允许全部
- 返回：proxyServer 对象，传给 proxyStop 停止
- 示例：
  - `s := proxyListen("127.0.0.1:1080")  // 启动代理，允许所有连接`
  - `s := proxyListen("0.0.0.0:1080", func(t, p, c) { return !contains(t, "blocked.host") })  // 自定义访问控制`
- 常见错误：
  - proxyListen() 绑定 'xxx' 失败（可能原因：地址被占用或权限不足）
  - proxyListen() 第 2 个参数应为 function，得到 X（可能原因：参数顺序错误）
  - 协议处理错误：未知协议 / 不支持的 SOCKS5 命令（仅支持 CONNECT=1）

### `proxyStop`

- 签名：`proxyStop(server) -> undefined`
- 简介：停止 proxyListen 启动的代理服务器。
- 参数：
  - `server`：proxyListen 返回的 proxyServer 对象
- 返回：undefined
- 示例：
  - `proxyStop(s)  // 停止代理`
- 常见错误：
  - proxyStop() 参数不是代理服务器（可能原因：传入了错误类型，应使用 proxyListen 的返回值）
  - proxyStop() 参数应为代理服务器，得到 X（可能原因：参数类型不匹配）

## regex（13 个）

### `regCompile`

- 签名：`regCompile(pattern) -> regex|error`
- 简介：预编译正则表达式，返回可复用的 regex 对象（避免重复编译开销）。
- 参数：
  - `pattern`：正则表达式字符串
- 返回：regex 预编译对象（传给 regFind/regMatch 等的 pattern 参数）；编译失败返回 error
- 示例：
  - `var re = regCompile("\\d+")`
  - `regFind(re, "a12b")        → "12"`
  - `regMatch(re, "123")        → true`
- 常见错误：
  - 无效的正则语法会返回 error 对象（用 isErr 检查）

### `regContains`

- 签名：`regContains(pattern, s) -> bool`
- 简介：regMatch 的别名（是否整串匹配）。
- 参数：
  - `pattern`：正则
  - `s`：字符串
- 返回：bool

### `regContainsIn`

- 签名：`regContainsIn(pattern, s) -> bool`
- 简介：判断是否包含匹配（非整串）。
- 参数：
  - `pattern`：正则
  - `s`：字符串
- 返回：bool

### `regCount`

- 签名：`regCount(pattern, s) -> int`
- 简介：统计匹配次数。
- 参数：
  - `pattern`：正则
  - `s`：字符串
- 返回：int 匹配数

### `regFind`

- 签名：`regFind(pattern, s) -> string|undefined`
- 简介：在 s 中查找第一个匹配 pattern 的子串。
- 参数：
  - `pattern`：正则表达式（string 或 regCompile 对象）
  - `s`：被搜索的字符串
- 返回：string 第一个匹配子串；未匹配返回 undefined
- 示例：
  - `regFind("\\d+", "a12b34")        → "12"`
  - `regFind("xyz", "abc")             → undefined`
- 常见错误：
  - 参数顺序：pattern 在前，s 在后（最易搞反）
  - pattern 用字符串时反斜杠需双重转义

### `regFindAll`

- 签名：`regFindAll(pattern, s) -> array<string>`
- 简介：查找 s 中所有匹配 pattern 的子串。
- 参数：
  - `pattern`：正则表达式（string 或 regCompile 对象）
  - `s`：被搜索的字符串
- 返回：array<string> 所有匹配子串；无匹配返回空数组 []
- 示例：
  - `regFindAll("\\d+", "a1b22c333")   → ["1", "22", "333"]`
- 常见错误：
  - 参数顺序：pattern 在前，s 在后

### `regFindAllGroups`

- 签名：`regFindAllGroups(pattern, s) -> array<array<string>>`
- 简介：全部匹配及捕获组。
- 参数：
  - `pattern`：正则
  - `s`：字符串
- 返回：array<array<string>>

### `regFindAllIndex`

- 签名：`regFindAllIndex(pattern, s) -> array`
- 简介：全部匹配的起止位置。
- 参数：
  - `pattern`：正则
  - `s`：字符串
- 返回：array [start, end] 对

### `regFindFirst`

- 签名：`regFindFirst(pattern, s) -> array<string>|undefined`
- 简介：第一个匹配 + 捕获组。
- 参数：
  - `pattern`：正则
  - `s`：字符串
- 返回：array<string> [完整匹配, 捕获组1, ...]；无匹配 undefined

### `regMatch`

- 签名：`regMatch(pattern, s) -> bool`
- 简介：判断整串 s 是否完全匹配 pattern（^...$ 语义）。
- 参数：
  - `pattern`：正则表达式（string）或 regCompile 预编译对象
  - `s`：被匹配的字符串
- 返回：bool：整串完全匹配返回 true
- 示例：
  - `regMatch("\\d+", "12345")      → true`
  - `regMatch("\\d+", "12a")         → false（非整串数字）`
- 常见错误：
  - 参数顺序：pattern 在前，s 在后
  - pattern 用字符串时反斜杠需双重转义（"\\\\d+" 表示 \d+）

### `regQuote`

- 签名：`regQuote(s) -> string`
- 简介：转义字符串中的正则元字符。
- 参数：
  - `s`：字面文本
- 返回：string 可安全用作正则
- 示例：
  - `regQuote("1.5")  // 1\.5`

### `regReplace`

- 签名：`regReplace(pattern, s, repl) -> string`
- 简介：将 s 中所有匹配 pattern 的子串替换为 repl（repl 可含 $1/$2 捕获组引用）。
- 参数：
  - `pattern`：正则表达式（string 或 regCompile 对象）
  - `s`：原字符串
  - `repl`：替换串，可含 $1 $2 ${name} 引用捕获组
- 返回：string 替换后的字符串
- 示例：
  - `regReplace("\\d+", "a1b2", "#")   → "a#b#"`
  - `regReplace("(\\w)(\\d)", "a1b2", "$2$1")  → "1a2b"`
- 常见错误：
  - 参数顺序：pattern, s, repl

### `regSplit`

- 签名：`regSplit(pattern, s) -> array<string>`
- 简介：按 pattern 分割字符串 s。
- 参数：
  - `pattern`：分隔正则（string 或 regCompile 对象）
  - `s`：被分割的字符串
- 返回：array<string> 分割后的片段
- 示例：
  - `regSplit(",", "a,b,c")   → ["a", "b", "c"]`
  - `regSplit("\\s+", "a  b c") → ["a", "b", "c"]`
- 常见错误：
  - 参数顺序：pattern 在前，s 在后

## ring（11 个）

### `newRing`

- 签名：`newRing(size) -> ring`
- 简介：创建固定容量的环形缓冲区。
- 参数：
  - `size`：容量（int）
- 返回：ring 对象
- 示例：
  - `var r = newRing(100)`

### `ringClear`

- 签名：`ringClear(r) -> undefined`
- 简介：清空环形缓冲。
- 参数：
  - `r`：ring 对象
- 返回：undefined
- 示例：
  - `ringClear(r)`

### `ringGet`

- 签名：`ringGet(r, idx) -> value`
- 简介：按索引读取元素。
- 参数：
  - `r`：ring 对象
  - `idx`：索引（int）
- 返回：值
- 示例：
  - `ringGet(r, 0)`

### `ringInsert`

- 签名：`ringInsert(r, idx, val) -> undefined`
- 简介：在指定位置插入元素。
- 参数：
  - `r`：ring 对象
  - `idx`：索引
  - `val`：值
- 返回：undefined
- 示例：
  - `ringInsert(r, 0, 1)`

### `ringPick`

- 签名：`ringPick(r) -> value`
- 简介：查看最新值（不弹出）。
- 参数：
  - `r`：ring 对象
- 返回：最新值
- 示例：
  - `ringPick(r)`

### `ringPop`

- 签名：`ringPop(r) -> value`
- 简介：弹出最新写入的值。
- 参数：
  - `r`：ring 对象
- 返回：值
- 示例：
  - `var v = ringPop(r)`

### `ringPush`

- 签名：`ringPush(r, val) -> undefined`
- 简介：向环形缓冲写入值（满时覆盖最旧）。
- 参数：
  - `r`：ring 对象
  - `val`：值
- 返回：undefined
- 示例：
  - `ringPush(r, 42)`

### `ringRemove`

- 签名：`ringRemove(r, idx) -> value`
- 简介：删除指定位置元素并返回。
- 参数：
  - `r`：ring 对象
  - `idx`：索引
- 返回：被删除的值
- 示例：
  - `ringRemove(r, 0)`

### `ringSet`

- 签名：`ringSet(r, idx, val) -> undefined`
- 简介：按索引设置元素。
- 参数：
  - `r`：ring 对象
  - `idx`：索引
  - `val`：值
- 返回：undefined
- 示例：
  - `ringSet(r, 0, 99)`

### `ringSize`

- 签名：`ringSize(r) -> int`
- 简介：返回当前元素数。
- 参数：
  - `r`：ring 对象
- 返回：int
- 示例：
  - `ringSize(r)`

### `ringToList`

- 签名：`ringToList(r) -> array`
- 简介：将环形缓冲转为数组。
- 参数：
  - `r`：ring 对象
- 返回：array
- 示例：
  - `var a = ringToList(r)`

## s3（22 个）

### `s3BucketExists`

- 签名：`s3BucketExists(client, bucket) -> bool`
- 简介：检查 bucket 是否存在（HEAD 请求）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
- 返回：bool：true 存在，false 不存在；其他错误返回 error
- 示例：
  - `if (s3BucketExists(c, "my-bucket")) { println("存在") }`
- 常见错误：
  - HTTP 200 → true，HTTP 404 → false，其他状态返回 error
  - 请求失败：endpoint 不可达、网络问题

### `s3Close`

- 签名：`s3Close(client) -> undefined`
- 简介：关闭客户端（无实际资源，仅规范占位；客户端由 GC 回收）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
- 返回：undefined（恒成功）
- 示例：
  - `var c = s3Connect(...)`
  - `s3Close(c)  // 显式标记不再使用`
- 常见错误：
  - 客户端无连接池等需释放资源，close 仅作语义占位

### `s3Connect`

- 签名：`s3Connect(endpoint, region, ak, sk, pathStyle?) -> s3Client`
- 简介：创建 S3 兼容客户端（AWS S3 / MinIO / R2 / OSS / COS），自动 SigV4 签名。
- 参数：
  - `endpoint`：服务端点，如 "https://s3.amazonaws.com" 或 "http://minio.local:9000"
  - `region`：区域，如 "us-east-1"
  - `ak`：Access Key
  - `sk`：Secret Key
  - `pathStyle`：可选 bool：是否用 path-style URL（MinIO/R2/OSS/COS 需 true；省略时自动推断）
- 返回：s3Client 客户端对象（其他 s3* 函数的首参）；endpoint 解析失败返回 error
- 示例：
  - `var c = s3Connect("https://s3.amazonaws.com", "us-east-1", "AK...", "SK...")`
  - `var c = s3Connect("http://minio.local:9000", "us-east-1", "minio", "minio123")`
  - `var c = s3Connect("https://s3.amazonaws.com", "us-east-1", "AK", "SK", false)  // 显式 virtual-hosted`
- 常见错误：
  - endpoint 解析失败：需以 http:// 或 https:// 开头
  - path-style 推断规则：非标准端口 / IP / 非 amazonaws.com 默认为 true（兼容 MinIO）
  - 请求超时 30 秒（timeout_secs 固定）

### `s3CopyObject`

- 签名：`s3CopyObject(client, srcBucket, srcKey, dstBucket, dstKey) -> bool`
- 简介：服务端拷贝对象（不经过本地，通过 x-amz-copy-source 头）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `srcBucket`：源 bucket
  - `srcKey`：源对象 key
  - `dstBucket`：目标 bucket
  - `dstKey`：目标对象 key
- 返回：bool：true 拷贝成功；失败返回 error
- 示例：
  - `s3CopyObject(c, "photos", "a.jpg", "photos-backup", "2024/a.jpg")  // → true`
  - `s3CopyObject(c, "logs", "today.log", "logs", "archive/today.log")  // 同 bucket 内拷贝`
- 常见错误：
  - 源对象不存在、权限不足、目标 bucket 不存在
  - 跨 region 拷贝可能不支持（取决于服务端）

### `s3CreateBucket`

- 签名：`s3CreateBucket(client, bucket) -> bool`
- 简介：创建 bucket。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称（须符合 DNS 命名规则）
- 返回：bool：true 创建成功；失败返回 error
- 示例：
  - `s3CreateBucket(c, "my-new-bucket")  // → true`
- 常见错误：
  - HTTP 409：bucket 已存在
  - bucket 名不合法（含大写字母、下划线等）、权限不足

### `s3DeleteBucket`

- 签名：`s3DeleteBucket(client, bucket) -> bool`
- 简介：删除空 bucket（bucket 必须为空，否则失败）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：要删除的 bucket 名称
- 返回：bool：true 删除成功；失败返回 error
- 示例：
  - `s3DeleteBucket(c, "my-empty-bucket")  // → true`
- 常见错误：
  - HTTP 409：bucket 非空（须先删除所有对象）
  - bucket 不存在、权限不足

### `s3DeleteObject`

- 签名：`s3DeleteObject(client, bucket, key) -> bool`
- 简介：删除单个对象。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：要删除的对象 key
- 返回：bool：true 删除成功；失败返回 error
- 示例：
  - `s3DeleteObject(c, "logs", "2024/old.log")  // → true`
- 常见错误：
  - HTTP 404：bucket/key 不存在；权限不足
  - 删除不存在的 key 通常也返回成功（幂等）

### `s3DeleteObjects`

- 签名：`s3DeleteObjects(client, bucket, keys) -> object`
- 简介：批量删除多个对象（逐个 DELETE）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `keys`：array<string>：要删除的 key 列表
- 返回：object：{deleted: int, errors: array<{key, msg}>}
- 示例：
  - `var r = s3DeleteObjects(c, "logs", ["a.log", "b.log", "c.log"])`
  - `// → {"deleted":3, "errors":[]}`
  - `println(r["deleted"])  // 成功删除数`
- 常见错误：
  - 非字符串 key 会被跳过并记入 errors
  - 部分删除失败不影响其他 key（继续尝试），失败项记入 errors 数组
  - 不是 S3 原生批量删除 API，而是循环单删（兼容性更好）

### `s3DownloadFile`

- 签名：`s3DownloadFile(client, bucket, key, localPath) -> bool`
- 简介：将对象下载到本地文件。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：对象 key
  - `localPath`：本地目标文件路径
- 返回：bool：true 下载成功；失败返回 error
- 示例：
  - `s3DownloadFile(c, "backup", "db.sql.gz", "./restored.sql.gz")  // → true`
- 常见错误：
  - HTTP 404：bucket/key 不存在；网络问题
  - 写入本地文件失败：路径不存在、无写入权限

### `s3GetObject`

- 签名：`s3GetObject(client, bucket, key) -> string`
- 简介：读取对象为字符串（UTF-8 解码，适合文本）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：对象 key
- 返回：string：对象内容（UTF-8）；失败返回 error
- 示例：
  - `var text = s3GetObject(c, "logs", "2024/app.log")  // → "log line 1\n"`
  - `println(s3GetObject(c, "config", "app.json"))`
- 常见错误：
  - 二进制内容会以 UTF-8 lossy 解码（乱码），二进制请用 s3GetObjectBytes
  - HTTP 404：bucket/key 不存在；权限不足

### `s3GetObjectBytes`

- 签名：`s3GetObjectBytes(client, bucket, key) -> bytes`
- 简介：读取对象为 bytes（二进制安全）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：对象 key
- 返回：bytes：对象原始字节内容；失败返回 error
- 示例：
  - `var data = s3GetObjectBytes(c, "data", "blob.bin")`
  - `fileWriteBytes("./local.bin", s3GetObjectBytes(c, "photos", "a.jpg"))`
- 常见错误：
  - HTTP 404：bucket/key 不存在；权限不足
  - 适合图片、压缩包等二进制内容

### `s3ListBuckets`

- 签名：`s3ListBuckets(client) -> array<object>`
- 简介：列出当前账号下所有 bucket。
- 参数：
  - `client`：s3Connect 返回的客户端对象
- 返回：array<object>：每个元素为 {name: string, createdAt: string}；失败返回 error
- 示例：
  - `var bs = s3ListBuckets(c)  // → [{"name":"photos","createdAt":"2024-01-01T00:00:00Z"}, ...]`
  - `for (var b in s3ListBuckets(c)) { println(b["name"]) }`
- 常见错误：
  - HTTP 401/403：AK/SK 错误或过期、权限不足、签名错误、本地时钟偏差超 15 分钟
  - 请求失败：endpoint 不可达、网络问题

### `s3ListObjects`

- 签名：`s3ListObjects(client, bucket, prefix?, maxKeys?) -> array<object>`
- 简介：列出 bucket 内对象（支持前缀过滤与最大数量）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `prefix`：可选：对象 key 前缀过滤（默认空串）
  - `maxKeys`：可选：最大返回数量（默认 1000）
- 返回：array<object>：每个元素为 {key:string, size:int, lastModified:string}
- 示例：
  - `s3ListObjects(c, "photos")                       // → [{"key":"a.jpg","size":1024,...}]`
  - `s3ListObjects(c, "photos", "2024/")              // 只列出 2024/ 前缀`
  - `s3ListObjects(c, "photos", "2024/", 100)         // 最多 100 个`
- 常见错误：
  - HTTP 404：bucket 不存在、path-style 配置错误（MinIO 应为 true）
  - 权限不足、endpoint 不可达

### `s3MultipartAbort`

- 签名：`s3MultipartAbort(client, bucket, key, uploadId) -> bool`
- 简介：取消 multipart upload，丢弃已上传分片（避免计费）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：目标对象 key
  - `uploadId`：要取消的 uploadId
- 返回：bool：true 取消成功；失败返回 error
- 示例：
  - `s3MultipartAbort(c, "big", "video.mp4", uploadId)  // 上传中断时清理`
- 常见错误：
  - uploadId 已失效或已完成时仍返回成功（幂等）
  - 网络问题导致取消失败

### `s3MultipartComplete`

- 签名：`s3MultipartComplete(client, bucket, key, uploadId, parts) -> bool`
- 简介：完成 multipart upload，合并所有分片为最终对象。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：目标对象 key
  - `uploadId`：s3MultipartCreate 返回的 uploadId
  - `parts`：array<object>：每个元素为 {partNumber:int, etag:string}（来自 UploadPart 返回）
- 返回：bool：true 完成成功；失败返回 error
- 示例：
  - `s3MultipartComplete(c, "big", "video.mp4", uploadId, [{"partNumber":1,"etag":etag1}, {"partNumber":2,"etag":etag2}])`
- 常见错误：
  - parts 元素必须含 partNumber(int) 和 etag(string) 字段
  - uploadId 失效、part 列表不完整、权限不足
  - 完成后对象才真正可见，未 complete 的分片会被计费（建议失败时 Abort）

### `s3MultipartCreate`

- 签名：`s3MultipartCreate(client, bucket, key, contentType?) -> string`
- 简介：启动 multipart upload，返回 uploadId（用于后续上传分片）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：目标对象 key
  - `contentType`：可选：Content-Type（默认按扩展名推断）
- 返回：string：uploadId（传给 s3MultipartUploadPart / Complete / Abort）；失败返回 error
- 示例：
  - `var uploadId = s3MultipartCreate(c, "big", "video.mp4", "video/mp4")`
- 常见错误：
  - 响应中未找到 UploadId 时返回 error（服务端响应格式异常）
  - HTTP 404：bucket 不存在；权限不足
  - 通常用 s3UploadBigFile 便捷封装，无需手动调用此函数

### `s3MultipartUploadPart`

- 签名：`s3MultipartUploadPart(client, bucket, key, uploadId, partNo, data) -> string`
- 简介：上传单个分片，返回 ETag（含双引号，用于 Complete）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：目标对象 key
  - `uploadId`：s3MultipartCreate 返回的 uploadId
  - `partNo`：分片编号（1-10000）
  - `data`：分片数据：string / bytes / byteArray
- 返回：string：ETag（含双引号）；失败返回 error
- 示例：
  - `var etag = s3MultipartUploadPart(c, "big", "video.mp4", uploadId, 1, chunk1)`
- 常见错误：
  - partNo 必须在 1-10000 之间
  - 除最后一片外每片至少 5MB（S3 规范，服务端校验）
  - 响应缺少 ETag 头返回 error；uploadId 失效、网络问题

### `s3ObjectExists`

- 签名：`s3ObjectExists(client, bucket, key) -> bool`
- 简介：检查对象是否存在（HEAD 请求）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：对象 key
- 返回：bool：true 存在，false 不存在；其他错误返回 error
- 示例：
  - `if (s3ObjectExists(c, "config", "app.json")) { ... }`
- 常见错误：
  - HTTP 200 → true，HTTP 404 → false，其他状态返回 error
  - 请求失败：bucket 不存在、网络问题

### `s3ObjectSize`

- 签名：`s3ObjectSize(client, bucket, key) -> int`
- 简介：获取对象大小（字节，读取 Content-Length 头）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：对象 key
- 返回：int：对象字节数；失败返回 error
- 示例：
  - `var sz = s3ObjectSize(c, "backup", "db.sql.gz")  // → 1048576`
- 常见错误：
  - HTTP 404：对象不存在（与 bucket 不存在的 404 区分需看消息）
  - 响应缺少 Content-Length 头时返回 error（服务端异常）

### `s3PutObject`

- 签名：`s3PutObject(client, bucket, key, body) -> bool`
- 简介：写入对象（body 可为 string/bytes/byteArray），自动推断 Content-Type。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：对象 key（路径）
  - `body`：对象内容：string / bytes / byteArray
- 返回：bool：true 写入成功；失败返回 error
- 示例：
  - `s3PutObject(c, "logs", "2024/app.log", "log line 1\n")  // 文本`
  - `s3PutObject(c, "data", "blob.bin", fileReadBytes("./data.bin"))  // 二进制`
- 常见错误：
  - body 类型必须为 string/bytes/byteArray
  - HTTP 404：bucket 不存在；权限不足；key 不合法
  - 单次 PUT 上限 5GB，更大文件用 s3UploadBigFile

### `s3UploadBigFile`

- 签名：`s3UploadBigFile(client, bucket, key, localPath, partSize?) -> bool`
- 简介：大文件分片上传（自动启动/上传/完成，失败自动 abort；< 5MB 回退单次 PUT）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：目标对象 key
  - `localPath`：本地大文件路径
  - `partSize`：可选：分片大小字节（默认 5MB，最小 5MB，最大 5GB）
- 返回：bool：true 上传成功；失败返回 error（并已自动 abort）
- 示例：
  - `s3UploadBigFile(c, "videos", "movie.mp4", "./movie.mp4")               // 默认 5MB 分片`
  - `s3UploadBigFile(c, "videos", "movie.mp4", "./movie.mp4", 10*1024*1024)  // 10MB 分片`
- 常见错误：
  - partSize 最小 5MB、最大 5GB；分片数上限 10000（文件过大需增大 partSize）
  - 文件 < 5MB 自动回退单次 PUT
  - 任一上传步骤失败自动 abort（清理分片避免计费）
  - 读取本地文件失败：文件不存在、无权限

### `s3UploadFile`

- 签名：`s3UploadFile(client, bucket, key, localPath) -> bool`
- 简介：将本地文件上传为对象（单次 PUT，适合 < 5GB）。
- 参数：
  - `client`：s3Connect 返回的客户端对象
  - `bucket`：bucket 名称
  - `key`：目标对象 key
  - `localPath`：本地源文件路径
- 返回：bool：true 上传成功；失败返回 error
- 示例：
  - `s3UploadFile(c, "backup", "db.sql.gz", "./db.sql.gz")  // → true`
  - `s3UploadFile(c, "photos", "2024/pic.jpg", "C:\\Images\\pic.jpg")`
- 常见错误：
  - 读取本地文件失败：文件不存在、无读取权限
  - 单次 PUT 上限 5GB，更大文件用 s3UploadBigFile
  - HTTP 404：bucket 不存在；权限不足；网络问题

## seq（5 个）

### `getSeq`

- 签名：`getSeq(s, name) -> int`
- 简介：seqGet 的别名。
- 参数：
  - `s`：seq 对象
  - `name`：序号名称
- 返回：int

### `seqGet`

- 签名：`seqGet(s, name) -> int`
- 简介：获取下一个序号（递增并返回）。
- 参数：
  - `s`：seq 对象
  - `name`：序号名称
- 返回：int 下一个序号值

### `seqGetCurrent`

- 签名：`seqGetCurrent(s, name) -> int`
- 简介：获取当前序号（不递增）。
- 参数：
  - `s`：seq 对象
  - `name`：序号名称
- 返回：int 当前值

### `seqNew`

- 签名：`seqNew(connStr) -> seq`
- 简介：创建序号生成器（基于数据库或文件）。
- 参数：
  - `connStr`：连接配置
- 返回：seq 对象
- 示例：
  - `var s = seqNew(cfg)`

### `seqReset`

- 签名：`seqReset(s, name, val) -> undefined`
- 简介：重置序号为指定值。
- 参数：
  - `s`：seq 对象
  - `name`：序号名称
  - `val`：新值
- 返回：undefined

## ssh（22 个）

### `sshCreateFile`

- 签名：`sshCreateFile("--host=...", "--user=...", "--password=...", "--remotePath=/f", "--content=...") -> undefined`
- 简介：在远程创建文件并写入指定内容（通过 SFTP）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程目标文件路径（必填）
  - `--content`：文件内容字符串（默认空串）
- 返回：undefined：创建成功；失败返回 error
- 示例：
  - `sshCreateFile("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/etc/myapp.conf", "--content=port=8080\nlog=info")`
  - `sshCreateFile("--host=h", "--user=u", "--password=p", "--remotePath=/tmp/empty.txt", "--content=")  // 创建空文件`
- 常见错误：
  - SFTP 创建 / 写入失败：远程父目录不存在 / 权限不足
  - 缺少 --remotePath 参数

### `sshDownload`

- 签名：`sshDownload("--host=...", "--user=...", "--password=...", "--remotePath=...", "--localPath=...") -> undefined`
- 简介：用 SFTP 将远程文件下载到本地。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程源文件路径（必填）
  - `--localPath`：本地目标文件路径（必填）
- 返回：undefined：下载成功；失败返回 error
- 示例：
  - `sshDownload("--host=10.0.0.1", "--user=app", "--password=secret", "--remotePath=/var/log/app.log", "--localPath=./app.log")`
- 常见错误：
  - SFTP 读取失败：远程文件不存在 / 权限不足
  - 写入本地文件失败：路径不可写 / 磁盘满
  - 缺少 --remotePath 或 --localPath 参数

### `sshDownloadBytes`

- 签名：`sshDownloadBytes("--host=...", "--user=...", "--password=...", "--remotePath=/f") -> bytes`
- 简介：用 SFTP 下载远程文件到内存 bytes（不落本地磁盘）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程源文件路径（必填）
- 返回：bytes：文件全部内容的字节串；失败返回 error
- 示例：
  - `var data = sshDownloadBytes("--host=10.0.0.1", "--user=app", "--password=secret", "--remotePath=/tmp/data.bin")`
  - `fileWriteBytes("./local.bin", sshDownloadBytes("--host=h", "--user=u", "--password=p", "--remotePath=/tmp/x"))`
- 常见错误：
  - SFTP 读取失败：远程文件不存在 / 权限不足
  - 缺少 --remotePath 参数

### `sshEnsureMakeDirs`

- 签名：`sshEnsureMakeDirs("--host=...", "--user=...", "--password=...", "--remotePath=/a/b/c") -> undefined`
- 简介：递归创建远程目录（类似 mkdir -p），已存在的目录跳过。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要递归创建的远程目录路径（必填）
- 返回：undefined：创建成功；失败返回 error
- 示例：
  - `sshEnsureMakeDirs("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/opt/myapp/logs/2024")`
  - `sshEnsureMakeDirs("--host=h", "--user=u", "--password=p", "--remotePath=/a/b/c")  // 逐级创建`
- 常见错误：
  - 与 sshMkdir 区别：本函数递归创建父目录（mkdir -p 语义）
  - 中间某级创建失败：权限不足 / 已存在同名文件（非目录）
  - 缺少 --remotePath 参数

### `sshGetFileInfo`

- 签名：`sshGetFileInfo("--host=...", "--user=...", "--password=...", "--remotePath=/path") -> map`
- 简介：获取远程文件信息（大小、修改时间、是否目录等）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程文件或目录路径（必填）
- 返回：map：{size:int, mtime:int, atime:int, isDir:bool, isFile:bool, isSymlink:bool}；文件不存在返回 error
- 示例：
  - `var info = sshGetFileInfo("--host=10.0.0.1", "--user=u", "--password=p", "--remotePath=/var/log/syslog")`
  - `if (info["isDir"]) { ... }`
  - `println(info["size"])  // 文件字节数`
- 常见错误：
  - SFTP 获取文件信息失败：文件不存在 / 权限不足
  - size/mtime/atime 可能为 0（服务器未返回时）
  - 缺少 --remotePath 参数

### `sshIfFileExists`

- 签名：`sshIfFileExists("--host=...", "--user=...", "--password=...", "--remotePath=/path") -> bool`
- 简介：检查远程文件或目录是否存在（通过 SFTP stat）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要检查的远程路径（必填）
- 返回：bool：true 存在（文件或目录），false 不存在；连接失败返回 error
- 示例：
  - `if (sshIfFileExists("--host=10.0.0.1", "--user=u", "--password=p", "--remotePath=/etc/myapp.conf")) { ... }`
- 常见错误：
  - 连接 / 认证失败返回 error（与文件不存在的 false 区分）
  - 缺少 --remotePath 参数

### `sshJoinPath`

- 签名：`sshJoinPath(base, sub) -> string`
- 简介：拼接远程路径（固定用 / 分隔符，自动处理重复或缺失的斜杠）。
- 参数：
  - `base`：基础路径（字符串）
  - `sub`：要拼接的子路径（字符串）
- 返回：string：拼接后的路径（智能处理首尾斜杠）
- 示例：
  - `sshJoinPath("/home/user", "data")        // → "/home/user/data"`
  - `sshJoinPath("/home/user/", "/data")      // → "/home/user/data"`
  - `sshJoinPath("/home/user", "sub/dir/")    // → "/home/user/sub/dir/"`
- 常见错误：
  - 纯字符串操作，不需要 SSH 连接（速度极快）
  - 参数应为 string 类型，类型不符返回 error
  - 需要 2 个参数 (base, sub)

### `sshList`

- 签名：`sshList("--host=...", "--user=...", "--password=...", "--remotePath=/dir") -> array<string>`
- 简介：通过 SFTP 列出远程目录下的文件名（不含子目录递归）。
- 参数：
  - `--host/--user/--password`：认证参数（同 sshRun）
  - `--remotePath`：要列出的远程目录路径，默认 /
- 返回：array<string>：目录下条目的文件名；失败返回 error
- 示例：
  - `sshList("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/var/log")  // → ["syslog","auth.log"]`
  - `sshList("--host=10.0.0.1", "--user=app", "--password=secret", "--remotePath=/home/app")`
- 常见错误：
  - SFTP 读取目录失败：路径不存在 / 权限不足
  - 认证 / 连接失败（同 sshRun）

### `sshListDetail`

- 签名：`sshListDetail(--host=..., --user=..., --password=..., --remotePath=...) -> array<map>`
- 简介：列出远程目录内容（含元信息：名称/大小/类型/修改时间）。SSH 文件浏览器使用。
- 参数：
  - `--host`：SSH 主机地址
  - `--user`：用户名
  - `--password`：密码（或 --key 密钥路径）
  - `--remotePath`：远程目录路径，默认 /
  - `--port`：可选。端口，默认 22
- 返回：array<map{name,size,isDir,isFile,isSymlink,mtime}>；失败返回 error
- 示例：
  - `var items = sshListDetail("--host=1.2.3.4", "--user=root", "--password=x", "--remotePath=/etc")`
- 常见错误：
  - 连接失败或目录不存在返回 error

### `sshMkdir`

- 签名：`sshMkdir("--host=...", "--user=...", "--password=...", "--remotePath=/dir") -> undefined`
- 简介：用 SFTP 在远程创建单个目录（父目录必须存在，非递归）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要创建的远程目录路径（必填）
- 返回：undefined：创建成功；失败返回 error
- 示例：
  - `sshMkdir("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/opt/newapp")`
- 常见错误：
  - SFTP 创建目录失败：父目录不存在（如需递归用 sshEnsureMakeDirs）/ 权限不足 / 目录已存在
  - 缺少 --remotePath 参数

### `sshMove`

- 签名：`sshMove("--host=...", "--user=...", "--password=...", "--remotePath=/a", "--targetPath=/b") -> undefined`
- 简介：移动或重命名远程文件 / 目录（SFTP rename）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：源路径（必填）
  - `--targetPath`：目标路径（必填）
- 返回：undefined：移动成功；失败返回 error
- 示例：
  - `sshMove("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/tmp/a.log", "--targetPath=/var/log/a.log")`
  - `sshMove("--host=10.0.0.1", "--user=u", "--password=p", "--remotePath=/old/name", "--targetPath=/new/name")  // 重命名`
- 常见错误：
  - SFTP 移动失败：源路径不存在 / 目标路径已存在 / 跨文件系统 / 权限不足
  - 缺少 --remotePath 或 --targetPath 参数

### `sshRemove`

- 签名：`sshRemove("--host=...", "--user=...", "--password=...", "--remotePath=/path") -> undefined`
- 简介：删除远程文件或目录（自动尝试先删文件再删目录）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：要删除的远程文件或目录路径（必填）
- 返回：undefined：删除成功；失败返回 error
- 示例：
  - `sshRemove("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/tmp/old.log")`
  - `sshRemove("--host=10.0.0.1", "--user=root", "--password=secret", "--remotePath=/opt/emptydir")`
- 常见错误：
  - SFTP 删除失败：路径不存在 / 权限不足 / 目录非空
  - 内部先尝试 remove_file 再 remove_dir，两者都失败才报错

### `sshRun`

- 签名：`sshRun("--host=...", "--user=...", "--password=...", command, opts...) -> string`
- 简介：在远程主机执行 shell 命令，返回 stdout 输出（含 stderr）。
- 参数：
  - `--host`：远程主机地址（必填）
  - `--user`：登录用户名（必填）
  - `--password`：密码认证（与 --key 二选一；支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--key`：私钥文件路径（与 --password 二选一）
  - `--keyPassphrase`：私钥口令（可选，私钥加密时）
  - `--port`：SSH 端口，默认 22
  - `--cmdTimeout`：命令超时秒数，默认 0（无超时）
  - `command`：要执行的 shell 命令（位置参数；也兼容 Charlang 迁移写法 -cmd=<命令>）
- 返回：string：命令的标准输出（含合并的 stderr）；失败返回 error
- 示例：
  - `sshRun("--host=10.0.0.1", "--user=root", "--password=secret", "uname -a")`
  - `sshRun("--host=10.0.0.1", "--user=app", "--key=/home/app/.ssh/id_rsa", "ls -la /var/log")`
  - `sshRun("--host=10.0.0.1", "--user=app", "--password=secret", "--cmdTimeout=10", "sleep 999")`
- 常见错误：
  - SSH 连接失败：网络不通 / 端口错误（返回 error 而非抛异常）
  - 认证失败：密码或私钥被拒绝
  - 缺少 --host / --user 参数；未提供 --password 或 --key
  - 命令超时（--cmdTimeout 到期）

### `sshShellClose`

- 签名：`sshShellClose(session) -> undefined`
- 简介：关闭 PTY 会话（发送 EOF + disconnect），释放资源。
- 参数：
  - `session`：sshShellOpen 返回的会话对象
- 返回：undefined
- 示例：
  - `sshShellClose(sess)`

### `sshShellKeepalive`

- 签名：`sshShellKeepalive(session, --interval=30, --cmd="") -> undefined`
- 简介：启动保活线程：默认 SSH 协议级 keepalive；--cmd 非空时额外周期执行该命令。
- 参数：
  - `session`：sshShellOpen 返回的会话对象
  - `--interval`：保活间隔秒数，默认 30；≤0 表示禁用
  - `--cmd`：可选的空命令心跳，如 "echo ."；空则仅协议级 keepalive
- 返回：undefined
- 示例：
  - `sshShellKeepalive(sess)                            // 默认 30s 协议级`
  - `sshShellKeepalive(sess, "--interval=60")           // 60s`
  - `sshShellKeepalive(sess, "--cmd=echo .")            // 额外执行空命令`

### `sshShellOpen`

- 签名：`sshShellOpen(--host=..., --user=..., --password=..., --cols=80, --rows=24, opts...) -> session`
- 简介：建立 SSH 连接 + 申请 PTY + 启动交互式 shell，返回会话对象。
- 参数：
  - `--host/--user/--password`：认证参数（同 sshRun）
  - `--key`：私钥路径（与 --password 二选一）
  - `--keyPassphrase`：私钥口令
  - `--port`：SSH 端口，默认 22
  - `--cols`：终端列数，默认 80
  - `--rows`：终端行数，默认 24
- 返回：session 会话对象（用于 sshShellWrite/Resize/Close）；失败返回 error
- 示例：
  - `sshShellOpen("--host=10.0.0.1", "--user=root", "--password=secret", "--cols=120", "--rows=40")`
- 常见错误：
  - SSH 连接失败：网络不通 / 端口错误（返回 error）
  - 认证失败：密码或私钥被拒绝
  - PTY 申请失败：服务器不允许 PTY（如 SFTP-only 账户）

### `sshShellResize`

- 签名：`sshShellResize(session, cols, rows) -> undefined`
- 简介：调整远程 PTY 窗口大小（对应 xterm.js 的 onResize）。
- 参数：
  - `session`：sshShellOpen 返回的会话对象
  - `cols`：新列数（int）
  - `rows`：新行数（int）
- 返回：undefined；失败返回 error
- 示例：
  - `sshShellResize(sess, 120, 40)`
- 常见错误：
  - session 已关闭或无效
  - 服务器不支持 window-change（罕见）

### `sshShellStreamId`

- 签名：`sshShellStreamId(session) -> int`
- 简介：返回会话的流 ID（前端用此区分 onStreamData 的来源）。
- 参数：
  - `session`：sshShellOpen 返回的会话对象
- 返回：int 流 ID
- 示例：
  - `var sid = sshShellStreamId(sess)`

### `sshShellWrite`

- 签名：`sshShellWrite(session, data) -> undefined`
- 简介：向 PTY 写入用户输入（字节流或字符串）。
- 参数：
  - `session`：sshShellOpen 返回的会话对象
  - `data`：要写入的数据：string 或 bytes
- 返回：undefined；失败返回 error
- 示例：
  - `sshShellWrite(sess, "ls -la\r")`
  - `sshShellWrite(sess, bytes([3]))  // Ctrl+C`
- 常见错误：
  - session 已关闭或无效
  - 网络写入失败

### `sshSync`

- 签名：`sshSync("--host=...", "--localPath=...", "--remotePath=...", "--direction=push|pull", opts...) -> array<string>`
- 简介：在本地与远程之间同步目录（push 本地→远程，pull 远程→本地）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--localPath`：本地目录（必填）
  - `--remotePath`：远程目录（必填）
  - `--direction`：方向：push（默认）或 pull
  - `--recursive`：开关：递归同步子目录
  - `--delete`：开关：删除目标侧多余的文件（镜像同步）
  - `--dryRun`：开关：只输出将执行的操作，不实际写入
- 返回：array<string>：同步操作日志（如 PUT local → remote (N bytes)、DEL path）
- 示例：
  - `sshSync("--host=10.0.0.1", "--user=app", "--password=secret", "--localPath=./www", "--remotePath=/var/www", "--direction=push", "--recursive", "--delete")`
  - `sshSync("--host=h", "--user=u", "--password=p", "--localPath=./bak", "--remotePath=/data", "--direction=pull", "--dryRun")  // 预演`
- 常见错误：
  - --direction 只支持 push 或 pull，其他值返回 error
  - 读取本地 / 远程目录失败：路径不存在 / 权限不足
  - 缺少 --localPath 或 --remotePath 参数

### `sshUpload`

- 签名：`sshUpload("--host=...", "--user=...", "--password=...", "--localPath=...", "--remotePath=..." [, "--append"]) -> undefined`
- 简介：用 SFTP 将本地文件上传到远程主机。默认覆盖写入；指定 --append 时追加到远程文件末尾（文件不存在则创建）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--localPath`：本地源文件路径（必填）
  - `--remotePath`：远程目标文件路径（必填）
  - `--append`：可选开关。追加模式：数据写入远程文件末尾而非覆盖
- 返回：undefined：上传成功；失败返回 error
- 示例：
  - `sshUpload("--host=10.0.0.1", "--user=app", "--password=secret", "--localPath=./config.cfg", "--remotePath=/etc/app/config.cfg")`
  - `sshUpload("--host=10.0.0.1", "--user=root", "--key=/home/u/.ssh/id", "--localPath=C:\\data.zip", "--remotePath=/tmp/data.zip")`
- 常见错误：
  - 读取本地文件失败：路径不存在 / 权限不足
  - SFTP 创建 / 写入失败：远程路径父目录不存在 / 权限不足
  - 缺少 --localPath 或 --remotePath 参数

### `sshUploadBytes`

- 签名：`sshUploadBytes(data, "--host=...", "--user=...", "--password=...", "--remotePath=/f" [, "--append"]) -> undefined`
- 简介：用 SFTP 将内存数据上传到远程文件。数据可为 bytes/byteArray/string（string 按 UTF-8 编码）。默认覆盖写入；指定 --append 时追加到文件末尾（文件不存在则创建）。
- 参数：
  - `--host/--user/--password`：认证参数（--password 支持 //TXDEF# / 740404 加密格式，自动解密）
  - `--remotePath`：远程目标文件路径（必填）
  - `--append`：可选开关。追加模式：数据写入远程文件末尾而非覆盖
  - `data`：要上传的 bytes/byteArray/string（最后一个非开关参数；以 - 开头的字符串视为开关参数）
- 返回：undefined：上传成功；失败返回 error
- 示例：
  - `sshUploadBytes("--host=10.0.0.1", "--user=app", "--password=secret", "--remotePath=/tmp/data.bin", fileReadBytes("./local.bin"))`
  - `sshUploadBytes(getNowStr() + "\n", "--host=h", "--user=u", "--password=p", "--remotePath=/var/log/app.log", "--append")  // 直接上传字符串并追加一行`
- 常见错误：
  - 缺少数据参数（bytes/byteArray/string，最后一个非开关参数）
  - SFTP 创建 / 写入失败：远程路径无效 / 权限不足
  - 缺少 --remotePath 参数

## string（43 个）

### `bytesAt`

- 签名：`bytesAt(b, idx) -> int（b 为 string 或 bytes/byteArray）`
- 简介：获取字节值（0-255）。
- 参数：
  - `b`：bytes/string
  - `idx`：字节索引
- 返回：int

### `bytesGbToUtf8Str`

- 签名：`bytesGbToUtf8Str(b) -> string`
- 简介：GBK 字节转 UTF-8。
- 参数：
  - `b`：GBK bytes
- 返回：string

### `bytesSlice`

- 签名：`bytesSlice(b, start[, end]) -> bytes（b 为 string 或 bytes/byteArray）`
- 简介：按字节切片。
- 参数：
  - `b`：bytes/string
  - `start`：起始
  - `end`：可选
- 返回：bytes

### `charFromCode`

- 签名：`charFromCode(code) -> string`
- 简介：Unicode 码点转字符。
- 参数：
  - `code`：码点
- 返回：string

### `codeOf`

- 签名：`codeOf(s) -> int`
- 简介：字符转 Unicode 码点。
- 参数：
  - `s`：单字符
- 返回：int

### `formatCode`

- 签名：`formatCode(src) -> string`
- 简介：格式化 Sflang 源码：按大括号深度重排缩进（4 空格/层），去行尾空白，行首 Tab 展开，连续空行压缩为最多 2 行，结尾恰一个换行。
- 参数：
  - `src`：Sflang 源码字符串
- 返回：string：格式化后的源码（保持语义不变；不重排跨行结构）
- 示例：
  - `formatCode("func f() {
pln(1)
}") → 第二行缩进 4 空格`
  - `字符串/原始字符串/注释中的 {} 不影响缩进`

### `isUtf8`

- 签名：`isUtf8(b) -> bool`
- 简介：是否有效 UTF-8。
- 参数：
  - `b`：bytes
- 返回：bool

### `lenBytes`

- 签名：`lenBytes(b) -> int`
- 简介：返回字节长度。
- 参数：
  - `b`：bytes/string
- 返回：int

### `reverseMap`

- 签名：`reverseMap(m) -> object`
- 简介：反转 map 键值。
- 参数：
  - `m`：object/map
- 返回：object

### `simpleStrToMap`

- 签名：`simpleStrToMap(s[, sep1[, sep2]]) -> object`
- 简介：解析 key=val 为 map。sep1/sep2 为可选，缺省分别为 "," 与 "="。
- 参数：
  - `s`：字符串
  - `sep1`：可选。对分隔符，缺省 ","
  - `sep2`：可选。键值分隔符，缺省 "="
- 返回：object
- 示例：
  - `simpleStrToMap("a=1,b=2")  → {a: "1", b: "2"}`

### `strContainsAny`

- 签名：`strContainsAny(s, chars) -> bool`
- 简介：是否包含任意指定字符。
- 参数：
  - `s`：字符串
  - `chars`：字符集
- 返回：bool

### `strContainsIn`

- 签名：`strContainsIn(s, arr) -> bool`
- 简介：是否包含数组中任意子串。
- 参数：
  - `s`：字符串
  - `arr`：子串数组
- 返回：bool

### `strCount`

- 签名：`strCount(s, sub) -> int`
- 简介：统计子串出现次数。
- 参数：
  - `s`：字符串
  - `sub`：子串
- 返回：int

### `strEndsWith`

- 签名：`strEndsWith(s, suffix) -> bool`
- 简介：判断字符串 s 是否以 suffix 结尾。
- 参数：
  - `s`：原字符串
  - `suffix`：后缀字符串
- 返回：bool
- 示例：
  - `strEndsWith("hello", "lo")  → true`

### `strFind`

- 签名：`strFind(sub, s) -> int`
- 简介：查找子串 sub 在 s 中首次出现的字符索引。
- 参数：
  - `sub`：要查找的子串
  - `s`：被搜索的字符串
- 返回：int 首次出现的索引（0-based）；未找到返回 -1
- 示例：
  - `strFind("lo", "hello")   → 3`
  - `strFind("x", "hello")    → -1`
- 常见错误：
  - 参数顺序：sub 在前，s 在后

### `strFindDiffPos`

- 签名：`strFindDiffPos(a, b) -> int`
- 简介：首个不同位置。
- 参数：
  - `a`：字符串1
  - `b`：字符串2
- 返回：int；相同返回 -1

### `strJoin`

- 签名：`strJoin(arr, sep) -> string`
- 简介：用分隔符 sep 连接字符串数组的各元素。
- 参数：
  - `arr`：待连接的字符串数组（非字符串元素自动转换）
  - `sep`：分隔符字符串
- 返回：string 连接后的字符串
- 示例：
  - `strJoin(["a","b","c"], ",")   → "a,b,c"`
  - `strJoin(["a","b"], "")         → "ab"`
- 常见错误：
  - 参数顺序：arr 在前，sep 在后

### `strLimit`

- 签名：`strLimit(s, maxLen[, suffix]) -> string`
- 简介：截断到 maxLen 字符。结果总长度（含后缀）不超过 maxLen；后缀比 maxLen 长时截短后缀。默认后缀 "..."。
- 参数：
  - `s`：字符串
  - `maxLen`：最大长度（≥0）
  - `suffix`：可选。默认 ...
- 返回：string
- 示例：
  - `strLimit("Hello World", 5)  → "He..."`
- 常见错误：
  - maxLen 为负返回 error

### `strPad`

- 签名：`strPad(s, len[, pad[, align]]) -> string`
- 简介：填充到指定长度。
- 参数：
  - `s`：字符串
  - `len`：目标长度
  - `pad`：可选
  - `align`：可选。left/right/center
- 返回：string

### `strQuote`

- 签名：`strQuote(s) -> string`
- 简介：用双引号包裹并转义。
- 参数：
  - `s`：字符串
- 返回：string

### `strRemoveBomHead`

- 签名：`strRemoveBomHead(s) -> string`
- 简介：去除 UTF-8 BOM。
- 参数：
  - `s`：字符串
- 返回：string

### `strRepeat`

- 签名：`strRepeat(s, n) -> string`
- 简介：将字符串重复 n 次。
- 参数：
  - `s`：原字符串
  - `n`：重复次数（int，≥0）
- 返回：string 重复后的字符串
- 示例：
  - `strRepeat("ab", 3)  → "ababab"`

### `strReplace`

- 签名：`strReplace(s, old, new) / strReplace(s, old1, new1, old2, new2, ...) -> string`
- 简介：替换字符串中的子串（全部替换）。支持多对替换依次执行。
- 参数：
  - `s`：原字符串
  - `old`：要替换的子串
  - `new`：替换为的子串
- 返回：string 替换后的字符串
- 示例：
  - `strReplace("a-b-c", "-", "+")        → "a+b+c"`
  - `strReplace("abc", "a", "x", "b", "y")  → "xyc"`

### `strReplaceN`

- 签名：`strReplaceN(s, old, new, n) -> string`
- 简介：替换前 n 个匹配。
- 参数：
  - `s`：字符串
  - `old`：旧子串
  - `new`：新子串
  - `n`：次数
- 返回：string

### `strSplit`

- 签名：`strSplit(s, sep) -> array<string>`
- 简介：按分隔符 sep 分割字符串 s（源串在前，与主流语言一致）。
- 参数：
  - `s`：被分割的字符串
  - `sep`：分隔符字符串（非正则）
- 返回：array<string> 分割后的片段
- 示例：
  - `strSplit("a,b,c", ",")    → ["a", "b", "c"]`
  - `strSplit("abc", "")       → ["a", "b", "c"]（空分隔符按字符分割）`
- 常见错误：
  - 参数顺序：s 在前，sep 在后

### `strSplitLines`

- 签名：`strSplitLines(s) -> array<string>`
- 简介：按行分割。
- 参数：
  - `s`：多行文本
- 返回：array<string>

### `strSplitN`

- 签名：`strSplitN(s, sep, n) -> array<string>`
- 简介：分割，最多 n 段（源串在前，与 strSplit 一致）。
- 参数：
  - `s`：字符串
  - `sep`：分隔符
  - `n`：最大段数
- 返回：array<string>
- 示例：
  - `strSplitN("a,b,c,d", ",", 2)  → ["a", "b,c,d"]`

### `strStartsWith`

- 签名：`strStartsWith(s, prefix) -> bool`
- 简介：判断字符串 s 是否以 prefix 开头。
- 参数：
  - `s`：原字符串
  - `prefix`：前缀字符串
- 返回：bool
- 示例：
  - `strStartsWith("hello", "he")  → true`

### `strSub`

- 签名：`strSub(s, start[, end]) -> string`
- 简介：截取子串。索引基于字符（Unicode scalar），负数表示从末尾倒数。
- 参数：
  - `s`：原字符串
  - `start`：起始字符索引（含），负数从末尾倒数
  - `end`：可选。结束字符索引（不含）；省略则到末尾
- 返回：string 截取的子串
- 示例：
  - `strSub("hello", 1, 3)    → "el"`
  - `strSub("hello", 2)       → "llo"`
  - `strSub("hello", -2)      → "lo"`

### `strSubBytes`

- 签名：`strSubBytes(s, start[, end]) -> string`
- 简介：按字节截取子串。
- 参数：
  - `s`：字符串
  - `start`：字节起始
  - `end`：可选
- 返回：string

### `strToFloat`

- 签名：`strToFloat(s) -> float|error`
- 简介：字符串转浮点。
- 参数：
  - `s`：数字字符串
- 返回：float；失败 error

### `strToGbkBytes`

- 签名：`strToGbkBytes(s) -> bytes`
- 简介：UTF-8 转 GBK 字节。
- 参数：
  - `s`：字符串
- 返回：bytes

### `strToInt`

- 签名：`strToInt(s) -> int|error`
- 简介：字符串转整数。
- 参数：
  - `s`：数字字符串
- 返回：int；失败 error

### `strToLower`

- 签名：`strToLower(s) -> string`
- 简介：将字符串转为小写（Unicode 感知）。
- 参数：
  - `s`：原字符串
- 返回：string 小写形式
- 示例：
  - `strToLower("HELLO")  → "hello"`

### `strToUpper`

- 签名：`strToUpper(s) -> string`
- 简介：将字符串转为大写（Unicode 感知）。
- 参数：
  - `s`：原字符串
- 返回：string 大写形式
- 示例：
  - `strToUpper("hello")  → "HELLO"`
  - `strToUpper("你好")    → "你好"`

### `strToUtf8`

- 签名：`strToUtf8(b) -> string`
- 简介：字节转 UTF-8 字符串。
- 参数：
  - `b`：bytes
- 返回：string

### `strTrim`

- 签名：`trim(s) -> string`
- 简介：去除字符串首尾空白字符（空格/制表/换行）。别名 strTrim。
- 参数：
  - `s`：原字符串；undefined 视为空串
- 返回：string 去除首尾空白后的字符串
- 示例：
  - `trim("  hi  ")  → "hi"`

### `strTrimLeft`

- 签名：`strTrimLeft(s, cutset) -> string`
- 简介：去除左侧指定字符集。
- 参数：
  - `s`：字符串
  - `cutset`：字符集
- 返回：string

### `strTrimPrefix`

- 签名：`strTrimPrefix(s, prefix) -> string`
- 简介：去除头部子串（如有）。
- 参数：
  - `s`：字符串
  - `prefix`：前缀
- 返回：string

### `strTrimRight`

- 签名：`strTrimRight(s, cutset) -> string`
- 简介：去除右侧指定字符集。
- 参数：
  - `s`：字符串
  - `cutset`：字符集
- 返回：string

### `strTrimSuffix`

- 签名：`strTrimSuffix(s, suffix) -> string`
- 简介：去除尾部子串（如有）。
- 参数：
  - `s`：字符串
  - `suffix`：后缀
- 返回：string

### `strUnquote`

- 签名：`strUnquote(s) -> string`
- 简介：去除引号并反转义。
- 参数：
  - `s`：带引号字符串
- 返回：string

### `trim`

- 签名：`trim(s) -> string`
- 简介：去除字符串首尾空白字符（空格/制表/换行）。别名 strTrim。
- 参数：
  - `s`：原字符串；undefined 视为空串
- 返回：string 去除首尾空白后的字符串
- 示例：
  - `trim("  hi  ")  → "hi"`

## system（27 个）

### `absPath`

- 签名：`absPath(path) -> string`
- 简介：返回绝对路径。
- 参数：
  - `path`：相对或绝对路径
- 返回：string 绝对路径

### `baseName`

- 签名：`baseName(path) -> string`
- 简介：返回路径的文件名部分。
- 参数：
  - `path`：文件路径
- 返回：string

### `changeDir`

- 签名：`changeDir(path) -> undefined`
- 简介：改变当前工作目录（影响后续相对路径解析）。等同于 shell 的 cd。
- 参数：
  - `path`：目标目录路径
- 返回：undefined
- 示例：
  - `changeDir("/tmp")`
  - `changeDir("..")`
- 常见错误：
  - 目录不存在或权限不足返回 error
  - 影响整个进程的相对路径基准；子线程也会受影响

### `dirName`

- 签名：`dirName(path) -> string`
- 简介：返回路径的目录部分。
- 参数：
  - `path`：文件路径
- 返回：string

### `exit`

- 签名：`exit([code]) -> !`
- 简介：立即退出进程。可选 code 为退出码（int，默认 0）。
- 参数：
  - `code`：可选退出码（int，默认 0）
- 返回：不返回（进程直接终止）
- 示例：
  - `exit(1)`
  - `exit()   // 等同 exit(0)`
- 常见错误：
  - 不会触发 defer；调用后进程立即终止

### `fileExt`

- 签名：`fileExt(path) -> string`
- 简介：返回文件扩展名（含点）。
- 参数：
  - `path`：文件路径
- 返回：string

### `getChar`

- 签名：`getChar() -> string`
- 简介：读取单个按键（无需回车）。
- 返回：string 单字符

### `getCurDir`

- 签名：`getCurDir() -> string`
- 简介：返回当前工作目录的绝对路径。
- 返回：string 当前工作目录
- 示例：
  - `getCurDir()   → "/home/user/project"`
  - `println(getCurDir())`
- 常见错误：
  - 目录被删除或权限不足返回 error

### `getEnv`

- 签名：`getEnv(name) -> string|undefined`
- 简介：读取环境变量。不存在（或未设置）返回 undefined。
- 参数：
  - `name`：环境变量名（区分大小写）
- 返回：string 变量值；未设置返回 undefined
- 示例：
  - `getEnv("PATH")        → "/usr/bin:..."`
  - `var home = getEnv("HOME") ?? "/tmp"`
- 常见错误：
  - 环境变量名在 Unix 区分大小写；未设置返回 undefined（非 error）

### `getHomeDir`

- 签名：`getHomeDir() -> string`
- 简介：返回用户主目录。
- 返回：string

### `getInput`

- 签名：`getInput([prompt]) -> string|undefined`
- 简介：从标准输入读一行（去掉末尾换行）。可选 prompt 作为提示先打印到 stdout。
- 参数：
  - `prompt`：可选提示字符串，先打印（不换行）
- 返回：string 读到的行；EOF（Ctrl+D / Ctrl+Z）返回 undefined
- 示例：
  - `name := getInput("请输入姓名: ")`
  - `line := getInput()`
- 常见错误：
  - stdin 被关闭或重定向导致读取失败返回 error
  - EOF 返回 undefined（须判空），不会报错

### `getInputPassword`

- 签名：`getInputPassword([prompt]) -> string`
- 简介：读取密码输入（不回显）。
- 参数：
  - `prompt`：可选。提示信息
- 返回：string

### `getOsArgs`

- 签名：`getOsArgs() -> array<string>`
- 简介：返回命令行参数（含程序名）。
- 返回：array<string>

### `getTempDir`

- 签名：`getTempDir() -> string`
- 简介：返回系统临时目录。
- 返回：string

### `getVersion`

- 签名：`getVersion() -> string`
- 简介：返回 Sflang 解释器版本号（如 "0.1.6"）。
- 返回：string Cargo 包版本号
- 示例：
  - `getVersion()  → "0.1.6"`
  - `pln("Sflang v" + getVersion())`

### `joinPath`

- 签名：`joinPath(seg1, seg2, ...) -> string`
- 简介：用平台路径分隔符拼接多个路径段，自动处理冗余分隔符。
- 参数：
  - `segN`：路径段（可变参数，每段为 string）
- 返回：string 拼接后的路径
- 示例：
  - `joinPath("a", "b", "c.txt")   → "a/b/c.txt"`
  - `joinPath("/usr", "local/bin")  → "/usr/local/bin"`
- 常见错误：
  - 所有参数须为 string，非 string 会报错

### `listDir`

- 签名：`listDir(path) -> array<string>`
- 简介：列出目录下的条目名（不递归，仅返回文件名不含路径前缀）。
- 参数：
  - `path`：目录路径
- 返回：array<string> 条目名数组；目录不存在或非目录返回 error
- 示例：
  - `listDir(".")   → ["a.txt", "sub", "b.rs"]`
  - `for (name in listDir(dir)) { ... }`
- 常见错误：
  - 路径不存在或不是目录返回 error
  - 返回的是名称（不含父路径），需完整路径请用 joinPath 拼接

### `lookPath`

- 签名：`lookPath(name) -> string|undefined`
- 简介：在 PATH 环境变量中查找可执行文件路径（Windows 自动尝试 PATHEXT 中的扩展名）。
- 参数：
  - `name`：可执行文件名（如 "go"、"python"）或含分隔符的路径
- 返回：string 找到的完整路径；未找到返回 undefined
- 示例：
  - `lookPath("go")      → "/usr/local/go/bin/go"`
  - `lookPath("python") → undefined（未安装时）`
  - `var p = lookPath("git")`
- 常见错误：
  - 未找到返回 undefined（非 error）
  - name 含 / 或 \ 时直接检查该路径是否为文件

### `makeDir`

- 签名：`makeDir(path) -> undefined`
- 简介：创建单层目录（父目录须存在；目录已存在则报错）。递归建目录请用 makeDirAll。
- 参数：
  - `path`：要创建的目录路径
- 返回：undefined
- 示例：
  - `makeDir("newdir")`
  - `makeDir("a/b/c")  // a/b 须已存在，否则报错`
- 常见错误：
  - 目录已存在、父目录缺失、权限不足均返回 error
  - 递归创建多层请用 makeDirAll

### `makeDirAll`

- 签名：`makeDirAll(path) -> error|undefined`
- 简介：递归创建目录。
- 参数：
  - `path`：目录路径
- 返回：undefined；失败返回 error

### `osArch`

- 签名：`osArch() -> string`
- 简介：返回 CPU 架构名：amd64 / arm64 / 386（其他回退到 std::env::consts::ARCH）。
- 返回：string 编译期确定的架构名称
- 示例：
  - `osArch()   → "amd64"`

### `osName`

- 签名：`osName() -> string`
- 简介：返回操作系统名：windows / linux / macos（未知为 unknown）。
- 返回：string 编译期确定的 OS 名称
- 示例：
  - `osName()   → "linux"`
  - `if (osName() == "windows") { ... }`

### `removeDir`

- 签名：`removeDir(path) -> error|undefined`
- 简介：删除目录。
- 参数：
  - `path`：目录路径
- 返回：undefined

### `rename`

- 签名：`rename(old, new) -> error|undefined`
- 简介：重命名/移动文件或目录。
- 参数：
  - `old`：旧路径
  - `new`：新路径
- 返回：undefined

### `setEnv`

- 签名：`setEnv(name, val) -> undefined`
- 简介：设置环境变量（仅当前进程及其子进程可见，不持久化到系统）。
- 参数：
  - `name`：环境变量名
  - `val`：变量值（string）
- 返回：undefined
- 示例：
  - `setEnv("MY_VAR", "hello")`
  - `systemCmd("echo $MY_VAR")  // 子进程可见`
- 常见错误：
  - 参数顺序：name 在前，val 在后
  - 仅影响当前进程；退出后不保留（不写入注册表/shell 配置）

### `systemCmd`

- 签名：`systemCmd(cmd[, arg1, arg2, ...]) -> string`
- 简介：执行 shell 命令（Windows 用 cmd /C，Unix 用 sh -c），返回 stdout 字符串。
- 参数：
  - `cmd`：命令字符串（如 "ls" 或 "dir"）
  - `argN`：可选追加参数（string，附加到命令后）
- 返回：string 命令的 stdout 输出；命令失败（含 stderr）返回 error
- 示例：
  - `systemCmd("echo hello")   → "hello\n"`
  - `systemCmd("ping", "127.0.0.1")`
  - `var out = systemCmd("git status")`
- 常见错误：
  - 命令不存在或权限不足返回 error
  - 退出码非 0 且有 stderr 时合并拼成 error 信息
  - 存在命令注入风险，切勿将不可信输入直接拼接为 cmd

### `systemCmdDetached`

- 签名：`systemCmdDetached(cmd) -> undefined`
- 简介：后台执行命令（不等待）。
- 参数：
  - `cmd`：命令字符串
- 返回：undefined

## tcp（13 个）

### `tcpClose`

- 签名：`tcpClose(conn [, how]) -> undefined`
- 简介：关闭连接，可选只关闭读端/写端/双向（默认双向 both）。
- 参数：
  - `conn`：连接对象
  - `how`：可选："read" / "write" / "both"，默认 "both"
- 返回：undefined
- 示例：
  - `tcpClose(conn)  // 双向关闭`
  - `tcpClose(conn, "write")  // 仅关闭写端（半关闭）`
- 常见错误：
  - tcpClose() 第二参数应为 'read'/'write'/'both'（可能原因：拼写错误）
  - tcpClose() 关闭失败（可能原因：连接已关闭）

### `tcpConnect`

- 签名：`tcpConnect(host, port [, timeoutMs]) -> conn`
- 简介：连接到 TCP 服务器，返回连接对象（默认禁用 Nagle 以降低延迟）。
- 参数：
  - `host`：主机名或 IP，如 "127.0.0.1"
  - `port`：端口号（int）
  - `timeoutMs`：可选连接超时毫秒，省略则阻塞等待直到成功或失败
- 返回：TcpConn 连接对象
- 示例：
  - `conn := tcpConnect("127.0.0.1", 8080)  // 阻塞连接`
  - `conn := tcpConnect("example.com", 443, 3000)  // 3 秒超时`
- 常见错误：
  - tcpConnect() 解析地址 'xxx' 失败（可能原因：主机名无法解析）
  - tcpConnect() 连接 'xxx' 失败（可能原因：目标未启动或防火墙拦截 / 目标不可达或超时 Nms）

### `tcpListen`

- 签名：`tcpListen(addr, handler) -> server`
- 简介：启动 TCP 服务器，每个新连接在独立线程调用 handler(conn)。
- 参数：
  - `addr`：监听地址，如 "0.0.0.0:8080" 或 ":8080"
  - `handler`：func(conn) { ... }，每个连接在独立线程中调用
- 返回：TcpServer 对象，传给 tcpStopServer 停止
- 示例：
  - `srv := tcpListen("127.0.0.1:0", func(conn) { tcpWriteLine(conn, "hi"); tcpClose(conn) })  // 启动回显式服务`
- 常见错误：
  - tcpListen() 绑定 'xxx' 失败（可能原因：地址被占用或权限不足）
  - tcpListen() 设置非阻塞模式失败（可能原因：系统不支持非阻塞 IO）

### `tcpLocalAddr`

- 签名：`tcpLocalAddr(conn) -> string`
- 简介：获取连接本端地址，返回 "ip:port" 字符串。
- 参数：
  - `conn`：连接对象
- 返回：string "ip:port"
- 示例：
  - `local := tcpLocalAddr(conn)  // 如 "127.0.0.1:8080"`
- 常见错误：
  - tcpLocalAddr() 获取本端地址失败（可能原因：连接已关闭）
  - tcpLocalAddr() 参数不是 TCP 连接

### `tcpPipe`

- 签名：`tcpPipe(conn1, conn2) -> undefined`
- 简介：双向转发两个连接的数据，阻塞直到任一方关闭（常用于代理转发）。
- 参数：
  - `conn1`：连接对象 A
  - `conn2`：连接对象 B
- 返回：undefined（任一方关闭后返回）
- 示例：
  - `tcpPipe(client, backend)  // client 与 backend 间双向透传`
- 常见错误：
  - tcpPipe() 参数不是 TCP 连接（可能原因：传入错误类型或 undefined）
  - tcpPipe() 参数应为 TCP 连接，得到 X（可能原因：参数顺序错误）

### `tcpRead`

- 签名：`tcpRead(conn, n) -> bytes|undefined`
- 简介：从连接读取最多 n 字节，连接关闭且无数据时返回 undefined。
- 参数：
  - `conn`：tcpConnect 或 tcpListen 回调中的连接对象
  - `n`：期望读取的字节数（实际可能更少）
- 返回：bytes（可能少于 n），完全无数据时为 undefined
- 示例：
  - `data := tcpRead(conn, 1024)  // 读最多 1024 字节`
- 常见错误：
  - tcpRead() 读取失败（可能原因：连接已关闭或网络中断）
  - tcpRead() 参数不是 TCP 连接（可能原因：传入错误类型或 undefined）

### `tcpReadFull`

- 签名：`tcpReadFull(conn, n) -> bytes|undefined`
- 简介：读满恰好 n 字节（不足时持续等待），适合长度前缀帧、定长协议头等场景。
- 参数：
  - `conn`：tcpConnect 或 tcpListen 回调中的连接对象
  - `n`：必须读取的字节数（int，>0）
- 返回：bytes（恰好 n 字节）；一个字节都没读到且连接关闭时为 undefined
- 示例：
  - `hdr := tcpReadFull(conn, 2)  // 读满 2 字节长度头`
  - `len := bytesToData(hdr, 2)  // 大端解读长度`
  - `body := tcpReadFull(conn, len)  // 读满整帧`
- 常见错误：
  - tcpReadFull() 已读 X/n 字节后连接关闭（可能原因：对端提前关闭、帧长度与实际数据不符或加密密码/方法不一致）
  - tcpReadFull() 读取失败（可能原因：连接已关闭或网络中断）
  - tcpReadFull() 第二参数应为正整数（可能原因：传入 0 或负数）

### `tcpReadLine`

- 签名：`tcpReadLine(conn) -> string|undefined`
- 简介：逐字节读取直到遇到 \n，返回不含换行符的一行（自动去掉尾 \r）。
- 参数：
  - `conn`：连接对象
- 返回：string（不含 \n），连接关闭且无数据时为 undefined
- 示例：
  - `line := tcpReadLine(conn)  // 读一行`
- 常见错误：
  - tcpReadLine() 读取失败（可能原因：连接已关闭或网络中断）
  - tcpReadLine() 参数不是 TCP 连接（可能原因：传入错误类型或 undefined）

### `tcpRemoteAddr`

- 签名：`tcpRemoteAddr(conn) -> string`
- 简介：获取连接对端地址，返回 "ip:port" 字符串。
- 参数：
  - `conn`：连接对象
- 返回：string "ip:port"
- 示例：
  - `remote := tcpRemoteAddr(conn)  // 如 "127.0.0.1:54321"`
- 常见错误：
  - tcpRemoteAddr() 获取对端地址失败（可能原因：连接已关闭）
  - tcpRemoteAddr() 参数不是 TCP 连接

### `tcpSetTimeout`

- 签名：`tcpSetTimeout(conn, readMs, writeMs) -> undefined`
- 简介：设置连接的读写超时，毫秒数为 0 表示无超时（阻塞）。
- 参数：
  - `conn`：连接对象
  - `readMs`：读超时毫秒，0 表示无超时
  - `writeMs`：写超时毫秒，0 表示无超时
- 返回：undefined
- 示例：
  - `tcpSetTimeout(conn, 5000, 5000)  // 读写各 5 秒超时`
- 常见错误：
  - tcpSetTimeout() 设置读超时失败
  - tcpSetTimeout() 设置写超时失败
  - tcpSetTimeout() 参数不是 TCP 连接

### `tcpStopServer`

- 签名：`tcpStopServer(server) -> undefined`
- 简介：停止 tcpListen 启动的 accept 循环（已在处理的连接会继续执行直到完成）。
- 参数：
  - `server`：tcpListen 返回的 TcpServer 对象
- 返回：undefined
- 示例：
  - `tcpStopServer(srv)  // 停止监听`
- 常见错误：
  - tcpStopServer() 参数不是 TCP 服务器（可能原因：传入错误类型，应先用 tcpListen 获取）
  - tcpStopServer() 参数为 undefined（可能原因：变量未初始化）

### `tcpWrite`

- 签名：`tcpWrite(conn, data) -> int`
- 简介：向连接写入数据（string/bytes/byteArray），返回写入字节数。
- 参数：
  - `conn`：连接对象
  - `data`：要写入的数据，可为 string / bytes / byteArray
- 返回：int 实际写入的字节数
- 示例：
  - `n := tcpWrite(conn, "hello")  // 写 5 字节`
- 常见错误：
  - tcpWrite() 写入失败（可能原因：连接已关闭或对端拒绝）
  - tcpWrite() 数据参数应为 string/bytes/byteArray（可能原因：参数类型不匹配）

### `tcpWriteLine`

- 签名：`tcpWriteLine(conn, data) -> int`
- 简介：向连接写入一行，自动在末尾追加 \n。
- 参数：
  - `conn`：连接对象
  - `data`：要写入的数据，可为 string / bytes / byteArray
- 返回：int 实际写入的字节数（含追加的 \n）
- 示例：
  - `tcpWriteLine(conn, "ping")  // 对端收到 "ping\n"`
- 常见错误：
  - tcpWriteLine() 写入失败（可能原因：连接已关闭或对端拒绝）
  - tcpWriteLine() 数据参数应为 string/bytes/byteArray（可能原因：参数类型不匹配）

## template（2 个）

### `renderMarkdown`

- 签名：`renderMarkdown(md) -> string`
- 简介：将 Markdown 转为 HTML。
- 参数：
  - `md`：Markdown 文本
- 返回：string HTML
- 示例：
  - `renderMarkdown(mdText)`

### `replaceHtmlByMap`

- 签名：`replaceHtmlByMap(tmpl, m) -> string`
- 简介：用 map 替换模板中的 {{key}} 占位符。
- 参数：
  - `tmpl`：含 {{key}} 占位符的模板
  - `m`：键值映射（object/map）
- 返回：string 替换后的字符串
- 示例：
  - `replaceHtmlByMap(tmpl, {"name": "Alice"})  // Hi Alice`

## test（3 个）

### `testByContains`

- 签名：`testByContains(actual, substr) -> bool`
- 简介：断言 actual 包含 substr。
- 参数：
  - `actual`：实际值
  - `substr`：期望包含的子串
- 返回：bool
- 示例：
  - `testByContains("hello world", "world")`

### `testByReg`

- 签名：`testByReg(actual, pattern) -> bool`
- 简介：断言 actual 匹配正则 pattern。
- 参数：
  - `actual`：实际值
  - `pattern`：正则表达式
- 返回：bool
- 示例：
  - `testByReg(str, pattern)`

### `testByText`

- 签名：`testByText(actual, expected) -> bool`
- 简介：断言两个值的文本表示相等。
- 参数：
  - `actual`：实际值
  - `expected`：期望值
- 返回：bool 是否相等
- 示例：
  - `testByText(1+1, "2")`

## tls（1 个）

### `tlsGetCertInfo`

- 签名：`tlsGetCertInfo(host [, port [, timeoutMs]]) -> object`
- 简介：连接 HTTPS 服务完成 TLS 握手，返回站点叶证书信息（含到期时间、是否已过期）。不做证书信任校验，因此已过期/自签名证书同样能取到信息。
- 参数：
  - `host`：主机名，如 "example.com"；也接受 "example.com:8443" 或完整 https:// URL（自动提取主机与端口）
  - `port`：可选端口号，默认 443
  - `timeoutMs`：可选超时毫秒（DNS/连接/握手每次 IO 分别限时），默认 10000
- 返回：object：host, port, subject, issuer, serial, notBefore, notAfter（UTC 时间字符串）, notBeforeTs, notAfterTs（Unix 秒）, daysRemaining（int，负数表示已过期天数）, expired（bool）, selfSigned（bool，主题与颁发者相同）, tlsVersion, chainCount
- 示例：
  - `info := tlsGetCertInfo("example.com")`
  - `pln(info.notAfter, " 剩余", info.daysRemaining, "天")`
  - `info := tlsGetCertInfo("https://example.com:8443", 8443, 5000)`
- 常见错误：
  - tlsGetCertInfo() 连接 'xxx:443' 失败（可能原因：域名无法解析、网络不通、服务器 443 端口未开放 TLS、防火墙拦截、公司内网代理限制、超时过短）
  - tlsGetCertInfo() TLS 握手失败（可能原因：目标端口不是 TLS 服务（误用了普通 HTTP 端口）、服务器不支持任何现代 TLS 版本、中间设备拦截 TLS、SNI 不匹配导致服务器拒绝）
  - tlsGetCertInfo() 服务器未提供证书（可能原因：端口上是普通 TCP/HTTP 服务而非 HTTPS）
  - tlsGetCertInfo() 解析证书失败（可能原因：服务器返回了非 X.509 数据、DER 编码异常）
  - tlsGetCertInfo() 参数 host 含非法字符（可能原因：传入了带路径的 URL 且格式异常、包含空格或全角字符）

## xml（3 个）

### `formatXml`

- 签名：`formatXml(s) -> string`
- 简介：格式化 XML（缩进美化）。
- 参数：
  - `s`：XML 字符串
- 返回：string 格式化后的 XML
- 示例：
  - `formatXml(rawXml)`

### `fromXml`

- 签名：`fromXml(s) -> object`
- 简介：解析 XML 字符串为对象（递归转换）。
- 参数：
  - `s`：XML 字符串
- 返回：object 对象
- 示例：
  - `var o = fromXml(xmlStr)`
- 常见错误：
  - XML 语法错误返回 error

### `xmlGetNodeStr`

- 签名：`xmlGetNodeStr(s, path) -> string|undefined`
- 简介：按路径提取 XML 节点文本。
- 参数：
  - `s`：XML 字符串
  - `path`：节点路径，如 root/child
- 返回：string 节点文本；未找到返回 undefined
- 示例：
  - `xmlGetNodeStr(xml, "root/item/name")`

## xxci（5 个）

### `xxciClient`

- 签名：`xxciClient(serverAddr, localAddr, password, encryptMethod [, verbose]) -> client`
- 简介：启动加密代理客户端，本地暴露 SOCKS5 代理，经加密通道转发到 xxciServer。
- 参数：
  - `serverAddr`：远程 xxciServer 地址，如 "your-host:8888"
  - `localAddr`：本地 SOCKS5 监听地址，如 "127.0.0.1:1080"
  - `password`：加密密码，需与服务器一致
  - `encryptMethod`：加密方法，需与服务器一致：des/txdef/txdee/txde
  - `verbose`：可选 bool，默认 false 静默；true 时输出每连接日志（对齐 goconnectit 的 -debug）
- 返回：XxciClient 对象，传给 xxciClientStop 停止
- 示例：
  - `c := xxciClient("my-server:8888", "127.0.0.1:1080", "mypassword", "txde")  // 本地 1080 提供加密代理`
- 常见错误：
  - xxciClient() 绑定 'xxx' 失败（可能原因：地址被占用或权限不足）
  - [xxciClient] 连接服务器 xxx 失败（可能原因：服务器未启动或网络不通）

### `xxciClientStop`

- 签名：`xxciClientStop(client) -> undefined`
- 简介：停止 xxciClient 启动的客户端。
- 参数：
  - `client`：xxciClient 返回的对象
- 返回：undefined
- 示例：
  - `xxciClientStop(c)  // 停止客户端`
- 常见错误：
  - xxciClientStop() 参数不是客户端对象（可能原因：传入了错误类型，应使用 xxciClient 的返回值）
  - xxciClientStop() 参数应为客户端，得到 X（可能原因：参数类型不匹配）

### `xxciServer`

- 签名：`xxciServer(addr, password, encryptMethod [, verbose]) -> server`
- 简介：启动加密代理服务器，接收加密 SOCKS5 连接（与 Go 版 goconnectit 协议兼容）。
- 参数：
  - `addr`：监听地址，如 "0.0.0.0:8888"
  - `password`：加密密码，空串时使用默认 "topxeq"
  - `encryptMethod`：加密方法："des" / "txdef" / "txdee" / "txde"
  - `verbose`：可选 bool，默认 false 静默；true 时输出每连接日志（对齐 goconnectit 的 -debug）
- 返回：XxciServer 对象，传给 xxciServerStop 停止
- 示例：
  - `s := xxciServer("0.0.0.0:8888", "mypassword", "txde")  // 启动 txde 加密的服务器`
  - `s := xxciServer("0.0.0.0:8888", "pw123456", "txde", true)  // 带连接日志`
- 常见错误：
  - xxciServer() 绑定 'xxx' 失败（可能原因：地址被占用或权限不足）
  - 不支持的加密方法（可能原因：拼写错误，支持 des/txdef/txdee/txde）
  - xxciServer() 第四参数应为 bool（可能原因：verbose 需传 true/false）

### `xxciServerStop`

- 签名：`xxciServerStop(server) -> undefined`
- 简介：停止 xxciServer 启动的服务器。
- 参数：
  - `server`：xxciServer 返回的对象
- 返回：undefined
- 示例：
  - `xxciServerStop(s)  // 停止服务器`
- 常见错误：
  - xxciServerStop() 参数不是服务器对象（可能原因：传入了错误类型，应使用 xxciServer 的返回值）
  - xxciServerStop() 参数应为服务器，得到 X（可能原因：参数类型不匹配）

### `xxciWrapConn`

- 签名：`xxciWrapConn(conn, password, encryptMethod) -> conn`
- 简介：把普通 TCP 连接包装为 xxci 加密连接（对标 goconnectit 的连接加密），包装后 tcpRead/tcpWrite/tcpPipe 自动走加密通道。
- 参数：
  - `conn`：tcpConnect 或 tcpListen 回调得到的连接对象
  - `password`：加密密码，空串时使用默认 "topxeq"
  - `encryptMethod`：加密方法："des" / "txdef" / "txdee" / "txde"
- 返回：新的加密连接对象（原连接对象不应再用于读写）
- 示例：
  - `srv := tcpListen("0.0.0.0:9000", func(c) { e := xxciWrapConn(c, "pw", "txde"); ... })  // 服务端包装`
  - `up := tcpConnect(host, port, 10000); e := xxciWrapConn(up, "pw", "txde")  // 客户端包装`
  - `tcpPipe(plainConn, encConn)  // 与普通连接一样双向转发`
- 常见错误：
  - xxciWrapConn() 参数不是 TCP 连接 (可能原因：传入错误类型或 undefined，应使用 tcpConnect/tcpListen 回调的连接)
  - xxciWrapConn() 不支持的加密方法 'xxx' (可能原因：拼写错误，支持 des/txdef/txdee/txde)
  - xxciWrapConn() 交换 DES IV 失败 (可能原因：对端不是用相同密码/方法包装的连接)

## zip（13 个）

### `compressBytes`

- 签名：`compressBytes(data, level?) -> bytes`
- 简介：用 zlib (deflate + zlib 头) 压缩数据。
- 参数：
  - `data`：要压缩的数据：bytes / byteArray / string
  - `level`：可选：压缩级别 1-9（默认 6），越高压缩率越大但越慢
- 返回：bytes：压缩后的数据（zlib 格式，含 2 字节头和 4 字节校验）
- 示例：
  - `var c = compressBytes("hello world")`
  - `var c = compressBytes(fileReadBytes("./data.bin"), 9)  // 最高压缩率`
- 常见错误：
  - data 类型必须为 bytes/byteArray/string
  - level 自动 clamp 到 1-9
  - 对应解压函数为 decompressBytes（与 gzipBytes 的 gzip 格式不同）

### `decompressBytes`

- 签名：`decompressBytes(data) -> bytes`
- 简介：解压 zlib (deflate + zlib 头) 压缩的数据。
- 参数：
  - `data`：compressBytes 返回的压缩数据：bytes / byteArray
- 返回：bytes：解压后的原始数据；失败返回 error
- 示例：
  - `var data = decompressBytes(compressBytes("hello"))  // → b"hello"`
- 常见错误：
  - 解压失败：数据不是有效的 zlib 格式（被截断 / 头损坏）
  - data 类型必须为 bytes/byteArray
  - 对应 gzip 格式请用 gunzipBytes

### `gunzipBytes`

- 签名：`gunzipBytes(data) -> bytes`
- 简介：解压 gzip 格式数据（兼容 .gz 文件内容）。
- 参数：
  - `data`：gzip 格式压缩数据：bytes / byteArray
- 返回：bytes：解压后的原始数据；失败返回 error
- 示例：
  - `var data = gunzipBytes(gzipBytes("hello"))  // → b"hello"`
  - `var data = gunzipBytes(fileReadBytes("./data.gz"))  // 读取 .gz 文件`
- 常见错误：
  - 解压失败：数据不是有效的 gzip 格式（头损坏 / 不是 gzip）
  - data 类型必须为 bytes/byteArray

### `gzipBytes`

- 签名：`gzipBytes(data, level?) -> bytes`
- 简介：用 gzip 格式压缩数据（含 gzip 文件头，兼容 .gz 文件）。
- 参数：
  - `data`：要压缩的数据：bytes / byteArray / string
  - `level`：可选：压缩级别 1-9（默认 6）
- 返回：bytes：gzip 格式压缩数据（含文件头，可写入 .gz 文件）
- 示例：
  - `var g = gzipBytes("hello world")`
  - `fileWriteBytes("./data.gz", gzipBytes(fileReadBytes("./data")))`
- 常见错误：
  - 与 compressBytes 区别：gzipBytes 含 gzip 文件头（10 字节），compressBytes 是 zlib 头（2 字节）
  - level 自动 clamp 到 1-9
  - 对应解压函数为 gunzipBytes

### `zipAddBytes`

- 签名：`zipAddBytes(zipWriter, data, entryName) -> undefined`
- 简介：将内存数据（bytes/byteArray/string）添加到 ZIP。
- 参数：
  - `zipWriter`：zipCreate 返回的写入器
  - `data`：要写入的数据：bytes / byteArray / string
  - `entryName`：zip 内的文件名（支持中文 UTF-8）
- 返回：undefined：添加成功；失败返回 error
- 示例：
  - `zipAddBytes(zw, "hello world", "hello.txt")`
  - `zipAddBytes(zw, fileReadBytes("./data.bin"), "data.bin")`
- 常见错误：
  - data 类型必须为 bytes/byteArray/string
  - zipWriter 已关闭后写入返回 error

### `zipAddDir`

- 签名：`zipAddDir(zipWriter, dirPath, basePath?) -> int`
- 简介：递归添加整个目录到 ZIP（保留相对路径结构）。
- 参数：
  - `zipWriter`：zipCreate 返回的写入器
  - `dirPath`：要添加的本地目录路径
  - `basePath`：可选：目录在 zip 内的根路径前缀（如 "" 或 "subdir/"，默认空）
- 返回：int：实际添加的文件数（不含目录条目）
- 示例：
  - `var n = zipAddDir(zw, "./project", "")           // zip 内保留 project 下的相对路径`
  - `var n = zipAddDir(zw, "C:\\www", "web/")         // zip 内路径加 web/ 前缀`
- 常见错误：
  - 目录不存在返回 error
  - zipWriter 已关闭后写入返回 error
  - 目录条目用 Stored（不压缩），文件用 Deflated

### `zipAddFile`

- 签名：`zipAddFile(zipWriter, srcPath, entryName) -> undefined`
- 简介：将本地文件添加到 ZIP（entryName 为 zip 内路径，支持中文）。
- 参数：
  - `zipWriter`：zipCreate 返回的写入器
  - `srcPath`：本地源文件路径
  - `entryName`：zip 内的文件名（路径，支持中文 UTF-8）
- 返回：undefined：添加成功；失败返回 error
- 示例：
  - `zipAddFile(zw, "./report.pdf", "reports/report.pdf")`
  - `zipAddFile(zw, "./配置.txt", "配置.txt")  // 中文文件名`
- 常见错误：
  - 打开源文件失败：路径不存在 / 权限不足
  - zipWriter 已关闭（zipClose 后不能再写）
  - 使用 Deflated 压缩方法

### `zipClose`

- 签名：`zipClose(zipWriter) -> bool`
- 简介：完成 ZIP 并写入磁盘（必须调用，否则不会生成文件）。
- 参数：
  - `zipWriter`：zipCreate 返回的写入器
- 返回：bool：true 写入成功；失败返回 error
- 示例：
  - `var zw = zipCreate("./out.zip")`
  - `zipAddFile(zw, "./a.txt", "a.txt")`
  - `zipClose(zw)  // 此时才真正写入 out.zip`
- 常见错误：
  - 重复 close 返回 error（已关闭）
  - 写入磁盘失败：路径不可写 / 磁盘满
  - 未调用 close 的写入器其内容会丢失（GC 时丢弃）

### `zipCreate`

- 签名：`zipCreate(zipPath) -> zipWriter`
- 简介：创建 ZIP 文件写入器（后续用 zipAddFile/zipAddBytes/zipAddDir 添加内容，最后 zipClose 落盘）。
- 参数：
  - `zipPath`：要生成的 ZIP 文件路径
- 返回：zipWriter 写入器对象（传入后续 zip* 函数）
- 示例：
  - `var zw = zipCreate("./out.zip")`
  - `zipAddFile(zw, "./a.txt", "a.txt")`
  - `zipAddBytes(zw, "hello", "b.txt")`
  - `zipClose(zw)  // 落盘`
- 常见错误：
  - zipPath 必须为 string
  - 实际写入在 zipClose 时发生；未 close 不会生成文件

### `zipExtract`

- 签名：`zipExtract(zipPath, destDir) -> int`
- 简介：解压整个 ZIP 到指定目录（自动创建目录，含 zip slip 安全防护）。
- 参数：
  - `zipPath`：ZIP 文件路径
  - `destDir`：目标目录（不存在则自动创建）
- 返回：int：解压出的文件数（不含目录条目）
- 示例：
  - `var n = zipExtract("./out.zip", "./unzipped")  // → 3`
- 常见错误：
  - zip slip 安全检查：条目含 .. 或绝对路径时拒绝解压（防路径穿越攻击）
  - 打开 / 读取 zip 失败；创建目录 / 文件失败
  - 中文文件名自动 UTF-8/GBK 解码

### `zipExtractFile`

- 签名：`zipExtractFile(zipPath, entryName, destPath) -> bool`
- 简介：解压 ZIP 中的单个文件到指定路径。
- 参数：
  - `zipPath`：ZIP 文件路径
  - `entryName`：zip 内的条目名（支持中文，需精确匹配）
  - `destPath`：本地目标文件路径
- 返回：bool：true 解压成功；未找到条目或失败返回 error
- 示例：
  - `zipExtractFile("./out.zip", "reports/report.pdf", "./restored.pdf")  // → true`
- 常见错误：
  - 未找到条目：文件名不匹配或编码不一致（中文需 UTF-8）
  - 打开 / 创建文件失败
  - 与 zipExtract 区别：本函数只解压指定单个条目

### `zipList`

- 签名：`zipList(zipPath) -> array<object>`
- 简介：列出 ZIP 文件中所有条目（文件名自动解码 UTF-8/GBK）。
- 参数：
  - `zipPath`：ZIP 文件路径
- 返回：array<object>：每个元素 {name:string, size:int, compressedSize:int, isDir:bool}
- 示例：
  - `var entries = zipList("./out.zip")  // → [{"name":"a.txt","size":100,"compressedSize":45,"isDir":false}]`
  - `for (var e in zipList("./out.zip")) { println(e["name"], e["size"]) }`
- 常见错误：
  - 打开文件失败：路径不存在 / 权限不足
  - 读取 zip 失败：不是有效的 zip 文件
  - 中文文件名优先 UTF-8 解码，失败回退 GBK（兼容 Windows 旧工具）

### `zipReadFile`

- 签名：`zipReadFile(zipPath, entryName) -> bytes`
- 简介：读取 ZIP 中单个文件的内容到内存 bytes（不解压到磁盘）。
- 参数：
  - `zipPath`：ZIP 文件路径
  - `entryName`：zip 内的条目名（支持中文）
- 返回：bytes：条目解压后的原始内容；未找到或失败返回 error
- 示例：
  - `var data = zipReadFile("./out.zip", "a.txt")`
  - `println(toStr(data))  // 文本文件可转字符串查看`
- 常见错误：
  - 未找到条目：文件名不匹配或编码不一致
  - 打开 zip / 读取条目失败
  - 适合不需要落盘的小文件读取