AI Agent+DevEco CLI：从零自动生成、构建并安装鸿蒙应用全流程实测

最近我一直在折腾一件事：让AI Agent不停留在“生成代码片段”这个层面，而是真正自己把一个鸿蒙应用从零写出来、编译通过、装进设备。搞了一圈之后发现，完成这条链路的关键不是AI模型选哪个，而是DevEco CLI这套命令行工具链能不能接得住。只要CLI链路通了，AI Agent写鸿蒙应用这件事，真不是噱头，而是每天都能用的工作方式。

这篇博文就是一次完整实测记录，我把整套流程拆开讲清楚：为什么非要用CLI而不是图形IDE、怎么把DevEco Studio里的工具“抠”出来给Agent用、提示词怎么写AI才能产出可编译的ArkTS代码、以及构建签名安装过程中那些只有踩过坑才知道的细节。内容不算浅，但我会尽量把每一步都说人话，适合两类人看：一是鸿蒙开发想拥抱AI/自动化的开发者，二是玩AI Agent、想让它干点正经活的人。

1. 先想清楚：为什么让 AI Agent 碰鸿蒙应用，这件事值得干

AI Agent的风向这两年已经从“聊天汇报”转向“真正干活”，但很多人试下来发现，Agent写代码是一回事，让它把一个项目从头到尾跑通是另一回事。鸿蒙开发恰好是验证这件事的绝佳试验田，原因有三：第一，鸿蒙应用开发有完整且目录结构清晰的标准工程；第二，它有一套相对独立的命令行工具链，不依赖图形界面；第三，整个生态比较新，AI训练语料里鸿蒙相关内容不如Web/Android那么多，反而能看出Agent的“工程兜底能力”到底有几斤几两。

这篇实测要打通的核心链路是：AI Agent基于ArkTS和Stage模型，生成一个完整鸿蒙应用工程；然后用DevEco Studio自带的CLI工具（hvigorw、hdc、hap-sign-tool）完成构建、签名、安装；最后让AI Agent读取构建日志，自动修复报错，循环到跑通为止。说白了，就是“AI生成代码＋命令行构建”这套组合拳的实战验收。

我实测用的目标应用是一个待办事项清单App，支持添加、勾选完成、删除。功能看着不起眼，但它能覆盖鸿蒙应用的核心骨架——EntryAbility入口、页面路由、状态管理、UI组件、资源文件、签名打包，跑通这个最小闭环之后，你完全可以把同一套方法论迁移到更复杂的应用上。整个项目做下来，我对“AI能不能端到端写App”这个问题的答案，已经从怀疑变成了“能，但要看你会不会调教”。

2. 环境准备：把 DevEco CLI 从 IDE 里“抠”出来

2.1 为什么必须绕开 DevEco Studio 图形界面

如果你让AI去点DevEco Studio的图形界面，体验极其痛苦。DevEco Studio是IntelliJ系IDE，菜单深、弹窗多、悬浮提示多，Agent哪怕用Computer Use这类模拟操作工具，每一步都要“看屏→理解→点击→确认”，点一个构建按钮可能要点四五下鼠标，构建日志还要在面板里翻半天。图形界面天生是给“人”用的，不是给“程序”用的。

命令行才是程序之间交流最自然的语言。hvigorw一条命令就能触发整个构建流程并输出结构化日志，hdc一条命令就能安装应用、拉取设备日志，hap-sign-tool一个JAR包就能完成签名。AI Agent本质上也是程序，让它读文本日志、执行命令、改配置文件，效率远高于模拟鼠标去点界面。所以走CLI路线，不是退而求其次，而是Agent能真正独立工作的前提。

2.2 DevEco CLI 四件套：各自负责什么

DevEco CLI并不是单独安装的一个工具，它藏在DevEco Studio安装目录里。拆开看，常用的是四个：

• hvigorw：项目构建器，负责编译ArkTS、打包资源、生成HAP/HSP/HAR，是整个自动化链路的地基。
• hdc：鸿蒙设备连接器，类似Android里的adb，负责装应用、传文件、拉日志。
• hap-sign-tool：签名工具，给未签名的包签上调试或发布证书，否则设备拒绝安装。
• ohpm：鸿蒙的包管理器，类似npm，负责安装第三方依赖，但和npm不通用。

实测最稳妥的落地方式，是先用DevEco Studio新建一个Empty Ability空模板工程，然后把工程目录和CLI工具路径都喂给AI Agent，让它基于真实模板去改代码，而不是从零生成整个工程结构。原因很现实：鸿蒙工程里有很多约定俗成的配置，比如build-profile.json5、hvigorfile.ts、资源映射、module.json5，AI凭空生成的工程经常缺漏，但在已有模板基础上增删改，成功率会高很多。

2.3 获取工具路径并验证命令行构建

环境准备的第一步，是确认DevEco Studio装好、SDK齐全。我实测用的是macOS（Apple Silicon），DevEco Studio 5.0.3，API 12（对应HarmonyOS NEXT 5.0.x）。Windows下的原理一致，只是路径不一样，我在关键位置都会标注。

macOS下需要记住这几个路径：

• DevEco Studio应用目录：/Applications/DevEco-Studio.app
• SDK目录：/Applications/DevEco-Studio.app/Contents/sdk
• 命令行工具目录：/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains
• 项目构建脚本：工程根目录下的./hvigorw

Windows下一般是C:\Program Files\Huawei\DevEco Studio\sdk和...\tools。

新建完空模板工程后，先别写业务代码，直接确认一下local.properties文件里SDK路径是否正确：

sdk.dir=/Applications/DevEco-Studio.app/Contents/sdk nodejs.dir=/Applications/DevEco-Studio.app/Contents/tools/node

然后跑一次最朴素的构建，验证CLI链路通不通：

cd MyHarmonyApp ./hvigorw assembleHap --mode module -p product=default -p module=entry@default

第一次执行会下载hvigor相关依赖，日志会卡在解析oh_modules的阶段，耐心等。构建成功后能看到entry/build/default/outputs/default/entry-default-unsigned.hap生成，这说明环境OK了。如果这步都不通过，问题不在AI，而在环境，千万别急着往下走。

可选操作是把工具路径写进环境变量，方便Agent调用：

export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk export PATH=$DEVECO_SDK_HOME/default/openharmony/toolchains:$PATH alias hvigor="./hvigorw" alias hdc="$DEVECO_SDK_HOME/default/openharmony/toolchains/hdc"

3. 让 AI Agent 真正“动手写”鸿蒙应用代码

3.1 提示词怎么写，AI 才不给你一堆没用的残次品

AI Agent写代码的能力，很大程度取决于你给的上下文有多完整。如果只说“帮我写一个鸿蒙待办应用”，你大概率会收到一份看起来像JS的伪TypeScript代码，装饰器缺失、资源文件没有、页面路径对不上，编译必挂。

我实测调得比较顺的提示词，至少包含四块信息：技术栈与版本、工程结构约束、功能清单、验收标准。以Claude为例，核心是这样一版：

你是鸿蒙应用开发专家。请基于Stage模型和ArkTS语言，修改我本地的空模板工程（工程路径：/Users/xxx/MyHarmonyApp），实现一个待办事项应用。 功能要求： 1. 支持输入文本添加待办项 2. 支持勾选完成/取消完成 3. 支持删除待办项 4. 待办数据用 @State 管理，不接后端 工程约束： - 主页面文件为 entry/src/main/ets/pages/Index.ets - EntryAbility 路径保持 entry/src/main/ets/entryability/EntryAbility.ets 不变 - 使用 ArkUI 声明式语法，所有组件用 struct 定义 - 不允许使用任何需要 ohpm install 的第三方依赖 - 编译目标 API 12（HarmonyOS NEXT 5.0.0(12)） 完成后请输出你修改/新增的完整文件清单，以及每个文件的内容。

注意关键词“修改我本地的空模板工程”，不是“从零生成”。给Agent一个真实工程路径，它就能通过文件读写能力直接改代码，落地程度完全不一样。如果Agent平台支持读本地文件，这种方式的成功率会远高于纯靠上下文生成。

3.2 生成结果必须对照的文件清单

无论AI输出多少文件，最终能决定构建成败的是下面这一组，缺一个都可能翻车：

• entry/src/main/ets/pages/Index.ets：应用主页，核心UI和交互逻辑在这里。
• entry/src/main/ets/entryability/EntryAbility.ets：应用入口Ability，负责加载首页，一般不用改。
• entry/src/main/module.json5：模块配置，声明Ability、页面路由、设备类型。
• entry/src/main/resources/base/element/string.json、color.json：资源文件，AI经常忽略。
• entry/src/main/resources/base/profile/main_pages.json：页面路由表，没它找不到页面。
• AppScope/app.json5：应用级配置，包名、版本号。
• entry/build-profile.json5：模块构建配置，签名配置在这里。

实操时最典型的问题，是Index.ets里用了$r('app.string.xxx')，但string.json里根本没有这个key；或者main_pages.json漏写了pages/Index。资源引用与JSON文件脱节，是AI生成鸿蒙代码的第一大坑。你可以在提示词里明确要求“涉及资源引用时同步更新JSON”，但最好还是在构建日志报错时让AI自己去读日志修复。

3.3 实测样例：AI 生成的待办事项应用页面代码

下面这段是AI生成、并且实测能通过编译和运行的Index.ets，可以作为你的参考基准：

// entry/src/main/ets/pages/Index.ets import { promptAction } from '@kit.ArkUI'; interface TodoItem { id: number; title: string; done: boolean; } @Entry @Component struct Index { @State todos: TodoItem[] = []; @State inputValue: string = ''; private nextId: number = 1; build() { Column({ space: 12 }) { Row({ space: 8 }) { TextInput({ placeholder: '输入待办事项', text: this.inputValue }) .layoutWeight(1) .onChange((value: string) => { this.inputValue = value; }) Button('添加') .onClick(() => { this.addTodo(); }) } .width('100%') List({ space: 8 }) { ForEach(this.todos, (item: TodoItem) => { ListItem() { Row({ space: 8 }) { Checkbox() .select(item.done) .onChange((checked: boolean) => { this.toggleTodo(item.id, checked); }) Text(item.title) .decoration({ type: item.done ? TextDecorationType.LineThrough : TextDecorationType.None }) .layoutWeight(1) Button('删除') .type(ButtonType.Normal) .onClick(() => { this.removeTodo(item.id); }) } .width('100%') .padding(12) .backgroundColor(Color.White) .borderRadius(8) } }, (item: TodoItem) => item.id.toString()) } .layoutWeight(1) .width('100%') } .width('100%') .height('100%') .padding(16) .backgroundColor('#F1F3F5') } addTodo(): void { const title = this.inputValue.trim(); if (!title) { promptAction.showToast({ message: '请输入内容' }); return; } this.todos.push({ id: this.nextId++, title: title, done: false }); this.inputValue = ''; } toggleTodo(id: number, done: boolean): void { const index = this.todos.findIndex(item => item.id === id); if (index !== -1) { this.todos[index].done = done; } } removeTodo(id: number): void { this.todos = this.todos.filter(item => item.id !== id); } }

代码本身走的是最常规的ArkUI声明式写法。有两个细节特别容易引发运行期问题，需要你人工扫一眼：一是ForEach必须保证第三个参数（key生成器）存在，否则列表勾选状态可能错乱；二是interface定义不要放在@Entry装饰的struct内部嵌套定义，ArkTS的编译器在这块比TypeScript敏感。

对应的module.json5，AI生成后我核对过一个可用版本：

{ "module": { "name": "entry", "type": "entry", "description": "$string:module_desc", "mainElement": "EntryAbility", "deviceTypes": ["phone"], "deliveryWithInstall": true, "installationFree": false, "pages": "$profile:main_pages", "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "$string:EntryAbility_desc", "icon": "$media:icon", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:icon", "startWindowBackground": "$color:start_window_background", "exported": true, "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ] } }

mainElement指向EntryAbility，pages指向$profile:main_pages，deviceTypes写了phone。如果你要跑在平板上，记得让AI把deviceTypes加上tablet。

3.4 AI Agent 怎么把代码“落地”到本地工程

有些Agent只能在对话框里输出代码，这其实不够“Agent”。我更推荐的形态是：Agent能直接读写你本地工程目录。Claude的桌面端、一些支持文件系统MCP的框架都能做到。

落地时注意编码问题。Windows环境生成的代码文件偶尔会以GBK写入，而hvigor要求UTF-8，构建会报unmappable character。遇到这种情况，用IDE或iconv命令转一下编码就行，这个问题在macOS/Linux基本遇不到。

4. 用 DevEco CLI 完成构建、签名、安装全流程

4.1 构建：hvigorw 的常用姿势和产物路径

代码落地后，在工程根目录执行：

./hvigorw assembleHap --mode module -p product=default -p module=entry@default

这条命令的含义是：以module模式构建entry模块，product为默认产品变体。如果你只想拿到最终产物，直接./hvigorw assembleHap也可以，但显式指定模块在排错时更清晰。

构建日志大致分三段：hvigor配置加载、ArkTS编译、资源打包。看到BUILD SUCCESSFUL就成功了。产物路径默认是：

entry/build/default/outputs/default/entry-default-unsigned.hap

注意文件名里带unsigned，这是未签名包。未签名包没法直接安装到设备，下一步必须处理签名。

4.2 签名：两种路线，按场景选

签名是最容易让人在命令行里卡壳的地方。图形IDE可以一键自动签名，命令行没有魔法。我实测下来有两条路线。

路线A：先让 DevEco Studio 生成签名，再让 CLI 复用。

在DevEco Studio中打开工程，进入File → Project Structure → Signing Configs，勾选自动生成签名，让IDE生成调试证书、调试profile。此时IDE会在工程里写入证书文件，并更新build-profile.json5的signingConfigs。之后CLI构建会自动带上签名，直接产出已签名hap。这种方案最省心，缺点是一台机器、一个包名要生成一次证书，没法完全脱离IDE。

"signingConfigs": [ { "name": "default", "type": "HarmonyOS", "material": { "certpath": "./sign/certificate.pem", "storePassword": "123456", "keyAlias": "debugKey", "keyPassword": "123456", "profile": "./sign/profile.p7b", "signAlg": "SHA256withECDSA", "storeFile": "./sign/keystore.p12" } } ]

路线B：纯命令行，用 hap-sign-tool 手动签名。

hap-sign-tool.jar在SDK的toolchains目录下，命令形如：

java -jar hap-sign-tool.jar sign-app \ -keyAlias "debugKey" \ -signAlg "SHA256withECDSA" \ -mode "localSign" \ -appCertFile "certificate.cer" \ -profileFile "profile.p7b" \ -inFile "entry-default-unsigned.hap" \ -keystoreFile "keystore.p12" \ -outFile "entry-default-signed.hap" \ -keyPwd "123456" \ -keystorePwd "123456"

这条路线的难点在于：调试证书和profile文件本身还是要在AGC平台或DevEco Studio里生成。所以个人实验阶段更建议走路线A，把签名配置一次性搞定后，后面CLI就畅通无阻了。

4.3 安装：hdc 连设备、装包、拉日志

签名完成后，用hdc把应用装到正在运行的模拟器或真机：

hdc list targets hdc install entry-default-signed.hap

hdc list targets先确认设备在线，如果返回[Empty]，说明模拟器没启动或设备没授权。装完以后可以用：

hdc shell aa start -a EntryAbility -b com.example.myapp

直接拉起应用。这一步对AI排错尤其重要——Agent可以通过hdc shell hilog读取运行日志，看到崩溃堆栈，然后回头改代码。日志命令一般是：

hdc shell hilog | grep -i "error\|exception"

4.4 把 AI Agent 和 CLI 串成自动闭环

工具都齐了，最关键的就是让AI Agent自己驱动这套流程。我的做法是给Agent封装一个“鸿蒙构建Skill”，定义好它可用的命令白名单，让它在循环里不断“改代码→构建→看日志→再改”。

最简单的实现，是给Agent写一段明确的操作流程提示，比如：

你是一个自动构建代理。工作循环如下： 1. 修改工程文件 2. 执行 ./hvigorw assembleHap --mode module -p product=default -p module=entry@default 3. 如果构建失败，读取 build 日志和 hilog，定位问题并修改代码 4. 重复直到构建成功

实测下来，AI在“读取编译器报错→修复代码”这个循环上的表现，比它从零写代码更好。因为编译器报错是明确的文本，AI很擅长做“根据错误信息改代码”这件事。很多问题，比如装饰器写错、资源key缺失、方法名拼错，AI都能根据日志自己修好。如果你想更工程化，也可以把hvigor和hdc封装成MCP工具暴露给Agent，让它自动发现工具，但我个人用Skill方式更顺手，因为可以在流程注释里写很多约束。

5. 实测踩坑：AI 写鸿蒙代码的 7 个典型问题

这部分是我最想讲的实战内容。AI写鸿蒙代码看着顺利，实际坑也不少。下面这些问题，我在实测中基本都遇到过，每个都附上排查思路。

5.1 装饰器写错位置或顺序

ArkTS里@Entry标记页面入口组件，@Component标记自定义组件，@State标记响应式状态。AI经常把@Entry和@Component顺序写反，或者把@State用在普通函数内部。这类问题编译器会直接报语法错误，把报错信息原样丢给AI，它基本能自己修好。

5.2 资源引用与 JSON 文件脱节

AI生成的代码喜欢用$r('app.string.xxx')引用资源，但不会自动在string.json里建key。构建报错通常是resource not found: string/xxx。排查方法：全局搜代码里所有$r(引用，去对应JSON文件核对，缺啥补啥。这块AI乱写率很高，建议提示词里强制要求“资源引用必须同步更新”。

5.3 把 npm 和 ohpm 混用

AI遇到第三方库需求时，常会建议执行npm install。鸿蒙项目的依赖管理用的是ohpm，仓库和格式跟npm完全不同。实测中AI很容易给出类似npm install @ohos/xxx的错误指令。我的处理方式是在Skill里加硬约束：不推荐任何未经验证的第三方依赖，全部用ArkUI原生组件实现。

5.4 module.json5 缺字段或路径写错

AI从零生成module.json5时，经常把srcEntry写成entry/src/main/ets/...这种从工程根目录开始的路径，但鸿蒙期望的是相对模块根目录的./ets/entryability/EntryAbility.ets。这类问题构建日志会给出明确行号，让AI读日志修是最快的。

5.5 API 版本不匹配

AI的知识库很可能跟你的SDK版本不同步。比如API 12推荐用@kit.ArkUI方式导入promptAction，但AI可能会写旧的@ohos.promptAction导入。代码看着合法，编译却报错。排查办法：让Agent把报错信息里的API提示当强约束，明确告诉它“当前编译目标是API 12，只用API 12支持的接口”。

5.6 ForEach 缺少 key 生成器

ArkUI的ForEach必须传第三个参数keyGenerator，否则列表项复用时会出诡异问题，比如勾选状态串行、数据更新不刷新。AI经常只写前两个参数，编译不报错但运行行为异常。这种“编译过、运行炸”的问题最难排查，所以我在提示词里会点名要求：所有ForEach必须提供key生成器。

5.7 构建成功后 hap 装不上设备

如果构建成功但hdc install失败，十有八九是签名问题，常见原因包括：签名证书过期、signingConfigs没有生效、profile与包名不匹配。排查步骤：确认build-profile.json5里signingConfigs不为空；确认产物文件名里不再是unsigned；如果还是不行，回DevEco Studio重新生成一次签名配置，再让CLI复用。

下面是快速排查对照表，我贴在项目里，遇到问题直接查：

写在最后：这套方案还能怎么玩

我实测下来的总体感受是：用AI Agent配合DevEco CLI开发鸿蒙应用，已经从“玩具”走到了“能用”的阶段，但还没到“完全自动驾驶”。AI写页面、写状态管理、写基础交互，完全没问题；它在资源管理、签名打包、版本适配这些“工程细节”上，还需要人在边上盯着。不过，只要把提示词写细、把Skill定义好，Agent确实可以做到“你提需求，它写代码，它编译，它自己修到你满意”。

最后分享一个小技巧：当你让AI Agent写鸿蒙应用时，别把它当成“万能编码工”，而是把它当成“一个聪明但缺乏工程经验的新同事”。给它清晰的工程上下文，给它真实的构建工具，让它看到日志反馈——剩下的，它真能搞定大部分。鸿蒙的工具链（DevEco CLI）其实天然适合走Agent自动化的路线，因为CLI暴露得足够彻底。如果你手头正好有鸿蒙项目，不妨从今天开始，先让Agent写一版待办应用，再跑一遍CLI，大概率会比你想的更顺利。