Communitygithub.com

geo-audit

仅凭一个网址,从外部排查网站在多个国家/语言市场的 AI 搜索可见度,输出客户可直接执行的优化报告。

geo-audit 是什么?

GEO 网站审计技能专为 AI SEO(生成式引擎优化)场景设计,支持在 Claude Code、Codex、Cursor 等工具中运行。它仅通过外部扫描(无需源代码)评估网站对 ChatGPT、Perplexity、谷歌 AI 概览、Gemini、Claude、Copilot、豆包、DeepSeek、Kimi、元宝、Naver AI Briefing、Le Chat 等 AI 系统的可发现性。 技能核心流程包括:检测 robots.txt 对 AI 爬虫的放行、UA 拦截情况、渲染后内容比例、结构化数据、hreflang 声明及站外提及。审计依据证据强度(E1–E16)给出建议,并强制引用证据库。支持中国、美国、日本、韩国、德国、法国、西班牙 7 个建档市场,最多同时审计 3 个市场。 技能内置时间预算(45 分钟)和限流保护,自动降级以避免过度请求。输出包含 `audit.json` 原始数据和格式化报告(中文或指定语言),支持复查模式(基于旧目录增量更新)。 红线包括:不编造数据、不承诺排名提升、不推荐隐藏指令、不伪造翻译。每条建议必须附带证据强度标记,未检测项明确标注“未能检测”。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ClydeKuo/geo-skill/tree/HEAD/geo-audit

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

GEO 网站审计

概述

只凭一个网址,从外部排查网站在一个或多个国家 / 语言市场的 AI 搜索可见度,输出客户可以照着改的报告。

核心原则:按证据强度分配精力。最大的杠杆依次是能被抓取 → 能被检索 → 能被吸收 → 站外有人提及,而不是改写文案的套路。每条建议都必须引用 references/evidence.md 的证据编号和强度。

本 skill 遵循开放的 Agent Skills 格式,可在 Claude Code、Codex、Cursor 等工具中使用,用 bash <skill>/install.sh 安装到各工具的 skill 目录。下文所有路径都相对于本 SKILL.md 所在的目录(记为 <skill>)。

何时不用

  • 传统 SEO 全量审计(外链、关键词排名):只在与 GEO 相关时提及。
  • 调用 AI 接口实测可见度:不做,报告中只给手动方法。
  • 直接修改客户网站:只出报告,最多附 1–2 段示范改写。

需要的环境能力

能力用途没有时怎么办
shell + Python 3运行 <skill>/scripts/ 下的检测脚本(只用标准库)无法审计,告知用户
网络访问脚本抓取客户网站第 1 步的试跑会发现,停止并提示用户开启联网
网页搜索工具(Claude Code 中为 WebSearch)站外提及站外一节写"未能检测(当前环境无网页搜索)",不得省略该节
网页抓取工具(Claude Code 中为 WebFetch)读站外页面用 curl 代替
文件写入工具写报告用 shell heredoc
Chrome / Chromium(可选)渲染对比脚本自动标"未检测"

文件

文件用途
scripts/crawl_check.pyrobots.txt 对 AI 爬虫的放行(RFC 9309)、UA 拦截对照、sitemap、canonical、noindex、HTTPS、llms.txt、ICP、hreflang(HTML / HTTP Link 头 / sitemap 三来源及双向检查)
scripts/render_diff.py不执行 JS 时与渲染后的正文比例
scripts/page_audit.py标题层级、证据单元、结构化数据、作者与更新时间、canonical、hreflang;--save-html 保存原始 HTML
references/checklist.md通用检查清单与 P0/P1/P2 规则
references/markets/<代码>.md市场档案:cn us jp kr de fr es;未建档市场用 _generic.md
references/evidence.md证据库 E1–E16
references/ai-crawlers.md爬虫用途、无公开 UA 的引擎、伪装 UA 的局限
references/report-template.md报告结构与写作规则(必须使用)

所有脚本的通用参数:python3 <skill>/scripts/<脚本>.py <url> [更多 url…] [--proxy URL] [--timeout 秒] [--lang 语言标签] [--out 文件.json],结果以 JSON 输出到标准输出,任何情况下退出码都是 0。crawl_check.py 只接受一个 url,另有 --markets cn,us,jp。

审计流程

先建立输出目录 geo-report-<主机名>-<YYYYMMDD>/(放在当前工作目录下;<主机名> 取首页最终地址的主机名原样,如 www.example.com),所有原始数据都存到这里。报告文件 geo-report-<主机名>-<YYYYMMDD>.md 与它放在同一级。

  1. 收集上下文

    • 网址必填。品牌、主营业务缺失时询问一次,用户不答就从首页推断,并写入报告的"审计范围与假设"。
    • 报告语言 = 用户发起审计时所用的语言;用户另行指定时以指定为准。
    • 目标市场(市场代码列表):用户点名的优先。没说时,先跑第 2 步,再从 crawl.json 的 hreflang 和语言切换器推断,请用户确认一次。一次审计默认最多 3 个市场;无人回答时取"网站默认语言对应的市场 + hreflang 中已建档的市场里最多 2 个(按 cn、us、jp、kr、de、fr、es 的顺序)",其余列为"本次未审计的市场"。用户明确要求更多时照做,但页数和时间预算不变。
    • 市场按国家或地区划分。zh-TW / zh-HK、en-GB 等非美国英语、de-AT / de-CH、fr-BE / fr-CA 等都走 _generic,参考关系见 markets/_generic.md 第 1 节。
    • 确认审计机的网络出口国家(例如 curl -s https://ipinfo.io/country)。
  2. 可抓取检查(同时是联网试跑)

    python3 <skill>/scripts/crawl_check.py <url> --markets <代码列表> --lang <首个目标市场的语言标签> --out <输出目录>/crawl.json
    
    • 如果 homepage 和 robots 都是网络错误,说明当前环境不能联网:停止,告诉用户需要开启联网(Codex 的开启方式见 README),不要出空报告。
    • 读 ai_crawlers(relevant 为 true 的重点看)、ua_blocking、homepage、robots.value.source、meta_robots、x_robots_tag、canonical、https、sitemap、icp、hreflang、other_domains。判定规则见 references/checklist.md,本地爬虫见各市场档案第 4 节。
    • sitemap.value.truncated 为 true 时,count 只是已读取的数量,不是全站总数。
    • 其他主机上的语言版本:hreflang.declared 中位于其他域名 / 子域名、且属于已选目标市场的版本,纳入本次审计,对其首页再跑一次 crawl_check.py,输出为 crawl-<主机名>.json。没有在 hreflang 中声明的其他域名(other_domains)只在报告中提示,建议另行审计。
  3. 选重点页:每个目标市场至少 2 页(该市场的语言版本),总数不超过 20。优先:首页、核心产品 / 服务页、对比页、定价页、关于页、内容页。来源优先用 sitemap 和导航。

  4. 渲染对比:每次传 1–5 个 URL,超时 30 秒,用对应市场的语言:

    python3 <skill>/scripts/render_diff.py <url1> <url2> --timeout 30 --lang ja-JP --out <输出目录>/render-1.json
    
  5. 单页审计并阅读正文:

    python3 <skill>/scripts/page_audit.py <url1> <url2> … --lang ja-JP --save-html <输出目录>/html --out <输出目录>/pages-jp.json
    
    • 脚本只负责计数,并排除 <nav> 和页面级 <header>、<footer> 中的链接与标题。
    • 阅读正文时读 --save-html 保存的文件,不要另写抓取脚本,也不要把中间文件放到输出目录以外。
    • 要判断的内容:有没有定义句、对比、步骤、可核实的数据,是否一段只讲一个主张;隐藏正文(折叠的 FAQ 只在 JS 数据里、数字动画在 HTML 中显示为 0);当地语言版本是否为人工本地化、是否有机翻痕迹;市场档案第 7 节的本地化要点。
  6. 可检索判断:每个目标市场用当地语言推演 10–20 个问题,句式参考市场档案第 6 节,覆盖认知 / 对比 / 决策 / 售后。逐条判断该市场语言版本中是否有页面直接回答,填入报告的"问题覆盖表"(当地语言原文 + 报告语言译文)。

  7. 站外提及:用网页搜索工具,按市场档案第 5 节的平台逐一查找,记录有 / 无 / 未能检测与代表链接。需要登录的平台不查。

  8. 保存审计选择:写入 <输出目录>/audit.json:

    {"target": "", "markets": ["jp", "us"], "report_language": "ja", "brand": "", "business": "",
     "pages": {"jp": ["…"], "us": ["…"]}, "questions": {"jp": ["…"], "us": ["…"]},
     "offsite_queries": {"jp": ["…"], "us": ["…"]}, "extra_hosts": ["…"],
     "proxy_country": {"jp": "JP"}, "date": "YYYY-MM-DD"}
    

    proxy_country 只记录用过哪个国家的出口(没用过写 {}),不记录代理地址。

  9. 写报告:按 references/report-template.md 的结构,用报告语言书写。章节编号固定,不适用的写"不适用"。

复查模式

用户提供上一次的 geo-report-<主机名>-<日期>/ 目录时:读取其中的 audit.json,沿用同样的市场、重点页、推演问题和站外查询词,重新执行第 2–7 步,填写报告的"整改前后对比"章节。

旧版 audit.json 使用 "market": "cn" | "global" | "both",按以下规则换算:"cn" → cn;"global" → us;"both" → cn,us。旧版的 questions 键 global 对应 us。

限流与时间预算

  • 脚本已内置退避:遇到 429 或带 Retry-After 的 503 会等待后重试一次,并自动放慢后续请求。结果中出现 rate_limited: true,或多个页面连续返回 429 时:
    • 把剩余重点页减到每个市场 2 页;
    • 在报告"审计范围与假设"中写明"站点限流,抽查页数已减少"。
  • 被限流时单个脚本可能运行数分钟(等待 Retry-After)。运行脚本时把 shell 超时设为 10 分钟,或放到后台运行,不要因超时中断而丢失 JSON 输出。
  • 整次审计建议在 45 分钟内完成。超过时停止新增抓取,用已有数据写报告,并注明未完成的检查。
  • 禁止为规避限流轮换代理或出口 IP,也不要改 UA、加速重试。
  • 只有两种情况可以用 --proxy 指定某个国家的出口:测试该目标国家的可达性;站点按访问地区返回不同内容。用了哪个国家的出口要写进报告,只写国家,不写代理地址(代理地址属于审计方的内部信息,报告和 audit.json 都要交给客户)。

判读要点

脚本结果含义报告怎么写
ai_crawlers 中检索类或用户触发类为 failrobots.txt 明确拦截P0
ai_crawlers 中为 unknownrobots.txt 读不到写"未能检测"及原因
ai_crawlers 中训练类为 warn拦截了训练爬虫只说明利弊
ua_blocking 为 suspect浏览器 UA 正常,伪装的 AI UA 被拦P1,"疑似",请客户核对 CDN/WAF 或服务器日志
ua_blocking 为 warn / unknown都被拦 / 被限流或请求失败说明审计受限
homepage 为 unknown审计机被 WAF 挑战不是"网站不可用",需从其他网络核实
render_diff 的 ratio < 0.5AI 爬虫基本看不到正文P0,列出 js_only_headings
hreflang.alternates 中 fail / warn语言版本打不开 / 不双向P1 / P2
任意项为 unknown没能检测写"未能检测"及原因,不评价
llms_txt只记录有无放进"不建议投入"
raw_words / rendered_words中日韩文字每字计 1,其他语言按单词计不同语言的字数不能直接比较

红线

  • 每条问题都要有证据,每条建议都要标证据编号和强度。目标市场不是 us 时加"(推断)",除非市场档案第 8 节另有说明。未建档市场注明"该市场未建档,证据较弱"。
  • 没抓到的内容写"未能检测",不能凭印象评价。
  • 不建议编造数据、伪造评价、刷评、隐藏给 AI 的指令、贬低竞品,也不建议用机器翻译批量生成多语言版本(E13)。
  • 不把 llms.txt、FAQ 化、Schema、权威语气当作核心建议(E10、E9、E7)。
  • 不承诺流量或排名的提升(E15)。
  • 报告语言必须与用户提问的语言一致(用户另行指定时除外)。

常见错误

  • 把 suspect 当成确定的拦截:只有 robots.txt 的明确拦截才是 P0。
  • 用 Google 排名推断 AI 可见度:两者重叠很低(E13),各市场、各引擎要分开看。
  • 用报告语言推演问题:推演问题要用目标市场的当地语言和当地用户的问法。
  • 只看脚本计数就下结论:numbers 多不代表数据可核实,external_links 也可能混入用 <div> 写的页脚链接,要看正文。
  • 把 sitemap 的 count 当成全站页面数:truncated 为 true 时要注明。
  • 被限流后硬撑:按"限流与时间预算"一节减少页数,不要自写循环长时间等待。
  • 漏掉其他主机上的语言版本:hreflang 中声明在其他域名的目标市场版本要纳入审计。

相关技能