1实现原理 · 为什么它能做到
整仓是一个 Claude Code 插件（.claude-plugin/plugin.json 与 marketplace.json 双清单），旗舰入口是 skills/seo/SKILL.md：它本身不做分析，只把 `/seo <command> <url>` 分派到 24 个同级子技能，并在全站审计时按条件并行 spawn 18 个 subagent。
skills/seo/SKILL.md
**Invocation:** `/seo $1 $2` where `$1` is the command and `$2` is the URL or argument.
注：「25 子技能 / 18 子agent」= skills/ 下 25 个目录（含 orchestrator 自身）与 agents/ 下 18 个 .md 的实数；SKILL.md 自述编排 24 个（21 core + 1 framework + 2 extension mirror），第 25 个即 orchestrator 自己。路由表覆盖 audit/page/sitemap/schema/images/technical/content/content-brief/geo/plan/programmatic/competitor-pages/local/maps/hreflang/google/backlinks/cluster/sxo/drift/ecommerce/flow/setup/doctor 等 20+ 子命令。
全仓强制单一脚本调用形态：skill/agent/hook 只能经 `"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run <script.py>` 执行内置 Python，明令禁止裸解释器；launcher 置于 scripts/ 而非 bin/ 是 marketplace 的硬约束。
skills/seo/SKILL.md
canonical form used by every skill and agent. Claude Code expands
注：该约定把 55 个 scripts/*.py 收敛到一个入口，也是 allowlist 与隔离 venv 能生效的前提；手动安装时 install.sh 用 sed 把这个 token 改写成 `"$HOME/.claude/skills/seo/scripts/claude-seo"`（只改本次安装拷进来的 .md，且幂等）。
launcher 只做解释器解析：按 CLAUDE_SEO_PYTHON → py -3 → python3 → python 顺序探测 >=3.10 的解释器，全部失败就报错退出，自身不装任何东西。
scripts/claude-seo
echo "Claude SEO requires Python 3.10 or newer. Tried CLAUDE_SEO_PYTHON, py -3, python3, and python." >&2
注：探测脚本为 `-c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'`，找到后 exec 到同目录 runtime.py；CLAUDE_SEO_PYTHON 被当作单个数组元素而非 shell 命令，注释明说是为了防注入并支持带空格路径。
运行时在 scripts/runtime.py：`run` 子命令先做脚本白名单校验（52 个核心脚本的 frozenset + 文件名正则 + 目录逃逸检查），再用隔离 venv 的解释器执行；运行时未就绪则明确要求先跑 `/seo setup`。
scripts/runtime.py
raise ValueError("script is not in the bundled runtime allowlist")
注：实核：scripts/ 下 55 个 .py 中只有 release_sign.py、verify_release.py、runtime.py 不在白名单（发布工具与被调起的 runtime 自身不可被 agent 调用）；extensions/*/scripts 走独立 extension 参数路径，banana 扩展还有 MANUAL_EXTENSION_SKILLS 的手动布局回退。
`/seo setup` 在持久化数据目录里原子建 venv：venv --without-pip → ensurepip → pip install -r requirements.txt → playwright install chromium，任一阶段失败即回滚。
scripts/runtime.py
[str(staged_python), "-m", "pip", "install", "--disable-pip-version-check", "-r", str(root / "requirements.txt")],
注：这是本插件唯一的大规模联网装包动作；依赖锁在 requirements.txt（18 个包，逐条带 CVE 备注），Chromium 可 --skip-browser 跳过，渲染缺失时以退出码 10 表达「核心可用、浏览器不完整」，由 install.sh/install.ps1 翻译成警告提示。
插件自带 PostToolUse 钩子：每次 Edit/Write 后由 node 拉起 hooks/validate-schema.py 校验被写文件中的 JSON-LD，placeholder/deprecated 类错误以 exit 2 阻塞该次编辑。
hooks/hooks.json
"${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js",
注：hooks.json 只声明 matcher `Edit|Write`；run-python-hook.js 负责跨平台找 Python（含 Windows Store 别名 stub 探测），validate-schema.py 仅处理 .html/.htm/.jsx/.tsx/.vue/.svelte/.php/.ejs、>10MiB 直接跳过、FAQPage 故意不拦（Google 已停 FAQ 富结果但类型仍合法）。手动安装只拷贝 hook 文件，install.sh 自陈「hook enforcement requires plugin install」。
面向目标站点的取数统一过 SSRF/DNS-rebinding 防护层：fetch_page.py 用 url_safety.safe_requests_session，render_page.py/capture_screenshot.py 用 Playwright 并在 route() 层复验每个子资源主机。
scripts/url_safety.py
Centralizes SSRF protection, DNS rebinding mitigation, and DNS-pinned HTTP
注：url_safety 还提供 validate_url_strict（解析全部 A 记录逐一判私网 + 返回 pinned IP）、safe_requests_get/head/session、CLAUDE_SEO_LOCAL_TARGETS 白名单（只作用于首个顶层 URL，重定向/子资源/浏览器请求不适用，云 metadata 地址即使列白也拒）。SECURITY.md 自陈残留：Chromium 内部 DNS 与 CONNECT 代理会削弱 pin，纯 IPv6 目标 fail-closed。
可选能力（8 个 MCP 扩展）不在核心包里，而由各自 installer 把 MCP server 与用户凭证合并进 `~/.claude.json` 的 mcpServers（原子替换 + chmod 0600），并把镜像 skill 拷进 ~/.claude/skills/。
extensions/dataforseo/install.sh
os.chmod(tmp, 0o600)
注：同一模式：firecrawl（FIRECRAWL_API_KEY）、banana（GOOGLE_AI_API_KEY → nanobanana-mcp）、ahrefs（AHREFS_API_TOKEN）；bing-webmaster/profound/seranking 改把 key 写进 `~/.claude/settings.json` 的 env 段。注释明确解释为何不写 settings.json 的 mcpServers：「`mcpServers` is not a key Claude Code reads there」。
2核心能力
01全站审计的并行 subagent 编排（/seo audit）
0224 子技能的命令路由面（/seo <command> <url> 单入口覆盖技术/内容/schema/图片/GEO/本地/maps/hreflang/电商/反链/聚类/SXO/漂移/程序化/计划/报告）
03Google 第一方数据接入（GSC / PageSpeed v5 / CrUX / Indexing / GA4 / Ads / NLP / YouTube），按凭证分 4 档能力
04AI 搜索 / GEO 审计（AI crawler 可达性、llms.txt 证据、段落级可引用性评分，且以 Google 官方立场为准）
05反链画像与毒性链接判定（免费 Moz/Bing/Keywords Everywhere/Common Crawl + 付费 DataForSEO + 存活验证爬虫）
06结构化数据检测/校验/生成，并在编辑时由 hook 阻塞不合格的 JSON-LD
07SEO 漂移监控：baseline / compare / history 三段式，把页面 SEO 关键元素快照存盘后做回归对比
08交付物生成：审计产物落 `{domain}-audit/`，并可出 A4 PDF/HTML/Excel 专业报告（weasyprint + matplotlib + openpyxl）
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | git |
| cli | python3 >= 3.10（或 CLAUDE_SEO_PYTHON / py -3 / python） |
| cli | node（hook 包装器） |
| cli | npx / Node 18+（MCP server 与 unlighthouse 经 npx 拉起） |
| network | PyPI（pip install -r requirements.txt，18 个包） |
| network | Playwright Chromium 下载 |
| api | Google PageSpeed Insights v5 |
| api | Chrome UX Report (CrUX) 现场数据与 25 周历史 |
| api | Google Search Console / Indexing / GA4 / Ads（google-api-python-client + OAuth） |
| api | Google Cloud Natural Language（实体/情感/分类） |
| api | Moz Link Explorer API（DA/PA、spam、domains、anchors） |
| api | Bing Webmaster Tools API |
| api | Keywords Everywhere openPageRank（免费反链回退档） |
| network | Common Crawl 超链接图（域名级 PageRank，无 key） |
| api | IndexNow（Bing/Yandex/Seznam/Naver 收录提交） |
| api | DataForSEO API（脚本直连路径）与 dataforseo-mcp-server（MCP 路径） |
| api | GitHub Contents API：把上游 FLOW 仓库的 prompt 文档同步进本 skill 的 references（写盘） |
| api | Gemini 图像生成（banana 扩展，generativelanguage v1beta） |
| api | Ahrefs 官方 MCP server（@ahrefs/[email protected]） |
| package | Python 依赖：requests/beautifulsoup4/lxml/lxml_html_clean/playwright/urllib3/trafilatura/htmldate/courlan/matplotlib/numpy/weasyprint/openpyxl/google-api-python-client/google-auth/google-auth-httplib2/google-analytics-data/google-ads |
| package | npm 包（扩展运行时）：[email protected]、@ycse/[email protected]、[email protected] |
| network | 任意用户指定目标站（HTTP 抓取 + Playwright 渲染 + 反链存活验证 + 截图） |
4风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- hook 是持续性的代码执行面，且能阻塞编辑 — 插件安装后 hooks/hooks.json 注册 PostToolUse(Edit|Write)，每次写入都执行 node → hooks/validate-schema.py，placeholder/deprecated 命中即 `sys.exit(2) # Block the edit`。审查该插件时必须把 hook 当常驻干预编辑流程的组件，而非文档。
- 安装与 setup 期供应链面较宽 — install.sh 走 git clone @tag + cp，setup 会 `pip install -r requirements.txt`（18 个包）并 `playwright install chromium`；扩展 installer 还会 `npx --yes --package=<pin>` 预热 5 个 npm 包。版本已 pin，但无校验和/签名校验——SECURITY.md 自陈 install script 校验「tracked for v2.3」。
- 明文凭证落盘与用户配置改写 — 8 个扩展 installer 读写 ~/.claude.json / ~/.claude/settings.json：DataForSEO 账号密码、Ahrefs/Firecrawl/Gemini key、Bing/IndexNow/Profound/SE Ranking key 均为明文 JSON（靠 0600 与原子写降低泄露面），并会改写用户既有 Claude 配置内容。
- prompt injection 面天然很大，防护是提示词级 — skill 的职责就是抓取任意第三方网页与第三方 API 结果并让模型据此产出建议；虽然 14+ 个 agent 文件写明 untrusted-data 条款，但该条款靠模型遵守，页面内诱导文本仍可能影响输出。建议不要对不可信站点开启渲染路径，关键结论人工复核。
- 上游内容会被同步进本地 skill 指令面 — scripts/sync_flow.py 从 api.github.com 拉取上游 FLOW 文档并覆盖写入 skills/seo-flow/references/**（主机白名单 + 5MB 上限 + 路径逃逸检查 + SHA-256 lock）。防护是「来源固定 + 完整性基线」，不含内容语义审查；上游若被篡改，其文本会成为后续会话的参考指令。
- SEO 结论本身有时效与商业色彩 — Google 政策类内容带明确到期日（FAQ 富结果 2026-05-07 停用、HowTo 2023-09 弃用、deprecated 字典硬编码在 hook 里），跨版本不可外推；skill 指令内嵌固定社区推广 footer（Skool 链接），大交付后会出现于报告尾部。
不是红档：无混淆/隐藏 payload（base64/eval/exec/\xNN 全仓零命中）、无遥测、MIT、SSRF 与 DNS-rebinding 做了罕见的工程化硬化（url_safety + 91 例回归）、凭证文件统一 0600、卸载可逆、README 明示 curl|bash 风险并建议先审。但确实超出黄档：① 插件安装即在宿主注册 PostToolUse hook，每次 Edit/Write 都执行 node+python 且可 exit 2 阻塞编辑，属持续代码执行面；② install.sh/setup 会 pip 安装 18 个包并下载 Chromium，扩展 installer 还会 npx 拉取预热 5 个 npm 包（供应链面；版本已 pin 但无校验和/签名校验，SECURITY.md 自陈 installer 校验「tracked for v2.3」）；③ 8 个扩展 installer 读写 ~/.claude.json / ~/.claude/settings.json，落盘明文凭证（含 DataForSEO 账号密码、Ahrefs/Firecrawl/Gemini key），并会改写用户既有 Claude 配置；④ 日常职责就是抓取任意第三方页面并让模型据其内容产出建议，prompt injection 面天然巨大而防护主要是提示词级；⑤ sync_flow.py 把上游仓库文本写进自己 references，形成长期指令面的外部内容通道。以上任一条被触发都在用户机器上产生真实副作用，故定 orange。用前建议：把 hook 纳入审查清单、扩展凭证用独立且可撤销的 key、避免对不可信站点启用渲染路径。
5第二遍独立确认
- [ok] skill.path 定位 — 候选：仓库根（无 SKILL.md，只有 README/AGENTS/CLAUDE/SECURITY 等治理文件）、skills/seo/（SKILL.md frontmatter `name: seo` + `user-invocable: true`，Quick Reference 表是全插件唯一命令入口，runtime 约定、编排逻辑、评分权重只写在这里）、skills/seo-audit/（只是被路由到的子技能）、extensions/*（需另行安装的可选项）。结论 skills/seo 为该插件旗舰入口目录，与被分配的 path 一致。注意本行 identity 是整个插件，故 analysis 覆盖全仓（8 扩展、18 agent、55 脚本、hook、安装器）而非仅路由文件。
- [discrepancy] 「扩展把 MCP 配置合并进 ~/.claude/settings.json」的说法 — docs/ARCHITECTURE.md:346 写「6. Merges MCP config into `~/.claude/settings.json` non-destructively」，但实际 dataforseo/firecrawl/banana/ahrefs 四个 installer 写的是 `~/.claude.json`，并在注释中明确反驳该文档（「MCP servers live in ~/.claude.json (the file `claude mcp add` writes). NOT ~/.claude/settings.json - `mcpServers` is not a key Claude Code reads there」）。真正写 settings.json 的是 bing-webmaster/profound/seranking（写 env 段，语义正确）。属文档未同步，非行为缺陷。
- [ok] 运行时白名单是否会挡住合法脚本 — 正则提取 ALLOWED_CORE_SCRIPTS 得 52 项，与 scripts/ 下 55 个 .py 的差集恰为 release_sign.py、verify_release.py、runtime.py；前两者是发布签名/校验工具，后者是 launcher 目标本身（_resolve_script 显式拒绝 candidate == __file__）。文档中被引用的脚本（render_page/fetch_page/google_auth/backlinks_auth/drift_*/schema_generate/sync_flow 等）全在白名单内，声明与实现相符。
- [discrepancy] CLAUDE.md 称 scripts/ 有 54 个 Python 执行脚本 — 实测 `ls scripts/*.py` = 55（白名单 52 + 3 个发布/运行时）。差一行注释，不影响能力结论，但说明此类计数属陈旧文案，引用须以磁盘为准。
- [ok] 「25 子技能 / 18 子agent」是否夸大 — skills/ 下 25 个目录、agents/ 下 18 个 .md，与 plugin.json「25 sub-skills (21 core + 1 orchestrator + 1 framework + 2 extension mirrors) and 18 sub-agents」精确对应；SKILL.md 正文说「orchestrates 24 sub-skills」并解释第 25 个是 orchestrator 自身，两种表述数学自洽。
- [ok] 「410 tests passing」徽章 — README 徽章声明 410 passing；本地 tests/ 有 90+ 个 test_*.py，且存在安全主题测试（test_url_safety、test_extension_installer_injection、test_agent_untrusted_content、test_banana_api_key_safety、test_google_api_key_safety 等）。按批 2 约束未执行任何测试，故仅作为「测试面存在」的证据，不背书通过数。
- [ok] 是否漏掉网络调用 / 隐藏脚本 / 混淆 — 全仓扫描 http(s) 主机与 requests./urlopen/subprocess/npx/pip/playwright 调用点后，未发现未列入 external_deps 的外发目标；base64 -d、eval(、exec(、\xNN、`curl | bash`、`irm | iex` 全部零命中；install.sh 把 clone 固定在 tag（REPO_TAG=v2.3.1，注释说明防 main 静默漂移），并有 test_manifest_consistency.py 守卫与 plugin.json 一致。
- [ok] 外部依赖逐条回源 — 22 条 external_deps 全部由「常量定义行 / installer 写入行 / env 读取行」直接引证，无一条取自 README 宣传语。唯一非源码级的是 Playwright Chromium 的下载域名（runtime.py 只写 `-m playwright install chromium`，域名未出现在仓库），已在该条 endpoint 如实标注。
6结论
适合：适合需要「可重复、可交付」SEO 工作流的人：代理机构批量做客户站审计、in-house SEO 在评审前做第二双眼、独立顾问用一次审计拿下客户。典型用法是插件安装后 `/seo setup` 建好隔离运行时，再 `/seo audit <url>` 起并行 subagent、按需接 GSC/PSI 等第一方数据，最后出 PDF 报告；合规要求高的场景可以只装核心、不装任何扩展（默认核心零第三方 API，只访问你指定的目标站）。
不适合：不适合期望「装上即用、零配置」的用户——首次必须 `/seo setup`（联网装 24 个 pip 包并下载 Chromium）；不适合禁止在宿主注册编辑期 hook 的环境（手动安装可绕过，但也同时失去 schema 质量门禁）；不适合把审计结论当合规凭据（结论仅对该 commit/该时点有效，且带行业时效）；不适合不愿让凭证落明文 JSON 的用户（扩展会把 key 写进 ~/.claude.json / settings.json）；也不适合把不可信站点直接扔进渲染路径的高对抗场景（插件自己把 Chromium DNS rebinding 列为已知残留风险）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 claude-seo.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent50b15d6fd70df445…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库AgriciDaniel / AgriciDaniel/claude-seo
原始 GitHubAgriciDaniel/claude-seo ↗
Stars16957
最近推送2026-09-11
本 skill commit
92795530b4许可MIT（仓库根 LICENSE 为 MIT License, Copyright (c) 2026 agricidaniel；.claude-plugin/plugin.json 的 license 字段与 pyproject.toml 亦为 MIT）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。