@deveco-codegenie/mcp-win32-x64 0.1.8 → 0.2.3-beta

package/README.md

@@ -11,13 +11,16 @@
   - [工程路径配置](#工程路径配置)
 - [主要功能](#主要功能)
   - [ArkTS 代码检查](#1-arkts-代码检查-check_ets_files)
-  - [构建 HAP/HSP/HAR](#2-构建-haphsphar-build_project)
-  - [启动应用](#3-启动应用-start_app仅-windows--macos)
-  - [UI 树获取](#4-ui-树获取-get_app_ui_treewindows--macos)
-  - [UI 操作](#5-ui-操作-perform_ui_actionwindows--macos)
-  - [UI 自动化校验](#6-ui-自动化校验-verifyui--getlog仅-windows--macos)
-  - [HiLog 日志采集](#7-hilog-日志采集windows--macos)
-  - [HarmonyOS 知识库搜索](#8-harmonyos-知识库搜索-harmonyos_knowledge_searchwindows--macos)
+  - [C/C++ 代码检查](#2-c代码检查-check_cpp_files)
+  - [构建 HAP/HSP/HAR](#3-构建-haphsphar-build_project)
+  - [启动应用](#4-启动应用-start_app-仅-windows--macos)
+  - [UI 树获取](#5-ui-树获取-get_app_ui_tree-windows--macos)
+  - [UI 操作](#6-ui-操作-perform_ui_action-windows--macos)
+  - [HiLog 日志采集](#7-hilog-日志采集-windows--macos)
+  - [HarmonyOS 知识库搜索](#8-harmonyos-知识库搜索-harmonyos_knowledge_search-windows--macos)
+  - [UI 自动化校验](#9-ui-自动化校验-verify_ui-仅-windows--macos)
+  - [项目同步](#10-项目同步-project_sync)
+  - [初始化工程路径](#11-初始化工程路径-init_project_path)
 - [平台支持](#平台支持)
 
 ---
@@ -60,12 +63,31 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 2. **MCP 根目录协议**：服务启动后向 MCP 客户端请求 `roots/list`，取第一个根目录作为工程路径。
 
+### 工具组配置
+
+服务将工具分为 **默认工具组** 和 **额外工具组**。默认工具组在服务启动时自动加载，而额外工具组需要通过环境变量显式激活。
+
+| 环境变量 | 说明 | 示例 |
+|----------|------|------|
+| `ADDITIONAL_TOOL_GROUPS` | 激活额外的工具组（逗号分隔） | `ui_integration_test,emulator_manager` |
+
+**默认加载的工具：**
+- ArkTS 代码检查、构建、同步
+- 启动应用、UI 树获取、UI 操作（仅限 Windows/macOS）
+- HiLog 日志采集、知识库搜索（仅限 Windows/macOS）
+
+**可选激活的额外工具组：**
+
+| 工具组名称 | 包含的工具 | 适用场景 |
+|------------|------------|----------|
+| `ui_integration_test` | `verify_ui`, `get_ui_verification_log`, `save_ui_screenshot` | 执行 UI 自动化脚本和意图校验 |
+| `emulator_manager` | `emulator_image_manager`,`emulator_management` | 管理模拟器镜像和实例 |
 
 ---
 
 ## 主要功能
 
-### 1. ArkTS 代码检查（`check_ets_files`）
+### 1. ArkTS 代码检查 check_ets_files
 
 对指定的 `.ets` / `.ts` 文件执行静态诊断，返回语法错误、类型错误等诊断信息。
 
@@ -75,13 +97,31 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `files` | `string[]` | 待检查的 ETS 文件路径列表 |
+| `files` | `string[]` | 待检查 ETS 文件路径列表 |
 
 **实现原理：** 服务内嵌 arkts-lang-server JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 ArkTS 语言服务通信，收集诊断结果后返回。
 
 ---
 
-### 2. 构建 HAP/HSP/HAR（`build_project`）
+### 2. C/C++ 代码检查 check_cpp_files
+
+对传入的 C/C++ 文件进行静态语法检查并返回 clangd 诊断信息。
+
+**工具名称：** `check_cpp_files`
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `files` | `string[]` | 待检查的 C/C++ 文件路径列表，格式为 `["file1.cpp","file2.hpp",...]` |
+
+**实现原理：** 服务内嵌 clangd LSP wrapper JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 clangd 语言服务通信，收集诊断结果后返回。需要项目根目录下存在 `compile_commands.json` 文件。
+
+**支持的文件类型：** `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.h`, `.hh`, `.hpp`, `.hxx`, `.h++`, `.ipp`, `.ixx`, `.inl`, `.inc`, `.tpp`
+
+---
+
+### 3. 构建 HAP/HSP/HAR build_project
 
 调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。
 
@@ -109,7 +149,7 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 ---
 
-### 3. 启动应用（`start_app`）（仅 Windows / macOS）
+### 3. 启动应用 start_app (仅 Windows / macOS)
 
 在连接的真机或模拟器上安装并启动 HarmonyOS 应用。
 
@@ -128,7 +168,7 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 ---
 
-### 4. UI 树获取（`get_app_ui_tree`）（Windows / macOS）
+### 4. UI 树获取 get_app_ui_tree (Windows / macOS)
 
 抓取设备当前界面的 UI 树信息，保存为 JSON 文件。
 
@@ -144,7 +184,7 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 ---
 
-### 5. UI 操作（`perform_ui_action`）（Windows / macOS）
+### 5. UI 操作 perform_ui_action (Windows / macOS)
 
 对设备屏幕执行模拟操作。
 
@@ -162,29 +202,7 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 ---
 
-### 6. UI 自动化校验（`verifyUI` / `getLog`）（仅 Windows / macOS）
-
-基于自然语言测试用例计划，对已安装的应用执行自动化 UI 校验。
-
-**工具名称：** `verifyUI`
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `bundleName` | `string` | 待测试应用的包名 |
-| `testPlan` | `string` | 自然语言描述的测试用例计划（包含步骤和预期结果） |
-| `freshStart` | `boolean` | 是否在测试前重新启动应用 |
-
-**工具名称：** `getLog`（获取校验运行日志）
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `id` | `string` | 校验任务 ID |
-| `maxLogSize` | `number` | 日志字符数上限，默认 5000，传 -1 不限制 |
-| `searchKeywords` | `string` | 日志搜索关键词，传空字符串获取完整日志 |
-
----
-
-### 7. HiLog 日志采集（Windows / macOS）
+### 6. HiLog 日志采集 (Windows / macOS)
 
 从真机或模拟器实时采集 HiLog 系统日志（或崩溃日志）。
 
@@ -199,11 +217,10 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 | `domain` | 日志领域（如 `0xD002800`） |
 | `bundleName` | 应用包名（自动获取 PID 过滤） |
 | `keyword` | 关键字正则过滤（与 `tag` 互斥） |
-| `logSize` | 日志缓冲区大小，范围 64K–16M，默认 4M |
 
 ---
 
-### 8. HarmonyOS 知识库搜索（`harmonyos_knowledge_search`）（Windows / macOS）
+### 7. HarmonyOS 知识库搜索 harmonyos_knowledge_search (Windows / macOS)
 
 调用云端知识库，搜索 HarmonyOS 开发文档。
 
@@ -220,17 +237,149 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 ---
 
+### 8. UI 自动化校验 verify_ui (仅 Windows / macOS)
+
+> **注意**：此功能属于额外工具组，需设置环境变量 `ADDITIONAL_TOOL_GROUPS=ui_integration_test` 才能开启。
+
+基于自然语言测试用例计划，在 HarmonyOS 设备上自动执行 UI 操作并验证结果。
+
+**功能特性：**
+
+- **自然语言驱动**：用中文描述测试步骤，无需编写代码
+- **智能 UI 识别**：基于 AI 视觉分析自动识别界面元素
+- **多种操作支持**：点击、滑动、输入文本、长按、启动应用等
+- **实时截图验证**：每步操作后自动截图验证是否成功
+- **截图保存**：可将每步截图保存到本地，便于复盘问题
+- **日志记录**：详细的测试过程日志，便于问题排查
+
+**环境要求：**
+
+需配置以下环境变量以连接 AI 视觉模型服务（需支持 Function Call，如阿里云百炼 Qwen3-VL）：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `UI_VERIFY_BASE_URL` | OpenAI 兼容接口地址 |
+| `UI_VERIFY_API_KEY` | API Key |
+| `UI_VERIFY_MODEL_NAME` | 模型名称（需支持视觉理解和 Function Call） |
+
+**MCP 配置示例：**
+
+```json
+{
+  "mcpServers": {
+    "deveco-mcp": {
+      "command": "cmd",
+      "args": [
+        "/C",
+        "path/to/mcp-server.exe"
+      ],
+      "env": {
+        "DEVECO_PATH": "path/to/DevEco Studio",
+        "PROJECT_PATH": "${workspaceFolder}",
+        "ADDITIONAL_TOOL_GROUPS": "ui_integration_test",
+        "UI_VERIFY_API_KEY": "your-api-key",
+        "UI_VERIFY_BASE_URL": "your-openai-compatible-base-url",
+        "UI_VERIFY_MODEL_NAME": "your-model-name"
+      }
+    }
+  }
+}
+```
+
+---
+
+**工具名称：** `verify_ui`（执行 UI 校验）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `bundleName` | `string` | 否 | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
+| `testPlan` | `string` | 是 | 自然语言描述的测试用例计划，包含每步操作和预期结果 |
+| `freshStart` | `boolean` | 否 | 是否在测试前重新启动应用，默认 `false` |
+
+返回字段：`successPart`（成功步骤描述）、`failPart`（失败步骤描述）、`id`（校验任务 ID，供后续查日志或截图使用）。
+
+---
+
+**工具名称：** `get_ui_verification_log`（获取校验运行日志）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 校验任务 ID |
+| `maxLogSize` | `number` | 否 | 日志字符数上限，默认 5000，传 -1 不限制 |
+| `searchKeywords` | `string` | 否 | 日志搜索关键词，传空字符串获取完整日志 |
+
+---
+
+**工具名称：** `save_ui_screenshot`（保存校验截图）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 校验任务 ID |
+| `dirname` | `string` | 是 | 截图保存目录（必须为绝对路径） |
+
+返回该次校验每步操作的截图文件名列表。
+
+---
+
+### 9. 项目同步 project_sync
+
+执行项目同步。包含 ohpm install 依赖安装和 hvigor 工程同步。通常在项目初始化或修改依赖配置后使用。
+
+**工具名称：** `project_sync`
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `product` | `string` | 否 | 指定的 Product 名称。如果不传，默认为 'default'。 |
+| `skip_ohpm_install` | `boolean` | 否 | 是否跳过 ohpm install。若环境中已安装依赖或遇到文件锁冲突,可设为 true。 |
+| `log_path` | `string` | 否 | sync 日志保存路径：若指定，则将所有的同步日志保存到该路径下。 |
+
+---
+
+### 10. 初始化工程路径 init_project_path
+
+当依赖工程路径的工具（如 ArkTS 代码检查、构建、sync等）因未配置工程路径而执行失败时，调用此工具来初始化或更新工程根目录路径。
+
+**工具名称：** `init_project_path`
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `project_path` | `string` | 是 | 工程根目录的绝对路径 |
+
+---
+
+**最佳实践：**
+
+在 AI 助手中配置好 MCP 后，建议在测试过程中加入以下指引，让 AI 自动串联完整开发测试流程：
+
+```
+开发完成后，请按以下流程完成验证：
+1. 调用 build_project 编译构建项目
+2. 调用 start_app 将应用安装并启动到设备
+3. 调用 verify_ui 执行功能验证，用自然语言描述测试步骤和预期结果
+4. 若验证失败，根据 failPart 描述定位问题，修复后重新执行上述流程，直到验证通过
+5. 如需查看详细日志，使用 get_ui_verification_log 获取运行日志
+6. 如需查看每步截图，使用 save_ui_screenshot 将截图保存到本地目录
+```
+
+---
+
+
 ## 平台支持
 
 | 功能 | Windows | macOS |
 |------|:-------:|:-----:|
 | ArkTS 代码检查 | ✅ | ✅ |
+| C/C++ 代码检查 | ✅ | ✅ |
 | 构建 HAP/HSP/HAR | ✅ | ✅ |
 | 启动应用 | ✅ | ✅ |
 | UI 树获取 | ✅ | ✅ |
 | UI 操作 | ✅ | ✅ |
-| UI 自动化校验 | ✅ | ✅ |
 | HiLog 日志采集 | ✅ | ✅ |
 | 知识库搜索 | ✅ | ✅ |
+| UI 自动化校验 | ✅ | ✅ |
 
 ---