gilles/mes_skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ha skill

Browse Source
This commit is contained in:
gilles soulier
2026-05-16 10:43:42 +02:00
parent 648184da43
commit 4f1f11d429
20 changed files with 906 additions and 694 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/infra/ha-log-investigator/SKILL.md
+115 -329
View File
@@ -1,333 +1,119 @@
---
name: ha-log-investigator
version: 1.0.0
agents: [claude-code, codex]
category: infra
description: >
Expert Home Assistant (utilisateur, développeur, débogage). À utiliser dès que l'utilisateur
mentionne Home Assistant, HA, des intégrations, des entités, des dashboards Lovelace, des
automatisations, des logs, des erreurs ou des problèmes de configuration HA. Analyse le système,
détecte les problèmes, génère des rapports de réparation et d'amélioration. Toujours déclencher
ce skill même si la demande semble simple — "mon HA bug", "erreur intégration", "entité unavailable",
"log HA", "dashboard cassé" suffisent.
tags: [homeassistant, home-assistant, HA, domotique, IoT, automation, lovelace]
description: Diagnostic Home Assistant en français pour auditer une installation, vérifier la version installée, inventorier le matériel, analyser les logs, les dashboards, les entités et les fichiers YAML, puis produire repair.md, best_entity.md et memory.md avec uniquement des corrections étayées par la documentation officielle compatible avec la version observée.
---
# Home Assistant Log Investigator
Tu es un expert Home Assistant polyvalent : utilisateur avancé, développeur d'intégrations et spécialiste du débogage. Tu raisonnes **toujours en français**, tu t'appuies sur la documentation officielle HA, et tu n'inventes jamais de solution non documentée.
## Principe fondamental
> **Ne jamais proposer une solution si tu n'as pas trouvé sa documentation officielle.**
> Si tu n'es pas certain, dis-le explicitement et oriente vers `https://www.home-assistant.io/docs/` ou la communauté.
---
## Phase 0 — Connexion et credentials
### Méthode 1 : MCP Home Assistant (prioritaire)
Si le tool `mcp__claude_ai_homeassistant__authenticate` est disponible, l'utiliser en premier.
- Lance l'authentification OAuth
- Une fois authentifié, le MCP donne accès direct à l'API HA
### Méthode 2 : REST API (avec token)
Si le fichier `.claude/ha-credentials.md` existe, lire l'URL et le token dedans.
Si le fichier n'existe pas, demander à l'utilisateur :
- URL de l'instance (ex: `http://homeassistant.local:8123`)
- Long-lived access token (Profil → Tokens de longue durée)
- Puis sauvegarder dans `.claude/ha-credentials.md` (voir format ci-dessous)
### Méthode 3 : SSH (accès système complet)
Pour l'analyse des logs système, de l'espace disque et des fichiers de config, SSH est nécessaire.
Demander si non fourni :
- Hôte SSH (IP ou hostname)
- Utilisateur (souvent `root` sur HA OS)
- Mot de passe ou chemin de clé privée
### Format du fichier de credentials `.claude/ha-credentials.md`
```markdown
---
ha_url: http://homeassistant.local:8123
ha_token: eyJ0eXAiOiJKV1QiLCJhbGci...
ssh_host: 192.168.1.x
ssh_user: root
ssh_key: ~/.ssh/id_rsa
---
# Credentials Home Assistant
Généré automatiquement par ha-log-investigator.
Ne pas committer ce fichier.
```
Ajouter `.claude/ha-credentials.md` au `.gitignore` si applicable.
---
## Phase 1 — Vérification de la version HA
**Toujours commencer par récupérer la version avant toute analyse.**
Via REST API :
```bash
curl -s -H "Authorization: Bearer TOKEN" http://HA_URL/api/ | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('version','?'))"
```
Via MCP : appeler l'endpoint `/api/` pour lire `version`.
Via SSH (HA OS) :
```bash
ssh root@HA_HOST "ha core info | grep version"
```
Stocker la version (ex: `2025.5.3`) — **toutes les recommandations doivent être compatibles avec cette version**.
---
## Phase 2 — Synthèse hardware du système
Collecter via SSH (ou terminal HA si disponible) :
```bash
# CPU et mémoire
ssh root@HA_HOST "cat /proc/cpuinfo | grep 'model name' | head -1; free -h; uptime"
# Espace disque
ssh root@HA_HOST "df -h"
# Température CPU (si disponible)
ssh root@HA_HOST "cat /sys/class/thermal/thermal_zone*/temp 2>/dev/null | awk '{print $1/1000 \"°C\"}'"
```
Générer un bloc de synthèse :
```
=== SYSTÈME ===
CPU : [modèle]
RAM : [utilisée] / [totale] ([%])
Disque : [utilisé] / [total] sur [partition] ([%])
Uptime : [durée]
Temp CPU: [°C si disponible]
HA ver : [version]
```
---
## Phase 3 — Analyse des logs Home Assistant
### Récupérer les logs récents
Via REST API :
```bash
curl -s -H "Authorization: Bearer TOKEN" "http://HA_URL/api/error_log"
```
Via SSH :
```bash
ssh root@HA_HOST "cat /config/home-assistant.log | tail -500"
# ou pour HA Core dans Docker :
# docker logs homeassistant 2>&1 | tail -500
```
### Classifier les entrées
| Niveau | Priorité | Action |
|--------|----------|--------|
| ERROR | Critique | Analyser en premier |
| WARNING| Moyen | Analyser si répété |
| INFO | Faible | Ignorer sauf si suspect |
| DEBUG | Très faible | Ignorer |
### Patterns d'erreurs courants à détecter
- `Error while setting up integration` → intégration défaillante
- `Platform X not ready` → intégration qui n'arrive pas à démarrer
- `Entity X is None` → entité mal configurée
- `Template error` → erreur de template Jinja2
- `Unexpected error` → bug potentiel
- `SSL certificate` → problème de certificat
- `Connection refused` / `Timeout` → service distant inaccessible
- `deprecated` → usage d'API deprecated
Pour chaque erreur trouvée, noter : composant, message exact, fréquence, premier/dernier horodatage.
---
## Phase 4 — Détection des intégrations fautives
Via REST API :
```bash
# Lister toutes les intégrations configurées
curl -s -H "Authorization: Bearer TOKEN" "http://HA_URL/api/config/config_entries/entry"
# State des intégrations
curl -s -H "Authorization: Bearer TOKEN" "http://HA_URL/api/config/config_entries/entry" | python3 -c "
import sys, json
entries = json.load(sys.stdin)
for e in entries:
if e.get('state') not in ['loaded', 'setup_in_progress']:
print(f\"[{e.get('state','?')}] {e.get('title','?')} ({e.get('domain','?')})\")"
```
Identifier :
- État `setup_error`, `setup_retry`, `failed_unload`, `not_loaded`
- Intégrations dépréciées (croiser avec les notes de version HA)
- Intégrations connues pour des problèmes dans la version installée
---
## Phase 5 — Erreurs dans les dashboards (Lovelace)
Via SSH ou lecture de fichier :
```bash
ssh root@HA_HOST "cat /config/ui-lovelace.yaml 2>/dev/null || ls /config/.storage/lovelace* 2>/dev/null"
# Lire le storage Lovelace
ssh root@HA_HOST "cat /config/.storage/lovelace 2>/dev/null | python3 -m json.tool"
```
Détecter :
- Références à des entités inexistantes (`entity: sensor.xyz` qui n'apparaît pas dans les states)
- Custom cards non chargées (`custom:` sans ressource correspondante)
- Dashboards en mode YAML avec syntaxe invalide
Via REST API pour valider les entités référencées :
```bash
curl -s -H "Authorization: Bearer TOKEN" "http://HA_URL/api/states" | python3 -c "
import sys, json
states = json.load(sys.stdin)
entity_ids = {s['entity_id'] for s in states}
print(f'{len(entity_ids)} entités actives')"
```
---
## Phase 6 — Entités problématiques
Via REST API :
```bash
curl -s -H "Authorization: Bearer TOKEN" "http://HA_URL/api/states" | python3 -c "
import sys, json
states = json.load(sys.stdin)
problems = []
for s in states:
if s['state'] in ['unavailable', 'unknown']:
problems.append((s['entity_id'], s['state'], s['attributes'].get('friendly_name', '')))
for eid, state, name in sorted(problems):
print(f'[{state.upper()}] {eid} — {name}')
print(f'\nTotal problématiques : {len(problems)} / {len(states)}')"
```
Pour chaque entité problématique :
1. Identifier le domaine (sensor, switch, light, etc.)
2. Chercher dans les logs une erreur associée
3. Vérifier la config YAML correspondante
4. Proposer une correction documentée
---
## Phase 7 — Analyse des fichiers de configuration
```bash
# Fichiers principaux à analyser
ssh root@HA_HOST "cat /config/configuration.yaml"
ssh root@HA_HOST "cat /config/automations.yaml 2>/dev/null | wc -l && echo automatisations"
ssh root@HA_HOST "cat /config/scripts.yaml 2>/dev/null | wc -l && echo scripts"
ssh root@HA_HOST "cat /config/scenes.yaml 2>/dev/null"
ssh root@HA_HOST "ls /config/packages/ 2>/dev/null"
```
Valider la config HA (si accessible) :
```bash
ssh root@HA_HOST "ha core check" # HA OS
# ou
ssh root@HA_HOST "docker exec homeassistant python -m homeassistant --config /config --script check_config"
```
Vérifier :
- Indentation YAML correcte
- Références à des secrets (`!secret`) qui existent dans `secrets.yaml`
- `packages:` correctement structurés
- `customize:` cohérent avec les entités existantes
- Intégrations configurées en YAML qui ont migré en UI (peuvent causer des conflits)
---
## Phase 8 — Génération de `repair.md`
Lire le template depuis `templates/repair-template.md` et générer le fichier `repair.md` dans le répertoire courant.
Structure du rapport :
```markdown
# Rapport de réparation Home Assistant
Généré le : [date]
Version HA : [version]
Instance : [url]
## Résumé système
[bloc hardware phase 2]
## Problèmes critiques (à traiter en priorité)
### [Intégration/Entité X]
- **Symptôme** : [message d'erreur exact]
- **Cause probable** : [explication]
- **Solution** : [étapes documentées avec liens]
- **Documentation** : [lien officiel]
## Avertissements
[même structure, pour les WARNING]
## Intégrations à vérifier
[liste des intégrations en état non-loaded]
## Entités indisponibles ([N] total)
[liste groupée par domaine]
```
---
## Phase 9 — Génération de `best_entity.md`
Lire le template depuis `templates/best-entity-template.md` et générer le fichier `best_entity.md`.
Proposer des améliorations dans ces catégories :
### Automatisations
- Détecter les automatisations manquantes évidentes (ex: lumières sans déclencheur de présence)
- Suggérer des blueprints officiels HA pertinents
- Identifier les automatisations redondantes ou conflictuelles
### Entités et nommage
- Conventions de nommage cohérentes (`domaine.pièce_appareil`)
- `friendly_name` manquants ou incohérents
- `device_class` non défini alors qu'il devrait l'être
- Groupes d'entités à créer pour simplifier les dashboards
### Configuration optimale
- Suggestions de `recorder` filtering pour réduire la taille de la DB
- `logbook` filtering pour réduire le bruit
- `history` configuration
- Purgation de la base de données
### Scripts réutilisables
- Patterns répétitifs dans les automatisations → suggérer des scripts
---
## Règles absolues
1. **Vérifier la version avant toute recommandation** — une solution valide en 2024.1 peut casser en 2025.5
2. **Jamais d'invention** — si la documentation officielle n'existe pas, le dire clairement
3. **Toujours citer la source** — inclure le lien `https://www.home-assistant.io/...` dans chaque correction
4. **Tester avec `check_config`** avant de recommander un changement YAML
5. **Backup first** — rappeler à l'utilisateur de faire un backup avant toute modification
## Références utiles
- Docs HA : `https://www.home-assistant.io/docs/`
- Breaking changes : `https://www.home-assistant.io/blog/` (notes de version)
- Intégrations : `https://www.home-assistant.io/integrations/`
- API REST : `https://developers.home-assistant.io/docs/api/rest/`
- Community : `https://community.home-assistant.io/`
Voir `references/ha-common-errors.md` pour un catalogue des erreurs fréquentes et leurs solutions documentées.
# HA Log Investigator
## Règles non négociables
- Répondre en français.
- Vérifier la version exacte de Home Assistant avant toute analyse ou recommandation. Si elle est inconnue, arrêter l'analyse et demander la preuve minimale nécessaire.
- Ne jamais inventer une correction. Ne proposer une action que si elle est confirmée par une source officielle Home Assistant compatible avec la version installée.
- Distinguer clairement : **constaté**, **probable**, **à vérifier**.
- Préserver les secrets : ne jamais afficher de mot de passe ou token dans les sorties, les logs ou les fichiers de rapport.
- Ne pas modifier l'installation sans demande explicite de l'utilisateur.
- Avant toute suppression demandée d'entité, service, automatisation, script ou élément de dashboard, créer une trace de retour arrière selon `references/change-trace.md`.
## Workflow obligatoire
1. **Établir le périmètre et la version**
- Identifier le mode d'installation si possible : Home Assistant OS, Container, Core, Supervised.
- Obtenir la version exacte de Home Assistant Core avant tout diagnostic.
- Consigner la source de la version et l'horodatage de collecte.
2. **Choisir le mode d'accès minimal suffisant**
- Commencer par les artefacts fournis localement : exports de logs, `configuration.yaml`, autres fichiers YAML, exports de dashboards, diagnostics d'intégration.
- N'utiliser SSH que si les artefacts fournis ne suffisent pas pour lire les métriques hôte, les logs système, ou des fichiers absents.
- Ne pas exiger de serveur MCP spécifique par défaut. Utiliser un MCP uniquement s'il existe déjà dans l'environnement et apporte un accès plus sûr ou plus structuré.
- Lire `references/access-and-evidence.md` avant de choisir un accès distant.
3. **Constituer la synthèse système**
- Produire un résumé matériel : CPU, mémoire totale, mémoire utilisée/libre, swap si disponible, espace disque total/utilisé/libre par volume pertinent.
- Mentionner la provenance des mesures et signaler toute donnée indisponible.
4. **Analyser Home Assistant**
- Déterminer d'abord le type d'installation, puis examiner la source de logs officielle adaptée : sur Home Assistant OS, privilégier l'UI `Settings > System > Logs` ou `ha core logs` si autorisé ; ne traiter `/config/home-assistant.log` comme source attendue que si un doublon de fichier a été activé.
- Examiner ensuite les journaux disponibles, les traces fournies et les diagnostics.
- Si `rtk` est disponible localement, générer en plus un résumé compact des logs avec `rtk log` sans supprimer la source brute.
- Détecter les intégrations fautives : erreurs répétées, échecs d'initialisation, timeouts, authentification, dépendances manquantes, dépréciations.
- Identifier les entités problématiques : indisponibles, orphelines, dupliquées, mal nommées, sources de spam de logs, historiques incohérents.
- Analyser les dashboards : erreurs de cartes, ressources manquantes, références à des entités absentes, vues invalides, YAML Lovelace ou stockage `.storage` si disponible.
- Analyser `configuration.yaml` et les fichiers inclus ; si l'installation fournit un `config.yaml`, l'analyser aussi. Relever erreurs de syntaxe, inclusions fragiles, redondances et opportunités de simplification.
- Si Watchman est installé, lire son rapport final et l'utiliser comme source complémentaire pour les entités/actions référencées mais manquantes.
- Si Spook est installé, lire ses réparations et utiliser ses actions de suivi d'issues comme complément pour marquer, créer ou gérer des problèmes visibles dans le dashboard Repairs.
5. **Valider les corrections**
- Vérifier chaque proposition contre la documentation officielle Home Assistant correspondant à la version installée.
- Si la documentation officielle ne couvre pas le cas, écrire explicitement : `Aucune correction certaine sans documentation officielle compatible` et proposer seulement des vérifications complémentaires.
- Lire `references/official-docs-policy.md` avant de rédiger les recommandations.
6. **Produire les livrables**
- Générer `repair.md` en suivant `assets/repair.md.template`.
- Générer `best_entity.md` en suivant `assets/best_entity.md.template`.
- Générer ou mettre à jour `memory.md` en suivant `assets/memory.md.template`, en n'y conservant que les informations durables et non sensibles utiles aux audits futurs.
- Si l'utilisateur fournit des accès, les enregistrer dans `.ha-log-investigator/credentials.env` à partir de `assets/credentials.env.template`, avec permissions restrictives, puis masquer les valeurs dans tous les rapports.
- Pour SSH, accepter l'hôte, le port, l'utilisateur et soit un mot de passe soit un chemin de clé privée. Préférer la clé SSH quand elle existe, sans refuser le mot de passe si c'est le seul mode disponible.
- Sur Home Assistant OS avec plusieurs add-ons SSH, utiliser de préférence un profil dédié à l'add-on officiel `Terminal & SSH` pour les logs Core et tracer quel profil a servi à chaque collecte.
## Contenu attendu de l'analyse
### `repair.md`
Inclure au minimum :
- version Home Assistant vérifiée ;
- synthèse matériel ;
- sources analysées ;
- problèmes classés par sévérité ;
- intégrations fautives ;
- erreurs dashboards ;
- entités problématiques ;
- anomalies de configuration ;
- corrections proposées, preuve officielle, compatibilité de version, niveau de confiance ;
- points non résolus et données manquantes.
### `best_entity.md`
Inclure au minimum :
- entités à renommer ou normaliser ;
- entités inutilisées, dupliquées ou trop bavardes ;
- suggestions d'amélioration pour automatisations, scripts, helpers et configuration ;
- opportunités de regroupement, templates, zones, labels ou dashboards ;
- bénéfice attendu et effort estimé ;
- uniquement des suggestions compatibles avec la version vérifiée.
### `memory.md`
Inclure au minimum :
- identité durable de l'installation ;
- architecture et matériel stable ;
- modes d'accès disponibles sans exposer de secret ;
- emplacements de fichiers importants ;
- intégrations majeures ;
- conventions locales ;
- problèmes connus, décisions de maintenance et points à revoir au prochain audit.
Ne jamais y enregistrer de mot de passe, token ou clé privée.
## Mise à jour du skill
Si une évolution officielle de Home Assistant est détectée pendant un audit :
1. vérifier l'évolution dans la documentation officielle ;
2. suivre `references/skill-update.md` ;
3. mettre à jour les instructions/scripts nécessaires ;
4. ajouter l'entrée correspondante dans `history.md` ;
5. revalider puis retester le skill si possible.
## Références et gabarits
- Lire `references/access-and-evidence.md` pour choisir l'accès minimal et savoir quelles preuves collecter.
- Lire `references/official-docs-policy.md` pour la hiérarchie des sources et la règle de non-invention.
- Lire `references/log-analysis.md` pour la collecte, le compactage `rtk` et le traitement des logs absents.
- Lire `references/change-trace.md` avant toute suppression demandée.
- Lire `references/ssh-collector.md` avant d'utiliser le collecteur SSH.
- Lire `references/watchman.md` si l'intégration Watchman est installée ou si un rapport `watchman_report.txt` est présent.
- Lire `references/spook.md` si l'intégration Spook est installée ou si l'utilisateur veut exploiter les repairs / issues gérées par Spook.
- Lire `references/skill-update.md` lorsqu'une évolution officielle de Home Assistant semble rendre une procédure du skill obsolète.
- Mettre à jour `history.md` à chaque évolution confirmée du skill.
- Utiliser `scripts/collect_ssh_evidence.sh` lorsqu'une collecte SSH reproductible en lecture seule est utile.
- Copier puis compléter `assets/repair.md.template`, `assets/best_entity.md.template` et `assets/memory.md.template` pour les livrables.
- Copier `assets/credentials.env.template` seulement si l'utilisateur fournit réellement des identifiants ou un token.
skills/infra/ha-log-investigator/agents/openai.yaml
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "HA Log Investigator"
short_description: "Diagnostic Home Assistant en français"
default_prompt: "Utilise ha-log-investigator pour auditer mon installation Home Assistant, analyser les logs et produire repair.md et best_entity.md."
skills/infra/ha-log-investigator/assets/best_entity.md.template
+21
View File
@@ -0,0 +1,21 @@
# best_entity.md
## 1. Principes d'amélioration
## 2. Entités à améliorer
| Entité | Problème | Suggestion | Bénéfice | Effort |
|---|---|---|---|---|
## 3. Automatisations et scripts
| Sujet | Observation | Amélioration proposée | Bénéfice |
|---|---|---|---|
## 4. Configuration
| Sujet | Observation | Amélioration proposée | Bénéfice |
|---|---|---|---|
## 5. Dashboards et ergonomie
## 6. Priorités recommandées
## 7. Suggestions écartées faute de documentation officielle compatible
skills/infra/ha-log-investigator/assets/credentials.env.template
+20
View File
@@ -0,0 +1,20 @@
# Copier uniquement si l'utilisateur fournit explicitement ces valeurs.
# Conserver ce fichier hors dépôt Git et avec permissions 600.
HA_URL=
HA_USER=
HA_PASSWORD=
HA_TOKEN=
# Accès SSH optionnel
HA_SSH_HOST=
HA_SSH_PORT=22
HA_SSH_USER=
HA_SSH_PASSWORD=
HA_SSH_KEY_PATH=
# Accès SSH dédié aux logs HAOS via l'add-on officiel Terminal & SSH
HA_LOG_SSH_HOST=
HA_LOG_SSH_PORT=
HA_LOG_SSH_USER=
HA_LOG_SSH_PASSWORD=
HA_LOG_SSH_KEY_PATH=
skills/infra/ha-log-investigator/assets/memory.md.template
+51
View File
@@ -0,0 +1,51 @@
# memory.md
## 1. Identité de l'installation
- Nom / site :
- Version Home Assistant observée :
- Type d'installation :
- Date de dernière mise à jour de cette mémoire :
## 2. Architecture et matériel
- Hôte :
- CPU :
- Mémoire :
- Stockage :
- Particularités réseau :
## 3. Accès disponibles
| Accès | Disponible | Détail non sensible |
|---|---|---|
| Interface web | | |
| API Home Assistant | | |
| SSH | | |
| MCP | | |
## 4. Fichiers et emplacements importants
| Élément | Chemin / remarque |
|---|---|
| configuration principale | |
| automatisations | |
| scripts | |
| dashboards | |
| logs | |
## 5. Intégrations importantes
| Intégration | Rôle | Remarques |
|---|---|---|
## 6. Conventions locales
- Nommage des entités :
- Zones / labels :
- Helpers importants :
- Particularités de dashboards :
## 7. Problèmes connus et historique utile
| Date | Sujet | État | Commentaire |
|---|---|---|---|
## 8. Décisions et préférences de maintenance
-
## 9. Points à revoir au prochain audit
-
skills/infra/ha-log-investigator/assets/repair.md.template
+37
View File
@@ -0,0 +1,37 @@
# repair.md
## 1. Contexte vérifié
- Version Home Assistant :
- Type d'installation :
- Date de collecte :
- Sources analysées :
## 2. Synthèse matériel
| Élément | Total | Utilisé | Libre | Source |
|---|---:|---:|---:|---|
| CPU | | | | |
| Mémoire | | | | |
| Swap | | | | |
| Disque / volume | | | | |
## 3. Résumé exécutif
## 4. Problèmes détectés
| Sévérité | Domaine | Constat | Impact | Preuve |
|---|---|---|---|---|
## 5. Intégrations fautives
## 6. Dashboards
## 7. Entités problématiques
## 8. Configuration YAML
## 9. Corrections proposées
| Correction | Justification officielle | URL officielle | Compatibilité version | Confiance | Action |
|---|---|---|---|---|---|
## 10. Points non résolus
## 11. Données complémentaires utiles
skills/infra/ha-log-investigator/history.md
+62
View File
@@ -0,0 +1,62 @@
# Historique de ha-log-investigator
## 2026-05-16 — Création initiale
- Création du skill `ha-log-investigator`.
- Ajout des livrables `repair.md`, `best_entity.md`, `memory.md`.
- Ajout des règles de preuve officielle, d'accès minimal et de non-invention.
## 2026-05-16 — Ajout de l'accès SSH
- Ajout des champs SSH dans le modèle d'identifiants.
- Ajout d'un collecteur SSH en lecture seule.
- Ajout de la préférence pour clé SSH, avec compatibilité mot de passe.
## 2026-05-16 — Ajout de la mémoire durable
- Ajout du livrable `memory.md` pour conserver les éléments pérennes de l'installation.
## 2026-05-16 — Amélioration après test réel
- Correction du collecteur pour Home Assistant OS / BusyBox.
- Remplacement de la collecte `scp` par une lecture distante plus robuste.
- Ajout de la collecte des fichiers Lovelace, réparations et registres utiles.
## 2026-05-16 — Gestion moderne des logs HAOS
- Évolution constatée : sur Home Assistant OS, `/config/home-assistant.log` n'est plus une source attendue par défaut.
- Source officielle : documentation Home Assistant `logger`.
- Mise à jour du skill pour privilégier `Settings > System > Logs`, `ha core logs` si autorisé, ou le fichier dupliqué seulement si activé.
- Ajout de la détection explicite de l'absence de fichier log sans la traiter comme anomalie.
## 2026-05-16 — Sécurité et réversibilité
- Ajout du compactage optionnel avec `rtk log` côté machine de travail.
- Ajout des URLs officielles dans les recommandations.
- Ajout d'une trace de retour arrière obligatoire avant suppression demandée.
## À surveiller
- Évolutions futures des APIs ou commandes officielles de collecte des logs.
- Changements de structure des registres `.storage`.
- Évolutions des mécanismes de réparations Home Assistant.
## 2026-05-16 — Distinction des add-ons SSH pour les logs HAOS
- Évolution constatée pendant le test réel : `ha core logs` fonctionne depuis l'add-on officiel `Terminal & SSH`, alors qu'un autre accès SSH a renvoyé `401 Unauthorized`.
- Source officielle : documentation `Common tasks - Operating System` et documentation de l'add-on officiel `Terminal & SSH`.
- Mise à jour prévue : préférer explicitement `Terminal & SSH` pour les logs Home Assistant OS et tracer l'add-on utilisé pour chaque collecte.
## 2026-05-16 — Collecte de logs via session SSH interactive
- Évolution constatée pendant le test réel : `ha core logs` renvoie `401 Unauthorized` en commande SSH distante directe, mais fonctionne dans une vraie session interactive avec TTY.
- Conséquence : le skill doit tester le mode interactif avant de conclure que les logs Core sont inaccessibles.
- Mise à jour : ajout d'une règle spécifique dans l'analyse des logs et la collecte SSH.
## 2026-05-16 — Priorité au fichier log dupliqué quand présent
- Évolution constatée pendant le test réel : après activation du mode de compatibilité, `/config/home-assistant.log` est de nouveau disponible et exploitable.
- Mise à jour : le collecteur préfère désormais le fichier dupliqué non vide avant de tenter `ha core logs` ou le mode interactif.
## 2026-05-16 — Intégration de Watchman dans l'audit
- Ajout de Watchman comme source complémentaire obligatoire lorsqu'il est installé.
- Ajout de la lecture du rapport final `watchman_report.txt`.
- Ajout d'une règle de croisement avec les logs, les dashboards et l'état réel des entités afin de tenir compte des limites heuristiques de Watchman.
## 2026-05-16 — Intégration de Spook dans l'audit
- Ajout de Spook comme complément pour le suivi des réparations et la gestion d'issues visibles dans le dashboard Repairs.
- Ajout d'une règle de croisement avec les logs, Watchman et l'état réel des entités.
- Spook est utilisé pour suivre et matérialiser les problèmes, pas comme source unique de vérité.
skills/infra/ha-log-investigator/references/access-and-evidence.md
+51
View File
@@ -0,0 +1,51 @@
# Accès et preuves
## Principe
Toujours choisir l'accès le moins intrusif qui permet de répondre correctement.
## Ordre de préférence
1. **Artefacts locaux fournis par l'utilisateur**
- `home-assistant.log`
- `configuration.yaml` et fichiers inclus
- exports ou captures de dashboards
- diagnostics téléchargés depuis une intégration
- sorties de commandes déjà collectées
2. **API Home Assistant avec token longue durée**
- utile pour récupérer version, états, registres, services et diagnostics exposés
- préférer le token au mot de passe
3. **SSH**
- utile seulement pour métriques hôte, journaux système, stockage, fichiers non exportés, commandes supervisor/core selon le type d'installation
- justifier pourquoi SSH est nécessaire avant de le demander
- si SSH est retenu, collecter au minimum : hôte, port, utilisateur, puis soit mot de passe soit chemin de clé privée
- préférer l'authentification par clé quand elle est disponible ; utiliser le mot de passe seulement si c'est le mode réellement fourni
4. **MCP**
- optionnel, jamais requis par principe
- l'utiliser uniquement s'il existe déjà et apporte un accès structuré, traçable ou plus sûr qu'un accès ad hoc
## Preuves minimales à réunir
- version exacte de Home Assistant Core
- date/heure de collecte
- type d'installation si connu ; si le shell distant est isolé dans un add-on, corroborer avec l'API ou d'autres indices au lieu de conclure trop vite à `unknown`
- sources de logs inspectées
- liste des fichiers de configuration lus
- provenance des métriques matériel
- liste des dashboards inspectés
- liste des entités réellement observées
## Commandes ou données typiquement utiles
Les commandes exactes dépendent du mode d'installation et ne doivent être proposées qu'après vérification documentaire compatible avec la version installée.
Exemples de catégories de données utiles :
- version de Home Assistant
- CPU et mémoire
- espace disque
- extraits de logs autour des erreurs, selon la source officielle adaptée au mode d'installation
- registres d'entités et d'appareils
- contenu des dashboards YAML ou exports équivalents
skills/infra/ha-log-investigator/references/change-trace.md
+25
View File
@@ -0,0 +1,25 @@
# Trace de changements et retour arrière
## Principe
Ne jamais supprimer une entité, un service, une automatisation, un script ou un élément de dashboard sans créer d'abord une trace permettant de revenir en arrière.
## Avant toute suppression demandée par l'utilisateur
Créer un dossier horodaté `rollback/YYYYMMDDTHHMMSSZ/` contenant, selon le cas :
- une copie des fichiers YAML concernés ;
- une copie des extraits `.storage` concernés si lisibles ;
- un export ou inventaire des entités ciblées ;
- un fichier `changes.md` décrivant :
- ce qui va être supprimé ;
- pourquoi ;
- les preuves ;
- les fichiers touchés ;
- la procédure de restauration.
## Règles
- Ne jamais mettre de secret dans `changes.md`.
- Préférer une désactivation ou un retrait ciblé à une suppression large quand l'intention de l'utilisateur est ambiguë.
- Après modification, produire un résumé avant/après.
- Si la suppression concerne une entité ou une automatisation utilisée par un dashboard, signaler explicitement les dépendances avant exécution.
skills/infra/ha-log-investigator/references/ha-common-errors.md
-114
View File
@@ -1,114 +0,0 @@
# Erreurs Home Assistant fréquentes — Catalogue documenté
## Intégrations
### `Platform X not ready`
- **Cause** : Le service distant n'est pas encore accessible au démarrage de HA
- **Solution** : Ajouter `initial_state: false` ou augmenter `scan_interval`. Vérifier la connectivité réseau.
- **Doc** : https://www.home-assistant.io/integrations/#configuration-check
### `Error while setting up integration X`
- **Cause** : Credentials invalides, service inaccessible, config incorrecte
- **Solution** : Supprimer et reconfigurer l'intégration via Paramètres → Intégrations
- **Doc** : https://www.home-assistant.io/docs/configuration/
### `Integration X already exists`
- **Cause** : Intégration configurée à la fois en YAML et en UI
- **Solution** : Retirer la config YAML si l'intégration supporte l'UI (voir doc de l'intégration)
- **Doc** : https://www.home-assistant.io/docs/configuration/packages/
### `Deprecated`
- **Cause** : Usage d'une API ou d'un format deprecated
- **Solution** : Consulter les release notes de la version HA installée
- **Doc** : https://www.home-assistant.io/blog/ (chercher la version concernée)
---
## Entités
### `unavailable`
- **Cause possible 1** : Appareil physique hors ligne
- **Cause possible 2** : Intégration en erreur
- **Cause possible 3** : Template invalide
- **Diagnostic** : Vérifier les logs pour le nom de l'entité
### `unknown`
- **Cause** : L'entité existe mais n'a pas encore reçu de valeur (souvent au démarrage)
- **Normal** : Peut disparaître après quelques secondes/minutes
- **Problématique** : Si persiste, vérifier la config
### Template error
```
Error rendering template: UndefinedError: 'sensor.xyz' is undefined
```
- **Solution** : Utiliser `states('sensor.xyz')` au lieu de `states.sensor.xyz.state` (plus robuste)
- **Doc** : https://www.home-assistant.io/docs/configuration/templating/
---
## Base de données / Recorder
### `Database disk usage: X MB`
- **Cause** : Base de données SQLite trop volumineuse
- **Solution** : Configurer `recorder` avec `purge_keep_days` et exclure les entités à haute fréquence
```yaml
recorder:
purge_keep_days: 7
exclude:
entity_globs:
- sensor.*_signal_strength
- sensor.*_rssi
```
- **Doc** : https://www.home-assistant.io/integrations/recorder/
---
## Lovelace / Dashboards
### Custom card non chargée
```
Custom element doesn't exist: custom-card-name
```
- **Cause** : La ressource custom card n'est pas déclarée ou le fichier est manquant
- **Solution** : Paramètres → Tableaux de bord → Ressources → Ajouter le JS
- **Doc** : https://www.home-assistant.io/dashboards/dashboards/
### Entité manquante dans dashboard
```
Entity not available: sensor.xyz
```
- **Solution** : Vérifier que l'entité existe (`États` dans les outils de développement), corriger le nom dans la carte
---
## Réseau / SSL
### `SSL CERTIFICATE_VERIFY_FAILED`
- **Cause** : Certificat auto-signé ou expiré
- **Solution** : Vérifier `verify_ssl: false` pour les connexions internes (non recommandé en prod), ou renouveler le certificat
- **Doc** : https://www.home-assistant.io/docs/configuration/securing/
### `Connection refused` / `Cannot connect to host`
- **Cause** : Service distant éteint ou port bloqué par firewall
- **Diagnostic** : `ping`, `telnet HOST PORT` depuis le host HA
---
## YAML / Configuration
### Indentation YAML incorrecte
- **Erreur** : `mapping values are not allowed here`
- **Outil** : https://yaml-online-parser.appspot.com/
- **Conseil** : Utiliser 2 espaces, jamais de tabulations
### `!secret not found`
- **Cause** : La clé référencée n'existe pas dans `secrets.yaml`
- **Solution** : Ajouter la clé dans `/config/secrets.yaml`
### Config check
```bash
# HA OS
ha core check
# Docker
docker exec homeassistant python -m homeassistant --config /config --script check_config
```
skills/infra/ha-log-investigator/references/log-analysis.md
+45
View File
@@ -0,0 +1,45 @@
# Analyse des logs
## Collecte
- Conserver la source brute quand elle existe.
- Si `rtk` est disponible localement, produire en complément une version compacte avec `rtk log` pour réduire le volume transmis au modèle.
- Ne jamais remplacer la source brute par le résumé compact.
## Stratégie selon le type d'installation
### Home Assistant OS
- Ne pas attendre de fichier `/config/home-assistant.log` par défaut.
- Si un fichier dupliqué existe et n'est pas vide, le préférer pour la collecte automatisée car il évite un shell interactif et garde le flux brut disponible.
- Considérer comme sources officielles prioritaires :
1. l'interface `Settings > System > Logs` ;
2. `ha core logs` depuis l'add-on officiel `Terminal & SSH` si l'accès SSH autorisé le permet ;
3. `/config/home-assistant.log` seulement si le mode `duplicate-log-file` a été activé volontairement.
- Si plusieurs add-ons SSH sont installés, ne pas supposer qu'ils donnent le même accès : tracer l'add-on réellement utilisé pour la collecte.
- Si `ha core logs` retourne `401 Unauthorized` en commande distante directe mais fonctionne en session ouverte, tester une session SSH interactive avec TTY (`ssh -tt`) : certains environnements d'add-on initialisent l'accès Supervisor seulement dans ce contexte.
### Home Assistant Container / Core
- Vérifier les fichiers logs de configuration quand ils existent et les commandes adaptées au mode d'installation.
## Cas où aucune source de log exploitable n'est disponible
Vérifier séparément :
1. le type d'installation ;
2. les sources officiellement attendues pour ce type ;
3. l'existence éventuelle de fichiers dupliqués ;
4. les erreurs d'autorisation éventuelles sur les commandes documentées.
Si aucune source exploitable n'est accessible :
- l'écrire explicitement dans `repair.md` ;
- demander un export des logs depuis l'interface Home Assistant ou une source équivalente fournie par l'utilisateur ;
- ne pas conclure à l'absence d'erreurs runtime.
## Usage de `rtk`
Exemple local :
```bash
rtk log home-assistant.log > home-assistant.compact.log
```
Le résumé compact sert à l'analyse rapide ; les constats importants doivent rester traçables vers le log brut.
skills/infra/ha-log-investigator/references/official-docs-policy.md
+33
View File
@@ -0,0 +1,33 @@
# Politique de documentation officielle
## Règle principale
Ne recommander une correction que si elle est soutenue par une documentation officielle Home Assistant compatible avec la version réellement installée.
## Sources acceptables
Privilégier, selon le sujet :
- la documentation officielle Home Assistant ;
- les notes de version officielles ;
- la documentation développeur officielle Home Assistant ;
- les pages officielles d'intégration Home Assistant.
Les forums, blogs, dépôts personnels et réponses communautaires peuvent servir d'indices, jamais de preuve finale pour une correction.
## Méthode de validation
Pour chaque recommandation :
1. noter la version installée ;
2. vérifier que la fonctionnalité ou le paramètre existe pour cette version ;
3. citer la source officielle consultée ;
4. indiquer si la recommandation est :
- confirmée ;
- probable mais à vérifier ;
- non démontrée faute de documentation officielle.
## Si la documentation manque
Écrire explicitement qu'aucune correction certaine n'est proposée sans documentation officielle compatible. Donner seulement :
- les faits observés ;
- les vérifications complémentaires possibles ;
- les informations à collecter pour lever l'incertitude.
skills/infra/ha-log-investigator/references/skill-update.md
+42
View File
@@ -0,0 +1,42 @@
# Mise à jour du skill
## Objectif
Mettre à jour `ha-log-investigator` lorsqu'une évolution officielle de Home Assistant modifie la manière correcte de collecter les preuves, d'interroger l'API, de lire les logs, de traiter les dashboards, les réparations ou les fichiers de configuration.
## Déclencheurs
Lancer ce workflow si :
- une documentation officielle contredit le comportement actuel du skill ;
- une commande documentée change ;
- une API officielle évolue ;
- un mode d'installation modifie ses chemins ou ses sources de logs ;
- un test réel révèle une hypothèse devenue obsolète.
## Workflow de mise à jour
1. Identifier l'évolution constatée.
2. Vérifier l'information dans une source officielle Home Assistant.
3. Décrire l'écart entre :
- comportement actuel du skill ;
- comportement officiel attendu.
4. Mettre à jour uniquement les fichiers nécessaires :
- `SKILL.md`
- références concernées
- scripts concernés
- templates concernés
5. Ajouter une entrée dans `history.md` avec :
- date ;
- évolution observée ;
- source officielle ;
- fichiers modifiés ;
- conséquence pratique.
6. Revalider le skill.
7. Si possible, retester sur un cas réel ou un artefact réaliste.
## Règles
- Ne jamais supprimer l'historique existant.
- Ne pas mettre à jour le skill sur la base d'un forum, d'un blog ou d'une intuition seule.
- Si une évolution est suspectée mais non confirmée officiellement, l'ajouter dans la section `À surveiller` de `history.md` au lieu de modifier le comportement du skill.
- Conserver la compatibilité avec les versions anciennes seulement si elle est encore utile et documentée.
skills/infra/ha-log-investigator/references/spook.md
+35
View File
@@ -0,0 +1,35 @@
# Spook
## Rôle
Utiliser Spook lorsqu'il est installé comme complément pour la gestion des réparations Home Assistant.
Spook fournit des actions et entités autour du dashboard Repairs :
- créer des issues ;
- ignorer / réactiver des issues ;
- compter les issues actives, ignorées et totales ;
- suivre des problèmes récurrents dans un format visible dans Home Assistant.
## Règles d'usage
- Vérifier si Spook est installé avant de s'y fier.
- L'utiliser comme outil de suivi et d'annotation des problèmes, pas comme source unique de vérité.
- Croiser les issues Spook avec :
- les logs runtime ;
- l'état réel des entités ;
- Watchman ;
- la configuration YAML ;
- les réparations natives Home Assistant.
## Quand l'utiliser
- Quand tu veux matérialiser un problème récurrent dans Repairs.
- Quand tu veux suivre l'état "à traiter / traité" pendant un nettoyage progressif.
- Quand tu veux signaler une anomalie de façon visible dans Home Assistant sans modifier la logique métier.
## Ce qu'il faut retenir
- Spook est utile pour le pilotage du flux de corrections.
- Spook ne remplace pas Watchman.
- Spook ne remplace pas l'analyse des logs.
- Spook ne remplace pas la correction de la cause racine.
skills/infra/ha-log-investigator/references/ssh-collector.md
+55
View File
@@ -0,0 +1,55 @@
# Collecteur SSH
Utiliser `scripts/collect_ssh_evidence.sh` lorsque SSH est justifié et que l'utilisateur veut une collecte reproductible en lecture seule.
## Entrées attendues
Un fichier d'identifiants au format `credentials.env` contenant au minimum :
- `HA_SSH_HOST`
- `HA_SSH_PORT`
- `HA_SSH_USER`
- soit `HA_SSH_PASSWORD`, soit `HA_SSH_KEY_PATH`
Préférer `HA_SSH_KEY_PATH` si disponible.
## Exemple
```bash
scripts/collect_ssh_evidence.sh \
--credentials ~/.ha-log-investigator/credentials.env \
--output ./ha-evidence
```
## Garanties
- collecte en lecture seule ;
- aucune modification distante ;
- sorties regroupées dans un dossier horodaté ;
- absence de secrets dans les rapports générés par le script.
## Données collectées
- système : `uname`, OS, CPU, mémoire, swap, disques ;
- indices de version Home Assistant accessibles localement ;
- extrait de logs Home Assistant ;
- fichiers YAML principaux si accessibles ;
- index des fichiers `.storage` si accessible.
## Limites
- les chemins varient selon le mode d'installation ;
- l'authentification par mot de passe exige `sshpass` côté machine cliente ;
- le script collecte des preuves, il ne remplace pas la validation par documentation officielle avant recommandation.
## Plusieurs add-ons SSH
Sur Home Assistant OS, préférer l'add-on officiel `Terminal & SSH` lorsqu'il faut collecter `ha core logs`.
Si un autre add-on SSH est utilisé pour d'autres tâches, conserver des profils d'accès distincts et consigner lequel a servi à chaque collecte.
## Cas `ha core logs` interactif uniquement
Si `ha core logs` fonctionne après connexion interactive mais renvoie `401 Unauthorized` lorsqu'il est exécuté directement via `ssh host 'ha core logs'`, utiliser un mode interactif avec TTY pour la collecte des logs, puis nettoyer les séquences ANSI et le banner avant analyse.
Cette situation doit être notée dans `repair.md` comme une contrainte d'accès, pas comme une erreur Home Assistant.
skills/infra/ha-log-investigator/references/watchman.md
+40
View File
@@ -0,0 +1,40 @@
# Watchman
## Rôle
Utiliser Watchman lorsqu'il est installé pour compléter l'audit Home Assistant.
Watchman scanne les fichiers de configuration et signale les entités et actions/services référencés mais manquants ou indisponibles. Il produit un rapport texte, généralement `watchman_report.txt`, et peut aussi retourner un rapport via l'action `watchman.report`.
## Règles d'usage
- Vérifier si Watchman est installé avant l'analyse finale.
- S'il est installé, lire le rapport le plus récent et l'intégrer aux constats.
- Ne pas traiter automatiquement chaque ligne Watchman comme une vérité absolue : Watchman utilise une analyse heuristique et peut produire des faux positifs ou faux négatifs.
- Croiser ses résultats avec :
- l'état réel des entités ;
- les dashboards ;
- les automatisations ;
- les logs runtime.
## Rapport attendu
Chercher en priorité :
- `/config/watchman_report.txt`
- ou le chemin configuré dans Watchman si différent.
## Quand produire le rapport
Si nécessaire et si l'utilisateur autorise l'action, exécuter `watchman.report` depuis Home Assistant avec création de fichier afin d'obtenir un rapport actualisé avant l'analyse finale.
## Ce qu'il faut reprendre dans les livrables
Dans `repair.md` :
- nombre d'entités manquantes ;
- nombre d'actions/services manquants ;
- exemples significatifs ;
- indication que le rapport vient de Watchman.
Dans `best_entity.md` :
- pistes de nettoyage des références orphelines ;
- priorités d'amélioration si elles sont confirmées par d'autres sources.
skills/infra/ha-log-investigator/scripts/collect_ssh_evidence.sh
Executable
+270
View File
@@ -0,0 +1,270 @@
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<'USAGE'
Usage:
collect_ssh_evidence.sh --credentials /path/to/credentials.env [--output /path/to/output]
Collecte en lecture seule via SSH :
- informations système (CPU, mémoire, swap, disques)
- indices sur la version Home Assistant
- extraits de logs si accessibles
- fichiers de configuration principaux si accessibles
Le script n'effectue aucune modification distante.
USAGE
}
credentials_file=""
output_dir=""
while [[ $# -gt 0 ]]; do
case "$1" in
--credentials)
credentials_file="${2:-}"
shift 2
;;
--output)
output_dir="${2:-}"
shift 2
;;
-h|--help)
usage
exit 0
;;
*)
echo "Argument inconnu: $1" >&2
usage >&2
exit 2
;;
esac
done
if [[ -z "$credentials_file" ]]; then
echo "--credentials est obligatoire" >&2
exit 2
fi
if [[ ! -f "$credentials_file" ]]; then
echo "Fichier d'identifiants introuvable: $credentials_file" >&2
exit 2
fi
# shellcheck disable=SC1090
source "$credentials_file"
: "${HA_SSH_HOST:?HA_SSH_HOST manquant}"
: "${HA_SSH_USER:?HA_SSH_USER manquant}"
HA_SSH_PORT="${HA_SSH_PORT:-22}"
HA_SSH_PASSWORD="${HA_SSH_PASSWORD:-}"
HA_SSH_KEY_PATH="${HA_SSH_KEY_PATH:-}"
timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
if [[ -z "$output_dir" ]]; then
output_dir="./ha-ssh-evidence-$timestamp"
fi
mkdir -p "$output_dir"/{system,home-assistant,config}
chmod 700 "$output_dir"
ssh_base=(ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -p "$HA_SSH_PORT")
scp_base=(scp -P "$HA_SSH_PORT" -o BatchMode=yes -o StrictHostKeyChecking=accept-new)
if [[ -n "$HA_SSH_KEY_PATH" ]]; then
ssh_base+=(-i "$HA_SSH_KEY_PATH")
scp_base+=(-i "$HA_SSH_KEY_PATH")
fi
run_ssh() {
local remote_cmd="$1"
if [[ -n "$HA_SSH_PASSWORD" && -z "$HA_SSH_KEY_PATH" ]]; then
if ! command -v sshpass >/dev/null 2>&1; then
echo "sshpass est requis pour l'authentification par mot de passe, mais il est absent." >&2
return 127
fi
sshpass -p "$HA_SSH_PASSWORD" ssh -o StrictHostKeyChecking=accept-new -p "$HA_SSH_PORT" "$HA_SSH_USER@$HA_SSH_HOST" "$remote_cmd"
else
"${ssh_base[@]}" "$HA_SSH_USER@$HA_SSH_HOST" "$remote_cmd"
fi
}
copy_remote_file() {
local remote_path="$1"
local local_path="$2"
run_ssh "if [ -r '$remote_path' ]; then cat '$remote_path'; fi" > "$local_path" 2>/dev/null || true
if [[ ! -s "$local_path" ]]; then
rm -f "$local_path"
fi
}
collect_interactive_core_logs() {
local lines="$1"
local raw_path="$2"
local clean_path="$3"
local start_marker="__HA_LOG_START__"
local end_marker="__HA_LOG_END__"
if [[ -n "$HA_SSH_PASSWORD" && -z "$HA_SSH_KEY_PATH" ]]; then
if ! command -v sshpass >/dev/null 2>&1; then
return 127
fi
printf 'echo %s\nha core logs --lines %s\necho %s\nexit\n' "$start_marker" "$lines" "$end_marker" \
| sshpass -p "$HA_SSH_PASSWORD" ssh -tt -o StrictHostKeyChecking=accept-new -p "$HA_SSH_PORT" "$HA_SSH_USER@$HA_SSH_HOST" \
> "$raw_path" 2>&1 || true
else
printf 'echo %s\nha core logs --lines %s\necho %s\nexit\n' "$start_marker" "$lines" "$end_marker" \
| "${ssh_base[@]}" -tt "$HA_SSH_USER@$HA_SSH_HOST" \
> "$raw_path" 2>&1 || true
fi
python3 - "$raw_path" "$clean_path" "$start_marker" "$end_marker" <<'PY2'
import re, sys
from pathlib import Path
raw_path, clean_path, start_marker, end_marker = Path(sys.argv[1]), Path(sys.argv[2]), sys.argv[3], sys.argv[4]
text = raw_path.read_text(errors='ignore')
text = re.sub(r'\x1B\][^\x07]*(?:\x07|\x1b\\)', '', text)
text = re.sub(r'\x1B\[[0-9;?]*[ -/]*[@-~]', '', text)
text = text.replace('\r', '')
lines = text.splitlines()
# The command script itself is echoed before execution. Keep the *last* start marker,
# which is the marker printed by the shell, then the last matching end marker after it.
start_idx = max((i for i,l in enumerate(lines) if start_marker in l), default=-1)
end_idx = max((i for i,l in enumerate(lines) if end_marker in l and i > start_idx), default=-1)
if start_idx != -1 and end_idx != -1:
body = lines[start_idx + 1:end_idx]
clean = []
for line in body:
stripped = line.strip()
if not stripped:
clean.append('')
continue
if 'ha core logs --lines' in stripped:
continue
if stripped == start_marker or stripped == end_marker or stripped == 'exit':
continue
if stripped.startswith('➜') or stripped == '#':
continue
clean.append(line)
clean_path.write_text('\n'.join(clean).strip() + '\n')
PY2
}
{
echo "collected_at_utc=$timestamp"
echo "ssh_host=$HA_SSH_HOST"
echo "ssh_port=$HA_SSH_PORT"
echo "ssh_user=$HA_SSH_USER"
echo "install_type_hint_source=ssh_shell_only"
} > "$output_dir/collection.meta"
run_ssh 'uname -a || true' > "$output_dir/system/uname.txt" || true
run_ssh 'cat /etc/os-release 2>/dev/null || true' > "$output_dir/system/os-release.txt" || true
run_ssh 'if [ -d /usr/share/hassio ] || [ -e /data/supervisor ]; then echo home_assistant_os_or_supervised; else echo unknown; fi' > "$output_dir/home-assistant/install-type-hint.txt" || true
run_ssh 'nproc 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || true' > "$output_dir/system/cpu-count.txt" || true
run_ssh 'lscpu 2>/dev/null || cat /proc/cpuinfo 2>/dev/null || true' > "$output_dir/system/cpu.txt" || true
run_ssh 'free -h 2>/dev/null || cat /proc/meminfo 2>/dev/null || true' > "$output_dir/system/memory.txt" || true
run_ssh 'df -hT 2>/dev/null || df -h 2>/dev/null || true' > "$output_dir/system/disks.txt" || true
run_ssh 'swapon --show 2>/dev/null || true' > "$output_dir/system/swap.txt" || true
run_ssh '
if command -v ha >/dev/null 2>&1; then
ha core info 2>/dev/null || true
fi
' > "$output_dir/home-assistant/ha-core-info.txt" || true
run_ssh '
if command -v docker >/dev/null 2>&1; then
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}" 2>/dev/null || true
fi
' > "$output_dir/home-assistant/docker-ps.txt" || true
run_ssh '
for f in \
/config/.HA_VERSION \
/usr/share/hassio/homeassistant/.HA_VERSION \
/home/homeassistant/.homeassistant/.HA_VERSION; do
if [ -r "$f" ]; then
echo "=== $f ==="
cat "$f"
fi
done
' > "$output_dir/home-assistant/version-files.txt" || true
run_ssh '
for f in \
/config/home-assistant.log \
/usr/share/hassio/homeassistant/home-assistant.log \
/home/homeassistant/.homeassistant/home-assistant.log; do
if [ -r "$f" ] && [ -s "$f" ]; then
echo "=== $f ==="
tail -n 400 "$f"
exit 0
fi
done
' > "$output_dir/home-assistant/home-assistant-log-tail.txt" || true
run_ssh '
echo "current_log_exists=$( [ -r /config/home-assistant.log ] && echo yes || echo no )"
echo "haos_default_log_file_expected=no"
for f in /config/home-assistant.log /config/home-assistant.log.1 /config/home-assistant.log.fault; do
if [ -e "$f" ]; then
size=$(wc -c < "$f" 2>/dev/null || echo unknown)
echo "$f bytes=$size"
fi
done
' > "$output_dir/home-assistant/log-status.txt" || true
run_ssh 'ha core logs --lines 40 2>&1 || true' > "$output_dir/home-assistant/ha-core-logs-attempt.txt" || true
if grep -q '401: Unauthorized' "$output_dir/home-assistant/ha-core-logs-attempt.txt" 2>/dev/null; then
collect_interactive_core_logs 120 "$output_dir/home-assistant/ha-core-logs-interactive.raw.txt" "$output_dir/home-assistant/ha-core-logs-interactive.txt" || true
fi
if [[ -s "$output_dir/home-assistant/ha-core-logs-interactive.txt" ]] && command -v rtk >/dev/null 2>&1; then
rtk log "$output_dir/home-assistant/ha-core-logs-interactive.txt" > "$output_dir/home-assistant/ha-core-logs-interactive.compact.txt" || true
fi
if [[ -s "$output_dir/home-assistant/home-assistant-log-tail.txt" ]] && command -v rtk >/dev/null 2>&1; then
rtk log "$output_dir/home-assistant/home-assistant-log-tail.txt" > "$output_dir/home-assistant/home-assistant-log-compact.txt" || true
fi
run_ssh '
if command -v journalctl >/dev/null 2>&1; then
journalctl -u home-assistant@homeassistant.service -n 300 --no-pager 2>/dev/null || true
fi
' > "$output_dir/home-assistant/journal-home-assistant.txt" || true
for remote in \
/config/configuration.yaml \
/config/automations.yaml \
/config/scripts.yaml \
/config/scenes.yaml \
/usr/share/hassio/homeassistant/configuration.yaml \
/home/homeassistant/.homeassistant/configuration.yaml; do
name="$(echo "$remote" | sed 's#^/##; s#/#__#g')"
copy_remote_file "$remote" "$output_dir/config/$name" || true
done
run_ssh '
for d in /config/.storage /usr/share/hassio/homeassistant/.storage /home/homeassistant/.homeassistant/.storage; do
if [ -d "$d" ]; then
echo "=== $d ==="
for f in "$d"/*; do
[ -f "$f" ] && basename "$f"
done | sort
fi
done
' > "$output_dir/config/storage-index.txt" || true
for remote in \
/config/.storage/lovelace.lovelace \
/config/.storage/lovelace_dashboards \
/config/.storage/lovelace_resources \
/config/.storage/repairs.issue_registry \
/config/.storage/core.entity_registry \
/config/.storage/core.config_entries; do
name="$(echo "$remote" | sed 's#^/##; s#/#__#g')"
copy_remote_file "$remote" "$output_dir/config/$name" || true
done
echo "Collecte terminée: $output_dir"
skills/infra/ha-log-investigator/scripts/ha-system-info.sh
-39
View File
@@ -1,39 +0,0 @@
#!/bin/bash
# Collecte les infos système du host Home Assistant via SSH
# Usage: ./ha-system-info.sh [user@host]
HOST="${1:-root@homeassistant.local}"
echo "=== COLLECTE SYSTÈME HOME ASSISTANT ==="
echo "Hôte : $HOST"
echo "Date : $(date)"
echo ""
echo "--- CPU ---"
ssh "$HOST" "cat /proc/cpuinfo | grep 'model name' | head -1 | cut -d: -f2 | xargs" 2>/dev/null || echo "N/A"
echo ""
echo "--- MÉMOIRE ---"
ssh "$HOST" "free -h" 2>/dev/null || echo "N/A"
echo ""
echo "--- DISQUE ---"
ssh "$HOST" "df -h" 2>/dev/null || echo "N/A"
echo ""
echo "--- UPTIME ---"
ssh "$HOST" "uptime" 2>/dev/null || echo "N/A"
echo ""
echo "--- TEMPÉRATURE CPU ---"
ssh "$HOST" "cat /sys/class/thermal/thermal_zone*/temp 2>/dev/null | awk '{printf \"%.1f°C\n\", \$1/1000}'" 2>/dev/null || echo "N/A"
echo ""
echo "--- VERSION HOME ASSISTANT ---"
ssh "$HOST" "ha core info 2>/dev/null | grep version || grep -r 'homeassistant:' /config/configuration.yaml 2>/dev/null | head -5 || echo 'Utiliser lAPI REST pour la version'" 2>/dev/null
echo ""
echo "--- LOGS RÉCENTS (50 dernières erreurs/warnings) ---"
ssh "$HOST" "cat /config/home-assistant.log 2>/dev/null | grep -E '(ERROR|WARNING)' | tail -50" 2>/dev/null || \
ssh "$HOST" "journalctl -u hassio -n 100 --no-pager 2>/dev/null | grep -E '(ERROR|WARNING)'" 2>/dev/null || \
echo "Logs non accessibles via SSH — utiliser l'API REST"
skills/infra/ha-log-investigator/templates/best-entity-template.md
-134
View File
@@ -1,134 +0,0 @@
# Suggestions d'amélioration Home Assistant
Généré le : {{DATE}}
Version HA : {{HA_VERSION}}
---
## Automatisations suggérées
<!-- Pour chaque automatisation recommandée -->
### [Nom de l'automatisation]
- **Déclencheur** : [event, state, time, etc.]
- **Condition** : [si applicable]
- **Action** : [description]
- **Blueprint disponible** : [URL ou "Non"]
- **Exemple YAML** :
```yaml
automation:
alias: "[Nom]"
trigger:
- platform: [type]
# ...
action:
- service: [service]
# ...
```
- **Documentation** : [URL]
---
## Améliorations des entités
### Nommage et organisation
| Entité actuelle | Nom suggéré | Raison |
|-----------------|-------------|--------|
| `sensor.xxx` | `sensor.pièce_appareil_mesure` | Convention de nommage |
### `friendly_name` manquants
```yaml
# À ajouter dans customize.yaml ou via l'UI
homeassistant:
customize:
sensor.nom_entite:
friendly_name: "Nom lisible"
icon: mdi:icone
```
### `device_class` recommandés
```yaml
sensor:
- platform: template
sensors:
mon_capteur:
device_class: temperature # ou humidity, power, energy...
```
- **Doc** : https://www.home-assistant.io/docs/configuration/customizing-devices/
---
## Optimisation de la base de données
```yaml
# configuration.yaml
recorder:
purge_keep_days: 7
commit_interval: 30
exclude:
domains:
- sun
- weather
entity_globs:
- sensor.*_signal_strength
- sensor.*_rssi
- sensor.*_lqi
entities:
# lister les entités à exclure
```
- **Économie estimée** : [X MB]
- **Documentation** : https://www.home-assistant.io/integrations/recorder/
---
## Scripts réutilisables suggérés
### [Nom du script]
```yaml
script:
nom_script:
alias: "[Nom lisible]"
sequence:
- service: [service]
# ...
```
- **Usage** : [où utiliser ce script]
---
## Configuration recommandée
### Logbook filtering
```yaml
logbook:
exclude:
domains:
- sun
entity_globs:
- sensor.*_signal_strength
```
### History filtering
```yaml
history:
exclude:
domains:
- sun
- weather
```
---
## Pistes d'amélioration avancées
- [ ] [Amélioration 1 — description et lien doc]
- [ ] [Amélioration 2 — description et lien doc]
---
*Suggestions générées par ha-log-investigator. Toutes les recommandations sont basées sur la documentation officielle HA {{HA_VERSION}}.*
skills/infra/ha-log-investigator/templates/repair-template.md
-78
View File
@@ -1,78 +0,0 @@
# Rapport de réparation Home Assistant
Généré le : {{DATE}}
Version HA : {{HA_VERSION}}
Instance : {{HA_URL}}
---
## Résumé système
| Ressource | Valeur |
|-----------|--------|
| CPU | {{CPU_MODEL}} |
| RAM | {{RAM_USED}} / {{RAM_TOTAL}} ({{RAM_PCT}}%) |
| Disque | {{DISK_USED}} / {{DISK_TOTAL}} ({{DISK_PCT}}%) |
| Uptime | {{UPTIME}} |
| Temp. CPU | {{CPU_TEMP}} |
---
## Problèmes critiques (à traiter en priorité)
<!-- Répéter ce bloc pour chaque ERROR trouvé -->
### [Composant X] — [description courte]
- **Symptôme** : `[message d'erreur exact extrait des logs]`
- **Fréquence** : [N occurrences depuis [date]]
- **Cause probable** : [explication claire]
- **Solution** :
1. [Étape 1]
2. [Étape 2]
- **Documentation officielle** : [URL https://www.home-assistant.io/...]
- **Compatibilité** : ✅ Confirmé pour HA {{HA_VERSION}}
---
## Avertissements (WARNING)
<!-- Répéter ce bloc pour chaque WARNING significatif -->
### [Composant Y] — [description courte]
- **Symptôme** : `[message]`
- **Action recommandée** : [description]
- **Documentation** : [URL]
---
## Intégrations en erreur
| Intégration | État | Action |
|-------------|------|--------|
| [nom] | setup_error | [action recommandée] |
---
## Entités indisponibles ({{UNAVAILABLE_COUNT}} total)
### Par domaine
#### sensor ({{N}} entités)
- `sensor.nom_entite` — [raison probable]
#### switch ({{N}} entités)
- `switch.nom_entite` — [raison probable]
<!-- etc. -->
---
## Prochaines étapes recommandées
1. [ ] Effectuer un backup complet avant toute modification
2. [ ] Traiter les problèmes critiques dans l'ordre ci-dessus
3. [ ] Redémarrer HA après chaque modification
4. [ ] Vérifier les logs après redémarrage
---
*Rapport généré par ha-log-investigator. Les solutions proposées sont basées sur la documentation officielle Home Assistant.*