ms-vite-plugin 1.4.74 → 1.4.76

package/docs/apicn/ai.md

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