GEO SEO Hub

Version 0.7.0 · Experimental · GEO-first · SEO-ready

GEO SEO Hub is an open, protocol-first agent skill hub with active GEO workflows and an SEO-ready shared foundation. Version 0.7.0 adds bounded multi-page website GEO diagnosis and a standalone visual report to the existing Artifact Bus, evaluation lab, hybrid routing, TaskPlans, discovery, explicit-source diagnosis, content, measurement, strategy optimization, knowledge governance, and eight active Skills.

The skills are Library-engineered packages while product behavior remains Experimental. maturity_tier=library describes packaging rigor and does not claim production outcome quality.

Current scope

• geo: routes Chinese and English requests through the registry and reports unavailable routes honestly.
• geo-discover: converts a validated GEO brief into a deterministic query map, opportunity map, evidence ledger, run manifest, and quality report.
• geo-diagnose: evaluates explicit brand, site, or page sources and emits a structured diagnosis, deterministic report, evidence ledger, remediation query map, opportunity map, quality report, and run manifest.
• geo-site-diagnose: starts from one public URL, discovers up to ten representative page types on the same host, emits reconstructable eight-dimension scores, and generates one offline ten-module visual HTML report.
• geo-content: creates evidence-lined titles, explainers, comparisons, rankings, page blueprints, refinements, and article-friendly artifacts as JSON, Markdown, and standalone HTML; DOCX/PDF are optional render layers.
• geo-measure: computes reproducible visibility, mention, source-inclusion, citation-share, and panel-coverage metrics from approved offline engine-observation bundles.
• geo-strategy: produces bounded intervention candidates, fidelity checks, experiment plans, external publication handoffs, and positive-only strategy memory.
• geo-knowledge: builds source-lined entity graphs, preserves conflicting facts, supports local/global queries, and replaces changed source-hash contributions.
• geo-publish: remains a visible roadmap route with planned status and no execution authority.

The resolver emits single_skill, workflow, clarify, abstain, or unavailable decisions. Lexical routing is always available; an explicitly prepared local FastEmbed cache can add clause-level semantic matches without network access. Exact workflows include brand-baseline-lite, content-campaign, brand-baseline-content, and the gated strategy-observation-loop. route --plan-output compiles a validated TaskPlan. workflow start runs it to completion or the next approval/external-evidence gate. The planned publish route keeps external write authority disabled. Route requests are bounded to 8,000 characters and 16,384 UTF-8 bytes. See skills/RESOLVER.md and docs/architecture.md.

No connector, live platform sampling, search volume, ranking, or conversion data is inferred. Missing evidence remains explicit in generated artifacts. Every executable run includes run-lineage.json with artifact hashes and allowlisted operational metadata. Run payloads stay out of adoption and drift aggregation.

GEO and SEO boundary

GEO SEO Hub treats GEO and SEO as related capability domains with a shared search foundation. Query intent, source evidence, brand facts, entity structure, content specifications, site parsing, quality reports, and Artifact Bus contracts can serve both domains.

Version 0.7.0 ships executable GEO discovery, explicit-source diagnosis, bounded website diagnosis, content, observation-bundle measurement, strategy planning, knowledge governance, routing, TaskPlan compilation, and gated workflow execution. Strategy execution pauses for human publication approval, then requires a verified publication receipt and approved observation bundle before measurement. Dedicated SEO workflows and outcome claims for technical SEO, SERP and keyword data, indexation, Core Web Vitals, internal linking, Search Console, and traffic measurement remain future Registry additions.

Version 0.6 retains geo-seo-hub as the distribution and CLI namespace, geo_seo_hub as the Python module, and share/geo-seo-hub as the installed data root. Existing geo-* Skill IDs, public imports, provider CLI contracts, legacy execution defaults, and Artifact Bus protocol 1.0.0 remain stable. Workflow state moves to 2.0.0 through an explicit backup migration. See docs/migration-0.6.md and CHANGELOG.md.

Quick start

Supported Python range: 3.11-3.14.

git clone https://github.com/yaojingang/geo-seo-hub.git
cd geo-seo-hub
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/geo-seo-hub --version
.venv/bin/geo-seo-hub route --text "帮我挖掘 AI 搜索问题"
.venv/bin/geo-seo-hub route --text "先拓词，再诊断网站" --plan-output task-plan.json

For development and the full release gate:

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python scripts/verify_all.py

Community packages:

python3 scripts/package.py --target all --channel community
python3 scripts/verify_packages.py
python3 scripts/install_simulation.py --target all

The twelve artifacts are a source ZIP, one unified single-Skill ZIP, eight provider Skill ZIPs, and Codex/Claude adapter ZIPs. Each ZIP supports pip install . from its extraction root. Unified and target adapters contain eight parseable provider entries and wrappers. Every community artifact is AGPL-3.0-only; commercial metadata remains inquiry_only. Version 0.7.0 has no verified GitHub Release assets in this source snapshot; build packages locally or run the attested release workflow. See docs/installation.md.

Version 0.2 removes the pre-release 0.1 runtime aliases. Recreate the environment before installing 0.2; the exact historical mapping remains in the migration ledger and third-party notice.

The CLI prints JSON. The --output value is a runs root; all provider executors write protocol 1.0.0 runs to <output>/<run-id>/ and return that actual run directory. Content runs remain offline and keep optional renderer failures explicit. geo-diagnose fetches at most five explicit public sources without crawl expansion. site-diagnose performs bounded same-host discovery with a ten-page hard limit, records render and source gaps, and writes a standalone report.html. Neither diagnostic path represents live AI-platform recall, ranking, citation share, traffic, or business outcomes.

geo-seo-hub site-diagnose \
  --url https://example.com \
  --output runs \
  --locale zh-CN \
  --max-pages 10 \
  --render auto

See the reproducible GEOHub demo report, desktop capture, mobile capture, discovery-module capture, and remediation-module capture. The complete fixture renders 23 chart views across ten diagnostic modules; live reports keep evidence gaps explicit when a chart is ineligible.

Release evidence is generated with scripts/generate_sbom.py, scripts/generate_provenance.py, scripts/verify_provenance.py, and scripts/render_production_readiness.py. Local provenance is explicitly unsigned. The current Production Readiness decision stays blocked while human review, live platform benchmarks, governed adoption, external strategy effect, production knowledge evaluation, legal review, and executed CI attestation remain missing evidence.

Data retention is preview-only by default. geo-seo-hub data-retention --runs-root <root> --apply-policy lists expired runs. Add --confirm to move them into a recoverable .geohub-trash batch. Recovery is explicit, and permanent purge requires a second confirmation after a seven-day grace period. See docs/data-governance.md.

Visual reports

• GEOHub 0.6.0 intent and orchestration upgrade records the Capability Card, hybrid routing, TaskPlan, recoverable workflow, security review, acceptance evidence, and remaining promotion gates.
• Migration to 0.7.0 records Site Diagnose routing, compatibility, packaging, browser rendering, and rollback boundaries.
• GEOHub 0.5.0 upgrade review provides the standalone Chinese HTML report with 17-module before-and-after scores, repair closure, deterministic gates, and remaining Production evidence.

License and governance

The open-source repository is licensed under AGPL-3.0-only. Commercial licensing is currently inquiry_only; see COMMERCIAL-LICENSING.md. The contributor agreement remains under legal review, so external code merges are paused.

make verify and python3 scripts/verify_all.py run the complete repository, evidence, test, evaluation, package, and isolated-install gates. make repo-verify runs the fast structural check. The gates use synthetic fixtures and require no external service or secret.

Copyright © 2026 姚金刚 / Yao.