EVCS/AGENTS.md

AGENTS.md — Projet n8n / Home Assistant / EVCS Solaire

🎯 Environnement

• Serveur n8n : https://n8n.airtria.pro (API v1)
• Accès n8n via le MCP n8n-mcp (lecture/écriture de workflows).
• Pilotage énergie via MCP dédiés. Modèle local : Qwen3.6-35B (contexte limité).

🔧 OUTILS — RÈGLES STRICTES

Noms d'outils MCP (TIRETS, jamais underscores)

• ha-get-state · lire un état Home Assistant
• ha-set-helper · écrire un helper HA
• grid-set-state · piloter le grid
• victron-set-charge-limits · limites de charge Victron
• pv-get-forecast · prévision solaire
• n8n-mcp · workflows n8n ⚠️ Recopie ces noms EXACTEMENT. N'invente jamais un nom d'outil.

Interdictions

• JAMAIS de curl / wget / appel HTTP direct vers HA, n8n, Victron. Tout passe par les MCP (le shell bloque curl de toute façon).
• JAMAIS d'IP, d'URL ni de token inventés. Info manquante → utilise le MCP ou demande-moi. Ne devine pas.
• ripgrep/rg N'EST PAS installé. Utilise grep.

📂 LIRE UN WORKFLOW n8n (méthode obligatoire)

⭐ R2 (07/08/2026) — SOURCE DE VÉRITÉ = src/nodes/

Le code des nodes du workflow EVCS V2.6 vit dans src/nodes/*.js (+ HA_SNAPSHOT_TEMPLATE.json.tpl). RÈGLES :

• Pour MODIFIER un node : éditer src/nodes/<NODE>.js, puis node tools/n8n-push.mjs workflows/evcs-surplus-controller-v2.6.json (build src→JSON + syntaxe + suite golden 19 scénarios + backup + PUT, tout automatique).
• Pour LIRE un node : lire src/nodes/<NODE>.js directement (PAS le MCP, pas le JSON).
• JAMAIS éditer le JSON du workflow ni l'UI n8n directement : le prochain push écrase avec src/. (Si ça arrive quand même : node tools/n8n-extract.mjs resynchronise.)
• Tests : node tests/golden/run.mjs (19 scénarios figés). Toute évolution voulue du comportement → mettre à jour tests/golden/scenarios.mjs dans le même commit.
• Les dossiers archive/ (ex decoupesurplus/, WINDOWS/, BATTERY/...) sont des copies mortes : NE PLUS UTILISER.

Le MCP n8n-mcp_get_workflow renvoie le workflow ENTIER (~357K, trop gros pour le contexte). opencode l'écrit alors dans un fichier ~/.local/share/opencode/tool-output/tool_* et te le tronque.

⚠️ Ce fichier commence par une ligne de texte Retrieved workflow: <nom> AVANT le JSON. Donc :

• N'utilise JAMAIS json.load(f) ni json.loads(text) directement → ÉCHEC garanti (JSONDecodeError, le fichier ne commence pas par {).

MÉTHODE VALIDÉE pour extraire UN nœud (ex: DECISION_ENGINEV2) :

1. Localise-le : grep -n '"name": "NOM_DU_NOEUD"' <fichier_tool-output>
2. Extrais sa section : sed -n 'DEBUT,FINp' <fichier_tool-output> (repère les bornes d'accolades autour du nœud avec le grep). Si tu tiens à Python, retire d'abord le préfixe texte : text = open(f).read(); json_text = text[text.index('{'):]

🧭 MÉTHODE DE TRAVAIL

• UN nœud / UNE tâche à la fois. Ne charge JAMAIS le workflow complet.
• Avant toute écriture (patch/PUT/set) : backup ou dry-run, puis attends ma validation. Applique une seule action, vérifie, puis continue.
• Si un outil ou un parse échoue 2 fois : ARRÊTE et demande-moi comment procéder. Ne pars jamais en boucle de réessais.
• Toutes les valeurs d'énergie (SOC, PV, charge, grid, courant EVCS) se lisent via ha-get-state, jamais en dur.

⚡ CONTEXTE MÉTIER — Workflow "HA Snapshot EVCS Surplus Controller V2.6"

ID: ATswvGfG4KJUls0K (les V1/V1.2/V2.0 sont INACTIFS, ne pas y toucher). Nœud central de décision : DECISION_ENGINEV2 (id 1a8271fd-...). Stratégies (entrées via strategy.userStrategy) → context.sourceMode :

• auto_solar → sourceMode solar_only / solar_potential
• force_grid_now → strategy.forceGridRequested=true → grid_forced / grid_hc_allowed Garde-fous connus : effectiveSocStartFloor, commonSafetyStartOk, gridAllowedBySoc (SOC<=35 OU forceGridRequested → bypass), batteryAssistSolarStartOk (SOC>=90).

Quand tu analyses le pipeline complet (plusieurs nœuds), n'extrais que les lignes pertinentes (grep -n "name"/"jsCode" puis sed sur la plage), jamais le workflow JSON entier en mémoire Python. Traite un nœud, résume, libère.

Qwen3-VL — Traitement obligatoire des captures d'ecran

Quand le modele actif est qwen3-vl et que l'utilisateur fournit une ou plusieurs captures d'ecran, images d'interface, screenshots, photos d'ecran ou pieces jointes image, tu DOIS systematiquement appliquer cette procedure avant toute autre analyse.

Procedure obligatoire

Pour chaque image recue, produire une sortie structuree avec exactement les sections suivantes :

1. OCR brut

   • Recopier tout le texte visible dans l'image.
   • Conserver les chemins, noms de fichiers, commandes, messages d'erreur, URLs visibles, noms de modeles, ports, statuts et valeurs numeriques.
   • Ne pas corriger silencieusement le texte : si un caractere est incertain, l'indiquer avec [incertain].

2. Elements UI visibles

   • Decrire les boutons, menus, onglets, listes, champs, cases cochees, selection active, panneaux ouverts et zones importantes.
   • Indiquer les elements selectionnes ou mis en evidence.

3. Erreurs, warnings et indices techniques

   • Lister tous les messages d'erreur, warnings, traces, logs, codes HTTP, statuts Docker/vLLM/OpenCode/MCP ou signaux visuels de probleme.
   • Si aucun probleme n'est visible, ecrire : Aucune erreur visible.

4. Etat actuel deduit

   • Resumer ce que l'image montre concretement.
   • Distinguer les faits visibles des hypotheses.
   • Ne jamais inventer d'IP, URL, token, nom d'outil MCP ou valeur absente de l'image.

5. Actions recommandees

   • Proposer les prochaines actions sous forme courte et operationnelle.
   • Si l'image concerne n8n, Home Assistant, Victron, grid ou EVCS, respecter les regles MCP du projet : ne pas proposer de curl/wget/appel HTTP direct.
   • Si une information manque, demander a l'utilisateur au lieu de deviner.

Memoire partagee avec les autres modeles

Apres l'analyse, si la capture contient une information utile pour la suite de la session OpenCode, tu DOIS proposer ou creer un resume exploitable en texte dans :

docs/vision-notes.md

Format recommande :

# Vision notes
Source
Image(s) analysee(s) : <description courte>

# OCR brut
...

# Éléments UI
...

# Erreurs visibles
...

# État actuel
...

# Actions recommandées
...


Objectif : permettre a un autre modele texte, par exemple `minimax-m2.5`, de reutiliser l'information extraite sans avoir acces aux pixels de l'image.

### Regle critique

Ne considere jamais que les autres modeles ont acces a l'image originale. Toute information importante vue dans la capture doit etre explicitement convertie en texte dans la reponse ou dans `docs/vision-notes.md`.

Cette analyse doit précéder toute modification de workflow ou configuration.