1ae8129658
- src/nodes/*.js (6 nodes + template snapshot) = source de vérité unique. - n8n-push.mjs reconstruit le JSON depuis src/ avant syntaxe+golden+PUT (src gagne toujours; n8n-extract.mjs pour resynchroniser si édition UI). - n8n-build.mjs --check pour vérifier la synchro. - Copies historiques déplacées dans archive/ (mortes, dérivées de la prod). - .gitignore: backups locaux de rollback. - AGENTS.md: règle R2 pour toutes les futures sessions (dont Qwen local). - Validé: idempotence, mutation/restauration, pipeline push complet en réel.
147 lines
6.7 KiB
Markdown
147 lines
6.7 KiB
Markdown
# 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 :
|
|
|
|
```md
|
|
# 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.
|