liangdabiao/geo

Service complet GEO

Du diagnostic à la livraison, une chaîne complète, pas seulement des conseils :

Crawling → Audit → Échantillonnage IA → Génération de tickets → Production d'assets → Rapport → Vérification automatique → Pack livrable client

Le jugement principal est unique : le but du GEO n'est pas le classement, c'est la phrase dans la réponse IA qui est dite selon votre discours. Donc l'unité minimum n'est pas la page, mais le bloc de fait extractible.

Dossier du projet : /Users/brucejan/geo, chaque client/produit a un dossier work/<slug>/.

---

Utilisation la plus rapide : donner une URL

python3 scripts/geo.py new --url https://example.com --market both

Neuf étapes entièrement automatiques : créer le projet → crawler le site → audit → déduction automatique des faits de marque/concurrents/banque de questions → relancer l'audit → échantillonnage des réponses IA → tickets et plan de construction → assets et rapport → trois livrables.

Produit dans work/<slug>/deliverables/ :

Fichier	Répond à quoi
1-RapportDiagnosticGEO.html	À quoi ça ressemble maintenant
2-PlanOptimisationGEO.html	Ce qu'il faut changer et pourquoi
3-PlanExecutionGEO.html	Qui fait quoi, quand, et quand c'est terminé

Les faits de marque déduits automatiquement doivent être vérifiés manuellement – bootstrap extrait uniquement du corps du site officiel, ce qui n'est pas extrait est marqué « à confirmer », jamais rempli par des connaissances générales. Les champs marqués « à confirmer » (date de création, entité juridique, clients nominatifs, etc.) doivent être complétés par vous ou clairement indiqués comme non divulgués.

Deux modes d'utilisation

Interface (recommandé)

python3 scripts/geo.py ui        # Par défaut http://127.0.0.1:8765

Tout le processus dans l'interface, pas besoin de se souvenir des commandes : créer un projet, éditer la configuration et la banque de questions, écrire les fiches de faits, lancer n'importe quelle étape ou le cycle complet (avec logs en temps réel) en un clic, modifier le statut des tickets, consulter les assets, importer une feuille d'échantillonnage manuelle, ouvrir le pack livrable.

L'interface est une ligne principale sombre en quatre sections (AtlasGEO) : État actuel (Vue d'ensemble / Performance des moteurs / Comparaison concurrents / Banque de questions) → Diagnostic (Écart de diagnostic / Carte des positions / Base de faits de marque) → Amélioration (Plan d'action / Atelier de contenu) → Résultats (Vérification des résultats / Rapports et livraison), plus les paramètres et un guide d'intégration en trois étapes. Métriques unifiées : Score de santé GEO (cinq facteurs pondérés, poids normalisé pour les non mesurés), Taux de mention, Part de citation, Position, Tâche, Contenu. Le titre de la vue d'ensemble est une conclusion générée automatiquement par les données ; tous les chiffres proviennent du même échantillonnage, les non calculables affichent « Non mesuré », pas de chiffres inventés. Les tâches s'exécutent en arrière-plan dans un sous-processus, la fermeture de la page ne les arrête pas ; un seul tâche est autorisée à la fois par projet pour éviter les conflits sur le même audit.json.

Utilise uniquement la bibliothèque standard pour le serveur, zéro dépendance externe pour le front-end, utilisable hors ligne.

Ligne de commande

python3 scripts/geo.py serve --slug <projet>

Crawl → Audit → Échantillonnage → Tickets → Assets → Rapport → Vérification de la période précédente → Packaging livrable, le tout fait. Production dans work/<slug>/delivery/<date>/, prêt à être envoyé au client.

Pour un nouveau client, suivez les étapes 0–2 ci-dessous pour établir la base, puis exécutez seulement cette ligne à chaque période.

---

Que lire en premier

• À lire absolument à chaque fois : references/method.md (référentiel de notation et sources de tous les critères, le script en est l'implémentation).
• À lire absolument pour prioriser les sources externes : references/cn-source-ranking.md (Classement réel des 187 818 citations CN-GEO. Le site officiel ne représente que 1,37 %, ce chiffre changera l'allocation des ressources).
• Pour les plateformes chinoises : references/cn-platforms.md ｜ Pour les plateformes internationales : references/global-platforms.md
• Pour écrire du contenu/modifier des pages : references/content-patterns.md
• Pour des méthodes plus approfondies ou des données brutes : references/sources.md (inclut les explications de choix entre GEORank / GEOFlow).
• En cas d'anomalie d'échantillonnage/de plateforme, consultez d'abord : references/known-issues.md (timeout de Doubao, modèle de point d'accès domestique/international 302, SPA vide, filtrage de portée llms.txt).

Ne donnez pas de conseils GEO par expérience. Chaque recommandation doit pouvoir être retracée jusqu'à un chiffre mesuré dans method.md, si vous ne pouvez pas en donner la source, ne l'écrivez pas dans le plan.

---

Étape 0 · Créer le projet

python3 scripts/geo.py init --url <URL du site produit> --name <Nom de la marque> --market both

--market prend cn / global / both.

Le double marché n'est pas « on fait aussi l'international en passant », ce sont deux champs de bataille parallèles – la banque de questions, le contenu, la liste des concurrents et les indicateurs sont complètement séparés. Discipline à voir dans la section 5 de global-platforms.md.

Étape 1 · Comprendre le produit, établir la base de faits

Lisez le site officiel + les documents fournis par l'utilisateur (PDF, PPT, documents, articles WeChat, etc.), complétez geo.json :

• brand : nom officiel, alias et fautes d'orthographe courantes (base de la désambigüisation de la marque), gammes de produits, secteur, utilisateurs cibles, objectifs commerciaux.
• competitors : 3 à 6 vrais concurrents, avec alias. Peut être laissé vide pour la première période – lancez d'abord un échantillonnage des questions de type « recommandation », déduisez l'ensemble concurrentiel réel à partir des réponses IA, c'est bien plus précis qu'une estimation subjective. Pour le double marché, les concurrents nationaux et internationaux ne sont généralement pas les mêmes, il faut tous les lister (l'indicateur de classement est calculé par rapport à cette liste, oublier un vrai concurrent surestimera votre classement).

Écrivez également work/<slug>/content/facts.md (fiche de faits de marque), modèle dans content-patterns.md section 1. Chaque fait doit être marqué d'un niveau de preuve A–E, ceux sans source sont marqués « à confirmer », ne pas inventer. Ce fichier est l'entrée pour la génération de tous les assets ultérieurs – llms.txt, JSON-LD, blocs de définition en proviennent.

Si les documents sont insuffisants, demandez directement à l'utilisateur, ne devinez pas les capacités ou les prix du produit.

Étape 2 · Construire la banque de questions

La banque de questions détermine ce qui est échantillonné, quel contenu est écrit et comment les indicateurs sont calculés. Pour chacun des sept groupes, créez 3 à 6 questions : Recommandation / Comparaison / Alternative / Prix / Risque / Vérification de marque / Scénario.

Chaque question doit avoir une balise market, le script achemine en fonction – les questions en chinois ne seront pas envoyées à Perplexity, les questions en anglais ne seront pas envoyées à Doubao :

{"id": "q001", "group": "Recommandation", "market": "cn",     "text": "Quels sont les bons SaaS pour la gestion de la clientèle privée en Chine ?"}
{"id": "q101", "group": "Recommandation", "market": "global", "text": "What's the best CRM for small B2B teams in 2026?"}
{"id": "q900", "group": "Vérification de marque", "market": "both", "text": "<Marque> c'est quoi comme entreprise ?"}

• cn : formulation orale chinoise, pas de traduction forcée ｜ global : formulation native anglaise, pas de traduction automatique.
• both est réservé aux questions de vérification de marque. Notez que ce type de questions nomme la marque, la réponse répétera forcément le nom de la marque, le script les classera séparément dans « Notoriété de marque », sans les mélanger dans les indicateurs de visibilité.

---

Cycle par période (serve le fait automatiquement, voici ce que fait chaque étape)

Crawling + Audit

Notation sur six dimensions : Crawlabilité / Longueur / Structure / Blocs extractibles / Signaux d'autorité / Pertinence. En lisant les résultats, regardez d'abord quatre choses :

1. Pages SPA vides (word_count proche de 0) – le défaut mortel le plus courant des sites officiels chinois, le crawler IA voit du blanc.
2. Est-ce que robots.txt bloque les crawlers IA – si oui, rien à faire.
3. language_coverage – l'anglais et le chinois sont-ils équivalents – faire de l'international sans page native anglaise est une P0 directe.
4. block_gap – le bloc le plus manquant – première priorité de l'ingénierie de contenu.

Échantillonnage des réponses IA

Marché	Plateforme	Variable	Description
Chine	Zhipu GLM	ZHIPUAI_API_KEY	Point d'accès compatible OpenAI, non connecté
Chine	Doubao	ARK_API_KEY	Volcano Ark ; l'accès à Internet nécessite d'activer séparément le plugin de contenu dans la console, sinon dégradation automatique
Chine	DeepSeek	DEEPSEEK_API_KEY	Non connecté, test de la notoriété de marque dans les connaissances paramétrées du modèle
Chine	Kimi	MOONSHOT_API_KEY	Par défaut non connecté
Chine	MiniMax	MINIMAX_API_KEY	Point d'accès compatible OpenAI, non connecté
International	Gemini	GEMINI_API_KEY	Point d'accès compatible OpenAI, sans grounding
International	OpenAI (ChatGPT)	OPENAI_API_KEY	Chat Completions, par défaut non connecté
International	Claude	ANTHROPIC_API_KEY	Protocole natif Anthropic, non connecté
International	Grok	XAI_API_KEY	API xAI, non connecté
International	Perplexity	PERPLEXITY_API_KEY	Connecté nativement et retourne les citations, meilleure qualité de preuve pour l'international

Les clés sont placées dans le fichier .env à la racine du projet (déjà dans gitignore, permissions 600), le script les charge automatiquement.

Doubao en mode 302.AI passe par une combinaison « recherche + réponse », le timeout par question est lu dans AI302AI_SEARCH_ASK_TIMEOUT du .env (45s par défaut). En cas d'anomalie de plateforme/point d'accès, consultez d'abord references/known-issues.md, ne laissez pas la tâche tourner à vide.

Pour les plateformes sans API de connexion publique – Nami IA / Baidu IA / Doubao App en Chine, ChatGPT Web / Claude Web à l'international – passez par un échantillonnage manuel ou navigateur :

python3 scripts/geo.py sample-sheet --slug <projet>
python3 scripts/geo.py sample-import --slug <projet> --file <feuille_echantillonnage>

Discipline de mesure (voir method.md section 4) :

• Chine ≠ International, le taux de mention moyen entre les marchés n'a pas de sens explicatif, le rapport a un tableau pour chacun.
• API ≠ Web, Web ≠ App (Qwen web et App n'ont que 24,5% de sources en commun), enregistrer et calculer séparément.
• Sans le texte original de la réponse / capture d'écran / enregistrement de l'environnement d'échantillonnage, ne pas marquer comme « échantillonnage réel ».
• Attribution par défaut : « corrélation observée », sauf s'il y a une fenêtre de base + un Prompt de contrôle + une comparaison avec les concurrents.
• Fréquence d'échantillonnage modérée, respectez les conditions d'utilisation des plateformes, pas d'échantillonnage en masse, pas de connexion simulée.

Génération de tickets plan

Résultats du diagnostic → tasks.json, c'est la source unique de vérité pour l'état d'exécution. Chaque ticket doit avoir : une source (quelle règle de method.md), un rôle responsable, une charge de travail, une fenêtre de temps, des critères d'acceptation, un marché.

Sept paquets de travail : Désambigüisation d'entité / Technique de page / Matrice de contenu / Système de titres / Base de connaissances / Preuve externe / Boucle de surveillance.

Ordre de priorité (section 6 de method.md) : Questions d'accès → Erreurs factuelles → Lacunes de blocs extractibles → Questions de grande valeur sans réponse → Sources externes (P1, pas P2) → Extension en longue traîne.

Les sources externes sont P1 pas P2, car le site officiel ne représente que 1,37% des citations de la base complète. Le site officiel est une source de fait, pas une source de citation. Le rendement marginal de l'améliorer de 60 à 90 est bien inférieur à celui d'obtenir une entrée sur un site d'annuaire.

Production d'assets generate

Dans work/<slug>/assets/, chinois et anglais séparés :

Produit	Description
llms.txt / llms.en.txt	Index officiel des faits, à placer directement à la racine du site
jsonld/*.json	Organization / SoftwareApplication / FAQPage / Article / BreadcrumbList, à intégrer dans <head>
snippets/definition.*.html	Bloc de définition, à placer sous le slogan de la première page (le slogan est conservé, n'affecte pas la conversion)
snippets/faq.*.html	Bloc FAQ, les réponses doivent être visibles dans le HTML statique, pas de pliage en JS pur
outlines/*.md	Un plan de contenu pour chaque question cible (avec suggestions de titres, squelette de chapitre, nombre de mots et exigences de blocs extractibles)
drafts/*.md	Avec --draft, appelle le LLM configuré pour produire un brouillon complet du texte

Répartition : Les assets structurels sont générés de manière déterministe par le code (pas d'oubli de champ schema) ; le corps de l'article est écrit par vous selon le plan – le code ne peut pas écrire une bonne copie. Le brouillon de --draft doit être vérifié manuellement avant publication.

Vérification automatique verify

Re-crawler le site → exécuter le checker → mettre à jour le statut des tickets. C'est la frontière entre « service » et « conseil » : Si on peut vérifier automatiquement, on ne se fie pas à une déclaration verbale. Terminé -> done, régression -> todo.

Pour les éléments non vérifiables par programme (ex : approbation d'une entrée Wikipédia), marquez « En attente de validation manuelle », puis marquez manuellement :

python3 scripts/geo.py task --slug <projet> --id T-003 --status done --note "Entrée en ligne"
python3 scripts/geo.py status --slug <projet>     # Tableau de bord d'avancement

Livraison client deliver

Packaging dans work/<slug>/delivery/<date>/ : index de synthèse, rapport de diagnostic, plan d'exécution, tableau des tickets (HTML + CSV importable dans un outil de gestion de projet), tableau de vérification, carte de construction, performance des moteurs / comparaison concurrents (réutilise la même méthodologie analytics de l'interface, taux de mention par moteur / part de citation / relecture des échantillons + matrice concurrents×moteur / questions non couvertes), dossier assets, instructions de livraison.

Ce que vous devez faire après l'exécution (ce que le script ne peut pas faire) :

1. Lire reports/latest.md pour voir le delta : variation du score moyen, changement du taux de mention, nouvelles P0.
2. Regarder le « Top des domaines sources réellement cités par l'IA » et « Comparaison avec le marché national dans son ensemble » – c'est la vraie carte de distribution de la période, utilisez-la pour corriger le plan des sources externes.
3. Vérifier s'il y a des erreurs factuelles dans les réponses échantillonnées (mauvaise marque, confusion, erreur de prix, mauvaise classification sectorielle) → immédiatement P0.
4. Écrire le contenu selon outlines/, mettre à jour l'avancement selon plan.md.

Rythme suggéré : Audit du site chaque semaine, échantillonnage des réponses toutes les deux semaines ou chaque mois (l'échantillonnage a un coût, les indicateurs sont bruités, trop fréquent ne montre pas de signal).

---

Toutes les commandes

Commande	Rôle
new	★ Avec une seule URL, produit automatiquement trois livrables
autopilot	Exécute le processus de guidage complet pour un projet déjà créé
bootstrap	Déduit les faits de marque, concurrents et banque de questions à partir du contenu du site officiel
deliverables	Produit les trois livrables officiels (diagnostic/optimisation/exécution)
init	Crée uniquement le squelette du projet, sans exécuter le processus
crawl / audit	Crawler le site / Audit multidimensionnel
sample / sample-sheet / sample-import	Échantillonnage API / Exporter la feuille d'échantillonnage manuelle / Réimporter
plan	Résultats du diagnostic → Tickets avec critères d'acceptation
generate	Produit les assets déployables (--draft ajoute le brouillon LLM)
report	Rapport Markdown + HTML autonome, avec delta et comparaison avec le marché
verify	Recrawler et vérifier automatiquement les tickets (--no-recrawl utilise les résultats existants)
task / status	Statut d'un ticket individuel / Tableau de bord du projet
deliver	Packager les livrables client
ui	Interface complète : création de projet, configuration, banque de questions, fiches de faits, exécution en un clic, tickets, assets, livraison
serve	Processus complet en une seule commande
cycle	Cycle léger (crawl → audit → échantillonnage → rapport, sans tickets ni livraison)
list	Tous les projets

Exécution planifiée automatique

Utilisez le skill schedule pour créer des tâches planifiées :

Exécuter tous les lundis matin python3 /Users/brucejan/geo/scripts/geo.py serve --slug <projet>, puis lire work/<projet>/reports/latest.md, si une nouvelle P0 apparaît, si le taux de mention baisse de plus de 10 points de pourcentage, ou si un ticket repasse de done à todo, prévenez-moi.

---

Périmètre

Fait : Diagnostic GEO, plan, tickets, ingénierie de contenu, génération d'assets, surveillance des réponses IA, boucle de vérification, pack livrable client.

Ne fait pas :

• Classement de mots-clés SEO traditionnels, achat de liens, enchères publicitaires
• Implémentation réelle de code pour la création/modification de site (donne le plan et des extraits directement utilisables, la mise en œuvre est faite par le développeur client)
• Collecte en masse contournant les limites des plateformes, simulation de connexion, manipulation de trafic
• Invention de faits de marque, cas clients, prix ou qualifications – si non trouvé, marquez « à confirmer », demandez à l'utilisateur

Ne garantit pas qu'une plateforme citera une page particulière. Le GEO augmente la probabilité, pas la certitude. Cette phrase doit être écrite textuellement dans le plan remis au client.

---

Structure des dossiers

/Users/brucejan/geo/
├── SKILL.md
├── references/
│   ├── method.md              Référentiel de notation et sources de tous les critères
│   ├── cn-source-ranking.md   Classement réel des sources chinoises (calcul CN-GEO, avec script de recalcul)
│   ├── cn-platforms.md        Adaptation aux plateformes chinoises
│   ├── global-platforms.md    Adaptation aux plateformes internationales
│   ├── content-patterns.md    Modèles de contenu extractible
│   └── sources.md             Index des ressources (inclut le choix entre GEORank / GEOFlow)
├── scripts/
│   ├── geo.py       Point d'entrée principal CLI
│   ├── crawl.py     Crawler      audit.py     Audit multidimensionnel
│   ├── sample.py    Échantillonnage multiplateforme  benchmark.py  Comparaison avec le marché national
│   ├── tasks.py     Système de tickets    generate.py  Génération d'assets
│   ├── verify.py    Vérification automatique    deliver.py   Pack livrable client
│   ├── bootstrap.py Déduction automatique de la base  deliverables.py  Trois livrables
│   ├── blueprint.py Carte de construction
│   ├── dashboard.py Backend interface    ui.html      Poste de travail frontend
│   ├── jobs.py      Tâches d'arrière-plan (sous-processus + logs en temps réel)
│   └── report.py    Rendu de rapport    geolib.py    Outils partagés
└── work/<slug>/
    ├── geo.json        Marque, concurrents, banque de questions, plateformes, objectifs
    ├── content/facts.md Fiche de faits de marque (entrée pour tous les assets)
    ├── evidence/       Snapshot du crawl      audit.json   Résultats de l'audit
    ├── samples/        Réponses brutes échantillonnées   metrics/     Indicateurs par période
    ├── tasks.json      Tickets (source unique de vérité pour l'état d'exécution)
    ├── assets/         Assets déployables
    ├── reports/        Rapports par période + latest.md
    ├── verify/         Résultats de vérification par période
    ├── delivery/<date>/ Pack livrable client
    ├── history/        Lignes de base historiques (pour calcul des deltas)
    └── plan.md         Plan 30/60/90