ezviz-open-capture（ezviz 打开捕获）

Phone Detection Alert (玩手机检测告警)

萤石开放平台 AI 算法 + 语音告警，检测到玩手机自动播放提醒。

快速开始

安装依赖

pip install requests edge-tts

设置环境变量（必需）

必需的环境变量:

export EZVIZ_APP_KEY="your_app_key"
export EZVIZ_APP_SECRET="your_app_secret"
export EZVIZ_DEVICE_SERIAL="dev1,dev2,dev3"

可选的环境变量:

export EZVIZ_CHANNEL_NO="1"  # 通道号，默认 1

⚠️ 重要:

• EZVIZ_APP_KEY, EZVIZ_APP_SECRET, EZVIZ_DEVICE_SERIAL 是必需的环境变量
• 技能运行前必须设置这些环境变量
• 不需要设置 EZVIZ_ACCESS_TOKEN！技能会自动用 appKey + appSecret 获取 Token（有效期 7 天，内存缓存）

运行：

python3 {baseDir}/scripts/phone_detection_alert.py

命令行参数：

# 单个设备
python3 {baseDir}/scripts/phone_detection_alert.py appKey appSecret dev1 1

# 多个设备（逗号分隔）
python3 {baseDir}/scripts/phone_detection_alert.py appKey appSecret "dev1,dev2,dev3" 1

# 指定通道号
python3 {baseDir}/scripts/phone_detection_alert.py appKey appSecret "dev1:1,dev2:2" 1

# 测试模式（跳过检测，直接播放告警）
python3 {baseDir}/scripts/phone_detection_alert.py appKey appSecret "dev1,dev2" 1 --test

工作流程

1. 获取 Token (appKey + appSecret → accessToken, 有效期 7 天)
       ↓
2. 设备抓图 (accessToken + deviceSerial → picUrl, 有效期 2 小时)
       ↓
3. AI 分析 (accessToken + picUrl → 是否玩手机)
       ↓ [检测到]
4. TTS 语音 ("检测到有人玩手机" → audio.mp3)
       ↓
5. 上传语音 (accessToken + audio.mp3 → fileUrl)
       ↓
6. 下发播放 (accessToken + deviceSerial + fileUrl → 设备播放)

Token 自动获取说明

你不需要手动获取或配置 EZVIZ_ACCESS_TOKEN！

技能会自动处理 Token 的获取和缓存：

首次运行:
  appKey + appSecret → 调用萤石 API → 获取 accessToken
  ↓
  缓存到内存（有效期 7 天）
  ↓
后续运行 (7 天内):
  使用缓存的 accessToken（无需重复获取）
  ↓
7 天后:
  自动重新获取新的 accessToken

Token 管理特性:

• ✅ 自动获取: 首次运行时自动调用萤石 API 获取
• ✅ 自动缓存: Token 保存在内存中，7 天内重复使用
• ✅ 自动刷新: Token 过期后自动重新获取
• ✅ 无需配置: 不需要手动设置 EZVIZ_ACCESS_TOKEN 环境变量
• ✅ 安全: Token 不写入日志，不保存到磁盘

为什么这样设计:

• 萤石 Token 有效期为 7 天，无需每次获取
• 自动管理减少用户配置负担
• 避免 Token 泄露风险（不暴露在环境变量中）

输出示例

============================================================
Phone Detection Alert System
============================================================
[INFO] Detected 2 device(s): [('dev1', 1), ('dev2', 1)]
[SUCCESS] Token obtained, expires: 2026-03-20 15:00:00

[Device] dev1 (Channel: 1)
[SUCCESS] Image captured: https://opencapture.ys7.com/...
[ALERT] Phone usage detected! (confidence: 0.95)
[SUCCESS] Voice uploaded: http://custom-voice-reminder-hn...
[SUCCESS] Alert sent to device dev1!

[Device] dev2 (Channel: 1)
[SUCCESS] Image captured: https://opencapture.ys7.com/...
[INFO] No phone usage detected

============================================================
DETECTION SUMMARY
============================================================
  Total devices:     2
  Phone detected:    1
  Not detected:      1
  Failed:            0
  Alerts sent:       1
============================================================

API 接口

网络端点

格式代码

检测返回:

• images: null - 图片中没有人
• label: "play_phone" - 检测到玩手机行为
• labelWeight: 0.95 - 置信度 95%

错误码:

• 200 - 操作成功
• 10002 - accessToken 过期
• 10028 - 抓图次数超限
• 20007 - 设备不在线
• 20008 - 设备响应超时

Tips

• 多设备: 逗号分隔 dev1,dev2,dev3
• 指定通道: 冒号分隔 dev1:1,dev2:2
• Token 有效期: 7 天，自动缓存
• 图片有效期: 2 小时
• 频率限制: 建议间隔 ≥4 秒
• 定时任务: 建议 ≥5 分钟

注意事项

⚠️ 频率限制: 萤石抓图接口建议间隔 4 秒以上，频繁调用可能触发限流（错误码 10028）

⚠️ 隐私合规: 使用摄像头监控可能涉及隐私问题，确保符合当地法律法规

⚠️ 设备要求: 设备必须在线且支持语音对讲功能（support_talk=1 或 3）

⚠️ Token 安全: Token 仅在内存中使用，不写入日志，不发送到非萤石端点

数据流出说明

⚠️ 重要：本技能会向以下第三方服务发送数据

数据流出详细说明:

1. 萤石开放平台 (open.ys7.com, aidialoggw.ys7.com):

- 发送：摄像头抓拍图片、appKey/appSecret、设备序列号 - 用途：Token 获取、AI 玩手机行为分析、设备控制 - 隐私：🔴 包含监控画面和凭据

1. Microsoft Azure TTS (edge-tts.microsoft.com):

- 发送：TTS 文本（"检测到有人玩手机，请立即停止使用手机！"） - 用途：生成语音文件 - 隐私：🟢 仅固定文本，不包含个人信息

1. 阿里云 OSS (aliyuncs.com):

- 发送：生成的语音文件（.mp3） - 用途：临时存储，供萤石设备下载播放 - 隐私：🟡 临时存储 2 小时，自动过期 - 存储位置：萤石合作的阿里云 OSS 存储桶

数据不流出:

• ❌ 不会发送数据到技能作者或任何个人
• ❌ 不会发送到 ClawHub 或 OpenClaw
• ❌ 不会永久存储任何数据

凭证安全建议:

• 使用最小权限的 appKey/appSecret（仅需设备控制和 AI 分析权限）
• 定期轮换凭据
• 不要使用主账号凭据
• 限制凭据的 IP 访问范围（如果萤石支持）

凭证权限建议:

• 使用最小权限的 appKey/appSecret
• 仅开通必要的 API 权限（设备抓图、AI 分析、语音）
• 定期轮换凭证
• 不要使用主账号凭证

本地处理:

• ✅ Token 缓存于内存，不写入磁盘
• ✅ 不记录完整 API 响应
• ✅ 不保存抓拍图片到本地（除非手动指定下载路径）