【寻迹校园 HarmonyOS NEXT 实战 08】V1.0 核心应用 + V1.1 小艺增强：避免 AI 平台阻塞首版交付

这是“寻迹校园 HarmonyOS NEXT 实战”系列第 8 篇。本文从真实交付风险出发，说明 HarmonyOS NEXT 应用如何把确定性核心闭环与 Agent Framework Kit 增强拆成两条可独立运行、独立验证的路线。

上图为本文原创生成的双版本路线图，不是平台或项目截图。V1.0 保证用户能够完成发布、筛选、匹配、认领和结案；V1.1 在能力可用时提供对话式比较和追问。

一、AI 功能最大的风险往往不在模型效果

做 HarmonyOS AI 应用时，团队容易把注意力全部放在提示词和回答质量上。但真正影响首版交付的，常常是模型之外的条件：

• Agent 是否通过平台审核；
• Agent 与应用是否完成关联；
• 当前账号、地区和设备是否满足条件；
• 签名包与平台配置是否一致；
• 系统服务是否支持当前能力；
• 网络、登录态和缓存是否正常；
• 平台状态是否已经传播到真机。

这些条件有一项不可控，AI 入口就可能不可用。如果发布、搜索和认领也依赖同一个 Agent，核心产品会被外部平台状态整体阻塞。

二、先定义没有 AI 也必须成立的核心价值

“寻迹校园”的核心价值不是“能和小艺聊天”，而是完成一条可核验的失物招领路径：

1. 用户结构化发布丢失或拾得信息；
2. 本地规则按类别、地点、日期和特征召回候选；
3. 页面展示相似依据与冲突点；
4. 用户提交脱敏认领证明；
5. 模拟发布者完成审核；
6. 双方在固定交接点完成确认；
7. 记录结案或进入举报治理。

这条路径完全由 ArkUI、Service、Repository 和本地确定性规则支撑。即使 Agent 不可用，用户仍然知道下一步做什么。

三、AI 只增强“比较与追问”，不拥有业务权威

项目把小艺放在候选解释层，而不是状态机核心层。XiaoYiAgentAdapter 先从 ReportService 获取匹配结果，只取少量候选并进行脱敏，再构造受限问题。

const bundleResult = await reportService.getMatchBundle(queryReportId);
if (!bundleResult.success || !bundleResult.data) {
  return new OperationResult<XiaoYiAgentSnapshot>(false, bundleResult.userMessage);
}

const candidates: MatchCandidate[] = bundleResult.data.candidates.slice(0, 5);
if (candidates.length === 0) {
  return new OperationResult<XiaoYiAgentSnapshot>(false, '暂无足够证据交给小艺比较');
}

Agent 可以总结差异、解释匹配理由、最多追问两个安全问题，但不能：

• 判定物品所有权；
• 同意或拒绝认领；
• 修改 ReportStatus；
• 读取私密核验特征；
• 索要手机号、证件号或精确住址；
• 把回答直接写回权威数据。

这条边界保证模型回答错误时，业务状态不会被自动污染。

四、V1.0 与 V1.1 分别交付什么

V1.0 核心应用关注确定性闭环：

• 结构化发布和草稿恢复；
• 分类、地点、时间与关键词组合筛选；
• 可解释候选召回；
• 认领、审核、交接和结案状态机；
• 举报与本地治理；
• Agent 不可用时的原生提示和降级路径。

V1.1 小艺增强关注平台能力：

• Agent 配置与内容审核；
• 应用关联和能力门禁；
• isAgentSupport 或等价支持检测；
• FunctionComponent 真实拉起；
• 脱敏候选摘要；
• 可见对话回复和失败反馈；
• 真机网络、账号和缓存复测。

两个版本共享业务模型，但证明标准不同。

五、能力门禁必须出现在 UI 之前

一个“看起来像 AI 对话”的自绘页面不能证明 Agent Framework Kit 已经可用。进入真实能力前，应该先检查：

• 当前系统 API 是否满足项目要求；
• 当前设备是否支持；
• Agent 是否已发布并可被查询；
• 应用关联与签名是否正确；
• 网络和账号环境是否可用；
• 查询是否命中了旧缓存。

支持检测失败时，页面应明确告诉用户原因和替代路径，例如继续查看本地候选，而不是保留一个永远 loading 的入口。

六、降级不是错误页，而是一条完整替代路径

上图展示同一份候选数据的两条消费路径。左侧原生页面始终可用；右侧小艺分支只有在能力门禁通过后才进入。

合理的降级流程是：

用户打开智能匹配
  -> 先展示本地候选和匹配理由
  -> 检测 Agent 能力
  -> 支持：准备脱敏快照并拉起 FunctionComponent
  -> 不支持：保留原生候选，展示可理解说明

这意味着 AI 是“加号”，不是“开关”。用户不会因为外部审核或网络故障失去核心流程。

七、隐私边界必须先于提示词优化

项目传给 Agent 的不是完整数据库记录，而是受限快照。Adapter 会隐藏手机号、证件号和联系方式，并限制单条文本长度。

private safeText(value: string): string {
  let result = value.trim().replace(/1[3-9][0-9]{9}/g, '[已隐藏手机号]');
  result = result.replace(/[0-9]{17}[0-9Xx]/g, '[已隐藏证件号]');
  result = result.replace(/(微信|QQ|手机|电话|联系方式)[:：]?\s*[A-Za-z0-9_-]{4,}/g,
    '$1[已隐藏]');
  return result.length > 80 ? `${result.substring(0, 80)}…` : result;
}

私密核验特征只在认领审核环节由当前设备的模拟发布者使用，不应进入 Agent 输入。脱敏不应该依赖模型“自觉忽略”，而要在普通 ArkTS 代码中先完成。

八、五个证明层级必须分开记录

AI 平台交付至少要区分：

层级	能证明什么	不能证明什么
Contract	类型、参数和调用契约正确	设备真实支持
Build	HAP/APP 构建成功	Agent 已发布
Runtime	页面和适配器能运行	云端能返回结果
Capability	支持检测、组件拉起成功	审核长期稳定
Platform	Agent 上架、应用关联生效	每次业务回答都正确

“已提交审核”不等于“已上架”，“编译通过”不等于“真机对话成功”，“页面出现 AI 卡片”也不等于真实 FunctionComponent 已工作。

九、真实项目如何处理外部阻塞

本项目的工程记录把 Agent 审核、应用关联、AGC 发布和真机可见回复分别追踪。写作时仍未取得“Agent 已发布 + 支持检测通过 + 真实组件拉起 + 可见回复”的完整证据，因此本文只讨论架构策略，不宣称小艺端到端已经打通。

平台状态可能变化，正式验收时应重新回读控制台并重启应用，避免缓存导致假阴性。只有当前证据链全部成立，才能更新为端到端通过。

十、发布与维护的直接收益

双版本策略带来四个工程收益：

• 核心应用可以独立测试、构建和演示；
• Agent 审核失败不会迫使业务层回滚；
• 问题定位能区分代码、设备、账号、签名和平台；
• V1.1 只需替换能力门禁和 Adapter，不改认领状态机。

对用户而言，最重要的收益是失败可解释：AI 不可用时仍能继续找物品，而不是面对一个没有下一步的错误页。

十一、什么时候不能采用这种拆分

如果产品核心价值就是云端生成结果，例如没有模型就无法完成的专业分析，那么 AI 无法简单降级为可选增强。此时必须为离线规则、人工兜底、请求队列和服务级别目标设计另一套产品策略。

“寻迹校园”适合拆分，是因为匹配召回和认领闭环可以由确定性业务规则完成，Agent 主要提升解释效率和交互体验。

十二、验收清单

发布前至少检查：

1. 关闭或禁用 Agent 后，发布—匹配—认领—结案仍可完成；
2. 无候选、无网络和不支持设备都有明确提示；
3. Agent 输入不包含私密核验特征和直接联系方式；
4. Agent 回答不会自动改变业务状态；
5. 支持检测与真实组件拉起分别留证；
6. 平台审核、应用关联和 AGC 状态分别记录；
7. 任何未运行项明确标记为 not run，不使用模糊完成表述。

十三、用阶段门禁管理“代码完成”和“能力可用”

为了避免交付口径漂移，可以把每个阶段写成可判定的门禁，而不是一句“AI 功能差不多好了”：

阶段	进入条件	退出证据	失败时用户仍可做什么
本地契约	Adapter 输入输出类型明确	类型检查与受限快照用例	使用本地候选
工程构建	依赖、签名和 API 版本满足	实际构建结果	使用本地候选
真机能力	设备和账号环境就绪	支持检测与组件拉起证据	查看匹配理由
平台发布	Agent 审核、关联生效	控制台状态与设备复测	完成原生认领流程
业务验收	可见回复且不越权改状态	端到端场景记录	始终保留确定性闭环

门禁的价值在于阻止“向上偷换概念”：Contract 通过不能跳过 Build，Build 通过不能替代 Platform，平台页面显示已提交也不能替代真机可见回复。每一层失败时，产品都清楚应该展示哪条降级路径。

十四、版本变更时的影响分析与回滚边界

V1.1 接入或替换 Agent 时，真正需要评估的是边界变化，而不只是提示词变化：

• 输入字段是否新增，是否意外包含私密特征；
• 候选数量和文本长度是否仍受限制；
• 能力检测失败是否会阻塞原生页面；
• Adapter 返回错误是否被映射为可理解提示；
• Agent 输出是否仍然只能提供建议，不能直接写 Repository；
• 平台下线、审核撤回或网络异常时是否能立即退回 V1.0。

回滚策略也因此很清晰：关闭或绕过 Agent 入口，保留 ReportService 的候选召回和原生匹配页面。不要通过回滚业务数据库、删除认领状态或修改核心路由来处理平台故障。

对维护者来说，平台状态属于外部事实，必须按验收时点重新核验；对用户来说，失败提示必须说明“当前增强能力不可用，但本地匹配仍可继续”。这种可观察、可降级、可回滚的边界，比把所有错误统一显示为“请求失败”更有交付价值。

十五、本文小结

V1.0 核心应用 + V1.1 小艺增强不是简单排期，而是风险隔离。确定性业务闭环拥有数据和状态权威，Agent 只消费脱敏候选并增强解释；平台不可用时，原生路径继续服务用户。

下一篇将回到发布功能，拆解为什么自由文本不利于搜索和核验，以及三步结构化 ArkUI 表单如何降低校园失物描述成本。

系列导航：第 8 篇 / 共 50 篇。上一篇：《用 dataRevision 实现跨页面刷新》；下一篇：《三步结构化发布表单》。