1. 项目概述：一个面向AI编程工具的终极SEO与GEO优化智能体
如果你是一名开发者、营销人员或创始人，正在使用Claude Code、Cursor、GitHub Copilot这类AI编程助手来构建或维护网站，那么你很可能面临一个共同的痛点：如何高效地、系统化地处理搜索引擎优化（SEO）和生成式引擎优化（GEO）这项复杂且持续的工作？传统的SEO工具要么操作繁琐，要么输出一堆难以落地的“建议”，而AI助手虽然强大，但如果没有明确的指令和专业知识框架，它们给出的答案也往往是零散且不完整的。这正是mykpono/ultimate-seo-geo这个项目要解决的核心问题。
简单来说，Ultimate SEO + GEO是一个“AI技能包”或“智能体”。它不是另一个独立的软件，而是一套精心设计的指令集、脚本和知识库，专门用来“武装”你正在使用的AI编程工具。它的核心价值在于，将零散的SEO/GEO知识体系化、流程化、自动化，让AI助手从一个普通的代码伙伴，转变为一个经验丰富的SEO专家。你只需要给它一个网站的URL，它就能执行一套完整的审计流程：从抓取分析、生成带评分的健康报告，到制定优先级明确的行動路线图，最后直接产出可部署的修复代码（如JSON-LD结构化数据、重定向规则、优化的元标签等）。整个过程，AI不再是泛泛而谈，而是基于一套严谨的框架进行诊断和“开处方”。
这个项目最大的特点是LLM-Agnostic（大语言模型无关）。它不依赖于某个特定的AI模型，而是基于一个名为AGENTS.md的跨工具标准文件。这意味着，只要你的AI工具（如OpenAI Codex、Google Gemini CLI、Cursor、Windsurf等）支持读取这个标准文件，你就能立即获得这套强大的SEO能力。它就像给你的AI工具安装了一个“专业插件”，瞬间扩展了其在搜索优化领域的专业边界。
2. 核心能力与模块深度解析
这个智能体并非简单的脚本集合，而是一个覆盖了现代搜索优化（包括传统SEO和新兴的AI搜索GEO）全链路的综合解决方案。理解其模块构成，是有效使用它的前提。
2.1 传统SEO的21个核心模块
项目将传统SEO拆解为21个模块，这几乎涵盖了从技术底层到内容策略的所有关键领域。我们挑几个核心模块深入看看：
技术SEO模块：这不仅仅是跑个PageSpeed Insights那么简单。它会系统性地检查网站的“可抓取性”和“可索引性”。例如，它会分析robots.txt文件是否错误地屏蔽了重要资源，检查JavaScript渲染的页面内容是否能被搜索引擎正确抓取（这是单页应用SPA的常见痛点），验证安全头（如HSTS、CSP）是否配置得当以提升安全性评分，并严格评估移动端优先索引的合规性。对于Core Web Vitals（核心网页指标），它不仅能获取LCP、INP、CLS等数据，还会根据行业基准给出具体的优化建议，比如“图片X未使用下一代格式，预计可提升LCP评分Y分”。
内容与E-E-A-T模块：E-E-A-T（经验、专业性、权威性、可信度）是谷歌评估YMYL（你的金钱或人生）内容的核心框架。这个模块会执行一套80项的CORE-EEAT内容基准检查。它不只是看字数，而是分析内容是否展示了第一手经验、作者资历是否明确、引用来源是否权威、以及是否存在“薄内容”（Thin Content）的风险。例如，对于一个医疗建议页面，它会检查是否引用了权威医学期刊，作者是否具备相关资质声明，从而给出一个量化的E-E-A-T分数和具体的改进清单。
结构化数据（Schema Markup）模块：这是许多开发者容易忽略或做错的地方。该模块不仅能验证页面现有的JSON-LD数据是否语法正确、符合Schema.org规范，还能智能生成缺失的、与页面内容最匹配的结构化数据代码。更关键的是，它紧跟谷歌的更新，能识别已弃用的类型（如过去的SpecialAnnouncement），确保你使用的始终是当前有效的Schema类型，避免因使用过时标记而浪费抓取预算。
2.2 生成式引擎优化（GEO）的独特价值
随着ChatGPT Search、Perplexity、Google AI Overviews等AI搜索的兴起，传统的SEO策略需要进化。GEO模块正是为此而生。
平台覆盖与可引用性评分：该模块深入研究各AI搜索平台的抓取和引用偏好。例如，它知道Perplexity偏好引用来自权威域名（如Wikipedia、Reddit高赞帖、知名媒体）的内容，而Google AI Overviews则更注重内容的时效性和答案的直接性。它会进行“可引用性评分”，分析你的内容是否在关键段落（通常是前60-134个单词）内提供了清晰、完整的答案块，以提高被AI摘要引用的概率。
AI爬虫管理：传统的robots.txt可能不包含对AI爬虫的指令。该模块会检查并为你生成针对GPTBot（OpenAI）、OAI-SearchBot、PerplexityBot、ClaudeBot等特定爬虫的允许或屏蔽规则。同时，它还支持新兴的llms.txt标准（一个专门面向大语言模型爬虫的声明文件），帮助你在AI时代更好地管理内容的可访问性。
品牌提及与实体策略：为了让你的品牌或产品在AI生成的答案中被提及，你需要强化其在知识图谱中的存在。该模块会检查你的网站是否与Wikidata、Wikipedia等实体库正确关联，sameAs链接是否设置完整，并指导你如何通过品牌内容策略，增加在YouTube、Reddit、LinkedIn等平台的相关性信号，从而提升被AI引用的可能性。
3. 跨平台安装与配置实战
项目的强大兼容性源于其清晰的架构设计。其核心是一个分层的知识系统，确保在不同能力的AI工具上都能获得最佳体验。
3.1 理解架构：渐进式知识披露
项目的文件结构设计精妙，采用了“渐进式披露”的策略：
- 第一层（
AGENTS.md）：这是一个小于32KB的通用入口文件，包含了所有核心指令的路由、浓缩版的操作流程、脚本索引和质量控制门禁。任何支持AGENTS.md标准的工具在打开项目文件夹时都会自动加载它，获得基础能力。 - 第二层（
SKILL.md+references/）：SKILL.md是一个轻量的路由外壳（约230行），专为像Claude Code这样支持完整Skill功能的平台设计。当AI需要执行某个具体任务（如“检查hreflang”）时，SKILL.md会引导它去references/procedures/目录下加载对应的详细步骤文件（如§12_hreflang_audit.md）。同时，references/目录下还有十几份深度专题文档（如核心EEAT框架、实体优化清单），供AI在需要时查阅。 - 第三层（
scripts/）：包含31个可独立运行的Python诊断脚本。这是真正的“重型武器”，用于执行实际的抓取、分析和验证工作。AI在需要时会调用这些脚本，并将结果整合到回复中。
这种设计保证了在功能受限的平台（如某些仅支持上传文档的ChatGPT自定义GPT）上，核心逻辑仍能运行；而在功能全面的平台（如Claude Code）上，则可以发挥全部威力。
3.2 主流平台安装指南
对于绝大多数AGENTS.md兼容工具（Cursor, Windsurf, Cline, Aider等）： 安装极其简单，本质上就是克隆代码库。在你的项目目录或AI工具的工作区中，直接运行：
git clone https://github.com/mykpono/ultimate-seo-geo.git cd ultimate-seo-geo pip install -r requirements.txt完成后，打开这个文件夹，你的AI工具就已经加载了AGENTS.md，可以开始接受SEO指令了。
对于Claude Code（插件市场安装）： 这是体验最完整的方式。请注意，以下命令需要在Claude Code的聊天界面中输入，而不是在系统终端：
/plugin marketplace add mykpono/ultimate-seo-geo /plugin install ultimate-seo-geo@ultimate-seo-geo安装后，该Skill会出现在你的技能列表中。一个重要提示：Claude Code的插件市场有本地缓存，不会自动拉取GitHub上的更新。如果你发现技能没有更新到最新版本，需要手动更新缓存：
# 在系统终端中执行 cd ~/.claude/plugins/marketplaces/ultimate-seo-geo && git pull然后，在Claude Code中重启会话或输入/reload-plugins命令。
对于ChatGPT自定义GPT： 由于ChatGPT自定义GPT无法直接读取仓库文件，你需要手动准备“知识文件”。项目提供了chatgpt/目录，其中包含一个浓缩版的指令文件和一个脚本，用于将必要的references/文档复制过来。你需要按照chatgpt/README.md的说明，将这些文件上传到你的自定义GPT的“知识库”中。虽然功能上会有一些限制（比如无法直接运行本地脚本），但核心的审计和规划能力仍然可用。
注意：在安装依赖（
pip install -r requirements.txt）时，如果你使用的是通过Homebrew等包管理器安装的Python 3.11+，可能会遇到“PEP 668”错误，提示外部环境受保护。这时，最佳实践是先创建一个虚拟环境：python3 -m venv .venv source .venv/bin/activate # Linux/macOS # 或 .venv\Scripts\activate # Windows .venv/bin/pip install -r requirements.txt后续运行项目脚本时，也需要确保在激活的虚拟环境中进行（
/.venv/bin/python scripts/generate_report.py ...）。
4. 工作流程与实战应用案例
理解了模块和安装后，我们来看它如何在实际场景中工作。其核心流程可以概括为“审计（Audit）-规划（Plan）-执行（Execute）”三步闭环。
4.1 标准工作流解析
审计模式：你向AI发出指令，如“审计 example.com 的SEO健康状况”。AI会调用
scripts/generate_report.py等脚本，对目标网站进行扫描。扫描范围默认基于种子URL进行适度抓取（避免对目标站点造成压力）。如果需要深度分析，你可以添加--crawl-deep参数。审计完成后，AI会生成一份包含“SEO健康分数（0-100分）”的报告，并列出所有发现的问题，每个问题都有严重性评分和优先级标记。规划模式：基于审计发现的问题，AI会自动进入规划模式。它会将技术问题转化为一个可执行的路线图，通常以表格形式呈现，包含“具体任务”、“预估工作量（低/中/高）”、“预期影响（低/中/高）”、“建议负责人（前端/后端/内容）”等列。这相当于一个项目经理为你制定的Sprint计划。
执行模式：这是最具价值的一步。AI不会只说“你需要添加产品Schema”，而是直接生成 ready-to-use 的代码。例如，对于缺失产品Schema的页面，它会输出一个完整的、包含
Product、Offer、AggregateRating等类型的JSON-LD代码块，你只需要复制粘贴到页面的<head>部分。对于需要设置301重定向的URL迁移，它会直接生成Apache.htaccess或Nginx配置代码片段。
4.2 典型场景实战指令
以下是一些可以直接“抄作业”的指令模板，展示了如何与搭载了此技能的AI进行高效对话：
场景一：网站流量莫名下降
- 你的指令：“我们的网站 mysite.com 过去三个月自然搜索流量下降了15%。请执行一次完整的SEO审计，重点分析技术健康度和核心网页指标，并给出优先级最高的三个修复项。”
- AI的行动：它会运行全面的技术审计（包括Core Web Vitals、爬取错误、索引状态），并交叉分析流量下降时间点与网站最近的改动（如部署、代码更新），最终给出像“INP交互延迟在产品列表页超标，建议优化JavaScript执行时序”这样具体的、可行动的洞见。
场景二：为本地服务业务优化
- 你的指令：“我是一家位于西雅图的屋顶维修公司。我们在‘西雅图屋顶维修’这个关键词上排名不佳，本地地图包（Local Pack）也几乎不显示。请诊断我们的本地SEO并生成优化方案。”
- AI的行动：它会检查网站上的NAP（名称、地址、电话）信息是否一致且带有正确的
LocalBusinessSchema，分析Google Business Profile（如果提供了资料）的完整性，检查本地引文（Citation）建设情况，并生成一份包含“修复不一致的电话号码”、“添加服务区域Schema”、“构建本地行业目录引用”的详细任务清单。
场景三：电商网站迁移
- 你的指令：“我们计划在下个季度将拥有5000个SKU的电商网站从WooCommerce迁移到Shopify。请制定一个分阶段的SEO迁移检查清单，并为首批100个核心产品页生成重定向映射和对应的Schema标记。”
- AI的行动：AI会调用“网站迁移”模块，输出一个包含“迁移前（内容备份、基准数据收集）”、“迁移中（URL结构映射、301重定向实施、测试）”、“迁移后（监控、索引提交、流量恢复）”的完整清单。同时，它会根据你提供的旧URL列表，批量生成对应的新URL重定向规则，并为新产品页面模板生成优化的商品Schema代码。
场景四：针对AI搜索进行内容优化
- 你的指令：“我们发布了一篇关于‘2024年深度学习框架对比’的深度文章。如何优化它，使其更可能被ChatGPT Search和Perplexity引用作为权威答案？”
- AI的行动：它会进入GEO优化模式，分析文章结构，指出哪些段落适合改造成134-167个单词的“答案块”，建议在文章开头60个单词内清晰抛出核心结论，并检查文章是否引用了足够多的高权威来源（如官方文档、知名研究论文），以增强其“可引用性评分”。
5. 内置脚本库：31把瑞士军刀详解
项目的scripts/目录是其能力的引擎。这些脚本不仅可以被AI调用，你也可以在命令行中独立使用它们进行快速检查。了解关键脚本的功能，能让你更灵活地运用这个工具。
| 脚本名称 | 核心功能与使用技巧 |
|---|---|
generate_report.py | 旗舰脚本。输入一个URL，它会串联多个检查，生成一个包含摘要、分数和详细发现的HTML仪表盘。使用--output report.html指定输出文件，使用--crawl-deep 3进行深度为3的有限爬取（谨慎使用，避免对目标站造成负载）。 |
validate_schema.py | 验证页面中JSON-LD数据的语法和结构。它不依赖外部API，使用Python标准库，速度快。可以本地验证HTML文件（--file page.html），也可以在线验证（--url https://...）。对于检查微数据或RDFa，需要结合其他工具。 |
robots_checker.py | 检查robots.txt对普通爬虫和AI爬虫（GPTBot, OAI-SearchBot等）的规则。它能模拟不同爬虫的访问，告诉你哪些路径被允许或禁止。实操心得：在部署新网站或修改robots.txt后，务必用此脚本测试，确保关键资源（如CSS/JS）没有被意外屏蔽。 |
hreflang_checker.py | hreflang标签是国际站点的常见错误点。此脚本会检查8条核心规则：标签是否存在、语言代码格式是否正确、是否使用了自返回标签（即当前页面的语言版本是否指向自己）、以及所有语言版本是否相互链接形成闭环。它能快速定位出缺失或错误的链接。 |
internal_links.py | 分析站内链接图。它能找出“孤儿页面”（没有任何内部链接指向的页面），计算每个页面的“链接权重”（Link Equity）流入流出情况，并分析锚文本的优化程度。避坑提示：一个常见的SEO错误是拥有大量只有导航栏链接的页面，缺乏内容相关的上下文内链，此脚本能清晰揭示这一问题。 |
entity_checker.py | 检查你的网站在知识图谱中的“实体”信号。它会查找页面是否链接到相关的Wikipedia、Wikidata条目，或通过sameAs声明了其他权威身份（如官方社交媒体）。强化实体关联是提升E-E-A-T和GEO表现的有效手段。 |
finding_verifier.py | 这是一个“后处理”脚本。当AI运行了多个审计脚本后，可能会产生重复或相似的问题条目。此脚本可以对这些发现进行去重、合并和优先级重排，确保最终报告简洁清晰。在编写自定义审计流水线时非常有用。 |
重要提示：大部分脚本都需要网络请求。在针对生产环境网站进行大规模或频繁扫描时，请务必设置合理的延迟（脚本内部通常有控制），或考虑在非高峰时段进行，以避免被视为恶意攻击。
6. 常见问题排查与效能提升
即使工具设计得再完善，在实际使用中也可能遇到各种环境或理解上的问题。这里汇总了一些典型场景的解决方案。
6.1 安装与加载问题
问题：在Claude Code中安装了插件，但技能列表里没有出现“Ultimate SEO + GEO”。
- 原因：这通常是Claude Code插件缓存加载的已知问题（类似issue #35641）。
/reload-plugins命令有时无法正确刷新新安装的技能。 - 解决：最彻底的方法是完全重启你的Claude Code会话（关闭并重新打开Claude Code应用）。如果问题依旧，尝试手动清理并重新克隆市场缓存：
然后重启Claude Code。rm -rf ~/.claude/plugins/marketplaces/ultimate-seo-geo git clone https://github.com/mykpono/ultimate-seo-geo.git ~/.claude/plugins/marketplaces/ultimate-seo-geo
问题：运行脚本时提示“ModuleNotFoundError: No module named 'requests'”。
- 原因：Python依赖没有安装，或者你在全局Python环境安装但脚本运行在另一个环境。
- 解决：首先确认你已在项目根目录下运行了
pip install -r requirements.txt。如果已安装但仍报错，很可能是环境问题。强烈建议使用虚拟环境。激活虚拟环境后再次安装依赖，并确保在同一个激活的环境下运行脚本（python scripts/...）。
6.2 使用技巧与效能提升
如何控制审计的深度和广度？默认的generate_report.py脚本使用“种子URL+适度爬取”策略，主要分析给定页面及其直接链接。这对于快速健康检查是足够的。如果你需要进行全站深度审计：
- 使用
--crawl-deep参数，例如--crawl-deep 5将爬取深度设为5。 - 同时使用
--crawl-limit 1000来限制最大爬取页面数，避免失控。 - 务必谨慎：深度爬取会对目标网站服务器产生压力。最好在获得授权后，针对自己的网站进行，或者利用网站的
sitemap.xml来获取URL列表进行逐个分析。
AI给出的修复代码可以直接用吗？绝大多数情况下可以，但需要人工审查。AI生成的代码（如JSON-LD、重定向规则）是基于最佳实践模板和你的页面内容生成的，通常语法正确且符合规范。然而，它无法理解你业务的全部上下文。例如，它生成的商品价格Schema，需要你确认货币单位、价格有效性等字段是否完全准确。最佳实践是：将AI生成的代码视为高质量的初稿，由开发者或SEO专家进行最终的业务逻辑校验后部署。
这个工具能替代专业的SEO顾问或工具吗？不能，它是一个强大的“力量倍增器”而非替代品。它的价值在于将重复性、标准化的审计和代码生成工作自动化，让专业人士从繁琐的检查中解放出来，专注于更高层次的策略和创意。对于中小型项目或开发者个人，它可能提供80%的解决方案；对于大型复杂项目，它则是一个不可或缺的辅助工具，能确保团队在执行层面不遗漏基础细节。它不处理付费广告、社交媒体运营或广义的营销策略。
如何扩展或定制这个技能？项目的模块化设计允许进行定制。如果你有特定的检查需求（例如，检查是否使用了某个特定的CDN，或验证某种自定义的元标签），你可以：
- 在
references/procedures/目录下创建新的流程文档（例如§22_custom_check.md），按照现有格式编写步骤。 - 在
scripts/目录下编写对应的Python检查脚本。 - 在
AGENTS.md或SKILL.md的路由部分注册你的新模块。 这样，AI在后续的审计中就能调用你的自定义检查了。这种开放性使得该项目可以成为一个团队内部SEO知识和工作流的承载平台。
