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爬虫的指令。该模块会检查并为你生成针对GPTBotOpenAI、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.mdreferences/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-geoultimate-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.pyhreflang标签是国际站点的常见错误点。此脚本会检查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应用。如果问题依旧尝试手动清理并重新克隆市场缓存rm -rf ~/.claude/plugins/marketplaces/ultimate-seo-geo git clone https://github.com/mykpono/ultimate-seo-geo.git ~/.claude/plugins/marketplaces/ultimate-seo-geo然后重启Claude Code。问题运行脚本时提示“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知识和工作流的承载平台。