Skip to content

SWITCHBOT_GUIDE.md

Latest commit

 

History

History
285 lines (228 loc) · 8.76 KB

SWITCHBOT_GUIDE.md

File metadata and controls

285 lines (228 loc) · 8.76 KB

SwitchBot Smart Home Plugin — 使用指南

这是 switchbot-home 插件的完整操作手册。当用户提到智能家居、设备控制、自动化时，参考此文档快速操作。

快速参考：16 个工具

工具 用途 常用场景
switchbot_query_history 查询本地 MQTT 设备状态历史 "最近温度变化" "设备状态"
switchbot_list_devices 列出所有设备（物理 + 红外） "我有哪些设备"
switchbot_device_status 查询单个设备实时状态 "插座开着吗" "温度多少"
switchbot_list_scenes 列出所有手动场景 "有哪些场景"
switchbot_execute_scene 执行场景 "执行回家场景"
switchbot_control_device 控制设备 "开灯" "关插座" "开窗帘"
switchbot_control_history 查看控制操作记录 "最近操作了什么"
switchbot_create_automation 创建自动化规则 "温度高了自动开空调"
switchbot_list_automations 列出自动化规则 "有哪些自动化"
switchbot_manage_automation 启用/禁用/删除自动化 "关掉那个自动化"
switchbot_automation_log 查看自动化触发历史 "自动化执行了吗"
switchbot_analyze_habits 分析设备使用习惯 "分析我的使用习惯"
switchbot_create_key_event 创建关键事件监控 "温度超35度提醒我"
switchbot_list_key_events 列出关键事件配置 "有哪些监控"
switchbot_manage_key_event 启用/禁用/删除关键事件 "关掉温度监控"
switchbot_key_event_log 查看关键事件触发历史 "监控触发过吗"

一、查询设备

列出所有设备

工具: switchbot_list_devices
参数: 无

查询设备状态

工具: switchbot_device_status
参数: device = 设备名称 或 设备ID 或 MAC地址

支持模糊匹配，例如传入 "插座" 可以匹配 "智能插座Mini（US） 1E"。

查询 MQTT 历史数据

工具: switchbot_query_history
参数:
  - device: MAC地址（如 "CD8BE5455C9D"）或设备类型（如 "WoMeterPro"）
  - history: true 返回多条历史
  - limit: 条数（默认20，最大100）
  - startTime / endTime: ISO 8601 时间过滤
  - includeImages: true 包含图片路径

二、控制设备

直接控制

工具: switchbot_control_device
参数:
  - device: 设备名称 或 ID
  - command: 命令名
  - parameter: 参数（默认 "default"）
  - commandType: "command"（默认）或 "customize"（红外遥控）

常用命令速查

设备类型 命令 参数 说明
Bot (智能开关) press default 按一下
Bot turnOn / turnOff default 开/关
Plug Mini (智能插座) turnOn / turnOff default 开/关
Color Bulb (灯泡) turnOn / turnOff default 开/关
Color Bulb setBrightness 1-100 亮度
Color Bulb setColor "255:0:0" RGB颜色
Color Bulb setColorTemperature 2700-6500 色温
Curtain (窗帘) turnOn / turnOff default 全开/全关
Curtain setPosition "0,ff,位置" 位置 0-100
Smart Lock lock / unlock default 锁门/开门
Humidifier (加湿器) turnOn / turnOff default 开/关
Humidifier setMode auto/101/102/103 模式
Robot Vacuum start / stop / dock default 开始/停止/回充
红外遥控设备 turnOn / turnOff default 开/关（commandType 用 "customize"）

执行场景

工具: switchbot_execute_scene
参数: scene = 场景名称 或 场景ID

三、创建自动化

核心概念

自动化 = 触发条件脚本 + 执行动作。脚本在设备事件到达时自动执行，不消耗 LLM token。

创建自动化

工具: switchbot_create_automation
参数:
  - name: 自动化名称
  - description: 描述
  - script: JavaScript 表达式（见下方）
  - triggerDeviceMac: 限定触发设备 MAC（可选）
  - triggerDeviceType: 限定触发设备类型（可选）
  - actionDeviceId: 要控制的设备 ID
  - actionCommand: 命令
  - actionParameter: 参数（默认 "default"）
  - actionSceneId: 或执行场景 ID（与 actionDeviceId 二选一）
  - notifyOnTrigger: true 触发时通知用户

script 脚本编写

脚本通过 event 对象访问设备状态字段，返回 truthy 即触发动作：

event 可用字段：

字段 类型 来源设备
event.deviceType string 所有设备
event.deviceMac string 所有设备
event.timeOfSample number 所有设备
event.temperature number 温湿度计、Hub 2
event.humidity number 温湿度计、Hub 2
event.power "on"/"off" 插座、灯泡
event.battery number (0-100) 电池供电设备
event.motionDetected boolean 人体传感器
event.detectionState "DETECTED"/"NOT_DETECTED" 人体传感器
event.openState "open"/"close"/"timeOutNotClose" 门窗传感器
event.brightness "bright"/"dim" 门窗传感器
event.lockState "locked"/"unlocked"/"jammed" 智能门锁
event.doorState "open"/"closed" 智能门锁
event.slidePosition number (0-100) 窗帘

脚本示例：

// 温度超过30度
event.temperature > 30

// 温度低于18度
event.temperature < 18

// 湿度低于30%
event.humidity < 30

// 检测到人体运动
event.motionDetected === true

// 门窗打开
event.openState === "open"

// 门锁卡住
event.lockState === "jammed"

// 电量低于10%
event.battery < 10

// 组合条件：温度高且湿度高
event.temperature > 30 && event.humidity > 70

// 插座断电
event.power === "off"

// 窗帘位置超过50%
event.slidePosition > 50

// 特定时间段（晚上10点后检测到运动）
event.motionDetected === true && new Date(event.timeOfSample).getHours() >= 22

自动化创建示例

示例1：温度高于30度开空调

name: "高温开空调"
script: "event.temperature > 30"
triggerDeviceType: "WoMeterPro"
actionDeviceId: "01-202207182154-66710217"  （红外空调ID）
actionCommand: "turnOn"
notifyOnTrigger: true

示例2：检测到运动开灯

name: "人来开灯"
script: "event.motionDetected === true"
triggerDeviceMac: "CC6435A90D26"
actionDeviceId: "灯泡设备ID"
actionCommand: "turnOn"

示例3：门窗长时间未关提醒

name: "门窗超时未关"
script: "event.openState === 'timeOutNotClose'"
actionSceneId: "提醒场景ID"
notifyOnTrigger: true

管理自动化

# 列出所有自动化
工具: switchbot_list_automations

# 启用/禁用/删除
工具: switchbot_manage_automation
参数: id = 自动化ID, action = "enable" | "disable" | "delete"

# 查看触发历史
工具: switchbot_automation_log
参数: automationId = 自动化ID（可选）, limit = 条数

四、关键事件监控

与自动化类似，但只发通知不执行动作，适合告警场景。

创建关键事件

工具: switchbot_create_key_event
参数:
  - name: 事件名称
  - script: JavaScript 表达式（同自动化脚本）
  - triggerDeviceMac / triggerDeviceType: 过滤（可选）
  - notifyMessageTemplate: 通知消息模板，支持 {字段名} 变量替换

消息模板示例：

"当前温度 {temperature}°C，湿度 {humidity}%，请注意"
"门锁状态异常: {lockState}"
"检测到运动，设备: {deviceMac}"

关键事件示例

高温报警：

name: "高温报警"
script: "event.temperature > 35"
triggerDeviceType: "WoMeterPro"
notifyMessageTemplate: "温度报警: {temperature}°C 超过35度阈值"

电量低报警：

name: "低电量提醒"
script: "event.battery < 10"
notifyMessageTemplate: "{deviceType} 电量过低: {battery}%，请及时更换电池"

五、使用习惯分析

工具: switchbot_analyze_habits
参数: days = 分析天数（默认30）

返回数据包括：

  • 按小时分布的操作频率（发现使用高峰时段）
  • 按星期分布（发现工作日/周末差异）
  • 各设备使用排名和常用命令
  • 设备组合（哪些设备经常一起操作）

分析完成后，可以根据数据建议自动化，用户确认后直接调用 switchbot_create_automation 创建。

六、运行机制

  • MQTT 实时推送：设备状态变化会通过 MQTT 实时推送到本地 SQLite，无需轮询
  • 自动化零 token：创建时 AI 生成脚本，运行时纯 JS 沙箱执行，不调用 LLM
  • 60秒冷却：同一自动化/关键事件触发后 60 秒内不会重复触发
  • 数据保留 90 天：设备状态历史自动清理超过 90 天的数据
  • 控制记录持久化：所有设备控制和场景执行都记录在 SQLite 中