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，验证配置合法性后注册到卡片管理服务中。解析流程依次校验：
- 语法校验：JSON 格式是否正确，必填字段是否完整
- 语义校验：agentId 是否唯一、displayMode 是否在支持范围内
- 资源校验：引用的布局文件、图标资源是否存在
- 权限校验：应用是否声明了所需的权限
通过校验后，卡片服务将 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 按以下流程恢复：
- 桌面卡片服务启动，加载持久化的卡片状态快照
- 应用进程被唤醒（如果未运行）
- 系统调用
onCreateForm()回调，传入上次保存的状态 - 应用根据状态重建卡片 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（用户操作触发）不同状态的资源占用策略：
| 状态 | 更新频率 | 内存占用 | 是否可交互 |
|---|---|---|---|
| Active | 实时 | 正常 | 是 |
| Background | 按策略（默认 30 分钟） | 低 | 是 |
| Suspended | 不更新 | 极低 | 否 |
| Destroyed | — | 0 | 否 |
应用可以监听生命周期回调，合理管理资源：
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 的自动更新依赖系统调度，并非精确到秒。我们的策略是：
- 每日 08:00 系统触发定时更新，展示今日单词
- 用户在应用内学习新词后，主动推送更新
- 卡片上执行"已掌握"操作后，立即刷新为下一个待学单词
7.2 性能考量
AgentCard 运行在独立进程（卡片服务）中，但渲染资源有限。因此：
- 卡片布局尽量扁平，避免深层嵌套
- 图片资源控制在 50KB 以内
- 避免在卡片 onUpdate 中执行耗时操作
7.3 与 Form 卡片的区别
| 维度 | 普通 Form 卡片 | AgentCard 智能体卡片 |
|---|---|---|
| 数据源 | 静态绑定 | 动态智能推荐 |
| 交互能力 | 有限的点击跳转 | 丰富的行内操作 |
| 状态持久化 | 基础快照 | 完整状态机 |
| 更新策略 | 固定刷新周期 | 智能触发 + 差异化刷新 |
八、总结
AgentCard 智能体卡片是 HarmonyOS 7.0 在桌面交互维度的重要创新。对于英语学习 App 而言，"每日一词"AgentCard 将学习入口前置到桌面，用户无需打开应用即可完成"看单词→回忆释义→标记状态"的完整学习闭环。这种高频轻量的交互模式，天然适合语言学习场景。随着 API 的进一步成熟，AgentCard 还可以扩展到"每日一句""听力训练"等更多学习场景。
