核心用法
SwitchBot OpenAPI Skill 允许用户通过 HTTPS 协议与 SwitchBot 官方 API 交互，实现对旗下智能家居设备的远程控制与状态查询。该技能基于 OpenAPI v1.1 版本，采用 HMAC-SHA256 签名认证机制，要求用户提供 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET 环境变量。
主要功能模块：
- 设备发现：
GET /v1.1/devices列出账户下所有设备及其元数据 - 状态查询：
GET /v1.1/devices/{deviceId}/status获取设备实时状态 - 命令控制：
POST /v1.1/devices/{deviceId}/commands执行开关、按压、锁定、温度调节、窗帘百分比等操作 - 场景执行：
POST /v1.1/scenes/{sceneId}/execute作为部分设备（如特定扫地机型）无直接指令时的备用方案
执行方式：技能提供 Node.js CLI 脚本 (switchbot_cli.js) 和 Bash curl 模板，自动处理签名计算、时间戳生成和重试逻辑，降低直接使用 API 的复杂度。
关键前置条件：蓝牙类设备（Bot、Lock、Curtain 等）必须在 SwitchBot App 中绑定 Hub 并开启 enableCloudService，否则 CLI 会前置拦截并提示修复步骤。
显著优点
1. 官方 API 背书：基于 SwitchBot 官方 OpenAPI，协议稳定，非逆向工程方案
2. 多区域支持：内置 global/na/eu/jp 区域配置，适配不同服务节点
3. 安全签名机制：HMAC-SHA256 + 时间戳 + 随机 nonce，防止重放攻击
4. 预检保护：CLI 在发送敏感命令前验证设备云服务能力，避免无效请求
5. 场景降级策略：当设备不支持直接指令时（如特定扫地机返回 160 错误），自动引导用户使用场景 API 作为替代方案
潜在缺点与局限性
1. 硬件依赖门槛：蓝牙设备强制要求 Hub 网关，无法纯云端直连
2. 功能覆盖缺口：OpenAPI v1.1 对部分新型设备（如某些扫地机型号）未开放完整指令集，需依赖场景 API 间接控制
3. 认证配置复杂：Token/Secret 的获取和容器环境变量配置对用户有一定技术门槛
4. 时间同步敏感：HMAC 签名依赖毫秒级时间戳，容器时间漂移可能导致 100/190 认证失败
5. 网络可达性：需公网 HTTPS 访问 SwitchBot 服务器，无法局域网离线控制
适合人群
- 已部署 SwitchBot Hub 并开启云服务的现有用户
- 希望将 SwitchBot 设备集成至自动化工作流的技术用户
- 具备基础容器/环境变量配置能力的智能家居爱好者
- 需要程序化控制窗帘、门锁、温控器等场景的开发者
常规风险
- 凭证泄露：Token/Secret 若硬编码或日志泄露，可导致设备被未授权控制
- 误操作风险：远程解锁、窗帘误开等物理安全后果，建议对敏感操作启用二次确认
- API 变更：官方 API 版本升级可能导致兼容性问题
- 服务依赖：设备控制完全依赖 SwitchBot 云服务可用性，无本地 fallback