ms-vite-plugin 1.4.74 → 1.4.76

package/docs/apilua/ai.md

@@ -0,0 +1,495 @@
+# AI 模块 (AI)
+
+模块表是内置全局 `ai`，直接调用即可。不要 `require` 宿主模块。
+
+AI 模块让脚本直接在手机上调用大模型：看图回答问题、做是非判断、从屏幕提取结构化数据、多轮对话。
+
+支持三种接口协议，覆盖绝大多数模型服务：
+
+| `protocol`  | 适用服务                                                                              |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `openai`    | DeepSeek、通义千问、Kimi、智谱、SiliconFlow、本机 Ollama / vLLM 等                     |
+| `anthropic` | 国内一般走 openai 兼容口，不必单独配                                                  |
+| `gemini`    | 国内一般走 openai 兼容口，不必单独配                                                  |
+
+模型配置（地址、Key、模型名）直接写在脚本里，脚本开头 `ai.setProvider` 一次即可；脚本停止后配置自动清空，不会存到手机上。
+
+所有方法同步阻塞，失败时返回 `nil` / `false`，原因用 `ai.lastError()` 查看。
+
+## 快速开始
+
+```lua
+-- 1. 脚本开头登记模型（只需一次）。通义千问 Qwen3.5 起原生多模态，看图、问字都能用。
+ai.setProvider({
+  name = "通义千问",
+  protocol = "openai",
+  baseUrl = "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  apiKey = "sk-xxxxxxxx",
+  model = "qwen3.5-flash",
+})
+
+-- 2. 直接问
+print(ai.ask("用一句话介绍你自己"))
+
+-- 3. 看着屏幕判断
+if ai.judge("当前是否已经登录成功？", { image = "screen" }) then
+  print("已登录")
+end
+
+-- 4. 从屏幕某个区域提取数据
+local data = ai.extract("提取验证码", {
+  image = "screen", x = 100, y = 800, ex = 600, ey = 900,
+  schema = { code = "string" },
+})
+if data then print(data.code) end
+```
+
+## 图片参数
+
+图片参数和 image 模块**完全一样**，没有单独的截图开关：
+
+| 参数                 | 含义                                                                                                                              |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `image`              | `imageId`，与所有 `image.*` 函数的 `imageId` 参数一样：`image.captureScreen()` 等返回的图片 ID、`"screen"`（当前屏幕）、res 目录或手机绝对路径的图片文件 |
+| `x`, `y`, `ex`, `ey` | 对 `image` 裁剪，同 `image.clip(imageId, x, y, ex, ey)`：左上角 / 右下角坐标，全 0 不裁剪。只写区域不写 `image` 时按 `"screen"`     |
+| `images`             | 多张图的数组，元素同 `image`，不裁剪                                                                                              |
+
+```lua
+-- 当前全屏
+ai.ask("屏幕上有几个按钮？", { image = "screen" })
+
+-- 屏幕区域：左上 (0, 200) 到右下 (750, 600)
+ai.ask("这一块显示的价格是多少？", { image = "screen", x = 0, y = 200, ex = 750, ey = 600 })
+
+-- 已有的图片 ID
+local id = image.captureScreen()
+ai.ask("描述这张图", { image = id, x = 0, y = 0, ex = 750, ey = 400 })
+image.release(id)
+
+-- 图片文件
+ai.ask("这张图里是什么", { image = "sample.png" })
+
+-- 一次传多张：模板图 + 当前屏幕
+ai.judge("第二张图里有没有第一张图的图标？", { images = { "icon.png", "screen" } })
+```
+
+## 费用说明
+
+模型按 token 计费，其中图片是大头：一张 iPhone 全屏截图约 1400 ~ 1500 token，文字提问通常只有几十个。
+
+- **能裁区域就不发全屏。** 只发需要看的那一块，token 通常能少 5 ~ 10 倍。
+- **循环里保持提示词不变。** 三家服务都有「前缀缓存」：连续请求里开头相同的部分按约 1/10 计费。AI 模块已经把 `system` 排最前、文字排在图片之前，循环里每次只有图片变，`system` 和问题文字都能命中缓存。不要往 `system` 或问题里拼时间、序号这类每次都变的内容。
+- **不同场景用不同模型。** 便宜的文本模型做默认，视觉模型只在需要看图时用（见 [setProvider](#setprovider---登记或更新模型供应商)）。
+
+## 数据类型
+
+### AiProvider
+
+```lua
+---@class AiProvider
+---@field id string 供应商 id，不传时自动生成
+---@field name string 展示名，例如 "DeepSeek"，调用时可用它选模型
+---@field protocol "openai"|"anthropic"|"gemini"
+---@field baseUrl string 接口根地址，例如 https://api.deepseek.com
+---@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 reasoningEffort "none"|"low"|"medium"|"high"|"xhigh"|nil 思考级别，仅 openai 协议；不传不发，用服务商默认
+---@field supportsVision boolean 是否支持图片输入，默认 true
+---@field isDefault boolean 是否为默认供应商
+```
+
+### AiOptions
+
+`ask` / `judge` / `extract` / `chat` 的第二个参数，所有字段可选：
+
+```lua
+---@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 模块：图片 ID / "screen" / 图片路径
+---@field x integer|nil 裁剪区域左上角 X，同 image.clip
+---@field y integer|nil 裁剪区域左上角 Y
+---@field ex integer|nil 裁剪区域右下角 X，全 0 不裁剪
+---@field ey integer|nil 裁剪区域右下角 Y
+---@field images string[]|nil 多张图，元素同 image，不裁剪
+---@field schema string|table|nil 仅 extract：期望的 JSON 结构说明
+```
+
+### AiMessage
+
+`chat` 的消息项，图片参数与 `AiOptions` 相同：
+
+```lua
+---@class AiMessage
+---@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
+```
+
+## API 参考
+
+### setProvider - 登记或更新模型供应商。
+
+```lua
+---@param config table
+---@return AiProvider|nil
+function setProvider(config) end
+```
+
+**参数：**
+
+| 参数名   | 类型    | 是否必填 | 默认值 | 描述                                                                                |
+| -------- | ------- | -------- | ------ | ----------------------------------------------------------------------------------- |
+| `config` | `table` | 是       | -      | 新建至少要有 `baseUrl`、`model`（`protocol` 缺省 openai）；同 `id` 更新时没传的字段沿用旧值 |
+
+**返回值：**
+
+| 类型         | 描述                                                                           |
+| ------------ | ------------------------------------------------------------------------------ |
+| `AiProvider` | 保存后的完整配置；`protocol` 不是三者之一或缺 `baseUrl` / `model` 时返回 `nil` |
+
+第一个登记的供应商自动成为默认；`isDefault = true` 会把默认切到它。
+
+**示例：**
+
+```lua
+-- 只用一个模型（通义能看图）
+ai.setProvider({
+  name = "通义千问", protocol = "openai",
+  baseUrl = "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  apiKey = "sk-xxxxxxxx", model = "qwen3.5-flash",
+})
+
+-- 多个模型省钱：便宜的文本模型做默认，视觉模型单独一个，用到时按 name 选
+ai.setProvider({
+  name = "文本", protocol = "openai", baseUrl = "https://api.deepseek.com",
+  apiKey = "sk-xxxxxxxx", model = "deepseek-v4-flash", supportsVision = false, isDefault = true,
+})
+ai.setProvider({
+  name = "视觉", protocol = "openai", baseUrl = "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  apiKey = "sk-xxxxxxxx", model = "qwen3.5-flash",
+})
+ai.ask("把这段话翻译成英文：你好")                                    -- 走默认的「文本」
+ai.judge("是否出现弹窗？", { image = "screen", provider = "视觉" })  -- 看图时才用视觉模型
+
+-- 同一供应商只换模型，不必再登记
+ai.ask("复杂推理题……", { model = "deepseek-v4-pro" })
+
+-- 智谱 GLM（OpenAI 兼容口）
+ai.setProvider({
+  name = "智谱 GLM", protocol = "openai", baseUrl = "https://open.bigmodel.cn/api/paas/v4",
+  apiKey = "sk-xxxxxxxx", model = "glm-5.3-flash",
+})
+
+-- 本机 Ollama，不需要 Key
+ai.setProvider({ name = "本机", protocol = "openai", baseUrl = "http://192.168.1.10:11434/v1", model = "qwen3:8b" })
+```
+
+### getProviders - 列出已登记的供应商。
+
+```lua
+---@return AiProvider[]
+function getProviders() end
+```
+
+**返回值：**
+
+| 类型           | 描述                       |
+| -------------- | -------------------------- |
+| `AiProvider[]` | 供应商数组，默认项排在最前 |
+
+**示例：**
+
+```lua
+for _, p in ipairs(ai.getProviders()) do
+  print(p.name .. " -> " .. p.model)
+end
+```
+
+### getDefaultProvider - 获取默认供应商。
+
+```lua
+---@return AiProvider|nil
+function getDefaultProvider() end
+```
+
+**返回值：**
+
+| 类型         | 描述                                 |
+| ------------ | ------------------------------------ |
+| `AiProvider` | 默认供应商；一个都没登记时返回 `nil` |
+
+### setDefaultProvider - 切换默认供应商。
+
+```lua
+---@param id string
+---@return boolean
+function setDefaultProvider(id) end
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述      |
+| ------ | ------ | -------- | ------ | --------- |
+| `id`   | string | 是       | -      | 供应商 id 或 name |
+
+**返回值：**
+
+| 类型      | 描述               |
+| --------- | ------------------ |
+| `boolean` | id 或 name 存在返回 `true` |
+
+### removeProvider - 删除供应商。
+
+```lua
+---@param id string
+---@return boolean
+function removeProvider(id) end
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述      |
+| ------ | ------ | -------- | ------ | --------- |
+| `id`   | string | 是       | -      | 供应商 id 或 name |
+
+**返回值：**
+
+| 类型      | 描述                  |
+| --------- | --------------------- |
+| `boolean` | 存在并删除返回 `true` |
+
+删掉的是默认供应商时，默认自动转给剩下的第一个。
+
+### ask - 单轮提问，可附带图片。
+
+```lua
+---@param prompt string
+---@param options AiOptions|nil
+---@return string|nil
+function ask(prompt, options) end
+```
+
+**参数：**
+
+| 参数名    | 类型        | 是否必填 | 默认值 | 描述                                              |
+| --------- | ----------- | -------- | ------ | ------------------------------------------------- |
+| `prompt`  | string      | 是       | -      | 问题                                              |
+| `options` | `AiOptions` | 否       | `nil`  | 见 [AiOptions](#aioptions)，图片参数同 image 模块 |
+
+**返回值：**
+
+| 类型     | 描述                                               |
+| -------- | -------------------------------------------------- |
+| `string` | 模型回复文本；失败返回 `nil`，原因看 `lastError()` |
+
+**示例：**
+
+```lua
+-- 纯文本
+local t = ai.ask("北京到上海高铁大概几小时？")
+
+-- 带系统提示 + 当前屏幕
+local desc = ai.ask("描述当前页面", { system = "你是手机自动化助手，回答尽量简短。", image = "screen" })
+
+-- 只看屏幕某个区域
+local price = ai.ask("这个区域里的价格是多少？只回答数字", { image = "screen", x = 0, y = 300, ex = 750, ey = 500 })
+
+-- 失败处理
+local r = ai.ask("你好")
+if r == nil then print(ai.lastError()) end
+```
+
+### judge - 是非判断。
+
+```lua
+---@param question string
+---@param options AiOptions|nil
+---@return boolean
+function judge(question, options) end
+```
+
+让模型只回答 yes / no，并解析成布尔值。适合做流程分支：「有没有弹窗」「是否到了首页」。
+
+**参数：**
+
+| 参数名     | 类型        | 是否必填 | 默认值 | 描述         |
+| ---------- | ----------- | -------- | ------ | ------------ |
+| `question` | string      | 是       | -      | 要判断的问题 |
+| `options`  | `AiOptions` | 否       | `nil`  | 同 `ask`     |
+
+**返回值：**
+
+| 类型      | 描述                                                                         |
+| --------- | ---------------------------------------------------------------------------- |
+| `boolean` | 模型回答肯定为 `true`；否定或请求失败为 `false`，失败时 `lastError()` 有内容 |
+
+**示例：**
+
+```lua
+if ai.judge("屏幕上是否出现了「领取成功」？", { image = "screen" }) then
+  print("领取成功")
+end
+
+-- 只看顶部区域，省 token
+while not ai.judge("顶部是否显示「首页」？", { image = "screen", x = 0, y = 0, ex = 0, ey = 200 }) do
+  action.click(375, 1500)
+  Sleep(1000)
+end
+
+-- 区分「回答否」和「请求失败」
+local ok = ai.judge("是否已登录？", { image = "screen" })
+if not ok and ai.lastError() then print("请求失败: " .. ai.lastError()) end
+```
+
+### extract - 从图片或文本里提取结构化数据。
+
+```lua
+---@param prompt string
+---@param options AiOptions|nil
+---@return table|nil
+function extract(prompt, options) end
+```
+
+要求模型输出 JSON 并自动解析成表。`schema` 用来告诉模型你想要的结构。
+
+**参数：**
+
+| 参数名    | 类型        | 是否必填 | 默认值 | 描述                                    |
+| --------- | ----------- | -------- | ------ | --------------------------------------- |
+| `prompt`  | string      | 是       | -      | 提取要求                                |
+| `options` | `AiOptions` | 否       | `nil`  | 同 `ask`，另支持 `schema`（字符串或表） |
+
+**返回值：**
+
+| 类型    | 描述                                                     |
+| ------- | -------------------------------------------------------- |
+| `table` | 解析后的表；模型没有输出合法 JSON 或请求失败返回 `nil` |
+
+**示例：**
+
+```lua
+-- 提取验证码
+local d = ai.extract("提取图中的验证码", {
+  image = "screen", x = 100, y = 800, ex = 600, ey = 900,
+  schema = { code = "string" },
+})
+if d then ime.input(d.code) end
+
+-- 提取列表
+local items = ai.extract("列出屏幕上所有商品的名称和价格", {
+  image = "screen", schema = { { name = "string", price = "number" } },
+})
+if items then
+  for _, it in ipairs(items) do print(it.name, it.price) end
+end
+
+-- 让模型给坐标（配合 action.click）
+local pos = ai.extract("找到「立即购买」按钮，给出它的中心点像素坐标", {
+  image = "screen", schema = { x = "number", y = "number" },
+})
+if pos then action.click(pos.x, pos.y) end
+```
+
+### chat - 多轮对话。
+
+```lua
+---@param messages (AiMessage|string)[]
+---@param options AiOptions|nil
+---@return string|nil
+function chat(messages, options) end
+```
+
+自己维护完整对话历史时用它；`ask` 是它的单轮封装。模块不记会话，每次都要把到目前为止的消息整表传进来。
+
+图片写在**那一条 user 消息**上，不要用 `options.image`。`options.system` 也不生效，系统提示写成第一条 `{ role = "system", content = "..." }`。
+
+失败返回 `nil`：不要把空回复推进历史，否则下一轮变成 `user → assistant(nil) → user`，Anthropic 会 400。Anthropic 协议下模块会自动合并连续同角色、并在首条是 assistant 时垫一条占位 user；OpenAI 兼容口更宽松，不必为此改脚本。
+
+**参数：**
+
+| 参数名     | 类型                    | 是否必填 | 默认值 | 描述                                                                    |
+| ---------- | ----------------------- | -------- | ------ | ----------------------------------------------------------------------- |
+| `messages` | `(AiMessage\|string)[]` | 是       | -      | 消息数组；直接写字符串等于 `user` 消息；图片参数写在消息里              |
+| `options`  | `AiOptions`             | 否       | `nil`  | `provider` / `model` / `temperature` / `maxTokens` / `json` / `timeout` |
+
+**返回值：**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `string` | 回复文本；失败返回 `nil` |
+
+**示例：**
+
+```lua
+local history = { { role = "system", content = "你是手机自动化助手" } }
+
+local function talk(content, extra)
+  local msg = { role = "user", content = content }
+  if extra then
+    for k, v in pairs(extra) do msg[k] = v end
+  end
+  table.insert(history, msg)
+  local reply = ai.chat(history)
+  if reply == nil then
+    table.remove(history)
+    print(ai.lastError())
+    return nil
+  end
+  table.insert(history, { role = "assistant", content = reply })
+  return reply
+end
+
+talk("看下现在在哪个页面", { image = "screen" })
+talk("那下一步该点哪里？")
+```
+
+### parseJson - 从模型文本里解析 JSON。
+
+```lua
+---@param text string
+---@return table|nil
+function parseJson(text) end
+```
+
+自动剥掉 Markdown 代码块和前后的解释文字。`extract` 内部就是用它解析。
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `text` | string | 是       | -      | 模型输出 |
+
+**返回值：**
+
+| 类型    | 描述                     |
+| ------- | ------------------------ |
+| `table` | 解析结果；失败返回 `nil` |
+
+### lastError - 最近一次调用失败的原因。
+
+```lua
+---@return string|nil
+function lastError() end
+```
+
+**返回值：**
+
+| 类型     | 描述                                 |
+| -------- | ------------------------------------ |
+| `string` | 错误文案；上一次调用成功时返回 `nil` |
+
+常见错误：未登记供应商、Key 错误 / 余额不足（接口返回的原文）、模型不支持图片、图片无效或裁剪越界、超时、模型没有输出 JSON。