【听见课堂 HarmonyOS NEXT 实战系列 07】“能运行”不等于“能力完成”：AI 功能真实性五级法

HarmonyOS NEXT 项目接入语音、OCR、人体骨骼或端侧模型后，最容易出现的表述问题是：一次构建成功，就写成“AI 已完成”；打开了系统相机，就写成“OCR 已验证”；合成序列跑出标签，就写成“模型准确率达标”。

这些说法混淆了完全不同的证据层级。听见课堂把能力状态拆成 规划、模拟、契约接口、已集成、运行证明 五级，并且允许同一能力的不同子环节处在不同等级。本文用实时字幕、OCR、人体骨骼、手部关键点和手语分类做一张可审计的真实性地图。

一、先定义五个层级

等级	含义	可以接受的证据	不能据此宣称
L1 规划 Planned	需求或设计里准备做	PRD、设计稿、任务清单	已开发、已接入
L2 模拟 Simulated	固定数据或合成输入可演示流程	明确模拟标识、确定性夹具、隔离证明	真实识别、真实准确率
L3 契约接口 Contract-only	Provider/Adapter 类型与失败路径存在	接口、单测、unavailable/unknown 降级	Kit 或模型已接通
L4 已集成 Integrated	真实 Kit/模型调用已接线	import、资源/配置、调用链、构建产物	真实设备已有有效结果
L5 运行证明 Runtime-proven	目标设备用真实输入得到预期结果	输入条件、截图/UI 树、当前 PID 日志、结果回读	所有设备、所有场景都通过

五级不是营销成熟度，而是证据成熟度。L5 也不是“永远完成”：一次真实字幕只能证明当时的设备、语言、权限和网络条件下产生过结果，不能自动推出长课堂性能、拒识率或所有机型兼容。

二、构建成功为什么只能证明“可构建”

当 ArkTS 类型检查和 assembleHap 通过时，我们至少知道：

• import 与公开类型在当前 SDK 下可解析；
• 调用代码能进入编译和打包；
• 必需模块能够组成当前产物。

但构建不会自动替你验证：

• 目标设备是否提供该能力；
• 权限是否被授予；
• 相机 profile 与预览 surface 是否匹配；
• 模型资产是否能加载；
• 真实输入是否产生非空结果；
• 资源是否在前后台、取消和异常后正确释放。

因此，BUILD SUCCESSFUL 可以支持 L4 的一部分证据，却不能独自把能力提升到 L5。

三、实时字幕：会话跑通与识别出文字要分开

听见课堂的实时字幕已经接入 Core Speech Kit、AudioCapturer、运行时麦克风权限、暂停/继续和结束保存流程。模拟器上也验证了授权、引擎与采集启动、暂停、继续和结束。

但项目记录同时写明：模拟器没有产生新的语音识别文本。因此更准确的拆分是：

子能力	当前等级	证据边界
权限、引擎和采集会话	L4，部分流程有运行证据	真实 API 已接线，设备上会话状态发生变化
新字幕文本输出	L4	真实识别调用已集成，但目标输入没有得到新文字
新字幕写入数据库并重启回读	待 L5	必须用真实说话输入产生新段落后再验证

“识别会话已启动”和“识别出了正确文字”不是同一句话。安全表述应写成：已完成实时听写适配层与会话生命周期接入；真实语音文本结果仍待具备有效输入的目标设备验证。

四、OCR：打开图库不等于 OCR 成功

扫描链路包含多个独立环节：

CameraPicker / PhotoViewPicker
  -> 返回非空 URI
  -> Image Kit 解码 PixelMap
  -> Core Vision OCR
  -> 用户校对
  -> 保存复核文字与来源

项目已通过系统图库拉起与取消、本地示例到复核保存的流程；ScanCaptureService 也已真实调用 Image Kit 和 Core Vision OCR。不过当时的模拟器没有可选真实图片，系统相机也不可用，所以真实图片的 OCR 文本结果仍是 not run。

因此，当前可以写“CameraPicker、PhotoViewPicker、Image Kit 与 Core Vision OCR 已集成并可构建”，不能写“真实板书识别已通过”。真实 OCR 的 L5 至少需要保存以下证据：测试图片、返回 URI、识别结果、人工修正、保存后回读，以及图片资源释放和数据库不落临时 URI 的检查。

五、人体骨骼：L5 也要写清输入和覆盖范围

听见课堂的手语 S02 链路使用真实 Camera Kit 预览、六帧 JPEG 内存采样与 Core Vision 17 点人体骨骼检测。BLK-AL80 上先验证了无人物时 6/6 帧完成推理并返回 no_person；随后又补了人物入镜正向路径：

• 6/6 帧 persons=1；
• 每帧 validPoints=13；
• 双肩、双肘、双腕 upperBody=6；
• 序列 poseReady=6、upperBodyAvg=100%、quality=ready。

这可以支持“人体骨骼采样与肩肘腕质量门禁在指定真机、指定构图下有运行证明”。但它仍不能推出：

• 手指关键点已经存在；
• 手语词义已经被识别；
• 不同衣着、距离、光照都稳定；
• 六帧测试等于长时间性能通过。

L5 的正确写法始终带输入条件、设备和结果范围，而不是只写一句“骨骼识别已完成”。

六、手部关键点：安全的 unavailable 比伪造结果更有价值

项目已经定义每手 21 点的 SignHandLandmarkProvider 契约，并区分三种模式：

export enum SignHandProviderMode {
  UNAVAILABLE = 'unavailable',
  REAL_MODEL = 'real_model',
  SYNTHETIC_TEST = 'synthetic_test'
}

当前默认实现是 UnavailableSignHandLandmarkProvider。没有真实手部模型时，它返回 unavailable，不会从人体腕点推导或伪造 21 个手指点。真机六帧结果也保持 hands=0。

这项能力处于 L3：接口、模式、资源释放和失败语义已经建立，但真实模型尚未接入。L3 不是失败，而是一条重要的安全边界。对于 AI 项目，能稳定返回“不具备能力”，通常比为了演示制造一个看似合理的结果更可信。

七、合成 24 帧只证明稳定器，不证明模型准确率

为了验证时序逻辑，项目提供了纯内存 24 帧双手夹具：每帧 2 手、每手 21 点，并覆盖连续 3 个一致窗口、1000ms 重复抑制、unknown 重置和标签切换重置。

这些测试能够证明：

• 窗口状态机按预期工作；
• 重复结果不会在短时间内反复发布；
• 低置信度或 unknown 会清空连续窗口；
• 合成输入没有进入 ArkUI 候选和正式历史。

它们不能证明：

• 摄像头能检测出真实手指点；
• 时序模型能分辨真实动作；
• 五类动作在真实用户中具有某个准确率；
• 真实推理满足时延、内存、功耗和温升要求。

合成夹具属于 L2；真实手部 Provider 和分类器当前分别保持 unavailable 与 unknown。即使合成测试 100% 通过，也不能把这个百分比写成“模型准确率 100%”。

八、规则分不是模型置信度

项目还基于真实肩、肘、腕快照实现了本机肢体规则解析，支持举手、双手举起、指向左/右、双手暂停姿态代理、自然站立与 unknown。规则采用肩宽归一化、至少 60% 六帧一致和最低 65 分门禁。

这里的“65 分”表示规则匹配程度，不是机器学习概率，更不是经过数据集统计的准确率。尤其是“双手暂停”只能证明腕部和肘部满足某种姿态代理，不能证明掌心方向或真实手语语义。

一项可信的对外说明应把三种数值分开：

数值	含义	所需证据
规则分	几何规则匹配程度	规则定义、阈值、边界样本
模型置信度	模型对单次输出的内部评分	真实模型、输入输出、校准说明
准确率/召回率	数据集上的统计指标	数据集划分、标注质量、评测脚本和混淆矩阵

没有评测集与统计过程时，不应出现“准确率 95%”一类数字。

九、当前能力真实性矩阵

下面是按项目现有证据得到的保守结论：

能力	当前可确认等级	已有证据	仍缺证据
实时字幕	L4 已集成	权限、Speech/Audio 调用、会话生命周期、构建与设备状态	真实语音产生新文本、入库与重启回读
Core Vision OCR	L4 已集成	Picker、Image Kit、OCR 调用、构建、取消和降级	真实图片成功文本、空结果与资源压力
人体骨骼	L5 有限运行证明	BLK-AL80 六帧无人物和人物正向骨骼结果	多姿态、多光照、长时与跨设备覆盖
21 点手部关键点	L3 契约接口	Provider、模式、unavailable 和释放路径	真实模型、真实双手关键点
五类手语分类	L2/L3	模拟候选、分类器契约、unknown 拒识、合成稳定器	真实时序模型、数据集、真实分类和评测
本地肢体规则	L4，有限运行降级	真实骨骼接线、规则契约、真机无人物 unknown	真人六类逐项识别与阈值校准

同一行也可能继续拆分。例如人体骨骼的“无人物降级”和“人物正向点位”已有运行证明，但基于骨骼的六类规则动作还没有逐类真人验收。

十、README、比赛材料和博客怎样安全表述

README 模板

Core Vision 人体骨骼已在 BLK-AL80 上完成六帧真实推理，
覆盖无人物降级与人物上半身点位质量门禁。
21 点手部关键点与真实手语时序模型尚未接入，
当前运行结果保持 unavailable/unknown。

比赛材料模板

当前演示包含真实相机与人体骨骼能力，以及明确标注的本地模拟候选。
模拟候选仅用于展示“识别—确认—记录”的交互闭环，
不作为真实手语模型准确率证明。

技术博客模板

24 帧合成夹具验证了结果稳定器、重复抑制和 unknown 重置；
它没有连接用户候选，也不能替代真实模型、真实数据集和真机评测。

还可以统一采用“已实现什么 + 在哪里验证 + 未验证什么”的三段式：

已实现：真实 Kit 调用与安全降级。
已验证：指定设备、指定输入下的运行结果。
未验证：跨设备、长时、准确率或发布级指标。

十一、把真实性分级纳入交付流程

每次交付可以维护一张能力真值表，字段至少包含：

• 能力名称与子环节；
• 当前等级；
• 当前 Provider 模式；
• 使用的真实或合成输入；
• 实际结果与错误码；
• 截图、UI 树、日志和报告路径；
• 未验证项与下一步最小动作。

升级等级时只看新增证据：

规划文档
  -> 明确模拟并隔离
  -> 建立 Provider/Adapter 契约
  -> 接入真实 Kit/模型并构建
  -> 目标设备使用真实输入产生结果

任何一步失败都应停在对应层级。尤其不能从“契约测试 passed”越级到“真实模型已完成”，也不能从“相机预览可见”越级到“OCR/手语识别已通过”。

总结

AI 功能的可信度不取决于页面有多完整，而取决于每个结论能否回到对应证据。听见课堂用五级法把规划、模拟、契约、集成和运行证明分开，也把真实字幕、OCR、骨骼、手部关键点、分类模型和本地规则分别标记。

这套方法的核心不是保守措辞，而是让团队知道下一步缺的究竟是代码、模型、设备、输入、评测还是长期稳定性。下一篇将进入人机协同闭环，讨论为什么 AI 生成的课堂任务必须先成为候选，经过编辑、拒绝和确认后才能进入正式任务中心。