Инструменты
Инструменты — это MCP-сервер homer (tools/speaker/homer_mcp.py) на компьютере с колонкой. Каждый инструмент — узкое действие с проверкой входных данных. Оболочки, доступа к файлам и произвольных сетевых запросов в нём нет.
Сервер работает на трёх уровнях:
- Колонка — Haiku, быстрые дела;
- Поручения — умная модель, которой колонка отдаёт сложное (по умолчанию Opus);
- Claude Code — ваш собственный Claude Code в терминале, если подключить сервер.
Список
| Инструмент | Что делает | Колонка | Поручения | Claude Code |
|---|---|---|---|---|
homer_help | Справка по Homer: где какая настройка приложения, как устроены колонка, мозги, журнал | ✓ | ✓ | ✓ |
homer_plan | План дома так, как его видит Homer: комнаты, вещи, группы света | — | ✓ | ✓ |
plan_add ⚠ | Ставит устройство из Home Assistant на план в комнату — тогда его видят приложение, Алиса и «Свет во всём доме» | — | ✓ | ✓ |
switch_to_light ⚠ | Выключатель, к которому подключена лампа, делает светильником: в HA — «Сменить тип» (switch_as_x), на плане — светильник | — | ✓ | ✓ |
memory_save ⚠ / memory_forget ⚠ | Постоянная память головы: «запомни», «забудь» | ✓ | ✓ | ✓ |
memory_read | Что голова помнит постоянно | — | ✓ | ✓ |
camera_look | Кадр с камеры дома: «что видно», «есть ли кто на кухне». Людей по лицу не узнаёт | ✓ | ✓ | ✓ |
house_state | Состояния устройств из Home Assistant, с поиском по имени или комнате | — | ✓ | ✓ |
ha_call | Сервис Home Assistant для одного устройства: свет, выключатели, сцены, шторы, климат, вентиляторы, медиа, автоматизации, пылесосы | —¹ | ✓ | ✓ |
zigbee_devices | Устройства Zigbee-сети: модель, производитель, прошло ли знакомство | — | ✓ | ✓ |
zigbee_pair ⚠ | Открывает сеть для новых устройств (до 254 с) и ждёт, кто подключится | — | ✓ | ✓ |
zigbee_stop_pairing ⚠ | Закрывает сеть | — | ✓ | ✓ |
zigbee_rename ⚠ | Переименовывает устройство в мосте и в Home Assistant | — | ✓ | ✓ |
music_play | Яндекс Музыка на колонках компьютера или на Станции | ✓ | ✓ | ✓ |
music_control | Стоп, следующий трек, громкость, что играет | ✓ | ✓ | ✓ |
timer_set / timer_list / timer_cancel | Таймеры и напоминания голосом | ✓ | ✓ | ✓ |
say | Сказать фразу колонкой | — | ✓ | ✓ |
diag | Живы ли Home Assistant, сервер дома, колонка, speaches и мост Zigbee | — | ✓ | ✓ |
delegate ⚠ | Поручение старшей модели | ✓ | — | — |
¹ Устройствами из снимка колонка управляет и без ha_call: действия приходят прямо в её ответе. ⚠ — каждый вызов записывается в журнал.
Разрешённые сервисы Home Assistant
| Домен | Сервисы |
|---|---|
light, switch, input_boolean | turn_on, turn_off, toggle |
scene | turn_on |
cover | open_cover, close_cover, stop_cover, set_cover_position |
climate | set_temperature, set_hvac_mode, turn_on, turn_off |
fan | turn_on, turn_off, set_percentage |
media_player | turn_on, turn_off, media_play, media_pause, media_next_track, volume_set, volume_mute |
automation | turn_on, turn_off, trigger |
vacuum | start, stop, return_to_base |
button | press — поворот камеры, «громче», «канал вперёд» у телевизора |
select | select_option — канал, вход телевизора |
number | set_value — громкость телевизора |
Колонке и поручениям правка конфигурации, удаление устройств и перезапуск Home Assistant недоступны: это умеют только инструменты настройки ниже, и только в вашем Claude Code.
Настройка дома (только Claude Code)
| Инструмент | Что делает | Колонка | Поручения | Claude Code |
|---|---|---|---|---|
ha_registry | Реестры HA: комнаты, этажи, метки, устройства, сущности | — | ✓ | ✓ |
ha_integrations | Интеграции, их состояние и то, что HA нашёл в сети сам | — | ✓ | ✓ |
ha_template | Выборка шаблоном Jinja | — | ✓ | ✓ |
ha_check | Проверка конфигурации, открытые проблемы, версия | — | ✓ | ✓ |
ha_logs | Ошибки и предупреждения журнала HA | — | ✓ | ✓ |
ha_area ⚠ | Завести, переименовать, удалить комнату, этаж, метку HA | — | — | ✓ |
ha_entity_update ⚠ | Имя, entity_id, комната, выключить, скрыть. При смене entity_id перечисляет, кто на него ссылался | — | — | ✓ |
ha_device_update ⚠ | Имя и комната устройства, выключить | — | — | ✓ |
ha_flow ⚠ | Мастер HA: добавить интеграцию или поменять её параметры, шаг за шагом | — | — | ✓ |
ha_integration ⚠ | Перезапустить, выключить, включить, удалить интеграцию | — | — | ✓ |
ha_config_item ⚠ | Автоматизации, скрипты и сцены, заведённые в интерфейсе HA | — | — | ✓ |
ha_service ⚠ | Любой сервис HA без белого списка, с ответом; перезагрузка HA | — | — | ✓ |
ha_ws ⚠ | Сырая команда WebSocket API HA; auth/* закрыты | — | — | ✓ |
ha_onboard ⚠ | Первый запуск свежего HA: владелец, место, язык, токен | — | — | ✓ |
ha_connect ⚠ | Проверить токен и переключить сервер на другой HA | — | — | ✓ |
homer_connect ⚠ | Подключиться к серверу дома владельцем; выдать ему токен HA | — | — | ✓ |
homer_settings ⚠ | Мозги Хомера, имена колонки, микрофоны, голос | — | — | ✓ |
homer_packages ⚠ | Пакеты HA homer_*.yaml: записать с автооткатом, подтвердить, откатить | — | — | ✓ |
homer_invite ⚠ | Приглашение нового устройства в Homer | — | — | ✓ |
Что закрыто и почему:
- Секреты в переписку не попадают. Пароли и токены инструменты пишут в
secrets/и в ответе называют только файл. Пароль интеграции в шаге мастера передают ссылкойsecret:<файл>:<ключ>— значение подставит сам сервер. - Пинкод, полный доступ и ключи облаков
homer_settingsне меняет: это только руками владельца в приложении. - Пакеты записываются с автооткатом: если за
confirm_withinсекунд (по умолчанию 300) не прийти сconfirm, сервер дома вернёт прежнюю версию сам. - Автоматизации из пакетов
ha_config_itemне трогает — сохранение там завело бы дубль вautomations.yaml.
Телевизор, камеры и группы Алисы
Колонка видит не только вещь с плана, но и её соседей по устройству в Home Assistant: у телевизора — громкость, канал, вход, «без звука» и паузу, у камеры — кнопки поворота. Служебное (защита от детей, таймер реле) в снимок не попадает. Камеры попадают всегда; «Хомер, кто на кухне?» — колонка берёт кадр camera_look и описывает его одной фразой.
Вещи зовут так же, как их зовёт Алиса: имена и группы из приложения Яндекса сервер дома забирает раз в десять минут. «Хомер, выключи мониторы» — группа «Мониторы» из приложения Яндекса раскрывается в три розетки. Устройство, которого нет в Home Assistant (подключено к Алисе другим навыком), колонка передаёт Алисе той же фразой.
Выключатель как лампа и «Свет во всём доме»
«Свет во всём доме» (light.homer_house) — это все светильники light.*, стоящие на планах дома: сервер дома ставит им метку homer_house, и группа собирает состав по ней сама. Выключатель (switch.*) в неё не входит, даже если к нему подключена лампа, — его сначала делают светильником.
Голосом: «Хомер, сделай выключатель на кухне лампой и добавь его в свет во всём доме». Колонка поручает это старшей модели, та вызывает switch_to_light: в Home Assistant появляется light.… с тем же именем (сам switch скрывается), на плане выключатель заменяется светильником, а если его на плане не было — светильник ставится в названную комнату. Через минуту лампа входит во «весь дом». Каждый шаг виден в журнале.
Руками то же: Home Assistant → Настройки → Устройства и службы → Помощники → «Сменить тип устройства» → выключатель → «Свет»; потом в Homer поставить новый светильник на план (правка плана → «Приборы и вещи»).
Включить и выключить
Настройки → Колонка → Мозги Хомера → Инструменты. У каждого инструмента по флажку на уровень.
Можно:
- выключить любой инструмент на любом уровне. Например, запретить своему Claude Code искать Zigbee-устройства или отключить поручения — снять
delegateу колонки; - вернуть всё как было кнопкой «По умолчанию».
Нельзя:
- включить инструмент там, где его не бывает (прочерк);
- добавить новый инструмент из настроек. Инструменты — это код, и каждый сам проверяет свои входные данные. Новое умение из существующих инструментов добавляется навыком.
Колонка подхватывает изменения в течение минуты, поручения — со следующего поручения, Claude Code — при следующем запуске сессии. Каждое изменение набора записывается в журнал: кто и что включил или выключил.
Как написать новый инструмент
Для разработчиков: инструмент — функция Python в tools/speaker/homer_mcp.py с аннотациями типов и docstring. Описание из docstring модель видит как инструкцию.
def vacuum_room(room: str) -> str:
"""Убрать одну комнату роботом-пылесосом: room — «кухня», «спальня»."""
...Затем:
- добавить функцию в список уровня (
VOICEилиFULL) в конце файла; - описать её в каталоге
AGENT_TOOLSсервера дома (sidecar/src/alice/agent.ts): название, описание, уровни, опасность; - для колонки — добавить подсказку в
TOOL_HINTSвspeaker.py.