🏠 Home Assistant Control Skill

让 AI Agent（OpenClaw / Hermes / CodeBuddy 等）能够控制你家中的智能家居设备。

通过 Home Assistant 作为中间层，支持华为、欧瑞博、小米、绿米 Aqara、涂鸦等主流中国市场智能家居品牌。

✨ 功能特性

• 🔌 设备控制 — 开关插座、灯光、空调、窗帘、风扇等
• 📊 状态查询 — 查询任意设备的在线状态和属性
• 🔍 设备发现 — 自动发现并列举 Home Assistant 中的设备
• 🎬 场景执行 — 执行「回家模式」「睡眠模式」等自定义场景
• 🛠️ 环境管理 — 自动检测、安装、启动 Home Assistant
• 🔐 安全认证 — Token 安全存储，敏感操作二次确认
• 🗣️ 自然语言 — 直接用中文控制："帮我把客厅插座打开"

📦 安装方式

提供 5 种安装方式，选择最适合你的：

方式 1：npm 全局安装（推荐）

npm install -g @sophiasong/home_assistant

安装后运行初始化：

ha-skill-install

这会自动将 Skill 文件复制到 ~/.codebuddy/skills/home-assistant-control/。

方式 2：OpenClaw 安装

在 OpenClaw 对话中直接说：

安装 skill: home-assistant-control

或手动安装：

openclaw skill install home-assistant-control

方式 3：从 GitHub 安装

# 克隆仓库
git clone https://github.com/YOUR_USERNAME/home-assistant-control-skill.git

# 复制到 Skill 目录
cp -r home-assistant-control-skill ~/.codebuddy/skills/home-assistant-control

方式 4：让 Agent 直接读取 GitHub 链接

在和机器人对话时，直接发送：

请阅读这个 Skill 的内容并使用它来控制我的智能家居:
https://github.com/YOUR_USERNAME/home-assistant-control-skill

Agent 会自动访问链接、阅读 SKILL.md 的内容，并按照其中的指令来执行操作。

💡 这种方式不需要安装，Agent 会即时加载 Skill 内容到上下文中。

方式 5：手动下载 zip 包

从 Releases 下载最新的 home-assistant-control.zip，解压到：

~/.codebuddy/skills/home-assistant-control/

🚀 快速开始

首次使用

安装完成后，对你的 AI 机器人说：

我想控制家里的智能家居

机器人会引导你完成以下步骤：

1. 环境检测 — 自动检测并安装 Home Assistant（Docker 或 pip）
2. 认证配置 — 引导你创建 Long-Lived Access Token
3. 设备接入 — 根据你的品牌引导添加集成（华为/小米/欧瑞博等）
4. 设备注册 — 发现设备并设置友好名称

日常使用

设置完成后，直接用自然语言控制：

| 你说的话 | 效果 | |---------|------| | "打开客厅插座" | ✅ 打开指定插座 | | "关掉卧室的灯" | 💡 关闭灯光 | | "空调调到26度" | ❄️ 设置空调温度 | | "家里设备什么状态？" | 📊 列出所有设备状态 | | "执行回家模式" | 🎬 执行场景 | | "把灯亮度调到50%" | 🔆 调节灯光亮度 |

🏗️ 项目结构

home_assistant/
├── SKILL.md                          # Skill 核心指令 (Agent 读取此文件)
├── package.json                      # npm 包配置
├── index.js                          # npm 入口
├── README.md                         # 说明文档
├── LICENSE                           # MIT 许可证
├── bin/
│   ├── cli.js                        # CLI 命令行工具
│   └── install.js                    # npm 安装后自动部署脚本
├── scripts/
│   ├── ha_setup.sh                   # HA 环境检测 & 安装
│   ├── ha_api.py                     # HA REST API 核心库
│   ├── ha_auth.py                    # 认证 & Token 管理
│   ├── ha_device_control.py          # 设备控制 (开关/调节/查询)
│   └── ha_discovery.py               # 设备发现 & 注册
├── references/
│   ├── ha_rest_api.md                # HA REST API 文档
│   ├── supported_integrations.md     # 支持的品牌集成列表
│   └── device_type_mapping.md        # 自然语言→设备操作映射
└── assets/
    └── config_template/
        └── configuration.yaml        # HA 配置模板

📋 支持的品牌

| 品牌 | 接入方式 | 支持设备 | |------|---------|---------| | 🔌 欧瑞博 (Orvibo) | HACS | 插座、开关、窗帘、门锁 | | 📱 华为 HiLink | HACS | HiLink 协议设备 | | 🏠 小米/米家 | HACS (MIoT Auto) | 灯、插座、空调、扫地机等 | | 🟢 绿米 Aqara | Native/HACS | 传感器、开关、窗帘 | | 🌐 涂鸦 Tuya | Native | 涂鸦方案的所有设备 | | 💡 Yeelight | Native | 各类灯具 | | 🌡️ 博联 Broadlink | Native | 万能遥控器、插座 | | 🔘 公牛 Bull | HACS/Tuya | 插座、开关 |

⚙️ 系统要求

• 操作系统: Linux / macOS / WSL
• Python: 3.9+
• Docker（推荐）或 pip 用于安装 Home Assistant
• 网络: 与智能家居设备在同一局域网

🔒 安全说明

• Token 存储在 ~/.config/home-assistant-skill/credentials.json，权限 600
• 批量操作（如"关掉所有设备"）需要用户二次确认
• 所有操作记录在 ~/.config/home-assistant-skill/operation.log
• Token 不会被 Skill 文件包含或传播

🤝 贡献

欢迎提交 Issue 和 PR！

• 添加新品牌支持：编辑 references/supported_integrations.md 和 scripts/ha_discovery.py
• 改进自然语言映射：编辑 references/device_type_mapping.md
• 修复 Bug / 新功能：提交 PR

📄 License

MIT License