Généré le 14/10/2026 22:43

🧠 SKILL : Automatisation Avancée Shopify & Manipulation React / IFrames

Date de création : 29 Mai 2026
Objectif : Ce fichier constitue la mémoire technique et la procédure d'excellence (SOP) pour manipuler des applications tierces Shopify complexes (comme Kaching Bundles), contourner les sécurités Cloudflare, et forcer des configurations dans des environnements protégés par React. À consulter obligatoirement avant toute manipulation technique avancée.


🛡️ SKILL : Automatisation Avancée Shopify & Manipulation React / IFrames

Date de création : 29 Mai 2026
Objectif : Ce fichier constitue la mémoire technique et la procédure d'excellence (SOP) pour manipuler des applications tierces Shopify complexes (comme Kaching Bundles), contourner les sécurités Cloudflare, et forcer des configurations dans des environnements protégés par React. À consulter obligatoirement avant toute manipulation technique avancée.


0. 💥 LE TERMINATOR (KILL-SWITCH UNIVERSEL)

Règle Absolue : Pour éviter la saturation de la mémoire (RAM) et la multiplication des processus fantômes qui font crasher le système et bloquent les boucles d'intelligence, l'Agent doit OBLIGATOIREMENT exécuter la commande taskkill /F /IM chrome.exe /T (via l'outil run_command) à deux moments précis :
1. Au tout début de N'IMPORTE QUELLE procédure ou SOP (avant d'ouvrir une page ou de démarrer une automatisation).
2. À la toute fin de chaque procédure ou SOP, pour nettoyer l'environnement.
Sanction : L'oubli de ce "task kill" entraîne une surcharge fatale. C'est le premier réflexe de l'Agent.

0.6. ✅ VÉRIFICATION APRÈS ACTION (RÈGLE ABSOLUE — décision Raphael 03/07/2026)

Chaque action lancée doit être VÉRIFIÉE avant d'être déclarée faite. Cas réels de la nuit du 03/07 : un message « envoyé » dans Gemini n'était jamais parti (le bouton d'envoi n'avait pas été cliqué — la touche Entrée ne suffit plus) ; une extraction de specs déclarée terminée avait produit un fichier quasi vide.
1. Après un clic d'envoi/validation : vérifier à l'écran que l'action a réellement eu lieu (message parti, page changée, spinner apparu). Si l'état n'a pas changé → l'action n'est PAS partie → recliquer/diagnostiquer.
2. Après une production de fichier : rouvrir le fichier, vérifier qu'il contient CE QUI ÉTAIT DEMANDÉ (pas juste qu'il existe). Un critère de réussite est donné dans chaque mission : le tester littéralement.
3. Avant tout compte-rendu « terminé » : si le critère de réussite n'est pas rempli, dire ÉCHEC + la raison précise — jamais « fait » par optimisme. Un échec bien décrit vaut mieux qu'un faux succès (il évite à Claude Code de tout revérifier à l'aveugle).

0.5. 🛡️ AUTO-CAPTCHA (CONTOURNEMENT TURNSTILE)

Règle Absolue : Aucune intervention humaine ne doit être sollicitée pour passer les sécurités Cloudflare/Turnstile. En cas de page de sécurité ("Je suis humain") :
1. L'Agent se connecte au port de débogage (9222).
2. L'Agent détecte l'encart Cloudflare.
3. L'Agent exécute un script de clic simulé automatisé (ex: scratch/click_turnstile_precise.py) ou injecte un événement clic via CDP pour valider le Captcha à la place de l'utilisateur.

0.7. 🗂️ GESTION STRICTE DES ONGLETS (RAM PROTECTION)

Règle Absolue : Ne jamais dépasser 2 onglets ouverts en simultané. Lors des sessions de scraping (Minea, Shopify, AliExpress), la multiplication des onglets surcharge la RAM. Dès qu'une vérification est terminée sur un onglet secondaire, l'Agent DOIT le fermer immédiatement (via page.close()) avant de passer au produit suivant. L'intelligence ne doit pas se perdre dans des dizaines d'onglets de chasse.


1. 🔑 Protocole Universel d'Aiguillage (Tiered Security Router)

L'approche de l'Agent doit obligatoirement s'adapter au "Niveau de Sécurité" (Tier) du site visé pour éviter de casser des processus fluides ou de bloquer sur des sécurités lourdes.

🔥 TIER 1 : Haute Sécurité (Meta Ads Manager, Shopify Admin, Minea Strict)
* Caractéristique : Protégé par Cloudflare Bot-Fight et architectures React/SPA hypersensibles.
* Ordre de l'Agent : Utiliser uniquement l'Architecture Hybride 2.0 (Profil Chrome Debug physique sur Port 9222). Les navigateurs headless et le browser_subagent simple sont proscrits car trop facilement détectés.
* Règle d'URL : Les URLs exactes et complexes ne sont autorisées que pour l'ouverture initiale (démarrage à froid via lance_chrome_debug.bat).
* Règle de Navigation : En cours de session, interdiction absolue d'injecter des URLs filtrées (?since=...). La navigation doit se faire exclusivement par Clics Profonds (browser_driver.py) imitant un humain.

⚡ TIER 2 : Standard & Usines Autonomes (AliExpress, APIs, Google Labs, Sites classiques)
* Caractéristique : Pas de protection anti-bot agressive, ou besoin d'exécuter des dizaines de requêtes sans déranger l'écran de l'utilisateur.
* Ordre de l'Agent : Privilégier Playwright Headless (invisible) ou l'injection classique du fichier de cookies (storage_state).
* Règle d'URL : L'injection d'URL avec paramètres est fortement recommandée pour gagner du temps, by-passer les formulaires UI et travailler en arrière-plan de manière fulgurante.


2. 🪟 La Maîtrise des Iframes & Shopify App Bridge

Les applications Shopify (Kaching, Dropmagic) ne s'affichent pas directement dans la page. Elles utilisent des IFrames.


3. 🧬 Le Hack Ultime : Interception Réseau (Bypasser React)

Le problème : Modifier un <input> HTML en Javascript (via evaluate) ne fonctionne pas sur les applications modernes (React/Vue). Au moment de sauvegarder, React réécrit la valeur avec son état virtuel en mémoire, annulant notre modification.

La Solution Absolue (Interception à la volée) :
Au lieu de se battre avec le DOM visuel, on intercepte la requête HTTP envoyée au serveur lors du clic sur le bouton "Sauvegarder", on modifie les données, et on l'envoie !

async def handle_route(route, request):
    if request.method in ["POST", "PUT", "PATCH"] and "deal_blocks" in request.url:
        data = json.loads(request.post_data)

        # Modification chirurgicale du paramètre cible
        data["disableVariantOptionSync"] = True 

        new_post_data = json.dumps(data)
        await route.continue_(post_data=new_post_data)
        return

    await route.continue_()

# 1. On active l'interception sur la page
await page.route("**/*", handle_route)

# 2. On clique nativement sur le bouton "Publier" dans l'UI
await pub_btn.click()

Avantage : C'est invisible pour React, 100% stable, et cela force l'enregistrement côté backend sans se soucier de l'interface visuelle.


4. ✅ Protocole de Validation Post-Modification

Après chaque modification critique sur une application, l'agent doit :
1. Naviguer sur la boutique publique de l'utilisateur (ex: ysenra.fr).
2. Contourner le cache en ajoutant un paramètre aléatoire : ?nocache=1.
3. Extraire le JSON de configuration final injecté par l'application dans le code source de la page publique pour prouver mathématiquement que la modification est active en production.

5. 🛠ï¸� Découvertes Techniques & Optimisations Agentiques (Mise à jour Minea/UI)

5. 🛠ï¸� Découvertes Techniques & Optimisations Agentiques (Mise à jour Minea/UI)

Cette section archive les nouvelles techniques découvertes pour rendre l'agent plus autonome et robuste.

A. La puissance du Playwright MCP natif sur le port 9222

Leçon : Il n'est pas toujours nécessaire de coder de lourds scripts Python Playwright pour interagir avec une session CDP existante (comme Minea sous Cloudflare).
Action Systématique : Si un Chrome de débogage tourne sur le port 9222, les outils Playwright du serveur MCP (ex: mcp_playwright_browser_evaluate) s'y accrochent automatiquement et nativement. INTERDICTION D'UTILISER browser_subagent ICI : le sous-agent plante car il tente de créer un nouveau "contexte" isolé, ce qui est refusé par une session de débogage physique. L'agent doit piloter lui-même le navigateur étape par étape en utilisant les appels directs d'outils MCP Playwright sans déclencher Cloudflare.

A2. Interchangeabilité et Fallback Stratégique (Outils MCP vs browser_driver.py)

Leçon : Puisque les outils MCP natifs et le script browser_driver.py pointent tous les deux vers le même port 9222, ils partagent strictement la même session et le même onglet en temps réel.
Action Systématique : Au cours d'une mission, l'agent doit jongler entre ces deux méthodes selon le besoin :
1. Utiliser en priorité les Outils MCP directs (mcp_playwright_browser_navigate, evaluate, snapshot) pour extraire ou lire le DOM instantanément et de façon intégrée.
2. S'il rencontre un blocage physique (popup récalcitrante, clic bloqué, captcha visuel), il doit exécuter un terminal avec browser_driver.py (python browser_driver.py --action ...) comme fallback immédiat. Ce script force l'action physique (clic, frappe clavier, coordonnées), débloque la situation, puis l'agent reprend sa lecture via les Outils MCP sur le même onglet.

B. Exploitation des Serveurs MCP (ex: Google Sheets)

Leçon : Éviter de recoder la roue avec des scripts Python complexes.
Action Systématique : Utiliser les outils MCP (ex: mcp_google-sheets_sheets_write).
Attention au Format (FR) : Convertir les décimales avec une virgule (69,99).
Sécurité des formules : Préférer sheets_write ciblé plutôt que append pour ne pas écraser les formules pré-étirées. Ne jamais envoyer de valeur dans les cellules contenant des formules de l'utilisateur.

C. Prévention du crash Unicode (cp1252) sous Windows

Leçon : Imprimer (print) des retours d'API JSON contenant des emojis (fréquent sur Telegram) fait crasher les scripts Python dans le terminal Windows natif.
Action Systématique : Dans les futurs scripts Python générés, forcer l'encodage UTF-8 en début de fichier avec import sys; sys.stdout.reconfigure(encoding='utf-8') ou formater la sortie pour ignorer les emojis.

D. La Règle d'or du Flexbox Mobile (UI E-commerce)

Leçon : Les navigateurs mobiles iOS/Android imposent des UI inaltérables sur les input type="number" et détruisent les proportions des éléments flexibles quand l'espace vertical manque.
Action Systématique (Pour tout patch UI Mobile) :
1. Remplacer type="number" par type="text" inputmode="numeric" pattern="[0-9]*". Cela annule le bridage natif mais affiche bien le pavé numérique à l'utilisateur.
2. Injecter obligatoirement shrink-0 (ou flex-shrink: 0) sur les éléments vitaux (boutons, inputs) pour interdire au navigateur mobile de les écraser sous la pression du contenu voisin.

E. L'Auto-Ouverture de Chrome & Les Favoris CDP (Recovery Absolu)

Leçon : Si un port CDP (9222) est hors ligne parce que l'utilisateur a tout fermé, l'agent ne doit pas s'arrêter. Il peut réveiller le navigateur de lui-même et utiliser des "favoris CDP" pour retrouver son contexte sans aucune intervention humaine ni blocage Cloudflare.
Action Systématique :
1. Auto-Recovery : Ne jamais abandonner sur une erreur "Target page or browser has been closed". Utiliser run_command pour exécuter .\lance_chrome_debug.bat afin de forcer le redémarrage natif de Chrome.
2. Navigation Éclair : Lire le dictionnaire FAVORIS_CDP.json pour extraire l'URL exacte du tableau de bord visé.
3. Injection : Ordonner à Playwright de naviguer (browser_navigate) sur cette URL fraîchement ouverte. Cela permet un accès instantané et transparent.

F. Preuve Visuelle Autonome (Proof of Execution Telegram)

Leçon : Pour garantir la confiance totale en mode hands-free, l'agent doit pouvoir envoyer des preuves visuelles de ses actions directement sur le téléphone de l'utilisateur.
Action Systématique : Prendre une capture via Playwright (page.screenshot()), puis utiliser la commande native Windows curl.exe -X POST ... -F photo="@image.png" pour pousser l'image sur l'API Telegram sans écrire de scripts Python complexes.

H. Déduction Contextuelle (Tolérance aux fautes vocales)

Leçon : Les outils de dictée vocale créent des erreurs phonétiques (ex: 'robe ample' au lieu de 'lampe ancienne').
Action Systématique : L'agent ne doit jamais bloquer bêtement en cas de non-correspondance exacte dans une base de données. Il doit appliquer une logique de déduction phonétique ou de similarité de sens pour identifier la cible réelle, tout en avertissant l'utilisateur de cette correction proactive.

I. Méta-Raisonnement et Protection des Quotas (Anti-Chronophage)

Leçon : L'agent ne doit pas exécuter aveuglément une instruction si celle-ci s'avère mathématiquement ou techniquement illogique (ex: chercher une vidéo brute sur une plateforme basée sur du texte comme Minea sans mots-clés précis).
Action Systématique :
1. Évaluation Préalable : Avant de lancer une navigation via Playwright ou un outil coûteux, évaluer la probabilité de succès.
2. Refus Stratégique : Si la tâche a un ratio coût/succès déraisonnable (gaspillage de quotas/temps), l'agent doit annuler l'action et expliquer son raisonnement.
3. Alternative Out-of-the-Box : L'agent doit toujours proposer une méthode alternative beaucoup plus efficiente (ex: utiliser Google Lens pour une recherche par image au lieu d'une recherche textuelle à l'aveugle).

J. Recherche Inversée (Sourcing par Image - Google Lens)

Leçon : Retrouver un fournisseur ou un concurrent sans posséder de lien texte est possible grâce à la recherche visuelle.
Action Systématique : Si l'URL concurrente est manquante mais qu'un visuel (ou une capture vidéo) est disponible, utiliser l'image pour effectuer une recherche inversée via Google Lens afin d'identifier les boutiques Shopify ou les fournisseurs AliExpress correspondants.

M. Résilience des Scripts en Arrière-Plan (VBS & Boucles Infinies)

Leçon : Un script VBS (WshShell.Run) lançant un script Python qui nécessite un flag d'argument (ex: --loop) pour tourner en continu se terminera instantanément si l'argument est omis. De plus, il ne faut jamais lier un service de monitoring (comme un Calendar Dispatcher) à un service applicatif bloquant ou lourd (comme Telegram).
Action Systématique : Toujours créer des fichiers VBS dédiés et isolés pour les services de fond (lance_dispatcher_invisible.vbs). Vérifier explicitement que tous les flags de la ligne de commande sont injectés.

N. Extraction NATIVE des Vidéos Facebook Ads (Bypass Minea)

Leçon : Minea redirige souvent vers la "Meta Ads Library" sans fournir le lien direct .mp4. L'extraction réseau via Minea peut échouer si le DOM ne contient pas directement la vidéo.
Action Systématique : Ne jamais soumettre un lien Facebook dans un livrable final. Naviguer silencieusement (via Playwright Evaluate ou Subagent) sur le lien Facebook Ads, attendre le rendu du DOM, et extraire l'attribut src de la balise <video> pour récupérer l'URL CDN pure (.fbcdn.net ou .cloudfront.net).

O. Exécution Réactive Post-Injection (Trigger Autonome)

Leçon : Lorsqu'un événement est injecté automatiquement dans le cerveau de l'Agent via une API (comme le Calendar Dispatcher), l'utilisateur attend une exécution immédiate.
Action Systématique : Dès réception d'un trigger, l'agent doit publier son message d'initialisation ("🚀 Initialisation...") ET enchaîner IMMÉDIATEMENT sur le premier outil de la mission (ex: navigation via outil MCP direct). Ne jamais faire de pause en attendant une confirmation humaine si la tâche a été déclenchée par un système autonome.

P. Automatisation des Interfaces Google (Gemini/Veo) & Téléchargement Playwright

Leçon : L'automatisation des plateformes Google (Gemini, Google Labs) est souvent bloquée par des sécurités de connexion robustes (MFA, Captchas) et des pop-ups intrusives (ex: l'overlay Canvas) qui bloquent les clics UI.
Action Systématique :
1. Bypass d'Auth (CDP) : Ne jamais tenter un login Playwright classique sur une plateforme Google. Toujours lancer un Chrome de débogage (port 9222) en spécifiant expressément le profil isolé --user-data-dir="%LOCALAPPDATA%\Google\Chrome\User Data Debug". Cela permet de préserver et réutiliser la connexion Premium (cookies Google One AI) sans créer de conflits avec la navigation principale de l'utilisateur.
2. Contournement de la Censure UI (Canvas Bypass) : Ne JAMAIS utiliser expect_file_chooser() ou des clics sur les boutons d'upload (+) sur Gemini. Ces clics sont souvent interceptés par des overlays publicitaires ou de nouvelles fonctionnalités. Méthode Infaillible : L'Injection Javascript (DataTransfer). Convertir l'image en Base64 en Python, et exécuter un page.evaluate() pour créer un ClipboardEvent('paste') contenant un objet File attaché à un DataTransfer. C'est l'unique solution 100% stable en arrière-plan (l'ancienne méthode Powershell avec le presse-papier Windows étant sujette à des crashs STA/Thread).
3. Interception de Fichiers : Pour récupérer les assets générés par les IA de manière fiable, il faut obligatoirement utiliser l'événement natif Playwright page.expect_download() juste avant de cliquer sur le bouton de téléchargement natif de l'interface, afin d'intercepter et sauvegarder le flux binaire du .mp4 sans dépendre de délais aléatoires.

Q. Automatisation Agentique Google Flow & Deadlocks Playwright

Leçon 1 (Désynchronisation Upload) : Lors de l'upload multi-médias (ex: une vidéo lourde et une image légère) via expect_file_chooser, Google traite l'image instantanément et la vidéo très lentement. Un clic immédiat sur 'Ajouter au prompt' créera des erreurs ou oubliera la vidéo.
Action : Toujours implémenter une boucle de surveillance (Agentic DOM Loop) qui attend explicitement que le bouton 'Ajouter au prompt' soit visible AVANT de cliquer.

Leçon 2 (Le Deadlock Playwright JS) : Forcer un clic via page.evaluate() sur un élément qui déclenche une grosse transition UI ou une navigation (comme 'Nouveau projet') va faire crasher/geler Playwright indéfiniment.
Action : Toujours encapsuler le clic natif dans un setTimeout : setTimeout(() => b.click(), 100). Cela libère Playwright avant la navigation.

Leçon 3 (Modaux de Crédits Fantômes) : Google Flow bloque souvent la génération avec des popups '20 crédits'.
Action : Après chaque pression sur 'Enter', ajouter systématiquement une boucle de 10-15s qui cherche Approuver et ne plus demander et clique sur Accepter.

Leçon 4 (Le Mur reCAPTCHA post-login) : Google Flow bloque désormais l'accès avec un reCAPTCHA persistant même après une connexion Google réussie sur le profil.
Action : Ne plus supposer que l'accès est libre une fois loggé. Toujours vérifier la présence de l'écran reCAPTCHA (Règle 0.6). Si présent, appliquer la procédure d'Auto-Captcha (Section 0.5) ou stopper et notifier via Telegram pour une validation physique.

R. L'Architecture Hybride 2.0 (Agentic Browser Driver + Vision)

Leçon : Les scripts figés d'extraction DOM (qui cherchent des textes ou des sélecteurs CSS précis) échouent systématiquement face aux UI virtualisées comme Meta Ads. De plus, avoir de multiples scripts (un pour Meta, un pour Shopify) est complexe à maintenir.
Action Systématique :
1. L'Outil Agentique Unique : Remplacer les scripts rigides par un unique "Driver" de navigateur (browser_driver.py) piloté via CDP sur le port 9222. Ce driver n'a aucune logique métier : il exécute bêtement des commandes dynamiques (--action goto, screenshot, scroll_down, new_tab).
2. L'Extraction 100% Multimodale : Le script prend une capture et l'envoie à la Vision de l'Agent. C'est l'Agent (le Cerveau) qui lit les chiffres et qui décide de lancer une nouvelle commande de scroll si l'information est cachée.

S. Sécurisation du Profil Debug (Le conflit du Port 9222)

Leçon : L'ouverture d'une session de débogage CDP sur le port 9222 va silencieusement échouer (ECONNREFUSED) si une instance normale de Chrome (ou des processus fantômes) tourne déjà en arrière-plan pour le même profil utilisateur.
Action Systématique :
Avant de lancer Chrome pour l'Agent, il faut TOUJOURS exécuter un nettoyage agressif : taskkill /F /IM chrome.exe. De plus, il est vital de démarrer Chrome sur un profil dédié et isolé (ex: --user-data-dir="%LOCALAPPDATA%\Google\Chrome\User Data Debug") pour s'assurer que Cloudflare reconnaisse une session humaine active, sans polluer ou être bloqué par la navigation personnelle de l'utilisateur.

⚠️ EXCEPTION Minea/Shopify (corrigé 09/08/2026, voir Architecture_Antigravity.md section 6) : cette règle générale de "profil Debug copié" ne s'applique PAS à Minea ni Shopify. Cause racine confirmée en conditions réelles : Chrome ne déchiffre pas fiablement les cookies/tokens copiés dans un dossier User Data Debug séparé ("Failed to decrypt token" constaté), ce qui produit des sessions Minea/Shopify faussement déconnectées (mur "Se connecter") malgré un login valide par ailleurs. Pour Minea/Shopify spécifiquement : toujours le vrai profil dédié déjà authentifié (tools\chrome_automation_profile, voir SOP_chasse_produits_scriptee_DRAFT.md / python minea_scraper.py check-auth), jamais une copie fraîche du profil Debug. Si un mur de connexion Minea apparaît malgré tout, ne pas re-tenter en boucle sur un profil différent : vérifier check-auth, et si réellement déconnecté, alerter Telegram pour une reconnexion manuelle plutôt que de changer de profil à l'aveugle.

T. L'Injection de Données via URL vs. Clics Natifs (Application des Tiers)

Leçon : Les interfaces React/SPA complexes réagissent très mal à l'injection brutale d'URL (provoquant le retour du mur Cloudflare). À l'inverse, l'utilisation de l'UI manuelle (clics) sur des sites lents peut créer des timeouts.
Action Systématique :
- Sur une cible TIER 2 (Standard) : L'injection dynamique dans l'URL (?search=...) est encouragée pour la vitesse pure.
- Sur une cible TIER 1 (Shopify Admin / Meta) : Le rechargement sauvage de l'URL est mortel. L'Agent doit obligatoirement scroller et cliquer via le Driver CDP (--action click) pour simuler le parcours humain et conserver sa connexion Premium. Ne jamais utiliser l'injection d'URL pour filtrer les dates sur ces cibles.


6. 🛠️ Leçons Techniques — Pipeline UGC Studio (Session 13-14 Juin 2026)

U. Déclaration d'Outils Gemini (MCP/SDK) : items obligatoire sur les tableaux

Leçon : Quand on déclare des tools pour Gemini via le SDK google.generativeai (ou MCP), tout paramètre de type "array" DOIT contenir un champ "items" décrivant le type des éléments. Sans ce champ, Gemini rejette l'intégralité des outils avec une erreur INVALID_ARGUMENT en boucle.
Exemple de l'erreur : tools[48].function_declarations[0].parameters.properties[clips]: unknown field
Fix systématique :

{
  "name": "clips",
  "type": "array",
  "items": {"type": "object"},
  "description": "Liste des clips"
}

Règle d'or : Avant de déployer un outil MCP avec des listes, toujours vérifier que chaque "type": "array" a son "items". S'applique aussi aux tableaux imbriqués.


V. ffmpeg sous Windows : Échapper les chemins dans le filtergraph

Leçon : Sur Windows, les chemins de fichiers contiennent des deux-points (C:/Windows/Fonts/arialbd.ttf). Le caractère : est un séparateur de clé/valeur dans le filtergraph ffmpeg. Sans échappement, ffmpeg crash avec No option name near '/Windows/Fonts/arialbd.ttf' ou Trailing garbage.
Deuxième piège : les virgules dans les expressions logiques (ex: lt(t,3)) doivent aussi être échappées en lt(t\,3) dans un -vf simple, ou lt(t\\,3) dans une f-string Python.
Fix systématique (fonction réutilisable) :

def _escape_path(p: str) -> str:
    """Échappe un chemin pour le filtergraph ffmpeg (Windows)."""
    return p.replace("\\", "/").replace(":", "\\:")

Usage dans un -vf :

vf = f"drawtext=fontfile='{_escape_path(font)}':...:enable='lt(t\\,3)'"

Règle d'or : Toute f-string ffmpeg contenant un chemin Windows ou une virgule dans une expression logique doit passer par _escape_path() et ses virgules doivent être doublées (\\,).


W. ffmpeg filter_complex : Les labels de flux audio DOIVENT avoir des crochets

Leçon : Dans un -filter_complex, les références aux flux audio doivent TOUJOURS être entourées de crochets []. La forme 0:a (sans crochets) est invalide dans ce contexte et produit l'erreur Trailing garbage in filtergraph description.
Mauvais (crash) :

audio_labels = ["0:a"]   # ← FAUX
# ...produit : 0:a[vo]amix=inputs=2 → Trailing garbage

Correct :

audio_labels = ["[0:a]"]  # ← CORRECT
# ...produit : [0:a][vo]amix=inputs=2:duration=first:normalize=0[out]

Règle d'or : Dans tout filter_complex Python construit dynamiquement, initialiser les labels avec leurs crochets dès la déclaration. Ne jamais les ajouter après coup avec .join() car c'est là qu'on oublie les crochets d'ouverture du premier élément.


X. L'Agrégateur Global d'Avis (Bypass Cloudflare & Amazon)

Leçon : Se fier à un seul fournisseur AliExpress (même s'il a une note de 4.9) expose au risque des faux avis. Extraire les avis via un script Playwright Headless classique échoue systématiquement à cause de Cloudflare.
Action Systématique (L'Audit Qualitatif) :
1. Multi-Fournisseurs (AliExpress) : L'Agent doit utiliser l'Architecture Hybride (Chrome sur le port 9222) pour aspirer les avis. L'outil officiel est aggregate_reviews_cdp.py. Il ouvre les liens des 3 à 5 meilleurs fournisseurs et extrait les textes/tags de manière invisible.
2. Le Filet Occidental (Amazon/Trustpilot) : L'Agent ne doit jamais s'arrêter à AliExpress. Il doit utiliser son outil interne search_web pour chercher des avis sur Amazon ou Trustpilot afin de vérifier s'il existe un consensus occidental sur un défaut structurel (taille, matériaux).
3. L'Analyse IA : L'API/Script ne fait que retourner du texte. C'est l'Agent qui fait l'analyse sémantique globale pour détecter les Red Flags cachés et prononcer le verdict.


Y. L'Extracteur d'Actifs Concurrentiels (Video Ripper via Network Interception)

Leçon : Les vidéos (tutoriels, démos, B-roll) des concurrents sont souvent impossibles à trouver via de simples requêtes HTML car elles sont intégrées dans des iframes complexes ou générées par des CDN (ex: Shopify CDN, Vimeo).
Action Systématique (Le Vol Légitime) :
1. Écoute du Trafic : L'Agent doit utiliser l'outil rip_competitor_video.py (ou un équivalent via Playwright) qui écoute passivement les requêtes réseau (page.on("response")) au lieu de scraper le DOM.
2. Déclenchement (Lazy Load) : Le script doit scroller la page pour forcer le déclenchement des requêtes réseau des vidéos.
3. Capture : Toute requête avec l'extension .mp4 ou le type mime video/mp4 est interceptée et téléchargée physiquement.
Utilisation Stratégique : Si un produit présente un "Red Flag" de complexité (ex: difficile à configurer), l'Agent doit proposer d'aspirer le tutoriel du concurrent (s'il est "neutre" sans branding) pour résoudre le problème SAV sans aucun coût de production.


Z. Protocole d'Upload GraphQL & Cartographie des Assets Shopify (OS 2.0)

Date de mise à jour : 21 Juin 2026
Leçons Techniques Majeures (Dernières 48h) :
1. Contrainte de Schéma shopify:// (Assets Theme API) : Les fichiers JSON des templates de produits dans Online Store 2.0 n'acceptent pas les URLs HTTP brutes ni les GIDs GraphQL (ex: gid://shopify/MediaImage/...) pour leurs réglages d'images (image_picker / image_media). Toute tentative génère une erreur 422 - Setting must be a valid shopify url. Ils doivent strictement être sous la forme : shopify://shop_images/nom_du_fichier.ext.
2. Automatisation d'Upload de Fichiers Global (GraphQL Pipeline) : Pour importer proprement des images externes dynamiquement dans le template d'un produit :
- Initier la demande via la mutation stagedUploadsCreate.
- Transmettre le fichier binaire au point de terminaison renvoyé (Google Cloud Storage) via un POST multipart avec les paramètres retournés.
- Enregistrer le fichier dans la bibliothèque Files de Shopify via la mutation fileCreate.
- Interroger le statut en boucle via node(id: $id) jusqu'à ce que fileStatus soit READY.
- Extraire le nom de fichier final nettoyé de la clé image { url } pour composer le schéma shopify://shop_images/{filename}.
3. Nettoyage strict des Suffixes de Fichiers Assets : Lors de l'écriture ou de l'association de templates personnalisés uniques via l'API REST Shopify (ex: templates/product.magic-{handle}.json), les caractères spéciaux (ex: marques déposées ™) ou les espaces insérés par erreur dans le handle provoquent des rejets immédiats de la plateforme. La sanitisation via regex (re.sub(r'[^a-zA-Z0-9\-_]', '', handle)) est obligatoire avant toute manipulation de template.


AA. Verrouillage du Port de Débogage CDP (Port 9222) & Contention Multi-Clients


AB. Injection Javascript DataTransfer (Base64) pour le Bypass d'Uploader


7. Lecons Techniques Studio Pub V1 (Session 04-05 Juillet 2026)

AC. Moderation Aleatoire Seedance (fal.ai) -> Repli Automatique sur Kling

Date : 04/07/2026 — Source : Construction Studio Pub P1-P7

Lecon (Factuel) : Le modele bytedance/seedance-2.0/mini/image-to-video sur fal.ai rejette
ALEATOIREMENT des prompts lifestyle inoffensifs avec une erreur de content policy. Ce rejet est
non-deterministe : le meme prompt peut passer a la tentative suivante. Il N'EST PAS lie a un mot
ou une image specifique — c'est une moderation probabiliste cote Seedance.

Action Systematique :
1. Ne JAMAIS modifier le prompt quand Seedance echoue avec une erreur de moderation.
2. Repli immediat sur Kling 3 standard (fal-ai/kling-video/v3/standard/image-to-video).
3. Seedance = draft uniquement. Jamais pour des pipelines autonomes sans supervision humaine.
4. MODELE BANNI : google/gemini-omni-flash/image-to-video — content-policy systematique.

Regle d'or : Dans tout pipeline fal.ai autonome :
try Seedance -> except moderation_error -> fallback Kling 3


AD. Pattern Idempotent state_manager pour Pipelines Multi-Etapes

Date : 05/07/2026 — Source : Studio Pub P7 (studio/state_manager.py)

Lecon : Tout pipeline multi-etapes (nettoyer -> animer -> assembler -> livrer) peut crasher
a n'importe quelle etape. Sans persistance d'etat, chaque crash force une reprise depuis zero
avec des couts API refactures inutilement (Kling : ~0,45 USD/clip, ElevenLabs : ~0,18 USD/min).

Pattern valide en production :

# Au debut de chaque etape couteuse :
cached = sm.step_done(state, "nom_etape")
if cached and os.path.exists(cached["output"]):
    result = cached["output"]   # saute l'etape — zero cout additionnel
else:
    result = appel_api_couteux(...)
    sm.record_step(state, work_dir, "nom_etape", result)

Conditions de validite du cache :
- Le fichier de sortie DOIT encore exister sur disque (os.path.exists).
- Si efface entre deux sessions -> l'etape est relancee normalement.
- --resume --slug mon_slug : reprend exactement ou le pipeline s'est arrete.

Regle d'or : Tout futur pipeline autonome multi-etapes (chasse, page produit, pub) DOIT
implementer ce pattern. Le cout de l'idempotence est negligeable ; le cout d'un crash sans
reprise est reel (argent + temps).


AE. Architecture fal_client.py : Le Client API Generique (Modele = Parametre)

Date : 05/07/2026 — Source : Studio Pub P1 (studio/providers/fal_client.py)

Lecon : Coder un client API dedie a chaque modele IA (Kling, Seedance, NanoBanana) cree
une dette technique massive. Tous les modeles fal.ai partagent la meme API queue avec le meme
cycle : submit -> poll -> download.

Pattern valide en production :

def run(model_slug: str, payload: dict, poll_interval: int = 20, timeout: int = 900):
    r = requests.post(f"https://queue.fal.run/{model_slug}", ...)
    status_url = r.json()["status_url"]
    response_url = r.json()["response_url"]
    while time.time() < deadline:
        status = requests.get(status_url, ...).json()["status"]
        if status == "COMPLETED":
            return requests.get(response_url, ...).json()
        elif status in ("FAILED", "ERROR"):
            raise RuntimeError(...)
        time.sleep(poll_interval)

def _find_url(obj):
    """Parcours recursif — chaque modele range son URL video differemment."""
    if isinstance(obj, dict):
        for k, v in obj.items():
            if k == "url" and isinstance(v, str) and (".mp4" in v or "video" in v):
                return v
            r = _find_url(v)
            if r: return r
    elif isinstance(obj, list):
        for item in obj:
            r = _find_url(item)
            if r: return r

Appels en production (un seul client, tous les modeles) :

fal_client.run("fal-ai/nano-banana",                         payload)  # generation image
fal_client.run("fal-ai/kling-video/v3/standard/image-to-video", payload)  # animation finale
fal_client.run("bytedance/seedance-2.0/mini/image-to-video", payload)  # animation draft

Regle d'or : Le modele est TOUJOURS un parametre externe, jamais hardcode dans la logique
de pipeline. Ne jamais coder un client dedie par modele.


8. 🛠️ Leçons Techniques — Consolidation Hebdomadaire (Session 24-26 Juillet 2026)

AF. Règle du Ratio 1:1 Strict & Injection aspect-ratio dans les Templates Shopify OS 2.0

AG. Pipeline GraphQL Staged Upload Multi-Étapes pour Média Produit

AH. Nettoyage Sécurisé des Médias Legacy Shopify via GraphQL

9. 🛠️ Leçons Techniques — Consolidation Hebdomadaire (Session 07-09 Août 2026)

AI. Élargissement d'un type union : vérifier TOUS les points de validation, pas seulement la définition

AJ. Les messages envoyés par un AUTRE script via le même bot Telegram sont invisibles dans le journal d'un bot qui ne fait qu'écouter

AK. Les signaux indirects (clic d'auto-approbation, URL d'onglet, date de modification d'un dossier) ne remplacent jamais une lecture directe de l'état réel

10. 🛠️ Leçons Techniques — Consolidation Hebdomadaire (Session 28-30 Août 2026)

AL. fal.ai : distinguer l'accès par session navigateur (NanoBanana) de l'accès par clé API (fal_client Python) — ne jamais fabriquer un résultat de repli en cas d'échec silencieux

AM. Itération sur génération IA (image/vidéo) : isoler une seule variable par tentative de correction, jamais combiner plusieurs corrections dans une régénération complète

11. 🛠️ Leçons Techniques — Consolidation Hebdomadaire (Session 11-13 Septembre 2026)

AN. Une consigne "ne touche à rien d'autre" donnée à un modèle d'édition d'image (nano-banana/edit) n'empêche pas la corruption de zones hors de l'édition demandée

AO. Distinguer "ajustement de format" (recadrage, compression, correction de ratio) et "habillage argumentatif" (texte, flèches, nouvelles affirmations visuelles) détermine quel outil utiliser — règle générale, pas propre à un seul type de visuel

AP. Sur Vercel, l'alias par défaut <projet>.vercel.app est régénéré automatiquement à chaque nouveau déploiement --prod, même après suppression explicite

AQ. Une détection anti-doublon par simple sous-chaîne dans cmdline matche aussi le shell wrapper qui lance le script (cmd /c "python script.py >> log"), pas seulement une vraie deuxième instance

12. 🛠️ Leçons Techniques — Consolidation Hebdomadaire (Session 09-11 Octobre 2026)

AR. Collision SOCKS5h sur Node.js et Python Standard (httplib2) : purge d'environnement obligatoire pour les sous-processus d'agents et les APIs Cloud

AS. Interfaçage natif OpenRouter avec Claude Code : distinction stricte entre ANTHROPIC_AUTH_TOKEN et ANTHROPIC_API_KEY

AT. Affichage Responsive Mobile sous WebView / Live Voice : bannir 100vh au profit de 100dvh et neutraliser la capture d'événements tactiles sur les conteneurs superposés