---
name: ezopensdk-harmony-skill
description: 萤石开放平台 EZOpenSDK HarmonyOS 端完整开发知识库。涵盖 SDK 接入配置、设备管理、实时预览/回放、语音对讲、设备配网、视频通话(ERTC)、数据模型、错误码排查共 8 大模块，帮助三方开发者快速规范地接入萤石摄像头/NVR 等设备能力。
---

# EZOpenSDK HarmonyOS Skill

## 触发条件
当用户提到以下关键词时，应激活此 Skill：
- 萤石、EZVIZ、EZOpenSDK、萤石开放平台
- HarmonyOS、鸿蒙、ArkTS、ETS、HAR
- 摄像头、监控、IPC、NVR、DVR
- 预览、直播、回放、录像、取流
- 对讲、全双工、半双工
- 配网、AP配网、网线配网、WiFi配置
- 云台、PTZ、云存储
- 设备列表、设备信息、设备添加、设备删除
- 告警消息、布防、撤防
- 截图、录制、水印、清晰度
- EZPlayer、EZOpenSDK、EZDeviceInfo

## SDK 简介
萤石开放平台 EZOpenSDK（HarmonyOS）是萤石提供的鸿蒙端 SDK，支持对萤石摄像头、NVR 等设备进行预览、回放、对讲、配网等操作。

### 核心类
| 类名 | 说明 |
|------|------|
| `EZOpenSDK` | SDK 主入口类，提供初始化、授权、设备管理、录像查询、配网、云台控制等 API |
| `EZPlayer` | 播放器类，提供预览、回放、对讲、录制、截图、电子放大等功能 |
| `EZDeviceInfo` | 设备信息对象，包含设备属性和能力集 |
| `EZCameraInfo` | 通道信息对象，包含通道号、清晰度、封面等属性 |
| `EzvizSupportKit` | 能力集查询工具类，判断设备是否支持云台、对讲、倍速回放等能力 |

### 接入必读
- 仅支持真机调试，不支持模拟器
- 最低系统版本 HarmonyOS 5.0.0(12)
- 导入方式：将 `EZOpenSDK.har` 复制到 `entry/libs` 目录下
- 所有 async 修饰的 API 调用必须加 await（包括父级链路）
- 国际化资源：en_US、zh_CN

## 功能模块索引

根据用户需求，参考对应的知识文件：

| 用户需求 | 参考文件 | 说明 |
|----------|----------|------|
| SDK 接入、初始化、授权、HAR 导入、权限配置 | `ezopensdk-setup.md` | 从零开始接入 SDK 的全部前置工作 |
| 设备列表、设备信息、设备添加/删除/升级/存储管理 | `ezopensdk-device.md` | 设备管理相关的所有 API |
| 预览、回放、录制、截图、云台、清晰度、电子放大、告警消息 | `ezopensdk-player.md` | EZPlayer 播放器相关的所有功能 |
| 对讲（全双工/半双工）、音量回调 | `ezopensdk-talk.md` | 语音对讲相关功能 |
| 设备配网（AP/网线） | `ezopensdk-wifi.md` | 设备网络配置 API 及流程 |
| 视频通话、ERTC | `ezopensdk-ertc.md` | 视频通话相关功能（鸿蒙暂未支持） |
| 数据模型对象属性（EZAlarmInfo、EZCloudRecordFile 等） | `ezopensdk-models.md` | 所有对外开放对象的属性详解 |
| 错误码查询、常见问题排查 | `ezopensdk-errorcode.md` | 错误码表和 FAQ |

## 使用指引

1. 三方开发者首次接入时，按 `setup → device → player/talk/wifi` 的顺序引导
2. 开发者描述具体功能需求时，直接路由到对应模块的知识文件
3. 开发者需要实现具体页面（设备列表、预览、回放、对讲、配网等）时，基于对应模块的 skill 知识文件 + 用户需求生成代码
4. 开发者遇到错误码或异常时，优先查阅 `ezopensdk-errorcode.md`
5. 所有异步操作（网络请求、设备控制、播放器操作）必须使用 await
6. 国内客户使用 `EZOpenSDK`（默认 apiUrl），海外客户需设置对应区域的 apiUrl
7. 应用发布时必须关闭 SDK 调试模式（`setDebugLogEnable(false)` + `setDebugStreamEnable(false)`）

### HarmonyOS 平台特殊注意事项

1. **async 方法必须 await**：所有标记为 async 的 SDK 方法（initLibWithAppKey、setAccessToken、startRealPlay 等）调用时必须加 await，且调用链路上的父函数也必须标记为 async
2. **播放器视图使用 XComponent**：播放器画面通过 `XComponent`（type: SURFACE）承载，onLoad 回调中获取 surfaceId 后通过 `player.setPlayerView(surfaceId)` 设置
3. **对讲前必须申请麦克风权限**：务必在发起对讲前向系统申请 `ohos.permission.MICROPHONE` 权限，否则第一次对讲异常
4. **非国标设备对讲需关闭预览声音**：对讲成功后关闭 `player` 的声音避免回音，对讲结束后恢复
5. **国标设备对讲不能关闭预览声音**：国标设备 talkPlayer 只负责采集手机端声音，设备端声音通过 player 播放
6. **页面生命周期管理**：`onPageShow` 中开始取流，`onPageHide` 中停止取流，`aboutToDisappear` 中释放播放器
7. **录像下载直接保存为 MP4**：鸿蒙 SDK 下载的录像文件格式为 MP4，无需像 iOS 那样做 PS→MP4 转码
8. **AP 配网需手动连接设备热点**：鸿蒙当前通过 `wifiManager.addCandidateConfig` 连接设备热点，如失败需引导用户去系统设置页手动连接
9. **验证码本地缓存**：使用 `PreferenceUtil` 按设备序列号作为 key 缓存验证码

## 各大区域 ApiUrl

| 区域 | ApiUrl |
|------|--------|
| 国内 | https://open.ys7.com |
| 海外（俄罗斯） | https://irusopen.ezvizru.com |
| 海外（亚洲） | https://isgpopen.ezvizlife.com |
| 海外（北美洲） | https://iusopen.ezvizlife.com |
| 海外（南美洲） | https://isaopen.ezvizlife.com |
| 海外（欧洲） | https://ieuopen.ezvizlife.com |
