导读

本文基于 claude-seo 仓库中的 seo-audit 技能定义，系统讲解该开源项目如何把一次"全站 SEO 审计"拆解为"渲染首页 → 业务类型识别 → 最多 500 页爬取 → 15 个专家子代理并行审查 → 聚合健康评分 → 落盘审计产物 → 生成优先级行动方案与 PDF 报告"的完整流水线。读完本文，你将掌握 seo-audit 的调用入口、子代理编排规则、爬虫配置、audit-data.json数据结构、评分权重与优先级定义，并能结合仓库源码理解render_page.py、google_report.py等底层脚本的真实行为。

一、技能定位：seo-audit 在 claude-seo 生态中的角色

claude-seo 是一个面向 Claude Code 的通用 SEO 技能集，包含 25 个子技能与 18 个子代理。在skills/seo/SKILL.md的快速参考表中，/seo audit <url>被定义为"使用并行子代理委托执行的全站审计"，而 seo-audit 正是承载这条命令的核心实现。

从skills/seo-audit/SKILL.md的 frontmatter 可以看到该技能的触发语义：

name: seo-audit description: "Full website SEO audit with parallel subagent delegation. Crawls up to 500 pages, detects business type, delegates to up to 15 specialists (8 always + 7 conditional), generates health score. Use when user says audit, full SEO check, analyze my site, or website health check." user-invocable: true argument-hint: "[url]" license: MIT metadata: author: AgriciDaniel version: "2.2.0" category: seo

四个关键事实值得注意：

• 可被用户直接调用（user-invocable: true），参数为一个 URL；
• 触发词覆盖自然语言意图：audit、full SEO check、analyze my site、website health check都会路由到该技能；
• 委托上限为 15 个专家子代理，其中 8 个始终参与，7 个按条件触发（详见下文"子代理编排"）；
• 输出一个 0-100 的健康评分，作为审计的量化结论。

在skills/seo/SKILL.md的编排逻辑中，/seo audit完成后还会要求按 PERCEIVE → ANALYZE → VALIDATE → ACT 的四阶段思维框架对发现进行综合（参考 thinking-framework），再按 Critical / High / Medium / Low 分桶，最后向用户提议生成 PDF 报告。也就是说，seo-audit 是"数据采集与发现"层，而合成方法论与报告层由 orchestrator 与 google_report.py 承接。

二、审计主流程：七步流水线

skills/seo-audit/SKILL.md的 Process 章节定义了完整的七步流程：

1. 渲染首页：执行python3 scripts/render_page.py <url> --mode auto --json，捕获原始 HTML、渲染后 HTML、抽取文本、SPA 状态与可访问性数据；
2. 检测业务类型：依据首页信号判断站点属于 SaaS、本地服务、电商、出版/媒体、代理商或其他类型；
3. 爬取站点：沿内部链接爬取最多 500 页，遵守 robots.txt；
4. 委托给子代理（可用则并行，否则按顺序内联执行）：seo-technical、seo-content、seo-schema、seo-sitemap、seo-performance、seo-visual、seo-geo 为固定项，另按条件追加 seo-local、seo-maps、seo-google、seo-backlinks、seo-cluster、seo-sxo、seo-drift、seo-ecommerce；
5. 评分：聚合为 SEO Health Score（0-100）；
6. 持久化审计产物：所有输出写入{domain}-audit/目录；
7. 报告：生成优先级行动方案，并可选用 PDF/HTML 报告交付。

源码级佐证：第一步为什么必须用 render_page.py

仓库测试 test_audit_instructions.py 以静态断言锁定了这条契约：

def test_seo_audit_starts_with_render_page_auto() -> None: process = text[text.index("## Process"):text.index("## Crawl Configuration")] assert "scripts/render_page.py" in process assert "--mode auto" in process assert "scripts/fetch_page.py` to retrieve HTML" not in process

即：审计流程必须以render_page.py --mode auto开头，且禁止退回旧的fetch_page.py裸抓取方式。原因在 render_page.py 的模块文档中写得很清楚——v2.0.0 之前只有 seo-visual 使用 Playwright，其余代理直接抓取原始 HTML，导致对 SPA 站点产生系统性漏报（空的<div id="root">、源码中无 schema、无正文内容）。

render_page.py提供三种模式：

SPA 检测逻辑位于_is_spa()，识别_SPA_SHELL_PATTERNS中的 React（<div id="root">）、Next.js（<div id="__next">）、Vue/Nuxt（<div id="__nuxt">）、Svelte（data-svelte-h=）、Astro（<astro-island）等水合外壳特征，并在<body>文本少于 100 字符时也判定为 SPA（阈值刻意保守以降低误判）。渲染模式下返回的 JSON 包含is_spa、extracted_text（经 trafilatura 去除样板后抽取正文）、publication_date（经 htmldate 识别）、console_errors、render_ms等字段。

此外，render_page.py内置了 SSRF 纵深防御：URL 先经 url_safety.py 的validate_url_strict校验，Playwright 内再通过route()拦截所有子资源请求、中止解析到非公网 IP 的域名，防止 Chromium 解析器内发生 DNS rebinding。

业务类型检测

按skills/seo/SKILL.md的行业检测规则，从首页信号推断业务类型：

若检测到本地服务，会自动建议用户执行/seo local做更深层分析；若检测结果模糊，orchestrator 会列出置信度最高的两个类型并请用户确认，再继续行业特定的建议。

三、子代理编排：8 个固定 + 7 个条件触发

seo-audit 的核心价值在于把一次审计按专业领域切片并并行执行。固定参与的 8 个代理（对应agents/目录中的同名文件）及分工如下：

条件触发的 7 个代理及其触发条件如下表：

条件判断的源码实现

凭据检测脚本均是真实可执行文件：

• google_auth.py 支持--check（检查全部凭据）、--check gsc（检查单项）、--setup（展示配置指引）、--tier（显示检测到的凭据等级）与--auth --creds <client_secret.json>（OAuth 浏览器流程）。配置读取顺序为~/.config/claude-seo/google-api.json→ 环境变量回退，覆盖 PageSpeed Insights、CrUX、GSC、Indexing API、GA4 五类服务。
• backlinks_auth.py 管理 Moz Link Explorer、Bing Webmaster Tools 与 Common Crawl Web Graph 三类数据源，其中 Common Crawl 无需 API Key（"commoncrawl": "none"），这也是 seo-backlinks"始终包含 Common Crawl 域级指标"的原因。它还从 url_safety 强制导入 SSRF 校验，缺少该模块时直接拒绝运行。
• drift_history.py 从 SQLite 数据库（drift_baseline模块中的DB_PATH）查询指定 URL 的基线记录，返回baselines与comparisons数组；若数据库不存在则返回提示"先运行 drift baseline"。

仓库测试 test_audit_instructions.py 同时校验了所有 15 个代理的agents/*.md文件都必须声明output_dir与findings/输出契约，保证审计产物能被统一收集。

四、爬虫配置：边界与礼貌参数

原文档给出的爬取配置是默认执行的硬性边界：

Max pages: 500 Respect robots.txt: Yes Follow redirects: Yes (max 3 hops) Timeout per page: 30 seconds Concurrent requests: 5 Delay between requests: 1 second

解读这些参数的实际意义：

• 500 页上限配合并发 5 请求与 1 秒间隔，是"覆盖足够样本"与"不触发目标站点限流"之间的平衡点；
• 最多 3 跳重定向用于捕获 canonical 指向跳转页这类问题，同时避免跟随过深的跳转链；
• 遵守 robots.txt是硬性要求——若目标站点的 robots.txt 阻断爬取，审计不得绕过，只能记录被阻断的路径并如实汇报；
• 遇到 429 限流时，策略是退避并降低并发，然后在报告中注明哪些板块未能完成。

五、输出文件契约与审计数据信封

审计完成后，所有产物写入{domain}-audit/目录。原文档定义的输出结构为：

测试 test_audit_instructions.py 中的test_seo_audit_requires_persistent_artifacts断言了FULL-AUDIT-REPORT.md、ACTION-PLAN.md、audit-data.json、findings/、screenshots/与{domain}-audit目录约定全部出现在 SKILL.md 中，说明这是一条被测试锁定的持久化契约，而不是可选项。

audit-data.json：可离线驱动的报告信封

audit-data.json被设计为"即使 Google API 数据不可用也能生成报告"的完整信封，其结构如下（完整继承自原文档）：

{ "summary": { "health_score": 0, "business_type": "detected type", "top_findings": [], "quick_wins": [] }, "categories": [ { "name": "Technical SEO", "score": 0, "what_works": [], "findings": [ { "title": "Finding title", "severity": "Critical|High|Medium|Low|Info", "description": "Evidence-backed detail", "recommendation": "Specific fix" } ] } ], "action_plan": { "phases": [ {"name": "Phase 1: Critical Fixes", "timeframe": "Week 1", "items": []}, {"name": "Phase 2: High-Impact Improvements", "timeframe": "Weeks 2-3", "items": []}, {"name": "Phase 3: Content & Authority", "timeframe": "Month 2", "items": []}, {"name": "Phase 4: Monitoring & Iteration", "timeframe": "Ongoing", "items": []} ] }, "artifacts": { "findings_dir": "findings/", "screenshots_dir": "screenshots/" } }

四个顶层字段各有用途：summary承载健康分与业务类型、categories以分类为单位的评分与发现明细、action_plan的四阶段实施路线（含时间框）、artifacts告诉报告生成器去哪找附加产物。测试 test_google_report_full_audit.py 展示了该信封的真实消费方式——它构造了包含health_score: 82、分类发现（如 "Canonical mismatch" 的 Critical 问题）与四阶段 action_plan 的数据，调用google_report.generate_report("full", data, "example.com", tmp_path, output_format="html")并断言 HTML 中包含了 summary、categories 与 roadmap 区块。

六、SEO 健康评分：权重与优先级语义

评分权重

七个分类按权重聚合为 0-100 的健康分：

值得注意的是 Content Quality（23%）与 Technical SEO（22%）合计近半，且"AI Search Readiness"作为一个独立分类存在——这与 claude-seo 面向 AI 搜索（GEO/AEO）的整体定位一致。

优先级定义

在 orchestrator 的合成方法论中，这四个优先级桶是 VALIDATE 阶段的输出而非替代品：每条建议都应携带其依赖的首因观察（THINK）、与其他建议的依赖/解锁关系（CONNECT-system）、可证伪的验收检查（ACCEPT）以及无需重跑审计即可监测的前瞻指标（GROW）。

与 CWV 指标版本相关的质量门槛

skills/seo/SKILL.md的质量门槛部分与 seo-audit 的 performance 分类直接相关：

• 所有 Core Web Vitals 引用一律使用INP，绝不使用 FID（INP 于 2024-03-12 取代 FID，FID 已于 2024-09-09 从 Chrome 各工具中完全移除）；seo-technical 代理 中的阈值表即以此为基准：LCP Good <2.5s、INP Good <200ms、CLS Good <0.1；
• 不建议推荐 HowTo schema（2023 年 9 月废弃）；
• FAQPage 在 2026-05-07 后不再获得 Google 富结果展示，仅按其 AI/LLM 引用价值以 Info 级别标记，不推荐移除也不推荐为新页面新增。

七、报告结构：从执行摘要到分项明细

FULL-AUDIT-REPORT.md的报告骨架（完整继承自原文档）包含以下板块：

Executive Summary

• 总体 SEO 健康分（0-100）
• 检测到的业务类型
• Top 5 关键问题
• Top 5 快速制胜点

Technical SEO

• 可抓取性问题
• 可索引性问题
• 安全关注点
• Core Web Vitals 状态

Content Quality

• E-E-A-T 评估
• 内容稀薄页面
• 重复内容问题
• 可读性评分

On-Page SEO

• 标题标签问题
• Meta 描述问题
• 标题结构
• 内链缺口

Schema & Structured Data

• 现有实现
• 校验错误
• 缺失的机会

Performance

• LCP、INP、CLS 得分
• 资源优化需求
• 第三方脚本影响

Images

• 缺失 alt 文本
• 超大图片
• 格式建议

AI Search Readiness

• 可引用性评分
• 结构性改进
• 权威信号

八、PDF 报告：一条命令完成企业级交付

审计完成后，seo-audit 强烈建议生成 PDF 报告。生成命令（继承自原文档）：

python3 scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain <domain> --output-dir {domain}-audit/

该命令读取审计信封，产出一份白色封面的 A4 企业级报告，包含目录、执行摘要、图表（Lighthouse 仪表盘、查询条形图、索引环形图）、指标卡片、阈值表、带工作量估算的优先级建议以及实施路线图。

从 google_report.py 源码可以看到该命令的实现细节：

• 模块文档给出了四种报告类型：cwv-audit、gsc-performance、indexation与full，其中full即全站审计模式；
• 报告依赖matplotlib（Agg 后端绘图）与weasyprint（HTML → PDF 渲染），缺失依赖时脚本会明确提示安装命令；
• 图表着色遵循 Lighthouse 风格阈值：分数 ≥90 绿色、50-89 琥珀、<50 红色（_score_color）；
• 渲染流程在generate_report()中按类型组装章节，full类型会调用_build_executive_summary生成执行摘要，并从action_plan.phases（或兼容的roadmap字段）展开roadmap-phase区块。

测试 test_google_report_full_audit.py 验证了即使数据完全来自 seo-audit 而非 Google API（"full audit report generation from non-Google audit data"），HTML 输出仍包含 summary、categories 与 roadmap，这正是 audit-data.json 信封设计的价值。

九、可选增强：DataForSEO 与 Google API 集成

DataForSEO 集成（可选）：若 DataForSEO MCP 工具可用，seo-audit 会额外启动 seo-dataforseo 代理，为审计注入真实 SERP 排名、含垃圾评分的反链画像、on-page 分析（Lighthouse）、商家列表与 AI 可见性检查（ChatGPT 抓取、LLM 提及）。其成本分级可参考 cost-tiers。

Google API 集成（可选）：若python3 scripts/google_auth.py --check检测到凭据，则启动 seo-google 代理，把实验室估算替换为真实字段数据：

• CrUX Core Web Vitals（替代仅实验室估算）；
• GSC URL 索引状态；
• 搜索表现（点击、展示、CTR）；
• GA4 自然流量趋势。

其中 Performance（CWV）分类的评分受益最大，因为 CrUX 字段数据反映了真实用户在真实网络环境下的体验分布，而非单机 Lighthouse 快照。

十、错误处理矩阵

原文档定义的四类故障场景及处置方式，是审计执行时的兜底策略：

orchestrator 层面还有两条补充规则：子技能在审计中失败时，报告其他子技能的成功结果并明确指出失败项及原因，建议单独重跑失败子技能；业务类型检测模糊时，列出置信度最高的两个类型并请求用户确认后再继续。

十一、落地实践建议

结合仓库内容，给出几条可直接操作的实践指引：

1. 先确认环境：render_page.py的 rendered 模式需要pip install -r requirements.txt && playwright install chromium；google_report.py需要 matplotlib 与 weasyprint；
2. 从审计信封驱动报告：即使没有配置任何付费 API，只要按第六节结构产出audit-data.json，--type full报告就能完整生成——这是{domain}-audit/目录的核心价值；
3. 按需开启条件代理：在本地服务站点上配置 DataForSEO MCP 可同时解锁 seo-maps 的网格排名追踪与地理竞对半径映射；在拥有 Google 凭据的站点上，CrUX 字段数据会显著提升 Performance 分类的评分可信度；
4. 用测试锁定契约：仓库中 test_audit_instructions.py 展示了如何用静态断言守护"流程必须以 render_page.py 开头、产物必须持久化、代理必须声明输出目录"等不变量，防止技能文档在演进中退化。

seo-audit 的完整技能定义位于 skills/seo-audit/SKILL.md，其编排入口与合成方法论见 skills/seo/SKILL.md，底层渲染与报告实现分别位于 scripts/render_page.py 与 scripts/google_report.py，测试证据集中在 tests/test_audit_instructions.py 与 tests/test_google_report_full_audit.py，可循此路径深入阅读源码。