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 | 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 | |
| 4 | −ne sont plus des bots de cartographie web : ce sont des **agents de maintenance | |
| 5 | −autonomes des connecteurs** des plateformes ·Ka, bâtis sur Claude (CLI headless). | |
| 3 | +**Les trois agents gardiens autonomes du Groupe KA.** Un seul repo, trois instances, | |
| 4 | +trois salles de contrôle publiques : | |
| 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 | 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 | 37 | <table> |
| 12 | 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> | |
| 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> | |
| 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> | |
| 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> | |
| 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> | |
| 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 | 42 | </tr> |
| 17 | 43 | <tr> |
| 18 | 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 | 47 | </tr> |
| 22 | 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 | 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 | 73 | ok/degraded/broken/stale toutes les 2 h). Un connecteur `broken` ou `stale` |
| 29 | 74 | de son périmètre → incident. |
| 30 | 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 | |
| 32 | − mission strict (diagnostiquer, reproduire, corriger minimalement, re-tester, | |
| 33 | − `pm2 restart` du process de sync, commit `[kaX] fix connecteur …`, jamais de push). | |
| 76 | + l'app : `claude -p` headless (Claude Code CLI, `--output-format stream-json`), | |
| 77 | + lancé dans le repo de l'app, avec un prompt de mission strict : diagnostiquer, | |
| 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 | 84 | 3. **Surveillance** — après réparation déclarée, l'incident passe en `watching` |
| 35 | 85 | pendant 8 h. Connecteur de retour à `ok` → résolu. |
| 36 | 86 | 4. **Rollback automatique** — si l'app tombe (healthcheck) ou si le connecteur |
| 37 | 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` | |
| 39 | − (intervention humaine). | |
| 40 | −5. **Vitrine live** — chaque site (www.ka2.bot / www.ka4.bot / www.ka6.bot) est | |
| 41 | − une salle de contrôle : flux SSE en direct de chaque action de l'agent | |
| 42 | − (outils, réflexions, verdicts), board d'incidents, couverture par service, | |
| 43 | − historique des missions avec transcript et coût. | |
| 88 | + (`git reset --hard`/revert) + `pm2 restart`. 3 tentatives max (cooldown 6 h | |
| 89 | + entre tentatives), puis `abandoned` (intervention humaine, ré-examen après 7 jours). | |
| 90 | +5. **Vitrine live** — chaque site est une salle de contrôle : flux SSE en direct de | |
| 91 | + chaque action de l'agent (outils, réflexions, verdicts), board d'incidents, | |
| 92 | + couverture par service (« Territoire surveillé »), registre des missions avec | |
| 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 | | |
| 48 | −|---|---|---| | |
| 49 | −| ka2 | www.ka2.bot :8799 | louka, immoka, restoka | | |
| 50 | −| ka4 | www.ka4.bot :8899 | autoka, foodka, sortika | | |
| 51 | −| ka6 | www.ka6.bot :8999 | fabrika, jobka, creaka + tout nouveau service (défaut) | | |
| 104 | +## Veilleur de sites (2026-08-25) | |
| 105 | + | |
| 106 | +En plus des connecteurs, chaque agent surveille le **site public** de chacun de ses | |
| 107 | +services (`site_engine` dans `main.py`, source d'incident `_site`) : | |
| 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 | 148 | ## Architecture |
| 54 | 149 | |
| 55 | −- `orchestrator/` — un process FastAPI par agent (M4M36, launchd | |
| 56 | − `com.kaX.guardian`), SQLite `data/kaX.db`, dashboard servi sur le même port, | |
| 57 | − tunnels ngrok existants conservés. | |
| 58 | −- `runner/` — un service par nœud d'app (M3U96a/b, M4M64a/b, port 7791, launchd | |
| 59 | − `com.ka.guardian-runner`), 1 mission à la fois par nœud, transcripts dans | |
| 60 | − `~/ka-guardian-runner/transcripts/`. Exécute `claude -p --output-format | |
| 61 | − stream-json` et relaie chaque événement à l'orchestrateur (`/api/ingest`). | |
| 62 | −- `topology.json` — source de vérité : agents, services (nœud/dir/pm2/port), | |
| 63 | − IP LAN, politique (fenêtres, cooldowns, modèle). | |
| 64 | −- Auth interne : token partagé `~/.ka-guardian.env` (orchestrateurs + runners), | |
| 65 | − header `X-KA-Token`. Clé Anthropic + clés anti-bot : `~/.claude/.env` des nœuds. | |
| 66 | −- Communication **par le LAN 192.168.2.x** (SSH/Tailscale inter-nœuds bloqué). | |
| 150 | +``` | |
| 151 | + M4M36 (nœud orchestrateur) | |
| 152 | + ┌────────────────────────────────────────────────────────────┐ | |
| 153 | + │ com.ka2.guardian :8799 com.ka4.guardian :8899 │ | |
| 154 | + │ com.ka6.guardian :8999 (FastAPI + SQLite data/kaX.db) │ | |
| 155 | + │ ngrok com.kaX.ngrok → www.ka2.bot / ka4.bot / ka6.bot │ | |
| 156 | + │ courrier zsh com.ka.guardian-courier (spool → ssh+curl) │ | |
| 157 | + └───────────────┬────────────────────────────────────────────┘ | |
| 158 | + │ LAN 192.168.2.x uniquement (via le courrier) | |
| 159 | + ┌────────────┼──────────────┬──────────────┬──────────────┐ | |
| 160 | + ▼ ▼ ▼ ▼ ▼ | |
| 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 | 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 | 277 | ```bash |
| 71 | −deploy/deploy.sh all # runners + orchestrateurs | |
| 72 | −deploy/deploy.sh runners # seulement les 4 runners | |
| 73 | −deploy/deploy.sh orchestrators | |
| 278 | +deploy/deploy.sh all # runners + orchestrateurs (+ courrier) | |
| 279 | +deploy/deploy.sh runners # seulement les 5 runners (refuse un runner occupé) | |
| 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 | 291 | ## Admin (token requis) |
@@ -79,10 +294,24 @@ deploy/deploy.sh orchestrators | ||
| 79 | 294 | # mission manuelle sur un connecteur |
| 80 | 295 | curl -X POST http://M4M36.maclustr.io:8799/api/admin/mission \ |
| 81 | 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 | 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 | 315 | ## Historique |
| 87 | 316 | |
| 88 | 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.