AgriciDaniel/claude-seo
GitHub: AgriciDaniel/claude-seo
一款专为 Claude Code 设计的开源 SEO 技能插件，通过并行运行 25 个子技能和 18 个专家 agent 实现覆盖技术与 AI 搜索的全面 SEO 审计。
Stars: 12876 | Forks: 1892
# Claude SEO：用于 Claude Code 的 SEO 技能
**Claude SEO 是一款专为 [Claude Code](https://claude.ai/claude-code) 设计的开源 SEO 分析插件。** 它可以并行运行 25 个子技能和 18 个专家 agent，全面覆盖技术 SEO、内容质量 (E-E-A-T)、Schema.org 标记、AI 搜索优化 (GEO)、本地 SEO、电商 SEO 以及国际 SEO。每次审计都会生成一份优先级排序的行动计划，其中包含基于 Google 官方一手指导的可测试建议。
[](https://github.com/AgriciDaniel/claude-seo/actions/workflows/ci.yml)
[](https://claude.ai/claude-code)
[](LICENSE)
[](https://github.com/AgriciDaniel/claude-seo/releases)
[](tests/)
[](https://www.skool.com/ai-marketing-hub-pro)
### 为什么选择 Claude SEO
- **AI 搜索优先。** 与 [Google 的 AI 优化指南](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)保持一致。具备基于问题的可引用性评分、关于 llms.txt 的一手证据、针对 AI 生成的产品图片的 IPTC `TrainedAlgorithmicMedia` 标记，以及符合 [web.dev](https://web.dev/) 标准的对 agent 友好的页面检查。
- **并行执行。** 全站审计可同时生成多达 15 个专家 agent。站点级审计在几分钟内即可完成，而不是几小时。
- **可证伪，而非推销。** 每条建议都附有其依据的第一性原理观察、依赖关系、明确的“我们如何知道它失败了？”检查方法，以及一个先行指标。详见 [方法论](#methodology)。
### 实际效果
这是一个于 2026 年 3 月 23 日上线并采用此工作流的网站在 Google Search Console 中的数据：展示了截至 2026 年 6 月 12 日，其前三个月的总点击量和展示量。
## 适用人群
- **运营 5 个以上客户网站的 SEO 代理商。** 用每周的自动化运行取代季度深度审计。在团队产能不变的情况下，将审计频率提升 4 倍，且每项建议都附带客户可自行验证的可证伪性检查。
- **SaaS / 出版方 / 电商公司的内部 SEO 负责人。** 在高管审查前提供第二双眼睛的审视。能够捕捉到 GSC 和 Lighthouse 隐藏的问题：Schema 弃用、AI 可引用性缺口、过期域名遗留风险、寄生 SEO 暴露、机器翻译漂移。
- **自由职业 SEO 顾问。** 通过 15 分钟的审计和真实的 0-100 分评分，在第一天就确定客户的业务范围。在您花费一小时撰写提案之前，用具体的价值证明赢得合作。
运行全面审计，观察并行 agent 在整个网站中展开工作：
[在 YouTube 上观看完整演示](https://www.youtube.com/watch?v=COMnNlUakQk)
## 目录
- [适用人群](#who-this-is-for)
- [安装](#installation)
- [快速开始](#quick-start)
- [命令](#commands)
- [功能](#features)
- [与手动 / 代理商 / 商业工具的对比](#compared-to-manual--agency--commercial-tools)
- [用例](#use-cases)
- [输出示例](#sample-output)
- [架构](#architecture)
- [方法论](#methodology)
- [v2 中的新特性](#whats-new-in-v2)
- [局限性](#limitations)
- [环境要求](#requirements)
- [卸载](#uninstall)
- [扩展](#extensions)
- [生态系统](#ecosystem)
- [文档](#documentation)
- [常见问题](#faq)
- [社区贡献者](#community-contributors)
- [许可证](#license)
- [贡献](#contributing)
- [作者](#author)
## 安装
### 插件安装 (Claude Code 1.0.33+)
最快的安装路径。只需一次性添加到市场，然后安装插件：
```
/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
/seo setup
```
此显式设置步骤会在 Claude 的持久化插件数据中创建一个隔离的 Python 环境，并安装 Playwright Chromium。您可以随时使用 `/seo doctor` 进行检查。不会创建任何全局 Python 包或 PATH 伪指令。
### 手动安装 (Unix / macOS / Linux)
```
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/install.sh
```
### Windows (PowerShell)
```
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1
```
## 快速开始
```
# 启动 Claude Code
claude
# 全站审计：并行 sub-agents 生成优先行动计划
/seo audit https://example.com
# 深度单页分析：on-page 元素、内容质量、Schema
/seo page https://example.com/about
# Schema markup 审计：检测、验证、生成
/seo schema https://example.com
# AI 搜索优化：段落可引用性 + 符合 primary-source 的建议
/seo geo https://example.com
# 使用行业模板生成 sitemap
/seo sitemap generate
```
## 命令
跨编排器、其子技能和 8 个 MCP 扩展的 32 个用户可调用的 `/seo` 命令。完整参考请见 [docs/COMMANDS.md](docs/COMMANDS.md)。
| 命令 | 描述 |
|---------|-------------|
| `/seo setup` | 创建或刷新隔离的 Python 运行时和 Chromium |
| `/seo doctor` | 检查运行时就绪状态，不更改系统 |
| `/seo audit ` | 通过并行委派子 agent 进行全网站审计 |
| `/seo page ` | 深度单页分析 |
| `/seo technical ` | 涵盖 9 个类别的技术 SEO 审计 |
| `/seo content ` | E-E-A-T 和内容质量分析 |
| `/seo content-brief ` | 详细的内容简报：目标关键字、大纲、内部链接 |
| `/seo schema ` | 检测、验证并生成 Schema.org 标记 |
| `/seo geo ` | AI Overviews / 生成式引擎优化 |
| `/seo sitemap ` | 分析或生成 XML 站点地图 |
| `/seo images ` | 图片优化分析 |
| `/seo plan ` | 战略性 SEO 规划 (saas, local, ecommerce, publisher, agency) |
| `/seo programmatic ` | 程序化 SEO 分析和规划 |
| `/seo competitor-pages ` | 竞争对手比较页面生成 |
| `/seo local ` | 本地 SEO 分析 (GBP, 引用, 评论, 地图包) |
| `/seo maps [command]` | 地图情报 (地理网格, GBP 审计, 评论, 竞争对手) |
| `/seo hreflang ` | Hreflang / i18n SEO 审计和生成 |
| `/seo google [command]` | Google SEO API (GSC, PageSpeed, CrUX, Indexing, GA4, PDF 报告) |
| `/seo backlinks ` | 反向链接配置分析 (Moz, Bing, Common Crawl) |
| `/seo cluster ` | 基于 SERP 的语义聚类 |
| `/seo sxo ` | 搜索体验优化 (页面类型, 用户故事, 画像) |
| `/seo drift baseline \| compare \| history ` | 带有 SQLite 快照的 SEO 漂移监控 |
| `/seo ecommerce ` | 电商 SEO 和市场情报 |
| `/seo flow [stage]` | FLOW 框架提示词 (CC BY 4.0, 证据主导) |
| `/seo firecrawl [command] ` | 全站抓取 (扩展) |
| `/seo dataforseo [command]` | 实时 SEO 数据 (扩展) |
| `/seo image-gen [use-case]` | 用于 SEO 资产的 AI 图像生成 (扩展) |
| `/seo ahrefs [command] ` | 通过官方 Ahrefs MCP 提供反向链接、自然关键字和内容数据 (扩展) |
| `/seo seranking [command]` | 跨 ChatGPT、Gemini、Perplexity、AI Overviews、AI Mode 的 AI 声音份额 (扩展) |
| `/seo profound [command]` | 带有时间序列数据的 LLM 引用追踪 (扩展) |
| `/seo bing [command] ` | Bing Webmaster Tools + IndexNow URL 提交 (扩展) |
| `/seo unlighthouse ` | 多页面 Lighthouse 运行器，在本地运行 (扩展) |
## 功能
### Claude SEO 会检查哪些 Core Web Vitals？
Claude SEO 会测量当前的三项 Core Web Vitals 指标：**LCP** (Largest Contentful Paint，目标低于 2.5 秒)、**INP** (Interaction to Next Paint，目标低于 200 毫秒) 和 **CLS** (Cumulative Layout Shift，目标低于 0.1)。[INP 于 2024 年 3 月 12 日取代了 FID](https://web.dev/articles/inp)；FID 已于 2024 年 9 月 9 日从 Chrome 的实测数据工具 (CrUX API, PageSpeed Insights) 中移除 (Lighthouse 作为实验室工具从未报告过 FID)，Claude SEO 也绝不会引用 FID。实测数据（如有）来自 Chrome User Experience Report (CrUX)；实验室数据则回退至通过 PageSpeed Insights 调用 Lighthouse 获取。通过 `/seo google` 的 CrUX 集成，可将 LCP 拆解为多个子部分 (TTFB, load delay, load duration, render delay) 以定位瓶颈。移动端和桌面端会分开测量。CrUX History（25 周趋势）包含在 Tier 0 免费凭据集中。
### Claude SEO 如何评估 E-E-A-T？
E-E-A-T (Experience 经验, Expertise 专业知识, Authoritativeness 权威性, Trustworthiness 可信度) 是根据《搜索质量评分指南》进行评估的，该指南最近一次更新是在 2025 年 9 月，将 YMYL 的范围扩大到了政治和社会话题。经验信号：原创研究、案例研究、第一手照片。专业知识：作者资质和主题深度。权威性：外部引用和品牌提及。可信度（四项中权重最大的一项）：联系信息、安全的 HTTPS、透明的更正机制、时间戳。在对子因素进行评分之前，Claude SEO 会应用 Google 自己在[实用内容指南](https://developers.google.com/search/docs/fundamentals/creating-helpful-content)中提出的 Who / How / Why 启发式评估法。只要符合 Search Essentials 的要求，生成式 AI 内容是没有问题的；但如果用它来批量制造低价值页面，就会越界成为垃圾内容，这正是 `seo-content humanize` 和 `seo-content verify` 设计用来检测的情况。
### Claude SEO 支持哪些 Schema.org 类型？
首选格式为 JSON-LD（Google 也明确表示首选此格式）。Claude SEO 会检测、验证并生成 [skills/seo/references/schema-types.md](skills/seo/references/schema-types.md) 中记录的活跃 Schema.org 类型，包括组织、文章、产品、本地、活动、工作、课程、软件/应用、服务、问答和视频模式。关于 FAQPage：Google 已于 2026 年 5 月 7 日停止在所有网站上显示 FAQ 富媒体结果；它不再带来任何 Google 富媒体结果收益。如有需要，请仅保留用于非 Google 语义或内部语义。已弃用且绝不推荐使用的类型：HowTo（富媒体结果于 2023 年 9 月被移除）、SpecialAnnouncement（2025 年 7 月）、ClaimReview、VehicleListing、EstimatedSalary、LearningVideo、CourseInfo 轮播（均于 2025 年 6 月被废弃）。替代指南详见：[skills/seo-schema/references/deprecated-types-2024-2026.md](skills/seo-schema/references/deprecated-types-2024-2026.md)。
### Claude SEO 如何针对 AI 搜索进行优化？
与 [Google 的 AI 优化指南](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)保持一致，该指南指出 "AEO" 和 "GEO" 只是 SEO 的重新包装。AI Overviews 和 AI Mode 建立在经典搜索相同的排名系统之上；页面必须被索引并有资格显示摘要，才能出现在任何 AI 功能中。Claude SEO 会对以下方面进行评分：段落引用性（最佳实践为 134-167 词的独立回答块）、基于问题的标题层级、归因密度、结构化数据覆盖率，以及在维基百科、Reddit、YouTube 和领英上的实体曝光度。`seo-geo` 技能基于证据反驳了三个流行的神话：llms.txt 目前并不是一个引用杠杆（[一手证据](skills/seo-geo/references/llmstxt-evidence.md)）、内容分块并非必需、并且因为同义词理解能力已经足够，AI 特定的关键字重写也是不必要的。
### Claude SEO 集成了哪些 Google SEO API？
4 层级的凭据系统允许您从零密钥开始，并按需添加数据。每个层级都能在其相应级别提供真正的价值：
| 层级 | 凭据 | 解锁的 API |
|------|------|------|
| 0 | API key | PageSpeed Insights, CrUX, CrUX History (25 周趋势) |
| 1 | + OAuth 或 Service Account | + Search Console (查询, URL 检查, 站点地图状态), Indexing API |
| 2 | + GA4 媒体资源配置 | + GA4 自然流量、热门着陆页、设备 / 国家细分数据 |
| 3 | + Ads 开发者 token | + Keyword Planner 搜索量和竞争数据 |
PDF 报告通过 [WeasyPrint](https://weasyprint.org/) 生成 (A4 布局)，包含 200 DPI 的 matplotlib 图表。运行 `/seo google setup` 启动凭据向导。所有凭据都存放在 `~/.config/claude-seo/` 目录下，权限为 `0o600`；不会将任何凭据提交到代码库中。
### Claude SEO 如何处理本地 SEO？
分为三个层级。**Google Business Profile 信号**：类别、营业时间、照片、帖子、产品、属性。**跨引用的 NAP 一致性**：将名称、地址、电话与主要目录进行匹配并标记偏差。**评论情报**：评分趋势、情感分析、回复覆盖率。对于多地点业务，Claude SEO 强制执行 30 页的警告阈值和 50 页的硬性停止，以防止门页违规（可配置）。`/seo maps` 工作流增加了地理网格排名追踪、GBP 配置审计和竞争对手半径映射。本地 Schema 生成涵盖了包含所有必需和推荐属性（地理坐标、营业时间、服务区域）的 `LocalBusiness`。阶段 F (v2) 增加了一个 GBP 弃用检测器，用于检测已废弃的聊天字段引用和 `.business.site` URL。
## 与手动 / 代理商 / 商业工具的对比
| | 手动审计 | 代理商合作 | 商业 SEO 审计工具 | **Claude SEO** |
|---|---|---|---|---|
| **每次审计耗时** | 资深 SEO 投入 4-8 小时 | 1-3 周周转时间 | 10-45 分钟抓取 + 报告 | **10-15 分钟** |
| **成本** | 高 (按小时计费) | $2k-$15k+ 每个项目 | $99-$999/月 订阅费 | **免费技能 + Claude Code 订阅** |
| **可重复性** | 不同分析师结果不一致 | 不同合作批次结果不一致 | 是 | **是，确定性 + 可脚本化** |
| **输出格式** | 堆砌发现的 PDF | 带品牌的幻灯片 | Web 仪表盘，CSV 导出 | **Markdown + PDF + JSON，本地文件** |
| **自定义基准** | 每个分析师手动设定 | 特定于代理商的框架 | 厂商固定 | **编辑本地 SKILL.md** |
| **数据会离开本机吗？** | 不会 (您的电子表格) | 会 (发送给代理商) | 会 (上传给厂商) | **不会，默认完全本地化** |
| **锁定效应** | 无 | 高 | 高 (数据导出阻力大) | **无。MIT 许可证，文件归您所有。** |
| **AI 搜索意识** | 取决于分析师 | 取决于代理商资深程度 | 滞后 (通常落后 6-12 个月) | **Google AI 优化指南 (2026 年 5 月), 2025 年 9 月 QRG, 采用 INP 而非 FID, GEO/AEO=SEO 重新定义, 基于 llms.txt 证据的立场** |
| **每项发现的可证伪性** | 否 | 否 | 否 | **是。每条建议都附带“我们如何知道它失败了？”的检查方法 + 先行指标** |
## 用例
**管理 10 个客户网站的 SEO 代理商负责人。** 用每周一早晨对每个网站执行一次 `/seo audit` 来取代每季度的“深度审计”惯例。提供客户健康评分邮件的时间从 4 小时缩短至 12 分钟；在不增加计费工时的情况下，覆盖范围从按季度变为按周。漂移基准可以捕获两次审计之间的指标倒退，从而将客户沟通从“看看这个快照”转变为“这是本周发生的变化”。
**拥有 50 名员工的 SaaS 公司内部 SEO 负责人。** 在每次季度业务审查前 24 小时运行 `/seo audit`。捕捉那些被平台 UI 隐藏的问题（程序化页面上失效的 canonical 链、Google 2025 年 6 月废弃潮后的 Schema 弃用、削弱从 SERP 到 AI Overview 引流能力的 AI 可引用性缺口、收购来的博客资产上存在的过期域名遗留问题），以免 CMO 在董事会面前询问为什么自然流量下降了。
**正在对接新客户的自由职业 SEO 顾问。** 在洽谈电话中运行 `/seo audit`。用真实的 0-100 分评分、3 个优先排序的关键发现以及针对每条建议的可证伪性检查，来锚定合作范围；而不是含糊地说“我看一下再回复您”。能够签下更多长期合同，因为价值证明发生在通话期间，而不是在提交提案之后。
## 输出示例
Claude SEO 会将编写真实的 Markdown 报告作为其核心交付物。以下是 `/seo schema https://rankenstein.pro/about` 审计报告前约 50 行的原文。该插件生成的实际结构、标题和评分格式如下所示。
```
# Schema Markup 报告：rankenstein.pro/about
**URL:** https://rankenstein.pro/about
**Date:** 2026-02-09
**Format Detected:** JSON-LD (3 blocks) | No Microdata | No RDFa
---
## 总结
| Metric | Value |
|--------|-------|
| **JSON-LD Blocks** | 3 |
| **Schema Types** | Organization, WebSite, SoftwareApplication |
| **Critical Issues** | 2 |
| **Warnings** | 5 |
| **Passed Checks** | 18 |
| **Overall Grade** | B+ (solid foundation, actionable gaps) |
---
## 现有 Schema 验证
### 1. Organization (`@id: #organization`)
| Property | Value | Status | Notes |
|----------|-------|--------|-------|
| `@context` | https://schema.org | Valid | |
| `@type` | Organization | Valid | Active type |
| `@id` | https://rankenstein.pro#organization | Good | Enables cross-referencing |
| `name` | Rankenstein | Valid | |
| `description` | Present, 200+ chars | Good | Descriptive and keyword-rich |
| `url` | https://rankenstein.pro | Valid | Absolute URL |
| `logo` | ImageObject with @id, url, width, height, caption | Excellent | Well-structured |
| `foundingDate` | "2024" | Imprecise | Year-only accepted but ISO 8601 preferred |
| `areaServed` | "Worldwide" | Text | Works but `GeoShape` is more semantic |
| `contactPoint` | email + contactType | Valid | Consider adding `telephone` |
| `founder` | 1 Person (Daniel Agrici) | Incomplete | Page describes two co-founders; second missing |
| `sameAs` | 5 social profiles | Good | GitHub, X, LinkedIn, YouTube, Reddit |
| `knowsAbout` | 6 topics | Good | Relevant topical signals |
**Critical Issue:** The `founder` property only includes Daniel Agrici. Benjamin Samar (Co-Founder & Technical Director) is displayed on the page but absent from the schema. This creates a content-schema mismatch that can confuse search engines.
```
其他审计输出遵循相同的结构：`FULL-AUDIT-REPORT.md` (总体审计)、`GEO-ANALYSIS.md` (AI 搜索就绪度)、`LOCAL-SEO-ANALYSIS.md` (GBP 和引用)，以及通过 WeasyPrint + matplotlib 生成的生产级 PDF（封面、目录、执行摘要、数据部分、建议、方法论，全站审计大约为 32 页 A4 纸）。
## 架构
该插件遵循 [Agent Skills 标准](https://docs.claude.com/en/docs/claude-code/skills)，采用三层架构（指令层、编排层、执行层）。技能和 agent 会从 `skills/seo-*/` 和 `agents/seo-*.md` 自动发现。编排器 (`skills/seo/SKILL.md`) 负责处理行业检测（SaaS、本地、电商、出版方、代理商）、并行子 agent 分派（最多同时进行 15 个），并在发出行动计划前通过 [10 原则框架](#methodology) 进行综合汇总。完整架构请见：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 方法论
每次审计都会遍历分为四个阶段的 10 项原则。每项发出的建议都包含四个字段：它所依据的第一性原理观察、它与其他建议的依赖关系、一个“我们如何知道它失败了？”的检查方法，以及一个需要监控的先行指标。
| 阶段 | 原则 | 作用 |
|---|---|---|
| **PERCEIVE** | OBSERVE (外部) · OBSERVE (内部) · LISTEN | 收集原始信号；审查自身的假设；阅读 SERP、品牌声音和社区真正在表达的内容 |
| **ANALYZE** | THINK · CONNECT (横向) · CONNECT (系统) | 归纳至第一性原理；寻找不明显的跨技能联系；排列成依赖关系图 |
| **VALIDATE** | FEEL · ACCEPT | 根据 UX、品牌声音、运营者能力进行压力测试；呈现可证伪性 |
| **ACT** | CREATE · GROW | 交付产出物；为下一次审计设定反馈循环 |
完整方法论请见：[skills/seo/references/thinking-framework.md](skills/seo/references/thinking-framework.md)。
## v2 中的新特性
v2.0.0 是该插件历史上最大规模的一次发布。历经六个构建阶段，现已全部发布：
- **阶段 A：全面引入无头渲染。** 共享的 `scripts/render_page.py` 结合了 Playwright Chromium 以及 [trafilatura](https://github.com/adbar/trafilatura) 和 [htmldate](https://github.com/adbar/htmldate)。每个审计子 agent 都能通过 `--render auto`（在 Next.js、React、Vue、Nuxt、Astro islands 上自动检测）获得具备 SPA 感知的抓取能力。解决了限制 v1.x 发展的 SPA 痛点。
- **阶段 B：符合 QRG 的内容质量门禁。** 基于 QRG §4.6.5 和 §4.6.6 的填充内容检测器和 AI 模式拟人化处理、声明验证扫描程序、通过 WHOIS 进行的过期域名遗留检查、Google 更新的一手官方更新日志。
- **阶段 C：技术和 CWV 深度。** 通过 CrUX 拆解 LCP 子部分 (TTFB, load delay, load duration, render delay)、Speculation Rules 和 bfcache 检测、适用于 Bing / Yandex / Seznam / Naver 的 IndexNow 提交器、Unlighthouse 多页面 Lighthouse 包装器。
- **阶段 D：Schema 完整性。** 四个明确的生成器 (Reservation, OrderAction, DiscussionForumPosting, ProfilePage)、电商 Schema 验证器 (`hasMerchantReturnPolicy`, `shippingDetails`, `MemberProgram`, EU `energyEfficiencyClass`, ProductGroup 变体)、双重验证器（结合 Rich Results Test 和 Schema Markup Validator）。
- **阶段 E：AI 搜索重构和 5 个全新的 MCP 扩展。** Ahrefs、SE Ranking (AI 声音份额)、Profound (LLM 引用追踪器)、Bing Webmaster 结合 IndexNow、Unlighthouse。此外，还推出了针对 Google 2024 年 11 月[站点信誉滥用政策](https://developers.google.com/search/blog/2024/11/site-reputation-abuse-update)的寄生 SEO 风险扫描器。
- **阶段 F：本地化、国际化和隐私打磨。** Google Business Profile 弃用检测器（聊天字段和 `.business.site` URL，Q&A 被视为类别/区域受限）、DMA consent-mode-v2 点击诊断、根据 2025 年 1 月 QRG 设定的机器翻译 QA 标记。
测试覆盖率从 39 项 (v1.9.9) 增长到涵盖 v2 产品线的 410 项；仅 url_safety 测试套件就运行了 91 个 SSRF 和 DNS-rebinding 绕过案例，填补了混淆 IPv4、FQDN 尾点 和重定向重绑定 等绕过漏洞类别。完整的迁移说明和破坏性变更请见：[docs/MIGRATION-v1-to-v2.md](docs/MIGRATION-v1-to-v2.md)。
### 自 v2.0.0 以来
- **v2.1.0 (2026 年 5 月)：时效性刷新。** 2026 年 5 月核心更新、Google I/O 2026（定制版 Gemini 2.5 为 AI Mode 提供支持）、FAQ 富媒体结果于 2026-05-07 被废弃 (QAPage 依然是用于真正问答页面的类型，只是 FAQ 标记本身不再产生富媒体结果)。
- **v2.2.0 (2026 年 6 月)：安全性 + 可移植性。** 修复了安装程序的凭据注入问题，填补了 SSRF authority-confusion 绕过漏洞，将 Google API 密钥移至 `X-Goog-Api-Key` 标头，增加了 secret-scan CI 门禁，修复了 Windows/macOS 上的问题；测试套件达到 326 个。
- **v2.2.1 (2026 年 6 月)：Google 时效性再次确认 + 全命令审计。** 包含全新 Agentic Browsing 类别的 Lighthouse 13.4.0、Google 搜索忽略 llms.txt、内部重新加权的 E-E-A-T 评分卡（根据 Google 的“信任最重要”原则，Trust 权重最高）；审计了所有的 `/seo` 命令和子命令，S.md 实现了 100% 的覆盖率。
- **v2.2.2 (2026 年 7 月)：全面审查与维护。** 修正了 GBP 问答处理、AI Mode 模型命名、图像模型 ID、Hook 输入行为，并增加了严格的参考图谱一致性门禁。
- **v2.2.3 (2026 年 7 月)：提示词规范对齐。** 在不改变行为、路由或输出契约的前提下，规范了整个提示词表面的强调和标点符号。
- **v2.2.4 (2026 年 7 月)：社区维护。** 添加了托管的跨平台运行时和安全的站点地图发现机制，修复了 GSC 分页和总数统计，替换了被移除的 Bing 接口，修补了扩展和 Windows 的可移植性缺口，并妥善处理了所有待解决的问题和拉取请求。
## 局限性
有两个真实的边界需要事先说明。
**繁重的客户端水合时机问题。** 阶段 A 的无头渲染器能够开箱即用地处理大多数 SPA（`--render auto` 会检测空的 `
单行命令 (curl，请先审查再执行)
``` curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh cat install.sh # review before running bash install.sh rm install.sh ```SCHEMA-REPORT.md: 一份真实审计报告的前 50 行
```
# Schema Markup 报告：rankenstein.pro/about
**URL:** https://rankenstein.pro/about
**Date:** 2026-02-09
**Format Detected:** JSON-LD (3 blocks) | No Microdata | No RDFa
---
## 总结
| Metric | Value |
|--------|-------|
| **JSON-LD Blocks** | 3 |
| **Schema Types** | Organization, WebSite, SoftwareApplication |
| **Critical Issues** | 2 |
| **Warnings** | 5 |
| **Passed Checks** | 18 |
| **Overall Grade** | B+ (solid foundation, actionable gaps) |
---
## 现有 Schema 验证
### 1. Organization (`@id: #organization`)
| Property | Value | Status | Notes |
|----------|-------|--------|-------|
| `@context` | https://schema.org | Valid | |
| `@type` | Organization | Valid | Active type |
| `@id` | https://rankenstein.pro#organization | Good | Enables cross-referencing |
| `name` | Rankenstein | Valid | |
| `description` | Present, 200+ chars | Good | Descriptive and keyword-rich |
| `url` | https://rankenstein.pro | Valid | Absolute URL |
| `logo` | ImageObject with @id, url, width, height, caption | Excellent | Well-structured |
| `foundingDate` | "2024" | Imprecise | Year-only accepted but ISO 8601 preferred |
| `areaServed` | "Worldwide" | Text | Works but `GeoShape` is more semantic |
| `contactPoint` | email + contactType | Valid | Consider adding `telephone` |
| `founder` | 1 Person (Daniel Agrici) | Incomplete | Page describes two co-founders; second missing |
| `sameAs` | 5 social profiles | Good | GitHub, X, LinkedIn, YouTube, Reddit |
| `knowsAbout` | 6 topics | Good | Relevant topical signals |
**Critical Issue:** The `founder` property only includes Daniel Agrici. Benjamin Samar (Co-Founder & Technical Director) is displayed on the page but absent from the schema. This creates a content-schema mismatch that can confuse search engines.
```
` 外壳并切换至 Playwright）。但仍会产生干扰性发现的边缘情况包括：水合过程与滚动到首屏下方位置绑定的页面、在用户交互（打开模态窗口、点击选项卡）后才获取关键内容的页面，以及极易引发竞态条件的第三方小部件挂载的页面。对于这些情况，建议的工作流是手动触发 `seo-visual` 子 agent，并将其 Playwright 快照与原始 HTML 子 agent 的发现进行比较。
**默认仅限本地且无数据扩充。** 免费层级默认不进行任何第三方 API 调用（审计程序仍会抓取您指定的目标 URL）。添加 Google API 凭据（Tier 0 到 3）可解锁真实的实测数据和实时的索引状态；否则，Core Web Vitals 只能是实验室预估值，索引状态也只能通过页面级信号进行推断。添加 MCP 扩展（Ahrefs、DataForSEO、SE Ranking、Profound）同样可以解锁竞争情报和 AI 引用数据，但需要您提供各自的账号。
## 环境要求
- Python 3.10+
- Claude Code CLI
- 可选：Playwright Chromium — install.sh 会提示您安装（您可以跳过该提示）；仅在需要 SPA 渲染和截图时使用
- 可选：用于丰富 CWV / GSC / GA4 数据的 Google API 凭据（参见 `/seo google setup`）
## 卸载
```
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/uninstall.sh
```
## 扩展
可选的 MCP 服务器可将实时数据添加到审计流水线中。Claude SEO 为 8 个服务器提供了扩展；插件核心在没有任何扩展的情况下也能正常工作。
### DataForSEO
实时 SERP 数据、关键字研究、反向链接、页面分析、内容分析、商家列表、AI 可见性检查和 LLM 提及追踪。跨越 9 个 API 模块的 23 个数据命令。
```
./extensions/dataforseo/install.sh # requires DataForSEO account
/seo dataforseo serp best coffee shops
/seo dataforseo ai-mentions your brand
```
完整的 DataForSEO 文档：[extensions/dataforseo/README.md](extensions/dataforseo/README.md)。
### Firecrawl
通过 [Firecrawl](https://www.firecrawl.dev/) MCP 服务器进行全站抓取和 URL 发现。
```
./extensions/firecrawl/install.sh
/seo firecrawl crawl https://example.com
```
完整的 Firecrawl 文档：[extensions/firecrawl/README.md](extensions/firecrawl/README.md)。
### Banana：AI 图像生成
通过 [Claude Banana](https://github.com/AgriciDaniel/banana-claude) 创意总监流水线生成 SEO 图像（OG 预览图、博客主图、产品照片、信息图表）。
```
./extensions/banana/install.sh
/seo image-gen og "Professional SaaS dashboard"
```
完整的 Banana 文档：[extensions/banana/README.md](extensions/banana/README.md)。
### Ahrefs, SE Ranking, Profound, Bing Webmaster, Unlighthouse (v2 新增)
阶段 E 新增了五个扩展：
- **Ahrefs：** 官方 `@ahrefs/mcp` 服务器，提供反向链接和自然搜索数据
- **SE Ranking：** 跨 ChatGPT、Gemini、Perplexity、AI Overviews、AI Mode 的 AI 声音份额
- **Profound：** 带有时间序列数据的 LLM 引用追踪器
- **Bing Webmaster：** Bing Webmaster Tools 结合统一的 IndexNow
- **Unlighthouse：** 基于 MIT 许可的多页面 Lighthouse 运行器
设置演练位于 `extensions//docs/` 下；集成说明请见：[docs/MCP-INTEGRATION.md](docs/MCP-INTEGRATION.md)。
## 生态系统
Claude SEO 是一系列能够无缝协作的 Claude Code 技能的一部分：
| 技能 | 作用 | 连接方式 |
|-------|-------------|-----------------|
| [Claude SEO](https://github.com/AgriciDaniel/claude-seo) | SEO 分析、审计、Schema、GEO | 核心。分析网站并生成行动计划。 |
| [Claude Blog](https://github.com/AgriciDaniel/claude-blog) | 博客写作、优化、评分 | 伴侣。根据 SEO 发现编写优化后的内容。 |
| [Claude Banana](https://github.com/AgriciDaniel/banana-claude) | 通过 Gemini 进行 AI 图像生成 | 共享。为 SEO 资产和博客文章生成图像。 |
| [Codex SEO](https://github.com/AgriciDaniel/codex-seo) | Codex 优先的 SEO 技能套件 | 移植。为 Codex 技能、TOML agent 和确定性运行器适配了相同的 SEO 系统。 |
| [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) | 文案、电子邮件、社交媒体、广告、漏斗、CRO | 社区。基于 SEO 发现执行营销行动。 |
| [FLOW](https://github.com/AgriciDaniel/flow) | 证据主导的 SEO 框架（41 个 AI 提示词，CC BY 4.0） | 知识库。驱动 `seo-flow` 提示词。 |
**工作流示例：**
1. `/seo audit https://example.com`：识别内容缺口和技术问题
2. `/seo backlinks https://example.com`：分析链接配置和竞争对手差距
3. `/seo geo https://example.com/blog/post`：对 AI 引用就绪度进行评分
4. `/blog write "target keyword"`：创建经过 SEO 优化的博客文章 (Claude Blog)
5. `/seo image-gen hero "blog topic"`：生成主图 (Banana 扩展)
## 文档
- [安装指南](docs/INSTALLATION.md)
- [命令参考](docs/COMMANDS.md)：深入解析每一个 `/seo` 命令
- [架构](docs/ARCHITECTURE.md)：三层设计、自动发现、并行分派
- [从 v1 迁移到 v2](docs/MIGRATION-v1-to-v2.md)：破坏性变更、六个阶段的工作
- [MCP 集成](docs/MCP-INTEGRATION.md)：集成说明；扩展设置位于 `extensions//docs/` 下
- [故障排除](docs/TROUBLESHOOTING.md)
- [贡献者](CONTRIBUTORS.md)：社区致谢
## 常见问题
### 什么是 Claude SEO？
Claude SEO 是一款专为 Claude Code 打造的开源 SEO 分析插件。它可并行运行 25 个子技能和 18 个专家 agent，全面覆盖技术 SEO、内容质量、Schema.org 标记、AI 搜索优化、本地 SEO、电商 SEO 以及国际 SEO。审计会生成一份优先级排序的行动计划，其中每条建议都附有其依据的第一性原理观察、与其他建议的依赖关系、一个“我们如何知道它失败了？”的检查方法，以及一个先行指标。该插件采用 MIT 许可证，不包含任何专有的追踪代码，无需第三方 API 扩充也能正常工作；但审计程序仍会联系您分析的目标 URL。本工具与 [Google 的 AI 优化指南](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) 及 2025 年 9 月的《搜索质量评分指南》保持一致。
### Claude SEO 与 Screaming Frog 或 Ahrefs Site Audit 有何不同？
覆盖面不同，权衡也不同。**Screaming Frog** 在链接图层面的抓取更深、速度更快；它是一款专门构建的爬虫，Claude SEO 并不试图取代它。**Ahrefs Site Audit** 带来了专有的反向链接索引和链接情报；Claude SEO 通过其 MCP 扩展与 Ahrefs 集成，而非与其竞争。Claude SEO 的领先之处在于：对话式的 LLM 原生工作流、建议的可证伪性（每项发现都附带明确的故障模式检查）、采用 MIT 开源许可且无任何按域名收费的模式、与 Google 一手指导保持一致的 AI 搜索优化，以及追踪一手来源的 Schema 弃用情况。请将 Screaming Frog 或 Ahrefs 用于它们最擅长的领域；而当您希望在与其他 Claude Code 工作流相同的环境中，获得 LLM 驱动的综合分析、对话式迭代以及 AI 搜索优先的审计能力时，请使用 Claude SEO。
### Claude SEO 可以在单页应用（Next.js、React、Vue）上运行吗？
可以。v2 的阶段 A 发布了一个由 Playwright Chromium 支持的共享无头渲染器 (`scripts/render_page.py`)。审计子 agent 会调用 `render_page.py --mode auto`，它会自动检测 SPA 特征（空的 `
单行命令
``` curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/uninstall.sh | bash ```` 外壳、单一的 bundle 脚本、水合标记）并切换至渲染模式获取内容。更底层的 `scripts/fetch_page.py` 包装器支持将 `--render auto` 作为可选的包装模式；其默认值为 `--render never`，用于进行原始 HTTP 请求。使用 `render_page.py --mode always` 或 `fetch_page.py --render always` 可强制进行渲染。内容提取使用 [trafilatura](https://github.com/adbar/trafilatura) 进行样板代码剔除。发布日期来源于 [htmldate](https://github.com/adbar/htmldate)。已知细节：对于那些绑定了滚动事件的水合页面或在交互后才获取内容的页面，依然会产生干扰性的发现；有关针对这些边缘情况推荐的 `seo-visual` 交叉检查工作流，请参阅[局限性](#limitations)章节。
### Claude SEO 会使用哪些 Google API，这些 API 是必需的吗？
都不是必需的。Claude SEO 在零 API 密钥的情况下也能完全发挥功能。4 层级的凭据系统允许您逐步升级：Tier 0（仅需 API 密钥）解锁 PageSpeed Insights、CrUX 和 CrUX History（25 周趋势数据）。Tier 1（+ OAuth 或 Service Account）增加了 Search Console（查询、URL 检查、站点地图状态）以及针对符合资格的 JobPosting 页面或 VideoObject 中的 BroadcastEvent 页面的 Indexing API；该 API 并不保证一定被收录。Tier 2（+ GA4 媒体资源配置）增加了自然流量、热门着陆页以及设备/国家细分明细。Tier 3（+ Ads 开发者 token）增加了 Keyword Planner 的搜索量和竞争数据。凭据设置向导可通过 `/seo google setup` 运行。所有凭据均存放在 `~/.config/claude-seo/` 目录下，文件权限为 `0o600`；代码库中不包含任何凭据，且除了 Google 自己的接口外，不会将凭据传输到任何其他地方。
### Claude SEO 是免费的吗？
是的。采用 MIT 许可证，完全开源，没有按域名的定价，没有遥测技术，也没有插件本身强加的 API 配额限制。核心插件和所有 25 个子技能在没有任何付费服务的情况下即可工作。部分可选的 MCP 扩展封装了付费服务（DataForSEO、Ahrefs、Profound、SE Ranking），您需要提供自己的账户凭据；它们的使用是可选的，插件在没有它们的情况下也能完全运行。Google API（PageSpeed Insights、Search Console、Indexing、GA4）由 Google 免费提供，具有正常的账户配额限制，并需要您自己的凭据。如果您需要超出该开源插件范围的商业支持或企业级功能，那将不属于本项目的范畴。
### 在 AI 搜索方面，Claude SEO 与普通 SEO 工具有何不同？
大多数 SEO 工具将 AI 搜索视为一门单独的优化准则。Claude SEO 遵循 [Google 自己的立场](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)，即 AEO 和 GEO 只是 SEO 换了个说法。AI Overviews 和 AI Mode 建立在经典搜索相同的排名系统之上；基本资格门槛就是正常的索引收录。Claude SEO 会对段落可引用性（134-167 词的独立回答块）、基于问题的标题层级、归因密度以及在维基百科、Reddit、YouTube 和领英上的实体存在感进行评分。它明确驳斥了三个来自网红的神话：将 llms.txt 作为引用杠杆、为 AI 进行内容分块、以及 AI 特定的关键字重写。对于商务网站，Claude SEO 会根据 Google Merchant Center 政策，对 AI 生成的产品图片进行 IPTC `TrainedAlgorithmicMedia` 要求审计。
## 社区贡献者
v1.9.0 包含了来自 [AI Marketing Hub](https://www.skool.com/ai-marketing-hub) Pro Hub 挑战赛的贡献：
| 贡献者 | 贡献内容 |
|------------|-------------|
| **Lutfiya Miller** (获胜者 | 语义聚类引擎 → `seo-cluster` |
| **Florian Schmitz** | SXO 技能 → `seo-sxo` |
| **Dan Colta** | SEO 漂移监控器 → `seo-drift` |
| **Chris Muller** | 多语言 SEO → `seo-hreflang` 增强 |
| **Matej Marjanovic** | 电商 + DataForSEO 成本配置 → `seo-ecommerce` + 成本防护机制 |
完整详情和原始仓库链接请见 [CONTRIBUTORS.md](CONTRIBUTORS.md)。
## 许可证
MIT 许可证。详情请参阅 [LICENSE](LICENSE)。
## 贡献
欢迎您的贡献。在提交 PR 之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并在 PR 描述中包含您所运行的测试或检查。
## 作者
由 **[Agrici Daniel](https://agricidaniel.com/about)**（AI 工作流架构师）构建。独立维护者，欢迎通过 [Pro Skool 社区](https://www.skool.com/ai-marketing-hub-pro) 进行社区贡献。在营销自动化、AI 辅助内容工作流以及 Claude Code 开源工具方面拥有丰富的背景。
- [博客](https://agricidaniel.com/blog)：关于 AI 营销自动化的深度剖析
- [AI Marketing Hub (免费)](https://www.skool.com/ai-marketing-hub)：开放的社区
- [AI Marketing Hub Pro](https://www.skool.com/ai-marketing-hub-pro)：Pro 社区，可抢先体验此技能
- [YouTube](https://www.youtube.com/@AgriciDaniel)：教程和演示
- [GitHub](https://github.com/AgriciDaniel)：所有开源工具
标签：AI插件, Claude Code, Schema标记, SEO优化, 代码示例, 内容营销, 数据分析, 特征检测, 网站审计, 逆向工具