Skill 评测与上架|真机能唤醒却难上架:评测集、审核证据和回滚策略 —— HarmonyOS Agent×Skill 实战 09 封面

图 01:AI 生成的技术主题封面。

一、先看故障现象

最后一篇不以“成功弹出一个结果”作为项目完成标准。真实发布流程会暴露出另一批问题:Skill 描述与行为不一致、误触发过多、参数错误没有解释、权限用途说不清,或者升级后旧用户仍调用旧能力。真机能够唤醒,只说明某条路径走通,距离稳定开放还有一整段距离。

二、问题为什么会出现

准备正式发布的第一步是把能力名称、功能描述、输入输出与实际代码逐项对齐。华为 Skill 审核规范明确提到,名称不宜含“最优”“最好”等诱导偏好词,功能说明不得夸大或隐藏底层行为。对于行旅事务助手,我们只承诺提供行前清单、预算核算和可审阅的日程草稿;没有实现实时航班查询、购票或第三方日历写入,就绝不在商店介绍中把它们写成“已经自动完成”。

第二步是把评测集做成可复用资产。至少区分正确触发、错误触发、参数缺失、权限拒绝、重复调用、弱网恢复、恶意输入、设备不支持八类。每类都要包含输入、预期路由、预期错误码、是否允许副作用与最终用户可见状态。不要只统计“AI 回答得像不像人”,还要统计 Skill 激活是否正确、执行是否成功、错误是否可解释、是否有越权或重复执行。尤其在多个相似 Skill 同时存在时,反例的价值往往不低于正例。

第三步是区别自动测试与设备验收。Node.js 测试能证明预算、日期、门禁与计划规则在当前逻辑下符合预期,却无法证明 DevEco Studio 的 HAP 构建、Skill 注册、系统智能体匹配、设备权限或应用市场审核已经通过。对于应用 Skill,应按官方指南将 HAP 导入对应调试流程,再进行真机测试;对于生态 Skill 包,应依据该平台的开发规范及审核流程提交。混用两套交付件会让问题变得难以定位。

发布材料还应记录版本与变更影响。升级 SKILL.md 的 description 可能改变被触发的语义范围,升级脚本参数会破坏旧调用,升级业务规则可能改变用户看到的结果。可以把改动分成声明层、适配层、业务层三种,每次针对受影响的案例回归。版本号使用 SemVer 不只是给运营看的数字,而是帮助定位“哪个版本的声明和代码组合产生了这条结果”。如果发现误唤醒显著增加,应保留上一稳定版本的文件和测试结果,按照实际平台允许的流程回滚或撤回。

隐私与安全材料应和实现一致:是否读取位置、是否上传用户行程、是否保存对话、保存多久、如何删除、是否调用外部模型,都需要有确定答案。用户可见的“已处理”不能替代后台审计;后台日志也不能为了排错就完整记录个人信息。审计最好使用 traceId、skillVersion、routeStatus、duration、errorCode 等必要字段,用白名单输出方式防止意外把姓名或地址打进日志。

回滚不是一句“出问题就重发上一版”。需要知道旧版是否仍被系统索引、数据结构有没有向后兼容、是否已经产生写入副作用、当前审核状态允许怎样调整。若新版参数多了一个必填字段,旧调用可能突然失败;这时要么提供兼容解释和明确错误,要么对版本做隔离,不能让模型自行猜参数填充。对于严重的越权风险,应优先停止相关能力的调用路径并通知相关人员核验,而不是继续等待漂亮的指标。

三、实现取舍和系统边界

这套连载的最终交付不是一个已上架的商业产品,而是一组经过结构化业务测试的示例文件、两种 Skill 结构对照,以及待设备验证的检查项。最值得保留的工程结论有三条:能力声明须与实现一致,任务执行须由代码规则把关,任何具备副作用的动作都应具备用户确认与可追踪记录。这三项不是模型参数调优可以取代的。

“优质主推”应理解为内容与产品质量的努力方向,而不是开发者能够自行保证的审核结果。不要在文章中虚构通过率、平台推荐资格、系统级授权或真机截图。能做的是提供可操作的测试方法、官方文档入口、已核验业务规则及仍需验证的项目清单,把读者带到一个可继续开发和提交评审的起点。

四、关键代码与实现路径

以下代码对应下载包中的 项目源码,业务层代码可使用 Node.js 18+ 运行;涉及 scriptManager 的片段需要集成到 Stage 模型并按目标 SDK 验证。所给例子并不包含任何实际订票、真实支付或自动写入系统日历的实现。

cd 项目源码/核心业务逻辑
node --test
# 测试范围:意图路由、非法日期、金额精度、计划依赖、
# 用户确认、幂等、权限失败、弱网重试和敏感日志字段

这段实现重点在于将“模型或系统提出的意图”与“程序真正允许执行的业务动作”分开:参数先经校验,再交给业务函数,最后用明确状态或错误码回报。不能直接用一句“执行成功”作为真实设备操作的证据。

Skill评测审核与上架 开发环境

图 02:AI 生成的 DevEco Studio 风格开发界面,代码窗口、调试状态与项目名称用于讲解本文排查位置。

五、四类高频踩坑与修复证据

坑 1:真机示例成功,审核材料却说有未实现的能力

表现:真机示例成功,审核材料却说有未实现的能力。

原因:宣传文字覆盖了下单、实时票价或自动日历写入,超出实际源码与权限声明。

处理:用能力矩阵逐条核对名称、描述、数据用途与测试证据,删除未经实现的承诺。

复验:让评审按文档复现每项功能,无法复现的能力不得写成已交付。

坑 2:正向问题通过,用户口语提问却误路由

表现:正向问题通过,用户口语提问却误路由。

原因:评测集只含固定模板,没有同义表达、反例和含糊请求。

处理:增加正反样例、方言口语和不适用场景,并记录激活与错误码。

复验:观察每次版本升级后的误唤醒数和应澄清场景表现。

坑 3:升级 description 后旧版本依然生效

表现:升级 description 后旧版本依然生效。

原因:Skill 声明、HAP 产物与平台索引可能处于不同版本。

处理:维护版本映射与发布记录,检查导入对象和缓存,保留可回退文件。

复验:比对 skillVersion、构建时间和调试返回,确认实际调用的是目标版本。

坑 4:线上排错时日志泄露完整行程

表现:线上排错时日志泄露完整行程。

原因:为了快速定位把原始用户提示、日期、姓名或联系人统一打到日志。

处理:日志改为字段白名单,只保留错误码、耗时、随机 traceId 与版本。

复验:检查日志样本不含私人地址和原始对话,删除流程覆盖缓存与索引。

六、深入复盘:工程上还要补什么

评测不能只展示几张漂亮的对话截图

“用户说一句话,Agent 立刻完成”可以当作产品示例,但绝不是质量证明。对 HarmonyOS Skill,至少还需要展示激活边界、参数缺失、执行失败、用户拒绝、版本升级和设备不支持时的行为。项目应准备一份结构化评测 CSV:每行记录输入、期望 Skill、期望状态、是否允许副作用、实际结果和备注。这样开发者改动 description 后,就能直观看到哪些口语表达的触发率变好、哪些负向场景开始误匹配。

如果可能,把失败案例留在版本库,不要每次“修好了”就删除。比如“我要买机票”被错误路由到行李清单,是一个长期需要回归的负例。某次修改恰好让它不再触发,但下一版扩展了预算功能后,误路由可能重新出现。把边界写成自动测试和人工复测步骤,比单纯追求一次示例的成功更具有可维护性。

审核证据应当有可复核的对象

提交材料可以围绕“功能说明、权限用途、示例截图、参数契约、失败处理、隐私说明”组织,而不是堆放大量营销文案。每张界面图都要与正文对应,不能将生成的示例界面误称为官方后台真实截图。对于未经实际构建和审核的项目,文档中应保留“待验证”与“需按当前平台操作”的标注。平台规则可能更新,因此关键步骤应附官方链接和查看时间,让读者知道何时必须重新核验。

如果项目接入大模型云服务,还要说明数据传输范围、密钥保管方式和外部服务依赖,不能将密钥写进公开源码或手机安装包。即便只是单机清单生成,也应该明确本地数据如何保留、删除和导出。审核人员需要知道代码实际做了什么,而不是接受“AI 会自己处理”这样的模糊解释。

发布后比发布前更需要回滚门禁

发布后真正的风险是新版本扩大了某项能力的触发范围,或者修改了参数后造成旧调用失败。版本管理应记录 Skill 声明版本、App 包版本和业务规则版本,三者未必一致,但必须能追溯。上线前保留上一版配置与测试集;发生越权、重复写入或隐私问题时,立即停止相关路径并按当前平台允许的方式撤回或回滚。不要为了保持表面成功率而继续让有风险的操作运行。

与其追求一个没有失败按钮的“万能 Agent”,不如让产品具备可见的失败、明确的边界和可验证的恢复。只有当能力与实际实现一致、错误能被解释、权限能够收回、用户知道操作状态时,才值得考虑更广泛分发。

七、运行、验证与边界检查

最终验收从离线到系统分四层:第一层跑业务规则测试,覆盖路由、日期、预算、计划、确认、幂等和输入安全;第二层在实际 Stage 模型工程中编译并检查 skillProfiles、入口签名与回包契约;第三层在目标设备与系统智能入口验证触发率、边界语句和权限行为;第四层依真实应用市场要求提交材料并保存审核意见。某层未完成就标明待验证,不能用“准备完毕”冒充已获批。

发布后监测也需要退出机制:每次变更保留测试记录和上一稳定版本,遇到高风险误触发或越权迹象,优先禁用相关动作;发生数据问题,按既定隐私流程处理。项目由此形成从能力设计到质量治理的闭环。九篇的最终价值在于让 Agent/Skill 不只会说、会调工具,还能解释边界、拒绝不合理调用并在失败时安全停止。

Skill评测审核与上架 手机效果

图 03:AI 生成的 HarmonyOS 风格手机操作界面,所有页面数据用于功能说明。

这套内容最终希望形成一种可复用的技术写作方法:每篇从实际易错的调用路径出发,展示失败条件、修复思路、代码边界与验证方法;对未验证的平台行为给出查证入口,而不是以漂亮截图代替事实。这样的文章即使面对新的版本,也能指导读者定位问题,并把差异补进自己的项目验收表。

八、本篇小结与下一篇预告

本篇将具体问题限定在可观察的调用链、可复现的业务规则与明确的拒绝分支中,给出了代码与手动验证顺序。尚未在目标设备上验证的系统行为应继续按当前 SDK 与官方文档核实。系列至此结束;代码仍需放入真实 Stage 模型工程并按最新官方文档完成平台验收。

官方核对资料

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐