DomoAI

Универсальная агентская среда для домашней автоматизации с семантической моделью устройств, многодаптерной композицией и единым общим интерфейсом MCP.

Среда разработки

Этот проект использует uv и Python 3.12.

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

Зависимости времени выполнения включают MCP Python SDK, Pydantic, HTTP/WebSocket клиенты Home Assistant, aiomqtt для опционального адаптера Zigbee2MQTT, проверку JSON Schema и OR-Tools. Локальное постоянство SQLite использует стандартную библиотеку Python. Инструменты разработки устанавливаются через стандартную группу зависимостей dev uv.

Чтобы добавить или обновить зависимость, отредактируйте pyproject.toml и перегенерируйте lockfile:

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 предоставляет обнаружение, состояние, энергетический контекст, проверку/выполнение планов с учетом политик и инструменты OR-Tools только для предложений validate_scenario, optimize_scenario и explain_solution через одну и ту же сессию MCP. Зарегистрируйте ровно один сервер в Claude Code, Codex или любом другом совместимом MCP клиенте, поддерживающем локальный stdio:

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

OR-Tools остается внутренним слоем предложений/проверки/объяснения. Он не может выполнить устройство, утвердить план или вызвать адаптер, и не существует второго публичного OR-Tools MCP эндпоинта.

Портативный навык optimize-home-energy направляет каждую операцию DomoAI через одну роль mcp. Его эталонный рабочий процесс проверяется локально с помощью детерминированных внутрипроцессных фикстур:

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 клиент, группирует сущности по device_id Home Assistant, когда доступны метаданные реестра, и предоставляет только явные отображения метрик сущностей/возможностей. Она остается дополнительной к классическому HomeAssistantAdapter; фабрика времени выполнения выбирает ее только при явном включении DOMOAI_HOME_ASSISTANT_PROVIDER=1. Тот же объект провайдера регистрируется в ProviderRegistry и оборачивается существующим AdapterPort, так что DeviceRegistry, StateStore, выполнение планов и MCP сохраняют один семантический путь и одного клиента Home Assistant. Смотрите docs/adapter-sdk.md и docs/contracts.md для публичной границы.

Живая среда выполнения Home Assistant

Для локальной разработки без аппаратного обеспечения воспроизводимая виртуальная лаборатория находится в dev/lab/README.md, и ее минимальный запуск охватывает Mosquitto/fake Zigbee2MQTT и PyModbus. Home Assistant, Matter Server и KNX Virtual/ETS остаются опциональными ручными профилями.

Рекомендуемый способ работы с этой лабораторией — явный runner:

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

Smoke-тест использует только локальные фикстуры Home Assistant, MQTT/Zigbee2MQTT, Modbus, Matter и KNX; не выдумывает шлюзы, токены или commissioning. Живые smoke-тесты остаются отдельными и требуют реальных сервисов и переменных DOMOAI_*.

Корень композиции выбирает детерминированную фикстуру, если не настроен ни один живой источник, прямой адаптер для одного источника или составную среду выполнения для двух или более полных конфигураций источников. Настройте 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/токен отклоняется до запуска. Токены читаются как секретная конфигурация и никогда не включаются в полезные нагрузки устройств, команд, результатов или аудита.

Путь SDK провайдера может быть опробован независимо от фабрики времени выполнения:

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

Только отображенные возможности датчиков становятся каноническими энергетическими метриками. Клиент также читает реестр включенных сущностей Home Assistant через WebSocket, когда полезные нагрузки состояния не включают device_id; идентичность реестра сохраняется при предоставлении, никогда не выводится из имен или зон.

Удаление DOMOAI_HOME_ASSISTANT_PROVIDER возвращает к классическому адаптеру без изменения ориентированной на агента поверхности MCP. Путь провайдера покрыт детерминированными фикстурами. Опциональный живой smoke провайдера-времени выполнения проверяет тот же маршрут на реальном экземпляре 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 мощности света/выключателя и яркости, а также состояние температуры, влажности и занятости только для чтения. Commissioning, управление fabric, OTA, группы, вендорские кластеры и произвольные операции с атрибутами остаются за пределами границы, ориентированной на агента. Живые smoke-тесты 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, commissioning, маршрутизация, безопасные учетные данные, произвольные операции с групповыми значениями, сцены и дополнительные профили устройств xknx не включены в v1.

Живая среда выполнения Modbus TCP

Родной адаптер Modbus использует явное отображение v1 идентификаторов устройств, областей регистров, нулевых смещений 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, покрытые набором тестов репозитория. Smoke-тест классического адаптера Home Assistant прошел в локальной Docker-лаборатории; локальные smoke-тесты Zigbee2MQTT и Modbus прошли; и smoke-тесты OMIE и Open-Meteo только для чтения в публичной сети прошли с опциональной конфигурацией. Обнаружение Matter и KNX/IP остаются опциональными, поскольку требуют commissioning узла Matter или доступного шлюза KNX и отображения.

Команда локального запуска:

uv run domoai-mcp

Контрольные точки качества:

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

Последний результат полного набора без живых учетных данных: 318 пройдено, 8 пропущено, без предупреждений. Пропуски — это опциональные Matter Server, KNX/IP и другие живые случаи без их внешнего узла, шлюза или конфигурации сервиса; покрытие детерминированных фикстур остается включенным. Отдельные живые результаты: Zigbee2MQTT/Modbus 2 пройдено, OMIE/ Open-Meteo 2 пройдено, классический адаптер Home Assistant 1 пройдено и мост времени выполнения провайдера Home Assistant 1 пройдено. Шов совместимости FastMCP удерживает известное предупреждение pydantic_settings о неполном поле вне контрактов MCP без глобального подавления предупреждений.

Руководство по адаптеру и публичному контракту находится в docs/adapter-sdk.md и docs/contracts.md.