【寻迹校园 HarmonyOS NEXT 实战 24】AI 不可用时怎么办：为 HarmonyOS 智能应用设计确定性降级路径

【寻迹校园 HarmonyOS NEXT 实战 24】AI 不可用时怎么办为 HarmonyOS 智能应用设计确定性降级路径这是“寻迹校园 HarmonyOS NEXT 实战”系列第 24 篇。本文结合本地ReportService、XiaoYiAgentAdapter、Agent Framework KitFunctionComponent与 API 24 真机验收说明为什么 AI 应建立在可独立工作的业务基线上以及如何把“本地候选”“显式复制交接”“系统小艺不可用”“自动 queryText 失败”分别记录。上图为原创生成的架构插画不是项目截图。主干是本地候选与安全核验AI 是旁路解释能力旁路失败时查看详情、申请核验和安全交接仍能继续。一、智能应用最危险的依赖是“AI 一失败产品就停”网络中断、账号未登录、隐私协议未同意、系统版本不足、Agent 参数错误或平台服务异常都可能让 AI 暂时不可用。如果发布、候选、认领和交接都依赖一次模型调用用户会在最需要帮助时遇到死路。“寻迹校园”的原则是V1.0 本地确定性流程先闭环V1.1 再让小艺比较脱敏 Top 3 并解释相似点与冲突。AI 不拥有业务状态也不是唯一入口。二、先定义一条不含 AI 的完整主链本地主链包括用户发布丢失或拾得记录ReportService召回相反类型的开放记录本地规则计算信息相似分、理由和冲突用户查看候选详情用户提交私密核验答案拾得侧审核并安排校内安全交接双方确认后结案。这条链不需要模型返回文本。小艺只在第 34 步之间提供辅助比较因此任何 AI 故障都不会删除原生候选。三、AI 适配器只接收脱敏派生数据XiaoYiAgentAdapter先调用reportService.getMatchBundle()最多取前三条候选再生成不超过 240 字的摘要。摘要只保留类型、类别、模糊地点、短日期和公开特征。lines.push(比较以下脱敏校园失物候选列出相似点与冲突不判断归属。);lines.push(查询${this.compactReport(bundle.query)});candidates.forEach((candidate:MatchCandidate,index:number){lines.push(候选${index1}${this.compactReport(candidate.report)});});适配器还会替换手机号、证件号和联系方式模式。私密核验答案、照片原图和精确位置不进入摘要。四、没有候选时不要为了“有 AI”强行调用当本地候选为空适配器返回“暂无足够证据交给小艺比较”。这不是模型错误而是业务证据不足。正确降级是返回原生空态引导用户稍后刷新或完善公开描述错误做法是让模型凭一条查询记录自由猜测校园里可能出现什么物品。先召回、后调用 AI 能控制成本、隐私和幻觉也让模型输出有清晰来源。五、系统能力检测要映射成用户能理解的状态XiaoYiFunctionPage通过FunctionController.isAgentSupport()检测能力并映射典型错误条件用户提示可执行下一步未同意小艺隐私协议请先同意隐私协议用户完成系统侧授权未登录华为账号请先登录华为账号登录后重新检测网络异常请联网后重试保留原生候选Agent 参数无效检查平台配置开发侧修复不让用户反复点击设备或账号不支持当前暂不支持返回本地候选页面不能把所有错误统一写成“AI 失败”也不能无限自动重试。用户应始终有返回原生流程的可见出口。六、真实验收必须拆开记录多个证据点2026 年 8 月 20 日项目在BLK-AL80、HarmonyOS API 24 真机完成了以下验证HDC 连接和/data/local/tmp写入passedApp 冷启动、isAgentSupport和真实FunctionComponentpassed系统小艺界面打开并显示“寻迹校园匹配助手”passed用户显式复制 193 字脱敏摘要、粘贴发送并获得三候选可见回复passedFunctionOptions.queryText自动显示或自动发送failed。这几项不能互相替代。系统界面打开不证明参数自动带入模型能回答手工问题不证明 App 摘要已交接平台“已上架”也不等于 App 已发布到 AGC。七、为什么最后选择显式复制、粘贴、发送API 24 真机空白新会话复测中App 已把 193 字摘要写入FunctionOptions.queryText但系统输入框为空控制树也没有查询和候选文本。因此自动交接被标记为失败。项目没有用旧历史回复冒充成功而是增加用户明确触发的路径App 二次脱敏摘要 → 用户点击“复制脱敏摘要” → LOCALDEVICE 系统剪贴板 → FunctionComponent 打开真实小艺 → 用户粘贴并发送 → 小艺返回候选比较这条路径多了一步却具备可见、可理解、可复核的用户授权动作。上图把已通过的显式复制路径和始终存在的原生降级出口放在一起。自动queryText仍保留为失败项不能用显式复制的成功覆盖它。八、剪贴板路径也要做最小化设计项目只在用户点击按钮后写入本机剪贴板使用ShareOption.LOCALDEVICE不读取剪贴板、不持久化内容也不新增读取权限。写入前再次调用prepareClipboardPayload()完成二次脱敏和长度限制。这样即使上游摘要被修改也不会直接把未检查的长文本交给系统小艺。剪贴板不是天然安全区。页面需要提示内容用途避免加入联系方式、证件号和精确住址未来还可以评估自动清理或一次性内容但不能宣称当前已经实现。九、AI 回复不得写回权威业务状态小艺可以列出相似点、冲突和建议补充信息但不会修改候选分数自动同意认领写入私密核验答案变更报告状态安排交接或完成结案。所有状态变化仍由ClaimService、HandoffService和 Repository 执行。模型文本是可丢弃的解释结果不是权威数据源。这个边界能避免提示词变化、模型升级或网络异常破坏业务一致性。十、降级不是只显示一条 Toast一个完整降级需要四部分保留可操作的原生结果解释失败原因和影响范围提供有限重试或返回路径不丢失用户已经完成的工作。例如用户进入小艺页后发现账号未登录返回时仍能看到原 Top 3候选详情、私密核验和安全交接继续可用。若页面只弹“调用失败”然后停在空白页不算可用降级。十一、离线和证据不足要分开离线表示外部能力暂时不可用本地候选仍可能完整证据不足表示本地没有合法候选即使联网也不应让模型猜。两者对应不同提示离线小艺暂时不可用已保留原生候选你可以继续查看与核验。证据不足暂无足够候选交给小艺比较请稍后刷新或完善公开描述。把两者混成“AI 暂无结果”用户不知道应该重试网络还是补充信息。十二、重试必须有上限和触发条件系统能力检测可以提供“重新检测”但不应在生命周期回调中持续重试。网络恢复、账号登录或协议同意属于外部状态变化用户主动触发一次重试更可控。若未来增加模型 HTTP 调用应设置超时、有限次数、幂等标识和页面销毁保护。重试失败后继续返回本地结果不能形成请求风暴。当前 Agent Framework Kit 路径没有引入自建模型网络请求不能把未来的重试设计描述成现状。十三、验证降级要主动制造失败仅在正常网络下看到 AI 回复不足以证明降级。测试矩阵至少包括设备系统版本低于要求isAgentSupport()返回 false未登录账号未同意隐私协议网络断开摘要为空复制失败系统小艺打开但参数未自动带入用户返回后原生候选仍完整AI 回复后不产生任何业务状态写入。当前真机已经证明显式复制核心链路断网、暗色模式、字体放大和另一型号设备仍为not run不应省略。十四、本地自动化能证明什么scripts/xiaoyi-agent-adapter.test.mjs验证候选最多三条、摘要不超过 240 字以及手机号、证件号和联系方式被隐藏scripts/xiaoyi-copy-handoff.test.mjs检查只写LOCALDEVICE剪贴板、不读取内容并保留明确的复制粘贴文案。powershell-ExecutionPolicy Bypass-File.\scripts\test-local.ps1这些测试可以证明源码合约和普通业务逻辑不能替代系统小艺 UI、账号状态、真机剪贴板和可见回复。设备证据与自动化证据必须分别记录。十五、上线状态也要分层表达当前 Agent 平台“已上架”来自用户确认本次文章写作没有重新登录平台独立回读。AppGallery Connect 应用状态仍是“未提交”没有执行应用市场发布。因此准确表达是Agent 能力已在 API 24 真机跑通显式复制交接不能写成“应用已在华为应用市场上线”也不能把 Agent 平台状态当作 AGC 审核证明。十六、本文小结可靠的 HarmonyOS 智能应用不是“模型永远成功”而是 AI 失败后核心任务仍可完成。先建立本地确定性候选和核验主链再用小艺解释脱敏 Top 3外部能力不可用时保留原生结果并把每个证据点分别标记。“寻迹校园”已经证明本地候选、真实FunctionComponent和显式复制到小艺的链路自动queryText交接仍然失败。保留这个失败结论正是工程可追踪性的一部分。系列导航第 24 篇 / 共 50 篇。上一篇《相反类型召回与稳定 Top 3》下一篇《匿名认领申请设计》。