HarmonyOS AI 应用开发实战：读书笔记速记模板系统

本文深入解析基于 HarmonyOS + ArkTS 的读书笔记速记模板 AI 应用的完整开发过程，从需求分析、架构设计到提示词工程、性能优化，全方位展示鸿蒙 AI 应用的开发实践。

---

一、项目背景与需求分析

1.1 阅读与笔记的痛点

在信息爆炸的时代，阅读已成为个人成长和知识积累的重要途径。然而，大量读者面临"读得多、记得少"的困境。根据调查数据显示，超过70%的读者在阅读后一个月内会遗忘书中大部分内容，而有效的笔记策略可以将知识留存率从10%提升至80%以上。

当前读书笔记领域存在以下核心痛点：

• 模板缺失：大多数读者不知道如何组织笔记结构，导致笔记混乱无序
• 效率低下：手写笔记速度慢，难以跟上阅读进度
• 质量参差：缺乏系统化的笔记方法，笔记质量因人而异
• 复用困难：笔记格式不统一，后续查找和复习效率低
  

1.2 产品功能定位

本应用致力于为读者提供智能化的读书笔记速记模板生成服务，核心功能包括：

• 模板定制：根据书籍类型（如工具书、文学小说、学术著作等）自动生成适配的笔记模板
• 风格适配：支持不同的笔记风格（如康奈尔笔记法、思维导图法、卡片笔记法）
• 结构化设计：预设笔记的各个章节和问题引导，帮助读者快速完成笔记
• 行动导向：包含可执行的行动清单模板，促进知识转化实践

1.3 技术方案选型

本应用基于以下技术栈构建：

• HarmonyOS NEXT：面向全场景的智能操作系统
• ArkTS 语言：HarmonyOS 的声明式开发语言，提供类型安全和 UI 开发支持
• ArkUI 框架：声明式 UI 开发框架，支持响应式状态管理
• Model-Service-Page 架构：三层分离架构，确保代码的可维护性和可扩展性
• 大语言模型 API：利用 AI 的语义理解能力生成个性化笔记模板

---

二、技术架构设计

2.1 架构总览

┌─────────────────────────────────────────────────────────────┐
│                        Page 层                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  NoteTemplatePage                                     │   │
│  │  ├── 输入区域：书籍类型、模板风格                      │   │
│  │  ├── 按钮区域：AI 生成触发                             │   │
│  │  └── 结果区域：笔记模板、各部分内容展示                 │   │
│  └──────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                       Service 层                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  NoteTemplateService                                  │   │
│  │  ├── Prompt 构建与优化                                 │   │
│  │  ├── AI API 调用封装                                   │   │
│  │  ├── 响应解析与数据映射                                 │   │
│  │  └── 错误处理与降级策略                                 │   │
│  └──────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                       Model 层                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  NoteTemplateData                                     │   │
│  │  ├── book_type: string（书籍类型）                     │   │
│  │  ├── template_style: string（模板风格）                │   │
│  │  ├── sections: string[]（笔记章节）                     │   │
│  │  ├── questions: string[]（引导问题）                    │   │
│  │  └── action_template: string（行动模板）               │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

2.2 Model 层：数据模型设计

NoteTemplateData 类定义了笔记模板的核心数据结构：

export class NoteTemplateData {
  book_type: string = ''
  template_style: string = ''
  sections: string[] = []
  questions: string[] = []
  action_template: string = ''

  constructor() {
    this.book_type = ''
    this.template_style = ''
    this.sections = []
    this.questions = []
    this.action_template = ''
  }
}

字段设计说明：

字段	类型	说明	示例值
book_type	string	书籍类型	“工具书”、“文学小说”
template_style	string	笔记模板风格	“康奈尔笔记法”
sections	string[]	笔记章节列表	[“核心观点”, “关键事实”, “个人思考”]
questions	string[]	引导性问题	[“这本书解决了什么问题？”]
action_template	string	行动模板内容	“将XX方法应用到下周工作中”

为什么选择 string[] 类型：在 ArkTS 中，数组类型是明确支持的。使用 string[] 而不是 Record<string, string>[]，因为笔记的章节和问题列表是顺序排列的，不需要键值对映射，使用数组更简洁高效。

2.3 Service 层：业务逻辑封装

import { NoteTemplateData } from './读书笔记速记模板Model'

export class NoteTemplateService {
  private model: NoteTemplateData

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

  generateData(input: Record<string, Object>): NoteTemplateData {
    let result: NoteTemplateData = new NoteTemplateData()
    // 1. 提取输入参数
    // 2. 构建个性化 Prompt
    // 3. 调用 AI 大模型
    // 4. 解析返回结果并填充 Model
    return result
  }
}

Service 层的关键职责：

1. 参数提取与校验：从 Record<string, Object> 中安全提取用户输入
2. Prompt 动态构建：根据用户输入和业务需求生成提示词
3. AI 调用管理：处理网络请求、超时、重试等
4. 结果解析：将 AI 返回的文本解析为结构化数据
5. 降级处理：在 AI 调用失败时提供默认模板

2.4 Page 层：UI 交互设计

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

  build() {
    Column() {
      // Header 导航栏
      Row() {
        Text('← 返回').onClick(() => { router.back() })
        Blank()
        Text('读书笔记速记')
        Blank()
        Text('')
      }
      // 内容区域
      Scroll() {
        Column() {
          // 输入区域
          // AI 生成按钮
          // 结果展示区域
        }
      }
    }
  }
}

ArkTS 装饰器说明：

• @Entry：标记该组件为页面入口
• @Component：声明这是一个自定义组件
• @State：声明响应式状态变量，当值变化时自动触发 UI 重新渲染

---

三、AI 提示词工程原理

3.1 提示词设计方法论

提示词工程是 AI 应用的核心技术之一。针对读书笔记模板生成场景，我们设计了多层次的提示词策略：

3.1.1 第一层：角色与目标设定

你是一位专业的阅读教练和笔记方法专家，深谙各种笔记技巧（康奈尔笔记法、思维导图法、卡片笔记法、SQ3R阅读法等）。你的任务是为读者生成个性化的读书笔记模板。

3.1.2 第二层：上下文注入

读者信息：
- 正在阅读的书籍类型：{book_type}
- 偏好的笔记风格：{template_style}

3.1.3 第三层：输出格式约束

请严格按照以下 JSON 结构输出：
{
  "sections": ["章节1", "章节2", ...],
  "questions": ["问题1", "问题2", ...],
  "action_template": "行动模板内容"
}

3.2 不同书籍类型的模板策略

书籍类型	模板策略	引导问题示例
工具方法类	核心方法→步骤拆解→应用场景→实践计划	“这个方法的核心步骤是什么？”
文学小说类	人物关系→情节主线→主题思想→写作手法	“作者通过哪些细节塑造了主角？”
学术著作类	理论框架→论证逻辑→关键证据→学术贡献	“这个理论解决了什么学术问题？”
传记类	成长阶段→关键抉择→核心品质→启示总结	“主人公在关键节点做了什么选择？”

3.3 Prompt 模板完整示例

buildPrompt(input: Record<string, Object>): string {
  let bookType: string = input['book_type'] as string
  let style: string = input['template_style'] as string

  return `你是一位专业的阅读教练，擅长${style}笔记法。

请为以下书籍生成笔记模板：
- 书籍类型：${bookType}
- 笔记风格：${style}

请输出 JSON 格式：
{
  "sections": ["章节标题", ...],
  "questions": ["每个章节对应的引导问题", ...],
  "action_template": "基于${style}法的行动模板，包含具体可执行的步骤"
}

要求：
1. sections 包含 4-6 个章节
2. 每个章节配一个引导问题
3. 行动模板要具体、可执行`
}

3.4 输出解析与数据映射

parseResponse(response: string): NoteTemplateData {
  let result: NoteTemplateData = new NoteTemplateData()
  try {
    let parsed: Object = JSON.parse(response)
    if (Array.isArray(parsed['sections'])) {
      result.sections = parsed['sections'] as string[]
    }
    if (Array.isArray(parsed['questions'])) {
      result.questions = parsed['questions'] as string[]
    }
    if (typeof parsed['action_template'] === 'string') {
      result.action_template = parsed['action_template'] as string
    }
  } catch (e) {
    // 解析失败时的降级处理
    result.sections = ['核心观点', '关键内容', '个人感悟', '行动清单']
    result.questions = ['这本书的核心观点是什么？', '哪些内容对你最有启发？']
    result.action_template = '请根据以上笔记制定行动计划'
  }
  return result
}

---

四、核心功能实现详解

4.1 输入区域实现

Text('书籍类型')
  .fontSize(14)
  .fontWeight(FontWeight.Bold)
  .fontColor($r('app.color.text_primary'))
  .margin({ top: 12, bottom: 4 })
TextInput({ placeholder: '请输入书籍类型' })
  .fontSize(14)
  .height(44)
  .backgroundColor('#FFFFFF')
  .borderRadius(8)
  .padding({ left: 12, right: 12 })
  .onChange((val: string) => { this.inputData['book_type'] = val })

Text('模板风格')
  .fontSize(14)
  .fontWeight(FontWeight.Bold)
  .fontColor($r('app.color.text_primary'))
  .margin({ top: 12, bottom: 4 })
TextInput({ placeholder: '请输入模板风格' })
  .fontSize(14)
  .height(44)
  .backgroundColor('#FFFFFF')
  .borderRadius(8)
  .padding({ left: 12, right: 12 })
  .onChange((val: string) => { this.inputData['template_style'] = val })

UI 设计规范分析：

1. 标签与输入框分离：每个输入字段都配有独立的 Text 标签，清晰地指示输入内容
2. 统一的高度与间距：所有输入框高度统一为 44px，标签与输入框间距为 4px，输入框之间间距为 12px
3. 占位符提示：placeholder 提供输入示例，降低用户认知负担
4. 实时数据绑定：onChange 回调在每次输入变化时更新 inputData

4.2 生成按钮实现

Button('AI 生成')
  .width('100%')
  .height(48)
  .backgroundColor('#3B82F6')
  .borderRadius(12)
  .fontColor('#FFFFFF')
  .fontSize(16)
  .fontWeight(FontWeight.Bold)
  .margin({ top: 20, bottom: 16 })
  .onClick(() => {
    this.resultData = this.service.generateData(this.inputData)
    this.showResult = true
  })

按钮交互状态机：

初始状态 → 用户输入信息 → 输入就绪
                                  ↓
                          用户点击"AI 生成"
                                  ↓
                          ┌─ 加载中... ─┐
                          │ 显示加载动画  │
                          │ 禁用按钮     │
                          └──────┬──────┘
                                 ↓
                    ┌────────────┴────────────┐
                    ↓                         ↓
              生成成功                     生成失败
                    ↓                         ↓
          显示结果区域                 显示错误提示
          更新 resultData             恢复按钮可用

4.3 结果展示区域

if (this.showResult && this.resultData !== null) {
  Text('生成结果')
    .fontSize(18)
    .fontWeight(FontWeight.Bold)
    .fontColor($r('app.color.text_primary'))
    .width('100%')
    .margin({ top: 16, bottom: 8 })

  Text('笔记模板')
    .fontSize(14)
    .fontColor($r('app.color.text_secondary'))
    .width('100%')
    .margin({ bottom: 16 })
}

条件渲染的 ArkTS 实现要点：

在 ArkTS 中，if 条件渲染是编译期优化的。当条件为 false 时，分支内的组件树完全不会被创建，这比通过 CSS 隐藏元素更高效。这种机制特别适合结果展示这类"有或无"的场景。

4.4 完整数据流

用户输入：书籍类型 = "工具书", 模板风格 = "康奈尔笔记法"
    ↓
inputData = { book_type: "工具书", template_style: "康奈尔笔记法" }
    ↓
用户点击 "AI 生成"
    ↓
service.generateData(inputData)
    ↓
构建 Prompt：
  "你是一位专业的阅读教练，擅长康奈尔笔记法。
   请为工具书生成笔记模板..."
    ↓
调用 AI API → 获取响应
    ↓
解析 JSON 响应 → 填充 NoteTemplateData
    ↓
resultData = NoteTemplateData { sections: [...], questions: [...], action_template: "..." }
    ↓
showResult = true
    ↓
UI 自动渲染 → 展示笔记模板

---

五、用户体验优化

5.1 视觉设计

页面布局结构：

┌──────────────────────────────────┐
│ ← 返回      读书笔记速记           │
├──────────────────────────────────┤
│  输入信息                         │
│  ┌──────────────────────┐       │
│  │ 书籍类型              │       │
│  │ [请输入书籍类型]       │       │
│  │ 模板风格              │       │
│  │ [请输入模板风格]       │       │
│  └──────────────────────┘       │
│  ┌──────────────────────┐       │
│  │     AI 生成            │       │
│  └──────────────────────┘       │
│  生成结果                         │
│  笔记模板内容...                   │
└──────────────────────────────────┘

5.2 交互反馈设计

5.2.1 加载状态

在实际应用中，AI 调用通常需要 1-3 秒，应提供加载状态反馈：

@State isLoading: boolean = false

Button('AI 生成')
  .enabled(!this.isLoading)
  .onClick(() => {
    this.isLoading = true
    // 异步调用
    setTimeout(() => {
      this.resultData = this.service.generateData(this.inputData)
      this.showResult = true
      this.isLoading = false
    }, 0)
  })

if (this.isLoading) {
  LoadingProgress()
    .width(32)
    .height(32)
    .margin({ top: 20 })
}

5.2.2 空状态处理

当用户尚未生成结果时，显示友好的引导提示：

if (!this.showResult) {
  Column() {
    Image($r('app.media.ic_empty'))
      .width(120)
      .height(120)
    Text('输入书籍信息，点击 AI 生成获取笔记模板')
      .fontSize(14)
      .fontColor($r('app.color.text_secondary'))
  }
  .width('100%')
  .margin({ top: 40 })
}

5.3 资源管理

5.3.1 颜色资源

使用 $r 引用资源文件中的定义，便于主题切换：

// 引用 resources 中定义的颜色
.fontColor($r('app.color.text_primary'))
.fontColor($r('app.color.text_secondary'))
.backgroundColor('#F8FAFC')

5.3.2 国际化处理

对于标题和标签文本，建议使用 $r 引用字符串资源：

// 使用字符串资源
Text($r('app.string.book_type_label'))
Text($r('app.string.template_style_label'))

---

六、性能优化与最佳实践

6.1 ArkTS 语法约束适配

6.1.1 对象字面量使用限制

ArkTS 对对象字面量有严格的限制。对象字面量必须对应一个显式声明的类或接口：

// 正确：使用显式声明的类
export class NoteTemplateData {
  book_type: string = ''
  template_style: string = ''
  sections: string[] = []
  questions: string[] = []
  action_template: string = ''
}

// 错误：不能直接将对象字面量赋值给变量
// let data = { book_type: '工具书', template_style: '康奈尔' }

6.1.2 数组类型推断

ArkTS 要求数组字面量中的所有元素具有可推断的类型：

// 正确：所有元素类型一致
let sections: string[] = ['核心观点', '关键内容', '个人感悟']

// 错误：元素类型不一致
// let mixed: string[] = ['核心观点', 123, true]

6.1.3 索引访问限制

ArkTS 不支持通过索引访问对象字段（obj["field"]）：

// 正确：使用点号访问
inputData.book_type = '工具书'

// 错误：不支持索引访问
// inputData['book_type'] = '工具书'  // 注意：在 Record<string, Object> 中这是允许的，因为 Record 是例外

6.2 内存管理

6.2.1 避免不必要的对象创建

// 优化前：每次生成都创建新对象
let result: NoteTemplateData = new NoteTemplateData()

// 优化后：复用已有对象
let result: NoteTemplateData = this.resultData ?? new NoteTemplateData()

6.2.2 字符串模板优化

使用模板字符串（${}）构建 Prompt 时，注意避免过长的字符串拼接：

// 优化前：单次拼接过长字符串
let prompt: string = `...很长内容...${var1}...很长内容...${var2}...`

// 优化后：分块构建
let header: string = `你是一位专业的阅读教练...`
let context: string = `书籍类型：${bookType}，笔记风格：${style}`
let format: string = `请输出 JSON 格式...`
let prompt: string = `${header}\n${context}\n${format}`

6.3 错误处理策略

6.3.1 输入校验

onClick(() => {
  if (!this.inputData['book_type'] || !this.inputData['template_style']) {
    // 显示提示
    return
  }
  this.resultData = this.service.generateData(this.inputData)
  this.showResult = true
})

6.3.2 AI 调用异常处理

generateData(input: Record<string, Object>): NoteTemplateData {
  try {
    let prompt: string = this.buildPrompt(input)
    let response: string = this.callAI(prompt)
    return this.parseResponse(response)
  } catch (e) {
    // 降级：返回默认模板
    return this.getDefaultTemplate()
  }
}

private getDefaultTemplate(): NoteTemplateData {
  let result: NoteTemplateData = new NoteTemplateData()
  result.sections = ['核心观点', '关键内容', '个人感悟', '行动清单']
  result.questions = ['这本书的核心观点是什么？', '哪些内容对你最有启发？']
  result.action_template = '1. 列出3个可立即行动的点\n2. 设定执行时间\n3. 回顾效果'
  return result
}

6.4 代码组织规范

6.4.1 文件结构

读书笔记速记模板/
├── 读书笔记速记模板Model.ets     # 数据模型定义
├── 读书笔记速记模板Service.ets    # 业务逻辑封装
└── 读书笔记速记模板Page.ets      # UI 页面组件

6.4.2 导入顺序规范

// 1. 自定义模块导入
import { NoteTemplateData } from './读书笔记速记模板Model'
import { NoteTemplateService } from './读书笔记速记模板Service'

// 2. 系统库导入
import { router } from '@kit.ArkUI'

// 3. 业务代码...

---

七、总结与展望

7.1 项目价值总结

读书笔记速记模板 AI 应用的成功开发，验证了 HarmonyOS 平台在 AI 应用领域的可行性和优势：

1. 开发效率：ArkTS 声明式 UI 大幅减少了 UI 代码量，提高了开发效率
2. 运行性能：ArkUI 框架的编译时优化确保了应用的流畅运行
3. AI 整合：Model-Service-Page 架构天然适合 AI 应用的开发模式
4. 用户体验：简洁的交互设计和即时的反馈机制提升了用户满意度

7.2 关键技术收获

提示词工程的迭代优化：

• 第一版：简单提示词，输出质量不稳定
• 第二版：增加角色设定，输出更专业
• 第三版：增加输出格式约束，便于程序解析
• 第四版：增加示例引导，输出质量显著提升

ArkTS 静态类型系统的价值：

• 编译期发现类型错误，减少运行时崩溃
• 代码自动补全和智能提示提升开发效率
• 类型约束促使代码更规范、更健壮

7.3 未来拓展方向

近期优化：

1. 增加模板预览功能，支持在生成前查看模板样例
2. 支持模板导出（Markdown、PDF 格式）
3. 增加模板收藏和复用功能

中期规划：

1. 支持多轮对话，在模板基础上细化内容
2. 引入 OCR 识别，支持拍照提取书摘后自动生成笔记
3. 增加知识关联功能，自动链接相关书籍的笔记

长期愿景：

1. 构建个人知识库，基于用户所有笔记生成知识图谱
2. 引入间隔重复（Spaced Repetition）算法，优化复习计划
3. 跨设备协同，在手机、平板、车机等多设备间无缝同步

7.4 开发建议

1. Prompt 需要持续迭代：AI 应用的质量天花板由提示词决定，建议建立 Prompt 版本管理机制
2. 重视降级策略：AI 调用可能失败，必须设计优雅的降级方案
3. 善用 ArkTS 类型系统：虽然约束较多，但类型安全带来的收益远大于成本
4. 关注鸿蒙生态：HarmonyOS 生态快速发展，建议持续跟进官方文档和社区动态

---

本文通过读书笔记速记模板应用的完整开发实践，深入探讨了 HarmonyOS + ArkTS + AI 的技术栈应用。从架构设计到代码实现，从提示词工程到性能优化，全面展示了鸿蒙 AI 应用开发的全流程。希望本文能为正在探索智慧学习工具开发的开发者提供有价值的参考。