最近我一直在折腾一件事让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.json5AI凭空生成的工程经常缺漏但在已有模板基础上增删改成功率会高很多。2.3 获取工具路径并验证命令行构建环境准备的第一步是确认DevEco Studio装好、SDK齐全。我实测用的是macOSApple SiliconDevEco Studio 5.0.3API 12对应HarmonyOS NEXT 5.0.x。Windows下的原理一致只是路径不一样我在关键位置都会标注。macOS下需要记住这几个路径DevEco Studio应用目录/Applications/DevEco-Studio.appSDK目录/Applications/DevEco-Studio.app/Contents/sdk命令行工具目录/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains项目构建脚本工程根目录下的./hvigorwWindows下一般是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 productdefault -p moduleentrydefault第一次执行会下载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/hdc3. 让 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 12HarmonyOS 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.json5AI生成后我核对过一个可用版本{ 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指向EntryAbilitypages指向$profile:main_pagesdeviceTypes写了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 productdefault -p moduleentrydefault这条命令的含义是以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.haphdc list targets先确认设备在线如果返回[Empty]说明模拟器没启动或设备没授权。装完以后可以用hdc shell aa start -a EntryAbility -b com.example.myapp直接拉起应用。这一步对AI排错尤其重要——Agent可以通过hdc shell hilog读取运行日志看到崩溃堆栈然后回头改代码。日志命令一般是hdc shell hilog | grep -i error\|exception4.4 把 AI Agent 和 CLI 串成自动闭环工具都齐了最关键的就是让AI Agent自己驱动这套流程。我的做法是给Agent封装一个“鸿蒙构建Skill”定义好它可用的命令白名单让它在循环里不断“改代码→构建→看日志→再改”。最简单的实现是给Agent写一段明确的操作流程提示比如你是一个自动构建代理。工作循环如下 1. 修改工程文件 2. 执行 ./hvigorw assembleHap --mode module -p productdefault -p moduleentrydefault 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复用。下面是快速排查对照表我贴在项目里遇到问题直接查报错/现象大概率原因处理建议resource not found资源key缺失核对$r(引用和JSON资源Cannot find module依赖或import路径错误检查oh-package.json5和import路径语法错误/装饰器报错AI写错ArkTS语法把编译器输出丢回给AI修复装不上设备签名缺失或profile过期重新生成签名配置运行后闪退ForEach缺key或空指针拉取hilog日志定位编码错误文件不是UTF-8用iconv或IDE转码写在最后这套方案还能怎么玩我实测下来的总体感受是用AI Agent配合DevEco CLI开发鸿蒙应用已经从“玩具”走到了“能用”的阶段但还没到“完全自动驾驶”。AI写页面、写状态管理、写基础交互完全没问题它在资源管理、签名打包、版本适配这些“工程细节”上还需要人在边上盯着。不过只要把提示词写细、把Skill定义好Agent确实可以做到“你提需求它写代码它编译它自己修到你满意”。最后分享一个小技巧当你让AI Agent写鸿蒙应用时别把它当成“万能编码工”而是把它当成“一个聪明但缺乏工程经验的新同事”。给它清晰的工程上下文给它真实的构建工具让它看到日志反馈——剩下的它真能搞定大部分。鸿蒙的工具链DevEco CLI其实天然适合走Agent自动化的路线因为CLI暴露得足够彻底。如果你手头正好有鸿蒙项目不妨从今天开始先让Agent写一版待办应用再跑一遍CLI大概率会比你想的更顺利。