【寻迹校园 HarmonyOS NEXT 实战 46】小艺不可用也不阻断业务：Agent 能力门禁与原生候选回退

本章导读：这是“寻迹校园 HarmonyOS NEXT 实战”系列第 46 篇。本文基于 XiaoYiAgentPage、XiaoYiFunctionPage、XiaoYiAgentAdapter 与项目真机记录，讨论一个比“成功拉起智能体”更重要的问题：当设备、账号、网络、平台关联或审核状态不满足要求时，核心失物招领流程是否仍然可用。本文保留 2026-08-14 isSupport:false 的真实失败证据，同时说明后续能力恢复后的验收结果，不把某一次平台状态写成永久结论。

上图是原创工程概念图，不是系统小艺截图。图中的主路径始终是本地候选、详情、核验和安全交接，小艺只是通过能力门禁接入的增强分支。

一、可选 AI 能力不能成为核心业务单点

寻迹校园的 V1.0 核心闭环是：发布记录、确定性召回、候选解释、认领核验、固定地点交接和双方确认。这个闭环不依赖云端大模型，也不要求用户一定具备小艺智能体的可用条件。

V1.1 才增加 Agent Framework Kit，用小艺比较已经脱敏的少量候选。架构关系不是“原生匹配被 AI 替换”，而是：

原生确定性候选 -> 用户可直接查看、核验、认领
                  \-> 可选的小艺比较增强

一旦把小艺按钮设计成唯一入口，平台审核、应用关联、账号登录、网络波动都会扩大成核心业务故障。

二、回退能力要从路由之前开始

进入系统组件页前，XiaoYiAgentPage 先调用业务适配器准备快照。只有查询记录存在、候选召回成功且至少有一条候选时，才生成脱敏摘要。

const result = await xiaoYiAgentAdapter.prepareMatchSnapshot(this.queryReportId);
if (result.success && result.data) {
  this.snapshot = result.data;
} else {
  this.snapshot = undefined;
  this.errorMessage = result.userMessage;
}

快照失败时页面显示错误说明和“返回原生候选”按钮。也就是说，回退不是在系统小艺报错后临时补一个 Toast，而是从数据准备阶段就拥有明确出口。

三、原生候选是权威数据，小艺只读摘要

小艺页不会直接持有长期业务数据，也不会改变候选分数、认领状态或物品归属。它只消费 ReportMatchBundle 经过白名单压缩后的文本快照。

这个边界带来两项收益：

• 平台失败不会破坏 Repository 中的候选和状态机；
• 用户从系统小艺返回后，仍能在原生页面继续查看同一批候选。

AI 输出也不会自动写回业务状态。即使小艺认为某条候选“更像”，最终仍需用户查看详情并完成私密特征核验。

四、第一道能力门禁：系统 API 版本

宿主页在进入独立 Function 页面前检查运行时 API 版本。项目当前以 API 20 为 Agent Framework Kit 页面门槛：

if (deviceInfo.sdkApiVersion < 20) {
  this.errorMessage = '当前系统版本低于能力要求，请使用受支持的真机。';
  return;
}

这里的版本检查只负责排除明确不满足的系统环境。它不能证明账号、地区、隐私协议、Agent 关联和云端仓库已经可用，所以后面还需要动态支持性检查。

五、第二道能力门禁：UIAbilityContext

FunctionController.isAgentSupport() 需要 UIAbilityContext。页面从当前 UI 上下文获取宿主，并在空值时停止调用：

const context = this.getUIContext().getHostContext() as common.UIAbilityContext | undefined;
if (!context) {
  this.statusMessage = '未获取到应用上下文，请返回后重试';
  return;
}

如果忽略这一步，错误路由、预览环境或宿主生命周期异常可能被误报成“智能体不可用”。先确认本地调用条件，有助于把本地故障和平台故障分开。

六、第三道能力门禁：isAgentSupport()

页面不会在检查完成前直接渲染 FunctionComponent，而是先读取支持性布尔值：

try {
  this.supported = await this.controller.isAgentSupport(context, 'agent_xxx');
  this.statusMessage = this.supported ?
    '小艺能力已就绪' : '当前设备或账号暂不支持此智能体';
} catch (error) {
  this.statusMessage = this.mapError((error as BusinessError).code);
}

false 与异常需要区分。false 表示当前条件组合不支持指定智能体；异常则可能指向登录、隐私协议、网络、参数或平台内部错误。

七、错误分类必须给用户下一步

项目把常见错误映射为可行动文案：未同意隐私协议就引导确认协议，未登录就引导登录，网络异常就提示联网，参数无效则提示检查平台关联。

普通用户不需要看到长错误栈，但不能只收到“打开失败”。理想错误状态至少包含：发生在哪一阶段、是否可以重试、是否可以返回原生候选。

开发日志可以保留错误码、支持性布尔值和阶段名，但不应记录完整候选摘要、真实 Agent ID、剪贴板内容或账号设备信息。

八、禁止自动循环拉起

平台能力失败后自动反复调用 checkSupport() 或重复打开系统组件，容易形成请求风暴，也可能触发平台风控。寻迹校园只在页面首次进入时检查一次，后续重试由用户点击“重新检测”明确触发。

安全状态机可以写成：

CHECKING -> SUPPORTED -> 用户点击打开
CHECKING -> UNSUPPORTED -> 返回原生候选 / 用户手动重试
CHECKING -> ERROR -> 展示原因 / 返回原生候选

不设置 ERROR -> 自动 CHECKING 的无限边。

九、原生回退到底保留哪些能力

“回退”不是退回一个空白首页，而是保留完整可行动路径：

• 查看候选列表和每条匹配理由；
• 打开候选详情，核对公开特征和冲突；
• 发起私密特征核验；
• 进入认领审核门禁；
• 选择固定校内交接点与时间片；
• 双方确认后结案；
• 对异常内容发起举报。

因此小艺不可用降低的是“对话式比较便利性”，不是“失物招领业务可用性”。

十、能力门禁与回退全流程

上图展示五个关键节点：原生候选、脱敏快照、能力检查、小艺增强、原生详情/核验/交接。黄色分支表示不可用时继续原生流程，回到门禁的虚线只代表用户主动重试，不代表自动循环。

十一、2026-08-14 的失败证据如何解读

2026-08-14 真机记录中，系统查询返回 isSupport:false，错误摘要为“The agentId is unsupported”。同一轮日志表明请求已经到达小艺服务，云端仓库却没有找到可用的应用内 Agent。

这组证据可以支持三条结论：

1. 应用确实调用了真实 Agent Framework Kit；
2. 当时的阻塞更接近云端可用状态或应用关联，而不是本地确定性匹配；
3. 原生 3 条候选、详情和后续安全流程仍然可用。

它不能支持“Kit 永久不可用”或“代码完全正确”。平台状态会变化，本地参数和关联仍需要继续核对。

十二、后续恢复也不能抹掉历史失败

后续记录中，项目在受支持真机上完成了 isAgentSupport=true、FunctionComponent 显示、系统小艺拉起和可见回复。2026-08-20 又完成显式复制、粘贴、发送与候选比较回复。

这说明早期阻塞已经变化，但文章仍保留 8 月 14 日失败，因为它证明了回退设计不是纸面假设。工程复盘应该保留状态演进：

8 月 14 日：Agent unsupported，原生回退 passed
8 月 20 日：Agent 拉起和对话 passed，自动 queryText failed
8 月 20 日后：显式复制/粘贴 passed

不同结果属于不同验收项，不能互相覆盖。

十三、为什么自动 queryText 失败仍不阻断

系统组件已能打开，不代表 FunctionOptions.queryText 一定自动出现在新会话输入框。项目空白会话复测中，候选摘要没有自动显示，因此自动交接记录为 failed。

当前可靠路径是用户显式确认摘要、复制到本机剪贴板、打开小艺、粘贴并发送。即使复制失败或系统小艺不可用，页面也持续提示返回原生候选。

这里体现了同一原则：任何增强链路都不能成为用户继续业务的唯一钥匙。

十四、日志如何区分本地阻塞与平台阻塞

建议只记录阶段化摘要：

阶段	可记录	不应记录
快照准备	成功/失败、候选数量	候选全文、私密特征
上下文	是否获取宿主	账号、设备序列号
支持性	布尔值、错误码	完整 Agent/Workflow ID
系统拉起	回调阶段、是否可见	对话全文、剪贴板正文
回退	用户返回原生候选	用户核验答案

如果本地快照已经失败，就没有必要把问题归因于平台；如果网络请求到达云端但返回不支持，则应检查审核、关联、账号和区域。

十五、回退按钮也要通过可用性验收

回退路径常被当作一句文案，但真实验收至少应覆盖：

• unsupported 状态下按钮可点击；
• 点击后回到原候选列表而不是首页；
• 查询记录 ID 和候选排序仍保留；
• 页面不会再次自动拉起小艺；
• 返回后详情、核验、交接入口仍可用；
• 深色模式和长错误文案不会挤掉操作按钮。

如果回退只能“退出”，却不能“继续完成任务”，它仍然不是业务降级。

十六、当天验证与历史证据分开

2026-08-28 本文准备时，项目本地四组自动化测试全部通过，完整 APP 构建返回 BUILD SUCCESSFUL。但当天 hdc list targets -v 没有发现连接设备，因此没有把历史真机记录描述为当天复测。

这种写法比一句“已真机验证”更精确：代码与构建是当天证据，Agent 真机行为来自已有日期明确的记录。

十七、适用范围与尚未证明的结论

本文能证明当前项目存在版本、上下文、支持性和运行错误门禁，且小艺失败时原生候选路径仍保留；也能证明项目曾真实经历 unsupported 并成功使用回退。

本文不能证明所有设备、地区和账号都支持该 Agent，不能证明平台状态不会再次变化，也不能证明自动 queryText 已恢复。商店中的某个版本是否包含该能力，还要以对应安装包和平台绑定版本为准。

十八、小结

可选 AI 能力的正确接入方式不是把它放在最显眼的位置，而是把它放在正确的依赖层级：核心业务先独立成立，AI 再通过能力门禁增强体验。

寻迹校园用原生确定性候选作为权威路径，用小艺做只读比较，用可行动错误、用户主动重试和原生回退吸收平台不确定性。即使系统组件暂时不可用，用户仍能查看、核验、交接和结案，这才是真正的“增强而不绑架”。

下一篇：《【寻迹校园 HarmonyOS NEXT 实战 47】小艺 Agent 审核驳回复盘：工作流“有输出”为什么智能体“无回复”》。