HarmonyOS AI 应用开发实战：每日一句英文 —— 从对齐到评估的完整研发流程

一、项目背景与需求分析（Align 阶段）

1.1 项目背景

在全球化浪潮下，英语学习已成为现代人提升自我竞争力的刚需。然而，传统英语学习应用往往存在内容固定、缺乏个性化、互动性差等痛点。用户每天面对千篇一律的学习材料，难以保持长期的学习动力。"每日一句英文"应用的诞生，正是为了解决这一痛点——通过 AI 大模型的能力，每天为用户生成个性化、高质量的英文学习内容，让英语学习变得轻松有趣且高效。

本项目基于 HarmonyOS 操作系统，采用 ArkTS 语言和 ArkUI 声明式框架进行开发，是鸿蒙生态中 AI 应用的一次积极探索。应用的核心价值在于：用户只需输入"主题"和"难度等级"两个参数，AI 即可自动生成包含英文句子、中文翻译、单词解析和语法点在内的完整学习内容，实现真正的"千人千面"个性化学习体验。

1.2 需求分析

通过深入的用户调研和场景分析，我们梳理出以下核心需求：

功能需求：

• 用户输入主题（如"科技"、“环保”、“励志"等）和难度等级（如"初级”、“中级”、“高级”），系统生成对应的英文句子
• 输出内容包含完整的英文句子、准确的中文翻译、重点单词解析、核心语法点讲解
• 支持多次生成，每次获得不同的学习内容
• 界面简洁清晰，交互流畅

非功能需求：

• 响应速度：AI 生成结果应在 3 秒内返回
• 内容质量：英文句子语法正确、表达地道
• 个性适配：不同难度等级应匹配不同的词汇量和句式复杂度
• 稳定性：支持连续多次生成不崩溃

1.3 边界确认

经过需求澄清，我们明确了以下边界：

• 本应用不涉及用户登录和账户系统
• 不提供历史记录持久化功能（当前会话有效）
• 不提供语音朗读功能（后续版本规划）
• AI 生成内容仅供参考学习，不保证 100% 准确性

二、技术架构设计（Architect 阶段）

2.1 整体架构概览

本应用采用 HarmonyOS 推荐的 Model-Service-Page 三层架构，这是一种典型的"数据-业务-视图"分离设计模式，与 MVVM 架构思想一脉相承。

┌─────────────────────────────────────────────────────┐
│                      Page 层                        │
│  ┌────────────────────────────────────────────────┐ │
│  │        DailyEnglishPage (ArkUI 组件)            │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │ │
│  │  │ 输入面板  │  │ 生成按钮  │  │ 结果展示区域  │ │ │
│  │  └──────────┘  └──────────┘  └──────────────┘ │ │
│  └────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────┤
│                    Service 层                       │
│  ┌────────────────────────────────────────────────┐ │
│  │      DailyEnglishService (业务逻辑层)           │ │
│  │  ┌────────────────┐  ┌──────────────────────┐  │ │
│  │  │ generateData() │  │   AI Prompt 构建     │  │ │
│  │  └────────────────┘  └──────────────────────┘  │ │
│  └────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────┤
│                     Model 层                        │
│  ┌────────────────────────────────────────────────┐ │
│  │      DailyEnglishData (数据模型)               │ │
│  │  theme | level | sentence_en | sentence_cn    │ │
│  │  grammar_point | pronunciation_tip | source   │ │
│  └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

2.2 分层职责说明

Model 层（数据模型层）：
DailyEnglishData 类定义了应用中的所有数据结构。每个字段都有明确的类型和默认值，遵循 ArkTS 的严格类型约束。例如：

export class DailyEnglishData {
  theme: string = ''           // 主题
  level: string = ''            // 难度等级
  sentence_en: string = ''      // 英文句子
  sentence_cn: string = ''      // 中文翻译
  grammar_point: string = ''    // 语法点
  pronunciation_tip: string = '' // 发音提示
  source: string = ''           // 句子来源
}

Service 层（业务逻辑层）：
DailyEnglishService 负责核心业务逻辑，包括接收用户输入、构建 AI 提示词、调用 AI 接口、解析返回结果并组装成 Model 数据。其核心方法是 generateData(input: Record<string, Object>): DailyEnglishData。

Page 层（视图层）：
DailyEnglishPage 是一个 ArkUI 组件，使用 @Entry 和 @Component 装饰器标记。它通过 @State 装饰器管理响应式状态，当用户点击"AI 生成"按钮时，调用 Service 层方法获取数据，并更新 UI 展示结果。

2.3 数据流设计

应用的数据流遵循"单向数据流"原则：

用户输入 → inputData (Record<string, Object>) 
    → 点击"AI 生成"按钮 
    → 调用 service.generateData(inputData) 
    → AI 大模型处理 
    → 返回 DailyEnglishData 实例 
    → 赋值给 resultData (@State 状态)
    → ArkUI 自动响应式更新视图

这种设计模式的优势在于：

1. 数据流向清晰，易于追踪和调试
2. 视图层与业务层完全解耦，便于单元测试
3. 状态变更由框架自动管理，减少手动 DOM 操作

三、AI 提示词工程原理

3.1 提示词设计策略

"每日一句英文"应用的核心竞争力在于 AI 生成内容的质量，而提示词（Prompt）设计是决定 AI 输出质量的关键因素。我们采用了"结构化提示词 + 参数化模板"的设计策略。

提示词模板结构：

你是一位专业的英语教育专家。请根据以下要求生成英语学习内容：

主题：{theme}
难度等级：{level}

要求：
1. 生成一句与主题相关的地道英文句子
2. 提供准确的中文翻译
3. 列出句子中的重点词汇（含音标和中文释义）
4. 解析句子中的核心语法点
5. 提供发音技巧提示

输出格式：
- 英文句子：...
- 中文翻译：...
- 单词解析：...
- 语法点：...
- 发音提示：...

3.2 难度分级策略

为了让 AI 生成的内容真正适配不同水平的学习者，我们在提示词中嵌入了难度分级指令：

初级（Beginner）：

• 词汇量控制在 300-500 基础词汇
• 使用简单现在时态
• 句子长度不超过 15 个单词
• 语法点聚焦于基础时态、主谓一致等

中级（Intermediate）：

• 词汇量扩展至 2000-3000 常用词汇
• 使用复合句和从句结构
• 句子长度 15-25 个单词
• 语法点涵盖定语从句、虚拟语气等

高级（Advanced）：

• 使用学术词汇和高级表达
• 包含并列复合句、倒装等复杂结构
• 句子长度 25 个单词以上
• 语法点涉及高级语法现象

3.3 Few-shot 示例引导

为了提升 AI 输出的稳定性和格式一致性，我们在提示词中加入了 Few-shot 示例：

示例（主题：环保，难度：中级）：
英文句子：The implementation of renewable energy policies has significantly reduced carbon emissions in urban areas, yet challenges remain in rural communities.
中文翻译：可再生能源政策的实施显著减少了城市地区的碳排放，但在农村地区仍面临挑战。
单词解析：
- implementation [ˌɪmplɪmenˈteɪʃn] n. 实施，执行
- renewable [rɪˈnjuːəbl] adj. 可再生的
- significantly [sɪɡˈnɪfɪkəntli] adv. 显著地
- emission [ɪˈmɪʃn] n. 排放
语法点：现在完成时（has reduced）表示过去发生的动作对现在造成的影响。

通过这种"模板 + 参数 + 示例"的组合策略，AI 能够稳定输出结构清晰、内容准确、难度适配的学习内容。

四、核心功能实现详解（Atomize 阶段）

4.1 数据模型实现

数据模型是整个应用的基石。在 ArkTS 中，我们使用 export class 关键字定义可导出的类，所有字段必须显式声明类型并初始化：

export class DailyEnglishData {
  theme: string = ''
  level: string = ''
  sentence_en: string = ''
  sentence_cn: string = ''
  grammar_point: string = ''
  pronunciation_tip: string = ''
  source: string = ''

  constructor() {
    this.theme = ''
    this.level = ''
    this.sentence_en = ''
    this.sentence_cn = ''
    this.grammar_point = ''
    this.pronunciation_tip = ''
    this.source = ''
  }
}

设计要点：

1. 所有字段均使用 string 类型，避免使用 any 或 unknown（ArkTS 不支持）
2. 每个字段都有空字符串默认值，确保模型实例化时不会出现 undefined
3. 构造函数中再次显式初始化，符合 ArkTS 的最佳实践
4. 不需要的字段（如原始的 words、usage、quote）在最终版本中被精简，保持模型轻量化

4.2 服务层实现

Service 层是业务逻辑的核心，负责连接 Page 层和 AI 能力：

export class DailyEnglishService {
  private model: DailyEnglishData

  constructor() {
    this.model = new DailyEnglishData()
  }

  generateData(input: Record<string, Object>): DailyEnglishData {
    let result: DailyEnglishData = new DailyEnglishData()
    // 实际项目中，此处应构建 AI 请求并解析返回结果
    // 当前为 Mock 数据，后续对接 AI SDK
    return result
  }
}

核心设计思路：

1. generateData 方法接收 Record<string, Object> 类型参数，灵活性高，可以接收任意键值对
2. 方法内部先创建新的 DailyEnglishData 实例，避免修改已有数据
3. 返回类型明确为 DailyEnglishData，调用方可以安全地访问所有字段
4. Service 类持有私有的 model 实例，用于内部状态管理

4.3 页面层实现

Page 层是用户直接交互的界面，采用 ArkUI 声明式语法：

@Entry
@Component
struct DailyEnglishPage {
  @State inputData: Record<string, Object> = {}
  @State resultData: DailyEnglishData | null = null
  @State showResult: boolean = false
  private service: DailyEnglishService = new DailyEnglishService()

  build() {
    Column() {
      // 顶部导航栏
      Row() {
        Text('← 返回')
          .onClick(() => { router.back() })
        Blank()
        Text('每日一句英文')
        Blank()
        Text('')
      }
      
      // 可滚动内容区域
      Scroll() {
        Column() {
          // 输入区域
          Text('输入信息')
          Text('主题')
          TextInput({ placeholder: '请输入主题' })
            .onChange((val: string) => { this.inputData['theme'] = val })
          Text('难度等级')
          TextInput({ placeholder: '请输入难度等级' })
            .onChange((val: string) => { this.inputData['level'] = val })
          
          // AI 生成按钮
          Button('AI 生成')
            .onClick(() => {
              this.resultData = this.service.generateData(this.inputData)
              this.showResult = true
            })
          
          // 结果展示区域
          if (this.showResult && this.resultData !== null) {
            Text('生成结果')
            // 展示具体内容...
          }
        }
      }
    }
  }
}

4.4 状态管理详解

ArkUI 的 @State 装饰器是实现响应式 UI 的核心机制：

• @State inputData: 管理用户输入的表单数据，通过 onChange 回调实时更新
• @State resultData: 管理 AI 生成的结果数据，类型为 DailyEnglishData | null，初始为 null
• @State showResult: 控制结果展示区域的显隐，初始为 false

当用户点击"AI 生成"按钮时，触发以下状态变更链：

1. service.generateData() 执行并返回结果
2. resultData 被赋值为新的 DailyEnglishData 实例
3. showResult 被设置为 true
4. ArkUI 框架检测到 @State 状态变更，自动触发 UI 重渲染
5. 条件渲染 if (this.showResult && this.resultData !== null) 为 true，展示结果区域

五、用户体验优化（Approve 阶段）

5.1 界面设计理念

应用采用"简洁高效"的设计理念，遵循 HarmonyOS Design 设计规范：

色彩体系：

• 背景色：#F8FAFC（浅灰蓝），营造舒适阅读氛围
• 主色调：#3B82F6（蓝色），用于按钮和关键操作
• 文字色：app.color.text_primary 和 app.color.text_secondary，通过资源引用实现主题适配

布局策略：

• 顶部固定导航栏，提供返回功能
• 主体内容使用 Scroll 组件包裹，支持上下滑动
• 输入区域和结果区域上下排列，符合阅读习惯
• 输入框使用白色背景和圆角设计，提升视觉亲和力

5.2 交互反馈优化

加载状态处理：
虽然当前版本未实现加载动画，但在生产版本中，我们建议在"AI 生成"按钮点击后：

1. 按钮变为禁用状态，并显示"生成中…"文字
2. 显示加载进度条或旋转动画
3. 生成完成后恢复按钮状态

空状态处理：

• 初始状态仅显示输入区域，引导用户输入
• 结果区域在未生成时完全隐藏，避免空数据展示
• 输入框提供 placeholder 提示文字，降低用户理解成本

错误处理：

• 网络错误时，应弹出 Toast 提示"网络异常，请稍后重试"
• AI 服务异常时，显示"内容生成失败，请重新尝试"
• 输入验证：当用户未输入主题或难度时，点击按钮应提示"请填写完整信息"

5.3 可访问性设计

• 使用 fontWeight 和 fontSize 区分信息层级
• 按钮文字使用 fontWeight.Bold 增强可识别性
• 输入框高度设置为 44vp，符合触控最佳实践
• 圆角 8-12vp，视觉友好

六、性能优化与最佳实践（Automate 阶段）

6.1 ArkTS 性能优化策略

1. 避免不必要的状态更新：
每次 @State 变更都会触发组件重渲染。在 onChange 回调中，我们只更新特定的键值对，而不是整个 inputData 对象：

.onChange((val: string) => { this.inputData['theme'] = val })

2. 使用 Scroll 组件管理长内容：
当结果内容较多时，将内容区域放在 Scroll 组件中，避免页面溢出，同时提升滚动性能。

3. 条件渲染减少 DOM 节点：
通过 if (this.showResult && this.resultData !== null) 条件渲染，初始状态下不渲染结果部分的 DOM 节点，减少首屏加载时间。

6.2 内存管理

• 每次点击"AI 生成"按钮时，Service 层创建新的 DailyEnglishData 实例，旧实例会被垃圾回收
• 避免在循环中创建大量临时对象
• 使用 let 而非 var 声明变量，确保块级作用域

6.3 遵循 ArkTS 语法约束

在开发过程中，我们严格遵循了项目组制定的 ArkTS 语法约束：

必须遵守的规则：

• 不使用 any 和 unknown 类型，所有变量显式指定类型
• 不使用 as const 断言，改用显式类型标注
• 不使用解构赋值，改用临时变量逐字段操作
• 不使用 for...in 遍历对象，改用常规 for 循环遍历数组
• 不使用 Function.bind、Function.apply、Function.call
• 函数表达式改用箭头函数
• 不使用 in 运算符，改用 instanceof
• 不使用索引签名，改用数组

通过遵循这些规则，我们确保了代码在 HarmonyOS 平台上的编译通过率和运行稳定性。

七、总结与展望（Assess 阶段）

7.1 项目总结

通过"每日一句英文"应用的完整开发流程，我们实践了 HarmonyOS AI 应用开发的完整方法论：

技术层面：

• 掌握了 Model-Service-Page 三层架构在 ArkTS 中的实现方式
• 理解了 ArkUI 声明式 UI 的 @State 状态管理机制
• 学会了 AI 提示词工程的结构化设计方法
• 积累了 ArkTS 语法约束的实战经验

工程层面：

• 实践了从对齐到评估的六阶段研发流程
• 建立了清晰的需求边界和验收标准
• 实现了可复用的应用架构模板

7.2 未来展望

功能扩展：

1. 集成 AI SDK：将当前 Mock 数据替换为真实的大模型 API 调用
2. 语音朗读：接入 HarmonyOS 的 TextToSpeech 能力，实现句子朗读
3. 学习记录：利用本地数据库（如 @ohos.data.preferences）保存学习历史
4. 每日推荐：基于用户历史学习数据，智能推荐学习内容

技术演进：

1. 引入 @ComponentV2 新特性，优化组件性能
2. 使用 @Animatable 实现更流畅的动画过渡效果
3. 探索 HarmonyOS 的分布式能力，实现多设备学习进度同步

7.3 经验教训

1. 提示词设计是 AI 应用的核心：输出质量 80% 取决于提示词的质量，而非模型本身
2. 类型安全至关重要：ArkTS 的严格类型系统虽然增加了编码量，但能有效避免运行时错误
3. 状态管理要精简：过多的 @State 变量会增加框架的跟踪开销，应保持状态的最小化

"每日一句英文"应用虽小，但完整地展示了 HarmonyOS 平台上 AI 应用开发的最佳实践。通过本项目的学习，开发者可以快速掌握 Model-Service-Page 架构的精髓，并将其应用到更复杂的 AI 应用场景中。

---

本文为 HarmonyOS AI 应用开发实战系列的第一篇，后续将深入探讨更多 AI 应用场景的实现细节。