1# aa工具 2 3Ability assistant（Ability助手，简称为aa），是用于启动应用和启动测试用例的工具，为开发者提供基本的应用调试和测试能力，例如启动应用组件、强制停止进程、打印应用组件相关信息等。 4 5## 环境要求 6 7在使用本工具前，开发者需要先获取[hdc工具](../dfx/hdc.md#环境准备)，执行hdc shell。 8 9本文中命令介绍均基于交互式命令环境。如果直接执行hdc shell [aa命令]，则需要采用""来包裹aa命令，确保命令中的传参能被正确识别。示例如下： 10 11```bash 12# 启动命令 13hdc shell "aa start -A ohos.want.action.viewData -U 'https://www.example.com'" 14 15# 应用调试/调优命令 16hdc shell "aa process -b com.example.myapplication -a EntryAbility -p perf-cmd" 17``` 18 19## aa工具命令列表 20 21| 命令 | 描述 | 22|--------|--------| 23| -h/help | 帮助命令。用于查询aa支持的命令信息。| 24| start | 启动命令。用于启动一个应用组件，目标组件可以是FA模型的PageAbility和ServiceAbility组件，也可以是Stage模型的UIAbility和ServiceExtensionAbility组件，且目标组件相应配置文件中的exported标签不能配置为false。| 25| stop-service | 停止命令。用于停止ServiceAbility。 | 26| dump<sup>(deprecated)</sup> | 打印命令。用于打印应用组件的相关信息。| 27| force-stop | 强制停止进程命令。通过bundleName强制停止一个进程。| 28| test | 启动测试框架命令。根据所携带的参数启动测试框架。 | 29| attach | 进入调试模式命令。通过bundleName使指定应用进入调试模式。| 30| detach | 退出调试模式命令。通过bundleName使指定应用退出调试模式。| 31| appdebug | 等待调试命令。用于设置、取消设置应用等待调试状态，以及获取处于等待调试状态的应用包名和持久化信息。等待调试状态只对debug类型应用生效。appdebug的设置命令只对单个应用生效，当重复设置时，应用包名与持久化状态会替换成最新设置内容。| 32| process | 应用调试/调优命令。对应用进行调试或调优，IDE用该命令集成调试和调优工具。| 33| send-memory-level | onMemoryLevel回调命令。指定进程的pid和内存使用级别来触发该进程的onMemoryLevel生命周期回调。| 34 35## 帮助命令（help） 36 37```bash 38# 显示帮助信息 39aa help 40``` 41 42## 启动命令（start） 43 44启动一个应用组件，目标组件可以是FA模型的PageAbility和ServiceAbility组件，也可以是Stage模型的UIAbility和ServiceExtensionAbility组件，且目标组件相应配置文件中的exported标签不能配置为false。 45 46```bash 47# 显示启动Ability 48aa start [-d <deviceId>] [-a <abilityName> -b <bundleName>] [-m <moduleName>] [-D] [-R] [-S] [-W] [--pi <key> <integer-value>] [--pb <key> <bool-value: true/false/t/f大小写不敏感] [--ps <key> <value>] [--psn <key>] [--wl <windowLeft>] [--wt <windowTop>] [--wh <windowHeight>] [--ww <windowWidth>] [-p <perf-cmd>] 49 50# 隐式启动Ability。如果命令中的参数都不填，会导致启动失败。 51aa start [-d <deviceId>] [-U <URI>] [-t <type>] [-A <action>] [-e <entity>] [-D] [-R] [--pi <key> <integer-value>] [--pb <key> <bool-value: true/false/t/f大小写不敏感] [--ps <key> <value>] [--psn <key>] [--wl <windowLeft>] [--wt <windowTop>] [--wh <windowHeight>] [--ww <windowWidth>] [-p <perf-cmd>] 52``` 53 54 **启动命令参数列表** 55 56 | 参数 | 参数说明 | 57 | -------- |-------------------| 58 | -h/--help | 帮助信息。 | 59 | -d | 可选参数，deviceId。 | 60 | -a | 可选参数，abilityName。 | 61 | -b | 可选参数，bundleName。 | 62 | -m | 可选参数，moduleName。 | 63 | -U | 可选参数，URI。 | 64 | -A | 可选参数，action。 | 65 | -e | 可选参数，entity。 | 66 | -t | 可选参数，type。 | 67 | --pi | 可选参数，整型类型键值对。 | 68 | --pb | 可选参数，布尔类型键值对。 | 69 | --ps | 可选参数，字符串类型键值对。 | 70 | --psn | 可选参数，空字符串关键字。 | 71 | --wl | 可选参数，windowLeft，窗口左边距，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 72 | --wt | 可选参数，windowTop，窗口上边距，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 73 | --wh | 可选参数，windowHeight，窗口高度，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 74 | --ww | 可选参数，windowWidth，窗口宽度，单位px。<br>**约束：**<br>仅当2in1设备处于开发者模式下，且被启动应用采用调试签名时，该字段生效。| 75 | -R | 可选参数，调试时是否开启多线程错误检测。携带该参数代表开启，不携带代表关闭。<br>**说明：** 从API version 14开始，支持该参数。 | 76 | -S | 可选参数，调试时是否进入应用沙箱。携带该参数代表进入，不携带代表不进入。 | 77 | -D | 可选参数，调试模式。 | 78 | -p | 可选参数，调优命令。命令由调用方自定义。 | 79 | -W | 可选参数，调优命令。用于测量UIAbility从启动到切换至前台状态耗时。<br>**说明：** <br>  - 从API version 20开始支持，支持该参数。<br>  - 仅当显式启动UIAbility（必须携带-b和-a参数）时，该参数生效。<br>**正常情况的返回信息如下：** <br>  - StartMode：UIAbility启动模式，值：Cold（冷启动）/Hot（热启动）。<br>  - BundleName：目标应用bundleName。<br>  - AbilityName：目标应用abilityName。<br>  - ModuleName：目标应用moduleName，命令中带有"-m"参数时会打印moduleName，否则不打印。<br>  - TotalTime：<br>    冷启动场景下，系统侧接收到aa启动UIAbility请求到该UIAbility完成首帧绘制的耗时，单位毫秒（ms）。<br>    热启动场景下，系统侧接收到aa启动UIAbility请求到该UIAbility状态切换至前台的耗时，单位毫秒（ms）。<br>  - WaitTime：命令启动到命令执行结束的耗时，单位毫秒（ms）。<br>**异常情况的返回信息如下：**<br>  - "The wait option does not support starting implict" ：不支持隐式启动。 <br>  - "The wait option does not support starting non-uiability" ：不支持启动非UIAbility组件。 | 80 81 **返回值**： 82 83 当启动成功时，返回"start ability successfully."；当启动失败时，返回"error: failed to start ability."，同时会包含相应的失败信息。 84 85 **错误码**： 86 87 | 错误码ID | 错误信息 | 88 | ------- | -------- | 89 | 10103001 | Failed to verify the visibility of the target ability. | 90 | 10104001 | The specified ability does not exist. | 91 | 10105001 | Failed to connect to the ability service. | 92 | 10105002 | Failed to obtain ability information. | 93 | 10106002 | The aa start command's window option or the aa test command does not support app with release signature. | 94 | 10100101 | Failed to obtain application information. | 95 | 10100102 | The aa start command cannot be used to launch a UIExtensionAbility. | 96 | 10103101 | Failed to find a matching application for implicit launch. | 97 | 10103102 | The passed appCloneIndex is invalid. | 98 | 10106101 | The current ability will be placed in the queue to wait for the previous ability to finish launching. | 99 | 10106102 | The device screen is locked during the application launch. | 100 | 10106103 | The target application is an expired crowdtesting application. | 101 | 10106105 | The target application is under control. | 102 | 10106106 | The target application is managed by EDM. | 103 | 10106107 | The current device does not support using window options. | 104 | 10107102 | Permission verification failed for the specified process. | 105 | 10108101 | An internal error occurs while attempting to launch the ability. | 106 107 **示例**： 108 109 以隐式启动Ability为例。 110 111 > **说明：** 112 > 113 > 本例中仅介绍了部分字段的使用。关于Ability匹配的详细规则参考[显式Want与隐式Want匹配规则](../application-models/explicit-implicit-want-mappings.md)。 114 115 116 - **目标应用**：修改module.json5配置，为目标Ability配置uris。 117 118 ```json 119 { 120 "name": "TargetAbility", 121 // ...... 122 "exported": true, 123 "skills": [ 124 { 125 "actions":[ 126 "ohos.want.action.viewData" 127 ], 128 "uris":[ 129 { 130 "scheme": "myscheme", 131 "host": "www.test.com", 132 "port": "8080", 133 "path": "path" 134 } 135 ] 136 } 137 ] 138 } 139 ``` 140 141 142 - **拉起方应用**：隐式启动Ability。 143 144 - 如果需要拉起应用的页面，可以使用-U命令，示例如下： 145 146 ```bash 147 aa start -U myscheme://www.test.com:8080/path 148 ``` 149 150 - 在上述基础上，如果需要携带参数，可以使用如下命令： 151 152 ```bash 153 aa start -U myscheme://www.test.com:8080/path --pi paramNumber 1 --pb paramBoolean true --ps paramString teststring --psn paramNullString 154 ``` 155 156 UIAbility获取传入参数示例如下： 157 158 ```ts 159 import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'; 160 import { hilog } from '@kit.PerformanceAnalysisKit'; 161 162 export default class TargetAbility extends UIAbility { 163 onCreate(want:Want, launchParam: AbilityConstant.LaunchParam) { 164 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 165 let paramNumber = want.parameters?.paramNumber; 166 let paramBoolean = want.parameters?.paramBoolean; 167 let paramString = want.parameters?.paramString; 168 let paramNullString = want.parameters?.paramNullString; 169 } 170 } 171 ``` 172 173 - 如果需要拉起浏览器并跳转指定页面，可以使用-A -U命令，示例如下： 174 175 本例中以`https://www.example.com`为例，请根据实际情况替换为真实的网址。 176 177 ```bash 178 aa start -A ohos.want.action.viewData -U https://www.example.com 179 ``` 180 181 182## 停止命令（stop-service） 183 184用于停止ServiceAbility。 185 186```bash 187aa stop-service [-d <deviceId>] -a <abilityName> -b <bundleName> [-m <moduleName>] 188``` 189 190 **停止命令参数列表** 191 | 参数 | 参数说明 | 192 | -------- | -------- | 193 | -h/--help | 帮助信息。 | 194 | -d | 可选参数，deviceId。 | 195 | -a | 必选参数，abilityName。 | 196 | -b | 必选参数，bundleName。 | 197 | -m | 可选参数，moduleName。 | 198 199 **返回值**： 200 201 当成功停止ServiceAbility时，返回"stop service ability successfully."；当停止失败时，返回"error: failed to stop service ability."。 202 203 **错误码**： 204 205 | 错误码ID | 错误信息 | 206 | ------- | -------- | 207 | 10103001 | Failed to verify the visibility of the target ability. | 208 | 10103201 | The target ability is not of the ServiceAbility type. | 209 | 10104001 | The specified ability does not exist. | 210 | 10105001 | Failed to connect to the ability service. | 211 | 10105002 | Failed to obtain ability information. | 212 213 **示例**： 214 215 ```bash 216 # 停止一个ServiceAbility 217 aa stop-service -a EntryAbility -b com.example.myapplication -m entry 218 ``` 219 220## 打印命令（dump<sup>(deprecated)</sup>） 221 222用于打印应用组件的相关信息。 223 224```bash 225aa dump -a 226``` 227 228> **说明：** 229> 230> aa dump命令从API version 7开始支持，从API version 9废弃，替换命令为[hidumper](../dfx/hidumper.md) -s AbilityManagerService。 231 232 **打印命令参数列表** 233 | 参数 | 二级参数 | 参数说明 | 234 | -------- | -------- | -------- | 235 | -h/--help | - | 帮助信息。 | 236 | -a/--all | - | 打印所有mission内的应用组件信息。 | 237 | -l/--mission-list | type（缺省打印全部） | 服务侧为了方便管理任务链，内部维护了4种类型的任务链。<br/>可取值：<br/>- NORMAL：正常启动的任务链(比如A拉起B拉起C, 则对应的任务链是A->B->C)<br/>- DEFAULT_STANDARD：已经被破坏的任务链中的任务, 启动模式为`multiton`的任务被放到该任务链中, 这里面的任务之间没有关联关系<br/>- DEFAULT_SINGLE：已经被破坏的任务链中的任务, 启动模式为`singleton`的任务被放到该任务链中, 这里面的任务之间没有关联关系<br/>- LAUNCHER：launcher的任务链 | 238 | -e/--extension | elementName | 打印扩展组件信息。 | 239 | -u/--userId | UserId | 打印指定UserId的栈信息，需要和其他参数组合使用，例如aa dump -a -u 100、aa dump -d -u 100。 | 240 | -d/--data | - | 打印DataAbility相关信息。 | 241 | -i/--ability | AbilityRecord ID | 打印指定应用组件详细信息。 | 242 | -c/--client | - | 打印应用组件详细信息，需要和其他参数组合使用，例如aa dump -a -c、aa dump -i 21 -c。 | 243 | -p/--pending | - | 打印pendingWant信息，需要和其他参数组合使用，例如aa dump -a -p。 | 244 | -r/--process | - | 打印应用进程信息，需要和其他参数组合使用，例如aa dump -a -r。 | 245 246 **错误码**： 247 248 | 错误码ID | 错误信息 | 249 | ------- | -------- | 250 | 10105001 | Failed to connect to the ability service. | 251 252 **示例**： 253 254 ```bash 255 # 打印所有mission内的应用组件信息 256 aa dump -a 257 ``` 258 259  260 261 262 ```bash 263 # 打印所有任务链 264 aa dump -l 265 ``` 266 267  268 269 270 ```bash 271 # 打印指定应用组件详细信息 272 aa dump -i 105 273 ``` 274 275  276 277## 强制停止进程命令（force-stop） 278 279通过bundleName强制停止一个进程。 280 281```bash 282aa force-stop <bundleName> 283``` 284 285 **返回值**： 286 287 当成功强制停止该进程时，返回"force stop process successfully."；当强制停止失败时，返回"error: failed to force stop process."。 288 289 **错误码**： 290 291 | 错误码ID | 错误信息 | 292 | ------- | -------- | 293 | 10105001 | Failed to connect to the ability service. | 294 | 10104002 | Failed to retrieve specified package information. | 295 | 10106401 | Failed to terminate the process. | 296 | 10106402 | Persistent processes cannot be terminated. | 297 298 **示例**： 299 300 ```bash 301 # 通过bundleName强制停止一个进程 302 aa force-stop com.example.myapplication 303 ``` 304 305## 启动测试框架命令（test） 306 307根据所携带的参数启动测试框架。 308 309```bash 310aa test -b <bundleName> [-m <module-name>] [-p <package-name>] [-s class <test-class>] [-s level <test-level>] [-s size <test-size>] [-s testType <test-testType>] [-s timeout <test-timeout>] [-s <any-key> <any-value>] [-w <wait-time>] -s unittest <testRunner> 311``` 312 313> **说明**： 314> 315> 关于class、level、size、testType等参数的详细说明请参见<!--RP2-->[aa test命令执行配置参数](../application-test/arkxtest-guidelines.md#在cmd执行)<!--RP2End-->。 316 317 **启动测试框架命令参数列表** 318 | 参数 | 参数说明 | 319 | -------- | -------- | 320 | -h/--help | 帮助信息。 | 321 | -b | 必选参数，bundleName。 | 322 | -s unittest | 必选参数，testRunner。 | 323 | -p | 可选参数，testRunner的packageName。<br>**说明**：该可选参数仅可在FA模型下使用。 | 324 | -m | 可选参数，testRunner的moduleName。<br>**说明**：该可选参数仅可在Stage模型下使用。 | 325 | -s class | 可选参数，指定要执行的测试套或测试用例。 | 326 | -s level | 可选参数，指定要执行用例的用例级别。 | 327 | -s size | 可选参数，指定要执行用例的用例规模。 | 328 | -s testType | 可选参数，指定要执行用例的用例类型。 | 329 | -s timeout | 可选参数，测试用例执行的超时时间（单位ms），默认为5000。 | 330 | -s \<any-key> | 可选参数，任意键值对。 | 331 | -w | 可选参数，指定测试运行时间（单位ms）。 | 332 | -D | 可选参数，调试模式。 | 333 334 **返回值**： 335 336 当成功启动测试框架时，返回"user test started."；当启动失败时，返回"error: failed to start user test."和对应的错误信息。 337 338 **错误码**： 339 340 | 错误码ID | 错误信息 | 341 | ------- | -------- | 342 | 10104002 | Failed to retrieve specified package information. | 343 | 10105001 | Failed to connect to the ability service. | 344 | 10106002 | The aa start command's window option or the aa test command does not support app with release signature. | 345 | 10108501 | An internal error occurs during the execution of the aa test command. | 346 347 **示例**： 348 349 ```bash 350 # 启动测试框架 351 aa test -b com.example.myapplication -s unittest ActsAbilityTest 352 # 启动测试框架并设置moduleName 353 aa test -b com.example.myapplication -m entry_test -s unittest ActsAbilityTest 354 # 启动测试框架并指定超时时间 355 aa test -b com.example.myapplication -m entry_test -s timeout 10000 -s unittest ActsAbilityTest 356 ``` 357 358## 进入调试模式命令（attach） 359 360通过bundleName使指定应用进入调试模式。 361 362```bash 363aa attach -b <bundleName> 364``` 365 366 **进入调试模式命令参数列表** 367 | 参数 | 参数说明 | 368 | -------- |-------------------| 369 | -h/--help | 帮助信息。 | 370 | -b | 必选参数，bundleName。 | 371 372 **返回值**： 373 374 当应用成功进入调试模式时，返回"attach app debug successfully."；当给定参数不合法时，返回"fail: unknown option."并打印帮助信息。 375 376 **错误码**： 377 378 | 错误码ID | 错误信息 | 379 | ------- | -------- | 380 | 10105001 | Failed to connect to the ability service. | 381 | 10106001 | The current device is not in developer mode. | 382 | 10106002 | The aa start command's window option or the aa test command does not support app with release signature. | 383 | 10103601 | The specified bundleName does not exist. | 384 | 10108601 | An internal error occurs while attempting to enter/exit debug mode. | 385 386 **示例**： 387 388 ```bash 389 # 通过bundleName使指定应用进入调试模式 390 aa attach -b com.example.myapplication 391 ``` 392 393## 退出调试模式命令（detach） 394 395通过bundleName使指定应用退出调试模式。 396 397```bash 398aa detach -b <bundleName> 399``` 400 401 **退出调试模式命令参数列表** 402 | 参数 | 参数说明 | 403 | -------- |-------------------| 404 | -h/--help | 帮助信息。 | 405 | -b | 必选参数，bundleName。 | 406 407 **返回值**： 408 409 当应用成功退出调试模式时，返回"detach app debug successfully."；当给定参数不合法时，返回"fail: unknown option."并打印帮助信息。 410 411 **错误码**： 412 413 | 错误码ID | 错误信息 | 414 | ------- | -------- | 415 | 10105001 | Failed to connect to the ability service.| 416 | 10106001 | The current device is not in developer mode. | 417 | 10106002 | The aa start command's window option or the aa test command does not support app with release signature. | 418 | 10103601 | The specified bundleName does not exist. | 419 | 10108601 | An internal error occurs while attempting to enter/exit debug mode. | 420 421 **示例**： 422 423 ```bash 424 # 通过bundleName使指定应用退出调试模式 425 aa detach -b com.example.myapplication 426 ``` 427 428## 等待调试命令（appdebug） 429 430用于设置、取消设置应用等待调试状态，以及获取处于等待调试状态的应用包名和持久化信息。等待调试状态只对debug类型应用生效。appdebug的设置命令只对单个应用生效，当重复设置时，应用包名与持久化状态会替换成最新设置内容。 431 432```bash 433aa appdebug -b <bundleName> [-p] 434``` 435 436 **等待调试命令参数列表** 437 | 参数 | 二级参数 | 参数说明 | 438 | -------- | -------- | -------- | 439 | -h/--help | - | 帮助信息。 | 440 | -b/--bundlename | bundleName | 为指定应用设置等待调试状态。设置时，不会进行包名合法化的校验。 | 441 | -p/--persist | - | 可选参数；持久化标志位，加入该参数，代表持续设置应用为等待调试状态，无论重启设备、重装应用都可以持续生效；不加入该参数，代表等待调试状态仅可以在重启设备前生效一次。需要和-b参数组合使用，例如：aa appdebug -b <bundleName> -p。 | 442 | -c/--cancel | - | 取消等待调试状态。 | 443 | -g/--get | - | 获取等待调试状态的应用包名和持久化信息。 | 444 445 **返回值**： 446 447 当执行成功时，返回"app debug successfully."；当执行失败时，返回"error: failed to app debug."；当失败原因为非开发者模式时，返回"error: not developer mode."。 448 449 **错误码**： 450 451 | 错误码ID | 错误信息 | 452 | ------- | -------- | 453 | 10105003 | Failed to connect to the app service. | 454 | 10106001 | The current device is not in developer mode. | 455 | 10106701 | Cannot debug applications using a release certificate. | 456 457 **示例**： 458 459 ```bash 460 # 显示帮助信息 461 aa appdebug -h 462 463 # 为指定应用设置等待调试状态 464 aa appdebug -b com.example.myapplication [-p] 465 466 # 取消等待调试状态 467 aa appdebug -c 468 469 # 获取等待调试状态的应用包名和持久化信息 470 # 获取信息例： bundle name : com.example.publishsystem, persist : false 471 aa appdebug -g 472 ``` 473 474## 应用调试/调优命令（process） 475 476对应用进行调试或调优，IDE用该命令集成调试和调优工具。 477 478```bash 479# 调试应用 480aa process -b <bundleName> -a <abilityName> [-m <moduleName>] [-D <debug-cmd>] [-S] 481 482# 调优应用 483aa process -b <bundleName> -a <abilityName> [-m <moduleName>] [-p <perf-cmd>] [-S] 484``` 485 486 **应用调试/调优命令参数列表** 487 | 参数 | 参数说明 | 488 | -------- | -------- | 489 | -h/--help | 帮助信息。 | 490 | -b | 必选参数，bundleName。 | 491 | -a | 必选参数，abilityName。 | 492 | -m | 可选参数，moduleName。 | 493 | -p | 可选参数，调优命令，与-D必须二选一。命令由调用方自定义。 | 494 | -D | 可选参数，调试命令，与-p必须二选一。命令由调用方自定义。 | 495 | -S | 可选参数，进入应用沙箱。 | 496 497 **返回值**： 498 499 当执行成功时，返回"start native process successfully."；当执行失败时，返回"error: failed to start native process."；当给定参数不合法时，返回"error: option requires a value."并打印帮助信息。 500 501 | 错误码ID | 错误信息 | 502 | ------- | -------- | 503 | 10105002 | Failed to obtain ability information. | 504 | 10105003 | Failed to connect to the app service. | 505 | 10106002 | The aa start command's window option or the aa test command does not support app with release signature. | 506 507 **示例**： 508 509 ```bash 510 # 调试应用 511 aa process -b com.example.myapplication -a EntryAbility -D debug_cmd [-S] 512 513 # 调优应用 514 aa process -b com.example.myapplication -a EntryAbility -p perf-cmd [-S] 515 ``` 516 517## onMemoryLevel回调命令（send-memory-level） 518 519从API version 13开始，开发者可以通过该命令来调试应用的[onMemoryLevel](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#onmemorylevel)生命周期。通过在参数中指定进程的pid和内存使用级别来触发该进程的onMemoryLevel生命周期回调。 520 521```bash 522# 触发onMemoryLevel回调 523aa send-memory-level -p <processId> -l <memoryLevel> 524``` 525 526**参数列表** 527 528| 参数 | 参数说明 | 529| -------- | -------- | 530| -h/--help | 帮助信息。 | 531| -p | 必选参数，进程pid。 | 532| -l | 必选参数，内存使用级别，具体值参考[AbilityConstant.MemoryLevel](../reference/apis-ability-kit/js-apis-app-ability-abilityConstant.md#memorylevel)。 | 533 534**返回值**： 535 536当执行成功时，返回"send memory level successfully."；当执行失败时，返回"error: failed to send memory level."；当给定参数值缺失时，返回"fail: unknown option."并打印帮助信息。 537 538| 错误码ID | 错误信息 | 539| ------- | -------- | 540| 10104003 | The specified pid does not exist. | 541| 10104004 | The specified level does not exist. | 542 543**示例**： 544 545```bash 546# 触发进程号为6066应用的onMemoryLevel回调，此时回调的level为0 547aa send-memory-level -p 6066 -l 0 548``` 549 550## aa工具错误码 551 552### 10103001 目标Ability可见性校验失败 553 554**错误信息** 555 556Failed to verify the visibility of the target ability. 557 558**错误描述** 559 560目标Ability可见性校验失败时，aa工具将返回该错误码。 561 562**可能原因** 563 564当目标应用在module.json5配置文件中的[abilities标签](../quick-start/module-configuration-file.md#abilities标签)/[extensionAbilities标签](../quick-start/module-configuration-file.md#extensionabilities标签)中的exported字段配置为false时，表示对应UIAbility组件/ExtensionAbility组件不可以被其他应用调用，也无法被aa工具命令拉起。 565 566**处理步骤** 567 568需要检查目标应用module.json5中对应Ability字段的exported配置是否为true，如果不为true，改为true重试即可。 569 570### 10104001 指定的Ability不存在 571**错误信息** 572 573The specified ability does not exist. 574 575**错误描述** 576 577当指定的Ability名称不存在时，aa工具将返回该错误码。 578 579**可能原因** 580 581指定的Ability未安装。 582 583**处理步骤** 584 5851. 检查aa命令的-a的参数abilityName和-b的参数bundleName是否正确。 5862. 检查指定的bundleName对应的应用是否安装。可使用如下命令查询已安装的应用列表，若该bundleName不在查询结果中，说明应用未安装成功。 587 ``` 588 hdc shell bm dump -a 589 ``` 5903. 多HAP应用需确认Ability所属的HAP是否已被安装。可使用如下命令查询应用的包信息，若安装的应用中没有对应的HAP和Ability，说明Ability所属的HAP未被安装。 591 ``` 592 hdc shell bm dump -n 包名 593 ``` 594 595### 10104003 指定的pid不存在 596 597**错误信息** 598 599The specified pid does not exist. 600 601**错误描述** 602 603当指定的pid不存在时，aa工具将返回该错误码。 604 605**可能原因** 606 607指定的pid不存在。 608 609**处理步骤** 610 611检查-p参数指定的进程号在设备上是否存在。 612 613### 10104004 指定的内存使用级别不存在 614 615**错误信息** 616 617The specified level does not exist. 618 619**错误描述** 620 621当指定的内存使用级别不存在时，aa工具将返回该错误码。 622 623**可能原因** 624 625指定的内存使用级别不存在。 626 627**处理步骤** 628 629检查-l参数指定的内存使用级别是否为[0, 2]区间内的整数值。 630 631### 10105001 Ability服务连接失败 632 633**错误信息** 634 635Failed to connect to the ability service. 636 637**错误描述** 638 639连接Ability服务失败。 640 641**可能原因** 642 643调用接口时Ability服务断开。 644 645**处理步骤** 646 647尝试重启设备重新执行。 648 649### 10105002 获取Ability信息失败 650 651**错误信息** 652 653Failed to obtain ability information. 654 655**错误描述** 656 657获取Ability信息失败。 658 659**可能原因** 660 661生成Ability请求时通过BMS获取AbilityInfo为空。 662 663**处理步骤** 664 665检查指定的bundleName对应的应用是否安装。可使用如下命令查询已安装的应用列表，若该bundleName不在查询结果中，说明应用未安装成功。 666 667 ``` 668 hdc shell bm dump -a 669 ``` 670 671### 10105003 App服务连接失败 672 673**错误信息** 674 675Failed to connect to the app service. 676 677**错误描述** 678 679App服务连接失败。 680 681**可能原因** 682 683调用接口时App服务断开。 684 685**处理步骤** 686 687尝试重启设备。 688 689### 10106001 当前设备不是开发者模式 690 691**错误信息** 692 693The current device is not in developer mode. 694 695**错误描述** 696 697当前设备不是开发者模式。 698 699**可能原因** 700 701当前设备不是开发者模式。 702 703**处理步骤** 704 705在设置中打开开发者模式。操作如下： 706 707查看设备的“设置 > 系统”中是否有“开发者选项”。如果不存在，可在“设置 > 关于本机”连续七次单击“版本号”，直到提示“开启开发者模式”，点击“确认开启”后输入PIN码（如果已设置），设备将自动重启。请等待设备完成重启后，可以在“设置 > 系统”中查看。 708 709### 10106002 不支持release签名的应用程序 710 711**错误信息** 712 713The aa start command's window option or the aa test command does not support app with release signature. 714 715**错误描述** 716 717aa start命令的参数wl、wt、wh、ww或aa test命令不支持release签名的应用程序。 718 719**可能原因** 720 721目标应用为release签名。 722 723**处理步骤** 724 725使用Debug签名证书重新签名，安装新签名出的HAP后，再尝试执行该该命令。 726 727### 10100101 获取应用信息失败 728 729**错误信息** 730 731Failed to obtain application information. 732 733**错误描述** 734 735从BMS查询到的App信息异常。 736 737**可能原因** 738 739从BMS查询到的App信息中应用名或包名异常。 740 741**处理步骤** 742 7431. 检查aa命令的-a的参数abilityName和-b的参数bundleName是否正确。 7442. 检查指定的bundleName对应的应用是否安装。可使用如下命令查询已安装的应用列表，若该bundleName不在查询结果中，说明应用未安装成功。 745 ``` 746 hdc shell bm dump -a 747 ``` 7483. 多HAP应用需确认Ability所属的HAP是否已被安装。可使用如下命令查询应用的包信息，若安装的应用中没有对应的HAP和Ability，说明Ability所属的HAP未被安装。 749 ``` 750 hdc shell bm dump -n 包名 751 ``` 752 753### 10100102 aa start命令无法拉起UIExtensionAbility 754 755**错误信息** 756 757The aa start command cannot be used to launch a UIExtensionAbility. 758 759**错误描述** 760 761aa工具无法拉起UIExtensionAbility。 762 763**可能原因** 764 765aa start命令不支持启动UIExtensionAbility。 766 767**处理步骤** 768 769确认目标Ability是否为UIExtensionAbility，aa start命令无法拉起UIExtensionAbility。 770 771### 10103101 隐式启动未查找到匹配应用 772 773**错误信息** 774 775Failed to find a matching application for implicit launch. 776 777**错误描述** 778 779隐式启动无法查找到匹配的Ability。 780 781**可能原因** 782 783* 如果为隐式启动，可能是启动参数配置有误或指定的HAP包未安装。 784* 如果为显式启动，可能是命令中指定了bundleName、却未指定abilityName。 785 786**处理步骤** 787 788* 如果为隐式启动，需要确保启动参数配置正确，且指定的HAP包已安装。 789* 如果为显式启动，需要确保abilityName传参正确。 790 791### 10103102 传入的AppCloneIndex是一个无效值 792 793**错误信息** 794 795The passed appCloneIndex is invalid. 796 797**错误描述** 798 799传入一个无效的AppCloneIndex，返回该错误码。 800 801**可能原因** 802 803aa start命令的参数中携带的AppCloneIndex是一个无效值，则返回该错误码。 804 805**处理步骤** 806 807确认AppCloneIndex是否合法。 808 809### 10106101 上一个Ability未启动完成，先缓存在队列中等待后续启动 810 811**错误信息** 812 813The current ability will be placed in the queue to wait for the previous ability to finish launching. 814 815**错误描述** 816 817需要启动的Ability过多，由于系统处理能力有限，会先将请求缓存在队列中，按照顺序依次处理。 818 819**可能原因** 820 821系统并发大。 822 823**处理步骤** 824 825无需处理，等待启动即可。 826 827### 10106102 启动应用时，设备处于锁屏状态 828 829**错误信息** 830 831The device screen is locked during the application launch. 832 833**错误描述** 834 835启动应用时，设备处于锁屏状态。 836 837**可能原因** 838 839启动应用时无法解锁屏幕。 840 841**处理步骤** 842 843解锁屏幕后重新尝试即可。 844 845### 10106103 目标应用为到期众测应用 846 847**错误信息** 848 849The target application is an expired crowdtesting application. 850 851**错误描述** 852 853当目标应用为众测应用并且到达测试期限时，方法将返回该错误码。 854 855**可能原因** 856 857众测应用到期，无法打开。 858 859**处理步骤** 860 861请检查应用是否众测到期，已过有效期的众测应用无法启动。 862 863### 10106105 目标应用被管控 864 865**错误信息** 866 867The target application is under control. 868 869**错误描述** 870 871当目标应用受到应用市场管控时，方法将返回该错误码。 872 873**可能原因** 874 875目标应用疑似存在恶意行为，受到应用市场管控不允许启动。 876 877**处理步骤** 878 879建议卸载该应用。 880 881### 10106106 目标应用被EDM管控 882 883**错误信息** 884 885The target application is managed by EDM. 886 887**错误描述** 888 889当目标应用受到企业设备管理管控时，方法将返回该错误码。 890 891**可能原因** 892 893目标应用被企业管理服务设置为禁止启动。 894 895**处理步骤** 896 897该设备是一个企业设备，目标应用被设置为禁止启动，开发者无法处理。 898 899### 10106107 当前设备不支持使用窗口选项 900 901**错误信息** 902 903The current device does not support using window options. 904 905**错误描述** 906 907尝试使用窗口选项但设备不支持。 908 909**可能原因** 910 911用户使用aa start命令指定了WindowOptions，但设备不支持。 912 913**处理步骤** 914 915删除aa start命令中代表WindowOptions的参数wl、wt、wh、ww后重试。 916 917### 10107102 指定的进程权限校验失败 918 919**错误信息** 920 921Permission verification failed for the specified process. 922 923**错误描述** 924 925当指定的进程权限校验失败时，方法将返回该错误码。 926 927**可能原因** 928 929指定的进程权限校验失败。 930 931**处理步骤** 932 933确认指定进程的权限是否正确。 934 935### 10108101 拉起Ability时内部错误 936 937**错误信息** 938 939An internal error occurs while attempting to launch the ability. 940 941**错误描述** 942 943当内存申请、多线程处理异常等内部处理错误时，方法将返回该错误码。 944 945**可能原因** 946 947内存申请、多线程处理等内核通用错误。具体原因可能包括：内部对象为空、处理超时、包管理获取应用信息失败、系统服务获取失败、启动的Ability实例已达到上限等原因。 948 949**处理步骤** 950 951内部错误是系统运行过程中出现的内部错误，开发者无法处理。 952 953### 10103201 目标Ability不是ServiceAbility类型 954 955**错误信息** 956 957The target ability is not of the ServiceAbility type. 958 959**错误描述** 960 961操作的目标Ability不是ServiceAbility类型。 962 963**可能原因** 964 965aa stop命令停止ServiceAbility时，-a的参数abilityName对应的Ability不是Service类型。 966 967**处理步骤** 968 969检查aa -a的参数abilityName对应的Ability是否为ServiceAbility类型。 970 971### 10104002 获取指定包信息失败 972 973**错误信息** 974 975Failed to retrieve specified package information. 976 977**错误描述** 978 979获取指定包信息失败。 980 981**可能原因** 982 983指定的包名对应的应用没有安装。 984 985**处理步骤** 986 9871. 检查指定的包名是否正确。 9882. 检查指定的bundleName对应的应用是否安装。可使用如下命令查询已安装的应用列表，若该bundleName不在查询结果中，说明应用未安装成功。 989 ``` 990 hdc shell bm dump -a 991 ``` 992 993### 10106401 杀死进程失败 994 995**错误信息** 996 997Failed to terminate the process. 998 999**错误描述** 1000 1001杀死进程失败。 1002 1003**可能原因** 1004 10051. aa force-stop命令指定的应用不存在。 10062. 未成功连接到AppManagerService。 1007 1008**处理步骤** 1009 10101. 检查指定的bundleName对应的应用是否安装。可使用如下命令查询已安装的应用列表，若该bundleName不在查询结果中，说明应用未安装成功。 1011 1012 ``` 1013 hdc shell bm dump -a 1014 ``` 10152. 尝试重启设备。 1016 1017### 10106402 常驻进程无法被杀死 1018 1019**错误信息** 1020 1021Persistent processes cannot be terminated. 1022 1023**错误描述** 1024 1025常驻进程无法被杀死。 1026 1027**可能原因** 1028 1029aa force-stop命令指定的bundleName是常驻进程。 1030 1031**处理步骤** 1032 1033检查目标应用是否为常驻进程，常驻进程无法通过命令杀死。 1034 1035**处理步骤** 1036 1037关闭目标应用的多实例之后重新尝试。 1038 1039### 10108501 aa test命令内部错误 1040 1041**错误信息** 1042 1043An internal error occurs during the execution of the aa test command. 1044 1045**错误描述** 1046 1047当内存申请、多线程处理异常等内部处理错误时，方法将返回该错误码。 1048 1049**可能原因** 1050 1051内存申请、多线程处理等内核通用错误。具体原因可能包括：内部对象为空、处理超时、系统服务获取失败等原因。 1052 1053**处理步骤** 1054 1055内部错误是系统运行过程中出现的内部错误，开发者无法处理。 1056 1057### 10108601 进入/退出调试模式时内部错误 1058 1059**错误信息** 1060 1061An internal error occurs while attempting to enter/exit debug mode. 1062 1063**错误描述** 1064 1065当内存申请、多线程处理异常等内部处理错误时，方法将返回该错误码。 1066 1067**可能原因** 1068 1069内存申请、多线程处理等内核通用错误。具体原因可能包括：内部对象为空、处理超时、系统服务获取失败等原因。 1070 1071**处理步骤** 1072 1073内部错误是系统运行过程中出现的内部错误，开发者无法处理。 1074 1075### 10103601 指定的包名不存在 1076 1077**错误信息** 1078 1079The specified bundleName does not exist. 1080 1081**错误描述** 1082 1083用户指定的包名未找到时返回该错误码。 1084 1085**可能原因** 1086 1087aa attach/detach命令指定的包名不存在。 1088 1089**处理步骤** 1090 1091检查指定的bundleName对应的应用是否安装。可使用如下命令查询已安装的应用列表，若该bundleName不在查询结果中，说明应用未安装成功。 1092 1093 ``` 1094 hdc shell bm dump -a 1095 ``` 1096 1097### 10106701 目标应用不是Debug应用 1098 1099**错误信息** 1100 1101Cannot debug applications using a release certificate. 1102 1103**错误描述** 1104 1105目标应用不是Debug应用。 1106 1107**可能原因** 1108 1109当前使用签名工具中“type”参数不为“debug”。 1110 1111**处理步骤** 1112 1113使用Debug签名证书重新签名，安装新签名出的HAP后，再尝试执行该该命令。 1114签名工具及签名证书的生成方式可以参考：[签名工具指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-signing)。
