CL Pipeline v5.1 — Deep Resolver

L'ancienne infra passait tous les produits par une lignée d'agents IA : lent, cher, non-déterministe — et ratait quand même ~17 %. Le Deep Resolver est un entonnoir à 2 étages : le code rapide fait le gros, l'IA n'intervient que sur l'échec, et chaque succès de l'agent est capitalisé pour que la part IA décroisse avec le temps.

Étage 1 DÉTERMINISTE · ~80 %

Du code, 0 IA. Rapide, parallélisable, reproductible, quasi gratuit. Tourne sur tous les produits. Il ne raisonne pas — il sait où regarder.

Prober — sonde les sous-domaines (docs. help. developer. support. api. kb.) et les chemins (/docs /latest/ug/ /kb). Étape 0 : robots.txt + sitemap-index (souvent déclaré dans robots, et index imbriqué à dérouler).raffinement ①
Manifest Sniffer — récupère le plan complet du site en 1 requête, via une liste de générateurs connus : sitemap.xml, AWS toc-contents.json, mkdocs search_index.json, Docusaurus, GitBook, ReadMe.io, Mintlify, Algolia DocSearch.raffinement ②
Crawler — l'existant, patché : aspire à partir des seeds validés (200) par le Prober, plus jamais à l'aveugle depuis une landing vide.

Étage 2 AGENT HERMES · ~20 %

Un seul agent IA. Ne se déclenche que sur l'échec de l'Étage 1 (0 page / 429 / 403) — jamais en parallèle sur tout.

Ouvre réellement le site — raisonne sur l'emplacement des docs, trouve les vraies URLs, relance le crawl dessus.
Écrit ce qu'il apprend — chaque succès devient une règle pour l'Étage 1.
Budget borné — plafond tokens/temps par produit : un site coriace ne plombe jamais le run.raffinement ④

Learned Map MÉMOIRE PARTAGÉE

Le cache JSON qui fait tout tenir. Chaque succès de l'agent y devient une règle déterministe → l'Étage 1 attrape de plus en plus de cas → l'agent travaille de moins en moins. Le système s'allège tout seul.

2 niveaux de clé — par éditeur et par plateforme (readme.io, gitbook…). Un pattern appris sur un produit se transfère à tous ceux qui partagent la même plateforme.raffinement ④
Auto-péremption — champ last_verified + compteur d'échec : un pattern qui se met à échouer est ré-escaladé vers l'agent, pas gardé à vie (les sites changent).raffinement ③

En clair : outils d'abord, agent seulement sur l'échec, jamais en parallèle sur tout. Fini la lignée d'agents — l'IA devient un filet de sécurité qui se rétracte.

Le parcours d'un produit, du nom d'éditeur jusqu'au verdict. Chaque étape ne s'exécute que si la précédente n'a pas suffi.

Parcours seed → verdict

0.Learned Map ?Si l'éditeur/la plateforme est déjà connu → on part directement des seeds appris (court-circuite tout le reste).

1.Domain Resolver (existant)Nom d'éditeur → domaine officiel.

2.Proberrobots.txt + sitemap-index, puis sonde docs./help./developer.… et les chemins profonds. Retient ce qui répond 200.

3.Manifest SnifferTente toc-contents.json / sitemap.xml / search_index.json / llms.txt. Trouvé → arbre complet d'URLs en 1 coup.

4.Crawl sur les seeds validés → verdictPages > seuil ? → ✅ FINI. Sinon / 429 / 403 → on escalade.

5.Étage 2 — Agent HermesOuvre le site, trouve, relance. Succès → écrit dans la Learned Map ✅. Échec réel → ✗ « pas de doc » (rare et, cette fois, justifié).

🎯 Le cœur du problème : les pages d'aiguillage

Le crawler actuel s'arrête sur une landing vide (cas AWS Verified Access : page coquille → mais ~35 pages de doc derrière). On l'attrape ainsi :

La landing ≠ la doc — on ne crawle jamais la landing seule ; on sonde d'abord sous-domaines + chemins profonds.
Les sites de doc exposent leur plan — le Manifest Sniffer récupère 100 % des URLs en 1 requête au lieu de N crawls aveugles.
429 / 403 = WAF, pas « pas de doc » — déclenche l'escalade furtive (cas Wiz), ne clôt jamais en échec.

🔎 Verdicts — pourquoi un produit donne 0 page

Fini le « 0 page, 0 erreur » muet : chaque produit reçoit une cause-racine explicite.

Verdict	Signification
ok	Doc trouvée et aspirée au-dessus du seuil.
partial	Quelques pages trouvées mais suspicieusement peu → re-vérification / escalade.raffinement ④
waf_429 / 403	Bloqué par un WAF, pas vide → escalade anti-bot furtive.
truly_empty	Vraiment aucune doc en ligne (rare, et désormais prouvé).
agent_recovered	L'Étage 1 avait échoué, l'agent a récupéré → règle écrite dans la Learned Map.

📜 Logs & observabilité

Une ligne JSONL structurée par produit / par étape, filtrable par verdict_reason.

Champ	Exemple	Sert à voir…
`stage`	`prober` / `manifest` / `crawl` / `agent`	où ça s'est arrêté
`domain_tested[]`	`docs.x.com → 200`, `help.x.com → 404`	quels sous-domaines sondés / répondus
`manifest_found`	`toc-contents.json` / `null`	si le plan a été capté
`seeds_count`	`35`	combien d'URLs réellement mises en file
`http_codes`	`{200: 34, 429: 1}`	distinguer WAF vs vide réel
`escalation_level`	`L0 → L2`	si l'anti-WAF s'est déclenché
`verdict_reason`	`no_subdomain_probed` / `waf_429` / `truly_empty` / `agent_recovered`	la cause-racine, enfin explicite
`agent_used`	`false` / `true` + coût tokens	si l'IA a tourné, et ce qu'elle a coûté

Objectif : un produit à 0 page doit dire lequel des cas c'est (no_subdomain_probed, waf_429, truly_empty), jamais un trou noir.

Structure prévue Le moteur n'est pas encore codé — ce qui suit décrit la structure cible de l'Étage 1 déterministe, pas des données live. Le « taux de hit » indiqué est l'indicateur que cette vue affichera une fois le moteur en place.

🌐 Sous-domaines sondés

Le Prober teste un jeu fixe de sous-domaines courants pour la doc et retient ceux qui répondent 200. C'est le premier filet : il attrape les docs qui ne sont jamais liées depuis la landing.

Sous-domaine	Cible typique	Taux de hit (prévu)
docs.	Documentation produit / dev	élevé
help.	Centre d'aide / KB utilisateur	élevé
developer.	Portail développeur / API	moyen
support.	Support / articles techniques	moyen
api.	Référence API / endpoints doc	moyen
kb.	Base de connaissances	faible

Étape 0 — robots.txt + sitemap-index : avant de sonder, le Prober lit robots.txt (le Sitemap: y est souvent déclaré) et déroule tout sitemap-index imbriqué. C'est souvent là que se cache la liste complète des URLs.raffinement ①

🗺️ Manifests connus reniflés

Plutôt que crawler page par page, le Manifest Sniffer tente de récupérer le plan complet du site en 1 requête. Chaque générateur de doc expose son plan d'une manière connue — on les essaie tous.

Générateur / plateforme	Manifest ciblé	Type
Universel	`sitemap.xml` / `sitemap-index`	XML
AWS Docs	`toc-contents.json`	JSON
mkdocs	`search/search_index.json`	JSON
Docusaurus	`sitemap.xml` + `/__docusaurus`	XML
GitBook	`sitemap.xml` + arbre `/content`	XML
ReadMe.io	API `/api-reference` + sitemap	API
Mintlify	`mint.json` (arbre de nav)	JSON
Algolia DocSearch	Index Algolia (requête API)	API
Émergent	`llms.txt` / `llms-full.txt`	TXT

Le plus gros levier : un manifest trouvé = 100 % des URLs d'un coup, sans crawl aveugle. La liste de générateurs est extensible — chaque nouveau pattern découvert par l'agent (Étage 2) y est ajouté.raffinement ②

Structure prévue Le filet de sécurité IA. Décrit ici le déclenchement, le travail et les garde-fous prévus de l'unique agent de l'Étage 2.

⚡ Quand l'agent se déclenche

Jamais par défaut. Uniquement quand l'Étage 1 déterministe rend un verdict non-concluant :

0 page — le Prober et le Manifest Sniffer n'ont rien validé.
429 / 403 — WAF : la doc existe mais est protégée → escalade furtive raisonnée.
partial — quelques pages trouvées mais suspicieusement peu → l'agent vérifie s'il manque un silo entier.

🧭 Ce qu'il fait

1.Ouvre réellement le siteNavigation réelle (rendu JS inclus) : il voit la page comme un humain, pas comme un fetch brut.

2.Raisonne sur l'emplacement des docsRepère les liens « Docs / Developers / API / Support », détecte la plateforme sous-jacente, devine les chemins profonds.

3.Relance le crawl sur les vraies URLsRéinjecte les seeds trouvés dans le Crawler de l'Étage 1.

4.CapitaliseSuccès → écrit le pattern dans la Learned Map (éditeur + plateforme) pour que l'Étage 1 l'attrape seul la prochaine fois.

⏱️ Budget par produit

Un site coriace ne doit jamais plomber le run entier. L'agent est borné par produit :raffinement ④

⏳ temps

Plafond de durée par produit — au-delà, on coupe et on verdicte partial/truly_empty.

🎟️ tokens

Plafond de tokens IA par produit — protège le coût global du batch.

🔁 essais

Nombre max de relances de crawl avant d'abandonner proprement.

Garde-fou : dépassement de budget = sortie propre avec verdict explicite et log, jamais un blocage silencieux du batch.

Structure prévue La mémoire qui rend le système de plus en plus déterministe. Structure de l'enregistrement appris et de son cycle de vie.

🧠 Deux niveaux de clé

Par éditeur spécifique

Le pattern exact d'un éditeur donné : où sont ses docs, quel manifest marche, quels sous-domaines.

Par plateforme transférable

Beaucoup d'éditeurs partagent la même plateforme (readme.io, gitbook, mintlify…). Un pattern appris une fois se transfère à tous les autres produits sur cette plateforme.raffinement ④

🗃️ Forme d'un enregistrement (exemple)

Champ	Exemple	Rôle
`key`	`vendor:acme` / `platform:readme.io`	clé éditeur ou plateforme
`doc_root`	`https://docs.acme.com`	racine de doc validée
`manifest`	`search_index.json`	manifest qui a marché
`last_verified`	`2026-05-29`	dernière vérif réussieraffinement ③
`fail_count`	`0`	échecs consécutifs depuis
`source`	`agent` / `deterministic`	qui a appris ce pattern

♻️ Cycle de vie & ré-escalade

Un pattern appris n'est pas gardé à vie — les sites changent. Le cache s'auto-périme :raffinement ③

✓Hit validePattern utilisé, doc trouvée → last_verified rafraîchi, fail_count remis à 0.

!Hit qui échouefail_count incrémenté. Le pattern reste tenté tant qu'il est sous le seuil.

⤴Ré-escaladefail_count au-delà du seuil ou last_verified trop ancien → le pattern est marqué périmé et renvoyé à l'agent (Étage 2) pour ré-apprentissage.

Effet net : au début l'agent travaille beaucoup ; à mesure que la Learned Map se remplit, l'Étage 1 attrape tout seul de plus en plus de cas. La part IA décroît avec le temps — le système s'allège seul.

Données réelles, en direct lues sur le VPS (/opt/cl-agents/shared/missions). Rafraîchi automatiquement toutes les 5 s. chargement…

🎯 Vue d'ensemble (live)

—

Missions au total

—

Résolues (done)

—

À reprendre (needs_recrawl)

—

Mortes confirmées (dead-confirmed)

—

Qualité finale moyenne

—

Pages aspirées (total)

📊 Répartition des statuts

chargement…

🗂️ Détail par mission

Produit	Statut	Qualité	Audit	Pages	Couv. %	Utiles	Doc
chargement…

Source : chaque ligne reflète le vrai status.json de la mission sur le disque. Aucune valeur n'est illustrative.

Logs au complet des agents, en direct depuis le VPS. Auto-rafraîchi toutes les 5 s.

⚡ live.log

📦 queue_runner

🌙 nightwatch

auto

chargement…

🧭 Deep Resolver