@deveco-codegenie/mcp-darwin-x64 0.2.5 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +174 -85
  2. package/THIRD_PARTY_LICENSES.md +1240 -1220
  3. package/bin/codegenie-mcp-server +0 -0
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  基于MCP协议，将 HarmonyOS 开发工具链封装为标准 MCP 工具，供 AI 助手调用。
4
4
 
5
- ***
5
+ ---
6
6
 
7
7
  ## 目录
8
8
 
@@ -16,10 +16,14 @@
16
16
  - [启动应用](#4-启动应用-start_app-仅-windows--macos)
17
17
  - [UI 树获取](#5-ui-树获取-get_app_ui_tree-windows--macos)
18
18
  - [UI 操作](#6-ui-操作-perform_ui_action-windows--macos)
19
- - [UI 自动化校验](#7-ui-自动化校验-verify_ui-仅-windows--macos)
19
+ - [HiLog 日志采集](#7-hilog-日志采集-windows--macos)
20
+ - [HarmonyOS 知识库搜索](#8-harmonyos-知识库搜索-harmonyos_knowledge_search-windows--macos)
21
+ - [UI 自动化校验](#9-ui-自动化校验-verify_ui-仅-windows--macos)
22
+ - [项目同步](#10-项目同步-project_sync)
23
+ - [初始化工程路径](#11-初始化工程路径-init_project_path)
20
24
  - [平台支持](#平台支持)
21
25
 
22
- ***
26
+ ---
23
27
 
24
28
  ## 配置方式
25
29
 
@@ -29,8 +33,8 @@
29
33
 
30
34
  服务优先读取以下环境变量来定位工具链安装目录：
31
35
 
32
- | 环境变量 | 适用平台 | 说明 |
33
- | ------------- | --------------- | ------------------------- |
36
+ | 环境变量 | 适用平台 | 说明 |
37
+ |----------|----------|------|
34
38
  | `DEVECO_PATH` | Windows / macOS | DevEco Studio 安装根目录，优先级最高 |
35
39
 
36
40
  **示例（macOS）：**
@@ -52,16 +56,38 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
52
56
  服务通过以下方式（按优先级）确定当前 HarmonyOS 项目的根目录：
53
57
 
54
58
  1. **环境变量** `PROJECT_PATH`：直接指定工程根路径。
59
+
55
60
  ```bash
56
61
  export PROJECT_PATH="/path/to/your/harmonyos-project"
57
62
  ```
63
+
58
64
  2. **MCP 根目录协议**：服务启动后向 MCP 客户端请求 `roots/list`，取第一个根目录作为工程路径。
59
65
 
60
- ***
66
+ ### 工具组配置
67
+
68
+ 服务将工具分为 **默认工具组** 和 **额外工具组**。默认工具组在服务启动时自动加载，而额外工具组需要通过环境变量显式激活。
69
+
70
+ | 环境变量 | 说明 | 示例 |
71
+ |----------|------|------|
72
+ | `ADDITIONAL_TOOL_GROUPS` | 激活额外的工具组（逗号分隔） | `ui_integration_test,emulator_manager` |
73
+
74
+ **默认加载的工具：**
75
+ - ArkTS 代码检查、构建、同步
76
+ - 启动应用、UI 树获取、UI 操作（仅限 Windows/macOS）
77
+ - HiLog 日志采集、知识库搜索（仅限 Windows/macOS）
78
+
79
+ **可选激活的额外工具组：**
80
+
81
+ | 工具组名称 | 包含的工具 | 适用场景 |
82
+ |------------|------------|----------|
83
+ | `ui_integration_test` | `verify_ui`, `get_ui_verification_log`, `save_ui_screenshot` | 执行 UI 自动化脚本和意图校验 |
84
+ | `emulator_manager` | `emulator_image_manager`,`emulator_management` | 管理模拟器镜像和实例 |
85
+
86
+ ---
61
87
 
62
88
  ## 主要功能
63
89
 
64
- ### 1. ArkTS 代码检查 check\_ets\_files
90
+ ### 1. ArkTS 代码检查 check_ets_files
65
91
 
66
92
  对指定的 `.ets` / `.ts` 文件执行静态诊断，返回语法错误、类型错误等诊断信息。
67
93
 
@@ -69,15 +95,15 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
69
95
 
70
96
  **参数：**
71
97
 
72
- | 参数 | 类型 | 说明 |
73
- | ------- | ---------- | -------------- |
98
+ | 参数 | 类型 | 说明 |
99
+ |------|------|------|
74
100
  | `files` | `string[]` | 待检查 ETS 文件路径列表 |
75
101
 
76
102
  **实现原理：** 服务内嵌 arkts-lang-server JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 ArkTS 语言服务通信，收集诊断结果后返回。
77
103
 
78
- ***
104
+ ---
79
105
 
80
- ### 2. C/C++ 代码检查 check\_cpp\_files
106
+ ### 2. C/C++ 代码检查 check_cpp_files
81
107
 
82
108
  对传入的 C/C++ 文件进行静态语法检查并返回 clangd 诊断信息。
83
109
 
@@ -85,26 +111,19 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
85
111
 
86
112
  **参数：**
87
113
 
88
- | 参数 | 类型 | 说明 |
89
- | ------- | ---------- | ----------------------------------------------------- |
114
+ | 参数 | 类型 | 说明 |
115
+ |------|------|------|
90
116
  | `files` | `string[]` | 待检查的 C/C++ 文件路径列表，格式为 `["file1.cpp","file2.hpp",...]` |
91
117
 
92
- **实现原理：** 服务内嵌 clangd LSP wrapper JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 clangd 语言服务通信，收集诊断结果后返回。
93
-
94
- **初始化流程：** 检查前会自动验证以下条件：
95
- 1. `compile_commands.json` 是否存在于 `.idea/.deveco/cxx/` 目录下
96
- 2. `compile_commands.json` 是否覆盖待检查的文件路径
97
- 3. 项目中是否存在含 C++ 文件的模块
98
-
99
- 若不满足上述条件，服务会自动执行 `compileNative` 生成编译数据库。`compile_commands.json` 会合并所有模块下的编译命令信息。
118
+ **实现原理：** 服务内嵌 clangd LSP wrapper JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 clangd 语言服务通信，收集诊断结果后返回。需要项目根目录下存在 `compile_commands.json` 文件。
100
119
 
101
120
  **支持的文件类型：** `.c`, `.cc`, `.cpp`, `.cxx`, `.c++`, `.h`, `.hh`, `.hpp`, `.hxx`, `.h++`, `.ipp`, `.ixx`, `.inl`, `.inc`, `.tpp`
102
121
 
103
- ***
122
+ ---
104
123
 
105
- ### 3. 构建 HAP/HSP/HAR build\_project
124
+ ### 3. 构建 HAP/HSP/HAR build_project
106
125
 
107
- 调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。为避免日志过长导致超出大模型上下文限制，工具返回的构建日志最多保留最后 50 行。如需查看完整日志，请使用 `logPath` 参数指定日志保存路径。
126
+ 调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。
108
127
 
109
128
  **工具名称：** `build_project`
110
129
 
@@ -121,9 +140,9 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
121
140
 
122
141
  构建前会自动执行 `ohpm install` 安装依赖。
123
142
 
124
- ***
143
+ ---
125
144
 
126
- ### 4. 启动应用 start\_app (仅 Windows / macOS)
145
+ ### 3. 启动应用 start_app (仅 Windows / macOS)
127
146
 
128
147
  在连接的真机或模拟器上安装并启动 HarmonyOS 应用。
129
148
 
@@ -131,18 +150,18 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
131
150
 
132
151
  **参数：**
133
152
 
134
- | 参数 | 类型 | 说明 |
135
- | --------- | -------- | ------------------------ |
136
- | `module` | `string` | 模块名称，默认为 `entry` |
137
- | `target` | `string` | 构建目标，默认为 `default` |
138
- | `hvd` | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
139
- | `ability` | `string` | 要启动的 Ability 名称 |
153
+ | 参数 | 类型 | 说明 |
154
+ |------|------|------|
155
+ | `module` | `string` | 模块名称，默认为 `entry` |
156
+ | `target` | `string` | 构建目标，默认为 `default` |
157
+ | `hvd` | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
158
+ | `ability` | `string` | 要启动的 Ability 名称|
140
159
 
141
160
  支持自动启动未运行的模拟器。
142
161
 
143
- ***
162
+ ---
144
163
 
145
- ### 5. UI 树获取 get\_app\_ui\_tree (Windows / macOS)
164
+ ### 4. UI 树获取 get_app_ui_tree (Windows / macOS)
146
165
 
147
166
  抓取设备当前界面的 UI 树信息，保存为 JSON 文件。
148
167
 
@@ -150,15 +169,15 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
150
169
 
151
170
  **参数：**
152
171
 
153
- | 参数 | 类型 | 说明 |
154
- | ----------------- | ---------------- | ------------------------------ |
155
- | `mode` | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
156
- | `outputDirectory` | `string` | 保存 JSON 文件的目录绝对路径 |
157
- | `hvd` | `string` | 目标设备名称（单设备时可省略） |
172
+ | 参数 | 类型 | 说明 |
173
+ |------|------|------|
174
+ | `mode` | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
175
+ | `outputDirectory` | `string` | 保存 JSON 文件的目录绝对路径 |
176
+ | `hvd` | `string` | 目标设备名称（单设备时可省略） |
158
177
 
159
- ***
178
+ ---
160
179
 
161
- ### 6. UI 操作 perform\_ui\_action (Windows / macOS)
180
+ ### 5. UI 操作 perform_ui_action (Windows / macOS)
162
181
 
163
182
  对设备屏幕执行模拟操作。
164
183
 
@@ -166,17 +185,54 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
166
185
 
167
186
  **支持的操作类型（`actionType`）：**
168
187
 
169
- | 操作类型 | 说明 | 主要参数 |
170
- | ------------------ | ----------- | -------------------------------------------------- |
171
- | `click` | 点击指定坐标 | `x`, `y` |
172
- | `inputText` | 在指定坐标输入文本 | `x`, `y`, `text` |
173
- | `directionalFling` | 方向滑动 | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
174
- | `keyEvent` | 模拟按键（支持组合键） | `key1`, `key2`, `key3` |
175
- | `screenshot` | 截图 | `savePath`, `localPath`, `displayId` |
188
+ | 操作类型 | 说明 | 主要参数 |
189
+ |----------|------|----------|
190
+ | `click` | 点击指定坐标 | `x`, `y` |
191
+ | `inputText` | 在指定坐标输入文本 | `x`, `y`, `text` |
192
+ | `directionalFling` | 方向滑动 | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
193
+ | `keyEvent` | 模拟按键（支持组合键） | `key1`, `key2`, `key3` |
194
+ | `screenshot` | 截图 | `savePath` |
195
+
196
+ ---
197
+
198
+ ### 6. HiLog 日志采集 (Windows / macOS)
199
+
200
+ 从真机或模拟器实时采集 HiLog 系统日志（或崩溃日志）。
176
201
 
177
- ***
202
+ 内部通过 `hdc hilog` 命令采集日志，支持多维度过滤：
178
203
 
179
- ### 7. UI 自动化校验 verify\_ui (仅 Windows / macOS)
204
+ | 过滤项 | 说明 |
205
+ |--------|------|
206
+ | `hvd` | 目标设备 |
207
+ | `iscrashLog` | `true` 时采集崩溃日志（faultlog），默认采集普通 hilog |
208
+ | `level` | 日志级别：`D` / `I` / `W` / `E` / `F` |
209
+ | `tag` | 日志标签过滤 |
210
+ | `domain` | 日志领域（如 `0xD002800`） |
211
+ | `bundleName` | 应用包名（自动获取 PID 过滤） |
212
+ | `keyword` | 关键字正则过滤（与 `tag` 互斥） |
213
+
214
+ ---
215
+
216
+ ### 7. HarmonyOS 知识库搜索 harmonyos_knowledge_search (Windows / macOS)
217
+
218
+ 调用云端知识库，搜索 HarmonyOS 开发文档。
219
+
220
+ **工具名称：** `harmonyos_knowledge_search`
221
+
222
+ **参数：**
223
+
224
+ | 参数 | 类型 | 说明 |
225
+ |------|------|------|
226
+ | `keywords` | `string[]` | 搜索关键词列表 |
227
+ | `maxCharSize` | `number` | 最大返回字符数，默认 5000 |
228
+
229
+ 支持搜索：API 参考、开发指南、最佳实践、常见问题、版本变更说明。
230
+
231
+ ---
232
+
233
+ ### 8. UI 自动化校验 verify_ui (仅 Windows / macOS)
234
+
235
+ > **注意**：此功能属于额外工具组，需设置环境变量 `ADDITIONAL_TOOL_GROUPS=ui_integration_test` 才能开启。
180
236
 
181
237
  基于自然语言测试用例计划，在 HarmonyOS 设备上自动执行 UI 操作并验证结果。
182
238
 
@@ -193,10 +249,10 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
193
249
 
194
250
  需配置以下环境变量以连接 AI 视觉模型服务（需支持 Function Call，如阿里云百炼 Qwen3-VL）：
195
251
 
196
- | 环境变量 | 说明 |
197
- | ---------------------- | ---------------------------- |
198
- | `UI_VERIFY_BASE_URL` | OpenAI 兼容接口地址 |
199
- | `UI_VERIFY_API_KEY` | API Key |
252
+ | 环境变量 | 说明 |
253
+ |----------|------|
254
+ | `UI_VERIFY_BASE_URL` | OpenAI 兼容接口地址 |
255
+ | `UI_VERIFY_API_KEY` | API Key |
200
256
  | `UI_VERIFY_MODEL_NAME` | 模型名称（需支持视觉理解和 Function Call） |
201
257
 
202
258
  **MCP 配置示例：**
@@ -213,6 +269,7 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
213
269
  "env": {
214
270
  "DEVECO_PATH": "path/to/DevEco Studio",
215
271
  "PROJECT_PATH": "${workspaceFolder}",
272
+ "ADDITIONAL_TOOL_GROUPS": "ui_integration_test",
216
273
  "UI_VERIFY_API_KEY": "your-api-key",
217
274
  "UI_VERIFY_BASE_URL": "your-openai-compatible-base-url",
218
275
  "UI_VERIFY_MODEL_NAME": "your-model-name"
@@ -222,40 +279,70 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
222
279
  }
223
280
  ```
224
281
 
225
- ***
282
+ ---
226
283
 
227
284
  **工具名称：** `verify_ui`（执行 UI 校验）
228
285
 
229
- | 参数 | 类型 | 必填 | 说明 |
230
- | ------------ | --------- | -- | ------------------------------------------ |
231
- | `bundleName` | `string` | 否 | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
232
- | `testPlan` | `string` | 是 | 自然语言描述的测试用例计划，包含每步操作和预期结果 |
233
- | `freshStart` | `boolean` | 否 | 是否在测试前重新启动应用，默认 `false` |
286
+ | 参数 | 类型 | 必填 | 说明 |
287
+ |------|------|------|------|
288
+ | `bundleName` | `string` | 否 | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
289
+ | `testPlan` | `string` | 是 | 自然语言描述的测试用例计划，包含每步操作和预期结果 |
290
+ | `freshStart` | `boolean` | 否 | 是否在测试前重新启动应用，默认 `false` |
234
291
 
235
292
  返回字段：`successPart`（成功步骤描述）、`failPart`（失败步骤描述）、`id`（校验任务 ID，供后续查日志或截图使用）。
236
293
 
237
- ***
294
+ ---
238
295
 
239
296
  **工具名称：** `get_ui_verification_log`（获取校验运行日志）
240
297
 
241
- | 参数 | 类型 | 必填 | 说明 |
242
- | ---------------- | -------- | -- | ------------------------ |
243
- | `id` | `string` | 是 | 校验任务 ID |
244
- | `maxLogSize` | `number` | 否 | 日志字符数上限，默认 5000，传 -1 不限制 |
245
- | `searchKeywords` | `string` | 否 | 日志搜索关键词，传空字符串获取完整日志 |
298
+ | 参数 | 类型 | 必填 | 说明 |
299
+ |------|------|------|------|
300
+ | `id` | `string` | 是 | 校验任务 ID |
301
+ | `maxLogSize` | `number` | 否 | 日志字符数上限，默认 5000，传 -1 不限制 |
302
+ | `searchKeywords` | `string` | 否 | 日志搜索关键词，传空字符串获取完整日志 |
246
303
 
247
- ***
304
+ ---
248
305
 
249
306
  **工具名称：** `save_ui_screenshot`（保存校验截图）
250
307
 
251
- | 参数 | 类型 | 必填 | 说明 |
252
- | --------- | -------- | -- | --------------- |
253
- | `id` | `string` | 是 | 校验任务 ID |
254
- | `dirname` | `string` | 是 | 截图保存目录（必须为绝对路径） |
308
+ | 参数 | 类型 | 必填 | 说明 |
309
+ |------|------|------|------|
310
+ | `id` | `string` | 是 | 校验任务 ID |
311
+ | `dirname` | `string` | 是 | 截图保存目录（必须为绝对路径） |
255
312
 
256
313
  返回该次校验每步操作的截图文件名列表。
257
314
 
258
- ***
315
+ ---
316
+
317
+ ### 9. 项目同步 project_sync
318
+
319
+ 执行项目同步。包含 ohpm install 依赖安装和 hvigor 工程同步。通常在项目初始化或修改依赖配置后使用。
320
+
321
+ **工具名称：** `project_sync`
322
+
323
+ **参数：**
324
+
325
+ | 参数 | 类型 | 必填 | 说明 |
326
+ |------|------|------|------|
327
+ | `product` | `string` | 否 | 指定的 Product 名称。如果不传，默认为 'default'。 |
328
+ | `skip_ohpm_install` | `boolean` | 否 | 是否跳过 ohpm install。若环境中已安装依赖或遇到文件锁冲突,可设为 true。 |
329
+ | `log_path` | `string` | 否 | sync 日志保存路径：若指定，则将所有的同步日志保存到该路径下。 |
330
+
331
+ ---
332
+
333
+ ### 10. 初始化工程路径 init_project_path
334
+
335
+ 当依赖工程路径的工具（如 ArkTS 代码检查、构建、sync等）因未配置工程路径而执行失败时，调用此工具来初始化或更新工程根目录路径。
336
+
337
+ **工具名称：** `init_project_path`
338
+
339
+ **参数：**
340
+
341
+ | 参数 | 类型 | 必填 | 说明 |
342
+ |------|------|------|------|
343
+ | `project_path` | `string` | 是 | 工程根目录的绝对路径 |
344
+
345
+ ---
259
346
 
260
347
  **最佳实践：**
261
348
 
@@ -271,19 +358,21 @@ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
271
358
  6. 如需查看每步截图，使用 save_ui_screenshot 将截图保存到本地目录
272
359
  ```
273
360
 
274
- ***
361
+ ---
275
362
 
276
- ## 平台支持
277
-
278
- | 功能 | Windows | macOS |
279
- | -------------- | :-----: | :---: |
280
- | ArkTS 代码检查 | ✅ | ✅ |
281
- | C/C++ 代码检查 | ✅ | ✅ |
282
- | 构建 HAP/HSP/HAR | ✅ | ✅ |
283
- | 启动应用 | ✅ | ✅ |
284
- | UI 树获取 | ✅ | ✅ |
285
- | UI 操作 | ✅ | ✅ |
286
- | UI 自动化校验 | ✅ | ✅ |
287
363
 
288
- ***
364
+ ## 平台支持
289
365
 
366
+ | 功能 | Windows | macOS |
367
+ |------|:-------:|:-----:|
368
+ | ArkTS 代码检查 | ✅ | ✅ |
369
+ | C/C++ 代码检查 | ✅ | ✅ |
370
+ | 构建 HAP/HSP/HAR | ✅ | ✅ |
371
+ | 启动应用 | ✅ | ✅ |
372
+ | UI 树获取 | ✅ | ✅ |
373
+ | UI 操作 | ✅ | ✅ |
374
+ | HiLog 日志采集 | ✅ | ✅ |
375
+ | 知识库搜索 | ✅ | ✅ |
376
+ | UI 自动化校验 | ✅ | ✅ |
377
+
378
+ ---