鸿蒙Agent Framework Kit小艺智能体槽位兜底

鸿蒙专家

在年度规划类应用中，最容易出问题的是目标写得大而全、周期却脱离现实。轻规划（AeroPlan）的这篇实战把HarmonyOS原生Agent Framework Kit接入进来，通过小艺智能体对项目做体检、可行性打分和甘特图拆解。本文按开发链路拆解其意图定义、槽位填充、会话通信、结果解析与本地兜底。

一、端云协同架构与客户端职责
原文把Agent Framework Kit描述为端云双向协同引擎，并不是端侧孤立大模型。应用客户端通过API唤起会话，管理AgentSession生命周期，并在本地做参数安全拦截与格式化；系统智能体引擎运行在独立系统级Service中，通过HarmonyOS IPC与应用建立低延迟信道，从而降低应用本身内存占用；云端NLU与LLM负责接收自然语言输入，运行NER，抽取配置文件中预设的意图槽位，并按System Prompt进行推理生成。由此带来的架构取舍是，客户端无需集成数十GB的大模型权重，只需关注意图契约和槽位定义，就能获取云端泛化推理能力。

二、意图配置与槽位声明
开发前需要在项目的resources/base/profile目录下配置intent_schema.json。原文声明了意图com.aeroplan.intent.DIAGNOSE_PROJECT，并定义槽位projectName（string，mandatory为true）和expectedDays（number，mandatory为false）。该配置文件在应用打包和分发阶段会被华为应用市场与系统意图管理模块解析并注册。槽位是智能体语义理解的基础单元，原文强调合理选择和配置槽位能显著提升小艺识别准确率，并讨论了槽位属性与行为映射。

三、客户端发起体检与会话管理
原文用XiaoyiAgentBridge桥接类维护agentSession。requestProjectDiagnosis中先调用agentFramework.createAgentSession创建端侧会话，agentId为aeroplan_planner_helper_agent，该ID必须与华为开发者联盟平台注册的智能体ID一致。随后做本地前置过滤，expectedDays大于0才采用，否则默认30天。构造AgentRequest时，intentName对应配置中的意图名，slots填充projectName和expectedDays，systemPrompt要求以资深人生规划理论专家角度诊断项目不合理性、打0至100分、给出修正后的里程碑甘特图建议，并要求输出包含JSON score参数和【诊断建议】标记块。sendRequest异步发送后，从response.replyText取回文本，再由parseAgentReply转成结构化DiagnoseResult，其中包括score、suggestions和recommendedSchedule。请求失败时捕获BusinessError并记录code与message，再走fallbackToLocalAnalysis；会话初始化失败也进入本地兜底。destroyBridge在UI组件销毁或退出功能模块时显式清空agentSession，避免IPC资源和内存引用泄漏。

四、结果解析与本地降级
parseAgentReply用正则从回复文本中提取形如score:85的分数，匹配不到时默认75分；再通过【诊断建议】标记截取建议块，recommendedSchedule直接回传replyText；若解析异常则返回60分和未能解析提示。fallbackToLocalAnalysis用于网络异常或云端不可达场景：当projectName长度大于20且expectedDays小于7时给40分，否则给80分，并返回固定的三步甘特图排期。这样即使网络或云端异常，界面也能给出结果，不至于一直卡在诊断中。

五、槽位对齐偏差与本地清洗
原文指出一个典型问题：用户输入往往很口语化，例如在明年春天暖和时去爬珠穆朗玛峰，云端可能把expectedDays槽位提取为空或无法匹配，形成槽位对齐偏差。槽位契约破裂会触发默认错误代码，前台若直接抛错，界面会卡在AI诊断中的loading状态。为此原文设计了LocalSlotInterceptor.extractDaysFromText，在本地用正则识别N天、N个月（按30天粗略折算）、N周或N星期（按7天折算），没有明显时间信息则返回0；调用时用finalExpectedDays = expectedDays大于0 ? expectedDays : (parsedDays大于0 ? parsedDays : 30)做清洗和缺省。原文称这层拦截能保证极端输入和网络延迟重试下分析链路100%成功回调，提升智能诊断体验。

六、技术取舍与落地注意
从原文实现看，这套方案把大模型推理放在系统与云端，应用端只做会话、契约和本地兜底，适合不想在端侧塞大模型的规划类应用。槽位配置文件是端云之间的契约，字段名、类型、是否必填要先定清楚；systemPrompt要约束输出结构，但大模型文本仍可能不稳定，所以正则解析、默认分、离线规则兜底缺一不可。原文还提醒agentSession要显式释放，异常分支要覆盖会话初始化和请求发送两类BusinessError。这些是接入Agent Framework Kit时更值得复用的工程细节。

原文在总结中说明，通过Agent Framework Kit对接小艺智能体，轻规划把计划录入变成了有专家反馈的互动，也完成了前9篇业务核心和Kit接入；后续将进入分布式数据库同步、UserId隔离与基于版本时钟的数据冲突消解。就本篇而言，核心可复用点是意图配置、槽位填充、会话管理、文本解析和本地兜底链路。