HarmonyOS 5.0 Intents Kit 迁移设计InsightIntent 类型、安全边界与验收矩阵2026-07-29 迁移基线复核源 Web 合同已在 Node.js v24.14.1 下重新通过 Smoke test。HarmonyOS 部分继续以官方 Intents Kit 5.0.0(12) 类型边界为依据本文是 ArkTS/InsightIntent 迁移设计当前仓库仍无 HAP 与真机接入记录因此手机、平板、2in1 和小艺唤起结果明确保持“待实现/待真机”状态。本文讨论一个明确的迁移问题如何把现有 Node.js Web Demo 的结构化任务结果映射到 HarmonyOS 5.0 及以上版本的 ArkTS 数据模型与 Intents Kit而不把“设计完成”写成“真机已经接入”。当前仓库只有可运行 Web Demo没有 HAP、没有 AgentExtensionAbility也没有小艺平台发布记录因此所有 HarmonyOS 代码都属于迁移合同和待验证实现。2026 年 7 月 28 日复核华为官方 insightIntent ArkTS APIInsightIntent起始于 4.0.0(10)IntentActionInfo与IntentEntityInfo从 5.0.0(12) 起提供明确类型元服务也从 5.0.0(12) 起支持相关接口。版本结论来自官方文档项目状态来自真实仓库两者必须分开表述。一、迁移前先冻结 Web 数据合同计划接口稳定返回profile、mode、department、timeline、questions、reminders与familyBrief。HarmonyOS 页面不能直接承接松散 JavaScript 对象应先把字段转换成严格 ArkTS 接口并决定哪些字段允许为空、哪些字段必须由 Service 补默认值。interface CareProfile { patient: string age: number symptoms: string duration: string history: string medicines: string familyConcern: string audienceMode: elder | chronic | family } interface CarePlan { profile: CareProfile department: DepartmentDirection timeline: TimelineItem[] questions: string[] reminders: ReminderItem[] familyBrief: string }类型接口不是把 JSON 字段照抄一遍。迁移时还要处理数字范围、文本长度、未知枚举、缺失数组和服务端字段升级。建议由 Repository 接收 DTOService 完成归一化再向页面暴露不可变模型页面只负责加载、空数据、错误、内容和重试状态。二、InsightIntent 只传最小必要信息意图开放不等于把完整健康记录共享给系统。可共享数据应缩减为任务标识、任务名称和计划时间症状、病史、药物与家属关注点继续留在应用自己的受控数据层。identifier 和 entityId 必须稳定且唯一删除任务时同步清理对应意图。import { insightIntent } from kit.IntentsKit const careIntent: insightIntent.InsightIntent { intentName: PrepareCareVisit, intentVersion: 1.0, identifier: taskId, intentActionInfo: { scheduledAt: planTime }, intentEntityInfo: { entityId: taskId, entityName: 就医准备任务 } }上面只展示类型映射。真正接入时必须根据目标意图 Schema 核对字段处理系统能力不可用、服务停止、参数错误与共享失败。官方 API 存在不代表任何设备都能执行应用必须提供可见的失败提示和手动进入任务页的替代路径。三、把意图唤起与业务执行分层建议将入口分成 IntentAdapter、CarePlanService 和页面 ViewModel。IntentAdapter 只解析系统传入参数并转换为内部命令Service 校验任务是否存在、是否过期、是否需要用户确认ViewModel 再决定导航到准备页、流程页或错误页。这样可以避免意图处理器直接修改页面状态或持久化数据。interface OpenCareTaskCommand { taskId: string source: insight_intent | manual } async function executeOpenTask( command: OpenCareTaskCommand ): PromiseOpenTaskResult { const task await repository.findById(command.taskId) if (!task) return { type: not_found } if (task.archived) return { type: archived, task } return { type: ready, task } }返回联合类型比抛出通用异常更适合 UI。页面可以对not_found、archived、permission_denied与service_unavailable分别显示说明和恢复动作不会把所有失败都压成一句“加载失败”。四、急症保护不能依赖系统推荐当前 Node.js 规则会检查胸痛、呼吸困难、意识不清等信号并让急症分支覆盖普通医院意图。迁移到 HarmonyOS 后这条保护必须继续存在于应用 Service而不是假设小艺或意图框架已经替应用完成医疗判断。系统意图负责打开能力业务 Service 负责执行自身安全边界。输入业务结果UI 动作普通准备任务ready打开准备页并回读任务任务不存在not_found提示重新选择不自动创建敏感记录急症描述emergency优先展示线下急救提示系统服务不可用service_unavailable保留手动入口与重试缺少必要参数invalid_command停止执行并说明缺失项五、HarmonyOS 页面状态与多设备布局手机可使用底部主导航和二级页顶部返回平板与 2in1 可以把任务列表与详情并排。无论布局如何变化状态所有权不能改变ViewModel 保存加载结果组件只根据状态渲染。长列表放入 Scroll底部操作区保留系统手势安全距离文本使用 maxLines 与 textOverflow 防止窄窗口溢出。type PageState | { kind: loading } | { kind: empty } | { kind: content; plan: CarePlan } | { kind: error; message: string; retryable: boolean } | { kind: permission_denied }需要验证手机竖屏、横屏/小窗、平板横竖屏和 2in1 缩放同时检查深浅色、状态栏、导航栏、键盘出现、重复点击和返回重进。这里列的是验收矩阵不宣称当前仓库已经完成这些真机结果。六、隐私与数据最小化就医任务可能包含健康与家庭信息。迁移设计应默认本地优先只保存完成任务所需字段日志不得输出症状全文、药物、身份证明或家属信息。共享意图只携带最小标识真正内容由应用在用户进入后按权限加载。清除任务时同时删除本地记录、缓存和已共享意图。七、分层验收矩阵层级执行环境通过标准当前状态Web 合同Node.js v24.14.1npm test27 条显式断言已通过ArkTS 类型DevEco 目标工程严格类型编译无隐式空值待实现意图共享HarmonyOS 5.0.0(12)成功、重复、删除和错误码可回读待真机页面恢复手机、平板、2in1失败可重试手动入口始终可达待真机安全边界自动化 人工复核不诊断、不处方、不提供剂量规则基线已有迁移后重测八、官方参考与结论官方参考insightIntent ArkTS API、Intents Kit。本文的核心结论不是“接入几个 API”而是先把 Web 数据合同固化为 ArkTS 类型再把系统意图限制为最小入口业务执行、安全边界、错误恢复和多设备状态仍由应用自己负责。当前设计具备可实施路径但必须在真实工程构建和目标设备联调通过后才能写成完成。AI 辅助声明本文在人工复核真实源码、配置字段与验证记录的基础上使用 AI 辅助整理结构和语言功能边界、代码路径、版本信息与测试结论均以当前工程为准未执行的真机、云测或平台操作不会写成已经通过。HarmonyOS 5.0 迁移版本与设备边界当前仓库交付的是可运行 Web Demo 与规则 Agent小艺智能体仍属于迁移设计不宣称已经在真机注册或上架。面向 HarmonyOS 5.0 及以上版本时应先把profile、timeline、questions、reminders和familyBrief固化为严格 ArkTS 接口再由独立 Service 暴露给智能体意图页面不能直接承接动态 JavaScript 对象。验证层设备或环境通过标准当前结论数据契约Node.js Smoke test字段、急症分流和错误语义稳定可按源码复核ArkTS 类型DevEco 目标工程严格类型编译通过无隐式可空字段迁移时执行意图唤起HarmonyOS 5.0 真机普通、缺参、急症输入均落入正确分支尚未实测不写成完成多设备手机、平板、2in1确认页、错误页和返回路径均可达需逐设备回归接入小艺前还要验证账号与设备权限、隐私说明、日志脱敏、取消与重试。智能体只能整理就医任务和提醒不能生成诊断、处方或剂量遇到急症信号必须优先引导线下急救这一边界应同时存在于意图描述、Service 和测试用例。Intents Kit 5.0.0(12) 官方能力核对2026 年 7 月 28 日复核华为官方 insightIntent ArkTS API 文档InsightIntent起始于 4.0.0(10)其中IntentActionInfo与IntentEntityInfo从 5.0.0(12) 起提供明确类型元服务也从 5.0.0(12) 起支持相关接口。当前仓库尚无 ArkTS 模块因此本文给出的是可执行迁移合同不把官方 API 存在误写成项目已经接入。import { insightIntent } from kit.IntentsKit const careIntent: insightIntent.InsightIntent { intentName: PrepareCareVisit, intentVersion: 1.0, identifier: taskId, intentActionInfo: { scheduledAt }, intentEntityInfo: { entityId: taskId, entityName: 陪诊任务 } }上面的 ArkTS 片段用于说明类型映射真正落地前必须在目标工程核对意图 Schema、系统能力、权限、错误码和设备可用性。尤其是官方错误码包含“小艺停止提供服务”等失败情形页面必须有可见的失败状态与手动返回路径医疗场景还要继续执行“不诊断、不处方、不提供剂量”的业务限制。迁移检查点官方或源码依据验收方式意图版本intentVersion 当前初始值为 1.0配置、代码与测试夹具保持一致实体标识identifier、entityId 需要业务唯一值重复任务与删除场景回归失败路径API 定义服务停止等错误码断网、服务不可用、缺参均可恢复当前项目状态仅有 Node.js Web Demo未构建 HAP、未真机联调明确标为待办系列延伸阅读InsightIntent 驱动的迁移设计,核心是把用户想说的话变成系统能理解的结构化意图。这套思路在准备台页面上体现为把患者信息变成任务结构,在清单生成上体现为把任务变成问题清单——都是同一个结构化思想的延伸。语音交互篇则处理了意图的另一端:老年用户说的话如何被准确识别。系列的安全边界与隐私设计保证这些能力不越界。相关文章:【安心陪诊】准备台页面实现:把患者信息变成可执行陪诊计划【安心陪诊】语音交互设计:陪诊助手的声音应该怎样不机械【安心陪诊】医生沟通清单生成:让家属进诊室前知道该问什么【安心陪诊】医疗安全边界:不诊断、不剂量、不替代十三、接入前检查清单HarmonyOS 5.正式接入前工程侧要过一遍检查清单SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停带着不匹配的版本往上冲排错成本会翻倍。interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] [ { name: SDK/API版本匹配, pass: false }, { name: 权限声明完整, pass: false }, { name: 开关集中管理, pass: false }, { name: 包体积增量预算, pass: false }, ] const allPass checklist.every(x x.pass)检查清单跑通的标志是新建工程按清单接入一次成功且不依赖任何口头经验。做不到说明文档还缺关键步骤。十四、常见坑与版本适配记录HarmonyOS 5.最常踩的坑集中在三处示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表注明坑点、影响版本、修复方式与验证方式。interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p p.sinceApi api) }适配表的价值在升级时兑现每次目标版本变更先对照表过一遍已知坑能省下一整轮盲目排查。