ms-types 0.9.42 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-types",
-  "version": "0.9.42",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -18,6 +18,6 @@
   "devDependencies": {
     "vitepress": "^1.6.4",
     "vitepress-theme-teek": "^1.6.2",
-    "wrangler": "^4.128.0"
+    "wrangler": "^4.129.0"
   }
 }

package/types/ai.d.ts

@@ -0,0 +1,172 @@
+/**
+ * AI 模块 让脚本直接在手机上调用大模型：看图回答、是非判断、提取结构化数据、多轮对话。
+ * 支持 openai 兼容 / anthropic / gemini 三种协议；模型配置写在脚本里，脚本开头 ai.setProvider 一次即可。
+ * 所有方法同步阻塞，失败返回 null / false，原因用 ai.lastError() 查看。
+ */
+declare namespace ai {
+  /**
+   * 模型供应商配置
+   */
+  interface AiProvider {
+    /** 供应商 id，不传时自动生成 */
+    id: string;
+    /** 展示名，例如 "DeepSeek"，调用时可用它选模型 */
+    name: string;
+    /** 接口协议 */
+    protocol: "openai" | "anthropic" | "gemini";
+    /** 接口根地址，例如 https://api.openai.com/v1 */
+    baseUrl: string;
+    /** API Key；openai 协议连本机模型时可为空 */
+    apiKey: string;
+    /** 默认模型名 */
+    model: string;
+    /** 额外请求头，某些网关需要 */
+    headers: Record<string, string>;
+    /** 默认温度；不传则不发该字段，用模型自己的默认值 */
+    temperature?: number;
+    /** 默认最大输出 token；不传则不发该字段，用模型自己的默认值（Anthropic 因接口必填仍默认 2048） */
+    maxTokens?: number;
+    /** 是否支持图片输入，默认 true；为 false 时带图调用直接报错 */
+    supportsVision: boolean;
+    /** 是否为默认供应商 */
+    isDefault: boolean;
+  }
+
+  /**
+   * ask / judge / extract / chat 的可选参数
+   */
+  interface AiOptions {
+    /** 用哪个供应商：id 或 name；不传用默认 */
+    provider?: string;
+    /** 临时换模型，覆盖供应商默认模型 */
+    model?: string;
+    /** 覆盖默认温度 */
+    temperature?: number;
+    /** 覆盖默认最大输出 token */
+    maxTokens?: number;
+    /** 超时毫秒，默认 90000 */
+    timeout?: number;
+    /** 要求模型输出 JSON（extract 自动开启） */
+    json?: boolean;
+    /** 系统提示（chat 不用这个，写在 messages 里） */
+    system?: string;
+    /** imageId，与 image 模块所有函数的 imageId 参数一致：图片 ID / "screen" / 图片路径 */
+    image?: string;
+    /** 对 image 裁剪，同 image.clip：左上角 X；全 0 不裁剪。只写区域不写 image 时按 "screen" */
+    x?: number;
+    /** 裁剪区域左上角 Y */
+    y?: number;
+    /** 裁剪区域右下角 X */
+    ex?: number;
+    /** 裁剪区域右下角 Y */
+    ey?: number;
+    /** 多张图，元素同 image，不裁剪 */
+    images?: string[];
+    /** 仅 extract：期望的 JSON 结构说明，字符串或对象 */
+    schema?: string | object;
+  }
+
+  /**
+   * chat 的消息项，图片参数与 AiOptions 相同
+   */
+  interface AiMessage {
+    /** 角色 */
+    role: "system" | "user" | "assistant";
+    /** 文本内容 */
+    content: string;
+    /** imageId，同 AiOptions.image */
+    image?: string;
+    /** 裁剪区域，同 AiOptions */
+    x?: number;
+    y?: number;
+    ex?: number;
+    ey?: number;
+    /** 多张图，同 AiOptions.images */
+    images?: string[];
+  }
+
+  /**
+   * 登记或更新模型供应商（脚本开头调用一次；只存内存，脚本停止即清空）
+   * 可登记多个：便宜的文本模型做默认，视觉模型单独一个，调用时用 options.provider 选
+   * @param config 新建至少要有 baseUrl、model（protocol 缺省 openai）；同 id 再次调用为更新，没传的字段沿用旧值
+   * @returns 保存后的完整配置；protocol 不合法或缺 baseUrl / model 时返回 null
+   * @example
+   * ai.setProvider({ name: "DeepSeek", protocol: "openai", baseUrl: "https://api.deepseek.com", apiKey: "sk-...", model: "deepseek-v4-flash" })
+   */
+  function setProvider(config: Partial<AiProvider>): AiProvider | null;
+  /**
+   * 列出已登记的供应商，默认项排在最前
+   * @example ai.getProviders().forEach(p => logi(p.name))
+   */
+  function getProviders(): AiProvider[];
+  /**
+   * 获取默认供应商
+   * @returns 一个都没登记时返回 null
+   * @example const p = ai.getDefaultProvider()
+   */
+  function getDefaultProvider(): AiProvider | null;
+  /**
+   * 切换默认供应商
+   * @param id 供应商 id 或 name
+   * @returns id 或 name 存在返回 true
+   * @example ai.setDefaultProvider("cheap")
+   */
+  function setDefaultProvider(id: string): boolean;
+  /**
+   * 删除供应商；删掉的是默认项时默认转给剩下的第一个
+   * @param id 供应商 id 或 name
+   * @returns 存在并删除返回 true
+   * @example ai.removeProvider("cheap")
+   */
+  function removeProvider(id: string): boolean;
+  /**
+   * 单轮提问，可附带图片
+   * @param prompt 问题
+   * @param options 可选参数，图片参数与 image 模块一致：image 为 imageId，x/y/ex/ey 同 image.clip 裁剪
+   * @returns 回复文本；失败返回 null
+   * @example
+   * ai.ask("屏幕上有几个按钮？", { image: "screen" })
+   * ai.ask("这个区域的价格是多少？", { image: "screen", x: 0, y: 300, ex: 750, ey: 500 })
+   */
+  function ask(prompt: string, options?: AiOptions): string | null;
+  /**
+   * 是非判断：让模型只回答 yes / no
+   * @param question 要判断的问题
+   * @param options 同 ask
+   * @returns 肯定为 true；否定或请求失败为 false（失败时 lastError() 有内容）
+   * @example if (ai.judge("是否出现了「领取成功」？", { image: "screen" })) { ... }
+   */
+  function judge(question: string, options?: AiOptions): boolean;
+  /**
+   * 结构化提取：要求模型输出 JSON 并解析成对象或数组
+   * @param prompt 提取要求
+   * @param options 同 ask，另支持 schema
+   * @returns 解析后的对象或数组；没有合法 JSON 或请求失败返回 null
+   * @example
+   * const d = ai.extract("提取验证码", { image: "screen", x: 100, y: 800, ex: 600, ey: 900, schema: { code: "string" } })
+   * if (d) logi(d.code)
+   */
+  function extract(prompt: string, options?: AiOptions): any | null;
+  /**
+   * 多轮对话：自己维护完整消息数组，每次整表传入。失败返回 null，不要把空回复推进历史。
+   * @param messages 消息数组；直接写字符串等于 user 消息；图片写在该条消息上
+   * @param options provider / model / temperature / maxTokens / json / timeout（不用 system / image）
+   * @returns 回复文本；失败返回 null
+   * @example
+   * ai.chat([{ role: "system", content: "你是助手" }, { role: "user", content: "看下这是哪个页面", image: "screen" }])
+   */
+  function chat(messages: (AiMessage | string)[], options?: AiOptions): string | null;
+  /**
+   * 从模型文本里解析 JSON，自动剥掉 Markdown 代码块和前后解释
+   * @param text 模型输出
+   * @returns 解析结果；失败返回 null
+   * @example ai.parseJson("```json\n{\"a\":1}\n```")
+   */
+  function parseJson(text: string): any | null;
+  /**
+   * 最近一次调用失败的原因
+   * @returns 错误文案；上一次调用成功时返回 null
+   * @example if (ai.ask("你好") === null) loge(ai.lastError())
+   */
+  function lastError(): string | null;
+}

package/types/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference path="action.d.ts" />
+/// <reference path="ai.d.ts" />
 /// <reference path="appleocr.d.ts" />
 /// <reference path="cloud.d.ts" />
 /// <reference path="config.d.ts" />

package/types/lua/ai.lua

@@ -0,0 +1,102 @@
+---@meta
+---@class Ai
+local _Ai = {}
+
+---@class AiProvider
+---@field id string 供应商 id，不传时自动生成
+---@field name string 展示名，例如 "DeepSeek"，调用时可用它选模型
+---@field protocol "openai"|"anthropic"|"gemini" 接口协议
+---@field baseUrl string 接口根地址，例如 https://api.openai.com/v1
+---@field apiKey string API Key；openai 协议连本机模型时可为空
+---@field model string 默认模型名
+---@field headers table<string, string> 额外请求头，某些网关需要
+---@field temperature number|nil 默认温度；不传则不发该字段，用模型自己的默认值
+---@field maxTokens integer|nil 默认最大输出 token；不传则不发该字段，用模型自己的默认值（Anthropic 因接口必填仍默认 2048）
+---@field supportsVision boolean 是否支持图片输入，默认 true
+---@field isDefault boolean 是否为默认供应商
+
+---@class AiOptions
+---@field provider string|nil 用哪个供应商：id 或 name；不传用默认
+---@field model string|nil 临时换模型，覆盖供应商默认模型
+---@field temperature number|nil 覆盖默认温度
+---@field maxTokens integer|nil 覆盖默认最大输出 token
+---@field timeout integer|nil 超时毫秒，默认 90000
+---@field json boolean|nil 要求模型输出 JSON（extract 自动开启）
+---@field system string|nil 系统提示（chat 不用这个，写在 messages 里）
+---@field image string|nil imageId，与 image 模块所有函数的 imageId 参数一致：图片 ID / "screen" / 图片路径
+---@field x integer|nil 对 image 裁剪，同 image.clip：左上角 X；全 0 不裁剪。只写区域不写 image 时按 "screen"
+---@field y integer|nil 裁剪区域左上角 Y
+---@field ex integer|nil 裁剪区域右下角 X
+---@field ey integer|nil 裁剪区域右下角 Y
+---@field images string[]|nil 多张图，元素同 image，不裁剪
+---@field schema string|table|nil 仅 extract：期望的 JSON 结构说明
+
+---@class AiMessage 图片参数与 AiOptions 相同
+---@field role "system"|"user"|"assistant"
+---@field content string
+---@field image string|nil
+---@field x integer|nil
+---@field y integer|nil
+---@field ex integer|nil
+---@field ey integer|nil
+---@field images string[]|nil
+
+--- 登记或更新模型供应商（脚本开头调用一次；只存内存，脚本停止即清空）
+--- 至少要有 baseUrl、model（protocol 缺省 openai）；同 id 再次调用为更新，没传的字段沿用旧值
+---@param config table
+---@return AiProvider|nil 保存后的完整配置；参数不合法返回 nil
+function _Ai.setProvider(config) return nil end
+
+--- 列出已登记的供应商，默认项排在最前
+---@return AiProvider[]
+function _Ai.getProviders() return {} end
+
+--- 获取默认供应商；一个都没登记时返回 nil
+---@return AiProvider|nil
+function _Ai.getDefaultProvider() return nil end
+
+--- 切换默认供应商
+---@param id string 供应商 id 或 name
+---@return boolean id 或 name 存在返回 true
+function _Ai.setDefaultProvider(id) return true end
+
+--- 删除供应商；删掉的是默认项时默认转给剩下的第一个
+---@param id string 供应商 id 或 name
+---@return boolean 存在并删除返回 true
+function _Ai.removeProvider(id) return true end
+
+--- 单轮提问，可附带图片；图片参数与 image 模块一致（image + x/y/ex/ey，或 images）
+---@param prompt string
+---@param options AiOptions|nil
+---@return string|nil 回复文本；失败返回 nil，原因看 lastError()
+function _Ai.ask(prompt, options) return nil end
+
+--- 是非判断：让模型只回答 yes / no
+---@param question string
+---@param options AiOptions|nil
+---@return boolean 肯定为 true；否定或请求失败为 false（失败时 lastError() 有内容）
+function _Ai.judge(question, options) return false end
+
+--- 结构化提取：要求模型输出 JSON 并解析成表
+---@param prompt string
+---@param options AiOptions|nil 另支持 schema
+---@return table|nil 解析后的表；没有合法 JSON 或请求失败返回 nil
+function _Ai.extract(prompt, options) return nil end
+
+--- 多轮对话：自己维护完整消息数组，每次整表传入。失败返回 nil，不要把空回复推进历史。
+---@param messages (AiMessage|string)[] 直接写字符串等于 user 消息；图片写在该条消息上
+---@param options AiOptions|nil provider / model / temperature / maxTokens / json / timeout（不用 system / image）
+---@return string|nil 回复文本；失败返回 nil
+function _Ai.chat(messages, options) return nil end
+
+--- 从模型文本里解析 JSON，自动剥掉 Markdown 代码块和前后解释
+---@param text string
+---@return table|nil
+function _Ai.parseJson(text) return nil end
+
+--- 最近一次调用失败的原因；上一次调用成功时返回 nil
+---@return string|nil
+function _Ai.lastError() return nil end
+
+---@type Ai
+ai = _Ai

package/types/lua/cv.lua

@@ -741,12 +741,15 @@ function _OpenCV.imread(path) return nil end
 function _OpenCV.imdecode(data) return nil end
 
 --- imwrite
+--- 格式由扩展名决定，可用 png/apng/jpg/jpeg/jpe/bmp/dib/webp/ppm/pgm/pbm/pnm/pam/sr/ras；
+--- 其它扩展名或通道数不是 1/3/4 的 Mat 返回 false。
 ---@param path string
 ---@param mat OpenCV.Mat
 ---@return boolean
 function _OpenCV.imwrite(path, mat) return false end
 
 --- imencode
+--- 扩展名与通道限制同 imwrite；quality 取值 1-100，仅 jpg 有效。
 ---@param ext string
 ---@param mat OpenCV.Mat
 ---@param quality number|nil

package/types/opencv.d.ts

@@ -256,7 +256,14 @@ declare namespace cv {
   function imread(path: string): Mat | null;
   /** 仅解码 base64 / data URI；路径与 imageId 请用 `imread` */
   function imdecode(data: string): Mat | null;
+  /**
+   * 保存 Mat 到本地文件，格式由扩展名决定。
+   * 可用 `png` / `apng` / `jpg` / `jpeg` / `jpe` / `bmp` / `dib` / `webp` /
+   * `ppm` / `pgm` / `pbm` / `pnm` / `pam` / `sr` / `ras`；
+   * 其它扩展名或通道数不是 1 / 3 / 4 的 Mat 返回 `false`。
+   */
   function imwrite(path: string, mat: Mat): boolean;
+  /** 编码为纯 base64；扩展名与通道限制同 `imwrite`，`quality` 取值 1–100（仅 jpg 有效） */
   function imencode(ext: string, mat: Mat, quality?: number): string | null;
   function fromImageId(imageId: string): Mat | null;
   function toImageId(mat: Mat): string | null;

package/types/zh/AI/346/250/241/345/235/227.d.ts

@@ -0,0 +1,172 @@
+/// <reference path="全局模块.d.ts" />
+
+/**
+ * AI 模块 让脚本直接在手机上调用大模型：看图回答、是非判断、提取结构化数据、多轮对话。
+ * 支持 openai 兼容 / anthropic / gemini 三种协议；模型配置写在脚本里，脚本开头 $AI.设置模型 一次即可。
+ * 所有方法同步阻塞，失败返回 null / false，原因用 $AI.获取错误() 查看。
+ */
+declare namespace $AI {
+  /**
+   * 模型供应商配置
+   */
+  interface 模型供应商 {
+    /** 供应商 id，不传时自动生成 */
+    id: 字符串;
+    /** 展示名，例如 "DeepSeek"，调用时可用它选模型 */
+    name: 字符串;
+    /** 接口协议 */
+    protocol: "openai" | "anthropic" | "gemini";
+    /** 接口根地址，例如 https://api.openai.com/v1 */
+    baseUrl: 字符串;
+    /** API Key；openai 协议连本机模型时可为空 */
+    apiKey: 字符串;
+    /** 默认模型名 */
+    model: 字符串;
+    /** 额外请求头，某些网关需要 */
+    headers: 字典<字符串>;
+    /** 默认温度；不传则不发该字段，用模型自己的默认值 */
+    temperature?: 数字;
+    /** 默认最大输出 token；不传则不发该字段，用模型自己的默认值（Anthropic 因接口必填仍默认 2048） */
+    maxTokens?: 数字;
+    /** 是否支持图片输入，默认 true */
+    supportsVision: 布尔值;
+    /** 是否为默认供应商 */
+    isDefault: 布尔值;
+  }
+
+  /**
+   * 提问 / 判断 / 提取 / 对话 的可选参数
+   */
+  interface 调用选项 {
+    /** 用哪个供应商：id 或 name；不传用默认 */
+    provider?: 字符串;
+    /** 临时换模型 */
+    model?: 字符串;
+    /** 覆盖默认温度 */
+    temperature?: 数字;
+    /** 覆盖默认最大输出 token */
+    maxTokens?: 数字;
+    /** 超时毫秒，默认 90000 */
+    timeout?: 数字;
+    /** 要求模型输出 JSON（提取 自动开启） */
+    json?: 布尔值;
+    /** 系统提示 */
+    system?: 字符串;
+    /** imageId，与图片模块所有函数的 imageId 参数一致：图片 ID / "screen" / 图片路径 */
+    image?: 字符串;
+    /** 对 image 裁剪，同 $图片.裁剪图片：左上角 X；全 0 不裁剪。只写区域不写 image 时按 "screen" */
+    x?: 数字;
+    /** 裁剪区域左上角 Y */
+    y?: 数字;
+    /** 裁剪区域右下角 X */
+    ex?: 数字;
+    /** 裁剪区域右下角 Y */
+    ey?: 数字;
+    /** 多张图，元素同 image，不裁剪 */
+    images?: 数组<字符串>;
+    /** 仅 提取：期望的 JSON 结构说明 */
+    schema?: 字符串 | object;
+  }
+
+  /**
+   * 对话 的消息项，图片参数与 调用选项 相同
+   */
+  interface 对话消息 {
+    /** 角色 */
+    role: "system" | "user" | "assistant";
+    /** 文本内容 */
+    content: 字符串;
+    /** imageId，同 调用选项.image */
+    image?: 字符串;
+    /** 裁剪区域，同 调用选项 */
+    x?: 数字;
+    y?: 数字;
+    ex?: 数字;
+    ey?: 数字;
+    /** 多张图，同 调用选项.images */
+    images?: 数组<字符串>;
+  }
+
+  /**
+   * 登记或更新模型供应商（脚本开头调用一次；只存内存，脚本停止即清空）
+   * @param 配置 新建至少要有 baseUrl、model（protocol 缺省 openai）；同 id 再次调用为更新
+   * @returns 保存后的完整配置；参数不合法返回 null
+   * @example
+   * $AI.设置模型({ name: "DeepSeek", protocol: "openai", baseUrl: "https://api.deepseek.com", apiKey: "sk-...", model: "deepseek-v4-flash" })
+   */
+  function 设置模型(配置: Partial<模型供应商>): 模型供应商 | null;
+  /**
+   * 列出已登记的供应商，默认项排在最前
+   * @example $AI.获取模型列表()
+   */
+  function 获取模型列表(): 数组<模型供应商>;
+  /**
+   * 获取默认供应商
+   * @returns 一个都没登记时返回 null
+   * @example $AI.获取默认模型()
+   */
+  function 获取默认模型(): 模型供应商 | null;
+  /**
+   * 切换默认供应商
+   * @param id 供应商 id 或 name
+   * @returns id 或 name 存在返回 true
+   * @example $AI.设置默认模型("cheap")
+   */
+  function 设置默认模型(id: 字符串): 布尔值;
+  /**
+   * 删除供应商
+   * @param id 供应商 id 或 name
+   * @returns 存在并删除返回 true
+   * @example $AI.删除模型("cheap")
+   */
+  function 删除模型(id: 字符串): 布尔值;
+  /**
+   * 单轮提问，可附带图片
+   * @param 问题 问题
+   * @param 选项 可选参数，图片参数与图片模块一致：image 为 imageId，x/y/ex/ey 同 $图片.裁剪图片
+   * @returns 回复文本；失败返回 null
+   * @example
+   * $AI.提问("屏幕上有几个按钮？", { image: "screen" })
+   * $AI.提问("这个区域的价格是多少？", { image: "screen", x: 0, y: 300, ex: 750, ey: 500 })
+   */
+  function 提问(问题: 字符串, 选项?: 调用选项): 字符串 | null;
+  /**
+   * 是非判断：让模型只回答 yes / no
+   * @param 问题 要判断的问题
+   * @param 选项 同 提问
+   * @returns 肯定为 true；否定或请求失败为 false
+   * @example if ($AI.判断("是否出现了「领取成功」？", { image: "screen" })) { ... }
+   */
+  function 判断(问题: 字符串, 选项?: 调用选项): 布尔值;
+  /**
+   * 结构化提取：要求模型输出 JSON 并解析成对象或数组
+   * @param 要求 提取要求
+   * @param 选项 同 提问，另支持 schema
+   * @returns 解析后的对象或数组；失败返回 null
+   * @example
+   * const d = $AI.提取("提取验证码", { image: "screen", x: 100, y: 800, ex: 600, ey: 900, schema: { code: "string" } })
+   */
+  function 提取(要求: 字符串, 选项?: 调用选项): 任意类型 | null;
+  /**
+   * 多轮对话：自己维护完整消息数组，每次整表传入。失败返回 null，不要把空回复推进历史。
+   * @param 消息列表 消息数组；直接写字符串等于 user 消息；图片写在该条消息上
+   * @param 选项 provider / model / temperature / maxTokens / json / timeout（不用 system / image）
+   * @returns 回复文本；失败返回 null
+   * @example
+   * $AI.对话([{ role: "system", content: "你是助手" }, { role: "user", content: "看下这是哪个页面", image: "screen" }])
+   */
+  function 对话(消息列表: 数组<对话消息 | 字符串>, 选项?: 调用选项): 字符串 | null;
+  /**
+   * 从模型文本里解析 JSON，自动剥掉 Markdown 代码块和前后解释
+   * @param 文本 模型输出
+   * @returns 解析结果；失败返回 null
+   * @example $AI.解析JSON("```json\n{\"a\":1}\n```")
+   */
+  function 解析JSON(文本: 字符串): 任意类型 | null;
+  /**
+   * 最近一次调用失败的原因
+   * @returns 错误文案；上一次调用成功时返回 null
+   * @example if ($AI.提问("你好") === null) $打印错误日志($AI.获取错误())
+   */
+  function 获取错误(): 字符串 | null;
+}

package/types/zh/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference path="动作模块.d.ts" />
+/// <reference path="AI模块.d.ts" />
 /// <reference path="工具模块.d.ts" />
 /// <reference path="节点模块.d.ts" />
 /// <reference path="卡密模块.d.ts" />