企业官网建设流程全解析

一键开通华为云码道 CodeArts 代码智能体 ：Developer Events_Developer Alliance-Huawei Cloud

摘要

本文为华为云码道 CodeArts Agent 开发赛参赛作品实录，项目依托华为云码道 CodeArts Agent IDE（鸿蒙专属智能体 IDE），基于 HarmonyOS API10、ArkTS、Stage 模型开发鸿蒙元服务 —— 代码片段管理器。项目设计单一变量对照实验，使用相同需求指令对比码道网页工作台与CodeArts Agent IDE两套 AI 开发链路，全部代码在 DevEco Studio 的 Mate 90 Pro 模拟器验证。项目实现沙箱 JSON 持久化、片段增删改查、标签检索、剪贴板复制、负一屏元服务卡片等功能。元服务免安装即用，本地私有沙箱保障数据安全，方便开发者快速查阅复用代码模板。

关键词：HarmonyOS；元服务；ArkTS；沙箱持久化；元服务卡片；CodeArts

一、项目概述

1.1 项目背景与需求分析

开发调试 Demo 时经常需要保存小段代码、命令与模板。普通笔记应用需要打开 App 才能查看，缺少鸿蒙负一屏快速预览能力，现有代码片段工具缺少原生元服务卡片。

本项目并非用于手机编写大段代码，核心场景为代码片段快速查阅复制，亮点是负一屏元服务卡片，无需启动应用预览收藏代码。项目无后端，数据保存在应用私有沙箱。为探究 AI 开发鸿蒙应用的方案，设计对照实验，固定需求对比两套码道智能体，代码统一在 Mate 90 Pro 模拟器验证，根据实验结果选定开发方案。

项目能力边界：本元服务仅用于代码片段本地管理、查阅复制，不支持云端同步、在线代码编译执行；数据无法跨设备同步；卡片仅展示、不能编辑新增；导入导出仅兼容本项目 JSON 文件，有文件大小限制。

图 1 ：AtomGit 平台主页，右上角新建项目，创建代码仓库用于存放码道智能体生成的项目源码，实现代码版本管理。

图 2 ：新建完成后的 AtomGit 代码仓库初始页面，仓库为空，提供 Git 拉取、推送命令，后续可将码道生成的项目代码推送至此仓库保存版本。

1.2 技术选型

1. 应用类型：鸿蒙元服务（HAP）
2. 系统 API：HarmonyOS API10
3. 开发语言：ArkTS
4. 应用模型：Stage 模型
5. 存储方案：鸿蒙沙箱文件 API，本地 JSON 持久化
6. 系统能力：Pasteboard 剪贴板服务
7. UI 框架：ArkUI 声明式组件
8. 元服务：Form 卡片，完整实现卡片 onAdd、onUpdate、onRemove 生命周期
9. 开发工具：华为云码道网页工作台智能体（模型 CodeArts、GLM5.2）、CodeArts Agent IDE 鸿蒙专属智能体（模型鸿蒙开发、GLM5.2） + DevEco Studio 本地 IDE + 华为 Mate 90 Pro 鸿蒙模拟器

1.3 功能模块总览

整个项目划分为五大核心模块：

1. 沙箱持久化存储模块：封装文件读写工具，负责 JSON 数据保存与读取，数据隔离在应用私有沙箱；
2. 代码片段业务模块：片段新增、修改、删除、搜索、标签筛选、收藏状态管理；
3. 页面 UI 模块：首页片段列表、代码详情页，ArkUI 构建页面；
4. 剪贴板交互模块：调用系统 Pasteboard，代码一键复制；
5. 元服务卡片模块：负一屏卡片展示收藏片段，支持卡片刷新、生命周期回调。

二、对照实验：码道网页工作台智能体 VS CodeArts Agent IDE 鸿蒙智能体

实验目的：对比两套智能体在鸿蒙代码生成、工程完整性、开发便捷度、平台适配能力差异；统一使用 DevEco Studio + Mate 90 Pro 模拟器验证。

实验控制变量：完全相同的需求 Prompt、同一元服务项目，统一模拟器验证环境。

2.1 实验组 A：码道网页工作台智能体

实验操作： 网页端提交需求生成工程源码，支持 tar.gz 打包下载；打包失败手动复制代码，导入 DevEco Studio 编译调试。

实验现象：

✅ 优势：无需本地安装 DevEco 即可生成完整工程；网页可浏览文件树，支持打包导出，适合快速原型验证。

❌ 局限：对元服务、json5 工程配置理解不足，易触发 Schema 校验报错；打包不稳定，失败时代码复制工作量大；无内置模拟器，只能输出源码，无法预览 UI 缺陷。

图 3 ：华为云码道 CodeArts 网页工作台界面，提交与 IDE 端一致的需求 Prompt，选用 GLM-5.2 模型生成鸿蒙元服务工程。

图 4 ：智能体完成项目代码生成，所有源码输出至 /workspace/CodeSnippetManager 目录，支持打包 tar.gz 下载源码包到本地。

图 5 ：将网页工作台下载的源码压缩包解压，导入本地 DevEco Studio，编译构建 HAP 包，BUILD SUCCESSFUL。

图 6 ：网页工作台智能体生成的项目原型，在模拟器下的界面效果，展示首页片段列表与帮助弹窗。

2.2 实验组 B：CodeArts Agent IDE 鸿蒙专用智能体

实验操作：Agent IDE 提交相同需求，智能体自动维护完整工程目录，无需手动新建文件。代码生成后在 DevEco Studio 编译运行；捕获 BUG 后将日志、截图提交智能体迭代修复。

实验现象：

✅ 优势：鸿蒙专项优化，熟悉 Stage 模型、Form 卡片与 json5 配置，编译报错更少；自动维护工程；可复现 UI 缺陷，持续迭代。

❌ 局限：依赖本地 DevEco Studio 与鸿蒙模拟器，智能体仅负责代码生成，不能直接运行 HAP。

图 7 ：CodeArts Agent IDE 界面，提交与网页工作台相同需求指令，选用鸿蒙开发 + GLM5.2 模型生成鸿蒙元服务项目源码。

图 8 ：CodeArts Agent IDE 代码生成完成界面，右侧展示任务产物，左侧资源管理器查看完整工程目录。

图 9 ：项目在 DevEco Studio 中选择 Mate 90 Pro 模拟器，作为对照实验统一测试设备。

2.3 对照实验结果与方案选择

实验结论：网页工作台适合快速产出原型，但元服务配置能力弱，调试成本高。CodeArts Agent IDE 针对鸿蒙专项优化，工程规范，降低 Stage、Form 卡片开发门槛。因此本项目选定CodeArts Agent IDE 作为核心开发智能体，开展后续完整迭代开发。

三、基于对照实验结论的完整开发流程

分为源码生成、本地迭代开发两个阶段。

3.1 第一阶段：CodeArts Agent IDE 智能体生成初始工程源码

编写结构化需求，明确元服务类型、API 版本、功能、沙箱、剪贴板、卡片规范。智能体自动规划目录，生成 ets 代码、资源与 json5 配置，一次性输出完整工程。

图 10 ：CodeArts Agent IDE 初始开发界面。右下角可选择智能体类型与底层大模型；右侧智能体面板提供氛围编程（Vibe-Coding）与规范开发（Spec-Driven）两种开发模式。

注：氛围编程：边开发边沟通，持续迭代需求，适合原型搭建；规范开发：文档驱动标准化代码。本项目采用氛围编程开发。

3.2 第二阶段：本地 IDE 导入、模拟器测试 + 智能体迭代修复 BUG

导入工程，配置依赖与签名，模拟器运行 HAP。首轮测试发现布局拥挤、状态栏遮挡、json5 配置报错等问题；将截图与日志提交智能体，优化 SafeArea 并修正配置，反复编译复测直至功能、UI 正常。

图 11 ：CodeArts Agent IDE 迭代开发界面，AI 批量修复项目 Bug，内置 Git 工具完成迭代版本提交，留存代码变更记录。

四、系统设计

4.1 项目目录结构

harmony-code-snippet-widget/ ├── AppScope/ # 应用全局配置、应用级资源 │ ├── app.json5 # 应用全局基础配置 │ └── resources/ # 全局图片、字符串资源 │ ├── entry/ # 主HAP模块，元服务核心入口 │ ├── src/main/ets/ │ │ ├── entryability/ # UIAbility，应用入口与页面生命周期 │ │ ├── entryformability/ # FormAbility，元服务卡片生命周期 │ │ ├── pages/ # 业务页面：首页、详情、编辑、标签管理、导入导出、设置页 │ │ ├── widget/ # 负一屏元服务卡片UI代码 │ │ ├── components/ # 公共复用组件：代码块、标签胶囊、片段卡片、搜索栏 │ │ ├── model/ # 数据实体模型：代码片段、标签数据结构 │ │ ├── db/ # 数据库持久化封装 │ │ ├── service/ # 业务服务层，片段/标签/导入导出业务逻辑 │ │ ├── utils/ # 通用工具函数（文件、日期、偏好存储） │ │ └── common/ # 全局常量、路由、数据库常量 │ │ │ ├── src/main/resources/ # 模块资源：文字、颜色、图片、卡片form配置、路由配置 │ ├── src/ohosTest/ # 单元测试目录 │ └── 模块构建配置文件（build-profile.json5、hvigorfile.ts等） │ ├── 工程根目录配置文件 # 项目整体构建、依赖、代码检查配置

注：目录树仅展示核心业务层级，省略缓存、次要文件。

4.2 核心模块设计

• 沙箱持久化：获取 UIAbility 私有沙箱 context.filesDir，封装读写工具操作 snippet.json，数据隔离符合鸿蒙规范；文件不存在自动返回空数组，避免程序崩溃。
• 页面路由：main_pages.json 注册页面，router 实现页面跳转，携带片段 ID 加载详情数据。
• 剪贴板模块：调用 PasteboardKit 写入文本，复制完成弹出 Toast 提示。
• 元服务卡片生命周期：实现 onAdd、onUpdate、onRemove；onUpdate 回调读取沙箱收藏片段；form_config.json 与 module.json5 卡片 ID 保持一致，完成卡片注册。

核心代码片段：Form 卡片 onUpdate 刷新逻辑

卡片动态刷新是鸿蒙元服务开发中的难点，下面这段核心代码由华为云码道 CodeArts Agent 生成，后续我对数据来源做了微调以便卡片数据实时更新。

import { formBindingData, formProvider } from '@kit.FormKit'; // onUpdate 回调：通过 formId 刷新卡片数据 async function onUpdate(formId: string) { const data = { title: '已更新', time: new Date().toLocaleTimeString() }; // 将数据绑定到卡片 await formProvider.updateForm(formId, formBindingData.createFormBindingData(data)); }

卡片 UI 侧通过@LocalStorageProp接收传递过来的数据，完成界面渲染：

@Entry @Component struct WidgetCard { @LocalStorageProp('title') title: string = '默认'; @LocalStorageProp('time') time: string = '--'; build() { Column() { Text(this.title).fontSize(16) Text(this.time).fontSize(12) } } }

核心在于formProvider.updateForm(formId,formBindingData.createFormBindingData(data))，调用该 API 主动推送数据至桌面卡片，实现负一屏卡片内容动态刷新。

注：Agent 初始生成版本仅演示静态文本刷新，后续我改造为读取本地沙箱内收藏代码片段，真正实现业务数据更新。

4.3 安全设计

五、功能演示与界面效果

图 12 ：代码片段管理器首页模拟器界面，以卡片形式提供全部功能导航入口，集成帮助与主题切换控件；左图为浅色主题首页，右图为深色主题首页。

图 13 ：代码片段模块界面演示。左图为片段列表页，支持搜索、标签筛选；中图为片段详情页，展示完整代码，提供复制、导出等操作；右图为新建片段页面，支持填写信息、选择编程语言、绑定标签，完成代码片段创建

图 14 ：导入 / 导出模块界面演示。左图为导入导出主页，支持导出、剪贴板导入、备份恢复；中图为导出成功弹窗，展示文件信息，支持复制路径；右图为备份删除确认弹窗，防止误操作。

图 15 ：代码工具模块界面演示。左图为 JSON 格式化页面，校验语法并美化输出；右图为：代码统计页面，统计字符、总行数、有效代码行与空行，辅助快速统计代码规模。

图 16 ：元服务卡片配置与负一屏展示界面演示。左图为卡片设置页面，提供 3 种卡片展示模式；右图为鸿蒙负一屏效果，展示代码片段元服务卡片，点击卡片可唤起应用。

六、技术难点、人机协作记录和解决方案

难点 1：UI 布局留白异常，筛选栏下方大片空白，卡片列表下移

初次提交需求仅简单要求页面布局整洁，智能体生成代码后，模拟器出现筛选栏下方大面积留白，片段列表被挤压至页面底部。

• 第一轮反馈：提交模拟器截图反馈现象，智能体仅微调组件间距，未能定位多余 Blank 自动填充组件，问题没有根治。
• 第二轮反馈：提供布局相关源码，明确要求排查 Blank 组件、Scroll 边距、layoutWeight 布局属性。

解决方案：智能体扫描页面布局代码，移除无意义 Blank 填充组件；清除 Scroll 外层多余外边距与内边距，取消 layoutWeight 挤压布局，让片段列表紧贴筛选区域。

​​​​​

图17 ：左图为优化前，筛选按钮下方存在大片空白，代码卡片被挤压至页面底部；右图为优化完成后，消除多余留白，卡片列表紧贴筛选区域。

难点 2：页面控件被系统状态栏遮挡，右上角按钮无法点击

初次生成 UI 页面时，需求描述未加入鸿蒙安全区域适配约束，智能体采用全屏渲染方案，页面顶部交互按钮被系统状态栏遮挡，点击失效。

• 迭代反馈：提交模拟器截图，说明控件被系统 UI 遮挡的问题。

解决方案：智能体在页面外层增加 SafeArea 安全区域组件，开启顶部区域避让，同步微调组件内边距，既解决点击遮挡问题，也改善页面拥挤的观感。

图 18 ：左图为修复前，页面右上角功能按钮被系统状态栏遮挡；右图为使用 SafeArea 安全区域组件修复后，页面顶部控件完整展示，按钮可正常交互。

难点 3：元服务卡片开发与生命周期适配

初始需求仅要求负一屏卡片展示收藏片段，未说明 Form 卡片生命周期限制。智能体完成基础卡片 UI，但卡片无法感知应用内数据变更，新增收藏片段后负一屏内容不会自动刷新。

• 迭代反馈：提交卡片不更新现象，补充鸿蒙卡片无法主动监听应用数据的平台特性，要求在 onUpdate 回调中读取沙箱数据。

解决方案：智能体补全 Form 完整生命周期回调，在 onUpdate 事件重新读取沙箱内收藏片段；对齐 form_config.json 与 module.json5 内卡片 ID，修复卡片注册失败、内容不刷新缺陷。

难点 4：工程配置混淆、状态管理与路由逻辑隐性 BUG

首轮生成代码时，智能体混淆根目录与 entry 模块下 build-profile.json5 配置字段，触发 hvigor 编译校验报错；同时新增片段保存返回首页、新增标签后，页面列表无法刷新数据。

• 第一轮反馈：粘贴编译日志修复 json5 配置，但页面响应式 BUG 依旧存在。
• 第二轮反馈：复现完整操作流程并附上截图，定位两处根源：直接用 push() 修改 @Trace 数组无法触发 V2 响应式更新；router.clear() 清空路由栈，破坏页面生命周期，页面重新进入不会重载数据。

解决方案：将数组更新逻辑改为新数组赋值，触发响应式刷新；把router.clear()+pushUrl替换为router.replaceUrl，并在首页 onPageShow 生命周期加载沙箱 JSON 数据，保证每次页面唤起均可读取最新数据。

人机协作小结

智能体可以快速搭建基础代码框架，但容易忽略鸿蒙平台特有机制，例如安全区适配、卡片生命周期、V2 响应式、路由特性。如果需求缺少平台约束，会引入隐性 BUG，开发中需要人工在模拟器复现缺陷，结合截图、操作步骤、报错日志提交给智能体，通过多轮调试引导智能体定位并修复问题。

七、项目测试

测试环境统一：DevEco Studio，Mate 90 Pro 鸿蒙模拟器。测试分为单元测试和人工模拟器验收测试两部分。

7.1 单元测试

基于 ohosTest 框架，针对底层工具类、数据模型、沙箱读写编写 12 条用例，覆盖读写、空文件、非法 JSON、标签序列化场景。

执行单元测试命令：

hvigorw test

单元测试全部通过，验证底层函数正确性。单元测试仅保证底层逻辑，不可替代页面交互与卡片模拟器验证。

7.2 人工验收测试

模拟器全流程验收，覆盖常规与边界场景：片段增删改查、检索复制、卡片刷新；异常场景包含损坏 JSON 导入、空片段提交。验收全部通过，异常场景捕获异常，程序无崩溃。

八、码道智能体使用心得

本项目通过对照实验对比两套码道开发链路：网页工作台适合快速原型，但元服务配置易出错；CodeArts Agent IDE 深度适配鸿蒙，自动维护工程，对 Stage、Form 卡片支持更好。借助码道智能体，自然语言即可快速搭建项目骨架，节省基础编码工作量。

但 AI 输出代码不能直接交付，存在布局、配置、生命周期等缺陷，开发者仍需要掌握鸿蒙基础，完成测试、定位问题，结合日志截图持续迭代。

九、后续可优化方向以及开源说明

项目已实现片段管理、标签检索、导入导出、元服务卡片基础能力。后续可迭代方向：增加代码语法高亮；完善标签分组；增强备份策略；优化负一屏卡片交互；迁移项目至 API12 适配新版鸿蒙。源码开源，欢迎同好们二次开发。

9.1 项目仓库与源码说明

项目源码托管于 AtomGit，遵循 Apache 2.0 开源协议。

harmony-code-snippet-widget_仓库

图 19 ：源码托管于 AtomGit 码道平台，仓库含完整鸿蒙元服务代码、README 说明文档、开源协议 LICENSE、功能说明文档 FEATURES.md 与测试用例 TEST_CASE.md等。

9.2 项目运行方式

# 克隆仓库 git clone https://atomgit.com/gcw_Un3J6cce/harmony-code-snippet-widget.git

1. 使用 DevEco Studio 打开项目；
2. 配置对应 SDK 版本（API10）；
3. 选择模拟器；
4. 执行 hvigor 编译，运行 HAP；
5. 执行单元测试：hvigorw test