ms-vite-plugin 1.4.74 → 1.4.76

package/docs/apipython/ai.md

@@ -0,0 +1,466 @@
+# AI 模块 (AI)
+
+AI 模块让脚本直接在手机上调用大模型：看图回答问题、做是非判断、从屏幕提取结构化数据、多轮对话。
+
+支持三种接口协议，覆盖绝大多数模型服务：
+
+| `protocol`  | 适用服务                                                                              |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `openai`    | DeepSeek、通义千问、Kimi、智谱、SiliconFlow、本机 Ollama / vLLM 等                     |
+| `anthropic` | 国内一般走 openai 兼容口，不必单独配                                                  |
+| `gemini`    | 国内一般走 openai 兼容口，不必单独配                                                  |
+
+模型配置（地址、Key、模型名）直接写在脚本里，脚本开头 `ai.setProvider` 一次即可；脚本停止后配置自动清空，不会存到手机上。
+
+所有方法同步阻塞，失败时返回 `None` / `False`，原因用 `ai.lastError()` 查看。
+
+## 快速开始
+
+```python
+from kuaijs import ai
+
+# 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"}):
+  print("已登录")
+
+# 4. 从屏幕某个区域提取数据
+data = ai.extract("提取验证码", {
+  "image": "screen", "x": 100, "y": 800, "ex": 600, "ey": 900,
+  "schema": {"code": "string"},
+})
+if data:
+  print(data.code)
+```
+
+## 图片参数
+
+图片参数和 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`，不裁剪                                                                                              |
+
+```python
+from kuaijs import ai, image
+
+# 当前全屏
+ai.ask("屏幕上有几个按钮？", {"image": "screen"})
+
+# 屏幕区域：左上 (0, 200) 到右下 (750, 600)
+ai.ask("这一块显示的价格是多少？", {"image": "screen", "x": 0, "y": 200, "ex": 750, "ey": 600})
+
+# 已有的图片 ID
+img = image.captureScreen()
+ai.ask("描述这张图", {"image": img, "x": 0, "y": 0, "ex": 750, "ey": 400})
+image.release(img)
+
+# 图片文件
+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
+
+```python
+from kuaijs._types import KuaiJSNamespace
+
+class AiProvider(KuaiJSNamespace):
+    id: str                       # 供应商 id，不传时自动生成
+    name: str                     # 展示名，例如 "DeepSeek"，调用时可用它选模型
+    protocol: str                 # "openai" / "anthropic" / "gemini"
+    baseUrl: str                  # 接口根地址，例如 https://api.deepseek.com
+    apiKey: str                   # API Key；openai 协议连本机模型时可为空
+    model: str                    # 默认模型名
+    headers: Dict[str, str]       # 额外请求头，某些网关需要
+    temperature: Optional[float]  # 默认温度；不传则不发该字段，用模型自己的默认值
+    maxTokens: Optional[int]      # 默认最大输出 token；不传则不发，用模型默认值（Anthropic 必填，缺省 2048）
+    reasoningEffort: Optional[str]  # 思考级别 none/low/medium/high/xhigh，仅 openai；不传不发，用服务商默认
+    supportsVision: bool          # 是否支持图片输入，默认 True
+    isDefault: bool               # 是否为默认供应商
+```
+
+### options 字典
+
+`ask` / `judge` / `extract` / `chat` 的第二个参数，所有键可选：
+
+| 键            | 类型               | 描述                                                       |
+| ------------- | ------------------ | ---------------------------------------------------------- |
+| `provider`    | str                | 用哪个供应商：id 或 name；不传用默认                       |
+| `model`       | str                | 临时换模型，覆盖供应商默认模型                             |
+| `temperature` | float              | 覆盖默认温度                                               |
+| `maxTokens`   | int                | 覆盖默认最大输出 token                                     |
+| `timeout`     | int                | 超时毫秒，默认 90000                                       |
+| `json`        | bool               | 要求模型输出 JSON（extract 自动开启）                      |
+| `system`      | str                | 系统提示（chat 不用这个，写在 messages 里）                |
+| `image`       | str                | imageId，同 image 模块：图片 ID / `"screen"` / 图片路径    |
+| `x` `y` `ex` `ey` | int            | 对 image 裁剪，同 `image.clip`；全 0 不裁剪                |
+| `images`      | List[str]          | 多张图，元素同 image，不裁剪                               |
+| `schema`      | str \| dict \| list | 仅 extract：期望的 JSON 结构说明                          |
+
+## API 参考
+
+### setProvider - 登记或更新模型供应商。
+
+```python
+def setProvider(config: Dict[str, Any]) -> Optional[AiProvider]:
+```
+
+**参数：**
+
+| 参数名   | 类型             | 是否必填 | 默认值 | 描述                                                                                |
+| -------- | ---------------- | -------- | ------ | ----------------------------------------------------------------------------------- |
+| `config` | `Dict[str, Any]` | 是       | -      | 新建至少要有 `baseUrl`、`model`（`protocol` 缺省 openai）；同 `id` 更新时没传的字段沿用旧值 |
+
+**返回值：**
+
+| 类型                   | 描述                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `Optional[AiProvider]` | 保存后的完整配置；`protocol` 不是三者之一或缺 `baseUrl` / `model` 时返回 `None` |
+
+第一个登记的供应商自动成为默认；`"isDefault": True` 会把默认切到它。
+
+**示例：**
+
+```python
+from kuaijs import ai
+
+# 只用一个模型（通义能看图）
+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 - 列出已登记的供应商。
+
+```python
+def getProviders() -> List[AiProvider]:
+```
+
+**返回值：**
+
+| 类型               | 描述                       |
+| ------------------ | -------------------------- |
+| `List[AiProvider]` | 供应商列表，默认项排在最前 |
+
+**示例：**
+
+```python
+from kuaijs import ai
+for p in ai.getProviders():
+  print(p.name, "->", p.model)
+```
+
+### getDefaultProvider - 获取默认供应商。
+
+```python
+def getDefaultProvider() -> Optional[AiProvider]:
+```
+
+**返回值：**
+
+| 类型                   | 描述                                  |
+| ---------------------- | ------------------------------------- |
+| `Optional[AiProvider]` | 默认供应商；一个都没登记时返回 `None` |
+
+### setDefaultProvider - 切换默认供应商。
+
+```python
+def setDefaultProvider(id: str) -> bool:
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述      |
+| ------ | ---- | -------- | ------ | --------- |
+| `id`   | str  | 是       | -      | 供应商 id 或 name |
+
+**返回值：**
+
+| 类型   | 描述               |
+| ------ | ------------------ |
+| `bool` | id 或 name 存在返回 `True` |
+
+### removeProvider - 删除供应商。
+
+```python
+def removeProvider(id: str) -> bool:
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述      |
+| ------ | ---- | -------- | ------ | --------- |
+| `id`   | str  | 是       | -      | 供应商 id 或 name |
+
+**返回值：**
+
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | 存在并删除返回 `True` |
+
+删掉的是默认供应商时，默认自动转给剩下的第一个。
+
+### ask - 单轮提问，可附带图片。
+
+```python
+def ask(prompt: str, options: Optional[Dict[str, Any]] = None) -> Optional[str]:
+```
+
+**参数：**
+
+| 参数名    | 类型             | 是否必填 | 默认值 | 描述                                           |
+| --------- | ---------------- | -------- | ------ | ---------------------------------------------- |
+| `prompt`  | str              | 是       | -      | 问题                                           |
+| `options` | `Dict[str, Any]` | 否       | `None` | 见 [options 字典](#options-字典)，图片参数同 image 模块 |
+
+**返回值：**
+
+| 类型            | 描述                                                |
+| --------------- | --------------------------------------------------- |
+| `Optional[str]` | 模型回复文本；失败返回 `None`，原因看 `lastError()` |
+
+**示例：**
+
+```python
+from kuaijs import ai
+
+# 纯文本
+t = ai.ask("北京到上海高铁大概几小时？")
+
+# 带系统提示 + 当前屏幕
+desc = ai.ask("描述当前页面", {"system": "你是手机自动化助手，回答尽量简短。", "image": "screen"})
+
+# 只看屏幕某个区域
+price = ai.ask("这个区域里的价格是多少？只回答数字", {"image": "screen", "x": 0, "y": 300, "ex": 750, "ey": 500})
+
+# 失败处理
+r = ai.ask("你好")
+if r is None:
+  print(ai.lastError())
+```
+
+### judge - 是非判断。
+
+```python
+def judge(question: str, options: Optional[Dict[str, Any]] = None) -> bool:
+```
+
+让模型只回答 yes / no，并解析成布尔值。适合做流程分支：「有没有弹窗」「是否到了首页」。
+
+**参数：**
+
+| 参数名     | 类型             | 是否必填 | 默认值 | 描述         |
+| ---------- | ---------------- | -------- | ------ | ------------ |
+| `question` | str              | 是       | -      | 要判断的问题 |
+| `options`  | `Dict[str, Any]` | 否       | `None` | 同 `ask`     |
+
+**返回值：**
+
+| 类型   | 描述                                                                          |
+| ------ | ----------------------------------------------------------------------------- |
+| `bool` | 模型回答肯定为 `True`；否定或请求失败为 `False`，失败时 `lastError()` 有内容 |
+
+**示例：**
+
+```python
+from kuaijs import ai, action
+import time
+
+if ai.judge("屏幕上是否出现了「领取成功」？", {"image": "screen"}):
+  print("领取成功")
+
+# 只看顶部区域，省 token
+while not ai.judge("顶部是否显示「首页」？", {"image": "screen", "x": 0, "y": 0, "ex": 0, "ey": 200}):
+  action.click(375, 1500)
+  time.sleep(1)
+
+# 区分「回答否」和「请求失败」
+ok = ai.judge("是否已登录？", {"image": "screen"})
+if not ok and ai.lastError():
+  print("请求失败:", ai.lastError())
+```
+
+### extract - 从图片或文本里提取结构化数据。
+
+```python
+def extract(prompt: str, options: Optional[Dict[str, Any]] = None) -> Optional[Any]:
+```
+
+要求模型输出 JSON 并自动解析。对象返回 namespace（属性访问），数组返回 `list`。`schema` 用来告诉模型你想要的结构。
+
+**参数：**
+
+| 参数名    | 类型             | 是否必填 | 默认值 | 描述                                           |
+| --------- | ---------------- | -------- | ------ | ---------------------------------------------- |
+| `prompt`  | str              | 是       | -      | 提取要求                                       |
+| `options` | `Dict[str, Any]` | 否       | `None` | 同 `ask`，另支持 `schema`（字符串、字典或列表） |
+
+**返回值：**
+
+| 类型            | 描述                                                      |
+| --------------- | --------------------------------------------------------- |
+| `Optional[Any]` | 解析后的数据；模型没有输出合法 JSON 或请求失败返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import ai, action, ime
+
+# 提取验证码
+d = ai.extract("提取图中的验证码", {
+  "image": "screen", "x": 100, "y": 800, "ex": 600, "ey": 900,
+  "schema": {"code": "string"},
+})
+if d:
+  ime.input(d.code)
+
+# 提取列表
+items = ai.extract("列出屏幕上所有商品的名称和价格", {
+  "image": "screen", "schema": [{"name": "string", "price": "number"}],
+})
+if items:
+  for it in items:
+    print(it.name, it.price)
+
+# 让模型给坐标（配合 action.click）
+pos = ai.extract("找到「立即购买」按钮，给出它的中心点像素坐标", {
+  "image": "screen", "schema": {"x": "number", "y": "number"},
+})
+if pos:
+  action.click(pos.x, pos.y)
+```
+
+### chat - 多轮对话。
+
+```python
+def chat(messages: List[Union[Dict[str, Any], str]], options: Optional[Dict[str, Any]] = None) -> Optional[str]:
+```
+
+自己维护完整对话历史时用它；`ask` 是它的单轮封装。模块不记会话，每次都要把到目前为止的消息整表传进来。
+
+图片写在**那一条 user 消息**上，不要用 `options["image"]`。`options["system"]` 也不生效，系统提示写成第一条 `{"role": "system", "content": "..."}`。
+
+失败返回 `None`：不要把空回复推进历史，否则下一轮变成 `user → assistant(None) → user`，Anthropic 会 400。Anthropic 协议下模块会自动合并连续同角色、并在首条是 assistant 时垫一条占位 user；OpenAI 兼容口更宽松，不必为此改脚本。
+
+**参数：**
+
+| 参数名     | 类型                               | 是否必填 | 默认值 | 描述                                                                                  |
+| ---------- | ---------------------------------- | -------- | ------ | ------------------------------------------------------------------------------------- |
+| `messages` | `List[Union[Dict[str, Any], str]]` | 是       | -      | 每项 `{"role", "content", 可选 image / x / y / ex / ey / images}`；直接写字符串等于 `user` 消息 |
+| `options`  | `Dict[str, Any]`                   | 否       | `None` | `provider` / `model` / `temperature` / `maxTokens` / `json` / `timeout`               |
+
+**返回值：**
+
+| 类型            | 描述                      |
+| --------------- | ------------------------- |
+| `Optional[str]` | 回复文本；失败返回 `None` |
+
+**示例：**
+
+```python
+from kuaijs import ai
+
+history = [{"role": "system", "content": "你是手机自动化助手"}]
+
+def talk(content, extra=None):
+  msg = {"role": "user", "content": content}
+  if extra:
+    msg.update(extra)
+  history.append(msg)
+  reply = ai.chat(history)
+  if reply is None:
+    history.pop()
+    print(ai.lastError())
+    return None
+  history.append({"role": "assistant", "content": reply})
+  return reply
+
+talk("看下现在在哪个页面", {"image": "screen"})
+talk("那下一步该点哪里？")
+```
+
+### parseJson - 从模型文本里解析 JSON。
+
+```python
+def parseJson(text: str) -> Optional[Any]:
+```
+
+自动剥掉 Markdown 代码块和前后的解释文字。`extract` 内部就是用它解析。
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述     |
+| ------ | ---- | -------- | ------ | -------- |
+| `text` | str  | 是       | -      | 模型输出 |
+
+**返回值：**
+
+| 类型            | 描述                                              |
+| --------------- | ------------------------------------------------- |
+| `Optional[Any]` | 对象为 namespace，数组为 `list`；失败返回 `None` |
+
+### lastError - 最近一次调用失败的原因。
+
+```python
+def lastError() -> Optional[str]:
+```
+
+**返回值：**
+
+| 类型            | 描述                                  |
+| --------------- | ------------------------------------- |
+| `Optional[str]` | 错误文案；上一次调用成功时返回 `None` |
+
+常见错误：未登记供应商、Key 错误 / 余额不足（接口返回的原文）、模型不支持图片、图片无效或裁剪越界、超时、模型没有输出 JSON。

package/docs/apipython/overview.md

@@ -8,45 +8,6 @@
 from kuaijs import action, cloud, hid, image, appleocr, paddleocr, yolo, yolocls, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
 ```
 
-## 下载资源
-
-- 官方网盘下载：[链接](https://pan.kuai.js.cn/#/_/%E5%BF%AB%E7%82%B9JS)
-
-## nodejs 环境
-
-`快点JS` 开发工具基于 nodejs 环境，因此需要先安装 nodejs 环境。
-
-## python 环境
-
-`快点JS` - Python 基于 Python3.14 版本，因此需要先安装 Python3.14 环境。
-
-自行安装：`pip install kuaijs-ios` 以获取代码提示
-
-## IDE 配置
-
-### Visual Studio Code
-
-`快点JS` 使用 Visual Studio Code 作为主要开发工具，并安装以下扩展：
-
-#### 必需扩展
-
-- **`快点JS开发工具`** - 提供 `快点JS` 相关功能，如创建项目、代码补全、图色工具、节点查找、打包软件包 等
-
-#### 安装步骤
-
-1. 打开 Visual Studio Code
-2. 点击左侧扩展图标（或使用快捷键 `Ctrl+Shift+X`）
-3. 在搜索框中输入 `快点JS开发工具`
-   <img src="/img/DevPlugin.jpg" width="800" alt="安装快点JS开发工具">
-4. 点击安装按钮安装扩展
-5. 安装完成后，重新启动 Visual Studio Code
-
-## 创建项目
-
-- 参照[创建 JS 项目](../quick/createProject.md)创建项目
-
-- 创建项目时选择 `Python` 作为项目类型
-
 ## 标准库
 
 Python 的标准库大部分都是支持的.

package/docs/quick/vscode/createProject.md

@@ -4,7 +4,6 @@
 
 - 已安装 Visual Studio Code 和 快点 JS 开发工具插件
 - 快点 JS 开发工具插件需要登录`快点JS 开发者账号`，才能创建项目，请点击顶部菜单`开发者后台`注册账号
-- 快点 JS APP 也需要注册账号才能使用，注意`快点JS APP的账号`和 `快点JS 开发工具插件`的账号是不同的
 - 快点 JS APP 需要从`快点JS APP` 上<span style="color: red;">注册账号</span>，注册完成后，需要登录`快点JS APP`，才能使用
 
 ## 创建项目

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.74",
+  "version": "1.4.76",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {