（4348期）Switchbot – 官方 API 掌控全屋智能设备

官方 API 掌控全屋智能设备 通过官方 API 控制 SwitchBot 智能窗帘、插座、灯光、门锁等设备，支持本地安全凭证管理，适合智能家居自动化场景。 使用说明 SwitchBot 智能家居控制技能评估 核心用法 该技能通过 SwitchBot Cloud API v1.1 提供对 SwitchBot 全系智能设备的控制能力，涵盖窗帘（Curtain/Curtain3）、智能插座（Plug Mini/Plug）、灯光（Light/Strip Light）、门锁（Lock）、加湿器（Humidifier）、温湿度传感器（Meter/MeterPlus）以及 Bot 机械按钮控制器等。用户首次使用时需在 SwitchBot App 中获取 Token 和 Secret Key，按指引存储于本地加密目录（~/.config/switchbot/credentials.json，权限 600），随后通过 Python 脚本完成设备发现与控制。 操作层面，技能支持设备列表查询、窗帘开合及百分比定位、插座/灯光开关、传感器状态读取、以及通用命令接口。错误处理机制明确，涵盖设备离线（151）、命令不支持（152）、参数无效（161）等常见场景，便于问题排查。 显著优点 官方 API 支持：直接对接 SwitchBot 官方云服务，稳定性与兼容性有保障，非逆向工程方案。 本地凭证安全：强制要求 600 权限的 JSON 凭证文件，避免硬编码或明文暴露，符合最小权限原则。 设备覆盖全面：支持 10 余类设备、30+ 指令，从简单的开关到复杂的窗帘定位、灯光调色均可实现。 Agent 友好设计：内置首次引导流程、设备别名映射建议（TOOLS.md）、批量操作与状态预检提示，降低自动化脚本开发门槛。 潜在缺点与局限性 云依赖：所有指令经 api.switch-bot.com 中转，无本地局域网直连能力，网络中断或云服务故障时完全不可用。 认证流程繁琐：Token/Secret 获取路径较深（Profile → Preferences → About → Developer Options），对非技术用户不够直观。 Hub 网关依赖：部分设备需配合 Hub/Hub Mini/Hub 2 使用，离线报错（151）时需人工排查硬件连接。 速率与并发限制：官方未公开 API 限流策略，高频自动化场景存在潜在触发上限风险。 适合人群 已部署 SwitchBot 生态、希望通过脚本或 AI Agent 实现自动化的技术型用户 需要将窗帘、灯光、环境传感器接入 Home Assistant 或其他智能家居中枢的进阶玩家 追求「语音/定时触发 → 设备执行」闭环，且能接受云端架构的智能家居爱好者 常规风险 凭证泄露：若 credentials.json 权限设置不当或被误提交至代码仓库，可能导致设备被恶意控制 隐私数据外流：温湿度等传感器数据经云 API 读取，存在上传至 SwitchBot 服务器的合规性考量 指令误触：批量操作或别名配置错误可能导致窗帘异常开合、门锁误解锁等物理安全问题 服务持续性：SwitchBot 保留 API 变更或废弃权利，长期自动化需关注官方迁移公告 原始说明 Control SwitchBot smart home devices (curtains, plugs, lights, locks, etc.) via SwitchBot Cloud API. Use when user asks to open/close curtains, turn on/off l...