# Lobster-HomeAgent（龙虾家庭AI管家）

> **English documentation: [README.en.md](README.en.md)**

> ## ⚠️ 强制说明：这是测试版本，请酌情使用
>
> 当前版本 **`v0.1.0-alpha.1` 是测试版本**：只完成了方案的第一阶段，
> 且**从未在真实 Home Assistant 上验证过**（所有测试都跑在内置的模拟环境上）。
>
> **请勿直接用于真实家庭，更不要依赖它做安全相关的判断。**
> 这个软件会向真实设备下发控制指令，一次误判就可能造成后果。
> 燃气、门锁、安防等安全相关设备**默认已被策略拒绝**，
> 但请不要为了"试试看"去放开它们——那是本项目明确不负责的范围。
>
> 使用前请先读 [DISCLAIMER.md](DISCLAIMER.md)（免责声明与安全警告），
> 自行评估风险后酌情决定是否使用。**作者不对使用后果负责。**
> 强烈建议先用 `HA_DRY_RUN=true` 预演模式观察一段时间。
>
> 开发者：**YeXiaoYe** ｜ 联系：**zqjqyq123@qq.com**

基于 OpenClaw 二次开发、MCP 协议驱动、对接 Home Assistant 的全屋 AI 家庭管家。
本仓库是**能力层**：把 Home Assistant 的全屋设备能力，以 MCP 服务 + OpenClaw 插件两种形式暴露给 Agent，
并内置安全策略——**只控制家电类设备**（灯、窗帘、影音、空调等）；
燃气、阀门、门锁、安防等安全相关设备**默认直接拒绝**，不交给 AI。

> 只完成方案「第 1-2 个月：基础链路验证」阶段，详见[已知限制](#已知限制重要)。

授权模式为**个人使用免费、企业商用收费**（PolyForm Noncommercial 1.0.0）——
源码可见，但**不是** OSI 认证的开源项目，详见[许可证](#许可证)。

## 当前进度

| 方案阶段 | 内容 | 状态 |
| --- | --- | --- |
| 第 1-2 月 | 基础链路验证：Agent 对接 Home Assistant，聊天控制设备 | ✅ 已完成 |
| 第 3-4 月 | 语音层：离线唤醒、ASR、声纹识别 | ⏳ 待开发 |
| 第 5-6 月 | 场景 Skill：回家 / 离家 / 睡眠 / 安防 | ⏳ 待开发 |
| 第 7-8 月 | 本地多模态、上下文压缩、模型混合路由 | ⏳ 待开发 |
| 第 9-10 月 | 一键部署脚本、文档、Bug 修复 | ⏳ 待开发 |

第一阶段已实现并通过测试的能力：

- **设备控制**：查询实体、查状态、调服务、场景激活、模板统计、历史查询，共 10 个工具。
- **安全策略（范围控制）**：只控制家电类设备。燃气 / 阀门 / 门锁 / 警报 / 安防面板 / 热水器 /
  门窗类 cover **默认直接拒绝**，模型连执行入口都拿不到；无法识别的敏感设备走
  一次性令牌二次确认；`shell_command` 等能执行任意命令的 domain 一律拒绝。
  支持预演模式与 domain 黑白名单，全部规则可配置。
- **两种接入方式**：MCP stdio 服务器（方案里的「MCP 服务层」）与 OpenClaw 原生插件。
- **无硬件开发**：内置 Mock Home Assistant（REST + WebSocket + 区域注册表），没有真设备也能跑通全链路。
- **区域语义**：通过 WebSocket 注册表把「客厅」「主卧」解析成实体，支持自然语言按房间控制。

测试：59 项自动化测试全部通过，含 MCP 协议端到端用例（真起子进程、走完整 JSON-RPC 协议）。

## 已知限制（重要）

请在动手之前先读这一节，**这个版本还不能当作可用的家庭管家**。

| 限制 | 影响 | 说明 |
| --- | --- | --- |
| **未在真实 HA 上验证** | 高 | 所有测试都跑在内置 Mock 上。真实环境的实体命名、区域配置缺失、`device_class` 不规范等情况都可能出问题 |
| **OpenClaw 接入未实测** | 高 | 插件清单与 `openclaw mcp add` 命令是按官方文档写的，还没用真实 CLI 执行过。第一次接入可能需要调整 |
| 语音层完全没有 | 高 | 方案里的离线唤醒、ASR、声纹校验都还没开始，现在只能打字 |
| 没有主动智能 | 中 | 只会「你说什么它做什么」，还不会根据位置/传感器/时间自动执行场景 |
| 没有上下文压缩与模型路由 | 中 | 长对话、隐私数据本地跑、复杂任务上云都还没做 |
| 没有操作审计日志 | 中 | 只有待确认队列，没有 append-only 的操作记录，商用场景的合规需求未满足 |
| 确认队列非持久化 | 低 | 内存或文件实现，进程重启后待确认操作丢失 |

已经做了但没有验证的：断线自动重连、区域过滤、历史查询在真实环境下的表现。

## 故障排查

**`认证失败：HA_TOKEN 无效或已过期`**
长期访问令牌不对或已撤销。在 Home Assistant「个人资料 → 安全性 → 长期访问令牌」重新生成。
注意令牌只在创建时显示一次。

**`无法访问 Home Assistant（...）：fetch failed`**
地址不通。确认 `HA_BASE_URL` 带上了端口（`http://homeassistant.local:8123`），
且本机能访问该地址；HA 默认拒绝跨域以外的直连，但局域网内应当可达。

**Agent 说找不到工具 / 工具列表里没有 `ha_*`**
按顺序检查：`openclaw mcp status --verbose` 看 MCP 服务器是否连接成功；
`openclaw mcp tools lobster-home` 看工具是否注册；
再确认没有同时启用 MCP 与插件（两条路工具同名，同时开会冲突）。

**`ha_list_entities` 的 `area` 参数不生效**
区域信息只能通过 WebSocket 注册表获取。如果 WebSocket 连不上（例如只允许 REST 的反向代理），
工具会降级为忽略 `area` 并在返回里注明原因。检查 `ws://` / `wss://` 是否可达。

**高危设备没有被拒绝，或者想控制的设备被拒绝了**
先确认 `HA_POLICY` 或插件 `policy` 配置没有覆盖掉默认规则——
一旦设置了 `denyDomains` / `confirmDomains` / `denyCoverClasses`，
它会**替换**默认值而不是追加。用 `node dist/cli.js doctor` 可以看到当前生效的规则。

想让某类设备从不允许变成允许，改 `denyDomains`；想从"直接执行"变成"必须确认"，
改 `confirmDomains`。注意安全兜底：即使把 `lock` 从 `denyDomains` 里去掉，
它仍会强制进入确认流程，不会被静默放行。

**想让 Agent 先"空跑"看看它会做什么**
设 `HA_DRY_RUN=true`（插件配置里是 `dryRun: true`），策略照常判定但不会真正下发指令。

**Windows 上路径含空格**
配置 `mcp.servers` 时 `args` 里的路径要写成 JSON 字符串（含转义反斜杠），
用 `openclaw mcp add` 时把整个路径放在引号里。

## 环境要求

- Node.js **≥ 24.16**（用到原生 TypeScript 运行、内置 WebSocket）
- 一个可访问的 Home Assistant 实例（本地部署即可），或使用内置 Mock 免硬件体验

## 一键安装

**Linux / macOS**

```bash
curl -fsSL https://raw.githubusercontent.com/yxy123a/lobster-homeagent/main/install.sh | bash
```

**Windows（PowerShell）**

```powershell
irm https://raw.githubusercontent.com/yxy123a/lobster-homeagent/main/install.ps1 | iex
```

脚本会检查 Node 版本（需 ≥ 24.16）、拉取代码、安装依赖、构建，并在检测到
`openclaw` 命令与 `HA_BASE_URL` / `HA_TOKEN` 时自动注册 MCP 服务。

不想盲跑脚本的话，先把脚本下载下来看一眼再执行：

```bash
curl -fsSL https://raw.githubusercontent.com/yxy123a/lobster-homeagent/main/install.sh -o install.sh
less install.sh          # 看完再执行
bash install.sh
```

常用参数与环境变量：

| | Linux / macOS | Windows |
| --- | --- | --- |
| 指定安装目录 | `--dir /opt/lobster` 或 `LOBSTER_HOME` | `-Dir D:\lobster` 或 `$env:LOBSTER_HOME` |
| 指定版本 | `--ref v0.1.0-alpha.1` | `-Ref v0.1.0-alpha.1` |
| 不注册到 OpenClaw | `--no-register` | `-NoRegister` |
| 装完直接起 Mock 演示 | `--mock` | `-Mock` |
| 卸载 | `--uninstall` | `-Uninstall` |
| 自动注册用 | `HA_BASE_URL` + `HA_TOKEN` | `$env:HA_BASE_URL` + `$env:HA_TOKEN` |

> ⚠️ 安装脚本目前**尚未被任何人实际执行过**（写完之后没跑过，包括作者）。
> 它会在 CI 里做冒烟测试（Linux + Windows 各跑一遍），
> 但第一次在你机器上运行时如果报错，请直接提 issue。

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 构建
npm run build

# 3. 无硬件体验：另开一个终端启动 Mock Home Assistant
npm run mock-ha            # 默认监听 8123，输出 HA_BASE_URL 与 HA_TOKEN

# 4. 用 CLI 验证链路
set HA_BASE_URL=http://127.0.0.1:8123
set HA_TOKEN=mock-token
node dist/cli.js doctor
node dist/cli.js states light
node dist/cli.js call light turn_on light.zhuwo_deng "{\"brightness_pct\":70}"
```

> Linux / macOS 把 `set VAR=value` 换成 `export VAR=value`。
> 仓库里的代码不依赖任何平台特有 API，Windows / Linux / macOS 都能跑。

接入真实 Home Assistant：在 HA 里「个人资料 → 安全性 → 长期访问令牌」新建令牌，
然后设置 `HA_BASE_URL`（如 `http://homeassistant.local:8123`）与 `HA_TOKEN`。

## 接入 OpenClaw

两种方式注册的工具**完全相同**，二选一即可，同时启用会出现重名工具。

### 方式 A：MCP 服务（推荐，对应方案的「MCP 服务层」）

```bash
# Windows (cmd)
openclaw mcp add lobster-home ^
  --command node ^
  --arg "C:\path\to\lobster-homeagent\dist\mcp\server.js" ^
  --env HA_BASE_URL=http://homeassistant.local:8123 ^
  --env HA_TOKEN=<你的长期访问令牌>

# Linux / macOS
openclaw mcp add lobster-home \
  --command node \
  --arg "/home/pi/lobster-homeagent/dist/mcp/server.js" \
  --env HA_BASE_URL=http://homeassistant.local:8123 \
  --env HA_TOKEN=<你的长期访问令牌>

# 验证
openclaw mcp status --verbose
openclaw mcp tools lobster-home
```

等价的 `~/.openclaw/openclaw.json` 配置（两种写法等价，用其中一种即可）：

```json5
{
  mcp: {
    servers: {
      "lobster-home": {
        command: "node",
        args: ["C:\\Users\\as\\lobster-homeagent\\dist\\mcp\\server.js"],
        env: {
          HA_BASE_URL: "http://homeassistant.local:8123",
          HA_TOKEN: "你的长期访问令牌"
        }
      }
    }
  }
}
```

### 方式 B：OpenClaw 插件（进程内，后续挂 Hook 用这个）

```bash
openclaw plugins install -l "C:\path\to\lobster-homeagent" --force
openclaw plugins enable lobster-homeagent
openclaw plugins inspect lobster-homeagent --runtime --json
```

然后在 `~/.openclaw/openclaw.json` 的 `plugins.entries.lobster-homeagent.config` 里填写：

```json5
{
  plugins: {
    entries: {
      "lobster-homeagent": {
        enabled: true,
        config: {
          haBaseUrl: "http://homeassistant.local:8123",
          haToken: "你的长期访问令牌",
          dryRun: false
        }
      }
    }
  }
}
```

> 为什么两条路都留着：MCP 是方案里的架构主干，跨 Agent 通用；
> 插件是进程内的，后续「上下文压缩」「模型混合路由」需要挂 OpenClaw 的
> `before_prompt_build` / `before_compaction` / `agent_end` 等 Hook，只能在插件里做。

## 工具清单

| 工具 | 作用 | 只读 |
| --- | --- | --- |
| `ha_health` | 连接、版本、实体数量与策略自检 | ✅ |
| `ha_list_entities` | 按 domain / 区域 / 关键词列出实体与状态 | ✅ |
| `ha_get_state` | 查单个实体完整状态与属性 | ✅ |
| `ha_list_services` | 查可用服务及参数 | ✅ |
| `ha_call_service` | 控制家电（敏感设备会返回确认令牌，安全设备直接拒绝） | ❌ |
| `ha_confirm_action` | 用户同意后凭令牌执行敏感操作 | ❌ |
| `ha_list_scenes` | 列出场景 | ✅ |
| `ha_activate_scene` | 激活场景 | ❌ |
| `ha_render_template` | Home Assistant 模板只读统计查询 | ✅ |
| `ha_get_history` | 查实体历史状态变化 | ✅ |

## 控制范围与安全策略

**本项目的定位是控制家电，不是看管家里的安全设备。**
燃气、阀门、门锁、警报、安防面板、热水器、门窗类设备默认**直接被拒绝**，
模型连执行入口都拿不到——不是"确认后可用"，而是"不归 AI 管"。

```
模型调用 ha_call_service
        │
        ├── 允许（allow）─────→ 直接执行，返回设备新状态
        │
        ├── 需确认（confirm）──→ 不执行！返回一次性确认令牌与操作摘要
        │                        模型必须把操作复述给用户
        │                        用户明确同意后调用 ha_confirm_action 才真正执行
        │
        └── 拒绝（deny）──────→ 直接拒绝并说明原因，不给确认入口
```

**默认拒绝**（不在本项目控制范围内）：

- 安全相关 domain：`lock`、`valve`、`siren`、`alarm_control_panel`、`gas`、`water_heater`
- 门窗类 `cover`：`device_class` 为 `window` / `door` / `garage` / `gate`
- 命名命中 `燃气`、`阀门`、`总阀`、`门锁`、`报警`、`烟雾` 等规则的实体
  （很多家庭把燃气阀接在 `switch` 上，靠这条兜住）
- 能执行任意命令的 domain：`shell_command`、`python_script`、`command_line`、
  `rest_command`、`hassio`、`homeassistant`、`recorder`、`system_log`

**默认放行**（家电类）：灯光、窗帘（`curtain` / `blind` / `shade` / `shutter`）、
空调、风扇、影音、扫地机、开关、场景、脚本。

**需要确认**：无法识别类型的 `cover`（比如没设 `device_class` 的投影幕布）。
确认令牌一次性、默认 5 分钟有效、可跨进程传递。

> 想让 AI 控制某个安全设备（例如只在你在家时允许开门锁）？
> 把它从 `denyDomains` 移到 `confirmDomains` 即可，行为会变成"每次执行前必须经你确认"。
> 但请先读 [DISCLAIMER.md](DISCLAIMER.md)——**不建议这么做**。

规则可通过配置覆盖，详见 [docs/safety-policy.md](docs/safety-policy.md)。

## 配置项

| 环境变量 | 插件配置项 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `HA_BASE_URL` | `haBaseUrl` | 必填 | Home Assistant 地址 |
| `HA_TOKEN` | `haToken` | 必填 | 长期访问令牌 |
| `HA_TIMEOUT_MS` | `timeoutMs` | 15000 | 单次请求超时 |
| `HA_DRY_RUN` | `dryRun` | false | 预演模式：只判定与回显，不下发指令 |
| `HA_POLICY` | `policy` | 默认策略 | JSON 形式的安全策略覆盖 |
| `LOBSTER_HA_CONFIG` | — | 无 | 指向 JSON 配置文件，优先级高于环境变量 |
| `LOBSTER_HA_CONFIRM_FILE` | — | 系统临时目录 | CLI 的待确认操作队列文件 |

也兼容 `HOMEASSISTANT_URL` / `HASS_URL`、`HOMEASSISTANT_TOKEN` / `HASS_TOKEN` 别名。

## CLI

```bash
node dist/cli.js doctor                     # 连接与策略自检
node dist/cli.js states [domain] [--area 客厅] [--search 关键词]
node dist/cli.js get <entity_id>
node dist/cli.js call <domain> <service> [entity_id] [json]
node dist/cli.js confirm <token>            # 配合上一条完成敏感操作
node dist/cli.js scenes
node dist/cli.js watch [domain]             # 实时订阅状态变化
node dist/cli.js mock-ha [--port 8123]      # 启动内置 Mock HA
```

CLI 的确认队列落在文件里（`LOBSTER_HA_CONFIRM_FILE`），因此 `call` 与 `confirm`
分两条命令也能完成一次需要确认的操作。

## 开发

```bash
npm run typecheck    # tsc --noEmit
npm test             # 59 项测试
npm run build        # 输出到 dist/
```

测试不需要任何硬件（全部跑在内置 Mock 上），任何操作系统都能跑。
仓库配了 GitHub Actions（`.github/workflows/ci.yml`），
在 Ubuntu 与 Windows 上各跑一遍类型检查、测试、构建，
并额外验证构建产物 `dist/mcp/server.js` 能作为 MCP 服务器被真实协议调通——
所以不想在本地装环境的话，推上去让 CI 跑就行。

单独验证构建产物：

```bash
# Windows
set LOBSTER_TEST_MCP_ENTRY=%CD%\dist\mcp\server.js
# Linux / macOS
export LOBSTER_TEST_MCP_ENTRY=$PWD/dist/mcp/server.js

node --test test/mcp-server.test.ts
```

## 目录结构

```
src/
  core/            与 Agent 无关的核心（可被任何前端复用）
    config.ts        配置加载与校验（环境变量 / JSON 文件 / 插件配置）
    policy.ts        风险判定、确认令牌队列（内存版 + 文件版）
    gateway.ts       动作网关：串起策略判定、确认流程与实际执行
    ha-rest.ts       Home Assistant REST 客户端
    ha-ws.ts         WebSocket 客户端、区域注册表、实时状态缓存
    format.ts        面向中文对话的状态格式化
    types.ts         领域类型
    errors.ts        统一错误与可读翻译
  mcp/             MCP 服务层
    tools.ts         10 个工具的定义（MCP 与插件共用同一份规格）
    server.ts        MCP stdio 服务器
  plugin/          OpenClaw 插件适配器（进程内）
  dev/mock-ha.ts   Mock Home Assistant（REST + WebSocket）
  cli.ts           调试 CLI
test/              单元测试与 MCP 协议端到端测试
docs/              架构、安全策略、路线图
.github/           CI 工作流与 issue 模板
```

根目录的说明性文件：

| 文件 | 内容 |
| --- | --- |
| `LICENSE` | PolyForm Noncommercial 1.0.0 协议全文 |
| `DISCLAIMER.md` | **免责声明与安全警告（使用前必读）** |
| `NOTICE` | 版权声明、开发者信息与授权模式摘要 |
| `COMMERCIAL.md` | 什么算商业用途、如何获取商业授权 |
| `CONTRIBUTING.md` | 开发环境、代码约定、贡献者授权声明 |
| `CHANGELOG.md` | 版本变更记录 |
| `install.sh` / `install.ps1` | 一键安装脚本（Linux/macOS 与 Windows） |
| `openclaw.plugin.json` | OpenClaw 插件清单（工具契约与配置 schema） |

## 文档

- [DISCLAIMER.md](DISCLAIMER.md) —— **免责声明与安全警告（使用前必读）**
- [docs/architecture.md](docs/architecture.md) —— 分层架构与关键设计决策
- [docs/safety-policy.md](docs/safety-policy.md) —— 安全策略细则与配置方式
- [docs/roadmap.md](docs/roadmap.md) —— 后续阶段落点（语音层 / 场景 Skill / 模型路由）
- [CHANGELOG.md](CHANGELOG.md) —— 版本变更记录
- [CONTRIBUTING.md](CONTRIBUTING.md) —— 开发环境、代码约定、贡献者授权声明
- [COMMERCIAL.md](COMMERCIAL.md) —— 商业授权说明

## 许可证

本项目采用 **[PolyForm Noncommercial License 1.0.0](LICENSE)**：
个人及非商业用途免费，企业/商业用途需购买授权。

| 用途 | 是否收费 |
| --- | --- |
| 自己家里用、学习研究、非商业开源项目 | 免费 |
| 企业、门店、民宿、公寓、办公等经营性场所 | **需购买授权** |
| 作为产品的一部分交付给客户、对外提供付费服务、硬件预装 | **需购买授权** |

需要说明的是：这**不是**一份 OSI 认证的开源协议，而是「源码可见 + 非商业免费」的授权模式。
之所以这么选，是因为方案里的商业模式要求「企业商用需付费」——
宽松协议（MIT / Apache-2.0）允许企业免费商用，无法支撑收费；
AGPL-3.0 虽然能迫使企业开源自己的修改，但企业只要愿意开源就依然可以免费商用。
PolyForm Noncommercial 让「个人免费、商用付费」成为可执行的授权条款。
详见 [COMMERCIAL.md](COMMERCIAL.md)。

## 贡献

欢迎帮忙测试和提 issue。当前阶段最有价值的贡献是**真实 Home Assistant 下的兼容性反馈**
——所有测试都跑在 Mock 上，真实环境的问题只有你能发现。

提 PR 前请先读 [CONTRIBUTING.md](CONTRIBUTING.md)，
其中包含一条**贡献者授权声明**（因为项目是双授权模式，
提交 PR 即表示同意你的贡献可用于商业授权版本）。

## 开发者与联系方式

| | |
| --- | --- |
| 开发者 | **YeXiaoYe** |
| 邮箱 | **zqjqyq123@qq.com** |
| 项目主页 | https://github.com/yxy123a/lobster-homeagent |
| 问题反馈 | https://github.com/yxy123a/lobster-homeagent/issues |

> 再次强调：**当前是测试版本（v0.1.0-alpha.1），请酌情使用**。
> 使用前请务必阅读 [DISCLAIMER.md](DISCLAIMER.md)。
> 如果你在真实 Home Assistant 上跑通了，或者遇到了问题，欢迎邮件或提 issue 告诉我
> ——这正是当前阶段最需要的信息。