前言端插件End Plugin是鸿蒙智能体平台中连接HarmonyOS设备侧应用的桥梁。通过端插件智能体可以直接调用设备上安装应用的能力——从查询日历、发送短信到操控音乐播放将系统级能力开放给智能体生态。相比云插件端插件无需网络请求直接在设备本地执行响应更快、隐私更安全。本文是「鸿蒙智能体开发实战」系列的第四十五篇系统讲解端插件的创建、配置、端侧实现和权限管控帮助开发者将自己的HarmonyOS应用能力开放给智能体。前置条件熟悉HarmonyOS应用开发了解ArkTS语言和Ability框架。建议先阅读本系列第6篇《插件开发与使用》了解插件基础。一、端插件概述1.1 核心概念端插件的本质是HarmonyOS应用向智能体暴露能力接口的过程。小艺智能体通过端插件协议与设备侧应用通信实现一句话操控应用的体验。端插件的工作流程创建工具定义在小艺开放平台定义插件的输入输出参数配置端侧实现在HarmonyOS应用代码中实现工具逻辑匹配调用大模型根据用户意图选择合适的端插件并调用执行与返回设备侧应用执行操作并返回结果1.2 端插件 vs 云插件 vs MCP插件特性端插件云插件MCP插件运行位置HarmonyOS设备侧云端服务器开发者自部署Server网络依赖无需联网需要网络需要网络响应速度毫秒级依赖网络延迟依赖网络延迟隐私安全数据不出设备数据经过云端数据经过第三方开发语言ArkTS任意任意需实现MCP协议更新方式应用更新附带云端热更新服务端热更新提示端插件特别适合本地实时操作类场景如设置闹钟、发送短信、播放音乐而云插件适合在线数据查询类场景。二、创建端插件工具2.1 工具基本信息配置在小艺开放平台的端插件管理页面点击新建工具后填写以下信息配置项说明示例工具名称插件的显示名称“创建闹钟”工具版本号语义化版本“1.0.0”工具描述用于大模型理解功能精准匹配调用场景“根据用户指定的时间和标签创建闹钟”执行方式前台/后台/卡片“前台执行”涉及端侧页面操控是否需要操控应用UI“否”2.2 三种执行方式端插件支持三种执行方式开发者需根据业务场景选择合适的类型1. 前台执行拉起端侧应用到前台页面包含三种实现方式实现方式说明适用场景标准实现通过HarmonyOS Ability API实现完整交互需要复杂UI交互的场景AppLink实现基于HarmonyOS App Linking能力已有AppLink实现的应用DeepLink实现基于标准Deep Link能力已有DeepLink实现的应用{execution:{type:foreground,implementation:applink,applink:{min_app_version:5.0.0,link:https://example.com/app/schedule?actioncreatetypealarm,short_link:https://example.com/alarm,parameters:{time:${alarm_time},label:${alarm_label},repeat:${repeat_type}}}}}2. 后台执行在后台静默执行操作适合数据查询类场景。后续可以在界面上绑定卡片以卡片形式呈现返回数据。3. 卡片执行调用端侧应用渲染自定义卡片界面提供更丰富的交互体验。最佳实践对于需要用户确认的操作如发送消息、支付选择前台执行让用户看到操作过程对于无需用户感知的操作如数据同步选择后台执行。三、输入输出参数配置3.1 输入参数配置大模型会根据用户输入的词和参数描述进行匹配在调用插件时传入参数{input_parameters:[{name:alarm_time,type:String,description:闹钟时间格式为HH:mm如07:00,required:true},{name:alarm_label,type:String,description:闹钟标签如起床、会议,required:false},{name:repeat_days,type:ArrayString,description:重复日期可选值[周一,周二,周三,周四,周五,周六,周日],required:false}]}{input_parameters:[{name:alarm_sound,type:String,description:闹钟铃声,required:false,default_value:default_ringtone,visible_to_model:false}]}提示对于参数值较为稳定的输入参数建议设置默认值并关闭「开启开关」参数对模型不可见减少大模型调用插件时的流程提高调用效率。对于必填参数如需关闭需先填写缺省值。3.2 输出参数规范输出参数必须包含code和result两个字段# 成功返回示例success_output{code:0,result:{alarm_id:alarm_123456,created_time:07:00,label:起床闹钟,status:enabled}}# 失败返回示例error_output{code:1001,message:闹钟时间不能早于当前时间,result:{}}四、端侧应用实现4.1 module.json5配置在HarmonyOS项目中端插件的代码实现需要配置module.json5{module:{name:entry,type:entry,abilities:[{name:AgentPluginAbility,srcEntry:./ets/plugins/AgentPluginAbility.ets,description:小艺端插件服务,icon:$media:icon,label:$string:app_name,exported:true,skills:[{entities:[entity.system.home],actions:[action.custom.plugin]}]}]}}4.2 ArkTS代码实现使用ArkTS实现端插件的核心逻辑import{UIAbility,AbilityConstant,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassAgentPluginAbilityextendsUIAbility{onNewWant(want:Want,launchParam:AbilityConstant.LaunchParam):void{constpluginActionwant.parameters?.pluginActionasstring;constinputParamswant.parameters?.inputParamsasstring;switch(pluginAction){casecreate_alarm:this.handleCreateAlarm(inputParams);break;casequery_schedule:this.handleQuerySchedule(inputParams);break;default:console.error(Unknown plugin action:,pluginAction);}}privatehandleCreateAlarm(params:string):void{const{alarmTime,alarmLabel,repeatDays}JSON.parse(params);try{constalarmManagerthis.context.getAlarmManager();constalarmIdalarmManager.createAlarm({hour:parseInt(alarmTime.split(:)[0]),minute:parseInt(alarmTime.split(:)[1]),daysOfWeek:this.convertRepeatDays(repeatDays),label:alarmLabel});this.sendPluginResult({code:0,result:{alarm_id:alarmId.toString(),time:alarmTime,label:alarmLabel,status:enabled}});}catch(error){this.sendPluginResult({code:-1,message:创建闹钟失败:${error.message},result:{}});}}privateconvertRepeatDays(days:string[]):number[]{constdayMap:Recordstring,number{周一:1,周二:2,周三:3,周四:4,周五:5,周六:6,周日:7};returndays.map(daydayMap[day]||0).filter(dd0);}privatehandleQuerySchedule(date:string):void{constcalendarManagerthis.context.getCalendarManager();constschedulecalendarManager.queryEvents({startDate:${date}T00:00:00,endDate:${date}T23:59:59});this.sendPluginResult({code:0,result:{date:date,events:schedule.map(event({title:event.title,startTime:event.startTime,endTime:event.endTime,location:event.location})),total:schedule.length}});}privatesendPluginResult(output:object):void{constresultWant:Want{parameters:{ability.want.params.pluginResult:JSON.stringify(output)}};this.context.startAbility(resultWant);}}4.3 多版本兼容端插件支持为同一个工具配置多个版本用于兼容不同端侧版本{tools:[{name:open_weather_page,versions:[{version:1.0.0,description:基础版 - 打开天气主页,min_app_version:3.0.0,parameters:{city:{type:String,required:false}}},{version:2.0.0,description:增强版 - 支持定位到具体天气详情,min_app_version:4.0.0,parameters:{city:{type:String,required:false},detail_date:{type:String,required:false}}}]}]}当选择多版本端插件时工作流运行时端侧会自动匹配与设备版本兼容的最新版本未命中的版本会返回特定错误码如code204。五、工作流中的端插件集成5.1 端插件节点特性在工作流中端插件节点与云插件节点的差异如下特性端插件节点云插件节点单节点调试不支持支持试运行不支持需真机测试支持模拟集支持支持多版本配置支持不支持5.2 代码节点聚合处理端插件的返回结果需要配合代码节点进行聚合defaggregate_plugin_results(plugins:dict)-dict:聚合多个版本端插件的执行结果results{}errors[]forplugin_name,resultinplugins.items():coderesult.get(code,-1)ifcode0:results[plugin_name]result.get(result,{})elifcode204:continueelse:errors.append({plugin:plugin_name,code:code,message:result.get(message,未知错误)})return{success:len(results)0,results:results,errors:errors}注意由于平台侧无法获取到端插件的执行结果在试运行时会有提示信息。开发者可以使用选择器节点针对code为204的情况绕过代码组件的端插件引用分路让工作流能够试运行成功得以上架。5.3 执行方式配置{plugin_execution:{mode:immediate,interrupt_tts:true}}立即执行清空已下发指令立即执行当前指令打断播报在涉及音视频播放的场景使用使用时必须开启「立即执行」开关方可生效六、权限管控与模拟集6.1 端插件权限管控端插件涉及设备侧数据访问和应用操控权限管控尤为重要权限分类说明典型权限基础权限插件运行必需的基础能力网络状态、设备信息数据权限访问用户个人数据日历、联系人、位置操作权限操控系统或应用功能发送通知、打开应用安全建议端插件应遵循最小权限原则只申请插件功能所必需的权限并在隐私协议中明确声明权限用途。6.2 工具模拟集端插件支持使用Mock数据进行调试无需依赖真机{plugin_mock:{tool:create_alarm,version:1.0.0,mock_input:{alarm_time:07:00,alarm_label:起床},mock_output:{code:0,result:{alarm_id:mock_alarm_001,time:07:00,label:起床,status:enabled}}}}七、端插件应用场景7.1 智能日程助手asyncfunctioncreateMeetingEvent(title:string,startTime:string,endTime:string,attendees:string[]){consteventIdawaitCalendarManager.createEvent({title,startTime:newDate(startTime),endTime:newDate(endTime),attendees:attendees?.map(email({email})),reminderTime:15});return{code:0,result:{eventId,status:created}};}7.2 智能家居控制asyncfunctioncontrolDevice(device:string,action:string,params:object){constdeviceApinewSmartHomeAPI();constresultawaitdeviceApi.execute({deviceId:DEVICE_MAP[device],command:ACTION_MAP[action],parameters:params});return{code:result.success?0:-1,result:{device,action,status:result.status,message:result.message}};}总结本文详细介绍了鸿蒙智能体平台中端插件的完整开发流程从工具创建、参数配置、端侧代码实现到权限管控。端插件为HarmonyOS应用开发者提供了一条零门槛开放能力给智能体的通道让应用不再只是被动等待用户操作而是可以被智能体主动调用实现真正意义上的智能交互体验。关键要点端插件数据不出设备隐私更安全三种执行方式前台/后台/卡片适应不同场景多版本兼容确保插件在不同设备版本上都能正常运行配合代码节点和选择器节点处理多版本端插件的执行结果如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源端插件创建指南链接端插件配置文档链接端侧应用实现文档链接端插件权限管控链接端插件模拟集创建链接AppLink开发指南链接DeepLink开发指南链接鸿蒙智能体开发实战系列链接HarmonyOS UIAbility开发链接