# Claude Code SEO审计技能

`SEO` `Claude Code` `技术SEO` `内容优化` `谷歌API`

# Claude SEO - Claude Code 的 SEO 审计技能

Claude Code 的全面 SEO 分析技能。涵盖技术SEO、页面分析、内容质量（E-E-A-T）、Schema标记、图片优化、站点地图架构、AI搜索优化（GEO）、本地SEO、地图智能、谷歌SEO API（Search Console、PageSpeed、CrUX、GA4）、PDF报告生成及战略规划。

[![CI](https://github.com/AgriciDaniel/claude-seo/actions/workflows/ci.yml/badge.svg)](https://github.com/AgriciDaniel/claude-seo/actions/workflows/ci.yml)
[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-blue)](https://claude.ai/claude-code)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/github/v/release/AgriciDaniel/claude-seo)](https://github.com/AgriciDaniel/claude-seo/releases)

> **博客：** [Claude Code SEO技术栈完整解析](https://agricidaniel.com/blog/claude-code-seo-stack) | [v1.7.2版本：Firecrawl外链分析](https://agricidaniel.com/blog/claude-seo-172-firecrawl-backlink-analysis)

## 目录

- [安装](#安装)
- [快速开始](#快速开始)
- [命令](#命令)
- [功能特性](#功能特性)
- [架构](#架构)
- [扩展](#扩展)
- [生态系统](#生态系统)
- [文档](#文档)
- [系统要求](#系统要求)
- [卸载](#卸载)
- [贡献](#贡献)

## 安装

### 插件安装（Claude Code 1.0.33+）

```bash
# 添加市场（一次性操作）
/plugin marketplace add AgriciDaniel/claude-seo

# 安装插件
/plugin install claude-seo@AgriciDaniel-claude-seo
```

### 手动安装（Unix/macOS/Linux）

```bash
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/install.sh
```

<details>
<summary>一键安装（curl）</summary>

```bash
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash
```

或通过 [install.cat](https://install.cat)：

```bash
curl -fsSL install.cat/AgriciDaniel/claude-seo | bash
```

希望在运行前检查脚本？

```bash
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
cat install.sh        # 检查内容
bash install.sh       # 确认无误后运行
rm install.sh
```

</details>

### Windows（PowerShell）

```powershell
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1
```

> **为什么用 git clone 而不是 `irm | iex`？** Claude Code 自身的安全机制会将 `irm ... | iex` 标记为供应链风险（下载并直接执行远程代码，无需验证）。git clone 方式允许您在运行前检查 `claude-seo\install.ps1` 脚本内容。

## 快速开始

```bash
# 启动 Claude Code
claude

# 运行完整站点审计
/seo audit https://example.com

# 分析单个页面
/seo page https://example.com/about

# 检查 Schema 标记
/seo schema https://example.com

# 生成站点地图
/seo sitemap generate

# 优化 AI 搜索
/seo geo https://example.com
```

### 演示：
[在 YouTube 观看完整演示](https://www.youtube.com/watch?v=COMnNlUakQk)

**`/seo audit`：通过并行子代理执行完整站点审计**

## 命令

| 命令 | 描述 |
|------|------|
| `/seo audit <url>` | 通过并行子代理委托执行完整网站审计 |
| `/seo page <url>` | 深度单页面分析 |
| `/seo sitemap <url>` | 分析现有 XML 站点地图 |
| `/seo sitemap generate` | 使用行业模板生成新站点地图 |
| `/seo schema <url>` | 检测、验证并生成 Schema.org 标记 |
| `/seo images <url>` | 图片优化分析 |
| `/seo technical <url>` | 技术SEO审计（9个类别） |
| `/seo content <url>` | E-E-A-T 与内容质量分析 |
| `/seo geo <url>` | AI 摘要 / 生成式引擎优化 |
| `/seo plan <type>` | 战略SEO规划（saas、本地、电商、媒体、代理商） |
| `/seo programmatic <url>` | 程序化SEO分析与规划 |
| `/seo competitor-pages <url>` | 竞品对比页面生成 |
| `/seo local <url>` | 本地SEO分析（GBP、引用、评论、地图包） |
| `/seo maps [command]` | 地图智能（地理网格、GBP审计、评论、竞品） |
| `/seo hreflang <url>` | Hreflang/i18n SEO 审计与生成 |
| `/seo google [command] [url]` | 谷歌SEO API（GSC、PageSpeed、CrUX、索引、GA4） |
| `/seo google report [type]` | 生成带图表的 PDF/HTML 报告（cwv-audit、gsc-performance、full） |

### `/seo programmatic [url|plan]`
**程序化SEO分析与规划**

从数据源批量构建SEO页面，并设有质量保障机制。

**功能：**
- 分析现有程序化页面的内容稀薄问题和关键词蚕食现象
- 为数据驱动页面规划URL模式和模板结构
- 生成页面之间的内部链接自动化
- 规范标签策略与索引膨胀防控
- 质量门控：超过100个页面时发出警告，超过500个页面时强制停止并要求审计

### `/seo competitor-pages [url|generate]`
**竞品对比页面生成器**

创建高转化率的"X vs Y"和"X 的替代方案"页面。

**功能：**
- 带功能矩阵的结构化对比表格
- 带 AggregateRating 的产品 Schema 标记
- 针对转化优化的布局与 CTA 放置
- 针对比较意图查询的关键词定向
- 竞品公正呈现的准确性指引

### `/seo hreflang [url]`
**Hreflang / i18n SEO 审计与生成**

验证并生成多语言网站的 hreflang 标签。

**功能：**
- 生成 hreflang 标签（HTML、HTTP 头或 XML 站点地图）
- 验证自引用标签、返回标签、x-default
- 检测常见错误（缺少返回标签、无效代码、HTTP/HTTPS 不一致）
- 跨域 hreflang 支持
- 语言/地区代码验证（ISO 639-1 + ISO 3166-1）

## 功能特性

### 核心网页指标（当前指标）
- **LCP**（最大内容绘制）：目标 < 2.5秒
- **INP**（下次绘制交互）：目标 < 200毫秒
- **CLS**（累积布局偏移）：目标 < 0.1

> 注意：INP 已于2024年3月12日取代 FID。FID 已于2024年9月9日从所有 Chrome 工具中完全移除。

### E-E-A-T 分析
更新至2025年9月质量评估指南：
- **经验（Experience）**：第一手知识信号
- **专业知识（Expertise）**：作者资质与内容深度
- **权威性（Authoritativeness）**：行业认可度
- **可信度（Trustworthiness）**：联系信息、安全性、透明度

### Schema 标记
- 检测：JSON-LD（推荐）、Microdata、RDFa
- 依据谷歌支持类型进行验证
- 使用模板生成
- 废弃提醒：
  - HowTo：已废弃（2023年9月）
  - FAQ：仅限政府/医疗网站（2023年8月）
  - SpecialAnnouncement：已废弃（2025年7月）

### AI搜索优化（GEO）
2026年新增 - 优化适配：
- 谷歌 AI 摘要
- ChatGPT 网页搜索
- Perplexity
- 其他 AI 驱动搜索引擎

### 谷歌SEO API（v1.7.0新增）
直接集成谷歌SEO数据：
- **PageSpeed Insights + CrUX**：实验室和现场核心网页指标数据
- **Search Console**：热门查询、URL检查、站点地图状态
- **索引API**：通知谷歌新增/更新/删除的URL
- **GA4**：自然流量、热门落地页、设备/国家分布
- **PDF报告**：通过 WeasyPrint + matplotlib 生成企业级A4报告含图表

四级凭证系统——每个层级均可获得对应价值：
| 层级 | 认证 | 可用API |
|------|------|---------|
| 0 | API密钥 | PSI、CrUX、CrUX历史 |
| 1 | + OAuth/SA | + GSC、URL检查、索引 |
| 2 | + GA4配置 | + GA4自然流量 |
| 3 | + Ads令牌 | + 关键词规划师 |

### 本地SEO与地图智能（v1.6.0新增）
- 谷歌商家资料优化
- NAP一致性审计
- 引用与评论分析
- 地理网格排名跟踪与竞品半径地图

### 质量门控
- 超过30个地区页面时发出警告
- 超过50个地区页面时强制停止
- 按页面类型检测内容稀薄问题
- 门廊页面防控

## 架构

```
~/.claude/skills/seo/         # 主编排技能
~/.claude/skills/seo-*/       # 子技能（15个 + 2个扩展）
~/.claude/agents/seo-*.md     # 子代理（10个 + 2个扩展）
```

### 视频与直播 Schema（新增）
针对视频内容、直播和关键时刻的额外 Schema 类型：
- VideoObject：视频页面标记，含缩略图、时长、上传日期
- BroadcastEvent：直播内容的直播标识支持
- Clip：视频内的关键时刻/章节
- SeekToAction：在视频富结果中启用跳转功能
- SoftwareSourceCode：开源及代码仓库页面

参见 `schema/templates.json` 获取即用型 JSON-LD 代码片段。

### 近期新增
- 程序化SEO技能（`/seo programmatic`）
- 竞品对比页面技能（`/seo competitor-pages`）
- 多语言 hreflang 验证（`/seo hreflang`）
- 视频与直播 Schema 类型（VideoObject、BroadcastEvent、Clip、SeekToAction）
- 谷歌SEO快速参考指南

## 系统要求

- Python 3.10+
- Claude Code CLI
- 可选：Playwright（用于截图）
- 可选：谷歌API凭证（用于获取丰富数据，参见 `/seo google setup`）

## 卸载

```bash
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/uninstall.sh
```

<details>
<summary>一键卸载（curl）</summary>

```bash
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/uninstall.sh | bash
```

</details>

### MCP集成

与MCP服务器集成以获取实时SEO数据，包括来自 **Ahrefs**（`@ahrefs/mcp`）和 **Semrush** 的官方服务器，以及用于 Google Search Console、PageSpeed Insights 和 DataForSEO 的社区服务器。参见 [MCP集成指南](docs/MCP-INTEGRATION.md) 进行配置。

## 扩展

通过MCP服务器集成外部数据源的可选附加组件。

### DataForSEO

实时SERP数据、关键词研究、外链、页面分析、内容分析、商业列表、AI可见性检查及LLM提及追踪。涵盖9个API模块共22条命令。

```bash
# 安装（需要 DataForSEO 账户）
./extensions/dataforseo/install.sh
```

```bash
# 示例命令
/seo dataforseo serp best coffee shops
/seo dataforseo keywords seo tools
/seo dataforseo backlinks example.com
/seo dataforseo ai-mentions your brand
/seo dataforseo ai-scrape your brand name
```

完整文档参见 [DataForSEO扩展](extensions/dataforseo/README.md)。

### Banana（AI图片生成）

使用 [Claude Banana](https://github.com/AgriciDaniel/banana-claude) 创意总监流水线生成SEO图片（OG预览图、博客封面、产品图、信息图）。

```bash
# 安装扩展
./extensions/banana/install.sh
```

```bash
# 示例命令
/seo image-gen og "Professional SaaS dashboard"
/seo image-gen hero "AI-powered content creation"
/seo image-gen batch "Product photography" 3
```

完整文档参见 [Banana扩展](extensions/banana/README.md)。
已在使用独立版 Claude Banana？该扩展会复用您现有的 nanobanana-mcp 配置。

## 生态系统

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资产和博客文章生成图片 |
| [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) | 文案、邮件、社交、广告、漏斗、CRO | 社区——基于SEO发现执行营销行动 |

**工作流示例：**
1. `/seo audit https://example.com` — 识别内容缺口和技术问题
2. `/seo backlinks https://example.com` — 分析外链情况和竞品差距
3. `/blog write "目标关键词"` — 创作SEO优化博客文章
4. `/seo image-gen hero "博客主题"` — 生成封面图（banana扩展）
5. `/seo geo https://example.com/blog/post` — 优化AI引用

## 文档

- [安装指南](docs/INSTALLATION.md)
- [命令参考](docs/COMMANDS.md)
- [架构说明](docs/ARCHITECTURE.md)
- [MCP集成](docs/MCP-INTEGRATION.md)
- [故障排查](docs/TROUBLESHOOTING.md)

## 许可证

MIT 许可证 - 详情参见 [LICENSE](LICENSE)。

## 贡献

欢迎贡献！提交 PR 前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

由 [@AgriciDaniel](https://github.com/AgriciDaniel) 为 Claude Code 构建