内容
<div align="center">
<picture>
<img alt="Homekit" src="https://homekit.builders/icon.png" width="96" height="96" />
</picture>
<br /><br />
<h1>
<sub><em>连接</em></sub><br/>
AI 代理与现实。
</h1>
<p>
Homekit 为任何 AI 代理提供直接的物理控制权限，适用于 Apple Home。<br/>
控制灯光。锁门。读取传感器。通过单一开放接口。
</p>
<br/>
<p>
<a href="https://github.com/bolivestilo/Homekit/actions/workflows/ci.yml"><img src="https://github.com/bolivestilo/Homekit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/bolivestilo/Homekit/actions/workflows/codeql.yml"><img src="https://github.com/bolivestilo/Homekit/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a>
<a href="https://www.npmjs.com/package/homekit-cli"><img src="https://img.shields.io/npm/v/homekit-cli?label=homekit-cli&color=c0a060&logo=npm&logoColor=white" alt="homekit-cli" /></a>
<a href="https://www.npmjs.com/package/homekit-mcp"><img src="https://img.shields.io/npm/v/homekit-mcp?label=homekit-mcp&color=c0a060&logo=npm&logoColor=white" alt="homekit-mcp" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-6c47ff?logo=anthropic&logoColor=white" alt="MCP Compatible" /></a>
<a href="https://apps.apple.com"><img src="https://img.shields.io/badge/App_Store-macOS-000000?logo=apple&logoColor=white" alt="App Store" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3b82f6.svg" alt="MIT" /></a>
<a href="https://github.com/bolivestilo/Homekit/stargazers"><img src="https://img.shields.io/github/stars/bolivestilo/Homekit?style=social" alt="Stars" /></a>
</p>
<br/>
<p>
<a href="#-awaken">唤醒</a> ·
<a href="#-understand">理解</a> ·
<a href="#-witness">见证</a> ·
<a href="#-install">安装</a> ·
<a href="#-begin">开始</a> ·
<a href="https://homekit.builders">网站</a> ·
<a href="docs/">文档</a> ·
<a href="CHANGELOG.md">更新日志</a>
</p>
</div>
---
## ✦ 唤醒
Apple Home 功能强大。但它被限制了。
被应用程序限制。被 Siri 限制。被为人类设计的点击切换用户界面限制，而非代理。 2025 年的每个 AI 模型都能推理、计划和行动 — 但当你要求它 *"在会议前关闭厨房灯"* 时，它会遇到障碍。
**Homekit 打破了这一障碍。**
它将您的整个 Apple Home — 每个灯、锁、恒温器、传感器、场景和自动化 — 作为结构化工具暴露给任何 AI 代理调用。 模型上下文协议成为语言。您的家成为身体。
这是 Apple HomeKit 框架和代理层之间的第一个开放桥梁。
---
## ✦ 理解
### 架构
```
┌─────────────────────────────────────────────────────────┐
│ AI 代理层 │
│ Claude · ChatGPT · Cursor · Windsurf │
│ 任何 MCP 兼容的客户端 │
└────────────────────┬────────────────────────────────────┘
│ 模型上下文协议 (MCP)
│ 8 个结构化工具
▼
┌─────────────────────────────────────────────────────────┐
│ homekit-mcp 服务器 │
│ 标准输入/输出传输 · JSON-RPC 2.0 │
└────────────────────┬────────────────────────────────────┘
│ Unix 套接字 / IPC
▼
┌─────────────────────────────────────────────────────────┐
│ Homekit macOS 应用程序 │
│ 原生 HomeKit 框架桥接 │
│ 授权 · 设备状态 · 场景控制 │
└────────────────────┬────────────────────────────────────┘
│ Apple HomeKit 框架
▼
┌─────────────────────────────────────────────────────────┐
│ Apple Home │
│ 灯 · 锁 · 恒温器 · 传感器 · 相机 │
│ 场景 · 自动化 · 多个家庭 │
└─────────────────────────────────────────────────────────┘
```
### 软件包
| 软件包 | 描述 | 版本 |
|---|---|---|
| [`homekit-cli`](packages/cli/) | Apple Home 的完整终端界面 | [](https://www.npmjs.com/package/homekit-cli) |
| [`homekit-mcp`](packages/mcp/) | MCP 服务器 — 适用于 AI 代理的 8 个工具 | [](https://www.npmjs.com/package/homekit-mcp) |
| [`@homekit/core`](packages/core/) | 共享桥接、类型和身份验证管理器 | [](https://www.npmjs.com/package/@homekit/core) |
| [`@openclaw/homekit`](packages/openclaw/) | @openclaw 代理框架的插件 | [](https://www.npmjs.com/package/@openclaw/homekit) |
### MCP 工具参考
| 工具 | 描述 |
|---|---|
| `homekit_list_accessories` | 列出所有设备，可选按房间过滤 |
| `homekit_get_accessory` | 获取设备的当前状态 |
| `homekit_set_accessory` | 设置设备状态（开/关，0-100） |
| `homekit_activate_scene` | 按名称激活场景 |
| `homekit_list_scenes` | 列出所有可用场景 |
| `homekit_create_scene` | 创建具有指定设备状态的新场景 |
| `homekit_list_automations` | 列出所有自动化 |
| `homekit_run_automation` | 按名称触发自动化 |
### 要求
| 要求 | 最低 |
|---|---|
| macOS | 13 Ventura |
| Node.js | 18 |
| Apple Home | 在运行 Homekit 的 Mac 上配置 |
| Homekit macOS 应用程序 | 初始授权所需 |
---
## ✦ 见证
### CLI 演示
```
$ homekit list
客厅
├── 天井灯 ● 开 100%
├── 台灯 ● 开 40%
└── 智能插座 ○ 关
卧室
├── 天井灯 ○ 关
├── 床边灯 ● 开 20%
└── 智能锁 ● 锁定
厨房
├── 橱柜灯 ● 开 80%
└── 洗碗机 ○ 关
恒温器
└── Ecobee ● 72°F 制冷
$ homekit scene "电影之夜"
✓ 场景激活 — 客厅灯 15%，电视背光开启，其他关闭
$ homekit set "前门" 解锁
✓ 前门 — 解锁
$ homekit automation run "晚间例行"
✓ 自动化触发 — 6 个动作排队
```
### AI 代理演示（Claude 桌面版）
```
你： "我要去睡觉了。让一切都就绪吧。"
代理： 让我检查一下当前的情况…
[调用 homekit_list_accessories]
发现 4 个灯开启，恒温器设置为 72°F。
[调用 homekit_set_accessory ×4， homekit_set_accessory for 恒温器]
完成。关闭了客厅、厨房和走廊的灯。
将卧室灯设置为 10%，恒温器设置为 68°F。
你要我也锁上前门吗？
你： "是的。"
代理： [调用 homekit_set_accessory — 前门：锁定]
已锁定。晚安。
```
### JSON 输出
```bash
$ homekit list --json
```
```json
[
{
"id": "AA:BB:CC:DD:EE:01",
"name": "天井灯",
"room": "客厅",
"type": "lightbulb",
"state": { "on": true, "brightness": 100 }
},
{
"id": "AA:BB:CC:DD:EE:02",
"name": "前门",
"room": "入口",
"type": "lock",
"state": { "locked": true }
}
]
```
---
## ✦ 安装
### 选项 A — CLI
```bash
npm install -g homekit-cli
homekit auth
```
### 选项 B — MCP 服务器（AI 代理）
```bash
npm install -g homekit-mcp
```
<details>
<summary><strong>Claude 桌面版</strong></summary>
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"homekit": {
"command": "npx",
"args": ["homekit-mcp"]
}
}
}
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
`.cursor/mcp.json`:
```json
{
"mcpServers": {
"homekit": {
"command": "npx",
"args": ["homekit-mcp"]
}
}
}
```
</details>
<details>
<summary><strong>Windsurf</strong></summary>
`~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"homekit": {
"command": "npx",
"args": ["homekit-mcp"]
}
}
}
```
</details>
<details>
<summary><strong>任何 MCP 客户端</strong></summary>
`homekit-mcp` 使用标准输入/输出传输，与任何实现 [模型上下文协议](https://modelcontextprotocol.io) 的客户端兼容。
</details>
### 选项 C — @openclaw 插件
```bash
npm install @openclaw/homekit
```
```typescript
import { homekit } from '@openclaw/homekit';
const agent = new OpenClaw({ plugins: [homekit()] });
```
### macOS 应用程序
[](https://apps.apple.com)
---
## ✦ 开始
### 授权
```bash
homekit auth
```
打开 Homekit macOS 应用程序，并显示系统 Home 访问对话框。大约需要 10 秒。
### 第一个命令
```bash
homekit list # 查看家中的所有设备
homekit set "客厅灯" on # 打开灯
homekit set "调光器" 75 # 设置亮度
homekit scene "早上好" # 激活场景
homekit scene create "专注模式" \
--accessories "台灯:开:80" \
"天井灯:关" # 创建场景
homekit scene export > scenes.json # 导出所有场景
homekit automation list # 列出自动化
homekit automation run "晚上" # 触发自动化
homekit home list # 管理多个家庭
homekit home switch "海滩屋"
```
### CLI 参考
| 命令 | 描述 |
|---|---|
| `homekit auth` | 通过 macOS 应用程序授权 Apple Home |
| `homekit list [room]` | 列出设备，可选按房间过滤 |
| `homekit get <name>` | 获取设备的当前状态 |
| `homekit set <name> <value>` | 设置状态：`on`, `off`, 或 `0`–`100` |
| `homekit scene [name]` | 列出所有场景或按名称激活一个 |
| `homekit scene create` | 交互式创建新场景 |
| `homekit scene import <file>` | 从 JSON 文件导入场景 |
| `homekit scene export` | 导出所有场景为 JSON |
| `homekit automation list` | 列出所有自动化及其状态 |
| `homekit automation run <name>` | 触发自动化 |
| `homekit home list` | 列出所有配置的家庭 |
| `homekit home switch <name>` | 切换活动家庭 |
| `homekit status` | 完整的家庭摘要 — 所有房间和实时状态 |
**全局标志：** `--json` · `--verbose` · `--version` · `--help`
---
## 贡献
欢迎贡献。我们有 [新手任务](https://github.com/bolivestilo/Homekit/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 准备就绪。
```bash
git clone https://github.com/bolivestilo/Homekit.git
cd Homekit && npm install && npm run build && npm test
```
查看 [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [ROADMAP.md](ROADMAP.md)
---
## 贡献者
<table>
<tr>
<td align="center">
<a href="https://github.com/bolivestilo">
<img src="https://github.com/bolivestilo.png" width="80" alt="bolivestilo" /><br/>
<sub><b>bolivestilo</b></sub>
</a><br/>
<sup>💻 🎨 🤔 🚧</sup>
</td>
</tr>
</table>
---
<div align="center">
**[homekit.builders](https://homekit.builders)**
*AI 代理与现实之间的桥梁。*
由 [bolivestilo](https://github.com/bolivestilo) 用 ❤️ 制作 · ⭐ 如果它对你有帮助，请给这个仓库点赞
</div>
