docs: README ultra détaillé + visites guidées ka2/ka4/ka6 (30 captures)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
31 changed files +269 −40
modified
README.md
+269 −40
@@ -1,18 +1,44 @@ | |||||
| 1 | # KA Guardian — ka2 · ka4 · ka6 | 1 | # KA Guardian — ka2 · ka4 · ka6 | ||
| 2 | 2 | ||||
| 3 | −Les trois agents gardiens autonomes du Groupe KA. Depuis le 2026-08-23, ka2/ka4/ka6 | 3 | +**Les trois agents gardiens autonomes du Groupe KA.** Un seul repo, trois instances, | ||
| 4 | −ne sont plus des bots de cartographie web : ce sont des **agents de maintenance | 4 | +trois salles de contrôle publiques : | ||
| 5 | −autonomes des connecteurs** des plateformes ·Ka, bâtis sur Claude (CLI headless). | 5 | + | ||
| 6 | +**[www.ka2.bot](https://www.ka2.bot)** · **[www.ka4.bot](https://www.ka4.bot)** · **[www.ka6.bot](https://www.ka6.bot)** | ||||
| 7 | + | ||||
| 8 | +Depuis le 2026-08-23, ka2/ka4/ka6 ne sont plus des bots de cartographie web : ce sont | ||||
| 9 | +des **agents de maintenance autonomes des connecteurs** des plateformes ·Ka, bâtis sur | ||||
| 10 | +Claude (CLI headless). Un connecteur tombe en panne quelque part dans l'écosystème ·Ka ? | ||||
| 11 | +Le gardien concerné le détecte, ouvre le code, le répare, prouve que ça marche — et si | ||||
| 12 | +ça empire, il revient au commit d'avant. **Tout ce qu'il fait est public, en direct.** | ||||
| 13 | + | ||||
| 14 | +--- | ||||
| 15 | + | ||||
| 16 | +## Les trois agents | ||||
| 17 | + | ||||
| 18 | +| Agent | Domaine | Port | Tagline | Périmètre | Accent | | ||||
| 19 | +|---|---|---|---|---|---| | ||||
| 20 | +| **ka2** | [www.ka2.bot](https://www.ka2.bot) | :8799 | Gardien immobilier & local | Lou·Ka, Immo·Ka, Resto·Ka, House·Ka, Rent·Ka | bleu `#a9d1f7` / `#1e4fa3` | | ||||
| 21 | +| **ka4** | [www.ka4.bot](https://www.ka4.bot) | :8899 | Gardien mobilité & quotidien | Auto·Ka, Food·Ka, Sorti·Ka | ambre `#ffc36b` / `#a35c00` | | ||||
| 22 | +| **ka6** | [www.ka6.bot](https://www.ka6.bot) | :8999 | Gardien flagship — gros volumes | Fabri·Ka, Job·Ka, Créa·Ka, Vrai·Prix **+ tout nouveau service** (défaut) | violet `#cdb4f9` / `#5b21b6` | | ||||
| 23 | + | ||||
| 24 | +L'identité de chaque agent (numéro, domaine, tagline, accents, services surveillés, | ||||
| 25 | +modèle Claude) vit dans **`topology.json`**, la source de vérité partagée entre | ||||
| 26 | +orchestrateurs et runners. Les pages web (`orchestrator/web/index.html`, | ||||
| 27 | +`commander.html`) sont des gabarits communs : les jetons `__NUM__`, `__DOMAIN__`, | ||||
| 28 | +`__TAGLINE__` sont rendus par agent au démarrage (`_render_page` dans `main.py`). | ||||
| 29 | +Chaque agent a sa bannière de partage OG (`orchestrator/web/og-ka{2,4,6}.png`, | ||||
| 30 | +servie à `/og.png`, régénérable via `deploy/make_og_images.py`), ses favicons et son | ||||
| 31 | +apple-touch-icon aux couleurs de son accent. | ||||
| 6 | 32 | ||||
| 7 | ## Aperçu des sites publics | 33 | ## Aperçu des sites publics | ||
| 8 | 34 | ||||
| 9 | −*Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900) — chaque gardien rend des comptes en direct sur son site.* | 35 | +*Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900) — chaque gardien rend des comptes en direct sur son site. Visites guidées détaillées (30 captures du 2026-08-28) plus bas.* | ||
| 10 | 36 | ||||
| 11 | <table> | 37 | <table> | ||
| 12 | <tr> | 38 | <tr> | ||
| 13 | − <td align="center"><img src="docs/screenshots/desktop/ka2.webp" width="300" alt="ka2.bot"><br><sub><b><a href="https://www.ka2.bot">ka2.bot</a> — gardien immobilier & local (lou-ka, immo-ka, resto-ka)</b></sub></td> | 39 | + <td align="center"><img src="docs/screenshots/desktop/ka2.webp" width="300" alt="ka2.bot"><br><sub><b><a href="https://www.ka2.bot">ka2.bot</a> — gardien immobilier & local</b></sub></td> | ||
| 14 | − <td align="center"><img src="docs/screenshots/desktop/ka4.webp" width="300" alt="ka4.bot"><br><sub><b><a href="https://www.ka4.bot">ka4.bot</a></b></sub></td> | 40 | + <td align="center"><img src="docs/screenshots/desktop/ka4.webp" width="300" alt="ka4.bot"><br><sub><b><a href="https://www.ka4.bot">ka4.bot</a> — gardien mobilité & quotidien</b></sub></td> | ||
| 15 | − <td align="center"><img src="docs/screenshots/desktop/ka6.webp" width="300" alt="ka6.bot"><br><sub><b><a href="https://www.ka6.bot">ka6.bot</a></b></sub></td> | 41 | + <td align="center"><img src="docs/screenshots/desktop/ka6.webp" width="300" alt="ka6.bot"><br><sub><b><a href="https://www.ka6.bot">ka6.bot</a> — gardien flagship</b></sub></td> | ||
| 16 | </tr> | 42 | </tr> | ||
| 17 | <tr> | 43 | <tr> | ||
| 18 | <td align="center"><img src="docs/screenshots/mobile/ka2.webp" width="200" alt="ka2 mobile"><br><sub>mobile</sub></td> | 44 | <td align="center"><img src="docs/screenshots/mobile/ka2.webp" width="200" alt="ka2 mobile"><br><sub>mobile</sub></td> | ||
@@ -21,56 +47,245 @@ autonomes des connecteurs** des plateformes ·Ka, bâtis sur Claude (CLI headles | |||||
| 21 | </tr> | 47 | </tr> | ||
| 22 | </table> | 48 | </table> | ||
| 23 | 49 | ||||
| 24 | −## Ce qu'ils font | 50 | +--- | ||
| 51 | + | ||||
| 52 | +## Cycle de vie d'une mission | ||||
| 53 | + | ||||
| 54 | +``` | ||||
| 55 | +api-ka /monitoring/connectors nœud de l'app (runner :7791) | ||||
| 56 | + │ (scan aux 5 min) │ | ||||
| 57 | + ▼ ▼ | ||||
| 58 | + ① DÉTECTION ──► incident ──► ② MISSION claude -p headless | ||||
| 59 | + │ (diagnostic, correctif minimal, | ||||
| 60 | + │ test réel, commit [kaX] …) | ||||
| 61 | + ▼ | ||||
| 62 | + ③ SURVEILLANCE 8 h (watching) | ||||
| 63 | + │ | ||||
| 64 | + ┌───────────────┴───────────────┐ | ||||
| 65 | + ▼ ▼ | ||||
| 66 | + connecteur ok toujours cassé / app down | ||||
| 67 | + → RÉSOLU ④ ROLLBACK git + pm2 restart | ||||
| 68 | + (3 tentatives max → abandoned) | ||||
| 69 | +``` | ||||
| 25 | 70 | ||||
| 26 | 1. **Détection** — toutes les 5 min, chaque agent lit la supervision centralisée | 71 | 1. **Détection** — toutes les 5 min, chaque agent lit la supervision centralisée | ||
| 27 | − d'api-ka (`/api/v1/monitoring/connectors`, ~2 600 connecteurs classés | 72 | + d'api-ka (`/api/v1/monitoring/connectors`, ~2 800 connecteurs classés | ||
| 28 | ok/degraded/broken/stale toutes les 2 h). Un connecteur `broken` ou `stale` | 73 | ok/degraded/broken/stale toutes les 2 h). Un connecteur `broken` ou `stale` | ||
| 29 | de son périmètre → incident. | 74 | de son périmètre → incident. | ||
| 30 | 2. **Mission** — l'agent dépêche une mission au **runner** du nœud qui héberge | 75 | 2. **Mission** — l'agent dépêche une mission au **runner** du nœud qui héberge | ||
| 31 | − l'app : `claude -p` headless, lancé dans le repo de l'app, avec un prompt de | 76 | + l'app : `claude -p` headless (Claude Code CLI, `--output-format stream-json`), | ||
| 32 | − mission strict (diagnostiquer, reproduire, corriger minimalement, re-tester, | 77 | + lancé dans le repo de l'app, avec un prompt de mission strict : diagnostiquer, | ||
| 33 | − `pm2 restart` du process de sync, commit `[kaX] fix connecteur …`, jamais de push). | 78 | + reproduire, corriger minimalement (mêmes patterns que les connecteurs voisins), | ||
| 79 | + re-tester en volume réel, `pm2 restart` du process de sync, commit | ||||
| 80 | + `[kaX] fix connecteur …` — **jamais de push par la mission elle-même** | ||||
| 81 | + (voir le pousseur plus bas). La pile d'escalade anti-bot du Groupe KA | ||||
| 82 | + (curl → Scrapfly → Bright Data → proxys résidentiels Oxylabs → Serper/Tavily) | ||||
| 83 | + est à sa disposition sur le nœud. | ||||
| 34 | 3. **Surveillance** — après réparation déclarée, l'incident passe en `watching` | 84 | 3. **Surveillance** — après réparation déclarée, l'incident passe en `watching` | ||
| 35 | pendant 8 h. Connecteur de retour à `ok` → résolu. | 85 | pendant 8 h. Connecteur de retour à `ok` → résolu. | ||
| 36 | 4. **Rollback automatique** — si l'app tombe (healthcheck) ou si le connecteur | 86 | 4. **Rollback automatique** — si l'app tombe (healthcheck) ou si le connecteur | ||
| 37 | est toujours cassé après la fenêtre : retour au commit d'avant mission | 87 | est toujours cassé après la fenêtre : retour au commit d'avant mission | ||
| 38 | − (`git reset --hard`/revert) + `pm2 restart`. 3 tentatives max, puis `abandoned` | 88 | + (`git reset --hard`/revert) + `pm2 restart`. 3 tentatives max (cooldown 6 h | ||
| 39 | − (intervention humaine). | 89 | + entre tentatives), puis `abandoned` (intervention humaine, ré-examen après 7 jours). | ||
| 40 | −5. **Vitrine live** — chaque site (www.ka2.bot / www.ka4.bot / www.ka6.bot) est | 90 | +5. **Vitrine live** — chaque site est une salle de contrôle : flux SSE en direct de | ||
| 41 | − une salle de contrôle : flux SSE en direct de chaque action de l'agent | 91 | + chaque action de l'agent (outils, réflexions, verdicts), board d'incidents, | ||
| 42 | − (outils, réflexions, verdicts), board d'incidents, couverture par service, | 92 | + couverture par service (« Territoire surveillé »), registre des missions avec | ||
| 43 | − historique des missions avec transcript et coût. | 93 | + transcript complet, nombre de tours, durée et coût API par mission. | ||
| 94 | + | ||||
| 95 | +### Garde-fous (politique `topology.json`) | ||||
| 44 | 96 | ||||
| 45 | −## Répartition | 97 | +- 1 mission à la fois par agent **et** par nœud (le runner refuse s'il est occupé). | ||
| 98 | +- Plafonds de mission : 70 tours / 1 h (efforts commandés : 150 tours / 2 h). | ||||
| 99 | +- Seuil d'incident de masse (≥ 20 connecteurs d'un coup) : pas de missions en | ||||
| 100 | + rafale — c'est presque toujours une panne d'infrastructure, pas 20 bugs. | ||||
| 101 | +- Push git **jamais** fait par la mission : commits `[kaX]` locaux seulement, | ||||
| 102 | + poussés par le pousseur (chaîne launchd de confiance, voir Architecture). | ||||
| 46 | 103 | ||||
| 47 | −| Agent | Domaine | Services surveillés | | 104 | +## Veilleur de sites (2026-08-25) | ||
| 48 | −|---|---|---| | 105 | + | ||
| 49 | −| ka2 | www.ka2.bot :8799 | louka, immoka, restoka | | 106 | +En plus des connecteurs, chaque agent surveille le **site public** de chacun de ses | ||
| 50 | −| ka4 | www.ka4.bot :8899 | autoka, foodka, sortika | | 107 | +services (`site_engine` dans `main.py`, source d'incident `_site`) : | ||
| 51 | −| ka6 | www.ka6.bot :8999 | fabrika, jobka, creaka + tout nouveau service (défaut) | | 108 | + | ||
| 109 | +1. GET du site de chaque service toutes les 120 s ; down = ≥ 500/timeout, confirmé | ||||
| 110 | + par un 2ᵉ essai puis 2 cycles consécutifs. | ||||
| 111 | +2. Down confirmé → **pm2 restart automatique** via l'endpoint `/restart` du runner | ||||
| 112 | + du nœud (throttle 10 min), re-check du site. | ||||
| 113 | +3. Toujours down → incident `site_down` (priorité max au dispatch) → **mission | ||||
| 114 | + Claude d'investigation** sur le nœud : logs pm2, cause racine (crash, port, | ||||
| 115 | + build, DB, disque, tunnel ngrok), correctif minimal, commit. | ||||
| 116 | +4. Cycle standard ensuite : watching (fenêtre courte 1 h), rollback si faux | ||||
| 117 | + « réparé », cooldown 1 h, max 3 tentatives puis abandon (ré-examen après 24 h). | ||||
| 118 | + Les restarts automatiques continuent pendant les cooldowns. | ||||
| 119 | + | ||||
| 120 | +`vraiprix` (M3U96a, :8090) est un service **site seulement** de ka6 : aucun | ||||
| 121 | +connecteur sous api-ka, seule la surveillance du site s'applique. | ||||
| 122 | + | ||||
| 123 | +## Efforts commandés — la page `/commander` | ||||
| 124 | + | ||||
| 125 | +Chaque site expose un **poste de commande** (`/commander`, « Donne-lui du | ||||
| 126 | +travail. ») : un opérateur muni du **jeton d'opérateur** (jamais publié — il vit | ||||
| 127 | +dans `~/.ka-guardian.env` des nœuds) peut commander un effort autonome à l'agent : | ||||
| 128 | + | ||||
| 129 | +| Type d'effort | Ce que fait l'agent | | ||||
| 130 | +|---|---| | ||||
| 131 | +| **Nouveau connecteur** (`effort_new`) | Cartographie l'existant, **découvre des sources québécoises non couvertes via Serper** (gl=ca, hl=fr — sitemaps, pages listes, endpoints JSON internes), évalue 3-5 candidats (volume, faisabilité, qualité, stabilité), choisit le meilleur et construit le connecteur complet — testé en volume réel. | | ||||
| 132 | +| **Enrichissement** (`effort_enrich`) | Améliore un connecteur existant : couverture, champs, robustesse. | | ||||
| 133 | +| **Inspection des dégradés** (`effort_degrade`) | Passe en revue les connecteurs `degraded` du service et les remet d'aplomb. | | ||||
| 134 | + | ||||
| 135 | +L'opérateur fixe **la laisse** : durée max et budget max (coût API estimé en direct). | ||||
| 136 | +Plafond atteint → la session s'arrête proprement ; les réparations déjà committées | ||||
| 137 | +et testées sont conservées si la plateforme est saine. Une consigne libre optionnelle | ||||
| 138 | +oriente l'agent (« vise les microbrasseries de la Côte-Nord… »). Chaque effort est | ||||
| 139 | +journalisé action par action dans le flux, listé dans « Efforts commandés récents », | ||||
| 140 | +et annulable par rollback git. Contrairement aux incidents api-ka, un effort livré | ||||
| 141 | +est validé par healthcheck de l'app (pas par la supervision) : app en échec | ||||
| 142 | +post-effort → rollback préventif automatique. | ||||
| 143 | + | ||||
| 144 | +API équivalente : `POST /api/admin/effort` (header `X-KA-Token`). | ||||
| 145 | + | ||||
| 146 | +--- | ||||
| 52 | 147 | ||||
| 53 | ## Architecture | 148 | ## Architecture | ||
| 54 | 149 | ||||
| 55 | −- `orchestrator/` — un process FastAPI par agent (M4M36, launchd | 150 | +``` | ||
| 56 | − `com.kaX.guardian`), SQLite `data/kaX.db`, dashboard servi sur le même port, | 151 | + M4M36 (nœud orchestrateur) | ||
| 57 | − tunnels ngrok existants conservés. | 152 | + ┌────────────────────────────────────────────────────────────┐ | ||
| 58 | −- `runner/` — un service par nœud d'app (M3U96a/b, M4M64a/b, port 7791, launchd | 153 | + │ com.ka2.guardian :8799 com.ka4.guardian :8899 │ | ||
| 59 | − `com.ka.guardian-runner`), 1 mission à la fois par nœud, transcripts dans | 154 | + │ com.ka6.guardian :8999 (FastAPI + SQLite data/kaX.db) │ | ||
| 60 | − `~/ka-guardian-runner/transcripts/`. Exécute `claude -p --output-format | 155 | + │ ngrok com.kaX.ngrok → www.ka2.bot / ka4.bot / ka6.bot │ | ||
| 61 | − stream-json` et relaie chaque événement à l'orchestrateur (`/api/ingest`). | 156 | + │ courrier zsh com.ka.guardian-courier (spool → ssh+curl) │ | ||
| 62 | −- `topology.json` — source de vérité : agents, services (nœud/dir/pm2/port), | 157 | + └───────────────┬────────────────────────────────────────────┘ | ||
| 63 | − IP LAN, politique (fenêtres, cooldowns, modèle). | 158 | + │ LAN 192.168.2.x uniquement (via le courrier) | ||
| 64 | −- Auth interne : token partagé `~/.ka-guardian.env` (orchestrateurs + runners), | 159 | + ┌────────────┼──────────────┬──────────────┬──────────────┐ | ||
| 65 | − header `X-KA-Token`. Clé Anthropic + clés anti-bot : `~/.claude/.env` des nœuds. | 160 | + ▼ ▼ ▼ ▼ ▼ | ||
| 66 | −- Communication **par le LAN 192.168.2.x** (SSH/Tailscale inter-nœuds bloqué). | 161 | + M3U96a M3U96b M4M64a M4M64b M4M36 | ||
| 162 | + runner :7791 (com.ka.guardian-runner) sur chaque nœud d'app | ||||
| 163 | + + pousseur git com.ka.pousseur (nœuds à repos Ka) | ||||
| 164 | +``` | ||||
| 165 | + | ||||
| 166 | +- **`orchestrator/`** — un process FastAPI par agent (M4M36, launchd | ||||
| 167 | + `com.kaX.guardian`, env `AGENT=ka2|ka4|ka6`), SQLite `data/kaX.db`, dashboard | ||||
| 168 | + servi sur le même port (flux SSE, board incidents, couverture, registre des | ||||
| 169 | + missions + transcripts, `/commander`), tunnels ngrok existants conservés. | ||||
| 170 | +- **`runner/`** — un service par nœud d'app (M3U96a/b, M4M64a/b, M4M36 ; :7791, | ||||
| 171 | + launchd `com.ka.guardian-runner`), **1 mission à la fois par nœud**, transcripts | ||||
| 172 | + dans `~/ka-guardian-runner/transcripts/`. Exécute `claude -p --output-format | ||||
| 173 | + stream-json` dans le repo de l'app et relaie chaque événement à l'orchestrateur | ||||
| 174 | + (`/api/ingest`). Expose aussi `/restart` (pm2) pour le veilleur de sites et | ||||
| 175 | + `/health` (`busy`). ⚠️ Ne jamais redémarrer un runner occupé : ça tue la | ||||
| 176 | + mission Claude en vol. | ||||
| 177 | +- **`topology.json`** — source de vérité : agents (port/domaine/accent/tagline/ | ||||
| 178 | + modèle/services), services (app, nœud, dir, process pm2, port web, site), | ||||
| 179 | + IP LAN des nœuds, politique (fenêtres, cooldowns, plafonds). | ||||
| 180 | +- **`deploy/courier.sh`** — courrier inter-nœuds 100 % zsh (launchd | ||||
| 181 | + `com.ka.guardian-courier`). macOS 26 « Local Network Privacy » refuse le trafic | ||||
| 182 | + LAN dès que python (homebrew) est dans la chaîne de processus ; le courrier | ||||
| 183 | + (binaire responsable : zsh) expédie donc les requêtes via spool : | ||||
| 184 | + `spool/outbox/<id>.job → ssh <nœud> curl http://127.0.0.1:<port><path>` → | ||||
| 185 | + `spool/done/<id>.resp`, avec 3 tentatives et multiplexage SSH. Ne pas le contourner. | ||||
| 186 | +- **`deploy/pousseur.sh`** — pousseur git (launchd `com.ka.pousseur` sur les nœuds | ||||
| 187 | + qui hébergent des repos Ka). Chaîne 100 % binaires Apple | ||||
| 188 | + (launchd → zsh → `/usr/bin/git` → `/usr/bin/ssh`) : contourne le blocage LNP des | ||||
| 189 | + `git push` lancés par les missions (descendants du runner python homebrew). | ||||
| 190 | + Toutes les 5 min, pousse vers spbgit les commits en attente des repos listés dans | ||||
| 191 | + `~/.ka-pousseur-repos`. Push **simple** uniquement (jamais de force) : un | ||||
| 192 | + non-fast-forward est loggé, jamais résolu d'autorité. | ||||
| 193 | +- **Auth interne** — token partagé entre orchestrateurs et runners (fichier | ||||
| 194 | + `~/.ka-guardian.env` sur chaque nœud, header `X-KA-Token`). Clé Anthropic et | ||||
| 195 | + clés anti-bot : `~/.claude/.env` des nœuds. **Aucun secret dans ce repo.** | ||||
| 196 | +- **Communication par le LAN 192.168.2.x** (SSH/Tailscale inter-nœuds bloqué par ACL). | ||||
| 197 | + | ||||
| 198 | +--- | ||||
| 199 | + | ||||
| 200 | +## Visite guidée — ka2 (www.ka2.bot) | ||||
| 201 | + | ||||
| 202 | +*Gardien immobilier & local — Lou·Ka, Immo·Ka, Resto·Ka, House·Ka, Rent·Ka. Captures du 2026-08-28 (desktop 1440×900, mobile 390×844).* | ||||
| 203 | + | ||||
| 204 | +| Capture | Description | | ||||
| 205 | +|---|---| | ||||
| 206 | +|  | **Accueil** — héro « Il veille. Il répare. Il rend des comptes. », définition *gar·dien* (détecte / répare / surveille / recule), tuiles « L'état du gardien » (1 378 connecteurs sous garde, incidents actifs, missions lancées, réparations confirmées, rollbacks assumés, temps moyen de guérison, coût API total) et amorce du flux temps réel + board d'incidents. | | ||||
| 207 | +|  | **Poste de commande `/commander`** — « Donne-lui du travail. » : type d'effort (nouveau connecteur avec découverte Serper, enrichissement, inspection des dégradés), plateforme cible (avec son nœud), consigne libre, laisse durée max / coût max et champ jeton d'opérateur. | | ||||
| 208 | +|  | **Territoire surveillé** — couverture live par service : Lou·Ka (M3U96b, 431 connecteurs), Immo·Ka (M4M64A, 140), Resto·Ka (14), House·Ka (M4M64B, 25), Rent·Ka (M4M36, 768), chacun avec sa barre ok/dégradé/cassé/endormi ; en dessous, l'entête du registre des missions. | | ||||
| 209 | +|  | **Registre des missions (récentes)** — une ligne par mission : horodatage, connecteur, service, nœud, verdict (ici « RIEN À FAIRE »), commits, tours · durée, coût API. Cliquer une ligne ouvre le déroulé complet, commits inclus. | | ||||
| 210 | +|  | **Registre des missions (suite)** — tout l'éventail des verdicts en conditions réelles : RÉPARÉ, ÉCHEC, RIEN À FAIRE, LIVRÉ (efforts commandés), INCONNU, avec tentatives, commits et coûts (de 0,10 $ à 3,64 $ la mission). | | ||||
| 211 | +|  | **Fin du registre + pied de page « Zéro boîte noire »** — « Chaque diagnostic, chaque commit, chaque rollback de cet agent est journalisé et affiché ici. Les réparations sont committées dans les repos des plateformes, jamais poussées sans passage humain. » Liens vers les plateformes gardées et les agents frères. | | ||||
| 212 | +|  | **Accueil mobile** — la salle de contrôle complète en 390×844 : héro, tuiles d'état, flux, incidents, territoire, registre. | | ||||
| 213 | +|  | **`/commander` — bas de page** — plafonds (durée, coût max estimé en direct), jeton d'opérateur, bouton « Lancer l'effort → », liste « Efforts commandés récents » avec statuts (LIVRÉ / TERMINÉ) et rappel « La laisse est réelle ». | | ||||
| 214 | +|  | **Poste de commande mobile** — le formulaire d'effort complet au téléphone. | | ||||
| 215 | +|  | **Flux en temps réel (SSE)** — le terminal « KA2 — FLUX EN TEMPS RÉEL » : chaque outil, réflexion et verdict de l'agent y est diffusé en direct ; au repos, « en attente d'activité — le gardien scrute api-ka toutes les 5 minutes… ». | | ||||
| 216 | + | ||||
| 217 | +## Visite guidée — ka4 (www.ka4.bot) | ||||
| 218 | + | ||||
| 219 | +*Gardien mobilité & quotidien — Auto·Ka, Food·Ka, Sorti·Ka. Accent ambre.* | ||||
| 220 | + | ||||
| 221 | +| Capture | Description | | ||||
| 222 | +|---|---| | ||||
| 223 | +|  | **Accueil** — même gabarit que ses frères, aux couleurs de ka4 : héro, définition *gar·dien*, tuiles d'état de son périmètre mobilité & quotidien, flux temps réel et incidents. | | ||||
| 224 | +|  | **Poste de commande `/commander`** — commander un effort à ka4 : nouveau connecteur (découverte Serper), enrichissement ou inspection des dégradés sur Auto·Ka, Food·Ka ou Sorti·Ka, avec laisse durée/coût et jeton d'opérateur. | | ||||
| 225 | +|  | **Flux + incidents + Territoire surveillé** — couverture live des trois services (Auto·Ka sur M4M64b, Food·Ka sur M4M64b, Sorti·Ka sur M3U96a) avec barres ok/dégradé/cassé/endormi, puis le registre des missions. | | ||||
| 226 | +|  | **Accueil mobile** — la salle de contrôle ka4 en 390×844. | | ||||
| 227 | +|  | **`/commander` — bas de page** — plafonds, jeton d'opérateur et « Efforts commandés récents » de ka4. | | ||||
| 228 | +|  | **Poste de commande mobile.** | | ||||
| 229 | +|  | **Flux en temps réel (1/4)** — le terminal SSE de ka4. | | ||||
| 230 | +|  | **Flux en temps réel (2/4)** — chaque action de mission (outil lancé, fichier lu, test exécuté) s'affiche ici à mesure. | | ||||
| 231 | +|  | **Flux en temps réel (3/4)** — le même flux que consomme le board d'incidents et le registre. | | ||||
| 232 | +|  | **Flux en temps réel (4/4)** — au repos : « en attente d'activité — le gardien scrute api-ka toutes les 5 minutes… ». | | ||||
| 233 | + | ||||
| 234 | +## Visite guidée — ka6 (www.ka6.bot) | ||||
| 235 | + | ||||
| 236 | +*Gardien flagship — gros volumes : Fabri·Ka, Job·Ka, Créa·Ka, Vrai·Prix (site seulement) + tout nouveau service par défaut. Accent violet.* | ||||
| 237 | + | ||||
| 238 | +| Capture | Description | | ||||
| 239 | +|---|---| | ||||
| 240 | +|  | **Accueil** — le plus gros périmètre du trio : 2 819 connecteurs sous garde, 251 missions lancées, 89 réparations confirmées, 14 rollbacks assumés, 3,3 h de temps moyen de guérison ; incidents en SURVEILLANCE (fabrika, jobka) visibles au chargement. | | ||||
| 241 | +|  | **Poste de commande `/commander`** — commander un effort à ka6 sur Fabri·Ka, Job·Ka ou Créa·Ka (nouveau connecteur découvert via Serper, enrichissement, inspection des dégradés). | | ||||
| 242 | +|  | **Flux + incidents + Territoire surveillé** — couverture live de Fabri·Ka (M4M64a), Job·Ka (M3U96a), Créa·Ka (M3U96b) et Vrai·Prix (M3U96a, surveillance du site seulement). | | ||||
| 243 | +|  | **Registre des missions (1/5)** — le registre le plus long du trio : gros volumes = plus d'incidents, plus de missions, plus de verdicts. | | ||||
| 244 | +|  | **Registre des missions (2/5)** — missions récentes avec verdicts, tours, durées et coûts par connecteur. | | ||||
| 245 | +|  | **Registre des missions (3/5)** — l'historique se déroule : réparations confirmées, échecs assumés, missions « rien à faire ». | | ||||
| 246 | +|  | **Registre des missions (4/5)** — chaque ligne reste cliquable : déroulé complet de la mission, commits inclus. | | ||||
| 247 | +|  | **Registre des missions (5/5) + pied de page « Zéro boîte noire »** — fin de l'historique et engagement de transparence. | | ||||
| 248 | +|  | **Accueil mobile** — la salle de contrôle ka6 en 390×844. | | ||||
| 249 | +|  | **`/commander` — bas de page** — plafonds, jeton d'opérateur et « Efforts commandés récents » de ka6. | | ||||
| 250 | + | ||||
| 251 | +--- | ||||
| 252 | + | ||||
| 253 | +## Transparence publique | ||||
| 254 | + | ||||
| 255 | +Le principe fondateur des gardiens : **zéro boîte noire.** | ||||
| 256 | + | ||||
| 257 | +- Chaque diagnostic, chaque commit, chaque rollback est journalisé et affiché en | ||||
| 258 | + direct sur le site de l'agent (flux SSE, board d'incidents, registre des missions | ||||
| 259 | + avec transcript, tours, durée et coût API au cent près). | ||||
| 260 | +- Les réparations sont committées `[kaX] …` dans les repos des plateformes et | ||||
| 261 | + poussées par le pousseur vers le git du Groupe — jamais de force-push, jamais de | ||||
| 262 | + résolution d'autorité. | ||||
| 263 | +- Les trois agents sont présentés publiquement sur | ||||
| 264 | + **[groupe-ka.com/bots](https://www.groupe-ka.com/bots)**, et chaque site gardien | ||||
| 265 | + lie ses frères et les plateformes qu'il garde. | ||||
| 266 | +- Les actions sensibles (`/commander`, API admin) exigent le jeton d'opérateur — | ||||
| 267 | + la consultation, elle, est ouverte à tous. | ||||
| 67 | 268 | ||||
| 68 | ## Déploiement | 269 | ## Déploiement | ||
| 69 | 270 | ||||
| 271 | +- **Nœud de production : M4M36** — répertoire `~/cluster-projects/ka-guardian` | ||||
| 272 | + (ce repo, origin = gitsrv/spbgit `ka-guardian.git`). | ||||
| 273 | +- **Process : launchd** (PAS pm2) — `com.ka2.guardian` (:8799), `com.ka4.guardian` | ||||
| 274 | + (:8899), `com.ka6.guardian` (:8999). Tunnels ngrok `com.kaX.ngrok` (ne pas toucher). | ||||
| 275 | +- Pas d'étape de build : Python servi en place (`.venv` local au nœud). | ||||
| 276 | + | ||||
| 70 | ```bash | 277 | ```bash | ||
| 71 | −deploy/deploy.sh all # runners + orchestrateurs | 278 | +deploy/deploy.sh all # runners + orchestrateurs (+ courrier) | ||
| 72 | −deploy/deploy.sh runners # seulement les 4 runners | 279 | +deploy/deploy.sh runners # seulement les 5 runners (refuse un runner occupé) | ||
| 73 | −deploy/deploy.sh orchestrators | 280 | +deploy/deploy.sh orchestrators # ka2/ka4/ka6 sur M4M36 (tar-over-ssh + md5 + relance launchd) | ||
| 281 | +``` | ||||
| 282 | + | ||||
| 283 | +Après toute modification sur M4M36 : | ||||
| 284 | + | ||||
| 285 | +```bash | ||||
| 286 | +launchctl kickstart -k gui/$(id -u)/com.ka2.guardian # idem ka4/ka6 | ||||
| 287 | +curl -sf localhost:8799/health # puis 8899, 8999 + site public | ||||
| 288 | +git add … && git commit && git push origin main # origin = gitsrv/spbgit, PAS GitHub | ||||
| 74 | ``` | 289 | ``` | ||
| 75 | 290 | ||||
| 76 | ## Admin (token requis) | 291 | ## Admin (token requis) | ||
@@ -79,10 +294,24 @@ deploy/deploy.sh orchestrators | |||||
| 79 | # mission manuelle sur un connecteur | 294 | # mission manuelle sur un connecteur | ||
| 80 | curl -X POST http://M4M36.maclustr.io:8799/api/admin/mission \ | 295 | curl -X POST http://M4M36.maclustr.io:8799/api/admin/mission \ | ||
| 81 | -H "X-KA-Token: $TOKEN" -d '{"service":"louka","source":"kijiji"}' | 296 | -H "X-KA-Token: $TOKEN" -d '{"service":"louka","source":"kijiji"}' | ||
| 297 | +# effort commandé (équivalent API de /commander) | ||||
| 298 | +curl -X POST http://M4M36.maclustr.io:8799/api/admin/effort \ | ||||
| 299 | + -H "X-KA-Token: $TOKEN" -d '{"kind":"effort_new","service":"restoka"}' | ||||
| 82 | # pause / reprise d'un agent | 300 | # pause / reprise d'un agent | ||
| 83 | −curl -X POST http://M4M36.maclustr.io:8799/api/admin/pause -H "X-KA-Token: $TOKEN" -d '{"paused":true}' | 301 | +curl -X POST http://M4M36.maclustr.io:8799/api/admin/pause \ | ||
| 302 | + -H "X-KA-Token: $TOKEN" -d '{"paused":true}' | ||||
| 84 | ``` | 303 | ``` | ||
| 85 | 304 | ||||
| 305 | +## Repo & contact | ||||
| 306 | + | ||||
| 307 | +- **Repo** : `ka-guardian.git` sur **spbgit** (le git personnel du Groupe — | ||||
| 308 | + git.spboucher.ai, bare repos sur M3U96a). Origin des nœuds : `gitsrv:srv/git/ka-guardian.git`. | ||||
| 309 | +- **Structure** : `orchestrator/` (main.py + web/), `runner/runner.py`, | ||||
| 310 | + `deploy/` (deploy.sh, courier.sh, pousseur.sh, make_og_images.py), | ||||
| 311 | + `topology.json`, `docs/screenshots/`. | ||||
| 312 | +- **Contact** : [groupe-ka.com](https://www.groupe-ka.com) — Groupe KA, | ||||
| 313 | + agrégation automatisée, Québec. | ||||
| 314 | + | ||||
| 86 | ## Historique | 315 | ## Historique | ||
| 87 | 316 | ||||
| 88 | Les anciens bots (cartographie du web québécois / influenceurs) sont archivés : | 317 | Les anciens bots (cartographie du web québécois / influenceurs) sont archivés : | ||
added
docs/screenshots/ka2/01-accueil.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/02-commander.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/03-accueil-section-1.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/04-accueil-section-2.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/05-accueil-section-3.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/06-accueil-section-4.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/07-accueil-mobile.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/08-commander-section-1.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/09-commander-mobile.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka2/10-accueil-flux-10.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/01-accueil.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/02-commander.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/03-accueil-section-1.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/04-accueil-mobile.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/05-commander-section-1.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/06-commander-mobile.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/07-accueil-flux-7.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/08-accueil-flux-8.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/09-accueil-flux-9.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka4/10-accueil-flux-10.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/01-accueil.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/02-commander.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/03-accueil-section-1.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/04-accueil-section-2.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/05-accueil-section-3.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/06-accueil-section-4.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/07-accueil-section-5.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/08-accueil-section-6.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/09-accueil-mobile.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/ka6/10-commander-section-1.jpg
+0 −0
Binary file not shown.