Home Assistant saiu do núcleo: o que acontece com a sua configuração

Você pede ao Hermes para diminuir a luz da sala e recebe de volta unknown platform: homeassistant. Você não mudou nada nem apagou nada — apenas rodou hermes update na noite passada.

É assim que o “enxugamento do núcleo” se parece do lado do usuário: um adaptador de plataforma que antes vinha dentro do Hermes foi movido para o catálogo de plugins. A boa notícia é que a mudança veio com uma migração automática e, para a maioria das pessoas, nada na configuração precisa mudar. Veja o que saiu, como a migração roda e o que fazer se ela não funcionar.

O que de fato saiu do núcleo

O Home Assistant costumava fazer parte do kernel: plugins/platforms/homeassistant/ (o adaptador de plataforma do gateway) mais tools/homeassistant_tool.py (a ferramenta do agente), junto com os toolsets homeassistant / hermes-homeassistant, o enum Platform.HOMEASSISTANT, a linha de habilitação por env HASS_TOKEN, o extra pip homeassistant e um monte de entradas codificadas espalhadas pela saída de dump, o resumo de setup, o cartão de plataforma do dashboard e as listas de ferramentas do ACP.

O #132469 removeu tudo isso. O recurso agora vive no plugin de catálogo homeassistant (repo NousResearch/hermes-homeassistant, fixado em 2.0.1 na revisão). Na sua árvore atualizada, plugins/platforms/ não tem mais um diretório homeassistant.

Sua configuração continua igual

Esta é a melhor parte: o plugin foi feito para ser mesmos nomes, mesmas chaves de configuração, mesmas variáveis de ambiente.

  • HASS_TOKEN e HASS_URL não mudaram;
  • platforms.homeassistant na sua configuração do gateway não mudou;
  • os nomes de ferramenta ha_* não mudaram.

Em outras palavras, não há nenhuma chave nova para aprender. A única coisa que você precisa confirmar é que o plugin está de fato instalado.

Como a migração automática funciona

A versão adiciona uma migração genérica de “saiu do núcleo” em hermes_cli/left_core_migration.py, e seu design vale a leitura porque resolve a parte mais difícil de qualquer divisão de plugin: migrar usuários existentes sem uma thread de suporte.

A tabela é LEFT_CORE, e cada linha indica qual plugin de catálogo instalar, além de um predicado somente leitura para “este home usava o recurso”. Neste momento há exatamente uma linha:

LEFT_CORE: tuple[LeftCoreFeature, ...] = (
    LeftCoreFeature(
        plugin="homeassistant", label="Home Assistant", in_use=homeassistant_in_use,
        unchanged="HASS_TOKEN/HASS_URL, platforms.homeassistant and the ha_* tool names are unchanged",
        secret_env=("HASS_TOKEN",), private_env=("HASS_URL",),
        toolsets=("homeassistant",), off_platforms=("acp", "webhook"), platform="homeassistant",
        enable_env=("HASS_TOKEN",), channel_env_prefixes=("HASS_",),
    ),
)

O teste “este home usava?” é somente leitura: HASS_TOKEN no .env do home (essa única variável habilitava tanto o adaptador quanto as ferramentas), a plataforma habilitada na configuração do gateway (o legado gateway.json ou os blocos gateway.platforms / platforms / gateway.homeassistant, onde o último enabled explícito vence), ou homeassistant selecionado nos toolsets do home. Um HASS_TOKEN vindo do ambiente do processo (systemd, Docker) também conta.

As instalações acontecem em três momentos:

  1. hermes update — instala para todo home de perfil que compartilha o venv e usava o recurso;
  2. início do agente — tenta de novo uma vez por processo para o home ativo (usuários do desktop atualizam pelo app e nunca rodam hermes update, então é assim que eles recebem), respeitando security.allow_lazy_installs;
  3. início do gateway — também tenta de novo uma vez e enfileira o resultado para o primeiro turno do agente daquele home.

As instalações passam pelo caminho normal do catálogo no pin revisado, então a kill list, as restrições de dependência e a etapa de habilitação se aplicam. Um detalhe atencioso: o consentimento de dependência é não assistido para essas linhas, porque o recurso vinha no núcleo e seus usuários já aceitaram aquelas dependências na época.

Mais duas regras anti-aborrecimento:

  • após uma tentativa falha (não está no catálogo, inacessível, erro de instalação), as tentativas de inicialização pulam a linha por STARTUP_RETRY_SECONDS — então uma máquina offline paga uma ida e volta de rede, não uma a cada hermes chat, enquanto o hermes update sempre tenta de novo;
  • um home é auto-instalado no máximo uma vez, registrado como _left_core_installed em seu config.yaml. Se você remover o plugin depois, essa é a sua escolha e ela permanece.

Confirmando depois da atualização

hermes update
hermes plugins list | grep homeassistant

Se o plugin aparecer (habilitado), pronto. Se ele não foi instalado — digamos, security.allow_lazy_installs: false, ou a máquina está offline — instalar manualmente funciona igualmente bem:

hermes plugins install homeassistant
hermes plugins enable homeassistant

Observe que plugins install resolve o pin revisado a partir do catálogo de plugins, e não de um repositório arbitrário, então você não está puxando código não revisado. Para saber como as capacidades de plugin são isoladas depois de instaladas, veja modo de isolamento de host de plugin e o guia do catálogo de plugins.

A tabela vai crescer

O LEFT_CORE é genérico; o Home Assistant é apenas a primeira linha. Combinado com as verificações de revisão e cadeia de suprimentos do catálogo (veja CI e cadeia de suprimentos do catálogo de plugins), é razoável esperar que mais capacidades embutidas sigam esse caminho: removidas do núcleo e depois instaladas automaticamente para os usuários que as tinham.

Para os usuários, este é um formato mais saudável — um kernel menor, atualizações mais rápidas e adaptadores de plataforma que podem lançar em seu próprio ritmo em vez de esperar a próxima minor do Hermes. O custo é que “embutido” não significa mais “sempre presente”, então uma olhada rápida nos seus plugins de plataforma após uma atualização é um hábito que vale manter.

Resumindo

  • A plataforma de gateway do Home Assistant e a ferramenta homeassistant saíram do núcleo e agora são um plugin oficial do catálogo;
  • o hermes update o instala para perfis que o usavam, com uma nova tentativa no início do agente e do gateway que respeita security.allow_lazy_installs;
  • chaves de configuração, variáveis de ambiente e nomes de ferramenta não mudaram — se o hermes plugins list o mostra, a migração funcionou;
  • se ele não foi instalado, hermes plugins install homeassistant é o caminho manual, e mais entradas são esperadas em LEFT_CORE.