ms-vite-plugin 1.2.0 → 1.2.2

package/docs/SKILL.md

@@ -1,24 +1,54 @@
 ---
 name: kuaijs-mcp
-description: 快点JS专用 MCP 开发助手。用于快点JS项目开发、API 文档查询、iOS 设备自动化、HTTP API 调用、截图、节点 XML、日志查看、项目运行和打包；必须先查快点JS文档并使用当前 MCP 工具能力，不臆造 API 或运行机制。
+description: 快点JS专用开发助手。用于快点JS项目开发、API 文档查询、iOS 设备自动化、HTTP API 调用、截图、节点 XML、日志查看、项目运行和打包；MCP 工具和项目自带 ms CLI 都可以使用，但必须依据快点JS文档与项目结构，不臆造 API 或运行机制。
 ---
 
-# 快点JS MCP 技能
+# 快点JS开发技能
 
 ## 使用场景
 
 当任务涉及快点JS项目开发、快点JS API 查询、iOS 设备自动化、HTTP API 调用、截图、节点 XML、日志、项目运行或打包时，使用本技能。
 
-你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。必须严格依据快点JS官方 API 文档、当前项目结构和当前 MCP 工具能力回答问题与编写代码。
+你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。必须严格依据快点JS官方 API 文档、当前项目结构、当前 MCP 工具能力和项目自带命令能力回答问题与编写代码。
 
 ## 基本约束
 
 - 不要臆造不存在的 API、对象、参数、行为或运行机制。
 - 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
-- JavaScript 项目使用 JavaScript 文档与写法。
 - Python 项目使用 Python 文档与写法。
+- JavaScript 项目使用 JavaScript 文档与写法。
 - 不要混用 JavaScript 与 Python API。
 - 文档未确认的能力必须明确说明无法确认，并给出保守方案。
+- 快点JS Python 脚本不使用 CPython 编译校验；不要运行 `python -m py_compile`、`py_compile` 或类似命令。
+
+## 允许的执行方式
+
+MCP 工具和项目命令都可以使用。
+
+优先使用 MCP 的情况：
+
+- 查询快点JS API 文档。
+- 查询 HTTP API 文档并通过 `http_api_call` 调用。
+- 设置设备、设置工作区、运行项目、截图、抓节点树、读日志。
+
+可以使用命令的情况：
+
+- MCP transport 断开或不可用。
+- 用户明确要求使用命令。
+- 需要快速验证项目本地 `ms` CLI 能力。
+- 使用项目自带 KuaiJS CLI 进行同步、运行、停止、截图。
+
+允许的常用命令示例：
+
+```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>
+```
+
+使用 `curl` 调用设备 HTTP API 前，必须先通过 MCP HTTP API 文档或本地 HTTP API 文档确认接口存在、方法、路径、参数位置和返回结构。
 
 ## 目录职责
 
@@ -29,66 +59,67 @@ description: 快点JS专用 MCP 开发助手。用于快点JS项目开发、API
 - `res`：脚本运行真正依赖的资源文件，如图片、模板等。
 - `screenshot`：调试、预览和问题定位产生的截图。
 
-截图不属于脚本资源，用户需要保留时默认建议保存到 `screenshot` 目录。只有脚本运行真正依赖的资源才放入 `res`。节点树、截图、长文本结果优先写入文件后再读取，避免响应被截断。
+截图不属于脚本资源，用户需要保留时默认保存到 `screenshot` 目录。只有脚本运行真正依赖的资源才放入 `res`。节点树、截图、长文本结果优先写入文件后再读取，避免响应被截断。
+
+不要把 `__pycache__` 或 `.pyc` 当成项目产物保留或同步；如果本地工具意外生成，清理掉。
 
 ## 文档工作流
 
 回答快点JS API 或编写脚本前，先确认语言并查询对应语言文档。
 
+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/apipython/`、`node_modules/ms-vite-plugin/docs/httpapi/`。
+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`。
 
-示例：
-
-```json
-{
-  "method": "GET",
-  "path": "/api/status",
-  "docSlug": "get-api-status"
-}
-```
-
-带 query 参数示例：
-
-```json
-{
-  "method": "GET",
-  "path": "/api/control/click",
-  "docSlug": "get-api-control-click",
-  "query": {
-    "x": 100,
-    "y": 200,
-    "duration": 20
-  }
-}
-```
+命令 fallback 时：
 
-`http_api_call` 只能调用 HTTP API 文档中声明过的接口，并且会校验 `docSlug`、`method`、`path` 是否匹配。
+1. 先在本地 HTTP API 文档中确认接口。
+2. 再用 `curl` 调用明确存在的接口。
+3. 不要把未确认的路径当成可用接口。
 
 ## 设备工作流
 
-设备相关操作以 `set_device` 设置的 HTTP 设备为准。
+设备相关操作以用户指定的设备为准。当前常用测试设备是 `192.168.31.152:9800`，但用户给出新设备时必须使用新设备。
+
+MCP 可用时：
 
 1. 使用 `get_device` 查看当前默认设备。
 2. 如果未设置设备，使用 `set_device` 设置设备 IP 和端口。
 3. 设置设备后，日志 SSE 后台订阅会自动启动。
 4. 使用 `get_logs` 获取日志缓存快照。
 
-UI 预览发起后不需要长时间等待结果，可以用 `take_screenshot` 查看当前界面效果。
+命令 fallback 时：
+
+- 用 `npx ms run -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>` 停止项目。
+
+UI 预览发起后不需要长时间等待结果，可以用截图查看当前界面效果。
 
 ## 项目运行工作流
 
+MCP 可用时：
+
 1. 使用 `set_workspace` 设置快点JS项目根目录。
 2. 使用 `get_workspace` 确认当前工作区。
 3. 使用 `run_project` 运行脚本项目。
@@ -96,6 +127,12 @@ UI 预览发起后不需要长时间等待结果，可以用 `take_screenshot`
 5. 使用 `stop_project` 停止当前设备上的项目。
 6. 使用 `package_project` 执行生产打包。
 
+命令可用时：
+
+1. 使用项目根目录执行 `npx ms --help` 确认 CLI。
+2. 使用 `npx ms run -i <device-ip> --port <port>` 同步并运行。
+3. 使用 `npx ms screenshot ...` 验证界面。
+
 工作区必须包含 `package.json` 和 `scripts/`。
 
 ## 工具分组
@@ -131,17 +168,17 @@ UI 预览发起后不需要长时间等待结果，可以用 `take_screenshot`
 
 - `http_api_call`
 
-控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用，不再依赖大量独立 MCP 工具。
+控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；命令 fallback 时可用已确认文档的 `curl` 调用。
 
 ## 禁止事项
 
 - 不要在没有查询文档的情况下回答 API 用法或编写 API 调用代码。
 - 不要调用 HTTP API 文档中未声明的接口。
 - 不要把完整 URL 传给 `http_api_call.path`。
-- 不要用 `http_api_call` 替代截图落文件、节点 XML 落文件、日志缓存、项目运行或项目打包工具。
+- 不要用未确认的通用命令替代 KuaiJS MCP 或项目自带 `ms` CLI。
+- 不要对 `scripts/*.py` 运行 `py_compile` 或把快点JS Python 当 CPython 编译。
 - 不要假设设备、工作区或运行环境已经准备好。
-- 不要执行通用构建命令替代 MCP 项目运行工具。
 
 ## 文档入口
 
-所有 API 文档都通过 MCP 文档工具查询，不直接依赖或暴露本地文档路径。
+优先通过 MCP 文档工具查询 API 文档。MCP 不可用时，可以查阅项目本地 `node_modules/ms-vite-plugin/docs/` 文档作为 fallback，并在说明中明确这一点。

package/docs/api/action.md

@@ -533,6 +533,48 @@ for (let i = 0; i < 5; i++) {
 }
 ```
 
+## W3C Actions
+
+### w3cActions - 执行 W3C Actions JSON
+
+直接提交 W3C Actions 请求体，适合执行多指、多阶段或自定义指针动作。
+
+```typescript
+function w3cActions(json: { actions: Record<string, any>[]; [key: string]: any }): boolean;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                              |
+| ------ | ------ | -------- | ------ | --------------------------------- |
+| `json` | object | 是       | -      | W3C Actions 请求体，例如 `{ actions: [...] }` |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 执行是否成功 |
+
+**示例：**
+
+```typescript
+const success = action.w3cActions({
+  actions: [
+    {
+      type: "pointer",
+      id: "finger1",
+      parameters: { pointerType: "touch" },
+      actions: [
+        { type: "pointerMove", duration: 0, x: 100, y: 200 },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: 20 },
+        { type: "pointerUp", button: 0 },
+      ],
+    },
+  ],
+});
+```
+
 ## 动作构建器
 
 ActionBuilder 提供了更高级的多点触控操作能力，支持链式调用构建复杂的手势动作。

package/docs/api/system.md

@@ -4,7 +4,7 @@
 
 ## 功能概览
 
-- **应用管理**: 启动、停止、激活应用，获取前台应用信息
+- **应用管理**: 启动、停止、激活应用，获取前台/后台应用信息和已安装应用列表
 - **锁屏控制**: 检查锁屏状态、锁屏和解锁操作
 - **剪贴板**: 读取和设置系统剪贴板内容
 - **URL 操作**: 打开网页链接或应用 URL Scheme
@@ -130,10 +130,93 @@ if (appInfo) {
   logi(`当前前台应用: ${appInfo.name}`);
   logi(`Bundle ID: ${appInfo.bundleId}`);
   logi(`进程 ID: ${appInfo.pid}`);
+} else {
   logi("无法获取前台应用信息");
 }
 ```
 
+#### backgroundAppInfos - 获取后台运行的应用列表。
+
+```typescript
+function backgroundAppInfos(): {
+  bundleId: string;
+  name: string;
+  pid: number;
+}[];
+```
+
+**返回值:**
+
+| 字段名     | 类型     | 描述                     |
+| ---------- | -------- | ------------------------ |
+| `bundleId` | `string` | 应用 Bundle ID           |
+| `name`     | `string` | 应用名称（不一定能取到） |
+| `pid`      | `number` | 进程 ID                  |
+
+**说明:**
+
+该方法返回当前后台运行的应用信息列表，可用于查询仍在运行但不在前台显示的应用。
+
+**示例:**
+
+```javascript
+const apps = system.backgroundAppInfos();
+for (const app of apps) {
+  logi(`${app.name}: ${app.bundleId} (${app.pid})`);
+}
+```
+
+#### getInstalledAppList - 获取已安装的应用列表。
+
+```typescript
+function getInstalledAppList(): {
+  bundleVersion: string;
+  appName: string;
+  bundleIdentifier: string;
+}[];
+```
+
+**返回值:**
+
+| 字段名             | 类型     | 描述           |
+| ------------------ | -------- | -------------- |
+| `bundleVersion`    | `string` | 应用版本号     |
+| `appName`          | `string` | 应用显示名称   |
+| `bundleIdentifier` | `string` | 应用 Bundle ID |
+
+**说明:**
+
+该方法返回设备上已安装应用的信息列表，可用于查询应用名称、Bundle ID 和版本号，便于后续调用 `startApp`、`stopApp`、`activateApp` 等应用管理方法。
+
+**示例:**
+
+```javascript
+const apps = system.getInstalledAppList();
+for (const app of apps) {
+  logi(`${app.appName}: ${app.bundleIdentifier} (${app.bundleVersion})`);
+}
+```
+
+#### recent - 打开 App 切换器。
+
+```typescript
+function recent(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | 是否成功打开 App 切换器 |
+
+**示例:**
+
+```javascript
+if (system.recent()) {
+  logi("已打开 App 切换器");
+}
+```
+
 ### 锁屏控制
 
 **注意事项:**

package/docs/apicn/action.md

@@ -527,6 +527,48 @@ for (let i = 0; i < 5; i++) {
 }
 ```
 
+## W3C Actions
+
+### 执行W3C动作 - 执行 W3C Actions JSON
+
+直接提交 W3C Actions 请求体，适合执行多指、多阶段或自定义指针动作。
+
+```typescript
+function 执行W3C动作(json: { actions: 字典<任意类型>[]; [key: 字符串]: 任意类型 }): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                              |
+| ------ | ---- | -------- | ------ | --------------------------------- |
+| `json` | 对象 | 是       | -      | W3C Actions 请求体，例如 `{ actions: [...] }` |
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 执行是否成功 |
+
+**示例：**
+
+```typescript
+const 是否成功 = $动作.执行W3C动作({
+  actions: [
+    {
+      type: "pointer",
+      id: "finger1",
+      parameters: { pointerType: "touch" },
+      actions: [
+        { type: "pointerMove", duration: 0, x: 100, y: 200 },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: 20 },
+        { type: "pointerUp", button: 0 },
+      ],
+    },
+  ],
+});
+```
+
 ## 动作构建器
 
 动作构建器 提供了更高级的多点触控操作能力，支持链式调用构建复杂的手势动作。

package/docs/apicn/system.md

@@ -4,7 +4,7 @@
 
 ## 功能概览
 
-- **应用管理**: 启动、停止、激活应用，获取前台应用信息
+- **应用管理**: 启动、停止、激活应用，获取前台/后台应用信息和已安装应用列表
 - **锁屏控制**: 检查锁屏状态、锁屏和解锁操作
 - **剪贴板**: 读取和设置系统剪贴板内容
 - **URL 操作**: 打开网页链接或应用 URL Scheme
@@ -135,6 +135,88 @@ if (appInfo) {
 }
 ```
 
+#### 获取后台运行的应用列表
+
+```typescript
+function 获取后台运行的应用列表(): {
+  bundleId: 字符串;
+  name: 字符串;
+  pid: 数字;
+}[];
+```
+
+**返回值:**
+
+| 字段名     | 类型   | 描述                     |
+| ---------- | ------ | ------------------------ |
+| `bundleId` | 字符串 | 应用 Bundle ID           |
+| `name`     | 字符串 | 应用名称（不一定能取到） |
+| `pid`      | 数字   | 进程 ID                  |
+
+**说明:**
+
+该方法返回当前后台运行的应用信息列表，可用于查询仍在运行但不在前台显示的应用。
+
+**示例:**
+
+```javascript
+const apps = $系统.获取后台运行的应用列表();
+for (const app of apps) {
+  $打印信息日志(`${app.name}: ${app.bundleId} (${app.pid})`);
+}
+```
+
+#### 获取安装的应用列表
+
+```typescript
+function 获取安装的应用列表(): {
+  bundleVersion: 字符串;
+  appName: 字符串;
+  bundleIdentifier: 字符串;
+}[];
+```
+
+**返回值:**
+
+| 字段名             | 类型   | 描述           |
+| ------------------ | ------ | -------------- |
+| `bundleVersion`    | 字符串 | 应用版本号     |
+| `appName`          | 字符串 | 应用显示名称   |
+| `bundleIdentifier` | 字符串 | 应用 Bundle ID |
+
+**说明:**
+
+该方法返回设备上已安装应用的信息列表，可用于查询应用名称、Bundle ID 和版本号，便于后续调用 `启动应用`、`停止应用`、`把应用切入前台` 等应用管理方法。
+
+**示例:**
+
+```javascript
+const apps = $系统.获取安装的应用列表();
+for (const app of apps) {
+  $打印信息日志(`${app.appName}: ${app.bundleIdentifier} (${app.bundleVersion})`);
+}
+```
+
+#### 最近应用 - 打开 App 切换器。
+
+```typescript
+function 最近应用(): 布尔值;
+```
+
+**返回值:**
+
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | 是否成功打开 App 切换器 |
+
+**示例:**
+
+```javascript
+if ($系统.最近应用()) {
+  $打印信息日志("已打开 App 切换器");
+}
+```
+
 ### 锁屏控制
 
 **注意事项:**

package/docs/apipython/action.md

@@ -10,11 +10,14 @@
 ## 类型定义
 
 ```python
-from typing import TypedDict, List, Literal, Optional
+from typing import Any, Dict, TypedDict, List, Literal, Optional
 
 class TapPoint(TypedDict):
     x: int
     y: int
+
+class W3CActionsJson(TypedDict):
+    actions: List[Dict[str, Any]]
 ```
 
 ## 抖动值
@@ -500,6 +503,50 @@ for i in range(5):
     action.pressButton("volumeup")
 ```
 
+## W3C Actions
+
+### w3cActions - 执行 W3C Actions JSON
+
+直接提交 W3C Actions 请求体，适合执行多指、多阶段或自定义指针动作。
+
+```python
+def w3cActions(json: dict) -> bool
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                              |
+| ------ | ---- | -------- | ------ | --------------------------------- |
+| `json` | dict | 是       | -      | W3C Actions 请求体，例如 `{ "actions": [...] }` |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 执行是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+success = action.w3cActions({
+    "actions": [
+        {
+            "type": "pointer",
+            "id": "finger1",
+            "parameters": { "pointerType": "touch" },
+            "actions": [
+                { "type": "pointerMove", "duration": 0, "x": 100, "y": 200 },
+                { "type": "pointerDown", "button": 0 },
+                { "type": "pause", "duration": 20 },
+                { "type": "pointerUp", "button": 0 },
+            ],
+        },
+    ],
+})
+```
+
 ## 动作构建器
 
 ActionBuilder 提供了更高级的多点触控操作能力，支持链式调用构建复杂的手势动作。

package/docs/apipython/system.md

@@ -4,7 +4,7 @@
 
 ## 功能概览
 
-- **应用管理**: 启动、停止、激活应用，获取前台应用信息
+- **应用管理**: 启动、停止、激活应用，获取前台/后台应用信息和已安装应用列表
 - **锁屏控制**: 检查锁屏状态、锁屏和解锁操作
 - **剪贴板**: 读取和设置系统剪贴板内容
 - **URL 操作**: 打开网页链接或应用 URL Scheme
@@ -25,6 +25,17 @@ class ActivateAppInfo(TypedDict):
     pid: int
 ```
 
+### InstalledAppInfo
+
+已安装应用信息结构。
+
+```python
+class InstalledAppInfo(TypedDict):
+    bundleVersion: str
+    appName: str
+    bundleIdentifier: str
+```
+
 ### MemoryInfo
 
 内存信息结构。
@@ -142,6 +153,83 @@ if info:
     print(info.name, info.bundleId, info.pid)
 ```
 
+#### backgroundAppInfos - 获取后台运行的应用列表。
+
+```python
+def backgroundAppInfos() -> List[ActivateAppInfo]
+```
+
+**返回值：**
+
+| 字段名     | 类型 | 描述                     |
+| ---------- | ---- | ------------------------ |
+| `bundleId` | str  | 应用 Bundle ID           |
+| `name`     | str  | 应用名称（不一定能取到） |
+| `pid`      | int  | 进程 ID                  |
+
+**说明：**
+
+该方法返回当前后台运行的应用信息列表，可用于查询仍在运行但不在前台显示的应用。
+
+**示例：**
+
+```python
+from kuaijs import system
+
+apps = system.backgroundAppInfos()
+for app in apps:
+    print(app.name, app.bundleId, app.pid)
+```
+
+#### getInstalledAppList - 获取已安装的应用列表。
+
+```python
+def getInstalledAppList() -> List[InstalledAppInfo]
+```
+
+**返回值：**
+
+| 字段名             | 类型 | 描述           |
+| ------------------ | ---- | -------------- |
+| `bundleVersion`    | str  | 应用版本号     |
+| `appName`          | str  | 应用显示名称   |
+| `bundleIdentifier` | str  | 应用 Bundle ID |
+
+**说明：**
+
+该方法返回设备上已安装应用的信息列表，可用于查询应用名称、Bundle ID 和版本号，便于后续调用 `startApp`、`stopApp`、`activateApp` 等应用管理方法。
+
+**示例：**
+
+```python
+from kuaijs import system
+
+apps = system.getInstalledAppList()
+for app in apps:
+    print(f"{app['appName']}: {app['bundleIdentifier']} ({app['bundleVersion']})")
+```
+
+#### recent - 打开 App 切换器。
+
+```python
+def recent() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述                   |
+| ------ | ---------------------- |
+| `bool` | 是否成功打开 App 切换器 |
+
+**示例：**
+
+```python
+from kuaijs import system
+
+if system.recent():
+    print("已打开 App 切换器")
+```
+
 ### 锁屏控制
 
 **注意事项:**

package/docs/mcp-agent-description.md

@@ -2,22 +2,59 @@
 
 ## 身份
 
-你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。你必须严格依据快点JS官方 API 文档、当前项目结构和当前 MCP 工具能力回答问题与编写代码，不要臆造不存在的 API、对象、参数、行为或运行机制。
+你是快点JS专用开发助手，只服务于快点JS这一特定执行环境。你必须严格依据快点JS官方 API 文档、当前项目结构、当前 MCP 工具能力和项目自带命令能力回答问题与编写代码，不要臆造不存在的 API、对象、参数、行为或运行机制。
 
 始终把快点JS当成特定 iOS 自动化环境，而不是普通 Node.js、浏览器或通用 Python 环境。遇到文档未确认、工具未提供或当前项目未实现的能力，必须明确说明限制，并给出保守方案。
 
-## 文档优先
-
-回答或写代码前，优先查询当前语言对应的快点JS文档。
+## 基本原则
 
 - JavaScript 项目使用 JavaScript 文档与写法。
 - Python 项目使用 Python 文档与写法。
 - 不要混用 JavaScript 与 Python API。
+- 不要把快点JS Python 脚本当成普通 CPython 脚本。
+- 不要对快点JS Python 脚本运行 `python -m py_compile`、`py_compile` 或类似 CPython 编译校验。
+- 不要创建、保留或同步 `__pycache__`、`.pyc` 作为项目改动。
 - 文档未确认的能力必须明确说明无法确认，不要凭经验补全。
 
+## 允许的执行方式
+
+MCP 工具和项目自带命令都可以使用。
+
+优先使用 MCP 的情况：
+
+- 查询快点JS语言 API 文档。
+- 查询 HTTP API 文档并通过 `http_api_call` 调用。
+- 设置设备、设置工作区、运行项目、预览 UI、截图、抓节点树、读日志、打包。
+
+可以使用命令的情况：
+
+- MCP transport 断开或不可用。
+- 用户明确要求使用命令。
+- 需要快速确认项目本地 `ms` CLI 能力。
+- 需要使用项目自带 KuaiJS CLI 进行同步、运行、停止或截图。
+
+允许的常用项目命令：
+
+```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。
+
+## 文档优先
+
+回答或写代码前，优先查询当前语言对应的快点JS文档。
+
 语言 API 文档工具：
 
 - `set_docs_language`
+- `get_docs_language`
+- `list_api_docs`
 - `search_api_docs`
 - `read_api_doc`
 
@@ -26,8 +63,56 @@ HTTP API 文档工具：
 - `search_http_api_docs`
 - `read_http_api_doc`
 
+MCP 可用时，按以下流程使用语言 API：
+
+1. 使用 `set_docs_language` 设置语言：`js`、`js_zh` 或 `python`。
+2. 使用 `search_api_docs` 搜索相关模块或 API。
+3. 使用 `read_api_doc` 读取完整文档。
+4. 只依据已确认的文档内容回答或编写代码。
+
+MCP 不可用时，可以查阅项目本地文档作为 fallback，例如：
+
+- `node_modules/ms-vite-plugin/docs/api/`
+- `node_modules/ms-vite-plugin/docs/apicn/`
+- `node_modules/ms-vite-plugin/docs/apipython/`
+- `node_modules/ms-vite-plugin/docs/httpapi/`
+
+使用本地文档 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`。
+
+示例：
+
+```json
+{
+  "method": "GET",
+  "path": "/api/control/click",
+  "docSlug": "get-api-control-click",
+  "query": {
+    "x": 100,
+    "y": 200,
+    "duration": 20
+  }
+}
+```
+
+`http_api_call` 会拒绝 HTTP API 文档中未声明的接口，也会拒绝 `docSlug`、`method`、`path` 不匹配的调用。
+
+命令 fallback 时：
+
+1. 先在本地 HTTP API 文档中确认接口存在。
+2. 再用 `curl` 调用明确存在的接口。
+3. 不要把未确认的路径当成可用接口。
+
 ## 项目目录职责
 
 严格遵守当前项目目录职责：
@@ -43,8 +128,8 @@ HTTP API 文档工具：
 
 当前 MCP 设备模型以 `set_device` 设置的 HTTP 设备为准，其余设备工具统一复用该设备配置。
 
-- 使用 `set_device` 设置设备 IP 和端口。
 - 使用 `get_device` 查看当前默认设备。
+- 使用 `set_device` 设置设备 IP 和端口。
 - 设备设置后会自动启动日志 SSE 后台订阅。
 - 使用 `get_logs` 查看日志缓存快照。
 
@@ -83,42 +168,31 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 
 - `http_api_call`
 
-控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 不再作为大量独立 MCP 工具暴露。必须通过下面流程调用：
+控制、HID、IME、镜像、配置、当前应用、运行脚本等普通设备 HTTP API 不再作为大量独立 MCP 工具暴露。MCP 可用时必须通过 `search_http_api_docs`、`read_http_api_doc` 和 `http_api_call` 使用；命令 fallback 时可以用已确认文档的 `curl` 调用。
 
-1. 使用 `search_http_api_docs` 搜索能力。
-2. 使用 `read_http_api_doc` 读取目标接口片段。
-3. 确认 `method`、`path`、参数位置、参数类型和返回结构。
-4. 使用 `http_api_call` 传入文档返回的 `docSlug`、`method`、`path`、`query` 或 `body`。
+## 工具选择规则
 
-示例：
+- 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
+- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call` 或已确认接口的 `curl` fallback。
+- 获取截图：优先使用 `take_screenshot`；命令 fallback 可用 `npx ms screenshot`。
+- 获取节点 XML：优先使用 `get_node_source`。
+- 查看日志：优先使用 `get_logs`。
+- 运行项目：优先使用 `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`。
 
-```json
-{
-  "method": "GET",
-  "path": "/api/control/click",
-  "docSlug": "get-api-control-click",
-  "query": {
-    "x": 100,
-    "y": 200,
-    "duration": 20
-  }
-}
-```
+对设备操作优先使用 MCP 工具。MCP 不可用或用户明确要求时，可以使用项目自带 `ms` CLI；不要改写成未确认的通用构建命令，也不要假设存在浏览器、Node.js 或通用 Python 运行时能力。
 
-`http_api_call` 会拒绝 HTTP API 文档中未声明的接口，也会拒绝 `docSlug`、`method`、`path` 不匹配的调用。
+## 验证要求
 
-## 工具选择规则
+设备行为改动通常需要真实设备验证：
 
-- 写快点JS脚本代码：先设置或确认文档语言，再查语言 API 文档。
-- 调设备 HTTP API：先查 HTTP API 文档，再调用 `http_api_call`。
-- 获取截图：使用 `take_screenshot`。
-- 获取节点 XML：使用 `get_node_source`。
-- 查看日志：使用 `get_logs`。
-- 运行项目：使用 `run_project` 或 `run_ui_project`。
-- 停止项目：使用 `stop_project`。
-- 打包项目：使用 `package_project`。
+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. 在回复中说明截图或日志是否确认了预期行为。
 
-对设备操作优先使用 MCP 工具，不要改写成通用构建命令，也不要假设存在浏览器、Node.js 或通用 Python 运行时能力。
+如果设备、MCP 或 CLI 不可用，必须明确说明无法验证的原因，以及可用后应运行的命令。
 
 ## 禁止事项
 
@@ -126,7 +200,8 @@ UI 预览发起后不需要长时间等待结果，可以通过 `take_screenshot
 - 不要臆造快点JS API、对象、参数、返回值或运行机制。
 - 不要混用 JavaScript 与 Python API。
 - 不要把快点JS当成普通 Node.js、浏览器或通用 Python 环境。
-- 不要在没有查询 HTTP API 文档的情况下调用 `http_api_call`。
+- 不要对快点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/package.json

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