geo_site_skill（GEO 网站优化体检 Skill）

本 Skill 面向“目标网站代码库”的 Generative Engine Optimization（GEO）优化：既能做 代码库/构建产物 的可定位体检，也能做 浏览器可见内容快照 的体检，并尽可能补足 站外权威/实体验证（做不到的部分会在报告里输出待办）。

默认内置两套规则包：

• GEO-10（核心）：你提供的 10 条策略维度（倒金字塔/事实密度/语义足迹/机器可读性/Schema/语义 HTML/权威关联/实体一致性/robots/llms.txt）
• GEO-Plus（扩展）：国际化与消歧、canonical/hreflang、sitemap 健康度、可引用性、AI/搜索爬虫矩阵等（更贴近真实工程与多区域站点）

本项目的设计目标：模块化、可控 Token/上下文预算、可执行 FixSpec，方便 Claude Code / Codex 按“任务 → 证据包 → 决策 → 修复规格”流水线执行。

---

你会得到什么

运行一次审计后，仅输出一个完整报告：

1. output/geo_report_YYYYMMDD_HHMMSS.md：给人看的详细报告（每条规则：结论/证据/原因/修复建议/优先级/工作量）

以 Codex skill 运行时，默认输出目录为 C:\Users\<you>\.codex\output，可用 --out-dir 指定。

---

工作模式（三条通道）

1) Browser Snapshot Lane（前端可见内容快照）

从“浏览器可见内容”出发，采集：

• 首屏/主内容区可见纯文本（分块、带 DOM 路径）
• 标题大纲（H1-H6）
• H1/H2 后前 10% 内容块（用于 Fraggle/倒金字塔）
• 关键数字卡片与渲染差异摘要（raw 抓取 vs 可见文本）
• （可选）截图/HTML 证据

本仓库提供了 纯 requests + BeautifulSoup 的基础实现；如你的环境装了 Playwright，可启用 --render-js 做“渲染版快照”，更准确发现“JS 动态渲染导致抓取为 0”的问题。

2) Repo Audit Lane（代码库/构建产物体检）

对代码库与构建产物（build 输出 HTML）做可定位检测：

• JSON-LD Schema 清点与类型矩阵（Organization/WebSite/FAQPage/Article/...）
• 语义 HTML：标题层级、列表/表格语义、可抽取结构
• robots.txt / sitemap / headers（X-Robots-Tag、noindex 等）
• 国际化与重复：canonical/hreflang/x-default（GEO-Plus）

3) Offsite Lane（站外权威与实体验证）

尽力补足：

• 监管/牌照/权威来源是否存在、是否与站内说法一致
• 品牌实体的名称歧义与一致性（品牌名/法律实体/地址/服务范围）
• 第三方权威站点提及线索（无法做完整外链图谱的，会输出待办）

---

安装与环境

依赖（最低）

• Python 3.10+
• requests
• beautifulsoup4
• lxml
• pyyaml

可选增强：

• playwright（启用 --render-js 渲染快照）
• python-slugify（更友好的 run_id 命名）

安装：

pip install -r requirements.txt

---

快速开始（针对 WorldFirst UK）

你可以直接用内置样例：

python -m src.cli audit \
  --base-url https://www.worldfirst.com/uk/ \
  --repo-path /path/to/your/repo \
  --targets config/targets.worldfirst_uk.yaml \
  --ruleset geo10,geoplus \
  --out-dir output \
  --sample-pages 6

如果你暂时没有 repo，只做“前端快照体检”，也能跑：

python -m src.cli audit \
  --base-url https://www.worldfirst.com/uk/ \
  --out-dir output \
  --ruleset geo10,geoplus \
  --snapshot-only

启用 JS 渲染快照（需要 playwright）：

python -m src.cli audit \
  --base-url https://www.worldfirst.com/uk/ \
  --out-dir output \
  --render-js

---

Codex Skill 使用

安装路径（Windows）： C:\Users\<you>\.codex\skills\geo_site\

调用示例：

• /geo_site --base-url https://builderstream.info/ --repo-path D:\Project_GEO\00_geo_site_skill\target_sites\bs-landingpage2
• 指定输出目录：/geo_site --base-url https://builderstream.info/ --repo-path D:\Project_GEO\00_geo_site_skill\target_sites\bs-landingpage2 --out-dir D:\Project_GEO\00_geo_site_skill\output

---

配置说明

1) targets（目标采样策略）

文件：config/targets.worldfirst_uk.yaml

常用字段：

• base_url: 站点入口
• seed_paths: 必测路径（首页、产品页、帮助中心、隐私政策等）
• max_pages: 最大采样页数（控制成本）
• include_patterns / exclude_patterns: URL 过滤
• lanes: 启用哪些通道（snapshot/repo/offsite）

2) ruleset（规则包与阈值）

文件：

• config/rules.geo10.yaml
• config/rules.geoplus.yaml

每条规则都定义：

• id / name / goal
• inputs_needed（依赖哪些采集产物）
• thresholds（判定阈值）
• severity（P0/P1/P2）
• token_budget（证据包最大字符数，建议值）

---

输出结构（output/）

• geo_report_YYYYMMDD_HHMMSS.md：人类可读报告（唯一输出）

---

稳定性与可迁移性

• 规则去重：同一 id 出现在多个 ruleset 时只执行一次，避免重复报告。
• 规则集降级：某个 ruleset 加载失败会记入 backlog，但不会中断整次审计。
• 抓取容错：单页抓取失败会记录 fetch_error，其余页面与规则继续执行。
• 输出稳定：仅输出单一 Markdown 报告，按时间戳归档，便于 CI/多次运行对比。

---

如何让 Claude Code / Codex 使用本 Skill

建议工作流：

1. Agent 先运行 audit 生成报告（只读）
2. Agent 读取最新的 output/geo_report_YYYYMMDD_HHMMSS.md，按 severity 从 P0 → P2 执行
3. 对可自动改的项：
   • 插入 Fraggle 块
   • 补 FAQ 段 + FAQPage JSON-LD
   • 修正标题层级与列表语义
   • 生成/更新 llms.txt（代码层面手工补齐）
4. 对需要人工确认的项：
   • 法律实体、地址、监管牌照信息（NAP/合规）
   • 站外 PR / co-citation（输出待办）

本仓库的 prompts/ 提供了“写作/生成”提示词模板，Agent 可以用它来稳定地产出页面文案或结构化块。

---

扩展与二次开发

新增一条规则（Check）

1. 在 src/checks/ 新建 cXX_*.py
2. 在 config/rules.geoplus.yaml 中注册该规则
3. 确保该规则只读取自己需要的 Evidence Pack，避免拉爆上下文

接入 MCP 工具（Playwright/Browser/Firecrawl）

本仓库默认实现是“本地脚本可跑”。如果你在 Claude Code/Codex 环境里能用 MCP：

• 把 MCP 的抓取结果（可见文本、DOM 结构、截图、网络请求等）写入 artifacts/
• 让 src/orchestrator.py 直接复用这些 artifacts，跳过本地抓取步骤

---

免责声明与边界

• 站外权威/实体一致性：本 Skill 会尽力通过公开信息做对照，但无法替代法律/合规审查。
• 自动 patch：当前版本仅输出修复建议；如需自动应用，可在未来版本接入 --apply-patches。

---

目录结构

geo_site_skill/
  SKILL.md
  README.md
  AGENTS.md
  requirements.txt
  config/
    targets.worldfirst_uk.yaml
    rules.geo10.yaml
    rules.geoplus.yaml
  prompts/
    fix_writer.md
    faq_generator.md
    llms_txt_generator.md
  src/
    cli.py
    orchestrator.py
    crawl.py
    extract.py
    report.py
    patch.py
    model.py
    checks/
      c01_fraggle.py
      c02_fact_density.py
      c03_semantic_footprint.py
      c04_machine_readability.py
      c05_schema_jsonld.py
      c06_semantic_html.py
      c07_entity_authority.py
      c08_entity_consistency.py
      c09_robots_policy.py
      c10_llms_txt.py
      p01_i18n_canonical_hreflang.py
      p02_sitemap_health.py
      p03_attribution_readiness.py
  examples/
    worldfirst_uk.yaml
  docs/
    GEO_RULES.md

---

常见问题（FAQ）

Q: 我不想抓太多页面，怎么控制成本？
A: 调低 --sample-pages，并在 targets 里设定 seed_paths，再加 include/exclude_patterns。本 Skill 的每条 Check 都有 token_budget，默认会做截断。

Q: 没有 Playwright 会影响准确性吗？
A: 会影响“渲染差异/动态占位”类问题的发现。建议在 CI 或审计机器上装 playwright，用 --render-js。

Q: 如何把报告变成自动修复？
A: 按 output/geo_report_YYYYMMDD_HHMMSS.md 中每条规则的 FixSpec 与 patch_plan 逐条执行，形成可合并的改动。

---

如果你要把它升级成“可直接发 PR”的版本：下一步就是把 src/patch.py 的 patch 应用从“生成草案”扩展为“对 repo 生成 diff + 可选自动应用”，并增加 --apply-patches 和 --git-commit 选项。