--- title: "Monter la pile Fil en développement : le guide complet" subtitle: "Six services, deux façons de démarrer, sept variables optionnelles et huit pièges déjà rencontrés. Plus les lacunes qu'un guide honnête se doit d'avouer." date: 2026-09-15 time: "15:35" author: VFG publishedBy: idea status: pub tags: ["workflows-agentiques", "chronowflow", "fil", "environnement-dev", "fg-chronos", "vfgate", "fg-pulse", "agent-presence", "observabilite", "guide"] --- # Monter la pile Fil en développement : le guide complet Un Fil qui « n'affiche rien » a rarement un bug. C'est la première chose à comprendre avant d'installer quoi que ce soit : **Fil ne fabrique pas ses données**. Il lit des sources produites par d'autres services. Une interface vide est presque toujours le symptôme d'un service en amont éteint, pas d'une régression dans l'interface. Savoir cela fait gagner des heures — et transforme le diagnostic. Ce guide décrit tout ce qu'il faut monter pour développer Fil en local, dans quel ordre, et surtout ce qui casse quand une pièce manque. ## La chaîne, d'un bout à l'autre Chaque maillon est un processus séparé, sur un port distinct : ```text Claude Code / Codex / Cursor / Kimi │ hooks natifs ▼ VFGate :5191 (admin :5190) │ relais, interrogation toutes les 500 ms ▼ FG_Chronos :4340 ← le seul store durable │ API de lecture ▼ Fil (Chronowflow) :4477 FG_Pulse :4330 ──────────────────┐ dépôts git locaux ────────────────┼──▶ Fil blog.vfg.lol (distant) ───────────┘ Ollama :11434 → ai-usage-hub :11435 → VFGate ``` Trois propriétés structurent le reste : - **Fil lit, il n'écrit pas.** Il ne mute jamais le ledger de Chronos. « Masquer » un acte est une vue locale, pas une suppression côté source. - **Chronos est le seul stockage durable** de la chaîne de captation. Pulse et le blog sont lus à la volée. - **Le relais est le maillon fragile.** Sans lui, VFGate reçoit les événements mais rien n'atteint Chronos : tout « tourne », et Fil reste vide. ## Ce qu'il faut avoir | Composant | Rôle | Port | Obligatoire ? | |---|---|---|---| | **Fil** (Chronowflow) | l'interface | 4477 | oui | | **FG_Chronos** | le ledger | 4340 | oui | | **VFGate** | le bus d'intégration | 5191 / 5190 | oui pour la présence agents | | **relais VFGate→Chronos** | la jonction | — | oui pour la présence agents | | **FG_Pulse** | seconde source live | 4330 | recommandé | | **ai-usage-hub** | télémétrie usage | 11435 | optionnel | | **Ollama** | modèles locaux | 11434 | optionnel | | **dépôts git à observer** | source `git` | — | recommandé | Prérequis : **Node.js ≥ 20**, `git` dans le `PATH`, et PowerShell 5.1 pour les scripts de la chaîne. ## Trois pièges de topologie (avant de chercher) Ils coûtent du temps parce qu'ils contredisent l'intuition : 1. **Fil n'est pas dans le workspace principal.** Il vit dans son propre dépôt, hors de l'arborescence des projets. Le chercher au mauvais endroit fait perdre un temps certain. 2. **Chronos n'a aucun dépôt dédié.** C'est un dossier *à l'intérieur* d'un autre dépôt. Il n'apparaît donc dans aucun registre de projets — on y revient plus bas, car c'est la cause d'une vraie collision. 3. **Le dossier de VFGate porte encore son ancien nom.** Son nom npm est `vfgate`, mais le répertoire s'appelle toujours `BDDBridgePOC`. Le lien n'est pas évident. ## Deux façons de démarrer ### La voie scriptée — une commande Une installation initiale, puis un lanceur : ```powershell # une seule fois powershell -NoProfile -File \FG_Chronos\scripts\install-agent-presence.ps1 # à chaque session powershell -NoProfile -File \FG_Chronos\scripts\start-agent-presence.ps1 ``` Le lanceur démarre les services absents dans le bon ordre et ouvre Fil. > ⚠️ **Attention, ce lanceur exécute Fil en build de production.** S'il ne trouve pas de build existant, il reconstruit puis démarre. Conséquence : **modifier le code source ne change rien à ce qui est servi** tant que tu ne reconstruis pas. Pour développer l'interface, utilise la voie manuelle. ### La voie manuelle — service par service C'est celle du développement actif : un terminal par service. ```powershell # 1. Chronos — le ledger (la source qui compte) cd \FG_Chronos npm install node src/server.js # → :4340 # 2. VFGate — le bus cd \BDDBridgePOC npm install npm run start:api # → :5191 # 3. Le relais, indispensable entre 1 et 2 cd \FG_Chronos node scripts/relay-vfgate.mjs # 4. Pulse — seconde source live cd \FG_Pulse npm install npm start # → :4330 # 5. Fil — l'interface, avec rechargement à chaud cd \Chronowflow npm install npm run dev # → :4477 ``` Fil démarre **même si tout le reste est éteint** : il affichera des sources éteintes plutôt que de planter. C'est délibéré, et c'est ce qui rend le diagnostic possible. ## Les variables — toutes optionnelles Aucun `.env` n'est nécessaire : sans configuration, Fil vise les adresses locales par défaut. | Variable | Défaut | Rôle | |---|---|---| | `CHRONOS_URL` | `http://127.0.0.1:4340` | le ledger | | `PULSE_URL` | `http://127.0.0.1:4330` | Pulse | | `BLOG_URL` | `https://blog.vfg.lol` | source distante | | `VFJAH_URL` | `http://127.0.0.1:5210` | source *déclarée* | | `VFJAH_ADMIN_TOKEN` | — | jeton admin | | `FIL_GIT_REPOS` | — | dépôts à observer | La source `git` lit les derniers commits de chaque dépôt fourni. Le paramètre d'URL `?repos=` prend le pas sur la variable d'environnement. ```powershell $env:FIL_GIT_REPOS = "\Chronowflow;\FG_Chronos" npm run dev ``` ## Vérifier que la chaîne est vivante Deux scripts répondent à 90 % des questions « pourquoi Fil est vide » : ```powershell # diagnostic : ports, unicité des processus, configurations, tâche planifiée powershell -NoProfile -File \FG_Chronos\scripts\doctor-agent-presence.ps1 # preuve de bout en bout : émet une session étiquetée et vérifie qu'elle traverse # la chaîne complète, puis se referme node \FG_Chronos\scripts\smoke-agent-workflow.mjs ``` Ensuite, dans Fil, le **bandeau de monitoring** de l'en-tête montre l'état de chaque source, le nombre d'items et le retard. C'est la première chose à regarder. > **`empty` n'est pas une panne.** Une source qui ne renvoie rien est « silencieuse » et ne dégrade pas le badge. Seuls les états franchement dégradés le font. Une source d'archive, elle, ne devient jamais périmée. Confondre le silence et la panne fait passer une pile saine pour cassée — c'est un piège que le projet a déjà payé une fois. ## Huit pièges déjà rencontrés | Piège | Symptôme | |---|---| | Un sous-dossier fait remonter au dépôt parent | Commits attribués au mauvais dépôt, silencieusement | | Un ancien processus garde le port | L'interface ne change pas après redémarrage | | Le lanceur sert un build de production | Le code modifié n'apparaît jamais | | Les variables ne passent pas au processus enfant | Configuration ignorée sans erreur | | La liste de tests est explicite, pas un motif | Un nouveau test ne tourne jamais, et la suite reste verte | | Le silence pris pour une panne | Badge faussement dégradé | | Un plafond masque des items | Données invisibles sans avertissement | | Une pénalité tronquée | Un score abaissé sans explication | Les deux derniers méritent d'être soulignés, parce qu'ils sont **silencieux par nature** et que le projet les a identifiés comme les plus dangereux : une ligne de compteur qui disparaît derrière un filtre transforme un plafond en perte de données, et une raison tronquée transforme un score en arbitraire. ## Les lacunes, assumées Un guide qui n'avoue pas ses trous fait perdre du temps à celui qui le suit. 1. **Le port du ledger est doublement revendiqué.** Un registre le déclare pour un autre service, alors qu'en réalité c'est le ledger qui l'occupe — et toute la chaîne en dépend. Les deux ne peuvent pas tourner ensemble. Le sujet est documenté et l'arbitrage est en attente : **déplacer un port sur un service central casse les relais, les défauts côté client, les scripts de diagnostic et les tests de fumée.** Ce n'est pas une correction mécanique. 2. **Le port de l'interface n'était pas enregistré.** Corrigé — mais l'oubli a tenu des semaines. 3. **La commande de synchronisation du registre est cassée.** Elle cherche sa source à des emplacements qui n'existent plus. **Ne pas la lancer.** 4. **Le registre local est en avance sur sa source**, de sept entrées. Le régénérer les effacerait en silence. C'est le sujet d'un article séparé, et il vaut la lecture. 5. **Le service qui cause la collision n'est déclaré nulle part** : sans dépôt ni entrée de projet, il reste capable de créer des collisions qu'aucun registre ne peut voir venir. 6. **La pagination historique n'est pas complète côté source** : la couverture est donc rapportée partielle, honnêtement, plutôt que gonflée. 7. **La captation ambiante est bruitée** — environ 200 items de bruit identifiés. La correction appartient à la source, pas à l'interface qui les affiche et les replie. ## Le minimum vital Si tu ne retiens qu'une chose : ```text Chronos :4340 ──┐ Pulse :4330 ──┼──▶ Fil :4477 git local ──┘ (npm run dev) blog distant ──┘ ``` 1. `node src/server.js` dans Chronos — **c'est la source qui compte**. 2. `node scripts/relay-vfgate.mjs` si tu veux voir la présence des agents. 3. `npm run dev` dans Fil. 4. Ouvrir l'interface et **lire le bandeau de monitoring**. Puis, en cas de problème : le doctor d'abord, le smoke ensuite. --- *Ce guide est la version publique d'un document d'environnement maintenu dans le dépôt de Fil, où il vit aux côtés des tutoriels d'usage. La partie registre de ports mérite son propre article : un registre de ports qui ment n'est jamais bruyant, il est faux en silence — et c'est bien pire.*