HarmonyOS NEXT AI 智能生活助手：创建企业级 AI 工程与目录结构

HarmonyOS NEXT AI 智能生活助手创建企业级 AI 工程与目录结构前言在上一篇 [项目规划与架构设计] 中我们详细介绍了 HarmonyAI 的整体架构和 30 篇博客规划。本文是系列的第02 篇将带领大家从零开始创建一个企业级的 HarmonyOS NEXT AI 工程。企业级工程不是简单的新建项目而是按照生产级标准搭建项目骨架包括目录结构、模块划分、依赖管理、代码规范等。好的工程结构是后续 28 篇博客的基础。本文将涵盖两阶段创建流程先创建基础工程再搭建企业级目录结构完整目录树18 个模块目录设计核心配置build-profile.json5、oh-package.json5、hvigorfile.ts首个页面验证项目可编译运行Git 初始化版本控制与 Tag 管理图1HarmonyAI 企业级目录结构树一、创建基础工程1.1 环境准备在开始之前请确保已安装以下开发环境工具版本要求说明DevEco Studio5.0HarmonyOS NEXT 官方 IDEHarmonyOS SDK5.0.0API 12Node.js18用于 hvigor 构建Git2.30版本控制1.2 使用 DevEco Studio 创建基础工程打开 DevEco Studio按以下步骤操作点击Create Project选择Empty Ability模板配置项目信息配置项值说明Project NameHarmonyAI项目名称Bundle Namecom.harmonyai.app应用包名Save Location自定义路径建议不含中文字符Compatible API12API 版本ModelStage应用模型LanguageArkTS开发语言Device TypePhone目标设备1.3 创建完成后生成的目录DevEco Studio 默认生成的项目结构如下HarmonyAI/ ├── AppScope/ │ ├── app.json5 # 应用配置 │ └── resources/ # 应用级资源 ├── entry/ │ ├── src/ │ │ ├── main/ │ │ │ ├── ets/ │ │ │ │ ├── entryability/ │ │ │ │ │ └── EntryAbility.ts │ │ │ │ └── pages/ │ │ │ │ └── Index.ets │ │ │ └── resources/ │ │ └── module.json5 │ ├── build-profile.json5 # HAP 构建配置 │ └── oh-package.json5 # 依赖配置 ├── hvigor/ │ └── hvigor-config.json5 ├── hvigorfile.ts # Hvigor 构建入口 ├── oh-package.json5 # 顶层依赖配置 ├── build-profile.json5 # 顶层构建配置 └── local.properties # 本地 SDK 路径二、搭建企业级目录结构2.1 设计思路企业级目录结构遵循以下原则按功能模块划分每个目录有明确的职责高内聚低耦合模块间通过接口通信可扩展性新增功能不需要改动现有目录领域驱动按业务领域组织代码根据 Project-Design.md 的规划我们需要在entry/src/main/ets/下新增以下目录2.2 完整目录树ets/ ├── entryability/ │ └── EntryAbility.ts # Ability 入口 ├── pages/ # 页面目录12-15 个页面 │ ├── SplashPage.ets # 启动页 │ ├── HomePage.ets # 首页 │ ├── ChatPage.ets # AI 聊天页 │ ├── OCRPage.ets # OCR 识别页 │ ├── TranslatePage.ets # 翻译页 │ ├── FlowerPage.ets # 每日花语页 │ ├── SummaryPage.ets # 文章总结页 │ ├── CodePage.ets # 代码解释页 │ ├── TodoPage.ets # 待办生成页 │ ├── SchedulePage.ets # 日程规划页 │ ├── SettingPage.ets # 设置页 │ └── AboutPage.ets # 关于页 ├── components/ # 公共组件 │ ├── ChatBubble.ets # 聊天气泡 │ ├── MarkdownView.ets # Markdown 渲染 │ ├── TypingView.ets # 打字机效果 │ ├── PromptCard.ets # Prompt 卡片 │ ├── AIAvatar.ets # AI 头像 │ ├── MessageItem.ets # 消息列表项 │ ├── InputBar.ets # 输入栏 │ ├── ModelSelector.ets # 模型选择器 │ ├── LoadingView.ets # 加载动画 │ ├── HistoryCard.ets # 历史卡片 │ ├── CodeBlock.ets # 代码块 │ ├── Toolbar.ets # 工具栏 │ ├── ImagePicker.ets # 图片选择器 │ ├── OCRCard.ets # OCR 结果卡片 │ └── SettingItem.ets # 设置项 ├── common/ # 公共模块 │ ├── Logger.ts # 日志工具 │ ├── Constants.ts # 全局常量 │ └── Types.ts # 全局类型定义 ├── repository/ # 数据仓库层 │ ├── ChatRepository.ts # 聊天数据仓库 │ ├── ConversationRepository.ts # 会话仓库 │ ├── PromptRepository.ts # Prompt 仓库 │ └── SettingsRepository.ts # 设置仓库 ├── service/ # 服务层 │ └── AIService.ts # AI 服务统一入口 ├── provider/ # LLM Provider │ ├── LLMProvider.ts # Provider 接口 │ ├── OpenAIProvider.ts # OpenAI │ ├── DeepSeekProvider.ts # DeepSeek │ ├── QwenProvider.ts # 通义千问 │ ├── ZhipuProvider.ts # 智谱 AI │ └── DoubaoProvider.ts # 豆包 ├── ai/ # AI 能力模块 │ ├── ChatManager.ts # 聊天管理 │ ├── TranslateManager.ts # 翻译管理 │ ├── OCRManager.ts # OCR 管理 │ ├── SummaryManager.ts # 总结管理 │ ├── FlowerManager.ts # 花语管理 │ ├── TodoManager.ts # 待办管理 │ ├── ScheduleManager.ts # 日程管理 │ └── CodeManager.ts # 代码解释管理 ├── prompt/ # Prompt 管理 │ ├── PromptManager.ts # Prompt 管理器 │ └── templates/ # Prompt 模板文件 │ ├── chat.md │ ├── translate.md │ ├── flower.md │ ├── summary.md │ ├── todo.md │ ├── schedule.md │ ├── code.md │ └── system.md ├── model/ # 数据模型 │ ├── ChatMessage.ts # 聊天消息 │ ├── Conversation.ts # 会话 │ ├── Prompt.ts # Prompt │ ├── ModelConfig.ts # 模型配置 │ └── AIResponse.ts # AI 响应 ├── database/ # 数据库 │ ├── DatabaseManager.ts # 数据库管理器 │ └── tables/ # 表定义 ├── theme/ # 主题管理 │ ├── ThemeManager.ts # 主题管理器 │ ├── LightTheme.ts # 浅色主题 │ └── DarkTheme.ts # 深色主题 ├── constants/ # 常量 │ ├── AppConstants.ts # 应用常量 │ └── ApiConstants.ts # API 常量 └── utils/ # 工具类 ├── AIUtil.ts # AI 工具 ├── MarkdownUtil.ts # Markdown 工具 ├── PromptUtil.ts # Prompt 工具 ├── JsonUtil.ts # JSON 工具 ├── ImageUtil.ts # 图片工具 ├── OCRUtil.ts # OCR 工具 ├── RouterUtil.ts # 路由工具 ├── ToastUtil.ts # Toast 工具 ├── ThemeUtil.ts # 主题工具 └── PreferenceUtil.ts # 偏好存储工具完整的目录结构包含18 个一级目录、30 个页面和组件、10 工具类覆盖了企业级 AI 应用的所有模块。三、核心配置文件3.1 build-profile.json5顶层{ app: { products: [ { name: default, signingConfig: default } ], buildSettings: { compatibleSdkVersion: 5.0.0, compileSdkVersion: 5.0.0, targetSdkVersion: 5.0.0 } }, modules: [ { name: entry, srcPath: ./entry, buildProfile: ./entry/build-profile.json5 } ] }3.2 module.json5Entry 模块{ module: { name: entry, type: entry, description: HarmonyAI 主模块, mainAbility: EntryAbility, deviceTypes: [phone], abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ts, description: 应用主入口, icon: $media:app_icon, label: $string:app_name, startWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background } ], requestPermissions: [ { name: ohos.permission.INTERNET }, { name: ohos.permission.READ_MEDIA }, { name: ohos.permission.CAMERA } ] } }注意INTERNET权限用于 AI API 调用READ_MEDIA和CAMERA用于 OCR 图片识别功能。3.3 oh-package.json5Entry 模块{ name: entry, version: 1.0.0, description: HarmonyAI entry module, dependencies: { ohos/axios: ^2.2.0, ohos/data-preferences: ^1.0.0, ohos/data.persistence: ^1.0.0, ohos.multimedia.image: ^1.0.0, ohos.multimedia.camera: ^1.0.0, kit.MediaLibraryKit: ^1.0.0 } }四、创建首个验证页面4.1 EntryAbility 入口// entryability/EntryAbility.tsimportUIAbilityfromohos.app.ability.UIAbility;importwindowfromohos.window;importdisplayfromohos.display;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want,launchParam){hilog.info(0x0000,HarmonyAI,Ability onCreate);}onDestroy(){hilog.info(0x0000,HarmonyAI,Ability onDestroy);}asynconWindowStageCreate(windowStage:window.WindowStage){hilog.info(0x0000,HarmonyAI,onWindowStageCreate);// 安全区处理获取状态栏和导航栏高度并转换为 vpawaitthis.initSafeArea();windowStage.loadContent(pages/SplashPage,(err,data){if(err.code){hilog.error(0x0000,HarmonyAI,Failed to load content. Cause: %{public}s,JSON.stringify(err));return;}hilog.info(0x0000,HarmonyAI,Succeeded in loading content);});}// 初始化安全区高度privateasyncinitSafeArea():Promisevoid{try{constdefaultDisplaydisplay.getDefaultDisplaySync();constdensityPixelsdefaultDisplay.densityPixels;// 获取窗口实例constwindowClassawaitwindow.getLastWindow(this.context);// 获取状态栏高度px 转 vpconststatusBarHeightPxwindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM).topRect.height;conststatusBarHeightstatusBarHeightPx/densityPixels;// 获取导航栏高度px 转 vpconstnavBarHeightPxwindowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR).bottomRect.height;constnavBarHeightnavBarHeightPx/densityPixels;// 存储到 AppStorage供所有页面共享AppStorage.setOrCreatenumber(statusBarHeight,statusBarHeight);AppStorage.setOrCreatenumber(navBarHeight,navBarHeight);hilog.info(0x0000,HarmonyAI,SafeArea statusBar: %{public}.2f vp, navBar: %{public}.2f vp,statusBarHeight,navBarHeight);}catch(error){hilog.error(0x0000,HarmonyAI,Failed to init safe area: %{public}s,error.message);// 使用默认值兜底AppStorage.setOrCreatenumber(statusBarHeight,32);AppStorage.setOrCreatenumber(navBarHeight,24);}}onWindowStageDestroy(){hilog.info(0x0000,HarmonyAI,onWindowStageDestroy);}onForeground(){hilog.info(0x0000,HarmonyAI,onForeground);}onBackground(){hilog.info(0x0000,HarmonyAI,onBackground);}}4.2 启动页SplashPage// pages/SplashPage.etsEntryComponentstruct SplashPage{StateopacityValue:number0;StatescaleValue:number0.8;aboutToAppear(){// 启动动画animateTo({duration:1000,curve:Curve.FastOutSlowIn},(){this.opacityValue1;this.scaleValue1;});// 延迟跳转首页setTimeout((){RouterUtil.navigateTo(pages/HomePage);},2000);}build(){Column(){// LogoImage($r(app.media.app_icon)).width(120).height(120).opacity(this.opacityValue).scale({x:this.scaleValue,y:this.scaleValue})// 应用名称Text($r(app.string.app_name)).fontSize(28).fontWeight(FontWeight.Bold).margin({top:24}).opacity(this.opacityValue)// 应用描述Text(AI 智能生活助手).fontSize(16).fontColor(Color.Gray).margin({top:8}).opacity(this.opacityValue)}.width(100%).height(100%).justifyContent(FlexAlign.Center).backgroundColor($r(app.color.splash_background));}}4.3 验证编译在 DevEco Studio 中执行以下验证# 1. 清理项目hvigorw clean# 2. 编译 HAPhvigorw assembleHap# 3. 编译成功输出BUILD SUCCESSFULin30s出现BUILD SUCCESSFUL说明项目创建成功企业级目录结构搭建完成。五、Git 初始化5.1 创建 .gitignore# HarmonyOS.idea/ .gradle/ build/ local.properties *.hprof *.iml# Nodenode_modules/ .hvigor/# OS.DS_Store Thumbs.db# IDE*.swp *.swo5.2 初始化 Git 仓库# 初始化仓库gitinit# 添加文件gitadd.# 首次提交gitcommit-mfeat(init): 初始化企业级 AI 工程 - 创建 HarmonyOS NEXT 基础工程 - 搭建 18 个模块的企业级目录结构 - 配置 build-profile.json5、module.json5 - 实现启动页与基本动画 - 配置 Git 版本管理 Co-Authored-By: AtomCode (deepseek-v4-flash) noreplyatomgit.com# 创建 Taggittag v0.0.1六、验证清单6.1 项目结构完整性检查检查项要求状态一级目录18 个✅页面文件12 个✅组件文件15 个✅工具类10 个✅Provider5 个✅Prompt 模板8 个✅数据模型5 个✅配置文件3 个✅6.2 编译运行检查DevEco Studio打开项目无错误hvigorw assembleHap编译成功启动页动画正常显示路由跳转到首页正常如果以上检查项全部通过说明企业级工程创建成功七、企业级目录结构最佳实践7.1 分层依赖规则各层的依赖关系必须遵循以下规则pages/ → components/ → common/ pages/ → repository/ → service/ → provider/ service/ → ai/ → prompt/ repository/ → database/ components/ → theme/ → constants/禁止页面层直接调用 Provider 或 PromptManager必须通过 AIService 统一封装。7.2 模块职责矩阵模块对外暴露内部依赖禁止依赖pages页面组件components, repositoryprovider, aicomponentsUI 组件theme, constantsrepository, servicerepository数据接口database, modelpages, componentsserviceAI 服务provider, ai, promptpages, componentsproviderLLM 接口constants业务层promptPrompt 模板无无model类型定义无无7.3 命名规范// 1. 文件命名大驼峰// 正确ChatPage.ets, AIService.ts// 错误chatPage.ets, ai_service.ts// 2. 类/接口命名大驼峰interfaceChatMessage{}classAIService{}// 3. 方法命名小驼峰sendMessage()loadPrompts()// 4. 常量命名全大写 下划线constAPI_BASE_URLhttps://api.example.comconstMAX_RETRY_COUNT37.4 HarmonyOS NEXT 开发关键注意事项在企业级 HarmonyOS NEXT 开发中以下细节直接影响应用的稳定性和用户体验1. 安全区适配所有页面必须通过AppStorage获取安全区高度避免内容被状态栏或导航栏遮挡// pages/AnyPage.etsEntryComponentstruct AnyPage{// 从 AppStorage 读取安全区高度StorageLink(statusBarHeight)statusBarHeight:number32;StorageLink(navBarHeight)navBarHeight:number24;build(){Column(){// 顶部占位避开状态栏Row().width(100%).height(this.statusBarHeight);// 页面内容...// 底部占位避开导航栏Row().width(100%).height(this.navBarHeight);}.width(100%).height(100%);}}2. SVG 矢量图标HarmonyOS NEXT 设备上emoji 会渲染为蓝色或紫色块必须使用 SVG 矢量图替代用途错误做法正确做法功能图标使用 emoji如 使用 SVG如$r(app.media.ic_search)状态标识使用 emoji如 ✅使用 SVG如$r(app.media.ic_check)装饰元素使用 emoji如 使用 SVG如$r(app.media.ic_star)重要所有图标资源应放在resources/base/media目录下统一使用Image($r(app.media.xxx))加载。3. 文件操作模式HarmonyOS NEXT 中文件打开模式使用fs.OpenMode.READ_ONLY注意不是READONLY// 正确constfileawaitfs.open(filePath,fs.OpenMode.READ_ONLY);// 错误constfileawaitfs.open(filePath,fs.OpenMode.READONLY);// 不存在此枚举八、常见问题8.1 编译报错module.json5 权限不足// 错误缺少 INTERNET 权限 // 症状网络请求失败hilog 提示 Permission denied // 解决方案在 module.json5 中添加 { name: ohos.permission.INTERNET }8.2 目录引用路径问题// 错误使用相对路径引用import{AIService}from../../service/AIService// 正确使用相对路径从 ets 开始import{AIService}from../service/AIService提示HarmonyOS NEXT 的模块解析规则为相对路径从当前文件的所在目录开始计算。九、下一步开发计划工程创建完成后下一篇将进行首页设计与开发快捷入口网格布局最近聊天列表AI 推荐卡片每日一句展示今日花语 Widget总结本文详细介绍了如何创建一个企业级的 HarmonyOS NEXT AI 工程。核心要点两阶段创建基础工程 → 企业级目录结构18 个模块目录分层清晰职责明确核心配置build-profile.json5、module.json5、oh-package.json5首个页面验证启动页确认项目可编译运行Git 初始化版本控制与 Tag 管理如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力上一篇[项目规划与架构设计]下一篇[首页设计与快捷入口实现]相关资源DevEco Studio 下载HarmonyOS NEXT 开发指南Stage 模型开发文档ArkTS 语法规范hvigor 构建工具HarmonyOS 权限配置Git 版本管理企业级 ArkTS 项目模板