Hik Cloud Device Group Management

调用海康云眸开放平台设备分组管理接口，包括新增组、删除组、更新组、查询组织详情、查询所有组织、查询下级组和设备转移分组。用户提到设备组织、设备分组、groupNo、groupId、parentNo、设备转组等场景时使用。本技能自动处理 access_token 获取与刷新，不向用户暴露 token 调用流程。

Security Scan

The skill's code, instructions, and required credentials are consistent with its stated purpose (managing Hik-Cloud device groups); no obvious incoherent or malicious behaviors were found.

Purpose & Capability

The name/description match the included Python script and reference docs. Requested binaries (python3) and required env vars (HIK_OPEN_CLIENT_ID, HIK_OPEN_CLIENT_SECRET) are exactly what a client-credentials-based Hik-Cloud integration would need. Endpoints and operations in the SKILL.md align with the API paths in references and the script.

Instruction Scope

Runtime instructions stay within the stated scope (create/delete/update/get/list/device-transfer). The script reads environment variables, accepts an explicit --access-token, and caches tokens to a filesystem path (~/.cache/hik_open/token.json). Caching tokens to disk is expected for this workflow but is a privacy/operational consideration (token stored in plaintext unless the runtime secures the file).

Install Mechanism

No install spec; this is instruction-only with an included Python script. Nothing is downloaded from remote URLs or extracted. Risk from installation is low because no external installers or arbitrary downloads are present.

Credentials

The skill requires only HIK_OPEN_CLIENT_ID and HIK_OPEN_CLIENT_SECRET (primaryEnv is the client secret), which is proportional to obtaining an OAuth token for the Hik-Cloud API. It also optionally uses HIK_OPEN_ACCESS_TOKEN and HIK_OPEN_BASE_URL. The only caution: the resulting access_token is cached to disk by default, so the secret indirectly leads to persisted tokens; consider this when using the skill in shared environments.

Persistence & Privilege

always:false and normal autonomous invocation are set. The skill persists only its own token cache file and does not attempt to modify other skills or system-wide agent settings. No elevated or global privileges are requested.

Assessment

This skill appears coherent and implements the documented Hik-Cloud device-group operations. Before installing: (1) Treat HIK_OPEN_CLIENT_SECRET as sensitive — provide it via the sandboxed credential mechanism rather than pasting into chat or shared shells. (2) Be aware the script caches access_token to ~/.cache/hik_open/token.json in plaintext; on multi-user or shared systems, either change the cache path to a secure location or pass an explicit --access-token that you manage, and remove the cache after use. (3) Verify the base URL (HIK_OPEN_BASE_URL or --base-url) if you need to target a staging environment. (4) Audit network egress policies if you run this in a secure environment. No other inconsistencies or hidden endpoints were detected.

海康云眸设备分组管理

Overview

按固定链路执行海康云眸开放平台设备分组管理接口，优先使用 {baseDir}/scripts/hik_open_device_group_management.py，不要临时手写认证、URL 拼接和重试逻辑。

本技能只处理以下能力：

• 新增组
• 删除组
• 更新组
• 查询单个组详情
• 查询所有组织
• 查询下级组
• 设备转移分组

本技能不对外暴露 “获取 access_token” 操作。鉴权属于内部基础设施：脚本会自动读取凭证、获取 token、缓存 token，并在 401 时自动刷新后重试一次。

OpenClaw 配置

当 OpenClaw 通过 ~/.openclaw/openclaw.json 管理本技能时，使用 metadata.openclaw.skillKey 作为配置键：

{
  skills: {
    entries: {
      "hik-cloud-device-group-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. 若业务接口返回 HTTP 401，自动刷新 token 并重试一次。
4. 若接口返回非成功状态，直接返回真实错误，不臆造结果。
5. 组详情和删除操作使用 groupNo；设备转组使用 targetGroupId，不要混用。
6. parentNo 为空表示根组织；若用户未明确提供父组信息，不要擅自假设要挂到某个已有组织下。
7. 用户若要求“展示 token / 返回 token 原文”，说明这不属于本技能的主要职责；仅在明确要求调试认证链路时再解释。

快速开始

先准备环境变量：

export HIK_OPEN_CLIENT_ID="<YOUR_CLIENT_ID>"
export HIK_OPEN_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

新增组：

python3 {baseDir}/scripts/hik_open_device_group_management.py create \
  --group-name "华东一区" \
  --group-no "east-001" \
  --parent-no "root-01"

删除组：

python3 {baseDir}/scripts/hik_open_device_group_management.py delete \
  --group-no "east-001"

更新组：

python3 {baseDir}/scripts/hik_open_device_group_management.py update \
  --group-no "east-001" \
  --group-name "华东一区-新"

查询单个组：

python3 {baseDir}/scripts/hik_open_device_group_management.py get \
  --group-no "east-001"

查询所有组织：

python3 {baseDir}/scripts/hik_open_device_group_management.py list-all

查询下级组：

python3 {baseDir}/scripts/hik_open_device_group_management.py list-children \
  --parent-no "root-01"

设备转移分组：

python3 {baseDir}/scripts/hik_open_device_group_management.py device-transfer \
  --device-serial ABC1234567 \
  --target-group-id bc441199bec54f5a8d09b1b1c88c413d

子命令说明

• create：新增组
• delete：删除组
• update：更新组名称
• get：查询单个组详情
• list-all：查询所有组织
• list-children：查询下级组
• device-transfer：将设备转移到目标组

通用参数：

• --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：输出结构化结果，包含请求上下文和原始响应数据

资源说明

• {baseDir}/scripts/hik_open_device_group_management.py：主脚本，负责认证、缓存、组织接口调用
• {baseDir}/references/auth.md：认证与 token 自动刷新规则
• {baseDir}/references/device-group-management.md：设备分组管理接口摘要