geo

Full GEO Service Workflow

Fromdiagnosistodeliverya complete chain, not just advice:

抓取 → 体检 → AI答案采样 → 生成工单 → 产出资产 → 报告 → 自动验收 → 客户交付包

The core judgment is just one sentence:The endpoint of GEO is not ranking, but whether that sentence in the AI answer is said according to your framing. So the smallest unit is not the page, but theextractable fact block。

Project directory:/Users/brucejan/geo, one per client/product work/<slug>/。

Fastest usage: give a URL

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

Nine steps fully automated: create project → crawl website → health check → automatically derive brand facts/competitors/question bank → rerun health check → AI answer sampling → work orders and build blueprint → assets and report → three deliverables.

Produce work/<slug>/deliverables/：

File	What it answers
`1-GEO诊断报告.html`	What it looks like now
`2-GEO优化方案.html`	What it should be changed to, and why
`3-GEO执行方案.html`	Who does what and when, and what counts as done

Automatically derived brand facts must be manually reviewed——bootstrap only extracts from the website body text, anything that cannot be extracted is uniformly marked "to be confirmed", and common sense is never used to fill it in. Fields marked "to be confirmed" (founding date, business entity, named clients, etc.) need you to fill them in or explicitly state they are not disclosed externally.

Two ways to use

Interface (recommended)

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

The entire workflow is in the interface, no need to remember commands: create projects, edit configuration and question bank, write fact cards, one-click run any step or the entire cycle (with real-time logs), change work order status, view assets, import manual sampling tables, open delivery packages.

The interface is a dark four-section mainline (AtlasGEO):Current state(overview / engine performance / competitor comparison / question bank) → Diagnosis(gap diagnosis / position map / brand fact base) → Improvement(action plan / content workbench) → Results(effect acceptance / report and delivery), plus settings and a three-step onboarding guide. Unified definitions: GEO health score (five weighted items, weights normalized for untested items), mention rate, citation share, positions, tasks, content. The overview title is a conclusion automatically generated from the data; all numbers come from the same sampling, anything that cannot be calculated shows "untested", and no numbers are made up. Tasks run in background subprocesses and continue even if the page is closed; only one task is allowed at a time for the same project, to avoid competing for the same audit.json.

The service is started using only the standard library, the frontend has zero external dependencies, and it works offline.

Command line

python3 scripts/geo.py serve --slug <项目>

Crawl → health check → sampling → work orders → assets → report → accept previous period → package delivery, all done. Output is in work/<slug>/delivery/<日期>/, ready to send directly to the client.

When onboarding a new client for the first time, follow steps 0–2 below to build the foundation, and afterward only run this one command each period.

What to read first

Required reading every time：references/method.md(the source of the scoring definitions and all criteria; the script is its code implementation)
Required reading when prioritizing external sources：references/cn-source-ranking.md (CN-GEO 187,818 citations actual-calculation ranking.Official websites account for only 1.37%, and this number will change resource allocation)
Target domestic platforms:references/cn-platforms.md | Target overseas:references/global-platforms.md
Write content/edit pages:references/content-patterns.md
Deeper methods or raw data:references/sources.md(including GEORank / GEOFlow selection notes)
For sampling/platform anomalies, check the table first：references/known-issues.md(Doubao timeout, 302 domestic/overseas endpoint model catalog, SPA empty shell, llms.txt scope filtering)

Do not give GEO advice based on experience.Every recommendation must be traceable to method.md some measured number in it, and anything you cannot justify should not be written into the plan.

Step 0 · Create project

python3 scripts/geo.py init --url <产品官网> --name <品牌名> --market both

--market take cn / global / both。

Dual markets are not "also do overseas as a side thing", but two parallel battlefields—question bank, content, competitor list, and metrics are all separate. For discipline, see global-platforms.md Section 5.

Step 1 · Fully understand the product and build the factual foundation

Read the official website + materials provided by the user (PDF/PPT/documents/WeChat official account articles are all fine), and complete geo.json：

brand: canonical name,aliases and common misspellings(the foundation of brand disambiguation), product lines, industry, target users, business goals
competitors: 3–6 real competitors, with aliases.Can be left blank in the first phase—first run one round of sampling for "recommendation-type" questions, and infer the real competitive set from AI answers; this is much more accurate than subjective guesswork. In dual markets, domestic and overseas competitors are usually not the same group, and all must be listed (the ranking metric is calculated relative to this list; missing real opponents willoverestimatethe ranking)

At the same time, write work/<slug>/content/facts.md brand fact card, template see content-patterns.md Section 1. Mark each fact with evidence level A–E; mark those without sources as "to be confirmed"; do not make things up. This file is the input for all subsequent asset generation—llms.txt, JSON-LD, and definition blocks all come from it.

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

Step 2 · Build question bank

The question bank determines what to sample, what content to write, and how to calculate metrics. Produce 3–6 questions for each of the seven groups: recommendation / comparison / alternative / price / risk / brand verification / scenario.

Each question must be marked market, and the script routes accordingly—Chinese questions will not hit Perplexity, and English questions will not hit Doubao:

{"id": "q001", "group": "推荐", "market": "cn",     "text": "国内做私域运营的 SaaS 有哪些好用的？"}
{"id": "q101", "group": "推荐", "market": "global", "text": "What's the best CRM for small B2B teams in 2026?"}
{"id": "q900", "group": "品牌验证", "market": "both", "text": "<品牌> 是家什么公司？"}

cn: Chinese colloquial phrasing, no translationese | global：native English phrasing, not machine translation
both is reserved only for brand verification type. Note that this type of questionnames the brand, so the answer will inevitably repeat the brand name, and the script will classify them separately under "brand awareness" and not mix them into visibility metrics

Each cycle (`serve` is done automatically; here we explain what each step is doing)

Crawl + health check

Score by six dimensions: crawlability / length / structure / extractable blocks / authority signals / question relevance. When reading the results, look at four things first:

SPA empty shell page（word_count close to 0)—the most common fatal flaw of domestic official websites; what AI crawlers see is blank
whether robots blocks AI crawlers—if blocked, then nothing else matters
language_coverage Are Chinese and English equivalent?—Going overseas without a native English page is directly P0
block_gap The most missing block—The top priority of content engineering

AI answer sampling

Market	Platform	Variable	Description
Domestic	Zhipu GLM	`ZHIPUAI_API_KEY`	OpenAI-compatible endpoint, no internet access
Domestic	Doubao	`ARK_API_KEY`	Volcano Ark;internet access requires separately enabling the content plugin in the console, and if not enabled it automatically degrades
Domestic	DeepSeek	`DEEPSEEK_API_KEY`	No internet access, tests brand awareness in the model's parametric knowledge
Domestic	Kimi	`MOONSHOT_API_KEY`	No internet access by default
Domestic	MiniMax	`MINIMAX_API_KEY`	OpenAI-compatible endpoint, no internet access
Overseas	Gemini	`GEMINI_API_KEY`	OpenAI-compatible endpoint, without grounding
Overseas	OpenAI(ChatGPT)	`OPENAI_API_KEY`	Chat Completions has no internet access by default
Overseas	Claude	`ANTHROPIC_API_KEY`	Anthropic native protocol, no internet access
Overseas	Grok	`XAI_API_KEY`	xAI API, no internet access
Overseas	Perplexity	`PERPLEXITY_API_KEY`	Native internet access and returns citations, best overseas evidence quality

Put the Key in the project root directory .env(already gitignored, permissions 600), the script loads it automatically.

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

Those without a public internet-access API—domestic Nami AI Search/Baidu AI/Doubao App, overseas ChatGPT web version/ Claude web version—use manual or browser sampling:

python3 scripts/geo.py sample-sheet --slug <项目>
python3 scripts/geo.py sample-import --slug <项目> --file <采样表>

Caliber discipline(see method.md Section 4):

Domestic ≠ Overseas, cross-market average mention rates have no explanatory power, each gets its own table in the report
API ≠ Web, Web ≠ App (Qwen web and App sources overlap only 24.5%), record and calculate separately
Without the original answer text/screenshots/sampling environment records,it must not be marked as "real sampling"
Attribution defaults to "observed correlation" unless there is a baseline window + control Prompt + competitor comparison
Sampling frequency should be restrained, comply with platform terms of service, no mass abusive sampling, no simulated login

Generate work orders `plan`

Diagnosis results → tasks.json, this is the execution state'ssingle source of truth. Each work order must have: basis (traceable to method.md which one), responsible role, workload, time window,acceptance criteria, market.

Seven work packages: entity disambiguation / page technology / content matrix / title system / knowledge base / external evidence / monitoring loop.

Priority order (method.md Section 6): ticket issues → factual errors → extraction block gaps → high-value questions with no承接 → external sources (P1, not P2) → long-tail expansion.

External sources are P1 not P2, becausethe official website accounts for only 1.37% of all citations。 The official website is the source of truth, not a citation source. The marginal gain from taking it from 60 to 90 points is far lower than winning a ranking-site entry.

Produce assets `generate`

to work/<slug>/assets/, Chinese and English separately:

Artifact	Description
`llms.txt` / `llms.en.txt`	Official fact index, upload directly to the website root directory
`jsonld/*.json`	Organization / SoftwareApplication / FAQPage / Article / BreadcrumbList, paste into `<head>`
`snippets/definition.*.html`	definition block, place below the hero tagline (keep the tagline, it does not affect conversion)
`snippets/faq.*.html`	FAQ block,answers must be visible in static HTML, not pure JS collapse
`outlines/*.md`	one content outline per target question (including title candidates, section skeleton, word count and extraction block requirements)
`drafts/*.md`	add `--draft` , call the configured LLM to produce a full-text draft

Division of labor: structural assets are generated deterministically by code (schema fields will not be missed);article body text is written by you according to the outline—— code cannot write good copy.--draft 's draftmust be manually fact-checked before publication。

Automatic acceptance `verify`

Re-crawl the site → run checker → write back ticket status.This is the dividing line between "service" and "suggestion": anything that can be automatically accepted does not rely on people saying it is done. When done it will flip to done, and when it regresses it will flip back to todo。

For things that cannot be programmatically determined (such as whether an encyclopedia entry is approved), mark "pending manual review", and after confirmation mark manually:

python3 scripts/geo.py task --slug <项目> --id T-003 --status done --note "词条已上线"
python3 scripts/geo.py status --slug <项目>     # 进度看板

Client delivery `deliver`

package to work/<slug>/delivery/<日期>/: overview index, diagnostic report, execution plan, ticket table (HTML + CSV, importable into project management tools), acceptance table, build map,engine performance / competitor comparison (reusing the same set of analytics metrics as the UI, per-engine mention rate/citation share/sample replay + competitor × engine matrix/lost questions), assets directory, delivery notes.

What you need to do after the run (the parts scripts cannot do):

Read reports/latest.md to see the delta: average score change, mention rate change, newly appearing P0s
Look at "Top source domains actually cited by AI" and "comparison with the national baseline"——this is the real distribution map for the current period, use it to revise the external source plan
Check the sampled answers forfactual errors(wrong brand, misattribution, wrong price,wrong industry) → immediately P0
according to outlines/ write content, according to plan.md update progress

Recommended cadence:page checkup weekly, answer sampling every two weeks or monthly(sampling has a cost, the metrics themselves are noisy, and if you run it too densely you cannot see the signal).

All commands

Command	Effect
`new`	★ give just one URL and automatically produce three deliverables
`autopilot`	run the full onboarding process for an already built project
`bootstrap`	derive brand facts, competitors and question bank from the official website body text
`deliverables`	produce three formal deliverables (diagnosis/optimization/execution)
`init`	only build the project skeleton, do not run the process
`crawl` / `audit`	crawl site / six-dimension checkup
`sample` / `sample-sheet` / `sample-import`	API sampling / export manual sampling table / backfill
`plan`	Diagnosis results → work orders with acceptance criteria
`generate`	Produce deployable assets (`--draft` plus LLM first draft)
`report`	Markdown + self-contained HTML report, including delta and comparison with the overall market
`verify`	Re-crawl and automatically accept work orders (`--no-recrawl` use existing results)
`task` / `status`	Single work order status / project dashboard
`deliver`	Package client deliverables
`ui`	Full-process interface: create new project, configuration, issue library, fact cards, one-click run, work orders, assets, delivery
`serve`	Full process in one command
`cycle`	Lightweight loop (crawl → health check → sampling → report, excluding work orders and delivery)
`list`	All projects

Scheduled automatic execution

Use schedule skill to create a scheduled task:

Run every Monday morning python3 /Users/brucejan/geo/scripts/geo.py serve --slug <项目>, then read work/<项目>/reports/latest.md, if a new P0 appears, the mention rate drops by more than 10 percentage points, or a work order regresses from done to todo, tell me.

Boundaries

Do: GEO diagnosis, solutions, work orders, content engineering, asset generation, AI answer monitoring, acceptance loop, client delivery package.

Do not do：

Traditional SEO keyword rankings, link buying and selling, paid search advertising
Actual code implementation for building/modifying websites (provide solutions and ready-to-use snippets; implementation is done by the client's developers)
Bulk scraping, simulated login, or traffic manipulation that bypasses platform restrictions
Fabricate brand facts, client cases, prices, or qualifications—if it cannot be found, mark it as "to be confirmed" and ask the user

Do not promisethat any platform will definitely cite a certain page. GEO increases probability, not a guarantee. When writing proposals for clients, this sentence must be included verbatim.

/Users/brucejan/geo/
├── SKILL.md
├── references/
│   ├── method.md              评分口径与全部判据出处
│   ├── cn-source-ranking.md   国内信源实测榜（CN-GEO 实算，含复算脚本）
│   ├── cn-platforms.md        国内平台适配
│   ├── global-platforms.md    海外平台适配
│   ├── content-patterns.md    可抽取内容模板
│   └── sources.md             资料索引（含 GEORank / GEOFlow 选型）
├── scripts/
│   ├── geo.py       CLI 总入口
│   ├── crawl.py     抓站      audit.py     六维体检
│   ├── sample.py    多平台采样  benchmark.py 与全国大盘对照
│   ├── tasks.py     工单系统    generate.py  资产生成
│   ├── verify.py    自动验收    deliver.py   客户交付包
│   ├── bootstrap.py 自动推导底座  deliverables.py 三份交付物
│   ├── blueprint.py 建设地图
│   ├── dashboard.py 界面后端    ui.html      前端工作台
│   ├── jobs.py      后台任务（子进程 + 实时日志）
│   └── report.py    报告渲染    geolib.py    共用工具
└── work/<slug>/
    ├── geo.json        品牌、竞品、问题库、平台、目标
    ├── content/facts.md 品牌事实卡（所有资产的输入）
    ├── evidence/       抓取快照      audit.json  体检结果
    ├── samples/        采样原始答案   metrics/    每期指标
    ├── tasks.json      工单（执行状态单一真相源）
    ├── assets/         可部署资产
    ├── reports/        每期报告 + latest.md
    ├── verify/         每期验收结果
    ├── delivery/<日期>/ 客户交付包
    ├── history/        历史基线（算 delta）
    └── plan.md         30/60/90 方案

About this skill

Fastest usage: give a URL

Two ways to use

Interface (recommended)

Command line

What to read first

Step 0 · Create project

Step 1 · Fully understand the product and build the factual foundation

Step 2 · Build question bank

Each cycle (`serve` is done automatically; here we explain what each step is doing)

Crawl + health check

AI answer sampling

Generate work orders `plan`

Produce assets `generate`

Automatic acceptance `verify`

Client delivery `deliver`

All commands

Scheduled automatic execution

Boundaries

Table of contents

geo

About this skill

Fastest usage: give a URL

Two ways to use

Interface (recommended)

Command line

What to read first

Step 0 · Create project

Step 1 · Fully understand the product and build the factual foundation

Step 2 · Build question bank

Each cycle (serve is done automatically; here we explain what each step is doing)

Crawl + health check

AI answer sampling

Generate work orders plan

Produce assets generate

Automatic acceptance verify

Client delivery deliver

All commands

Scheduled automatic execution

Boundaries

Table of contents

Each cycle (`serve` is done automatically; here we explain what each step is doing)

Generate work orders `plan`

Produce assets `generate`

Automatic acceptance `verify`

Client delivery `deliver`