homey

核心用法

Homey CLI 是一款专为 Athom Homey 智能家居平台设计的命令行控制工具，支持通过本地局域网（LAN/VPN）或云端 API 两种方式连接并操控智能设备。用户需先配置认证令牌（本地 API Key 或云 Token），即可执行设备查询、状态控制、场景触发等操作。核心命令包括 homeycli devices 查看设备列表、、homeycli device <名称> on/off 开关设备、、homeycli flow trigger <场景名>> 触发自动化流程，以及 homeycli snapshot 获取全屋状态快照供 AI 解析。工具采用模糊匹配技术，支持设备名称的近似搜索，大幅降低语音或文本指令的识别门槛。

显著优点

1. 双模式灵活部署：本地模式延迟极低、隐私性佳，适合家庭内网；云模式支持远程 VPS 托管，满足 headless 场景需求。
2. AI 友好输出：所有命令支持 --json 参数，输出结构化数据便于 AI Agent 解析和自动化决策。
3. 模糊匹配体验：内置 Levenshtein 距离算法，容忍拼写错误和简称，如 "livng light" 可正确匹配 "Living Room Light"。
4. 官方 API 背书：底层依赖 Athom 官方 homey-api 包（v3.15.0），协议兼容性和长期维护有保障。
5. 细粒度控制能力：不仅支持开关操作，还可精确调节亮度、色温、目标温度、锁状态等数十种设备能力值。

潜在缺点与局限性

1. 硬件生态绑定：仅兼容 Athom Homey 系列（Pro/Cloud/Bridge），无法对接米家、HomeKit 等其他平台。
2. Token 管理门槛：用户需自行从 Homey Web App 或 Developer Tools 获取 API 密钥，对非技术用户存在学习成本。
3. 网络依赖性强：本地模式要求运行环境与 Homey 同网络或 VPN 可达；云模式依赖 Athom 云服务可用性。
4. 无图形界面：纯 CLI 交互，虽适合自动化脚本，但临时调试不如官方 App 直观。
5. 社区维护风险：目前为个人开发者项目（T3 来源），长期更新承诺弱于企业级产品。

适合的目标群体

• 智能家居极客：偏好代码和自动化脚本管理全屋设备的用户。
• AI Agent 开发者：需要将 Homey 设备控制能力集成到自定义 AI 助手的工程师。
• 远程运维场景：通过 VPS 或云服务器异地管理家庭设备的管理员。
• Homey 深度用户：已部署 Homey 生态，希望突破官方 App 功能边界的高级玩家。

使用风险

1. Token 泄露风险：API 密钥以明文形式存储于 ~/.homey/config.json，虽文件权限设为 0o600，但 root 用户或备份泄露仍可能导致未授权访问。
2. 网络中断影响：本地模式下 mDNS 发现失败或 IP 变更会导致连接中断；云模式受 Athom 服务稳定性制约。
3. 误操作风险：模糊匹配虽便利，但极端情况下可能误匹配相似名称设备（如 "Bedroom Light" 与 "Bedroom Light Strip"），建议关键操作前先用 --json 确认设备 ID。
4. 依赖项更新：homey-api 等依赖若出现破坏性更新，可能导致功能异常，需关注版本锁定状态。

Homey Skill：让 AI 成为你的智能家居管家

Homey Skill 是一个专为 Athom Homey 智能家居平台设计的命令行工具，它通过简洁的指令集，让 AI 助手能够直接控制家中的灯光、恒温器、门锁、传感器等各类设备，还能触发预设的自动化流程，实现真正的语音或自然语言交互式智能家居管理。

核心用法

该 Skill 的核心是通过 homeycli 命令行工具与 Homey 设备进行交互。它支持两种连接模式，满足不同场景需求：

• 本地模式（推荐）：当 AI 助手和 Homey 设备处于同一局域网时，可以通过局域网 API 密钥直接连接，响应速度最快，数据完全保存在本地。
• 云端模式：适用于在远程或云服务器上运行 AI 助手的场景，通过 Homey 官方云 API 的令牌进行远程控制。

用户只需简单配置后，就可以让 AI 利用 homeycli 执行各类操作，例如：

• 设备控制：开关灯、调节亮度、设置恒温器温度、改变灯光颜色等。命令类似 homeycli device "卧室灯" on。
• 状态查询：获取家中温度、湿度、传感器状态，或者一次性生成包含所有设备信息的快照。
• 自动化触发：启动或触发已创建的场景和流程，如“晚安模式”或“离家模式”。
• 模糊匹配：此工具具备强大的模糊匹配能力，即使拼写不完全准确或只记得部分设备名，也能精准找到目标设备，极大地提升了语音交互的容错率。

显著优点

• 本地化控制，隐私安全：优先推荐本地连接模式，设备指令和数据仅在家庭局域网内传输，无需经过外部服务器，最大程度保护了用户家庭数据的隐私。
• 强大的 AI 交互友好性：原生支持 JSON 格式输出，方便 AI 程序解析和理解。同时，其独特的模糊匹配算法（支持子串和纠错），有效解决了语音识别转文字时常见的设备名拼写错误问题，让 AI 对智能家居的控制更准确、更流畅。
• 全面的设备与功能覆盖：不仅支持灯泡、插座等简单开关，还深度集成了调节亮度、色温、颜色以及读取传感器数据等高级功能，几乎可以控制 Homey 生态系统下的所有设备类型和功能。
• 安全透明的代码实现：经过专业安全机构认证，代码规范，无任何有害行为。它对认证令牌的存储采用了严格的文件权限（读写权限仅限用户本人），并拒绝处理非标准的令牌格式，有效防止了凭证泄露。

潜在缺点或局限性

• 生态锁定：该 Skill 严格依赖于 Athom Homey 智能家居平台，无法直接控制其他品牌如小米、华为等的智能家居产品，除非它们已通过某种方式桥接进了 Homey 系统中。
• 社区信任度有待提升：该工具由个人开发者维护，GitHub 仓库创建时间较新，目前缺少社区活跃度与使用反馈。尽管通过了严格的人工安全审核，但对于高度敏感的大型部署，这可能是一个需要考量的因素。
• 配置要求一定的技术门槛：初始配置过程（如获取本地 API 密钥或云令牌）需要用户具备基础的网络和技术知识，这可能对部分普通用户造成些许困扰。

适合的目标群体

• 智能家居重度用户和发烧友：已深度投资 Athom Homey 平台，希望将 AI 语音助理能力与全屋智能深度结合的用户。
• 追求隐私和本地化控制的用户：不信任将所有家庭数据上传至云端的用户，他们可以通过本地模式，享受既智能又私密的家居自动化体验。
• AI 应用开发者与集成商：正在构建个人 AI 助理或智能家居集成解决方案的开发者，Homey Skill 提供了一个成熟、稳定的家居控制后端模块。

使用风险提示

• 网络依赖：本地控制依赖于家庭网络的稳定性；云端控制则依赖于外网连接和 Athom 云服务的可用性。
• 单一故障点：整个控制集中于 Homey 控制中枢，一旦 Homey 设备本身出现故障，所有自动化控制将失效。
• 权限管理：任何拥有该 Skill 和令牌访问权限的用户或程序都可以完全控制你的智能家居。务必保护好配置文件，避免泄露。
• 更新风险：作为个人开发者项目，未来的更新频率和维护的持续性可能存在不确定性。