AgentCard 智能体卡片为英语学习 App 打造桌面级学习助手适用平台HarmonyOS 7.0 (API 26 Beta)一、引言HarmonyOS 7.0API 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():Promisevoid {conststateData {currentWord:this.cardState.currentWord,wordIndex:this.cardState.wordIndex,status:this.cardState.status,lastUpdateTime:Date.now() };awaitagentCard.savePersistentState(daily_word_state, stateData); }publicasyncrestoreState():Promisevoid {constsavedState awaitagentCard.getPersistentState(daily_word_state);if(savedState) {this.cardState savedStateasAgentCardState; } } }系统在下列时机自动触发状态保存应用进程进入后台卡片执行交互操作后定期每 30 分钟快照保存3.2 状态恢复时机当用户重启设备或应用被重新拉起时AgentCard 按以下流程恢复桌面卡片服务启动加载持久化的卡片状态快照应用进程被唤醒如果未运行系统调用onCreateForm()回调传入上次保存的状态应用根据状态重建卡片 UIonCreateForm(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 卡片跳转主应用在卡片布局中配置点击跳转事件EntryComponentstruct 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(): Promisevoid{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) {caseonVisibilityChange:// 卡片从桌面消失/重新出现break;caseonAcquire:// 卡片被添加到桌面this.startDailyUpdate();break;caseonReload:// 卡片状态需要刷新this.refreshCardData();break; } }六、项目落地桌面每日一词智能体卡片6.1 卡片布局设计卡片采用 2x2 尺寸展示核心信息┌──────────────┐ │ 每日一词 │ │ │ │ enthusiasm │ │/ɪnˈθjuːziæzəm/│ │ n. 热情热忱 │ │ │ │ [已掌握] [待复习] │ └──────────────┘6.2 核心代码实现EntryComponentstruct 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 还可以扩展到每日一句听力训练等更多学习场景。