DomoAI

通用代理化家庭自动化运行时，具有语义设备模型、多适配器组合及一个通用 MCP 接口。

开发环境

本项目使用 uv 和 Python 3.12。

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

运行时依赖包括 MCP Python SDK、Pydantic、Home Assistant HTTP/WebSocket 客户端、用于可选 Zigbee2MQTT 适配器的 aiomqtt、JSON Schema 验证和 OR-Tools。本地 SQLite 持久化使用 Python 标准库。开发工具通过 uv 的默认 dev 依赖组安装。

要添加或更新依赖，编辑 pyproject.toml 并重新生成锁文件：

uv lock
uv sync

本地 MCP 服务器

语义 MCP 服务器可通过 stdio 启动。如果没有 Home Assistant 设置，则使用确定性夹具：

uv run domoai-mcp

示例主机配置：

{
  "mcpServers": {
    "domoai": {
      "command": "uv",
      "args": ["run", "domoai-mcp"],
      "cwd": "/path/to/DomoAI"
    }
  }
}

相同命令可注册到 Claude Code、Codex 或其他兼容的 MCP 客户端。

统一 MCP 界面

单一 domoai-mcp 服务器通过同一 MCP 会话暴露发现、状态、能源上下文、策略感知的计划验证/执行以及仅提议的 OR-Tools 工具 validate_scenario、optimize_scenario 和 explain_solution。在 Claude Code、Codex 或任何其他支持本地 stdio 的兼容 MCP 客户端中仅注册一个服务器：

{
  "mcpServers": {
    "domoai": {
      "command": "uv",
      "args": ["run", "domoai-mcp"],
      "cwd": "/path/to/DomoAI"
    }
  }
}

OR-Tools 仍然是内部提议/验证/解释层。它不能执行设备、批准计划或调用适配器，并且没有第二个公共的 OR-Tools MCP 端点。

可移植的 optimize-home-energy 技能通过一个 mcp 角色路由所有 DomoAI 操作。其参考工作流通过确定性进程内夹具进行本地验证：

uv run pytest -q tests/contract/test_skill_contract.py
uv run pytest -q tests/integration/test_energy_skill_workflow.py

工作流对语义读取、提议、解释和计划验证使用相同的连接，并且绝不执行 execute_plan 以外的操作。敏感计划暂停以等待操作员明确批准。

对于能源感知场景，可移植的 v2 过程在调用仅提议的优化器之前，通过 mcp.get_energy_context 读取完整的类型化上下文。上下文将电价和太阳能预测对齐到固定时间范围，并可能包含一个电池配置文件。CP-SAT 返回成本、峰值进口和太阳能自消费证据以及每个时段的能量平衡；它绝不调用物理适配器。上下文失败、修订不匹配、不可行性或求解器超时会在验证和执行之前停止。确定性提供者和专注的验收命令由仓库合约和集成测试覆盖。

实时能源数据的一次性太阳能配置文件

每当请求能源上下文时，会自动收集 OMIE 电价和 Open-Meteo 预报。仅需一次性提供物理安装元数据。复制示例，将其占位值替换为逆变器或安装商数据，并将运行时指向该文件：

cp config/solar-profile.example.json config/solar-profile.json
export DOMOAI_ENERGY_LIVE=1
export DOMOAI_TARIFF_PROVIDER=omie
export DOMOAI_SOLAR_PROVIDER=open_meteo
export DOMOAI_SOLAR_PROFILE_PATH=config/solar-profile.json
uv run domoai-mcp

配置文件是严格的、版本化的且无凭证。在使用结果进行优化之前，必须包含真实的安装值；示例中的马德里值仅用于说明格式。旧的独立 DOMOAI_SOLAR_* 变量仍可作为互斥的兼容性回退使用。

通用提供者 SDK

未来的 Home Assistant、逆变器和 MQTT 集成必须在到达语义运行时之前，将其来源特定的身份和有效负载转换为 Provider SDK v1 边界。SDK 重用 DomoAI 的标准 DeviceType、Capability 和 SourceRef 模型，并将提供者分为遥测和命令角色：

external provider
      ↓
ProviderManifest + DeviceDescriptor + Measurement
      ↓
ProviderRegistry (stable order, safe diagnostics)
      ↓
canonical runtime / StateStore / MCP / OR-Tools

提供者命令仅携带有限语义参数和幂等键。它们不会绕过 PlanService、策略验证或 AdapterPort。第一个具体实现是 HomeAssistantProvider。它重用经过身份验证的 REST/WebSocket 客户端，当注册表元数据可用时按 Home Assistant device_id 分组实体，并仅暴露显式的实体/能力指标映射。它是对经典 HomeAssistantAdapter 的补充；运行时工厂仅在显式启用 DOMOAI_HOME_ASSISTANT_PROVIDER=1 时选择它。同一提供者对象注册在 ProviderRegistry 中，并由现有的 AdapterPort 包装，因此 DeviceRegistry、StateStore、计划执行和 MCP 保持一条语义路径和一个 Home Assistant 客户端。 请参阅 docs/adapter-sdk.md 和 docs/contracts.md 了解公共边界。

实时 Home Assistant 运行时

Para desarrollo local sin hardware, el laboratorio virtual reproducible está en dev/lab/README.md y su arranque mínimo cubre Mosquitto/fake Zigbee2MQTT y PyModbus. Home Assistant, Matter Server y KNX Virtual/ETS permanecen como perfiles manuales opt-in.

La ruta recomendada para operar ese laboratorio es el runner explícito:

uv run domoai-lab up
uv run domoai-lab status
uv run domoai-lab smoke

El smoke usa únicamente fixtures locales de Home Assistant, MQTT/Zigbee2MQTT, Modbus, Matter y KNX; no inventa gateways, tokens ni commissioning. Los smoke tests live siguen separados y requieren sus servicios y variables DOMOAI_* reales.

组合根节点在未配置实时源时选择确定性夹具，对于单个源选择直接适配器，对于两个或更多完整源配置选择组合运行时。按如下方式配置 Home Assistant：

export DOMOAI_HOME_ASSISTANT_URL="http://home-assistant.local:8123"
export DOMOAI_HOME_ASSISTANT_TOKEN="<long-lived-access-token>"
export DOMOAI_HOME_ASSISTANT_PROVIDER="1"
export DOMOAI_HOME_ASSISTANT_MAPPING_PATH="config/home-assistant-mappings.json"
export DOMOAI_DATABASE_PATH="data/domoai.sqlite3"
uv run domoai-mcp

提供者模式是可选加入的。未启用时，选择经典 HomeAssistantAdapter 以保持兼容性。如果启用，需要 URL/令牌对，并且可选严格 v1 映射文档可以使能源角色显式化：

{
  "schema_version": "v1",
  "metric_mappings": {
    "sensor.pv_power": {"power": "energy.pv.power"},
    "sensor.grid_power": {"power": "energy.grid.power"}
  }
}

运行时对 REST 服务调用进行身份验证，将计划、结果和脱敏审计事件持久化到 SQLite，并在后台运行适配器事件消费者。当前支持的写入映射包括灯/开关电源和开关操作、灯光亮度、窗帘位置/打开/关闭/停止以及气候目标温度。不完整的 URL/令牌对会在启动前被拒绝。令牌作为秘密配置读取，永远不会包含在设备、命令、结果或审计负载中。

Provider SDK 路径可以独立于运行时工厂进行测试：

provider = HomeAssistantProvider(
    HomeAssistantClient(base_url, token),
    metric_mappings={
        "sensor.pv_power": {"power": "energy.pv.power"},
        "sensor.battery_soc": {"battery": "battery.soc"},
    },
)

只有映射的传感器能力才会成为标准能源指标。客户端还会通过 WebSocket 读取 Home Assistant 已启用的实体注册表（当状态负载不包含 device_id 时）；注册表身份在提供时保留，绝不会从名称或区域推断。

移除 DOMOAI_HOME_ASSISTANT_PROVIDER 会回退到经典适配器，且不影响面向代理的 MCP 界面。提供者路径由确定性夹具覆盖。可选加入的实时提供者-运行时冒烟测试在真实 Home Assistant 实例上验证同一路径，但不执行命令：

uv run pytest -q tests/integration/test_home_assistant_provider_smoke.py

它需要真实的 URL/令牌对，并将令牌保留在仓库外部。

实时 Zigbee2MQTT 运行时

原生 Zigbee2MQTT 适配器是可选加入的，支持有界 v1 配置文件：灯/开关电源、灯光亮度、温度、湿度和占用状态。与 Home Assistant 或其他源一起配置：

export DOMOAI_ZIGBEE2MQTT_URL="mqtt://mqtt-broker.local:1883"
export DOMOAI_ZIGBEE2MQTT_BASE_TOPIC="zigbee2mqtt"
export DOMOAI_MQTT_TIMEOUT_SECONDS="5"
export DOMOAI_MQTT_USERNAME="domoai"
export DOMOAI_MQTT_PASSWORD="<mqtt-password>"
uv run domoai-mcp

Zigbee2MQTT 可以与 Home Assistant 或其他已配置的源一起运行。适配器消费 Zigbee2MQTT 桥接器/设备主题，并通过现有的计划、策略和执行器边界仅发布映射的设备 /set 命令。配对、移除、OTA、组、桥接器管理和任意 MQTT 发布不会被暴露。

实时 Matter Server 运行时

原生 Matter 适配器将 Matter Server 作为控制器边界，并连接到其兼容的 WebSocket 端点。与 Home Assistant、Zigbee2MQTT 或其他源一起配置：

export DOMOAI_MATTER_SERVER_URL="ws://matter-server.local:5580/ws"
export DOMOAI_MATTER_TIMEOUT_SECONDS="5"
uv run domoai-mcp

适配器在发现之前验证服务器模式范围，保留 node:<node_id>/endpoint:<endpoint_id> 源引用，并仅暴露有界 v1 灯/开关电源和亮度配置文件以及只读的温度、湿度和占用状态。配网、织物管理、OTA、组、供应商集群和任意属性操作仍在面向代理的边界之外。实时 Matter 冒烟测试是可选加入的；夹具测试不需要 Matter 服务器或硬件。

实时 KNX/IP 运行时

原生 KNX 适配器使用显式映射文件，而不是从任意组流量推断设备。其有界 v1 配置文件支持灯和开关电源、灯光亮度以及只读的温度、湿度和占用状态。与其他物理源一起配置：

export DOMOAI_KNX_GATEWAY_HOST="knx-gateway.local"
export DOMOAI_KNX_CONFIG_PATH="config/knx.json"
export DOMOAI_KNX_TIMEOUT_SECONDS="5"
uv run domoai-mcp

映射文件声明每个实体、语义能力、状态组地址、命令组地址和 DPT。未知字段、格式错误的地址、不支持的 DPT 和可写传感器映射会在启动时被拒绝。KNX/IP 隧道是可选的，并且可以与其他已配置的适配器共存；夹具测试使用内存传输，不需要网关或硬件。ETS 导入、配网、路由、安全凭据、任意组值操作、场景和额外的 xknx 设备配置文件不包含在 v1 中。

实时 Modbus TCP 运行时

原生 Modbus 适配器使用显式的 v1 映射，包括单元 ID、寄存器区域、基于零的 PDU 偏移和标量编码。它支持灯/开关电源、灯光亮度以及只读的温度、湿度和占用状态。与其他物理源一起配置：

export DOMOAI_MODBUS_HOST="modbus-controller.local"
export DOMOAI_MODBUS_PORT="502"
export DOMOAI_MODBUS_CONFIG_PATH="config/modbus.json"
export DOMOAI_MODBUS_TIMEOUT_SECONDS="5"
export DOMOAI_MODBUS_POLL_INTERVAL_SECONDS="5"
uv run domoai-mcp

映射是严格的，不会扫描或推断设备。未知字段、模糊的 40001 样式地址、不支持的编码、可写传感器和不安全命令会被拒绝。Modbus TCP 是可选加入的，可以与 Home Assistant、Zigbee2MQTT、Matter Server 和 KNX 共存。RTU/ASCII、TLS、扫描、供应商功能码和任意寄存器读/写不在 v1 范围内。夹具测试使用内存传输，不需要控制器或硬件。

多适配器身份和路由

运行时遵循 Home Assistant 的设备/实体区分：一个物理源设备可能暴露多个源实体，而 DomoAI 呈现一个具有能力级路由的标准设备。稳定的源标识符和连接可以在名称或区域更改时保留身份；需要显式的 canonical_id 来链接来自不同适配器的贡献。命令在执行前解析到确切的源实体。不明确、未知或不可用的路由会失败关闭，因此运行时绝不会静默地将命令发送到另一个协议或实体。

此行为不需要实时网关、代理或控制器。确定性多适配器夹具覆盖了组合、部分故障、拓扑、精确路由和零写入安全性：

uv run pytest -q tests/contract/test_multi_adapter_runtime.py \
  tests/integration/test_multi_adapter_runtime.py \
  tests/performance/test_multi_adapter_targets.py

已验证的本地验证

2026-08-17，仓库通过了仓库测试套件覆盖的单元、适配器、发现、计划、MCP 合约、优化、性能、Home Assistant 执行、KNX 和 Modbus 夹具、运行时组合、OMIE 和 Open-Meteo 提供者场景。 经典 Home Assistant 适配器冒烟测试通过了本地 Docker 实验室；本地 Zigbee2MQTT 和 Modbus 冒烟测试通过；只读的 OMIE 和 Open-Meteo 公共网络冒烟测试通过可选配置。Matter 发现和 KNX/IP 仍然是可选的，因为它们需要已配网的 Matter 节点或可访问的 KNX 网关和映射。

本地启动命令是：

uv run domoai-mcp

质量门禁是：

uv run pytest -q
uv run ruff check .
uv run mypy src
uv lock --check

无实时凭据的最新完整套件结果为 318 passed, 8 skipped，无警告。跳过的测试是可选加入的 Matter Server、KNX/IP 和其他需要外部节点、网关或服务配置的实时案例；确定性夹具覆盖仍然启用。单独的实时结果：Zigbee2MQTT/Modbus 2 passed，OMIE/Open-Meteo 2 passed，Home Assistant 经典适配器 1 passed，以及 Home Assistant Provider 运行时桥接 1 passed。FastMCP 兼容性接缝使已知的 pydantic_settings 字段不完整警告保持在 MCP 合约之外，而无需全局抑制警告。

适配器和公共合约指南位于 docs/adapter-sdk.md 和 docs/contracts.md。