AI编程助手SEO/GEO优化智能体：从诊断到代码的自动化解决方案

1. 项目概述：一个面向AI编程工具的通用SEO与GEO优化智能体

如果你是一名开发者、创业者或营销人员，正在使用Claude Code、Cursor、GitHub Copilot这类AI编程助手来构建或维护网站，那么你很可能遇到过这样的困境：你希望网站能被搜索引擎和像ChatGPT、Perplexity这样的AI搜索平台更好地发现和理解，但相关的优化工作（SEO/GEO）既琐碎又专业。手动检查标题标签、元描述、结构化数据、页面速度，还要考虑AI搜索的引用策略，每一项都足以让人头大。更麻烦的是，当你向AI助手提出“帮我优化一下网站的SEO”时，得到的回复往往是泛泛而谈的建议，而不是可以直接执行的、针对你网站具体问题的修复方案。

mykpono/ultimate-seo-geo这个项目就是为了解决这个痛点而生的。它本质上是一个“技能包”或“智能体”，专门设计给那些能读取AGENTS.md文件的AI编程工具使用。你可以把它理解为你AI助手的一个“SEO专家”外挂。给它一个网址，它不会给你一堆空洞的理论，而是会执行一套完整的诊断流程：抓取你的网站，运行超过21个模块的深度检查，给每个发现的问题打分，生成一个优先级明确的行動计划，并最终产出可以直接部署的修复代码——比如修正后的JSON-LD结构化数据、重写好的meta标签、正确的重定向规则，甚至是针对AI爬虫（如GPTBot）优化的robots.txt配置。

这个项目的核心优势在于其“LLM无关性”（LLM-Agnostic）。它不依赖于某个特定的大语言模型，而是基于一个名为AGENTS.md的跨工具标准。这意味着无论你用的是OpenAI的Codex、Google的Gemini CLI、Anthropic的Claude Code，还是Cursor、Windsurf、GitHub Copilot等任何兼容此标准的工具，这个SEO技能都能无缝接入并工作。它通过“渐进式披露”的架构设计，将一个庞大的SEO知识库和31个诊断脚本打包，确保在不同平台和上下文限制下都能高效运行。

1.1 核心价值：从“建议”到“可执行方案”的转变

传统SEO工具或咨询提供的是报告和建议，而ultimate-seo-geo提供的是“动作”。它内置了三种工作模式，覆盖了从诊断到修复的全流程：

1. 审计模式：这是起点。工具会全面扫描目标网站，从技术SEO（核心网页指标、可抓取性）、页面SEO（标题、H1），到内容质量、结构化数据和本地SEO信号，生成一个0-100分的“SEO健康度”评分，并列出所有发现的问题及其优先级。
2. 计划模式：基于审计结果，它将问题转化为一个分阶段实施的路线图。这个路线图不是一个简单的待办清单，而是一个包含预估工作量、预期影响和负责人的实施表格，帮助你清晰地规划资源。
3. 执行模式：这是最具价值的一环。在此模式下，工具会直接生成修复问题的具体代码。例如，它会为你缺失产品信息的页面生成完整的Product类型Schema标记；或者为你的本地服务业务创建包含LocalBusiness、PostalAddress等详细信息的JSON-LD代码块，你可以直接复制粘贴到网站模板中。

对于使用AI编程工具的团队来说，这意味着SEO优化不再是需要专门学习和反复沟通的独立任务，而是可以像调用一个函数库一样，被整合到日常的开发工作流中。无论是进行网站迁移前的检查，还是针对流量下滑进行诊断，或是为了在Google AI Overviews和ChatGPT Search中获得更好展示而优化内容，你都可以通过向你的AI助手发出一个简单的指令来启动这个强大的SEO协作者。

2. 核心功能模块深度解析

ultimate-seo-geo的功能覆盖了现代搜索可见性的两个核心维度：传统搜索引擎优化（SEO）和生成式引擎优化（GEO）。下面我们来拆解其每个模块的具体职责和背后的优化逻辑。

2.1 SEO功能模块：21个维度的全方位诊断

项目的SEO部分被系统地划分为21个模块，这远不止是关键词和反向链接分析，而是一个从技术基础设施到内容战略的完整体系。

技术SEO是地基。它检查网站是否可以被搜索引擎蜘蛛顺利抓取和索引。这包括：

• 核心网页指标：通过集成Google PageSpeed Insights API，获取并分析 Largest Contentful Paint (LCP)、Interaction to Next Paint (INP)、Cumulative Layout Shift (CLS) 的实际数据。它会指出是哪些资源（如图片、JavaScript、CSS）拖慢了速度，并给出具体的优化建议，如延迟加载非关键资源、压缩图片、移除阻塞渲染的脚本。
• 可抓取性与可索引性：检查robots.txt是否错误地屏蔽了重要页面，确认meta robots标签设置是否正确，分析网站是否对JavaScript渲染内容有良好的支持（对于SPA应用至关重要），并验证HTTPS和安全头（如HSTS, CSP）的配置是否完善。
• 移动端优先：确保网站在移动设备上的渲染和体验与桌面端一致，这是Google排名的重要因素。

页面SEO关注单个页面的优化元素。工具会自动化检查：

• 标题标签与元描述：长度是否在推荐范围内（标题50-60字符，描述150-160字符），是否包含核心关键词，是否唯一且具有吸引力。
• 标题标签：检查H1是否唯一且准确地描述了页面内容，H2-H6的层级结构是否合理。
• URL结构：是否简洁、包含关键词、避免使用动态参数。
• 规范链接：rel=“canonical”标签是否正确设置，以避免内容重复问题。

内容与E-E-A-T模块是区分普通工具和专业工具的关键。E-E-A-T（经验、专业性、权威性、可信度）是Google评估YMYL（你的金钱或你的生活）类内容的核心框架。此模块不仅进行可读性分析（如Flesch-Kincaid分数），更重要的是：

• 内容质量评分：基于一套包含80个项目的CORE-EEAT基准，评估内容是否展示了第一手经验、深度的专业知识。
• 作者与网站权威信号：检查页面是否清晰展示了作者资历、网站是否有明确的“关于我们”和“联系”页面，是否在其他权威平台（如行业媒体、学术站点）有被引用。
• 单薄内容检测：识别那些字数过少、信息量不足、对用户价值低的页面，建议进行内容扩充或合并。

结构化数据模块非常实用。它不仅能识别页面上现有的Schema.org标记（如Article,Product,LocalBusiness），还能根据页面内容智能生成缺失的、符合最新标准的JSON-LD代码块。它甚至能识别已被弃用的类型（如HowTo,SpecialAnnouncement），确保你的标记不会过时。

其他高级模块则体现了其战略深度：

• 国际SEO：自动审计hreflang标签，确保多语言/多地区网站的正确配置，包括语言代码验证和双向返回标签检查，避免区域间流量蚕食。
• 网站迁移：提供迁移前、中、后的完整检查清单，特别是重定向映射的验证，这是大型迁移中SEO风险最高的环节之一。
• 程序化SEO：针对通过模板大量生成页面的网站（如电商产品列表、房源列表），设立质量关卡，防止因模板问题产生大量低质页面。

2.2 GEO功能模块：优化内容以被AI搜索引用

GEO是面向未来的模块，目标是让内容被ChatGPT、Perplexity、Google AI Overviews等AI搜索平台更好地引用和展示。

• 平台覆盖与可引用性评分：AI搜索在生成答案时，倾向于引用特定格式和长度的内容块。此模块会分析你的内容，评估其是否包含适合被引用的“答案块”（通常为134-167个单词），并检查核心答案是否出现在内容的前60个单词内，以提高被摘录的几率。
• 品牌提及策略：分析你的品牌或核心实体在YouTube、Reddit、Wikipedia、LinkedIn等平台上的提及情况。它会引导你建立或完善Wikidata实体，因为AI搜索常将知识图谱作为可信信息来源。
• AI爬虫管理：生成针对不同AI爬虫（如OpenAI的GPTBot、Google的OAI-SearchBot、PerplexityBot、ClaudeBot）的robots.txt规则。你可以选择允许它们抓取以增加曝光，或屏蔽它们以保护内容。
• 新兴标准支持：提供llms.txt文件的模板生成。这是一个类似于robots.txt但专为AI语言模型设计的新兴标准，用于声明内容是否允许被用于模型训练。同时，它也关注RSL 1.0（机器可读的AI内容许可标准），帮助内容创作者明确授权条款。

实操心得：很多开发者会忽略GEO优化，认为那是内容创作者的事。但实际上，技术层面的配合至关重要。例如，通过robots.txt正确配置AI爬虫的访问权限，是决定你的技术文档、API参考或产品页面能否进入AI搜索知识库的第一步。这个工具将复杂的策略转化为具体的、可执行的配置文件，价值巨大。

3. 架构设计与跨平台兼容性实现

ultimate-seo-geo能在众多AI编程工具中运行，其核心在于精巧的架构设计和对于不同平台特性的适配。它不是一个单一的巨大脚本，而是一个模块化、可按需加载的知识与工具系统。

3.1 渐进式披露的架构

项目的文件结构清晰地体现了这一设计思想：

ultimate-seo-geo/ ├── AGENTS.md # 通用入口点（<32KB），被兼容工具自动加载 ├── SKILL.md # 路由外壳（用于Claude Code等技能原生平台） ├── references/ # 领域知识与详细步骤（按需加载） │ ├── procedures/ # 分步骤的详细操作指南（§1-§21） │ ├── ai-search-geo.md │ └── ... ├── scripts/ # 31个Python诊断脚本 └── evals/ # 测试场景与断言

• 第一层：AGENTS.md：这是一个小于32KB的“导航手册”，是所有兼容AGENTS.md标准的工具（如Codex, Gemini CLI, Cursor, Windsurf）的自动加载入口。它包含了核心的路由逻辑、所有功能的简要索引、脚本调用方法以及质量关卡（防止AI幻觉或错误操作）。由于其体积小，可以轻松被各种工具的上下文窗口容纳。
• 第二层：SKILL.md+references/+scripts/：当用户提出具体任务（如“检查hreflang”）时，AGENTS.md或SKILL.md会引导AI助手去references/procedures/目录下加载对应的详细步骤文件（例如§12-international-seo.md）。同时，如果需要执行诊断，则会调用scripts/目录下相应的Python脚本（如hreflang_checker.py）。这种“按需加载”的方式，使得这个庞大的技能包能够灵活适应不同工具可能存在的上下文长度限制。

对于像Claude Code这样原生支持“技能”安装的平台，SKILL.md这个精简的路由文件会被直接加载为技能。当技能被触发时，Claude Code会根据指令，动态读取references/下的详细知识来指导行动。

3.2 多平台适配详解

项目的兼容性表是其一大亮点，它明确指出了在不同环境下如何工作：

• 对于“全能型”工具（如Cursor, Windsurf, Cline, Aider）：这些工具通常具有完整的Shell访问权限。你只需要将项目克隆到工作目录，它们会自动发现AGENTS.md文件。此后，你就可以在聊天窗口中直接使用SEO相关的指令，工具会代表你执行脚本、读取文件，完成所有操作。
• 对于Claude Code：作为重点支持平台，它提供了两种安装方式。最方便的是通过其插件市场：在Claude Code聊天界面中输入/plugin marketplace add mykpono/ultimate-seo-geo添加市场，然后/plugin install ultimate-seo-geo@ultimate-seo-geo进行安装。安装后，技能会出现在你的技能列表中。另一种方式是手动将技能文件复制到Claude的全局技能目录。
• 对于GitHub Copilot：除了依赖AGENTS.md，项目还提供了.github/copilot-instructions.md文件，作为Copilot的补充上下文，进一步优化其在SEO任务上的表现。
• 对于能力受限的环境（如ChatGPT Custom GPTs）：这些环境无法直接运行本地脚本或访问完整的文件系统。项目专门准备了chatgpt/目录，里面包含了压缩版的指令和必要的知识文件，需要用户手动上传到Custom GPT的“知识”库中。虽然功能上会有一定限制（无法运行脚本），但核心的审计逻辑和建议生成仍然可用。

注意事项：在Claude Code中更新插件时需要注意，其市场缓存不会自动更新。如果你通过GitHub发布了新版本，用户需要手动进入插件缓存目录执行git pull，或者完全重新安装插件，才能获取最新功能。这是目前平台的一个限制，项目文档中给出了明确的解决步骤。

4. 实战操作流程与核心脚本解析

理论再好，不如亲手操作一遍。下面我们以一个典型的“网站SEO健康度审计”任务为例，拆解使用ultimate-seo-geo的完整流程，并深入看看几个核心脚本是如何工作的。

4.1 完整审计流程实操

假设你正在使用Cursor IDE，并且已经将项目克隆到本地。

第一步：环境准备

# 克隆项目 git clone https://github.com/mykpono/ultimate-seo-geo.git cd ultimate-seo-geo # 安装Python依赖（建议使用虚拟环境） python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt

依赖主要是requests和beautifulsoup4用于网页抓取和解析，以及可能用到的其他库如lxml。项目提供了requirements-check.py脚本进行预检。

第二步：启动审计在Cursor的聊天窗口中，你可以直接输入自然语言指令：

“请对 https://my-startup.com 进行一次完整的SEO审计，并生成报告。”

此时，Cursor会读取AGENTS.md，理解这是一个SEO审计任务。根据内置的路由逻辑，它会决定执行“审计模式”。

第三步：脚本执行与数据收集AI助手（在AGENTS.md的指导下）可能会依次或并行调用多个脚本：

1. fetch_page.py：抓取目标首页的HTML。
2. meta_lengths_checker.py：分析抓取到的HTML，检查标题、描述、H1的长度和唯一性。
3. pagespeed.py：调用PageSpeed Insights API（如果需要，需提前在环境变量中配置API密钥），获取核心网页指标数据。
4. internal_links.py：从首页开始，进行有限深度的爬取（默认设置，避免对目标站点造成压力），分析内部链接结构，找出孤岛页面。
5. validate_schema.py：检查页面中是否存在结构化数据，并验证其语法是否正确。
6. robots_checker.py：获取并解析网站的robots.txt，检查其对搜索引擎和AI爬虫的屏蔽规则。 ... 其他相关脚本根据初始分析结果被触发。

第四步：生成报告与行动计划所有脚本运行完毕后，数据会被汇总。AI助手会调用generate_report.py脚本的核心逻辑（或直接整合信息），生成两种格式的报告：

• HTML仪表盘(seo-report.html)：一个可视化的单页报告，包含健康度总分、各模块得分、问题列表、图表等，非常适合分享给非技术团队成员。
• Excel报告：包含所有原始数据和详细发现的工作表，便于技术团队进行筛选、排序和进一步分析。

报告不仅列出问题，还会根据影响程度和修复难度进行优先级排序（P0, P1, P2）。例如，它可能将“首页核心网页指标LCP不达标”标记为P0，将“部分产品页缺少规范标签”标记为P1。

第五步：生成可执行修复基于审计报告，你可以进一步指令AI：“根据P0优先级的问题，生成修复方案。” 此时，工具进入“执行模式”。例如，对于缺失的Product Schema，它会生成一个完整的、包含name,image,description,offers等属性的JSON-LD代码块，你只需将其插入到网站模板的<head>部分即可。

4.2 核心脚本工作原理与参数

让我们深入看两个脚本，理解其背后的逻辑：

generate_report.py：这是总控脚本。它的工作流程是：

1. 接收URL和可选参数（如--output,--crawl-deep）。
2. 按顺序或使用线程池调用其他诊断脚本（meta_lengths_checker.py,pagespeed.py等）。
3. 收集每个脚本返回的标准化JSON结果。
4. 使用finding_verifier.py对结果进行去重和合并，避免同一问题被多个脚本重复报告。
5. 将整合后的数据渲染成HTML模板（使用Jinja2等模板引擎），并生成Excel文件（使用openpyxl或pandas库）。
6. 关键参数--crawl-deep：默认审计只分析种子URL和通过有限爬取发现的少数页面，以快速出结果。添加此参数会进行更深、更广的爬取，更像Screaming Frog这样的专业爬虫，能发现更多内部链接和规范链接问题，但耗时更长，对目标服务器负载也更大。

hreflang_checker.py：国际SEO的关键。它检查以下规则：

1. 自引用：每个页面的hreflang标签中必须包含指向自身的链接。
2. 双向性：如果页面A通过hreflang指向页面B（例如en-us指向fr-fr），那么页面B也必须通过hreflang指回页面A。
3. 语言/地区代码有效性：检查代码是否符合ISO标准（如en,fr,de）。
4. x-default：是否正确设置了默认语言页面。
5. HTTP状态码：所有hreflang指向的URL必须返回200 OK（或3xx重定向且最终可达）。 脚本通过解析HTML的<link rel=“alternate” hreflang=“x”>标签，并递归检查这些链接来实现上述验证。

实操心得：在运行深度爬取 (--crawl-deep) 前，务必确认你有权对目标网站进行此类扫描，并且最好在网站流量低谷期进行。对于大型站点，可以考虑使用--max-pages参数限制爬取页面数量，避免过度消耗资源。此外，pagespeed.py脚本需要Google PageSpeed Insights API密钥，虽然免费但有配额限制，对于批量审计需要妥善管理。

5. 常见问题排查与效能优化

在实际使用中，你可能会遇到一些问题。以下是根据项目文档和常见实践整理的排查指南与优化建议。

5.1 安装与加载问题

5.2 审计过程中的问题与优化

5.3 针对特定场景的进阶用法

• 网站迁移预检：在迁移前，对旧站运行一次完整审计并生成报告。迁移后，对新站的相同URL路径再次运行审计，使用redirect_checker.py重点验证所有重定向是否返回301状态码且链路过长（避免跳转超过3次），并用broken_links.py检查是否有链接在迁移中断裂。
• 持续监控：可以将核心脚本（如core_web_vitals_checker.py，如果项目后续添加）集成到CI/CD流水线中。设定一个性能阈值（如LCP<2.5秒），每次部署前自动检查，不达标则阻止部署，确保SEO基础不会因代码更新而恶化。
• 内容质量基准：对于内容团队，可以定期使用readability.py和基于core-eeat-framework.md的评估逻辑，对发布的文章进行打分，建立内容质量的门槛，确保所有产出都符合E-E-A-T标准。

个人经验与避坑指南：我发现在使用这类自动化工具时，最大的价值不在于它发现了多少个“错误”，而在于它如何帮你聚焦和排序。工具可能会列出上百个“建议”，但其中可能只有不到10个是真正影响排名和流量的P0级问题。我的习惯是，首先关注技术健康度（Core Web Vitals、可索引性）和内容核心（唯一且准确的标题、H1、规范的Schema），这些问题修复后往往能带来立竿见影的效果。至于H2标签的层级是否完美、图片的alt属性是否100%覆盖，这些可以放在后续迭代中优化。另外，不要盲目接受工具生成的所有代码，尤其是复杂的JSON-LD。一定要将其放入 Google的富媒体搜索结果测试工具 中进行验证，确保没有语法错误且能被正确识别。