【寻迹校园 HarmonyOS NEXT 实战 45】FunctionComponent 接入实战：支持性检查、queryText 与错误码映射

本章导读：这是“寻迹校园 HarmonyOS NEXT 实战”系列第 45 篇。本文以 XiaoYiAgentPage、XiaoYiFunctionPage、本机 HarmonyOS SDK 声明和 2026-08-20 真机记录为依据，完整拆解快照准备、API 版本门禁、独立 @Entry 页面、FunctionController.isAgentSupport()、FunctionOptions、onError 与可恢复错误提示。特别说明：queryText 自动交接在空白新会话复测中失败，当前成功路径是用户显式复制、打开小艺、粘贴并发送。

上图是原创接入流程概念图，不是系统小艺截图。组件能否编译、页面能否进入、系统弹窗能否打开、参数是否自动交接，是四个不同证据层级。

一、为什么不能直接在匹配页渲染组件

匹配页承担候选列表、详情跳转和原生回退。如果直接把 FunctionComponent 塞进列表，每次记录切换、断点变化或组件重建都可能触发支持性检查，平台错误也会污染核心页面状态。

寻迹校园把流程拆成两页：

XiaoYiAgentPage：准备并展示脱敏快照
XiaoYiFunctionPage：检查平台支持、复制摘要、渲染 FunctionComponent

业务数据准备与系统能力接入相互隔离，页面职责更容易验证。

二、宿主页先准备快照

XiaoYiAgentPage.aboutToAppear() 调用 prepareSnapshot()。只有 reportService.getMatchBundle() 成功且存在候选时，才得到 XiaoYiAgentSnapshot。

加载期间显示“正在准备脱敏候选摘要”；失败则给出返回原生候选的按钮；成功后展示候选数量、摘要文本和“先复制、再打开小艺粘贴发送”的说明。

这意味着平台组件不会接触原始 ItemReport，只接收已经压缩和脱敏的文本。

三、第一道门：API 版本检查

打开独立页面前，宿主页检查：

if (deviceInfo.sdkApiVersion < 20) {
  this.errorMessage = '当前系统版本低于小艺 Agent Framework Kit 要求，请使用 HarmonyOS 6.0 或更高版本真机。';
  return;
}

本机 SDK 的 Agent Framework 声明标注相关接口从 6.0.0(20) 起提供。版本门禁能避免在明显不支持的系统上进入页面，但它不能代替设备、账号和平台关联检查。

四、为什么使用独立 @Entry 页面

XiaoYiFunctionPage 是单独的 @Entry @Component 页面，通过 Router 参数接收 queryText 与 candidateCount。

这样做有三个收益：

• 系统 Kit 生命周期不与主 Navigation 页面混杂；
• 支持性检查和错误文案集中；
• 从小艺返回后仍能回到原生候选路径。

代价是 Router 参数必须防空，不能假设每次都由正确入口进入。

五、第二道门：获取 UIAbilityContext

isAgentSupport() 需要 UIAbilityContext。页面先从 getUIContext().getHostContext() 获取并检查，拿不到上下文时显示“无法获取应用上下文，请返回后重试”。

这比强制类型转换后立即调用更安全。Previewer、错误路由或组件宿主变化都可能使上下文不满足预期。

六、第三道门：isAgentSupport()

当前核心检查如下，示例已替换真实 Agent ID：

private async checkSupport(): Promise<void> {
  this.checking = true;
  const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  if (!context) {
    this.statusMessage = '无法获取应用上下文，请返回后重试';
    this.checking = false;
    return;
  }
  try {
    this.supported = await this.controller.isAgentSupport(context, 'agent_xxx');
    this.statusMessage = this.supported ?
      '小艺能力已就绪' : '当前设备或账号暂不支持此智能体';
  } catch (error) {
    this.statusMessage = this.mapError((error as BusinessError).code);
  }
  this.checking = false;
}

只有 supported=true 才渲染 FunctionComponent。不支持时页面保留状态文案和重试按钮，不让一个无效控件占据主操作位。

七、isAgentSupport=false 与抛错不同

布尔值 false 表示当前组合不支持指定智能体；异常则可能提供可分类的错误码。两者都不能简单显示“加载失败”。

用户需要知道下一步：登录账号、同意隐私协议、联网重试、检查平台参数，或返回原生候选。错误分类是可恢复体验的一部分。

八、当前错误码映射

本机 SDK 声明中，isAgentSupport() 可能抛出参数、隐私协议、账号、网络和内部错误。项目当前映射为：

错误码	用户文案	可行动作
1022400010	智能体参数无效，请检查平台配置	开发/运营检查关联配置
1022400011	请先同意小艺隐私协议	用户完成协议确认
1022400012	请先登录华为账号	用户登录后重试
1022400013	网络异常，请联网后重试	恢复网络后重试
其他	小艺助手暂时无法打开	返回原生候选或稍后重试

SDK 还声明 1022400014 为内部错误，当前项目落入通用文案。公开 UI 不需要把内部错误码直接甩给普通用户，但日志可在不包含摘要正文的前提下记录码值。

九、FunctionOptions 负责什么

项目构造的 FunctionOptions 包含：

• title 与 titleFontSize；
• iconSize 与图标颜色；
• queryText；
• ButtonType.CAPSULE；
• ControlSize.NORMAL；
• 阴影、标题色和背景色。

这些选项控制组件入口的内容和外观，不代表目标智能体已经正确关联，也不保证 queryText 在所有系统版本中自动显示。

十、queryText 的契约与运行事实必须分开

本机 SDK 的 FunctionOptions.queryText?: string 注释是“Initial query text”。项目因此继续传入脱敏摘要，作为兼容输入。

但 2026-08-20 使用空白新会话复测时：系统小艺成功打开，输入框却为空，193 字摘要没有自动显示或发送。因此本项目明确记录：

系统小艺拉起：passed
queryText 自动交接：failed
显式复制/粘贴/发送：passed

类型定义是契约线索，真机记录才是当前行为证据。

十一、为什么保留 queryText 但不依赖它

完全删除 queryText 会失去未来系统版本恢复支持时的兼容入口；把它当成功路径又会让当前用户在空输入框前迷失。

因此当前策略是：

• 继续传入脱敏 queryText；
• 页面先展示同一份摘要；
• 用户显式点击复制；
• FunctionComponent 打开小艺；
• 用户粘贴并发送；
• 验收只以可见粘贴内容和回复为准。

这种“保留兼容输入、另建可靠路径”的方式比猜测平台行为更稳。

十二、复制前还要二次脱敏

copyQueryText() 不直接把页面字符串写入剪贴板，而是先调用 prepareClipboardPayload()。该方法再次执行正则替换、空值检查和 240 字上限。

即使 Router 参数被意外构造，进入系统剪贴板前仍有一道独立业务防线。复制成功后页面显示“已复制，可再次复制”，失败则显示重新复制和错误原因。

十三、剪贴板范围限制在本机

适配器设置 pasteboard.ShareOption.LOCALDEVICE，只调用 setData()，没有读取剪贴板。用户操作是显式的，摘要不在应用中持久化，也不记录到日志。

这不能保证系统剪贴板等同于私有内存，但能明确本项目没有主动使用跨设备共享，也没有为了复制新增读取权限。

十四、onError 仍然需要

即使 isAgentSupport() 已通过，组件渲染或打开阶段仍可能出现参数或内部错误。FunctionComponent 的 onError 会把 BusinessError.code 交给同一错误映射函数，并把 supported 状态收敛为不可用。

这避免入口看起来仍可点击，却在每次点击后重复失败。支持性检查是前置门，onError 是运行期保险。

十五、组件渲染必须受状态保护

页面的逻辑应保持：

checking -> LoadingProgress
supported -> FunctionComponent
unsupported/error -> 文案 + 重试 + 返回原生候选

不能先渲染组件再异步隐藏，否则用户可能在检查完成前触发无效操作。也不能把 supported 永久缓存为全局真值，因为账号、网络和平台配置可能变化。

十六、完整时序

上图把自动 queryText 路径画成虚线失败分支，显式复制、打开和粘贴才是当前验收成功路径。它是技术时序示意，不是系统运行截图。

十七、构建成功不能证明什么

assembleApp 成功只能证明 ArkTS、资源、依赖和打包在当前环境中通过。它不能证明：

• 真机支持指定 Agent；
• 账号已登录或隐私协议已同意；
• Agent 与 bundle 关联正确；
• 系统弹窗成功打开；
• queryText 自动显示；
• 回复使用的是本次新摘要而非历史会话。

这些需要分层记录，尤其要用空白新会话排除历史回复干扰。

十八、真机验收应该如何拆分

阶段	证据
API 门禁	不支持版本出现明确提示
支持性检查	页面显示“能力已就绪”或可行动错误
组件入口	FunctionComponent 可见且可点击
系统拉起	新会话标题与目标智能体一致
参数交接	输入框真实可见内容，而不是代码参数
用户复制	App 显示复制成功，剪贴板内容一致
粘贴发送	空白会话中出现完整候选摘要
回复归因	回复明确比较本次候选 1～3
回退	失败后仍可返回原生候选

寻迹校园当前已记录显式复制链路成功，同时保留自动交接失败结论。

十九、日志与隐私边界

排查平台错误时可以记录页面阶段、错误码和支持性布尔值，但不要打印：

• 完整候选摘要；
• 真实 Agent/Workflow ID；
• 手机号、证件号、微信号；
• 剪贴板内容；
• 签名、Profile、账号或设备序列号。

公开文章里的 ID 使用 agent_xxx 占位，既能讲清接口，也不扩大配置暴露面。

二十、本章证据边界

本章能证明：当前代码存在 API 20 门禁、独立 Function 页面、isAgentSupport()、错误映射、FunctionOptions、onError 和显式复制路径；2026-08-20 真机上系统小艺打开与复制/粘贴/回复链路通过。

本章不能证明：queryText 自动交接成功、所有设备账号地区都支持、当前线上商店包已经包含该能力、未来 SDK 错误码与行为不会变化。华为官方对 Agent Framework Kit 的当前定位可在 HarmonyOS 文档中心 查询，发表或升级前应再次核对。

二十一、小结

可靠的 FunctionComponent 接入不是“写一个组件标签”，而是由快照准备、API 门禁、上下文检查、支持性检查、受控渲染、错误映射、显式数据交接和原生回退共同组成。

最重要的工程结论是：不要把参数已赋值当成用户已经收到。寻迹校园保留 queryText 作为兼容输入，但用空白新会话证明自动交接失败，再把用户可见的复制/粘贴链路做成真正的成功路径。

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