@deveco-codegenie/mcp-win32-x64 1.0.1-beta3 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 基于MCP协议，将 HarmonyOS 开发工具链封装为标准 MCP 工具，供 AI 助手调用。
 
----
+***
 
 ## 目录
 
@@ -11,16 +11,15 @@
   - [工程路径配置](#工程路径配置)
 - [主要功能](#主要功能)
   - [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)
+  - [UI 自动化校验](#7-ui-自动化校验-verify_ui-仅-windows--macos)
 - [平台支持](#平台支持)
 
----
+***
 
 ## 配置方式
 
@@ -30,8 +29,8 @@
 
 服务优先读取以下环境变量来定位工具链安装目录：
 
-| 环境变量 | 适用平台 | 说明 |
-|----------|----------|------|
+| 环境变量          | 适用平台            | 说明                        |
+| ------------- | --------------- | ------------------------- |
 | `DEVECO_PATH` | Windows / macOS | DevEco Studio 安装根目录，优先级最高 |
 
 **示例（macOS）：**
@@ -53,19 +52,16 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 服务通过以下方式（按优先级）确定当前 HarmonyOS 项目的根目录：
 
 1. **环境变量** `PROJECT_PATH`：直接指定工程根路径。
-
    ```bash
    export PROJECT_PATH="/path/to/your/harmonyos-project"
    ```
-
 2. **MCP 根目录协议**：服务启动后向 MCP 客户端请求 `roots/list`，取第一个根目录作为工程路径。
 
-
----
+***
 
 ## 主要功能
 
-### 1. ArkTS 代码检查（`check_ets_files`）
+### 1. ArkTS 代码检查 check\_ets\_files
 
 对指定的 `.ets` / `.ts` 文件执行静态诊断，返回语法错误、类型错误等诊断信息。
 
@@ -73,17 +69,42 @@ $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. 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 语言服务通信，收集诊断结果后返回。
+
+**初始化流程：** 检查前会自动验证以下条件：
+1. `compile_commands.json` 是否存在于 `.idea/.deveco/cxx/` 目录下
+2. `compile_commands.json` 是否覆盖待检查的文件路径
+3. 项目中是否存在含 C++ 文件的模块
+
+若不满足上述条件，服务会自动执行 `compileNative` 生成编译数据库。`compile_commands.json` 会合并所有模块下的编译命令信息。
 
-### 2. 构建 HAP/HSP/HAR（`build_project`）
+**支持的文件类型：** `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.h`, `.hh`, `.hpp`, `.hxx`, `.h++`, `.ipp`, `.ixx`, `.inl`, `.inc`, `.tpp`
 
-调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。
+***
+
+### 3. 构建 HAP/HSP/HAR build\_project
+
+调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。为避免日志过长导致超出大模型上下文限制，工具返回的构建日志最多保留最后 50 行。如需查看完整日志，请使用 `logPath` 参数指定日志保存路径。
 
 **工具名称：** `build_project`
 
@@ -93,23 +114,16 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 |------|------|------|------|
 | `module` | `string` | 否 | 指定模块及 Target（如 `entry@default`）；省略则构建整个 APP |
 | `product` | `string` | 否 | 指定 Product 名称（仅构建整个 APP 时有效，与 `module` 互斥） |
-| `buildIntent` | `BuildIntent` | 否 | 构建意图，默认为 `LogVerification` |
+| `buildMode` | `string` | 否 | 构建模式，值为 build-profile.json5 中 buildModeSet 定义的模式的 name 字段（如内置的 'debug'、'release'，或用户自定义的模式名称），默认为 `debug` |
+| `clean` | `boolean` | 否 | 是否在构建前执行 clean 清理构建产物。如果为 true，则会先执行清理然后再进行构建 |
+| `enable_inspector_source_jump` | `boolean` | 否 | 是否启用 ArkUI Inspector 源码跳转功能（对应底层 debugLine 参数）：在构建产物中为系统组件增加源码位置信息，从而支持 ArkUI Inspector 中点击组件跳转到源码位置。不传则使用构建模式默认值 |
 | `logPath` | `string` | 否 | 构建日志保存路径 |
 
-**构建意图（`BuildIntent`）：**
-
-| 枚举值 | 说明 |
-|--------|------|
-| `LogVerification`（默认） | 保留详细运行日志，支持断点调试 |
-| `UIDebug` | 支持获取界面元素与代码位置对应关系 |
-| `PerformanceProfile` | 开启代码优化，保留调试钩子，用于性能调优 |
-| `Release` | 极致压缩混淆，不支持断点调试（包体积最小） |
-
 构建前会自动执行 `ohpm install` 安装依赖。
 
----
+***
 
-### 3. 启动应用（`start_app`）（仅 Windows / macOS）
+### 4. 启动应用 start\_app (仅 Windows / macOS)
 
 在连接的真机或模拟器上安装并启动 HarmonyOS 应用。
 
@@ -117,18 +131,18 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 **参数：**
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `module` | `string` | 模块名称，默认为 `entry` |
-| `target` | `string` | 构建目标，默认为 `default` |
-| `hvd` | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
-| `ability` | `string` | 要启动的 Ability 名称|
+| 参数        | 类型       | 说明                       |
+| --------- | -------- | ------------------------ |
+| `module`  | `string` | 模块名称，默认为 `entry`         |
+| `target`  | `string` | 构建目标，默认为 `default`       |
+| `hvd`     | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
+| `ability` | `string` | 要启动的 Ability 名称          |
 
 支持自动启动未运行的模拟器。
 
----
+***
 
-### 4. UI 树获取（`get_app_ui_tree`）（Windows / macOS）
+### 5. UI 树获取 get\_app\_ui\_tree (Windows / macOS)
 
 抓取设备当前界面的 UI 树信息，保存为 JSON 文件。
 
@@ -136,15 +150,15 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 **参数：**
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `mode` | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
-| `outputDirectory` | `string` | 保存 JSON 文件的目录绝对路径 |
-| `hvd` | `string` | 目标设备名称（单设备时可省略） |
+| 参数                | 类型               | 说明                             |
+| ----------------- | ---------------- | ------------------------------ |
+| `mode`            | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
+| `outputDirectory` | `string`         | 保存 JSON 文件的目录绝对路径              |
+| `hvd`             | `string`         | 目标设备名称（单设备时可省略）                |
 
----
+***
 
-### 5. UI 操作（`perform_ui_action`）（Windows / macOS）
+### 6. UI 操作 perform\_ui\_action (Windows / macOS)
 
 对设备屏幕执行模拟操作。
 
@@ -152,85 +166,124 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
 
 **支持的操作类型（`actionType`）：**
 
-| 操作类型 | 说明 | 主要参数 |
-|----------|------|----------|
-| `click` | 点击指定坐标 | `x`, `y` |
-| `inputText` | 在指定坐标输入文本 | `x`, `y`, `text` |
-| `directionalFling` | 方向滑动 | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
-| `keyEvent` | 模拟按键（支持组合键） | `key1`, `key2`, `key3` |
-| `screenshot` | 截图 | `savePath` |
-
----
-
-### 6. UI 自动化校验（`verifyUI` / `getLog`）（仅 Windows / macOS）
+| 操作类型               | 说明          | 主要参数                                               |
+| ------------------ | ----------- | -------------------------------------------------- |
+| `click`            | 点击指定坐标      | `x`, `y`                                           |
+| `inputText`        | 在指定坐标输入文本   | `x`, `y`, `text`                                   |
+| `directionalFling` | 方向滑动        | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
+| `keyEvent`         | 模拟按键（支持组合键） | `key1`, `key2`, `key3`                             |
+| `screenshot`       | 截图          | `savePath`, `localPath`, `displayId`               |
+
+***
+
+### 7. UI 自动化校验 verify\_ui (仅 Windows / macOS)
+
+基于自然语言测试用例计划，在 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}",
+        "UI_VERIFY_API_KEY": "your-api-key",
+        "UI_VERIFY_BASE_URL": "your-openai-compatible-base-url",
+        "UI_VERIFY_MODEL_NAME": "your-model-name"
+      }
+    }
+  }
+}
+```
 
-基于自然语言测试用例计划，对已安装的应用执行自动化 UI 校验。
+***
 
-**工具名称：** `verifyUI`
+**工具名称：** `verify_ui`（执行 UI 校验）
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `bundleName` | `string` | 待测试应用的包名 |
-| `testPlan` | `string` | 自然语言描述的测试用例计划（包含步骤和预期结果） |
-| `freshStart` | `boolean` | 是否在测试前重新启动应用 |
+| 参数           | 类型        | 必填 | 说明                                         |
+| ------------ | --------- | -- | ------------------------------------------ |
+| `bundleName` | `string`  | 否  | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
+| `testPlan`   | `string`  | 是  | 自然语言描述的测试用例计划，包含每步操作和预期结果                  |
+| `freshStart` | `boolean` | 否  | 是否在测试前重新启动应用，默认 `false`                    |
 
-**工具名称：** `getLog`（获取校验运行日志）
+返回字段：`successPart`（成功步骤描述）、`failPart`（失败步骤描述）、`id`（校验任务 ID，供后续查日志或截图使用）。
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `id` | `string` | 校验任务 ID |
-| `maxLogSize` | `number` | 日志字符数上限，默认 5000，传 -1 不限制 |
-| `searchKeywords` | `string` | 日志搜索关键词，传空字符串获取完整日志 |
+***
 
----
+**工具名称：** `get_ui_verification_log`（获取校验运行日志）
 
-### 7. HiLog 日志采集（Windows / macOS）
+| 参数               | 类型       | 必填 | 说明                       |
+| ---------------- | -------- | -- | ------------------------ |
+| `id`             | `string` | 是  | 校验任务 ID                  |
+| `maxLogSize`     | `number` | 否  | 日志字符数上限，默认 5000，传 -1 不限制 |
+| `searchKeywords` | `string` | 否  | 日志搜索关键词，传空字符串获取完整日志      |
 
-从真机或模拟器实时采集 HiLog 系统日志（或崩溃日志）。
+***
 
-内部通过 `hdc hilog` 命令采集日志，支持多维度过滤：
+**工具名称：** `save_ui_screenshot`（保存校验截图）
 
-| 过滤项 | 说明 |
-|--------|------|
-| `hvd` | 目标设备 |
-| `iscrashLog` | `true` 时采集崩溃日志（faultlog），默认采集普通 hilog |
-| `level` | 日志级别：`D` / `I` / `W` / `E` / `F` |
-| `tag` | 日志标签过滤 |
-| `domain` | 日志领域（如 `0xD002800`） |
-| `bundleName` | 应用包名（自动获取 PID 过滤） |
-| `keyword` | 关键字正则过滤（与 `tag` 互斥） |
-| `logSize` | 日志缓冲区大小，范围 64K–16M，默认 4M |
+| 参数        | 类型       | 必填 | 说明              |
+| --------- | -------- | -- | --------------- |
+| `id`      | `string` | 是  | 校验任务 ID         |
+| `dirname` | `string` | 是  | 截图保存目录（必须为绝对路径） |
 
----
+返回该次校验每步操作的截图文件名列表。
 
-### 8. HarmonyOS 知识库搜索（`harmonyos_knowledge_search`）（Windows / macOS）
+***
 
-调用云端知识库，搜索 HarmonyOS 开发文档。
+**最佳实践：**
 
-**工具名称：** `harmonyos_knowledge_search`
+在 AI 助手中配置好 MCP 后，建议在测试过程中加入以下指引，让 AI 自动串联完整开发测试流程：
 
-**参数：**
+```
+开发完成后，请按以下流程完成验证：
+1. 调用 build_project 编译构建项目
+2. 调用 start_app 将应用安装并启动到设备
+3. 调用 verify_ui 执行功能验证，用自然语言描述测试步骤和预期结果
+4. 若验证失败，根据 failPart 描述定位问题，修复后重新执行上述流程，直到验证通过
+5. 如需查看详细日志，使用 get_ui_verification_log 获取运行日志
+6. 如需查看每步截图，使用 save_ui_screenshot 将截图保存到本地目录
+```
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `keywords` | `string[]` | 搜索关键词列表 |
-| `maxCharSize` | `number` | 最大返回字符数，默认 5000 |
+***
 
-支持搜索：API 参考、开发指南、最佳实践、常见问题、版本变更说明。
+## 平台支持
 
----
+| 功能             | Windows | macOS |
+| -------------- | :-----: | :---: |
+| ArkTS 代码检查     |    ✅    |   ✅   |
+| C/C++ 代码检查     |    ✅    |   ✅   |
+| 构建 HAP/HSP/HAR |    ✅    |   ✅   |
+| 启动应用           |    ✅    |   ✅   |
+| UI 树获取         |    ✅    |   ✅   |
+| UI 操作          |    ✅    |   ✅   |
+| UI 自动化校验       |    ✅    |   ✅   |
 
-## 平台支持
+***
 
-| 功能 | Windows | macOS |
-|------|:-------:|:-----:|
-| ArkTS 代码检查 | ✅ | ✅ |
-| 构建 HAP/HSP/HAR | ✅ | ✅ |
-| 启动应用 | ✅ | ✅ |
-| UI 树获取 | ✅ | ✅ |
-| UI 操作 | ✅ | ✅ |
-| UI 自动化校验 | ✅ | ✅ |
-| HiLog 日志采集 | ✅ | ✅ |
-| 知识库搜索 | ✅ | ✅ |
-
----