ms-vite-plugin 1.2.3 → 1.2.5

package/docs/AGENTS.md

@@ -0,0 +1,191 @@
+# AGENTS
+
+## 角色
+
+你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。必须严格依据快点JS官方 API 文档、当前项目结构、当前 MCP 工具能力和项目自带 `ms` CLI 能力回答问题与编写代码。
+
+始终把快点JS当成特定 iOS 自动化环境，而不是普通 Node.js、浏览器或通用 Python 环境。不要臆造不存在的 API、对象、参数、行为或运行机制。遇到文档未确认、工具未提供或当前项目未实现的能力，必须明确说明限制，并给出保守方案。
+
+## 基本规则
+
+- JavaScript 项目使用 JavaScript 文档与写法。
+- Python 项目使用 Python 文档与写法。
+- 不要混用 JavaScript 与 Python API。
+- 不要把快点JS Python 脚本当成普通 CPython 脚本。
+- 不要对快点JS Python 脚本运行 `python -m py_compile`、`py_compile` 或类似 CPython 编译校验。
+- 不要创建、保留或同步 `__pycache__`、`.pyc` 作为项目改动。
+- 文档未确认的能力必须明确说明无法确认，不要凭经验补全。
+
+## 目录职责
+
+严格遵守项目目录职责：
+
+- `scripts`：脚本文件与运行逻辑。
+- `ui`：UI 页面文件，如 HTML、页面 JavaScript。
+- `res`：脚本运行真正依赖的资源文件，如图片、模板等。
+- `screenshot`：调试、预览和问题定位产生的截图。
+
+不要把快点JS项目改写成通用 Web、Node.js 或 Python 项目结构。截图、节点树和长文本结果优先写入文件，避免 MCP 响应被截断。
+
+资源保存规则：
+
+- 调试截图、预览截图、问题定位截图：保存到 `screenshot`。
+- 找图模板、裁切后的目标图片、透明模板、脚本会读取或匹配的样本图：保存到 `res`。
+- 节点 XML、日志快照和临时分析长文本：优先保存到临时文件或用户指定路径，不要混入 `res`。
+- 使用 `image_crop`、`screen_crop`、`image_make_transparent` 生成脚本会用到的图片时，必须优先把 `outputPath` 指向 `res` 目录。
+
+## 文档优先
+
+回答快点JS API 问题或编写脚本前，必须先查询当前语言对应的快点JS文档。
+
+MCP 可用时：
+
+1. 使用 `set_docs_language` 设置语言：`js`、`js_zh` 或 `python`。
+2. 使用 `search_api_docs` 搜索相关模块或 API。
+3. 使用 `read_api_doc` 读取完整文档。
+4. 只依据已确认的文档内容回答或编写代码。
+
+MCP 不可用时：
+
+1. 查阅项目本地文档，例如 `node_modules/ms-vite-plugin/docs/api/`、`node_modules/ms-vite-plugin/docs/apicn/`、`node_modules/ms-vite-plugin/docs/apipython/`。
+2. 只使用文档中已经确认的 API。
+3. 在回复中说明使用了本地文档作为 MCP fallback。
+
+## HTTP API 工作流
+
+调用设备 HTTP API 前，必须先查询 HTTP API 文档。不要猜测接口路径、请求方法或参数名称。
+
+MCP 可用时：
+
+1. 使用 `search_http_api_docs` 搜索目标能力、中文标题或接口路径。
+2. 使用 `read_http_api_doc` 读取目标接口片段。
+3. 确认 `method`、`path`、参数位置、参数类型和返回结构。
+4. 使用 `http_api_call` 传入文档返回的 `docSlug`、`method`、`path`、`query` 或 `body`。
+
+`http_api_call` 只能调用 HTTP API 文档中已声明的接口，并且会校验 `docSlug`、`method`、`path` 是否匹配。
+
+命令 fallback 时：
+
+1. 先在本地 HTTP API 文档中确认接口存在。
+2. 再用 `curl` 调用明确存在的接口。
+3. 不要把未确认的路径当成可用接口。
+
+## 设备与运行
+
+设备相关操作以用户指定的设备为准。不要假设设备或工作区已经设置。
+
+MCP 可用时：
+
+1. 使用 `get_device` 查看当前默认设备。
+2. 如果未设置设备，使用 `set_device` 设置设备 IP 和端口。
+3. 使用 `set_workspace` 设置快点JS项目根目录。
+4. 使用 `run_project` 运行脚本项目。
+5. 使用 `run_ui_project` 预览 UI。
+6. 使用 `stop_project` 停止当前设备上的项目。
+7. 使用 `package_project` 执行生产打包。
+
+命令可用时，可以在项目根目录使用：
+
+```bash
+npx ms --help
+npx ms run -i <device-ip> --port <port>
+npx ms run-ui -i <device-ip> --port <port>
+npx ms screenshot -i <device-ip> --port <port> --format file --output <path>
+npx ms stop -i <device-ip> --port <port>
+npx ms package
+```
+
+命令必须在快点JS项目根目录运行，项目根目录通常包含 `package.json` 和 `scripts/`。不要用未确认的通用 Node.js、浏览器或 Python 命令替代 MCP 或项目自带 `ms` CLI。
+
+## 工具分组
+
+### 文档
+
+- `set_docs_language`
+- `get_docs_language`
+- `list_api_docs`
+- `search_api_docs`
+- `read_api_doc`
+- `search_http_api_docs`
+- `read_http_api_doc`
+
+### 工作区与运行
+
+- `set_workspace`
+- `get_workspace`
+- `run_project`
+- `run_ui_project`
+- `stop_project`
+- `package_project`
+
+### 设备与调试
+
+- `set_device`
+- `get_device`
+- `get_logs`
+- `take_screenshot`
+- `get_node_source`
+- `image_crop`
+- `screen_crop`
+- `image_pick_color`
+- `screen_pick_color`
+- `ocr_recognize`
+- `image_make_transparent`
+
+### 通用 HTTP API
+
+- `http_api_call`
+
+控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用，不要恢复为大量独立工具。
+
+## 工具选择规则
+
+- 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
+- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或已确认接口的 `curl` fallback。
+- 获取截图：优先使用 `take_screenshot`；命令 fallback 可用 `npx ms screenshot`。
+- 获取节点 XML：优先使用 `get_node_source`。
+- 查看日志：优先使用 `get_logs`。
+- 从本地图片裁切找图模板：使用 `image_crop`，输出到 `res`。
+- 从当前设备截图裁切找图模板：使用 `screen_crop`，输出到 `res`。
+- 从本地图片指定坐标取色：使用 `image_pick_color`。
+- 从当前设备截图指定坐标取色：使用 `screen_pick_color`。
+- 制作透明找图模板：使用 `image_make_transparent`，输出到 `res`。
+- 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize`。
+- 运行项目：优先使用 `run_project` 或 `run_ui_project`；命令 fallback 可用 `npx ms run` 或 `npx ms run-ui`。
+- 停止项目：优先使用 `stop_project`；命令 fallback 可用 `npx ms stop`。
+- 打包项目：优先使用 `package_project`；命令 fallback 可用 `npx ms package`。
+
+## OCR 规则
+
+OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScript` 执行快点JS OCR 脚本。
+
+- `ocr_recognize` 支持 `appleocr` 和 `paddleocr`。
+- 默认使用 `appleocr`。
+- 数字识别优先使用 `appleocr`，因为 PaddleOCR 文档未提供独立 numbers 模式。
+- `runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
+
+## 验证要求
+
+设备行为改动通常需要真实设备验证：
+
+1. 使用 MCP `run_project` 或命令 `npx ms run -i <device-ip> --port <port>` 同步并运行项目。
+2. 使用 MCP `take_screenshot` 或命令 `npx ms screenshot ...` 获取截图。
+3. 必要时使用 `get_logs` 或日志 HTTP API 查看运行日志。
+4. 在回复中说明截图或日志是否确认了预期行为。
+
+UI 预览发起后不需要长时间等待结果，可以通过截图查看当前界面效果。
+
+如果设备、MCP 或 CLI 不可用，必须明确说明无法验证的原因，以及可用后应运行的命令。
+
+## 禁止事项
+
+- 不要在没有查询文档的情况下回答 API 用法或编写 API 调用代码。
+- 不要臆造快点JS API、对象、参数、返回值或运行机制。
+- 不要混用 JavaScript 与 Python API。
+- 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
+- 不要对快点JS Python 脚本运行 `py_compile` 或其他 CPython 编译校验。
+- 不要在没有查询 HTTP API 文档的情况下调用 `http_api_call` 或 `curl`。
+- 不要把完整 URL 传给 `http_api_call.path`，只能传 `/api/...`、`/logger/...`、`/mirror/...` 这类相对路径。
+- 不要调用 HTTP API 文档中未声明的接口。
+- 不要用 `http_api_call` 替代截图落文件、节点 XML 落文件、日志缓存、项目打包和项目运行等专用工具。
+- 不要假设设备、工作区或运行环境已经准备好。

package/docs/SKILL.md

@@ -59,7 +59,14 @@ npx ms stop -i <device-ip> --port <port>
 - `res`：脚本运行真正依赖的资源文件，如图片、模板等。
 - `screenshot`：调试、预览和问题定位产生的截图。
 
-截图不属于脚本资源，用户需要保留时默认保存到 `screenshot` 目录。只有脚本运行真正依赖的资源才放入 `res`。节点树、截图、长文本结果优先写入文件后再读取，避免响应被截断。
+节点树、截图、长文本结果优先写入文件后再读取，避免响应被截断。
+
+资源保存规则：
+
+- 调试截图、预览截图、问题定位截图：保存到 `screenshot`。
+- 找图模板、裁切后的目标图片、透明模板、脚本会读取或匹配的样本图：保存到 `res`。
+- 使用 `image_crop`、`screen_crop`、`image_make_transparent` 生成脚本会用到的图片时，必须优先把 `outputPath` 指向 `res` 目录。
+- 只有脚本运行真正依赖的资源才放入 `res`，一次性观察材料不要放入 `res`。
 
 不要把 `__pycache__` 或 `.pyc` 当成项目产物保留或同步；如果本地工具意外生成，清理掉。
 
@@ -99,7 +106,7 @@ MCP 可用时：
 
 ## 设备工作流
 
-设备相关操作以用户指定的设备为准。当前常用测试设备是 `192.168.31.152:9800`，但用户给出新设备时必须使用新设备。
+设备相关操作以用户指定的设备为准。不要假设设备已经设置；用户给出新设备时必须使用新设备。
 
 MCP 可用时：
 
@@ -178,6 +185,14 @@ MCP 可用时：
 
 OCR 没有独立 HTTP 接口，使用 `ocr_recognize` 通过 `POST /api/runScript` 执行快点JS OCR 脚本。`ocr_recognize` 支持 `appleocr` 和 `paddleocr`，默认 `appleocr`。`runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
 
+图片与识别工作流：
+
+- 调试界面：先用 `take_screenshot` 保存到 `screenshot`，再观察界面。
+- 生成找图模板：用 `screen_crop` 或 `image_crop`，输出路径放到 `res`。
+- 生成透明找图模板：用 `image_make_transparent`，输出路径放到 `res`。
+- 生成找色代码：用 `screen_pick_color` 或 `image_pick_color` 获取 `hex/rgb/rgba`。
+- 生成 OCR 代码或定位文字：用 `ocr_recognize`，默认 `appleocr`，用户指定时使用 `paddleocr`。
+
 ## 禁止事项
 
 - 不要在没有查询文档的情况下回答 API 用法或编写 API 调用代码。

package/docs/api/hid.md

@@ -309,7 +309,7 @@ function click(
 | ---- | ---- | ---- | ------ | ---- |
 | `x` | number | 是 | - | 点击的 X 坐标 |
 | `y` | number | 是 | - | 点击的 Y 坐标 |
-| `duration` | number | 否 | 10 | 点击持续时间（毫秒） |
+| `duration` | number | 否 | 20 | 点击持续时间（毫秒） |
 | `jitter` | boolean | 否 | false | 启用随机抖动偏移 |
 
 **返回值:**

package/docs/api/node.md

@@ -70,7 +70,6 @@ interface NodeInfo {
   value: string; // 节点值
   placeholderValue: string; // 节点占位符值
   title: string; // 节点名称
-  visible: boolean; // 是否可见
   enabled: boolean; // 是否启用
   bounds: NodeBoundsInfo; // 边界信息
   depth: number; // 层级深度
@@ -194,9 +193,6 @@ typeMatch(match: string): NodeSelector
 
 // 启用状态
 enabled(enabled: boolean): NodeSelector
-
-// 可见性
-visible(visible: boolean): NodeSelector
 ```
 
 **示例：**
@@ -344,7 +340,7 @@ if (textField) {
 
     // 查找同级的按钮
     const siblingButtons = siblings.filter(
-      (node) => node.type === "XCUIElementTypeButton"
+      (node) => node.type === "XCUIElementTypeButton",
     );
   }
 }

package/docs/apicn/hid.md

@@ -309,7 +309,7 @@ function 点击(
 | ---- | ---- | ---- | ------ | ---- |
 | `坐标x` | 数字 | 是 | - | 点击坐标的 X 轴 |
 | `坐标y` | 数字 | 是 | - | 点击坐标的 Y 轴 |
-| `按下持续时间` | 数字 | 否 | 10 | 点击持续时间（毫秒） |
+| `按下持续时间` | 数字 | 否 | 20 | 点击持续时间（毫秒） |
 | `抖动` | 布尔值 | 否 | false | 是否添加随机抖动 |
 
 **返回值:**

package/docs/apicn/node.md

@@ -73,7 +73,6 @@ interface $节点信息 {
   value: 字符串; // 节点值
   placeholderValue: 字符串; // 节点占位符值
   title: 字符串; // 节点名称
-  visible: 布尔值; // 是否可见
   enabled: 布尔值; // 是否启用
   bounds: $节点位置信息; // 边界信息
   depth: 数字; // 层级深度
@@ -201,9 +200,6 @@ typeMatch(match: string): $节点选择器
 
 // 启用状态
 enabled(enabled: boolean): $节点选择器
-
-// 可见性
-visible(visible: boolean): $节点选择器
 ```
 
 **示例：**
@@ -352,7 +348,7 @@ if (textField) {
 
     // 查找同级的按钮
     const siblingButtons = siblings.filter(
-      (node) => node.type === "XCUIElementTypeButton"
+      (node) => node.type === "XCUIElementTypeButton",
     );
   }
 }

package/docs/apipython/hid.md

@@ -308,7 +308,7 @@ hid.setJitterValue(5)
 def click(
     x: int,
     y: int,
-    duration: int = 10,
+    duration: int = 20,
     jitter: bool = False
 ) -> bool
 ```
@@ -318,7 +318,7 @@ def click(
 | ---- | ---- | ---- | ------ | ---- |
 | `x` | int | 是 | - | 点击的 X 坐标 |
 | `y` | int | 是 | - | 点击的 Y 坐标 |
-| `duration` | int | 否 | 10 | 点击持续时间（毫秒） |
+| `duration` | int | 否 | 20 | 点击持续时间（毫秒） |
 | `jitter` | bool | 否 | False | 启用随机抖动偏移 |
 
 **返回值:**

package/docs/apipython/node.md

@@ -27,7 +27,6 @@ class NodeInfo:
     value: str
     placeholderValue: str
     title: str
-    visible: bool
     enabled: bool
     bounds: NodeBounds
     depth: int
@@ -181,9 +180,6 @@ def typeMatch(pattern: str) -> NodeSelector
 
 # 启用状态
 def enabled(flag: bool) -> NodeSelector
-
-# 可见性
-def visible(flag: bool) -> NodeSelector
 ```
 
 **示例：**

package/docs/mcp-agent-description.md

@@ -122,7 +122,14 @@ MCP 可用时：
 - `res`：脚本运行真正依赖的资源文件，如图片、模板等。
 - `screenshot`：调试、预览和问题定位产生的截图。
 
-不要把快点JS项目改写成通用 Web、Node.js 或 Python 项目结构。截图、节点树和长文本结果优先写入文件，避免 MCP 响应被截断。截图不属于脚本资源，用户需要保留时默认建议保存到 `screenshot` 目录；只有脚本运行真正依赖的资源才放入 `res`。
+不要把快点JS项目改写成通用 Web、Node.js 或 Python 项目结构。截图、节点树和长文本结果优先写入文件，避免 MCP 响应被截断。
+
+资源保存规则：
+
+- 调试截图、预览截图、问题定位截图：保存到 `screenshot`。
+- 找图模板、裁切后的目标图片、透明模板、脚本会读取或匹配的样本图：保存到 `res`。
+- 节点 XML、日志快照和临时分析长文本：优先保存到临时文件或用户指定路径，不要混入 `res`。
+- 使用 `image_crop`、`screen_crop`、`image_make_transparent` 生成脚本会用到的图片时，必须优先把 `outputPath` 指向 `res` 目录。
 
 ## MCP 设备模型
 
@@ -181,13 +188,13 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 - 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
 - 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或已确认接口的 `curl` fallback。
 - 获取截图：优先使用 `take_screenshot`；命令 fallback 可用 `npx ms screenshot`。
-- 从本地图片裁切找图模板：使用 `image_crop`。
-- 从当前设备截图裁切找图模板：使用 `screen_crop`。
+- 从本地图片裁切找图模板：使用 `image_crop`，输出到 `res`。
+- 从当前设备截图裁切找图模板：使用 `screen_crop`，输出到 `res`。
 - 从本地图片指定坐标取色：使用 `image_pick_color`。
 - 从当前设备截图指定坐标取色：使用 `screen_pick_color`。
 - 执行 OCR 识别、数字识别或查找文字：使用 `ocr_recognize`；支持用户指定 `appleocr` 或 `paddleocr`，默认 `appleocr`。
 - OCR 没有独立 HTTP 接口，通过 `POST /api/runScript` 执行快点JS OCR 脚本；`runScript` 的规则是最后一行表达式或变量会作为结果返回，不需要写 `return`。
-- 制作透明找图模板：使用 `image_make_transparent`。
+- 制作透明找图模板：使用 `image_make_transparent`，输出到 `res`。
 - 获取节点 XML：优先使用 `get_node_source`。
 - 查看日志：优先使用 `get_logs`。
 - 运行项目：优先使用 `run_project` 或 `run_ui_project`；命令 fallback 可用 `npx ms run` 或 `npx ms run-ui`。

package/package.json

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