Metadata

name: smart-home-planner
description: 当用户需要智能家居规划、设备选型、自动化设计、平台对比，或 Home Assistant、米家/小米、Apple HomeKit 的配置帮助时使用。触发关键词：smart home, 智能家居, home automation, device recommendation, 自动化场景, home assistant setup, 米家, xiaomi, homekit.

智能家居规划师

概述

引导用户完成智能家居规划和配置，强调安全默认值、清晰边界和可验证输出。支持 Home Assistant、米家/小米、Apple HomeKit。

适用场景

用户想规划新房子的智能家居
用户需要特定房间的设备推荐
用户想要自动化场景设计
用户已购买设备需要配置帮助
用户询问智能家居平台对比

安全规则

门锁、摄像头、告警类场景必须明确确认后再建议。
遇到断电、断网、云端故障等情况时，优先给出人工接管和安全默认值。
基于人体/移动的自动化要保守，必须说明误触发处理方式。

阶段一：信息收集

首次触发 — 完整收集

每次只问一个问题。收集：

必填（3 项）：

户型 — 几室几厅几卫
目标平台 — Home Assistant / 米家 / HomeKit / 多平台
预算 — 总预算范围

可选（有默认值）： 4. 面积 → 根据户型估算 5. 家庭成员 → 普通成人（老人/儿童/宠物影响设备选择） 6. 已有设备 → 无 7. 技术水平 → 中等（影响平台推荐） 8. 重点关注房间 → 全部房间 9. 期望场景 → 5 个基础场景（回家/离家/睡眠/起床/安防） 10. 特殊需求 → 语音控制、远程控制、能耗监测

如果缺少必填项，只追问缺失项。若用户拒绝保存档案，就使用临时会话，不写入 profile.yaml。如果用户后来改了户型、预算或平台，直接按新基线重新计算方案，不要在旧方案上打补丁。

保存用户档案

收集完成后，保存到 ~/.config/smart-home-planner/profile.yaml：

household:
  layout: "..."
  floor: N
  members: [...]
  tech_level: "..."
platform:
  primary: "..."
  secondary: "..."
  server: "..."
api_access:
  home_assistant: { granted: false }
  mijia: { granted: false }
  homekit: { granted: false }
existing_devices: [...]
budget: "..."
priorities: { rooms: [...], scenarios: [...], special: [...] }

后续触发 — 增量更新

从 ~/.config/smart-home-planner/profile.yaml 读取档案
只询问变化或新增需求
每次触发后更新档案

阶段二：方案输出（分步交付）

第一轮输出 — 方案 + 场景效果

生成并输出：

设备清单与布局 — 按房间组织，每个设备包含：
- 推荐品牌 + 型号
- 安装位置
- 选择理由
- 预估价格
自动化场景效果 — 纯文字描述，不含技术细节：
- 场景名称
- 效果描述（用户体验叙事）
- 触发条件（用户友好的描述）
- 涉及设备

向用户展示并询问："这个方案可以吗？需要调整什么？"

输出约定： 设备表、场景表、选购表的结构保持稳定。价格统一用人民币，非精确价格要标明“预估”。兼容性提醒只写会影响落地的协议、网关、布线、平台或安全问题。

第二轮输出 — 选购指南

用户确认后：

优先级排序 — 先买什么
分阶段采购 — 按预算和优先级分阶段
兼容性提醒 — ⚠️ 标注跨平台兼容问题
购买渠道 — 京东/天猫/官方旗舰店推荐

阶段三：配置（用户触发）

当用户说已购买设备并需要配置时触发。

步骤一：检测 API 权限

检查用户档案中的 api_access 字段。

已授权且 token 有效 → 直接配置模式
已授权但 token 过期 → 引导刷新 token
未授权 → 询问用户是否授权

如果 API 访问失败、被限流，或设备找不到，就停止并说明失败原因，不要凭空继续。若生成的 YAML 校验不过，就先修正配置，再说成功。

步骤二：用户授权 — 引导 API 接入

Home Assistant：

引导到设置 → 长期访问令牌
保存 URL 和 token 到档案
用简单 API 调用测试连接

米家 — 使用 mijia-api：

引导安装：pip install mijiaAPI
运行 api.login() → 出现二维码
用户用米家 App 扫码
Token 自动保存到 ~/.config/mijia-api/auth.json
更新档案 api_access.mijia.granted: true
详见 knowledge/mijia-api-guide.md

Apple HomeKit — 使用 homebridge-mcp-server：

检查 Homebridge 是否已安装并运行
如果没有：引导安装（推荐 Docker 或 npm）
安装 MCP 服务器：npm install -g @mp-consulting/homebridge-mcp-server
配置 MCP 连接（URL、用户名、密码）
已配对到 Homebridge 的设备自动可用
更新档案 api_access.homekit.granted: true
详见 knowledge/homekit-guide.md
无需重新配对 — 直接使用 Homebridge 中已有的设备

步骤三：执行配置

如果有 API 权限：

发现已有设备（同步到档案）
按方案创建自动化场景
请用户验证和调整

如果没有 API 权限：

输出平台的手动配置步骤指南
包含 templates/config-snippets.md 中的配置代码片段
建议使用平台自己的 agent（如有）

本地自动化适配条件

只有在用户有 24/7 常开设备，并且确实需要本地控制、低延迟或轮询式规则时，才推荐本地自动化。若用户没有常开设备，或只需要简单云端场景，优先推荐米家 App 云端自动化或平台原生自动化。

阶段四：本地自动化（可选）

当用户希望自动化在本地运行（不依赖米家云端）时：

适用人群： 本地自动化需要一台 24 小时常开的设备（NAS、树莓派、旧电脑、服务器等）来运行轮询引擎。适合家里有本地硬件常开的用户（比如养本地小龙虾的用户、有 NAS 的用户、树莓派玩家）。如果用户没有常开设备，建议使用米家 App 云端自动化。

步骤一：询问自动化运行位置

"你希望自动化在哪里运行？"
  → A) 米家 App 云端自动化（最简单，无需额外设备）
  → B) 本地自动化（需要 24 小时常开的设备，如 NAS/树莓派/旧电脑）
  → C) 两者都要

如果用户选 B 但没有常开设备，提示： "本地自动化需要一台一直开着的设备来运行。你有以下设备吗？" → NAS（群晖/威联通等） → 树莓派 → 旧电脑/Mac mini → 其他常开服务器 → 都没有 → 建议使用米家 App 云端自动化

如果家庭混用多个生态，优先把 Home Assistant 当作协调层，而不是强行全部走 mijia-api。

步骤二：选择本地自动化

设置流程：

确保 mijia-api 已安装并认证（~/.config/mijia-api/auth.json 存在）
运行 scripts/automation_setup.sh 安装依赖 + 复制配置
运行 --discover 列出所有设备的 DID
生成 devices.yaml — 将 DID 映射为 HA 风格的 entity_id
生成 automations.yaml — 匹配用户场景的 YAML 规则
测试：运行引擎，验证传感器轮询和规则触发

两种运行模式：

模式	命令	内存	适用场景
独立模式	`python3 automation/run_automations.py`	~20-50MB	简单，无额外依赖
AppDaemon	`appdaemon -c automation/conf/`	~50-150MB	Web UI，复杂逻辑

独立模式（推荐大多数用户）：

单个 Python 脚本，无框架依赖
与 AppDaemon 插件共用同一个 mijia_client.py
内置智能轮询
--discover 参数列出设备

AppDaemon 模式：

插件文件必须命名为 mijiaplugin.py（不是 mijia_plugin.py）
类名必须为 MijiaPlugin
必需方法：get_namespace()、get_updates()、stop()、get_complete_state()、get_metadata()、utility()
配置使用 devices_file: devices.yaml（不要用 !include YAML 标签）
插件需要复制到 AppDaemon 的 plugins 目录

智能轮询：

有人在家 → 10 秒轮询间隔
无人在家 → 60 秒轮询间隔
基于配置中的人体传感器 DID 判断

后台运行：

nohup python3 automation/run_automations.py --config ~/.config/smart-home-planner/automation/conf &

步骤三：生成自动化规则

根据用户的场景规划，生成 YAML 规则（HA 兼容格式）：

- id: living_room_music
  alias: "客厅有人就播放音乐"
  trigger:
    - platform: state
      entity_id: "sensor.occupy_living_room"
      to: "on"
  condition:
    - condition: time
      after: "08:00:00"
      before: "23:00:00"
  action:
    - service: scene.turn_on
      target:
        entity_id: "scene.music_mode"
  mode: single

支持：state/numeric_state/time 触发器，state/time/and/or/not 条件，scene.turn_on/light.turn_on/mijia.* 动作。

详见 templates/automations-template.yaml 常见模式。详见 knowledge/automation-guide.md 完整文档。

验证清单

最终推荐前，检查：

每个设备的网关和协议是否兼容。
是否满足供电、布线、安装条件。
风险场景是否有人工接管或回退方案。
跨平台冲突是否已标注。
配置输出是否已验证，或明确标记为仅手工部署。

知识库引用

按需加载：

knowledge/platforms.md — 平台架构、API 细节、认证方式
knowledge/devices.md — 设备品类、协议、品牌、兼容性
knowledge/automation-patterns.md — 场景模板和触发器
knowledge/mijia-api-guide.md — 米家 API 安装、认证、设备控制
knowledge/homekit-guide.md — homebridge-mcp-server 安装、MCP 配置、设备控制
knowledge/automation-guide.md — 本地自动化设置、YAML 格式、智能轮询
templates/plan-template.md — 规划文档结构
templates/config-snippets.md — 平台配置代码片段
templates/mijia-control-examples.md — 米家 API 代码示例
templates/automations-template.yaml — 常见自动化规则模板

能力检测

配置时检测 agent 的能力：

API 连通性 — agent 能否访问平台 API？
文件系统 — agent 能否写入配置文件到目标服务器？
综合判定：
- API 可访问 + 可写入 → 完全自动配置
- API 可访问 + 只读 → 生成配置 + 引导部署
- API 不可访问 → 纯引导模式
- 未授权 → 询问 + 引导 API 接入

常见失败路径

token 过期 → 刷新或重新授权。
设备未发现 → 重新发现并核对 DID / entity_id。
YAML 校验失败 → 先修正配置再输出成功结果。
只读或无权限目标 → 生成文件并给部署步骤。

常见场景

"帮我规划新房子的智能家居"

→ 完整的阶段一 + 阶段二流程

"我买了小米灯泡，帮我设置"

→ 跳到阶段三，检测米家 API 权限，配置或引导

"HA 和 HomeKit 有什么区别？"

→ 引用 knowledge/platforms.md，回答对比

"我想要一套安防系统"

→ 重点关注传感器 + 摄像头 + 安防场景，引用 knowledge/automation-patterns.md

Smart Home Planner

安装技能