企业官网建设流程全解析

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 API：InsightIntent起始于 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 接收 DTO，Service 完成归一化，再向页面暴露不可变模型；页面只负责加载、空数据、错误、内容和重试状态。

二、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 ): Promise<OpenTaskResult> { 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 负责执行自身安全边界。

五、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 缩放；同时检查深浅色、状态栏、导航栏、键盘出现、重复点击和返回重进。这里列的是验收矩阵，不宣称当前仓库已经完成这些真机结果。

六、隐私与数据最小化

就医任务可能包含健康与家庭信息。迁移设计应默认本地优先，只保存完成任务所需字段；日志不得输出症状全文、药物、身份证明或家属信息。共享意图只携带最小标识，真正内容由应用在用户进入后按权限加载。清除任务时同时删除本地记录、缓存和已共享意图。

七、分层验收矩阵

八、官方参考与结论

官方参考：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 对象。

接入小艺前还要验证账号与设备权限、隐私说明、日志脱敏、取消与重试。智能体只能整理就医任务和提醒，不能生成诊断、处方或剂量；遇到急症信号必须优先引导线下急救，这一边界应同时存在于意图描述、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、系统能力、权限、错误码和设备可用性。尤其是官方错误码包含“小艺停止提供服务”等失败情形，页面必须有可见的失败状态与手动返回路径；医疗场景还要继续执行“不诊断、不处方、不提供剂量”的业务限制。

系列延伸阅读

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) }

适配表的价值在升级时兑现：每次目标版本变更，先对照表过一遍已知坑，能省下一整轮盲目排查。