back
loading skill details...
设备管理工具，用于管理摄像头、监控等实时设备，支持设备增删改查、实时画面查看、直播流地址获取。当用户提及摄像头、监控、设备管理、查看实时画面、直播流、监控地址等关键词时使用。
---
name: "device-management"
description: "设备管理工具，用于管理摄像头、监控等实时设备，支持设备增删改查、实时画面查看、直播流地址获取。当用户提及摄像头、监控、设备管理、查看实时画面、直播流、监控地址等关键词时使用。"
version: "1.0.0"
---
# 设备管理工具
## 任务目标
- 本 Skill 用于：管理各类智能设备（摄像头、监控、传感器等），提供设备生命周期管理、实时流获取、状态查询、远程控制等功能
- 能力包含：设备增删改查、实时画面查看、直播流地址获取、设备状态监控、设备配置管理、云台远程控制、音频开关控制
- 触发条件：
1. 当用户提及设备管理、摄像头、监控、IPC、NVR等设备相关关键词时
2. 当用户提及以下功能关键词时：**列出所有设备**、**所有摄像头**
、查看实时画面、直播流地址、监控画面、设备列表、查看设备清单、设备信息、摄像头清单、摄像头信息、添加设备、删除设备、修改设备信息
3. 当用户需要查看某个设备的实时监控画面时，自动返回可播放的直播流地址（如m3u8、flv、rtmp格式）
- 重要说明：本技能管理的是云端注册的智能设备（摄像头、监控等），而非手机/宿主操作系统的原生设备，**不会触发任何原生设备管理相关功能
**，所有设备信息均通过云端API获取
- 自动行为：
1. 当用户要求查看实时画面时，自动查询对应设备的直播流地址，并以可直接播放的格式返回
2. 直播流地址支持在对话框中直接播放（如H5播放器、原生播放器支持的格式）
3. 设备信息自动持久化存储，支持跨会话查询
## 前置准备
- 依赖说明：scripts脚本所需的依赖包及版本
```
requests>=2.28.0
pyyaml>=6.0
```
- 安装方式：
```bash
# Debian/Ubuntu系统
sudo apt install -y python3-requests python3-yaml
# 或使用pip安装
pip install requests pyyaml --break-system-packages
```
## 操作步骤
### 🔒 open-id 获取流程控制（强制执行，防止遗漏）
**在执行设备管理操作前，必须按以下优先级顺序获取 open-id：**
```
第 1 步：【最高优先级】检查技能所在目录的配置文件（优先）
路径：skills/smyx_common/scripts/config.yaml（相对于技能根目录）
完整路径示例：${OPENCLAW_WORKSPACE}/skills/{当前技能目录}/skills/smyx_common/scripts/config.yaml
→ 如果文件存在且配置了 api-key 字段，则读取 api-key 作为 open-id
↓ (未找到/未配置/api-key 为空)
第 2 步：检查 workspace 公共目录的配置文件
路径：${OPENCLAW_WORKSPACE}/skills/smyx_common/scripts/config.yaml
→ 如果文件存在且配置了 api-key 字段，则读取 api-key 作为 open-id
↓ (未找到/未配置)
第 3 步：检查用户是否在消息中明确提供了 open-id
↓ (未提供)
第 4 步：❗ 必须暂停执行，明确提示用户提供用户名或手机号作为 open-id
```
**⚠️ 关键约束：**
- **禁止**自行假设,自行推导,自行生成 open-id 值（如 openclaw-control-ui、default、userC113、user123 等）
- **禁止**跳过 open-id 验证直接调用 API
- **必须**在获取到有效 open-id 后才能继续执行分析
- 如果用户拒绝提供 open-id，说明用途（用于保存和查询历史报告记录），并询问是否继续
---
### 📌 第 1 步详解：sessionKey 提取 open-id 方法（钉钉渠道）
**sessionKey 格式解析：**
```
标准格式：agent:<agentId>:<userId>:<channel>:<channelId>
钉钉示例：agent:main:openai-user:dingtalk-connector:__default__:03576226033537657619
└────────────┬────────────┘ └────────┬────────┘
渠道标识 channelId (= chat_id)
```
**提取规则：**
| 渠道类型 | sessionKey 特征 | open-id 提取方法 |
|--------|-------------------------|--------------|
| **钉钉** | 包含 `dingtalk-connector` | 取最后一个冒号后的内容 |
| 其他渠道 | 不包含钉钉标识 | 跳过，继续第 2-6 步 |
**提取代码示例（Python）：**
```python
def extract_openid_from_sessionkey(session_key: str) -> str | None:
"""
从 sessionKey 中提取 open-id（钉钉渠道）
Args:
session_key: 完整 sessionKey，如 "agent:main:openai-user:dingtalk-connector:__default__:03576226033537657619"
Returns:
提取的 chat_id，或 None（非钉钉渠道）
"""
if "dingtalk-connector" not in session_key:
return None # 非钉钉渠道，跳过
# 取最后一个冒号后的内容作为 chat_id
chat_id = session_key.split(":")[-1]
# 验证提取结果（钉钉 chat_id 通常为 19 位数字）
if chat_id and len(chat_id) >= 10:
return chat_id
return None
```
**提取代码示例（Bash）：**
```bash
# 从 sessionKey 提取 chat_id
SESSION_KEY="agent:main:openai-user:dingtalk-connector:__default__:03576226033537657619"
# 检查是否为钉钉渠道
if echo "$SESSION_KEY" | grep -q "dingtalk-connector"; then
# 提取最后一个冒号后的内容
OPEN_ID="${SESSION_KEY##*:}"
echo "提取成功：open-id = $OPEN_ID"
# 输出：提取成功：open-id = 03576226033537657619
else
echo "非钉钉渠道，跳过自动提取"
fi
```
**真实案例验证：**
```
✅ 已验证 sessionKey: agent:main:openai-user:dingtalk-connector:__default__:03576226033537657619
✅ 提取结果：open-id = 03576226033537657619
✅ API 调用成功：设备列表查询正常执行
```
---
**⚠️ 关键约束：**
- **禁止**自行假设,自行推导,自行生成 open-id 值（如 openclaw-control-ui、default、userC113、user123 等）
- **禁止**跳过 open-id 验证直接调用 API
- **必须**在获取到有效 open-id 后才能继续执行分析
- **钉钉渠道会话会自动提取 chat_id，无需询问用户**（已验证可用）
- 如果用户拒绝提供 open-id，说明用途（用于保存和查询历史报告记录），并询问是否继续
---
- 标准流程：
1. **自动触发逻辑**
- 当用户提及「**列出所有设备**」「**所有摄像头**」「查看设备清单」「设备信息」「摄像头清单」「摄像头信息」「设备列表」等关键词时，
**无需询问用户，直接执行
`-m scripts.device_management list --open-id <open-id>`
列出所有设备**
2. **设备管理操作**
- 列出所有设备：调用 `-m scripts.device_management list --open-id <open-id>`
（无需额外配置API地址，脚本内置云端API调用逻辑）
- 添加设备：调用
`-m scripts.device_management add --sn <设备序列号> --name <设备名称> [--type <设备牌子/代码>] [--scode <设备安全码> ] [--scene-code <设备使用场景/场景码> ] [--username <WIFI用户名>] [--password <WIFI密码>] --open-id <open-id>`
- 删除设备：调用
`-m scripts.device_management delete --sn <设备序列号> --open-id <open-id>`
- 修改设备：调用
`-m scripts.device_management update --id <设备ID> --name <新名称> [--ip <新IP>] [其他参数] --open-id <open-id>`
- 查询设备详情：调用
`-m scripts.device_management get --sn <设备序列号> --open-id <open-id>`
3. **实时画面查看**
- 获取直播流地址：调用 `-m scripts.device_management stream --id <设备ID> [--protocol <m3u8/flv/rtmp>]`
- 默认返回m3u8格式的直播流地址，可直接在支持HLS的播放器中播放
- 输出格式：提供可直接点击播放的链接，以及嵌入式播放代码（如需）
4. **设备远程控制**
- 云台转动控制：调用
`-m scripts.device_management control --sn <设备序列号> --direction <up|down|left|right|reset> [--speed <1-10>] --open-id <open-id>`
- `--direction`：指定方向，可选值 `up`/`down`/`left`/`right`/`reset`
- `--speed`：转动速度，范围 1-10，默认 1，速度越大转动幅度越大
- 声音开关控制：调用
`-m scripts.device_management control --sn <设备序列号> --sound <on|off> --open-id <open-id>`
- `--sound`：开启声音侦听 可选值 `on`/`off`
5. **结果返回规范**
- 设备列表表格展示：使用Markdown表格格式，包含ID、名称、类型、IP地址、状态、操作列, **不对URL中的特殊字符做任何转义处理
**，保证链接原始可用性
- 直播流地址生成规则：仅显示 HLS(m3u8) 格式，HLS(m3u8)格式流地址按照以下模板生成，仅需要替换最后的设备ID部分：
```
http://cmgw-vpc.lechange.com:8888/LCO/BJ10AF5PHAD32E9/0/1/20260129T141842/openhzdc2a6020d5714149b7b5b581634a1b28.m3u8?source=open&id={deviceId}
```
其中：
- 仅 `{deviceId}` 部分需要替换为设备的 `id` 字段值，其他部分固定不变
- 直播流地址输出：明确标注流格式，提供直接播放链接，如 `[▶️ 查看实时画面](streamUrl)`
- **禁止显示 FLV、RTMP 等其他格式**，仅输出 HLS(m3u8) 格式
- 设备列表中的操作列：直接填入生成好的HLS(m3u8)流地址，用户点击即可直接跳转播放
- 错误处理：明确提示设备离线、地址无效等异常情况
## 资源索引
- 必要脚本:见 [-m scripts.device_management](-m scripts.device_management)(
用途：设备增删改查、直播流地址获取、设备状态管理)
- 领域参考:见 [references/api_doc.md](references/api_doc.md)(何时读取：需要了解设备API接口规范、流媒体协议详情时)
- 播放模板:见 [assets/player_template.html](assets/player_template.html)(用途：提供网页播放模板，用于嵌入直播流)
## 注意事项
- 无需额外配置API地址，`device_management.py list` 脚本已内置云端API调用逻辑，直接运行即可获取设备列表
- 设备密码等敏感信息加密存储，不在日志和输出中明文显示
- 直播流地址有效期通常为1-24小时，过期后需要重新获取
- 仅在用户明确要求时提供公网可访问的流地址，默认返回局域网地址
- 实时画面查看功能需要设备在线且网络可达
- 分析结果仅供参考，不能替代专业安防系统
## 使用示例
```bash
# 列出所有设备
python -m scripts.device_management list --open-id openclaw-control-ui
# 添加大华摄像头设备
python -m scripts.device_management add --sn BJ10AF5PHAD32E9 --name "大门口摄像头" --type "大华" --scode "L21E3BE0" --open-id openclaw-control-ui
# 添加探鸽摄像头设备
python -m scripts.device_management add --sn AJ237DRHX678 --name "客厅摄像头" --type "探鸽" --scene-code "风险监测" --open-id openclaw-control-ui
# 获取设备1的m3u8直播流地址
python -m scripts.device_management stream --id 1 --protocol m3u8 --open-id openclaw-control-ui
# 删除ID为2的设备
python -m scripts.device_management delete --id 2 --open-id openclaw-control-ui
# 删除序列号为BF05CF0PHA7DF14的设备
python -m scripts.device_management delete --sn BJ10AF5PHAD32E9 --open-id openclaw-control-ui
# 控制云台向上转动，速度5（默认）
python -m scripts.device_management control --sn BF05CF0PHA7DF14 --direction up --open-id openclaw-control-ui
# 控制云台向左转动，速度8
python -m scripts.device_management control --sn BF05CF0PHA7DF14 --direction left --speed 8 --open-id openclaw-control-ui
# 开启声音侦听
python -m scripts.device_management control --sn BF05CF0PHA7DF14 --sound on --open-id openclaw-control-ui
# 关闭声音侦听
python -m scripts.device_management control --sn BF05CF0PHA7DF14 --sound off --open-id openclaw-control-ui
```
## 输出格式示例
### 设备列表示例
| 设备ID | 设备序号 | 设备名称 | 类型 | IP地址 | 状态 | 操作 |
|---------------------|-----------------|-----------|-----|---------------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 2020005731198033922 | BJ10AF5PHAD32E9 | 大华摄像头1BD9 | 大华 | - | ✅ 在线 | [▶️ 查看实时画面](http://cmgw-vpc.lechange.com:8888/LCO/BJ10AF5PHAD32E9/0/1/20260129T141842/openhzdc2a6020d5714149b7b5b581634a1b28.m3u8?source=open&id=2020005731198033922) |
| 2020001323218033921 | BJ20SF5ASSESEF1 | 客厅摄像头 | IPC | 192.168.1.101 | ❌ 离线 | - |
### 直播流返回示例
📹 **大华摄像头1BD9 实时画面**
- 流格式：HLS (m3u8)
-
播放地址：[▶️ 点击播放](http://cmgw-vpc.lechange.com:8888/LCO/BJ10AF5PHAD32E9/0/1/20260129T141842/openhzdc2a6020d5714149b7b5b581634a1b28.m3u8?source=open&id=2020005731198033922)
- 提示：点击链接即可直接在浏览器中播放实时画面，支持所有主流浏览器
don't have the plugin yet? install it then click "run inline in claude" again.