菜单
Home Assistant智能家居系统集成。当用户需要控制智能家居设备、查询设备状态、调用HA服务、管理HA集成配置、使用ha_api脚本时，必须使用此技能。支持通过REST API与Home Assistant交互，实现设备控制、状态查询、服务调用等核心功能。本技能为可选模块，不集成本技能时核心系统能正常运行。脚本零第三方依赖，开箱即用。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | home-assistant |
| version | 1.2.0 |
| description | Home Assistant智能家居系统集成。当用户需要控制智能家居设备、查询设备状态、调用HA服务、管理HA集成配置、使用ha_api脚本时，必须使用此技能。支持通过REST API与Home Assistant交互，实现设备控制、状态查询、服务调用等核心功能。本技能为可选模块，不集成本技能时核心系统能正常运行。脚本零第三方依赖，开箱即用。 |
| argument-hint | <操作类型> [实体ID/服务名] |
| user-invocable | true |
| paths | [".agents/scripts/ha_api.py",".agents/commands/home-assistant.md"] |
| title | Home Assistant 智能家居集成 (Home Assistant Integration) |
| x-toml-ref | ../../../.meta/toml/.agents/skills/home-assistant/SKILL.toml |
⚠️ 本Skill是可选集成模块（L1索引层），遵循渐进式披露三层架构：
- L0：.agents/ONBOARDING.md（入口速查）
- L1：本文件（<200行，触发词+决策树+核心步骤+安全清单）
- L2：commands/home-assistant.md（完整规范+RACI矩阵+错误处理）
📌 可选模块：不集成本技能时核心系统正常运行；HA连接不可用时优雅降级。
home-assistant
与 Home Assistant 智能家居系统交互的技能，支持通过 REST API 实现以下核心功能：
| 功能 | 说明 |
|---|---|
| 设备状态查询 | 获取指定实体的当前状态（开关、亮度、温度等） |
| 设备控制 | 控制设备状态（打开/关闭灯光、调节亮度、设置温度等） |
| 服务调用 | 调用 Home Assistant 服务（如 light.turn_on、climate.set_temperature） |
| 实体列表 | 获取所有已注册实体列表 |
| HA状态 | 检查 Home Assistant 连接状态和版本信息 |
为什么优先使用 ha_api.py？ 脚本方案支持配置化参数、错误处理和重试机制，比手动构造 API 请求更可靠，且内置dry-run防误操作。
当用户提到以下任何内容时触发：
关于触发：即使没有明确说"用 skill"，只要涉及 Home Assistant 操作就应该使用本技能，不要自己手动拼接 API 请求。
需要操作Home Assistant？
├─ 需要查询状态？ → ha_api.py status/get
├─ 需要控制设备？ → ha_api.py set/服务调用（先dry-run！）
├─ 需要获取实体列表？ → ha_api.py list
└─ HA连接不可用？ → 提示配置HA参数（优雅降级）
决策前输出CMD_START日志（session前缀 ha-YYYYMMDD-<entity>）：
[CMD-LOG] | level=INFO | cmd=home-assistant | step=S0 | event=CMD_START | session=ha-... | msg=开始HA操作：<操作简述> | ctx={"operation":"...","entity_id":"...","dry_run":true/false}
为什么决策前记录日志？ 设备控制是写操作，错误操作可能导致设备状态异常；CMD_START记录原始参数，便于操作失误后回溯排查。
步骤1：确认HA连接参数已配置（HA_URL、HA_TOKEN）
步骤2：读取L2文档了解完整参数和RACI责任
步骤3：查询类操作 → ha_api.py get/list/info
步骤4：控制类操作 → 先 --dry-run 预览 → 获得用户确认 → 正式执行
步骤5：验证执行结果（状态查询确认）
完整RACI矩阵、输入规范、错误码表见L2文档 commands/home-assistant.md。
脚本路径：ha_api.py
cd d:\spaces\SpecWeave
# 检查HA连接状态
python .agents/scripts/ha_api.py info
# 获取实体列表
python .agents/scripts/ha_api.py list
# 查询设备状态
python .agents/scripts/ha_api.py get light.living_room
# 控制设备（先dry-run预览！）
python .agents/scripts/ha_api.py set light.living_room --value true --dry-run
python .agents/scripts/ha_api.py set light.living_room --value true
# 设置亮度（0-255）
python .agents/scripts/ha_api.py set light.living_room --brightness 128
# 调用服务
python .agents/scripts/ha_api.py service light.turn_on --entity-id light.living_room
--dry-run）执行HA操作时按精简CMD-LOG规范输出：
cmd=home-assistant，session前缀 ha-YYYYMMDD-<entity_or_topic>DRY_RUN_OK、CONNECTION_FAILED、ENTITY_NOT_FOUND、OPERATION_VERIFIED写操作（set/service）必须输出S0和S5验证日志；只读操作（get/list/info）可简化日志。
| 错误码 | 场景 | 处理方式 |
|---|---|---|
| HA_001 | 连接失败 | 检查 HA_URL 是否正确，HA 实例是否运行 |
| HA_002 | 认证错误 | 检查 HA_TOKEN 是否有效，权限是否足够 |
| HA_003 | 实体不存在 | 确认 entity_id 正确，使用 list 命令查看可用实体 |
| HA_006 | HA 不可用 | 提示用户检查 HA 实例，优雅降级不影响核心系统 |
完整错误码表（HA_001~HA_006）见L2文档。
为什么需要Gotchas？ 错误处理记录"已知错误码及修复方式"，Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。
domain.object_id（如light.living_room、sensor.temperature），domain和object_id之间是点号不是下划线，且整个entity_id大小写敏感。通过list命令可以查看所有实体的准确ID。turn_on），必须使用完整格式domain.service（如light.turn_on、switch.turn_off）。不同domain的同名服务（如light.turn_on和switch.turn_on）是不同的服务。state字段始终是字符串类型。灯的开/关是"on"/"off"字符串，不是布尔值true/false，比较时必须用字符串相等判断，不能直接当布尔值用。https://开头。| 参考 | 层级 | 路径 | 何时查阅 |
|---|---|---|---|
| 完整命令文档（RACI/参数） | L2 | commands/home-assistant.md | 每次使用必读 |
| CMD-LOG日志规范 | L2 | cmd-log-specification.md | 日志格式参考 |
| ha_api.py 脚本 | 工具 | ha_api.py | 脚本参数、调试 |
当用户提到'CI检查'、'提交前检查'、'综合检查'、'ci-check'、'流水线检查'、'提交门禁'、'全量检查'、'跑一下CI'、'pre-commit'、'预检'、'检查所有'时，必须使用此技能。提供项目CI/CD综合检查能力，按标准流水线顺序执行10项核心检查：仓库合规→链接检查→Spec一致性→模式成熟度→文档生成→重复代码检测→阶段守卫日志→SG仪表盘→文件放置校验→.temp生命周期检查。提交前必跑，确保代码符合项目规范。不要手动逐个执行检查脚本——本Skill已按正确顺序编排，并处理了跨平台兼容（Windows用.ps1，Linux/Mac用.sh）。
当用户提到'链接检查'、'检查链接'、'断链'、'链接修复'、'fix links'、'check links'、'验证链接'、'死链'、'链接有效性'、'提交前检查'时，必须使用此技能。提供Markdown链接有效性检查与自动修复能力：本地文件引用验证、外部URL可达性检测、file:///绝对路径转相对路径、相对路径层级自动校正。不要手动查找断链——本Skill封装了缓存机制、并发检测、自动修复和dry-run预览，是提交前质量门禁的核心工具。
当用户提到'原子化收尾'、'finalize atomization'、'文档拆分完成'、'文件移动后处理'、'断链修复导航更新'、'一键收尾'、'重构完成后整理'时，必须使用此技能。原子化/文件移动/目录重构后的一键收尾工具：自动断链修复→导航表更新→Spec看板刷新→验证摘要。不要手动逐个执行后处理步骤——本Skill封装了正确的执行顺序和dry-run预览机制，是文档原子化工作流的标准最后一步。
当用户提到'萃取'、'extraction'、'模式沉淀'、'萃取模式'、'模式入库'、'沉淀为模式'、'可复用模式'、'更新模式库'、'生成模式文档'时，必须使用此技能。提供标准化的模式萃取流程：案例收集→本质抽象→结构化模板→反模式提炼→迁移验证→入库。不要手动组织萃取流程——本Skill封装了六步标准萃取法、反模式对等原则和可迁移性验证。替代旧的pattern-extraction-cmd（v1.0.0）。
当用户提到'知识图谱'、'knowledge graph'、'概念关系可视化'、'交互式知识图谱'、'节点关系网络'、'生成知识图谱'、'可视化知识库'、'概念网络'、'knowledge graph config'时，必须使用此技能。从结构化Markdown文档集（术语表/文档索引/时间线等）自动提取节点和关系，生成交互式vis-network HTML知识图谱。支持TOML声明式配置和Python API两种方式，内置节点去重、孤立节点检测、类型筛选、可信度分级显示。不要手动拼接vis-network代码——本Skill封装了表格解析、关系构建、HTML模板渲染和自包含输出，确保产出质量可预测。
当用户提到'mermaid'、'流程图'、'时序图'、'状态图'、'画个图'、'图表'、'架构图'、'思维导图'、'ER图'、'类图'、'甘特图'、'饼图'、'UML图'、'可视化流程'、'画流程图'、'mermaid图'、'可视化'、'流程可视化'时，必须使用此技能。提供标准化的Mermaid图表创建、检查、修复流程，引导完成从设计→编码→检查→修复→验证→交付的完整闭环。不要手写Mermaid代码绕过本Skill——本Skill封装了安全编码六规则、模板选择、自动检查修复流程，确保图表质量可预测。