# 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.

```bash
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:

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

Community packages:

```bash
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.

```bash
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](reports/examples/geo-site-diagnose-demo.html), [desktop capture](reports/examples/geo-site-diagnose-demo-desktop.png), [mobile capture](reports/examples/geo-site-diagnose-demo-mobile.png), [discovery-module capture](reports/examples/geo-site-diagnose-demo-discovery.png), and [remediation-module capture](reports/examples/geo-site-diagnose-demo-actions.png). 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](docs/intent-orchestration-upgrade-0.6.md) records the Capability Card, hybrid routing, TaskPlan, recoverable workflow, security review, acceptance evidence, and remaining promotion gates.
- [Migration to 0.7.0](docs/migration-0.7.md) records Site Diagnose routing, compatibility, packaging, browser rendering, and rollback boundaries.
- [GEOHub 0.5.0 upgrade review](docs/visual-reports/geohub-0.5.0-upgrade/README.md) 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.