Skill: hik-cloud-open/hik-cloud-open-device-management (version 1.0.0)

--- name: hik-cloud-device-management description: 调用海康云眸开放平台设备基础管理接口，包括注册设备、删除设备、修改设备名称、查询设备详情、查询设备列表、获取设备总数、查询设备状态和设备重启。用户提到设备注册、设备删除、设备重命名、设备列表、设备状态、设备重启等场景时使用。本技能自动处理 access_token 获取与刷新，不向用户暴露 token 调用流程。 metadata: { "openclaw": { "skillKey": "hik-cloud-device-management", "emoji": "🧰", "primaryEnv": "HIK_OPEN_CLIENT_SECRET", "requires": { "bins": ["python3"], "env": ["HIK_OPEN_CLIENT_ID", "HIK_OPEN_CLIENT_SECRET"] } } } --- # 海康云眸设备基础管理 ## Overview 按固定链路执行海康云眸开放平台设备基础管理类接口，优先使用 `{baseDir}/scripts/hik_open_device_management.py`，不要临时手写认证、URL 拼接和重试逻辑。 本技能只处理以下能力： - 注册设备 - 删除设备 - 修改设备名称 - 查询单个设备信息 - 查询设备列表 - 获取设备总数 - 查询设备状态 - 设备重启 本技能不对外暴露 “获取 access_token” 操作。鉴权属于内部基础设施：脚本会自动读取凭证、获取 token、缓存 token，并在 401 时自动刷新后重试一次。 ## OpenClaw 配置 当 OpenClaw 通过 `~/.openclaw/openclaw.json` 管理本技能时，使用 `metadata.openclaw.skillKey` 作为配置键： ```json5 { skills: { entries: { "hik-cloud-device-management": { enabled: true, env: { HIK_OPEN_CLIENT_ID: "...", HIK_OPEN_CLIENT_SECRET: "...", HIK_OPEN_BASE_URL: "https://your-custom-base-url" } } } } } ``` 若 Session 运行在 sandbox 中，宿主环境变量不会自动继承。此时应通过 OpenClaw 的 sandbox env 配置注入凭证，而不是依赖本机 shell 的 `process.env`。 域名切换优先级： 1. `--base-url` 2. `HIK_OPEN_BASE_URL` 3. 默认正式环境：`https://api2.hik-cloud.com` ## 执行规则 1. 认证固定使用 `Authorization: Bearer <access_token>`。 2. token 来源优先级： - `--access-token` - `HIK_OPEN_ACCESS_TOKEN` - token cache - `HIK_OPEN_CLIENT_ID + HIK_OPEN_CLIENT_SECRET` 自动换取 3. 域名来源优先级： - `--base-url` - `HIK_OPEN_BASE_URL` - 默认正式环境 `https://api2.hik-cloud.com` 4. 若业务接口返回 HTTP `401`，自动刷新 token 并重试一次。 5. 若接口返回非成功状态，直接返回真实错误，不臆造结果。 6. 设备重启属于高影响操作，执行前应再次确认设备序列号。 7. 查询设备状态接口目前仅支持萤石设备。 8. 用户若要求“展示 token / 返回 token 原文”，说明这不属于本技能的主要职责；仅在明确要求调试认证链路时再解释。 ## 快速开始 先准备环境变量： ```bash export HIK_OPEN_CLIENT_ID="<YOUR_CLIENT_ID>" export HIK_OPEN_CLIENT_SECRET="<YOUR_CLIENT_SECRET>" ``` 注册设备： ```bash python3 {baseDir}/scripts/hik_open_device_management.py create \ --device-serial E05426006 \ --group-no fsdfe \ --validate-code ADSEFE ``` 删除设备： ```bash python3 {baseDir}/scripts/hik_open_device_management.py delete \ --device-serial 123456 ``` 修改设备名称： ```bash python3 {baseDir}/scripts/hik_open_device_management.py rename \ --device-serial E05426006 \ --device-name "设备名称" ``` 查询单个设备信息： ```bash python3 {baseDir}/scripts/hik_open_device_management.py get \ --device-serial D05215100 \ --need-defence ``` 查询设备列表： ```bash python3 {baseDir}/scripts/hik_open_device_management.py list \ --group-no 1 \ --page-no 1 \ --page-size 50 ``` 获取设备总数： ```bash python3 {baseDir}/scripts/hik_open_device_management.py count ``` 查询设备状态： ```bash python3 {baseDir}/scripts/hik_open_device_management.py status \ --device-serial C01563792 ``` 设备重启： ```bash python3 {baseDir}/scripts/hik_open_device_management.py reboot \ --device-serial 123456789 ``` ## 子命令说明 - `create`：注册设备 - `delete`：删除设备 - `rename`：修改设备名称 - `get`：查询单个设备信息 - `list`：查询设备列表 - `count`：获取设备总数 - `status`：查询设备状态 - `reboot`：设备重启 通用参数： - `--base-url`：显式指定接口域名，优先级高于环境变量 - `--access-token`：显式指定 access token - `--timeout`：请求超时秒数，默认 `20` - `--token-cache-file`：token 缓存文件，默认 `~/.cache/hik_open/token.json` - `--format`：`text` 或 `json` 通用环境变量： - `HIK_OPEN_CLIENT_ID` - `HIK_OPEN_CLIENT_SECRET` - `HIK_OPEN_ACCESS_TOKEN` - `HIK_OPEN_BASE_URL` ## 输出约定 - `--format text`：输出简要结果摘要和关键字段 - `--format json`：输出结构化结果，包含请求上下文和原始响应数据 判读关键字段时优先看这些值： - `deviceStatus`：`0` 离线，`1` 在线 - `defence`：只在 `get + --need-defence` 时返回；具防护能力设备是 `0` 睡眠、`8` 在家、`16` 外出，普通 IPC 是 `0` 撤防、`1` 布防 - `privacyStatus`：`0` 关闭、`1` 打开、`-1` 初始值、`2` 不支持、`-2` 未上报/不支持 - `pirStatus`：`1` 启用、`0` 禁用、`-1` 初始值、`2` 不支持、`-2` 未上报/不支持 - `alarmSoundMode`：`0` 短叫、`1` 长叫、`2` 静音、`3` 自定义语音、`-1` 未上报/不支持 - `cloudStatus`：`-2` 不支持、`-1` 未开通、`0` 未激活、`1` 激活、`2` 过期 - `diskState` / `nvrDiskState`：状态串按盘位拼接，`0` 正常、`1` 存储介质错、`2` 未格式化、`3` 正在格式化；`nvrDiskState` 额外支持 `-2` 未关联 ## 资源说明 - `{baseDir}/scripts/hik_open_device_management.py`：主脚本，负责认证、缓存和设备管理接口调用 - `{baseDir}/references/auth.md`：认证与 token 自动刷新规则 - `{baseDir}/references/device-management.md`：设备基础管理文档摘要

path: agents/openai.yaml
content: interface:
  display_name: "海康云眸设备基础管理"
  short_description: "注册、删除、查询、重启海康云眸设备。"
  default_prompt: "Use $hik-cloud-device-management to manage Hik-Cloud devices for create, delete, rename, query, status, count, or reboot tasks."


path: references/auth.md
content: # 认证说明

本技能内部使用海康云眸开放平台 OAuth token：

- 地址：`https://api2.hik-cloud.com/oauth/token`
- 方法：`POST application/x-www-form-urlencoded`
- 参数：`client_id`、`client_secret`、`grant_type=client_credentials`、`scope=app`

Skill 约束：

- 不对用户暴露“先获取 access_token 再调用”的显式工作流
- 脚本优先自动处理 token 获取、缓存、续期
- 业务接口统一注入 `Authorization: Bearer <access_token>`
- 401 时自动刷新 token 并重试一次
- 认证接口与业务接口统一跟随当前 base URL

环境变量：

- `HIK_OPEN_CLIENT_ID`
- `HIK_OPEN_CLIENT_SECRET`
- `HIK_OPEN_ACCESS_TOKEN`（可选覆盖）
- `HIK_OPEN_BASE_URL`（可选，用于指定自定义环境域名）


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)