Claude SEO 安装部署完全指南：从插件市场到手动安装、卸载升级与故障排查
【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-seo
本篇技术指南以docs/INSTALLATION.md为核心骨架，结合仓库内的install.sh、install.ps1、uninstall.sh、hooks/hooks.json、requirements.txt与tests/test_manifest_consistency.py等源码实现，系统讲解 Claude SEO（面向 Claude Code 的通用 SEO 分析技能）在 macOS / Linux / Windows 三种平台上的全部安装路径、目录布局、验证方法、卸载与升级流程，以及常见故障的排查手段。读完本文，你将能够在本地完整部署这一由 25 个子技能与 18 个子 Agent 组成的 SEO 工作台，并理解安装脚本背后的版本锁定、依赖管理与安全机制。
前置条件
在开始安装前，请确认你的环境满足以下要求：
| 组件 | 要求 | 说明 |
|---|---|---|
| Python | 3.10+，含 pip | 安装脚本会显式校验版本，低于 3.10 会直接报错退出 |
| Git | 任意可用版本 | 用于克隆仓库与拉取指定 release tag |
| Claude Code CLI | 已安装并完成配置 | 安装完成后在 CLI 内通过/seo命令调用技能 |
| Playwright（可选） | 用于截图能力 | 用于 SPA 渲染与截图分析；缺失时视觉分析回退到 WebFetch |
Python 版本校验逻辑直接体现在 install.sh 中：脚本先检查python3与git是否存在，再通过python3 -c 'import sys; ...'探测主次版本号，只有sys.version_info >= (3, 10)才继续执行。Windows 侧的 install.ps1 则依次尝试py -3、python3、python三个候选解释器，并会主动识别并拒绝 Microsoft Store 的 App execution alias 伪 Python。
推荐路径：插件安装（Claude Code 1.0.33+）
插件安装是官方推荐的路径，只需两步命令，即可将技能纳入 Claude Code 的插件体系，获得 hook 强制加载等手动安装无法完全获得的能力。
在 Claude Code 内部依次执行：
/plugin marketplace add AgriciDaniel/claude-seo /plugin install claude-seo@agricidaniel-claude-seo- 第一条命令把仓库注册为插件市场（marketplace）；
- 第二条命令以
claude-seo@agricidaniel-claude-seo的插件标识安装并激活技能。
从源码角度看，插件安装的额外价值在于 hook 机制：仓库 hooks/hooks.json 定义了PostToolUse钩子，当 Agent 执行Edit或Write操作时，会自动调用 hooks/run-python-hook.js 与 hooks/validate-schema.py 对写入的 Schema 文件进行实时校验。这正是 install.sh 中那句提示的由来——手动安装只能尽力复制 hook 文件，而 hook 的真正强制执行依赖插件清单（plugin manifest）加载，因此若需要 hook 校验能力，应优先选择插件安装。
手动安装：macOS / Linux（Unix）
快速安装
克隆后直接运行安装脚本：
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git bash claude-seo/install.sh--depth 1只拉取最新提交，可显著减少下载量。
Review-then-run 替代方案
对"先审阅再执行"有安全偏好的用户，可以先把安装脚本下载到本地审阅，确认满意后再运行：
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh cat install.sh # review bash install.sh # run when satisfied rm install.sh这一流程与该仓库的安全理念一致：install.sh在脚本末尾同样提醒用户 "Inspect remote scripts before piping them to bash"（install.sh）。
手动安装：Windows（PowerShell）
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1Windows 路径刻意采用git clone而非irm | iex（远程管道执行），因为 Claude Code 自身的安全防护会对管道式远程脚本执行发出拦截告警。运行前请先审阅 install.ps1 的内容。
分步手动安装（通用流程）
若你希望完全掌控安装过程，可以按以下步骤手动操作：
第 1 步：克隆仓库
git clone https://github.com/AgriciDaniel/claude-seo.git cd claude-seo第 2 步：运行安装器
./install.sh第 3 步：安装 Python 依赖（若安装器未自动完成）
安装器默认会在~/.claude/skills/seo/.venv/创建虚拟环境并安装依赖。若该步骤失败，可手动补装：
# Option A: Use the venv ~/.claude/skills/seo/.venv/bin/pip install -r ~/.claude/skills/seo/requirements.txt # Option B: User-level install pip install --user -r ~/.claude/skills/seo/requirements.txt从 install.sh 的源码可以看到，依赖安装遵循"venv 优先、--user回退"策略：先尝试python3 -m venv创建独立虚拟环境，venv 内 pip 安装失败时自动回退到pip install --user；若两者都失败，脚本会打印手工安装提示，并把requirements.txt复制到技能目录（install.sh），方便日后随时重试。
依赖清单 requirements.txt 采用"有界版本锁定 + 安全底线"策略，值得关注：
- 解析类：
beautifulsoup4>=4.12.0,<5.0.0、lxml>=6.1.1,<7.0.0（含 libxml2 安全补丁）、trafilatura>=2.0.0,<3.0.0（无样板内容提取，SPA 安全）、htmldate（发布日提取）与courlan（URL 辅助）； - 网络类：
requests>=2.32.4,<3.0.0与urllib3>=2.7.0,<3.0.0，明确标注修复了 CVE-2024-47081、CVE-2024-35195 及多个 urllib3 高危公告； - 视觉类：
playwright>=1.59.0,<2.0.0（修复 CVE-2025-59288）、Pillow>=12.2.0,<13.0.0； - 报告生成类：
matplotlib、weasyprint（PDF 导出）、openpyxl（Excel 导出）； - Google API 类：
google-api-python-client、google-auth、google-analytics-data等，供 seo-google 技能调用 GSC / PageSpeed / GA4 接口。
第 4 步：安装 Playwright 浏览器（可选，用于视觉分析）
pip install playwright playwright install chromiumPlaywright 是可选项。未安装时，视觉分析会回退到 WebFetch 方案，功能不受阻断。安装器在 install.sh 中也会尝试自动执行playwright install chromium，失败时仅打印警告并继续。
安装目录布局
安装器会把文件复制到以下位置：
| 组件 | 路径 |
|---|---|
| 主技能（orchestrator） | ~/.claude/skills/seo/ |
| 子技能 | ~/.claude/skills/seo-*/ |
| 子 Agent | ~/.claude/agents/seo-*.md |
从 install.sh 的复制逻辑可以还原更完整的安装产物：
skills/seo/主技能目录，额外获得schema/（Schema 模板，来自仓库 schema/templates.json）、pdf/（参考文档）、scripts/（共享脚本）、hooks/（hook 文件，含执行权限）等子目录；skills/下所有含SKILL.md的子目录被逐个复制为~/.claude/skills/<name>/；agents/下所有seo-*.mdAgent 定义被复制到~/.claude/agents/；extensions/下的可选扩展（如 DataForSEO、Banana、Firecrawl）按"技能/Agent/参考文档/脚本"分类复制，其中参考文档与脚本会归入~/.claude/skills/seo/extensions/<ext_name>/下。
验证安装
安装完成后按如下步骤验证：
- 启动 Claude Code：
claude- 确认技能已加载：
/seo若安装成功，应看到帮助信息或 URL 输入提示。此时即可运行seo audit <url>、seo technical <url>、seo schema <url>、seo geo <url>等命令（完整命令清单见 skills/seo/SKILL.md）。/seo audit会按编排逻辑并行派发 seo-technical、seo-content、seo-schema、seo-sitemap、seo-performance、seo-visual、seo-geo 等子 Agent，并在检测到 Google API 凭据、本地商户信号、反向链接 API、内容策略信号等条件时追加对应 Agent（skills/seo/SKILL.md）。
卸载
插件安装用户的卸载
/plugin uninstall claude-seo@agricidaniel-claude-seo /plugin marketplace remove AgriciDaniel/claude-seo手动安装用户的卸载
从一份全新的克隆中运行卸载器：
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git bash claude-seo/uninstall.sh关于卸载，uninstall.sh 的实现值得注意：它采用glob 枚举而非硬编码列表（set -euo pipefail+shopt -s nullglob），自动清除~/.claude/skills/seo、所有seo-*子技能目录与所有seo-*.mdAgent 文件（uninstall.sh）。这意味着未来新增的子技能会被自动清理，无需随版本发布新卸载器；官方也明确告诫不要手工维护rm列表，仓库自带的卸载器才是权威来源。若当前环境中没有任何相关目录或文件，卸载器会提示"Nothing to remove"并引导插件用户改用/plugin uninstall。
升级到最新版本
升级时，官方建议优先采用"先下载审阅、再执行"的方式，避免直接管道执行远程脚本：
# Uninstall current version curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/uninstall.sh | bash # Install new version curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash注意：
curl ... | bash属于管道直执行形式，安全性较低，仅为便利选项；更稳妥的做法是分两步：先下载脚本审阅，确认无误后再执行。
版本锁定机制
install.sh 通过环境变量锁定默认安装版本：
REPO_TAG="${CLAUDE_SEO_TAG:-v2.2.0}"脚本默认克隆v2.2.0release tag，而不是随时漂移的main分支，避免静默更新带来的意外变更。如需安装main最新版，可覆盖环境变量：
CLAUDE_SEO_TAG=main bash install.sh这一默认 tag 并非随意写死：测试 tests/test_manifest_consistency.py 中的test_install_scripts_default_tag_matches_plugin_version专门校验install.sh与install.ps1的默认 tag 必须等于 plugin manifest 中的版本号，否则 CI 直接失败。同样的测试还覆盖了 plugin.json、marketplace.json、CITATION.cff、pyproject.toml 之间的版本三角校验，以及"文档声明的子技能/子 Agent 数量必须与磁盘实际数量一致"的一致性保障（tests/test_manifest_consistency.py）——这些机制共同保证用户拿到的安装器永远与当前版本配套。
故障排查
"Skill not found" 错误
确认技能安装在了正确位置：
ls ~/.claude/skills/seo/SKILL.md若文件不存在，重新运行安装器。
Python 依赖错误
手动安装依赖：
pip install beautifulsoup4 requests lxml playwright Pillow urllib3 validators注意：这是排查用的最小依赖集。完整运行全部技能（含 PDF/Excel 报告、Google API、SPA 提取）建议安装 requirements.txt 中的完整清单，命令为pip install -r ~/.claude/skills/seo/requirements.txt。
Playwright 截图错误
安装 Chromium 浏览器内核：
playwright install chromiumUnix 权限错误
确保脚本具有执行权限：
chmod +x ~/.claude/skills/seo/scripts/*.py安装后的安全与维护建议
- 版本固定：手动安装默认锁定
v2.2.0tag（install.sh），升级前先审阅 CHANGELOG 与本仓库的 CHANGELOG.md； - 卸载走官方脚本：不要自行编写
rm列表，使用仓库自带的 uninstall.sh，其 glob 枚举机制能自动覆盖未来新增的技能与 Agent； - 可选扩展按需启用：DataForSEO、Firecrawl、Banana 等扩展需要各自的账号或 MCP 服务，插件核心在无扩展状态下即可完整工作（README.md）；
- 网络与离线说明：免费层级不调用任何外部 API，完全本地分析；只有配置 Google API 凭据或扩展 MCP 服务后才会产生外部数据请求（README.md）。
参考文档
- 安装指南（本文核心文档）
- Unix 安装脚本 与 Windows 安装脚本
- Unix 卸载脚本
- Python 依赖清单 与 项目元数据
- 安装一致性测试
- 主技能编排说明 与 Hook 配置
- 架构文档、命令参考 与 故障排查文档
【免费下载链接】claude-seoUniversal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-seo
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
