liangdabiao/geo

GEO Full-Service Pipeline

The complete pipeline from diagnosis to delivery—not just advice:

Crawl → Audit → AI Answer Sampling → Generate Tickets → Produce Assets → Report → Auto-Verify → Client Delivery Package

Core principle: The end goal of GEO is not a ranking; it's whether that sentence in the AI answer says exactly what you want it to say. Therefore, the smallest unit is not a page but an extractable fact block.

Project directory: /Users/brucejan/geo, with each client/product in work/<slug>/.

---

Quickest Usage: Provide a URL

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

Nine steps fully automated: create project → crawl website → audit → automatically infer brand facts/competitors/question bank → re-run audit → AI answer sampling → tickets and construction blueprint → assets and reports → three deliverables.

Output in work/<slug>/deliverables/:

File	Answers What
1-GEO-Diagnostic-Report.html	Current state
2-GEO-Optimization-Plan.html	What it should become and why
3-GEO-Execution-Plan.html	Who does what, when, and what counts as done

Automatically inferred brand facts must be manually reviewed—the bootstrap only extracts from the official website body. Anything it cannot extract is marked "pending confirmation"; never fill in with common sense. Fields marked "pending confirmation" (founding date, business entity, named clients, etc.) require you to fill in or explicitly state they are not for public disclosure.

Two Usage Modes

UI (Recommended)

python3 scripts/geo.py ui        # Default http://127.0.0.1:8765

Full workflow on the interface—no need to memorize commands: create projects, edit configuration and question banks, write fact cards, one-click run any step or the entire cycle (with real-time logs), change ticket statuses, view assets, import manual sampling sheets, open the delivery package.

The interface is a dark-themed four-stage main line (AtlasGEO): Current State (Overview / Engine Performance / Competitor Comparison / Question Bank) → Diagnosis (Gap Analysis / Position Map / Brand Fact Repository) → Improvement (Action Plan / Content Workbench) → Results (Effectiveness Verification / Reports and Delivery), plus settings and a three-step onboarding guide. Unified metrics: GEO Health Score (five weighted dimensions, weights normalized for untested dimensions), Mention Rate, Citation Share, Position, Tasks, Content. The overview title is a dynamically generated conclusion from data; all numbers come from the same sample; if a value cannot be calculated, it shows "Not Tested"—no fabricated numbers. Tasks run in background sub-processes; closing the page does not stop them. Only one task is allowed per project at a time to avoid conflicts over the same audit.json.

Uses only standard library to serve, zero external dependencies for the frontend, works offline.

Command Line

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

Completes the entire workflow: crawl → audit → sample → tickets → assets → report → verify previous period → package deliver. Output in work/<slug>/delivery/<date>/, ready to send to the client.

For a new client, follow steps 0–2 below to build the foundation first, then run the above command each period thereafter.

---

What to Read First

• Must read every time: references/method.md (scoring criteria and sources for all judgments; the script is its code implementation)
• Must read when prioritizing external sources: references/cn-source-ranking.md (CN-GEO 187,818 citation real-world ranking. Official websites account for only 1.37%—this number will change resource allocation)
• For domestic platforms: references/cn-platforms.md ｜ For international: references/global-platforms.md
• For writing content / modifying pages: references/content-patterns.md
• For deeper methods or raw data: references/sources.md (includes GEORank / GEOFlow selection rationale)
• Check platform anomalies first: references/known-issues.md (Doubao timeout, 302 domestic/international endpoint model directory, SPA empty shell, llms.txt range filtering)

Do not give GEO advice based on experience alone. Every recommendation must be traceable to a specific measured number in method.md; if you cannot cite a source, do not include it in the plan.

---

Step 0 · Create Project

python3 scripts/geo.py init --url <product website> --name <brand name> --market both

--market takes cn / global / both.

"Both" markets does not mean "also do international as an afterthought"—it means two parallel battlefields—question banks, content, competitor lists, and metrics are all separate. Discipline rules in global-platforms.md section 5.

Step 1 · Understand the Product, Build the Fact Foundation

Read the official website + user-provided materials (PDFs, PPTs, documents, WeChat articles, etc.), complete geo.json:

• brand: canonical name, aliases and common misspellings (foundation for brand disambiguation), product lines, industry, target users, business objectives
• competitors: 3–6 real competitors, with aliases. Can be left empty for the first period—run a round of "recommendation" type question sampling, then infer the real competitive set from AI answers; this is far more accurate than subjective guessing. When targeting both markets, domestic and international competitors are usually not the same; list all of them (ranking metrics are calculated relative to this list; missing a real competitor will overestimate your rank)

Also write work/<slug>/content/facts.md brand fact cards, template in content-patterns.md section 1. Every fact must have an evidence level A–E; if there's no source, mark it "pending confirmation"; never fabricate. This file is the input for all subsequent asset generation—llms.txt, JSON-LD, definition blocks all come from it.

If materials are insufficient, directly ask the user for more; do not guess product capabilities or pricing.

Step 2 · Build the Question Bank

The question bank determines what to sample, what content to write, and how to calculate metrics. Generate 3–6 questions per group: Recommendation / Comparison / Substitute / Pricing / Risk / Brand Verification / Scenario.

Every question must have a market tag—the script routes accordingly—Chinese questions will not be sent to Perplexity; English questions will not be sent to Doubao:

{"id": "q001", "group": "Recommendation", "market": "cn",     "text": "What are some good SaaS tools for private domain operations in China?"}
{"id": "q101", "group": "Recommendation", "market": "global", "text": "What's the best CRM for small B2B teams in 2026?"}
{"id": "q900", "group": "Brand Verification", "market": "both", "text": "What kind of company is <Brand>?"}

• cn: Chinese colloquial phrasing, no translationese ｜ global: English native phrasing, not machine-translated
• both only for brand verification questions. Note that these questions name the brand, so answers will inevitably repeat the brand name— the script categorizes them separately under "Brand Awareness," not mixed into visibility metrics

---

Each Period Loop (serve does this automatically; here's what each step does)

Crawl + Audit

Score across six dimensions: Crawlability / Length / Structure / Extractable Blocks / Authority Signals / Question Alignment. When reading results, check four things first:

1. SPA empty shell pages (word_count close to 0)—most common fatal issue for domestic websites; AI crawlers see a blank page
2. Robots blocking AI crawlers—if blocked, nothing else matters
3. language_coverage parity between Chinese and English—doing international without native English pages is a direct P0
4. block_gap blocks with the most gaps—content engineering priority one

AI Answer Sampling

Market	Platform	Variable	Description
CN	GLM	ZHIPUAI_API_KEY	OpenAI-compatible endpoint, no internet access
CN	Doubao	ARK_API_KEY	Volcano Engine; Internet search must be separately enabled in the console via content plugin; without it, automatic fallback
CN	DeepSeek	DEEPSEEK_API_KEY	No internet access; tests brand awareness in the model's parametric knowledge
CN	Kimi	MOONSHOT_API_KEY	No internet access by default
CN	MiniMax	MINIMAX_API_KEY	OpenAI-compatible endpoint, no internet access
Global	Gemini	GEMINI_API_KEY	OpenAI-compatible endpoint, without grounding
Global	OpenAI(ChatGPT)	OPENAI_API_KEY	Chat Completions, no internet access by default
Global	Claude	ANTHROPIC_API_KEY	Anthropic native protocol, no internet access
Global	Grok	XAI_API_KEY	xAI API, no internet access
Global	Perplexity	PERPLEXITY_API_KEY	Native internet search with citations; best evidence quality for international

Keys go in the project root .env file (already gitignored, permissions 600); the script loads them automatically.

Doubao in 302.AI mode uses a "search + answer" combination; per-question timeout reads AI302AI_SEARCH_ASK_TIMEOUT from .env (default 45s). For platform/endpoint anomalies, first check references/known-issues.md; don't let tasks idle.

For platforms without a public internet-enabled API—domestic: NanoAI search, Baidu AI, Doubao App; international: ChatGPT web, Claude web—use manual or browser sampling:

python3 scripts/geo.py sample-sheet --slug <project>
python3 scripts/geo.py sample-import --slug <project> --file <sampling sheet>

Discipline rules (see method.md section 4 for details):

• Domestic ≠ International; cross-market average mention rates are meaningless; each market has its own table in the report
• API ≠ Web, Web ≠ App (Qwen web and App share only 24.5% of sources); record and calculate separately
• Without original answer text/screenshots/sampling environment records, do not mark as "real sampling"
• Default attribution is "observed correlation" unless there is a baseline window + control prompt + competitor control
• Sample frequency must be restrained, comply with platform terms of service, no batch over-sampling, no simulated login

Generate Tickets (plan)

Diagnostic results → tasks.json, the single source of truth for execution status. Every ticket must have: Justification (traceable to which rule in method.md), responsible role, workload, time window, acceptance criteria, and market.

Seven work packages: Entity Disambiguation / Page Technology / Content Matrix / Title System / Knowledge Base / External Evidence / Monitoring Loop.

Priority order (method.md section 6): Gatekeeper questions → Factual errors → Block gap → High-value questions without coverage → External sources (P1, not P2) → Long-tail expansion.

External sources are P1 not P2, because official websites account for only 1.37% of total library citations. The official website is a source of facts, not a source of citations. The marginal benefit of improving it from 60 to 90 points is far lower than capturing one directory/listing site entry.

Produce Assets (generate)

Output to work/<slug>/assets/, separate for Chinese and English:

Product	Description
llms.txt / llms.en.txt	Official fact index; place directly at the website root
jsonld/*.json	Organization / SoftwareApplication / FAQPage / Article / BreadcrumbList; embed in <head>
snippets/definition.*.html	Definition block; place below the hero headline (keep the headline for conversion)
snippets/faq.*.html	FAQ block; answers must be visible in static HTML, not pure JS accordion
outlines/*.md	One content outline per target question (including title candidates, section structure, word count and extractable block requirements)
drafts/*.md	Full draft generated via configured LLM when adding --draft

Division of labor: structural assets are deterministically generated by code (no missing schema fields); article body text is written by you based on the outline— code cannot write good copy. The --draft output must be manually fact-checked before publication.

Auto-Verify (verify)

Re-crawl the site → run checker → update ticket status. This is the line between "service" and "advice": if it can be auto-verified, don't rely on verbal confirmation. Completed tickets become done; regression turns them back to todo.

For items that cannot be programmatically verified (e.g., whether a Baidu Baike entry has been approved), mark as "pending manual review." After manual confirmation:

python3 scripts/geo.py task --slug <project> --id T-003 --status done --note "Entry published"
python3 scripts/geo.py status --slug <project>     # Progress dashboard

Client Delivery (deliver)

Package into work/<slug>/delivery/<date>/: overview index, diagnostic report, execution plan, tickets table (HTML + CSV, importable into project management tools), verification table, construction map, engine performance / competitive comparison (reusing the same analytics metrics from the UI—mention rate/citation share/sample replay per engine + competitor×engine matrix/lost questions), assets directory, delivery instructions.

After running, you need to do the following (things the script cannot do):

1. Read reports/latest.md for deltas: average score changes, mention rate changes, newly emerged P0 issues
2. Review "Top cited domains by AI" and "Comparison with national benchmarks"—this is the real distribution map for the period; use it to adjust the external source plan
3. Check sampled answers for factual errors (wrong brand name, misattribution, wrong pricing, wrong industry classification) → immediate P0
4. Write content based on outlines/, update progress via plan.md

Recommended cadence: page audit weekly, answer sampling every two weeks or monthly (sampling has costs, metrics have inherent noise; running too frequently makes signals indistinguishable).

---

Complete Command List

Command	Purpose
new	★ Provide only a URL, fully automatic output of three deliverables
autopilot	Run the complete guided workflow for an existing project
bootstrap	Infer brand facts, competitors, and question bank from the official website
deliverables	Generate three formal deliverables (diagnostic/optimization/execution)
init	Create the project skeleton only, no workflow execution
crawl / audit	Crawl website / six-dimension audit
sample / sample-sheet / sample-import	API sampling / export manual sampling sheet / import results
plan	Diagnostic results → tickets with acceptance criteria
generate	Produce deployable assets (--draft adds LLM-generated initial draft)
report	Markdown + self-contained HTML report, including deltas and national benchmark comparison
verify	Re-crawl and auto-verify tickets (--no-recrawl uses existing results)
task / status	Single ticket status / project dashboard
deliver	Package client deliverables
ui	Full workflow UI: create projects, configure, question bank, fact cards, one-click run, tickets, assets, delivery
serve	Full workflow with one command
cycle	Lightweight loop (crawl → audit → sample → report, no tickets or delivery)
list	All projects

Scheduled Execution

Use the schedule skill to set up cron tasks:

Every Monday morning run python3 /Users/brucejan/geo/scripts/geo.py serve --slug <project>, then read work/<project>/reports/latest.md. If a new P0 appears, mention rate drops more than 10 percentage points, or a ticket regresses from done to todo, notify me.

---

Boundaries

In scope: GEO diagnostics, plans, tickets, content engineering, asset generation, AI answer monitoring, verification loop, client delivery packages.

Out of scope:

• Traditional SEO keyword ranking, link buying, paid search
• Actual code implementation of website building or modification (provide the plan and ready-to-use snippets; deployment is done by the client's development team)
• Bulk scraping that bypasses platform limits, simulated logins, traffic inflation
• Fabricating brand facts, client cases, pricing, or qualifications—if you can't verify it, mark it "pending confirmation" and ask the user

No guarantee that any platform will definitely cite a given page. GEO increases probability, not certainty. This statement must be included verbatim in any proposal written for a client.

---

Directory Structure

/Users/brucejan/geo/
├── SKILL.md
├── references/
│   ├── method.md              Scoring criteria and all judgment sources
│   ├── cn-source-ranking.md   Domestic source real-world ranking (CN-GEO computed, with re-computation scripts)
│   ├── cn-platforms.md        Domestic platform adaptation
│   ├── global-platforms.md    International platform adaptation
│   ├── content-patterns.md    Extractable content templates
│   └── sources.md             Resource index (includes GEORank / GEOFlow selection)
├── scripts/
│   ├── geo.py       CLI main entry point
│   ├── crawl.py     Website crawler      audit.py     Six-dimension audit
│   ├── sample.py    Multi-platform sampler  benchmark.py  National benchmark comparison
│   ├── tasks.py     Ticket system      generate.py  Asset generation
│   ├── verify.py    Auto-verification    deliver.py   Client delivery package
│   ├── bootstrap.py Auto-foundation inference  deliverables.py  Three deliverables
│   ├── blueprint.py Construction map
│   ├── dashboard.py UI backend        ui.html      Frontend workbench
│   ├── jobs.py      Background tasks (sub-process + real-time logs)
│   └── report.py    Report rendering      geolib.py    Shared utilities
└── work/<slug>/
    ├── geo.json        Brand, competitors, question bank, platforms, targets
    ├── content/facts.md Brand fact cards (input for all assets)
    ├── evidence/       Crawl snapshots      audit.json  Audit results
    ├── samples/        Raw sampling answers   metrics/    Periodic metrics
    ├── tasks.json      Tickets (single source of truth for execution status)
    ├── assets/         Deployable assets
    ├── reports/        Periodic reports + latest.md
    ├── verify/         Periodic verification results
    ├── delivery/<date>/ Client delivery package
    ├── history/        Historical baselines (for delta calculation)
    └── plan.md         30/60/90 plan