手把手带你使用 DevEcoCli/DevEcoCode 快速开发 APP 功能

前言

之前的章节中已经介绍了 DevEcoCli （集 HarmonyOS 开发全链路功能的终端工具）和 DevEcoCode（类似 Claude Code 的鸿蒙官方的智能体），结合上述两个能力，开发者就可以使用自然语言快速开发 HarmonyOS APP 的功能了。

简单回顾 DevEcoCli 和 DevEcoCode

在正式开始之前，先用一两分钟回顾一下这两个核心工具，方便后文的实战演示。

DevEcoCli

一个集 HarmonyOS 开发全链路功能于一体的终端工具，把 DevEco Studio 里的 hvigor、ohpm、hdc、模拟器等工具链统一封装成一条 devecocli 命令。开发者只需要在终端用自然语言描述需求，就能完成建工程、编译、安装、运行、看日志、管模拟器等一整套操作，省去在 IDE 里来回点击。

bash

devecocli create --app-name MyApp          # 新建工程
devecocli build                             # 编译打包
devecocli emulator start "PixelPhone"       # 启动模拟器
devecocli run                               # 安装并运行
devecocli log --level E --tail 200          # 拉取错误日志

更多命令与用法可查阅前序章节的详细介绍。

DevEcoCode

华为官方推出的智能体（Agent），定位类似前端生态的 Claude Code。它深度理解 ArkTS / ArkUI 语法与 HarmonyOS 工程结构，能根据一句自然语言需求直接在工程里改代码、加页面、调样式、补配置，并自动完成编译验证。开发者不用手写每一行代码，只需描述"要什么"，DevEcoCode 负责"怎么写"。

两者如何配合

工具	定位	擅长场景
DevEcoCli	终端工具链	工程脚手架、编译、运行、设备/模拟器管理、日志
DevEcoCode	智能体	需求理解、代码生成、页面开发、样式调整、问题修复

典型的协作链路是：

DevEcoCli 搭好工程并跑起来 → DevEcoCode 根据需求生成/修改代码 → DevEcoCli 负责编译运行验证 → DevEcoCode 再根据日志或效果迭代修复。下面我们就以一个真实 APP 为例，看看这套组合拳怎么落地。

朋友圈文案已有功能

这里以已经上线的朋友圈文案APP 为例，它已经有的功能如下：

朋友圈文案 APP 功能架构

对应大部分页面效果图如下：

朋友圈文案核心讲解

朋友圈文案是一个端云一体化的 HarmonyOS 应用，工程由三大模块构成：

模块	类型	职责
`entry`	HAP（主应用）	全部 UI 页面、服务、组件、桌面卡片
`cloud_objects`	HAR	Cloud Object 代理声明（端侧像调本地对象一样调云函数）
`CloudProgram`	AGC 云侧	6 个云函数 + CloudDB Schema（8 张表）

下面从 7 个维度 拆解它的核心实现。

1. 应用入口与导航架构

EntryAbility.ets 是整个应用的总控制器，负责 11 个服务的有序初始化、桌面卡片路由分发和后台保活。

服务初始化链（onCreate）：PersistentStorage → initAppContext → appSettings.loadFromStorage → userIdentity.init → phoneAuthService.init → accountService.init（含静默登录）→ copyMetricsService.init → shareService.init → …，一气呵成完成全链路准备。
桌面卡片导航两套路径：冷启动在 onCreate 解析 want.parameters.params 写入 AppStorage('widgetNavAction')；热启动在 onNewWant 直接触发 triggerWidgetNav() 跳转目标页。
卡片定时刷新双保险：主进程每 5 分钟 setInterval 刷新文案卡片（因为 onFormEvent 所在的 FormExtension 进程会被系统随时杀死），同时通过 backgroundTaskManager.startBackgroundRunning 申请 TASK_KEEPING 长时任务权限保活。

Index.ets 是底部 Tab 导航骨架（@Entry @ComponentV2）：

使用 HdsTabs（@kit.UIDesignKit）实现 4 个浮空毛玻璃 Tab（首页 / 灵感 / 收藏 / 我的）。
维护一个 NavPathStack 路由表，通过 @Builder pathMap 映射 17 条二级页面路由（Generate、Result、CopyDetail、History、Settings…）。
processWidgetAction 根据卡片传来的动作三态分发：refresh 刷新文案、copyId > 0 跳详情、page 字段路由到对应页。

2. AI 文案生成核心流程

这是 APP 的核心卖点，端云两侧配合完成一次"输入 → 生成 → 配图 → 持久化"的闭环。

AI 文案生成端云闭环流程

端侧三件套：

GeneratePage.ets（输入页）：管理 prompt / style / lengthType 三个参数，提供 6 种风格标签（温婉治愈 / 文艺清新 / 幽默风趣…）和 3 档长度（short 15-35 字 / medium 45-90 字 / long 90-160 字）。点击「一键生成」前先经 AuthPromptService 拦截校验登录态。
ResultPage.ets（结果页）：展示文案 + 风格标签 + 「内容由 AI 生成」声明，并提供 AI 配图生成（ImageGenerationService.generate()）、配图云存储持久化（CloudStorageService.uploadImageFromUrl → 回填 CloudDB）、复制（去除 \n\n（AI生成） 尾标）、海报预览等操作。
AiGenerationService.ets（端侧服务）：封装 cloudFunction.call({ name: 'generate-copy', ... })，带 traceId 全链路追踪（app-{timestamp}-{random}），三层 unwrap 兼容云函数不同的返回包装格式。

云函数 generateCopy.ts（AGC Serverless）：

对接 智谱 GLM（默认模型 glm-4.5-flash，端点 open.bigmodel.cn/api/paas/v4/chat/completions）。
Prompt 工程约束只输出一条可直接发布的文案（禁止标题、解释、Markdown、多方案）。
参数映射：lengthType → max_tokens（80/160/320），temperature: 0.82，thinking: { type: 'disabled' } 关闭深度思考加速。
降级策略：API Key 缺失时返回模板文案（source: 'server-placeholder'），保证流程不中断。

合规细节：CopyStore.generateCopy 在落库前会追加 （AI生成） 标识，符合《人工智能生成合成内容标识》要求。

3. 端云协同（CloudDB）

端云协同 CloudDB + Cloud Object 架构

CloudEntities.ets 定义 7 个继承 cloudDatabase.DatabaseObject 的实体类，覆盖 CategoryEntity / CopyEntity / FavoriteEntity / UserEntity / AiGenerationEntity / CheckInEntity / AchievementEntity / FeedbackEntity。

CloudCopyRepository.ets 是数据访问层，封装所有 CRUD：

// 典型的 CloudDB 查询范式
const zone = cloudDatabase.zone("pyqwazone");
const query = new cloudDatabase.DatabaseQuery(CopyEntity)
  .equalTo("userId", userId)
  .orderByDesc("createdAt");
const result = await zone.query(query);

三个值得学习的设计：

复合主键保证幂等：FavoriteEntity 用 {userId}_{copyId}，CheckInEntity 用 {userId}_{checkinDate}，确保 upsert 不会重复。
软删除模式：deleteGeneration 不物理删除，而是设 isDeleted = true 再 upsert，便于审计与恢复。
三层排序 + 分页（filterSortAndPageCopies）：recommend / hot / latest 三种排序策略 + offset 分页，支撑灵感页无限滚动。

cloud_objects 模块 是一个巧妙的 Cloud Object Proxy 模式：

// ImportObject.ts —— 用 ES6 Proxy 把云函数调用伪装成本地对象方法
export function importObject<T>(tClass: new () => T): T {
  return new Proxy<T>(new tClass(), {
    get(target, prop) {
      return (...args) =>
        cloudFunction.call({
          name: target.name,
          data: { method: prop, params: args },
        });
    },
  });
}

端侧使用时就像调本地方法一样：const uuid = await idGenerator.randomUUID()，底层自动代理到 id-generator 云函数。

4. 桌面卡片（FormKit）

共 6 张卡片（文案卡片 / 每日金句 / 图文金句 / 灵感精选 / 快捷创作 / 签到成就），技术难点集中在 3 处：

① 卡片无法直接加载 HTTPS 图片

FormExtension 进程不支持网络图片，必须先下载到 tempDir 拿文件描述符 fd，再通过 formImages 字段传给卡片，卡片内用 Image('memory://' + imgName) 加载。

② 跨进程数据一致性

FormExtensionAbility 运行在独立进程，必须重新 widgetDataService.init() + reloadFromDisk() 才能读到主进程写入的最新数据。为此 WidgetDataService 放弃了 preferences，改用 JSON 文件（fileIo 直接读写），规避了 preferences 的跨进程缓存一致性问题。

③ 卡片与主进程通信

两种方式并存：

postCardAction({ action: 'message' })：卡片 → 主进程的 onNewWant，用于路由跳转。
postCardAction({ action: 'call' })：卡片 → 主进程的 callee.on('refreshCopyQuote')，通过实现 rpc.Parcelable 的 MyParcelable 做 IPC 调用，用于刷新数据。

5. 华为一键登录

PhoneAuthService.ets 封装 AccountKit：

const authRequest =
  new authentication.HuaweiIDProvider().createAuthorizationWithHuaweiIDRequest();
authRequest.scopes = ["quickLoginAnonymousPhone"];
authRequest.state = util.generateRandomUUID(); // CSRF 防护
const response =
  await new authentication.AuthenticationController().executeRequest(
    authRequest
  );

预取号超时保护：Promise.race([executeRequest, timeout(5000)])，5 秒不返回就降级，避免阻塞 UI。
错误码中文化：1001502001（未登录）、1001502012（取消）、1001502014（未配置权限）等都有友好提示。

AccountService.ets（@ObservedV2 + @Trace）管理登录状态：loginWithAuthCode 把授权码传给 phone-auth 云函数，云函数再调华为服务器用 grant_type=authorization_code 换取真实手机号，返回时调 maskPhone 生成 138****8888 脱敏格式。

6. 全局状态管理（CopyStore）

CopyStore 数据流与状态管理

CopyStore.ets 是应用的"数据中枢"（@ObservedV2），所有 @Trace 字段变化自动驱动 UI 刷新：

@Trace categories: CopyCategory[]
@Trace copies: CopyItem[]
@Trace favoriteCopyIds: number[]
@Trace generations: GenerationRecord[]
@Trace remainingQuota: number = 10
@Trace isGenerating: boolean

几个值得借鉴的工程实践：

双层数据降级：loadInitialData 调 CloudDB 加载，8 秒超时后降级到 getFallbackCategories() / getFallbackCopies() 本地兜底数据，保证弱网下首屏不空白。
收藏乐观更新：toggleFavoriteCopy 先改本地 favoriteCopyIds 再异步同步 CloudDB，UI 秒级响应。
浏览计数防抖：同一条文案 1.5 秒内重复进入只计一次，避免列表滑动时重复计数。
卡片数据联动：文案加载完成后自动 updateWidgetQuoteData() 解析云存储 URL 并推送卡片更新。

7. 通用组件与主题

Theme.ets：集中式设计令牌系统，静态常量（ColorPrimary: '#1677FF'）+ 动态 Getter 响应暗黑模式（ColorPageBg 根据 appSettings.darkMode 切换），字号通过 Theme.fontSize(size) 乘以用户设置的 fontScale 缩放。
CloudImage.ets：封装 AGC Cloud Storage 图片加载组件，核心是 loadToken 竞态保护——每次加载递增 token，异步回调时校验 this.loadToken === token，防止旧请求覆盖新状态；并集成 onImageReady 回调，供海报截图前等待图片真正解码完成。
PosterCard.ets：三段式海报布局（顶部图片 + 中部文案 + 底部标签 / 回流二维码），二维码指向 AppGallery 应用详情页，实现裂变引流。

技术栈速查

技术领域	Kit / API	应用场景
ArkUI V2	`@ComponentV2` / `@ObservedV2` / `@Trace` / `@Local` / `@Param` / `@Monitor`	全应用状态管理
Navigation	`NavPathStack` + `NavDestination`	17 页路由栈
CloudDB	`@kit.CloudFoundationKit`	8 张表端云协同 CRUD
CloudFunction	`cloudFunction.call()`	AI 生成、手机号认证
Cloud Storage	`CloudStorageService`	图片上传 / 下载 URL 解析
Cloud Object	`importObject` + ES6 Proxy	端侧代理调用云函数
FormKit	`FormExtensionAbility` / `formProvider`	6 张桌面卡片全生命周期
AccountKit	`HuaweiIDProvider` / `AuthenticationController`	华为一键登录 + 静默登录
BackgroundTasksKit	`backgroundTaskManager`	后台长时任务保活
IPCKit	`rpc.Parcelable` + `callee`	卡片与主进程跨进程通信
ShareKit	`systemShare.ShareController`	系统分享面板
ArkData	`preferences` / `pasteboard`	本地持久化 / 剪贴板
CoreFileKit	`fileIo`	卡片跨进程 JSON 文件读写

整体来看，这个工程是一个端云一体化 + 多 Kit 协同的典型案例：UI 层用 ArkUI V2 装饰器管理状态，数据层用 CloudDB 端云协同，能力层集成 AccountKit / FormKit / ShareKit 等鸿蒙特色 Kit，服务端用云函数对接第三方 AI 能力，结构清晰、职责分明。

DevEcoCode 追加功能

当前朋友圈文案只能生成文本文案，因此想要开发文本文案配图功能。

使用自然语言对话即可：

当前的AI生成文案功能，没有生成对应文案配图，请你服用我已有的skill:zhipu-image ,然后帮我实现 AI生成文案时，可以附带生成配图的功能

然后在过程中，可以根据实际情况多次对话，最终实现需求。

附带部分对话历史

用户：云函数上的 key，请你直接帮我写死吧，不需要配置环境变了，这样方便我部署和使用


用户：当前动态生成的文案图片，也帮我存入文案数据表了吗，这样我在首页浏览文案的时候也可以看到这个图片


用户：我在云端添加了 imageUrl字段，然后 点击 我的历史 ，应用出现了闪退

用户：我测试了，没有出现  这个配图

用户:可以，我实际测试没有问题，帮我提交git吧；

总结

本篇以已上线的「朋友圈文案」APP 为例，完整演示了 DevEcoCli + DevEcoCode 这套组合在真实工程中的落地姿势。

回顾整个流程，可以归纳为三层价值：

1. 开发效率的飞跃

传统的 HarmonyOS 开发需要开发者手动建工程、写页面、配路由、对接云函数、处理端云数据同步……每一个环节都要翻文档、查 API。而本案例中，从一个自然语言需求「给 AI 文案生成功能加上配图」，到最终落地上线，整个过程通过多轮对话完成，DevEcoCode 负责理解意图、生成代码、处理云函数 / CloudDB Schema 改动，开发者只需做决策和验收。这种"描述要什么，而不是写怎么做"的范式，让开发重心从编码转移到设计。

2. 端云一体化能力的集大成

「朋友圈文案」这个工程本身就是一个很好的端云一体化参考实现，它几乎用到了鸿蒙开发的核心 Kit：

维度	涉及能力
UI 架构	ArkUI V2 装饰器（`@ComponentV2` / `@ObservedV2` / `@Trace`）+ NavPathStack 路由
AI 能力	云函数对接智谱 GLM，端云闭环（输入 → 生成 → 配图 → 持久化）
数据层	CloudDB 端云协同（8 张表）+ Repository 模式 + 软删除 / 复合主键
鸿蒙特色	FormKit 桌面卡片（6 张）+ AccountKit 一键登录 + ShareKit 分享
工程实践	双层数据降级、乐观更新、竞态保护、跨进程通信、后台保活

这些技术点在文中都有对应的讲解和 SVG 图辅助理解，可以作为开发类似应用时的"对照清单"。

3. 自然语言驱动的开发新范式

从「附带部分对话历史」那一节可以看到，真实的开发过程是对话式、迭代式的：

先描述需求 → DevEcoCode 出初版实现
发现问题（云端字段缺失导致闪退、配图没显示）→ 用自然语言反馈 → DevEcoCode 定位修复
验证通过 → 一句话提交 git

这和传统"写代码 → 编译 → 报错 → 查文档 → 改代码"的循环相比，反馈链路更短、心智负担更轻。当然，这种范式对开发者并非没有要求——你需要懂架构、能判断 AI 生成的代码是否合理、会调试和验收，只是体力活大幅减少了。

如果你想动手实践，可以从一个简单的需求开始（比如给某个页面加一个新功能），用 DevEcoCli 搭好工程跑起来，再让 DevEcoCode 帮你实现，体验一下这种新的开发节奏。

参考文献

DevEco Studio 工具概览：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-tools-overview
DevEcoCode：鸿蒙专属AI智能体：https://atomgit.com/openharmony-sig/deveco-code
@deveco/deveco-cli · npm：https://www.npmjs.com/package/@deveco/deveco-cli
HarmonyOS 7新特性：https://developer.huawei.com/consumer/cn/features/?ha_source=51cto&ha_sourceId=70000008
HarmonyOS AI开发提效工具：DevEco Code & DevEco CLI：https://developer.huawei.com/consumer/cn/forum/topic/0202216647056043902?ha_source=51cto&ha_sourceId=70000008
社区干货合集：一帖看全，高效查阅 https://developer.huawei.com/consumer/cn/forum/topic/0201215860119833282?ha_source=51cto&ha_sourceId=70000008

手把手带你使用 DevEcoCli/DevEcoCode 快速开发 APP 功能 ​

前言 ​

简单回顾 DevEcoCli 和 DevEcoCode ​

DevEcoCli ​

DevEcoCode ​

两者如何配合 ​

朋友圈文案 已有功能 ​

朋友圈文案核心讲解 ​

1. 应用入口与导航架构 ​

2. AI 文案生成核心流程 ​

3. 端云协同（CloudDB） ​

4. 桌面卡片（FormKit） ​

5. 华为一键登录 ​

6. 全局状态管理（CopyStore） ​

7. 通用组件与主题 ​

技术栈速查 ​

DevEcoCode 追加功能 ​

附带部分对话历史 ​

总结 ​

参考文献 ​