HarmonyOS 应用开发《掌上英语》第81篇: 智能体卡片：为英语学习 App 打造桌面级学习助手

AgentCard 智能体卡片：为英语学习 App 打造桌面级学习助手

适用平台：HarmonyOS 7.0 (API 26 Beta+)

一、引言

HarmonyOS 7.0（API 26 Beta）新增了 AgentCard 智能体卡片能力，这是继 HMAF（鸿蒙智能体框架）之后，智能体技术的又一次重要演进。不同于 HMAF 的端云一体大模型集成，AgentCard 聚焦于桌面级的轻量智能体呈现——它允许应用在桌面上展示一个"活的"智能体卡片，无需打开应用即可完成高频、轻量的信息获取和操作。

在我们的英语学习 App 中，AgentCard 的最佳落地场景就是"每日一词"：用户在桌面上就能看到今日要学的单词、音标和释义，点击直接进入详情页，甚至可以在卡片上直接标记"已掌握"或"待复习"。本文将从 AgentCard 的配置声明、生命周期管理、通信机制和实际落地四个方面展开。

二、AgentCard 配置声明与解析流程

2.1 配置文件声明

AgentCard 的声明方式与普通的 Form 卡片类似，但增加了智能体相关的配置项。在resources/base/profile/目录下创建agent_card_config.json：

{"agentCards": [ {"cardName":"DailyWordAgent","cardType":"agent","description":"每日一词智能体卡片","updateEnabled": true,"scheduledUpdateTime":"08:00","agentConfig": {"agentId":"com.example.englishapp.dailyword","displayMode":"compact","interactiveActions": ["mark_known","mark_review"],"dataSource":"LearningPlanManager"},"formConfig": {"dimension":"2x2","supportDimensions": ["2x2","4x2"],"defaultGrid":4,"colorMode":"auto"} } ] }

其中agentConfig是 AgentCard 独有的配置段，定义了智能体的 ID、展示模式、支持的交互动作和数据源。这个配置文件需要在module.json5中注册：

{"module": {"proxyConfigs": [ {"type":"agentCard","configFile":"resources/base/profile/agent_card_config.json"} ] } }

2.2 解析流程

系统在应用安装时解析agent_card_config.json，验证配置合法性后注册到卡片管理服务中。解析流程依次校验：

1. 语法校验：JSON 格式是否正确，必填字段是否完整
2. 语义校验：agentId 是否唯一、displayMode 是否在支持范围内
3. 资源校验：引用的布局文件、图标资源是否存在
4. 权限校验：应用是否声明了所需的权限

通过校验后，卡片服务将 AgentCard 注册到桌面，用户即可在桌面添加该卡片。

三、AgentCard 持久化与状态恢复

AgentCard 真正的价值在于其持久化能力——即使应用进程被系统回收，卡片仍然在桌面上存活，状态不会丢失。

3.1 状态持久化策略

AgentCard 使用独立的持久化存储通道，与应用自身的 Preferences 存储隔离：

exportclassDailyWordAgentCard{privatecardState:AgentCardState;publicasyncsaveState():Promise<void> {conststateData = {currentWord:this.cardState.currentWord,wordIndex:this.cardState.wordIndex,status:this.cardState.status,lastUpdateTime:Date.now() };awaitagentCard.savePersistentState('daily_word_state', stateData); }publicasyncrestoreState():Promise<void> {constsavedState =awaitagentCard.getPersistentState('daily_word_state');if(savedState) {this.cardState= savedStateasAgentCardState; } } }

系统在下列时机自动触发状态保存：

• 应用进程进入后台
• 卡片执行交互操作后
• 定期（每 30 分钟）快照保存

3.2 状态恢复时机

当用户重启设备或应用被重新拉起时，AgentCard 按以下流程恢复：

1. 桌面卡片服务启动，加载持久化的卡片状态快照
2. 应用进程被唤醒（如果未运行）
3. 系统调用onCreateForm()回调，传入上次保存的状态
4. 应用根据状态重建卡片 UI

onCreateForm(want: Want): formBindingData.FormBindingData {constsavedState = want.parameters?.agentCardState;if(savedState) {// 恢复状态constword = JSON.parse(savedStateasstring);returnthis.buildFormData(word); }// 首次创建，从 LearningPlanManager 获取今日单词returnthis.buildFormData(LearningPlanManager.getInstance().getTodayWord()); }

四、卡片与主应用的通信机制

AgentCard 支持双向通信：卡片 → 应用的跳转和事件传递，以及应用 → 卡片的数据更新推送。

4.1 卡片跳转主应用

在卡片布局中配置点击跳转事件：

@Entry@Componentstruct DailyWordCard { build() { Column() { Text(this.wordText) .fontSize(16) .onClick(() => { postCardAction(this, { action:'router', bundleName:'com.example.englishapp', abilityName:'EntryAbility', params: { page:'CourseHomePage', wordId:this.wordId, from:'agent_card'} }); }); } } }

postCardAction是 AgentCard 特有的 API，支持三种 action 类型：

• router：跳转到应用指定页面
• message：向应用发送消息（无需跳转）
• call：调用应用的后台能力

4.2 应用更新卡片数据

当 LearningPlanManager 的今日目标发生变化时，应用主动刷新卡片：

publicasyncupdateCardWithTodayWord(): Promise<void>{consttodayWord =this.getTodayWord();constformData = formBindingData.createFormBindingData({ wordText: todayWord.word, phonetic: todayWord.phonetic, meaning: todayWord.meaning });awaitformProvider.updateForm(this.cardId, formData); }

五、智能体卡片生命周期管理

AgentCard 的生命周期比普通 Form 卡片更加复杂，因为它包含了智能体的状态管理：

Created→Active→Background→Suspended→Destroyed↓Interactive（用户操作触发）

不同状态的资源占用策略：

应用可以监听生命周期回调，合理管理资源：

onFormEvent(formId:string,event:string) {switch(event) {case'onVisibilityChange':// 卡片从桌面消失/重新出现break;case'onAcquire':// 卡片被添加到桌面this.startDailyUpdate();break;case'onReload':// 卡片状态需要刷新this.refreshCardData();break; } }

六、项目落地：桌面"每日一词"智能体卡片

6.1 卡片布局设计

卡片采用 2x2 尺寸，展示核心信息：

┌──────────────┐ │ 📖 每日一词 │ │ │ │ enthusiasm │ │/ɪnˈθjuːziæzəm/│ │ n. 热情，热忱 │ │ │ │ [已掌握] [待复习] │ └──────────────┘

6.2 核心代码实现

@Entry@Componentstruct DailyWordAgentCard {@LocalwordText: string ='';@Localphonetic: string ='';@Localmeaning: string ='';@LocalwordId: number =0;build() {Column({ space: 4 }) {// 顶部标题Row() {Image($r('app.media.ic_daily_word')).width(16).height(16)Text('每日一词').fontSize(12).fontColor('#666666') }// 单词信息Text(this.wordText).fontSize(18).fontWeight(FontWeight.Bold)Text(this.phonetic).fontSize(12).fontColor('#888888')Text(this.meaning).fontSize(14).margin({top:4})// 操作按钮Row({ space: 8 }) {Button('已掌握').onClick(() => {postCardAction(this, { action: 'message', data: { action: 'mark_known', wordId: this.wordId } }); })Button('待复习').onClick(() => {postCardAction(this, { action: 'message', data: { action: 'mark_review', wordId: this.wordId } }); }) } }.padding(12).backgroundColor('#FFFFFF').borderRadius(12) } }

七、最佳实践与注意事项

7.1 数据更新策略

AgentCard 的自动更新依赖系统调度，并非精确到秒。我们的策略是：

1. 每日 08:00 系统触发定时更新，展示今日单词
2. 用户在应用内学习新词后，主动推送更新
3. 卡片上执行"已掌握"操作后，立即刷新为下一个待学单词

7.2 性能考量

AgentCard 运行在独立进程（卡片服务）中，但渲染资源有限。因此：

• 卡片布局尽量扁平，避免深层嵌套
• 图片资源控制在 50KB 以内
• 避免在卡片 onUpdate 中执行耗时操作

7.3 与 Form 卡片的区别

八、总结

AgentCard 智能体卡片是 HarmonyOS 7.0 在桌面交互维度的重要创新。对于英语学习 App 而言，"每日一词"AgentCard 将学习入口前置到桌面，用户无需打开应用即可完成"看单词→回忆释义→标记状态"的完整学习闭环。这种高频轻量的交互模式，天然适合语言学习场景。随着 API 的进一步成熟，AgentCard 还可以扩展到"每日一句""听力训练"等更多学习场景。