【HarmonyOS 7新能力｜003】Core Vision Kit入门实战：从能力边界到最小可运行链路
HarmonyOS 7 将 Core Vision Kit 带入开发者的新能力视野后，很多应用都能想到视觉场景：票据识别、物体分类、图片理解、缺陷辅助检查或相册内容整理。但视觉功能最容易出现一种假完成：示例图片识别成功，就被描述成“能力已经接入”。真实工程还需要回答输入格式、图片方向、并发任务、低置信度、资源释放、权限和隐私等问题。
本文设计一条最小视觉链路：用户选择一张图片，应用完成输入检查与方向归一，调用视觉适配器，再把候选结果过滤成页面可以解释的数据。文中的类型和方法都是应用侧建议结构，不代表华为官方接口；具体 API、设备范围和开放条件必须以开发者账号当前可见的 HarmonyOS 7 / API 26 文档为准。
一、先确认场景是否真的需要视觉能力
视觉模型不是普通字符串工具。它会增加图片解码、内存占用、推理等待、结果不确定性以及隐私责任。接入前应先判断业务是否确实需要理解图像，还是使用文件元数据、二维码、固定模板或用户手工选择就能完成。
以“识别相册中的植物”为例，产品目标不能只写成“返回植物名称”。至少需要明确：支持相册还是相机；是否允许多张图；结果是单标签还是候选列表；低置信度时提示重拍还是人工选择；原图是否离开设备；是否保存缩略图；用户退出页面后是否取消任务。
只有这些条件明确，视觉结果才有业务意义。否则识别模型即使返回内容，页面也不知道该展示什么、何时允许用户确认，以及失败后怎样恢复。
二、输入契约必须比“传一张图片”更具体
建议在进入平台适配层之前，把输入转换成明确的应用契约：
interface VisionInput { requestId: string uri: string source: 'gallery' | 'camera' width: number height: number orientation: number mimeType: string } interface VisionCandidate { label: string confidence: number } interface VisionOutput { requestId: string candidates: VisionCandidate[] elapsedMs?: number }这里的elapsedMs只能在真实计时后填写，不能为了文章完整随便给出性能数字。uri也不应直接写入日志；调试时可记录来源、宽高、格式和请求标识，但不要暴露用户文件路径或图片内容。
输入校验至少覆盖空 URI、异常尺寸、不支持的 MIME 类型、超大图片和方向信息。图片能被系统相册预览，不代表视觉运行环境一定能直接处理。
三、最小链路应有六个可观察阶段
一条稳定链路可以拆成：获取图像、检查格式、方向归一、视觉推理、结果过滤、页面反馈。每个阶段都应能映射到状态和错误，而不是全部塞进一个异步方法。
type VisionRunState = | 'idle' | 'preparing' | 'running' | 'filtering' | 'success' | 'empty' | 'failed' | 'cancelled' | 'timeout'状态明确后，页面才能正确禁用重复按钮、展示进度、响应取消，并阻止旧任务结果覆盖新任务。empty与failed必须区分：前者表示调用完成但没有满足阈值的候选，后者表示链路没有正常完成。
四、方向归一是视觉功能的高频坑
相机和相册图片可能通过元数据表达旋转方向，像素矩阵本身并不一定已经转正。如果页面预览组件自动处理了方向，而送入推理的缓冲区没有处理，同一张图就会出现“人眼看着正常，模型输入却横着”的问题。
建议将方向归一放在统一预处理服务中，并保留原始宽高、目标宽高和旋转信息用于诊断。不要在页面、相机回调和视觉适配器中各写一套旋转逻辑。预处理完成后再进入推理，输出坐标如需映射回原图，也必须使用同一份变换参数。
interface NormalizedImage { requestId: string pixelWidth: number pixelHeight: number rotationApplied: number payload: Object }payload在真实项目中应替换为 SDK 要求的具体类型。这里使用占位类型，是为了避免把未经核实的类名写成官方 API。
五、使用四层架构隔离平台变化
页面层负责选图、拍摄入口和结果展示；编排层负责状态机、超时、取消和去重；视觉服务层负责预处理、推理和结果过滤；平台适配层封装 Core Vision Kit、权限与资源释放。
建议依赖方向始终向下。页面不直接持有平台会话或模型对象，服务层不依赖页面组件，平台适配器不决定业务阈值。这样当 SDK 接口、支持格式或初始化方式调整时，修改集中在适配层；业务规则仍能用假实现测试。
features/vision/ model/VisionContract.ets orchestration/VisionOrchestrator.ets service/ImagePreprocessor.ets service/ResultPolicy.ets adapter/CoreVisionAdapter.ets test/VisionOrchestrator.test.ets六、置信度不能直接当成真相
视觉结果通常带有不确定性。应用不能看到最高候选就宣布识别正确，也不能把一个固定阈值套在所有场景。阈值应根据业务风险、数据和验证结果确定。
低风险的相册整理可以展示多个候选让用户选择；涉及健康、金融、安全或设备控制时，视觉结果只能作为辅助信息，并增加人工确认或其他证据。文章示例可以展示策略结构，但不能杜撰“准确率达到多少”。
class ResultPolicy { filter(items: VisionCandidate[], threshold: number): VisionCandidate[] { return items .filter((item) => Number.isFinite(item.confidence)) .filter((item) => item.confidence >= threshold) .sort((a, b) => b.confidence - a.confidence) .slice(0, 3) } }阈值来源必须可追溯。没有真实数据集和测试记录时，只能把数值标记为待配置，不能包装成平台推荐值。
七、编排层处理超时、取消和迟到结果
用户连续选择图片会产生多个任务。最简单的防错方法是为每次运行生成requestId，页面只接受当前请求的结果。旧任务即使晚到，也不能覆盖新图的状态。
class VisionOrchestrator { private activeRequestId: string = '' begin(requestId: string): void { this.activeRequestId = requestId } isCurrent(requestId: string): boolean { return this.activeRequestId === requestId } cancel(): void { this.activeRequestId = '' } }真实取消还需要调用平台支持的释放或中止能力；如果底层不能立即停止，仍应在应用层丢弃迟到结果。超时也不能只弹提示，必须恢复按钮状态并释放本次任务占用的图片、缓冲区和会话引用。
八、资源生命周期必须有唯一负责人
视觉链路可能持有较大的图片数据或平台对象。如果页面离开后仍保留引用，容易造成内存压力；如果多个层都尝试释放，又可能产生重复调用。建议由平台适配器拥有底层资源，由编排层决定何时结束任务，页面只触发生命周期事件。
需要检查的时点包括：初始化失败、图片解码失败、推理完成、用户取消、页面退出、应用进入后台以及下一次任务开始。所有路径都应进入统一清理函数，清理失败记录结构化错误，但不得输出敏感路径或原图内容。
九、权限与隐私要和真实行为一致
使用相机时，仅在用户主动进入拍摄流程时请求必要权限；用户拒绝后提供清晰说明和可返回路径。使用系统选择器访问单张图片时，不应为了方便扩大到不必要的全量文件权限。具体权限名称和选择器用法要以当前官方文档核实。
如果产品主张端侧处理，就应验证原图是否真的没有上传，检查网络依赖、分析 SDK、日志和异常上报。隐私政策、应用说明和代码行为必须一致。端侧能力不等于应用自动合规，图片缓存、缩略图和识别结果仍需要明确保存与删除规则。
十、用失败场景完成验收
最小验收清单至少包括：正常图片得到候选；不支持格式被提前拒绝；横竖方向一致；超大图片不会导致页面无响应；低置信度进入人工确认；连续选图只展示最后一次结果；取消后不再显示成功；页面退出释放资源；权限拒绝可以恢复；适配器异常转换为用户可理解的信息。
测试应分三层。纯规则用单元测试；图片预处理和适配器用集成测试；相册、相机、前后台切换和内存表现用真机测试。没有执行的测试必须标为“未运行”，不能写成通过。
总结
Core Vision Kit 的接入重点不是让一张示例图得到结果，而是建立可控制的输入、方向归一、任务状态、结果策略、资源生命周期和隐私边界。采用页面层、编排层、视觉服务层与平台适配层后，平台变化被隔离，业务判断也更容易验证。
本文只完成建议架构和静态示例，不代表完成真机推理、性能测试、精度验证或上架审核。正式实现前，应结合 HarmonyOS 7 / API 26 的官方文档、API 变更清单以及账号开放权限核实具体接口。
参考资料
- HarmonyOS 7 开发者能力
- HarmonyOS 7 API 26 新能力说明
- HarmonyOS 升级适配说明
- HarmonyOS API 变更清单
