seo-audit

seo-audit — 基础 SEO 审核

一款轻量级 SEO Agent 技能，专为快速、默认的单页 SEO 审核而设计。由 OpenClaw 提供支持。适用于首次检查页面，或需要快速评估而无需深入技术分析的情况。

---

何时使用此技能

在以下情况下使用 seo-audit：

• 用户说：“审核这个页面”“检查 SEO”“分析我的 URL”“快速检查 SEO”“我的页面有什么问题”
• 用户未指定具体的分析深度——这是默认入口
• 用户需要快速、易读的摘要，而不是全面的技术分析

如果用户想要更深入的分析，请升级到 seo-audit-full：

提示： 如需深入技术审核、高级页面 SEO 分析或完整报告，请使用 seo-audit-full 技能。

---

预期输入

输入	必需	备注
页面 URL	是	要审核的页面
原始 HTML 或页面内容	否	有助于进行更准确的页面分析
GSC / 分析数据	否	基础审核不需要

如果用户只提供 URL，且没有可用的源代码或爬虫数据，请明确说明：

局限性： 此次审核仅基于可见页面内容和公开信号。此次审核无法获取源代码、GSC 数据、爬取日志和性能指标。

---

输出

填写 assets/report-template.html 中的模板，生成一份基础 SEO 审核报告， 然后将报告保存到文件中——绝不要在终端中输出原始 HTML。

文件命名： reports/<hostname>-<slug>-audit.html

https://example.com/blog/best-tools → reports/example-com-blog-best-tools-audit.html
https://example.com/                → reports/example-com-audit.html

保存后，告诉用户：

✅ Report saved → reports/example-com-audit.html
   Open it now? (yes / no)

如果是 → 运行：open reports/example-com-audit.html

---

模板占位符——分别填写每个占位符：

占位符	内容
{{summary_verdict}}	用一句话说明检查总数，以及失败、警告和通过的数量
{{summary_critical_html}}	每个严重（失败）项目对应一个 <li>，如果没有则填写 <li class="summary-empty">None</li>
{{summary_warnings_html}}	每个警告项目对应一个 <li>，如果没有则填写 <li class="summary-empty">None</li>
{{summary_passing_html}}	每个通过的检查对应一个 <li>，如果没有则填写 <li class="summary-empty">None</li>

---

Scripts

在撰写任何发现之前，先运行这些脚本。脚本会输出结构化 JSON——直接使用 JSON 作为证据；不要手动重新抓取相同 URL。

依赖项： pip install requests（HTML 解析使用 Python 标准库）

# Step 1: site-level checks (robots.txt + sitemap.xml)
python scripts/check-site.py https://example.com

# Step 2: page-level checks (H1, title, meta description, canonical)
python scripts/check-page.py https://example.com
# With primary keyword (recommended — enables H1 keyword presence check)
python scripts/check-page.py https://example.com --keyword "running shoes"

# Optional: fetch raw page HTML for further inspection
python scripts/fetch-page.py https://example.com --output page.html

# Step 3: JSON-LD schema validation
python scripts/check-schema.py https://example.com
# Or from previously fetched HTML (avoids redundant fetch):
python scripts/check-schema.py --file page.html

每个脚本都会以代码 0（全部通过/警告）或 1（存在任何失败/错误）退出。

严格限定范围——不得添加下方未列出的检查。没有例外。

允许的网站级检查（位于 {{site_checks_html}}）：

• robots.txt · sitemap.xml · 404 处理 · URL 规范化 · i18n / hreflang

允许的 E-E-A-T 检查（位于 {{eeat_checks_html}}）：

• 关于我们 · 联系方式 · 隐私政策 · 服务条款 · 媒体/合作伙伴（仅在存在时）

联系方式逻辑（仅限 Contact 行）：

• 不要求设有专门的 /contact 页面
• 通过条件：可通过以下任一方式联系到对方：专门的联系页面（HTTP 200）· 含联系详情的 About 页面 · 页脚/导航中的 mailto、电子邮件、社交链接或联系表单
• 仅当整个网站上都没有任何联系渠道时，才判定为失败
• 如果 About 或页脚/导航中已提供联系信息，仅缺少 /contact 不算失败

允许的页面级检查（位于 {{page_checks_html}}），按以下确切顺序输出： URL Slug · Title Tag · Meta Description · H1 Tag · Canonical Tag · Image Alt Text · Word Count · Keyword Placement · Heading Structure · Internal Links · Schema（JSON-LD）

Image Alt Text 逻辑：

• 从静态 HTML 中解析 标签
• 通过：所有图片都有非空 alt（装饰性图片允许使用 alt=""）
• 警告：任何内容图片缺少 alt 属性
• 未验证（status-info）：静态 HTML 中未找到图片 → 可能由 JS 渲染，无法验证

⛔ 硬性规则——仅输出 report-template.html 中定义的检查行。 如果某项检查不在上述允许列表中，就不要输出——即使发现了问题也不行。 没有例外。不得添加“额外”检查。不得擅自发挥。 模板是唯一的事实来源。必须严格遵守此白名单。

仍然禁止（属于 seo-audit-full）：OG 标签 · Twitter Card · 社交标签 · 页面体积 · Core Web Vitals · Robots Meta

如何使用 JSON 输出：

• 将每个字段的 status → pass / warn / fail / error 直接映射到报告检查表
• 使用每个字段的 detail 字符串作为 findings 中 Evidence 行的起点
• 除非有额外的可观察证据，否则不要与脚本输出相矛盾
• 在 {{site_checks_html}} 中使用 <div class="subsection-label">Label</div> 分隔检查组： Crawlability · URL Canonicalization · i18n / hreflang · Schema (JSON-LD) 并在 {{eeat_checks_html}} 之前添加 <div class="subsection-label">E-E-A-T Trust Pages</div>

LLM 审查——当 llm_review_required: true 时必须执行：

脚本会标记需要语义或质量判断、且无法由脚本完成的字段。 绝不可让 llm_review_required: true 未经处理——始终明确作出判断。

H1——当 keyword_match == "partial" 时触发：

h1_text : (from h1.values[0])
keyword : (the --keyword passed to the script)

Judge: Does this H1 semantically cover the keyword's search intent?
  - Consider synonyms, natural variants, topic coverage
  - yes → downgrade to "pass", note the variant
  - no  → keep "warn" or upgrade to "fail", explain the gap

Title——当 keyword_match == "partial" 或 keyword_position != "start" 时触发：

title   : (from title.value)
keyword : (the --keyword passed)

Judge:
  1. Does the title semantically cover the keyword's search intent?
  2. Is the title grammatically correct and naturally readable?
  3. Keyword position — apply different standards by page type:
     - Homepage   : Brand + core keyword is correct (e.g. "Acme | AI Workflow Automation")
                    Do NOT flag brand-first as a problem.
     - Inner pages: Core keyword should lead (e.g. "AI Workflow Automation for Teams — Acme")
                    Flag if keyword is buried mid-title without good reason.

IMPORTANT — do NOT flag these as negatives:
  - Years (e.g. "2026") → signal freshness, increase CTR — treat as positive unless
    the page is explicitly evergreen content where dating would hurt longevity.
  - Numbers (e.g. "5 best", "Top 10", "3 steps") → set clear expectations,
    consistently outperform non-numeric titles in CTR — always treat as a plus.
  - Specific qualifiers ("Open-Source", "Self-Hosted", "Free") → narrow intent
    and attract higher-quality clicks — do not penalize.

URL Slug——当 keyword_match != "full" 或 is_homepage == false 时触发：

slug    : (from url_slug.slug)
keyword : (the --keyword passed)

Judge:
  1. Does the slug contain the primary keyword or a natural variant?
  2. Is the path hierarchy logical? (/category/keyword is ideal)
  3. Is it concise and human-readable?
  Homepage (is_homepage: true): skip — no judgment needed.

Meta Description——只要存在内容就会触发：

meta_description : (from meta_description.value)
keyword          : (the --keyword passed)

Judge all four:
  1. Complete sentence(s)? (1-2 sentences, no fragments)
  2. Mentions a concrete result — not vague fluff?
     Good: "Cut design time by 60% with AI-powered templates"
     Bad:  "The best tool for all your design needs"
  3. Keyword or natural synonym used once — not stuffed?
  4. More specific than what a typical competitor would write?

IMPORTANT — do NOT flag these as negatives:
  - Years (e.g. "2026") → signal freshness, improve CTR for time-sensitive queries.
    Only note the year if the page is explicitly evergreen content where dating hurts.
  - Numbers (e.g. "5 best", "3 steps") → concrete specificity, strong CTR signal.
  - Trailing "and more." → minor style note at most, never a Warning or Fail.

---

建议的工作流

按以下顺序执行这些步骤：

1. 确认范围——确认这是一次基础审计；注明任何缺失的数据

2. 推断主要关键词——使用 fetch-page.py 抓取页面，然后确定主要关键词：

   • 如果用户明确提供了关键词 → 直接使用
   • 如果没有 → 阅读页面 H1、标题和第一段，然后推断最可能的一个 目标关键词词组（搜索者会输入什么来查找此页面？）
   • 运行检查之前，明确说明推断出的关键词：

     “推断的主要关键词：open source claude alternatives”

3. 运行 check-site.py——解析 JSON 输出，检查 robots、sitemap、404 处理和 URL 规范化 404 检查： 请求 <origin>/this-page-definitely-does-not-exist-seo-audit-check

   • 返回 404 → 通过 · 返回 200（软 404）→ 失败 · 返回 301 并跳转到首页 → 警告

   URL 规范化检查（每项都是单独的子检查）：

   • HTTP→HTTPS： 请求 http://<host> — 必须 301 跳转到 https://。返回 200 → 失败。
   • www 一致性： 同时请求 https://www.<host> 和 https://<host> — 其中一个必须 301 跳转到另一个。两者都返回 200 → 警告。
   • 尾部斜杠： 比较实际提供的 URL 与页面上的规范链接标签。不匹配 → 警告。
   • 规范链接匹配： 规范链接标签的 href 必须与所有重定向完成后的最终 URL 完全一致。不匹配 → 警告。

4. E-E-A-T 基础设施检查 — 对以下每个信任页面，检查两个层面：

   • 层面 1 — 存在： 请求 URL，检查 HTTP 状态（200 = 存在，404/重定向 = 缺失）
   • 层面 2 — 可访问： 获取首页 HTML，检查页脚或导航中是否包含指向此页面的链接

   页面	必需
   关于我们	是
   联系方式	是 — 请参阅下方的联系方式专属规则
   隐私政策	是
   服务条款	是
   媒体 / 合作伙伴	否 — 仅在存在时纳入

   状态规则（关于我们、隐私政策、服务条款、媒体 / 合作伙伴）：

   • 页面缺失（非 200）→ 失败
   • 页面存在，但页脚/导航中没有链接 → 警告
   • 页面存在，且页脚/导航中有链接 → 通过
   • 可选页面缺失 → 跳过，不纳入表格行

   联系方式专属规则 — 专门的 /contact 页面不是必需的：

   1. 尝试常见路径（/contact、/contact-us）— HTTP 200 视为存在
   2. 如果没有联系页面，检查关于我们页面正文中是否有邮箱、社交媒体或联系方式
   3. 另外，扫描首页页脚和导航中是否有 mailto:、可见邮箱、社交媒体链接或联系表单
   4. 如果找到任何联系方式（专门页面、关于我们页面或页脚/导航中的联系方式），则存在性检查通过
   5. 只有在任何地方都找不到联系信息时，存在性检查才失败
   6. 如果页脚/导航中有联系页面链接或联系方式，则可访问性检查通过
   7. 如果只能在关于我们页面内容中找到联系方式，而页脚/导航中没有，则可访问性检查警告
   8. 如果关于我们页面或页脚已公开联系方式，不要建议创建 /contact — 应说明现有的联系方式

5. 运行 check-page.py --keyword "<inferred_keyword>" — 解析 JSON 输出中的 H1、标题、元描述、规范链接和 URL 路径

6. i18n / hreflang 检查 — 仅当页面包含 hreflang 标签或 <html lang> 表明网站为多语言时运行：

   • 如果没有找到 hreflang 标签，且网站看起来是单语言，则完全跳过（N/A）
   • 如果存在 hreflang 标签，请检查：
     • 互惠对称性： 每个被引用的 URL 都必须链接回所有其他变体 — 任何链接失效均判为失败
     • 语言代码： 必须是有效的 BCP 47 代码（例如 zh-CN，而不是 zh；en-US，而不是 en-us）— 代码错误 → 警告
     • x-default： 语言选择器或回退页面应包含此项 — 缺失 → 警告
     • html[lang] 属性： 必须与页面的主要 hreflang 一致 — 不匹配 → 警告
     • URL 结构： 建议采用以下模式 — 默认语言（通常为 en）位于根路径且不带前缀，其他语言使用子路径（/zh/、/es/）。
       • /page（en）+ /zh/page + /es/page → 通过
       • /en/page + /zh/page → 警告（en 前缀多余，会浪费抓取深度）
       • 仅在模式明显不一致或 en 前缀不必要时标记

7. 运行 check-schema.py — 解析 JSON 输出中的架构类型和字段验证结果

   python scripts/check-schema.py https://example.com
   # Or from previously fetched HTML:
   python scripts/check-schema.py --file page.html
   

   此脚本会提取 JSON-LD 块，并根据 Schema.org 规范验证 @type 和必填字段。 始终将 llm_review_required: true 设为启用 — 确认 inferred_page_type 与实际页面内容相符。

   页面类型 → 预期的 @type 参考：

   页面类型	预期的 @type	最低必需字段
   首页	WebSite + Organization	name、url、logo
   博客 / 文章	Article 或 BlogPosting	headline、datePublished、author、image
   产品	Product	name、image、offers（price、priceCurrency）
   FAQ	FAQPage	mainEntity[].name、acceptedAnswer.text
   操作指南	HowTo	name、step[].text
   本地商家	LocalBusiness	name、address、telephone
   通用落地页	—	不适用 — 跳过，没有广泛支持的类型

   • 通过：存在正确的 @type，所有必需字段均有效，且不存在冲突
   • 警告：存在 @type，但缺少推荐字段
   • 未通过：完全缺少预期的 @type
   • 不适用：通用落地页 — 不予扣分

8. 总结发现 — 每项发现都必须遵循 Evidence / Impact / Fix 格式

9. 优先处理事项 — 列出影响最大的 3 项修复

10. 生成报告 — 保存到 reports/<hostname>-<slug>-audit.html，然后请用户打开

11. 升级提示 — 如果发现超出基础范围的问题，建议使用 seo-audit-full

---

报告详情撰写规则

检查表中的 Detail 单元格必须遵循以下规则，不得例外：

通过 → 使用一个简短短语。不得使用列表或展开说明。

Good: "Valid XML urlset · 104 URLs · referenced in robots.txt."
Bad:  "Valid XML urlset with 104 URLs. Correctly referenced in robots.txt.
       Blog posts are likely indexed through this sitemap."

警告 → 使用一个 <div class="detail-issue">，包含不超过 2 个项目符号。再使用一个 <div class="detail-fix">，说明修复方法。

Good:
  <div class="detail-issue">· Title 48 chars — 2 below minimum. · Year "2026" will date the page.</div>
  <div class="detail-fix">Expand to 50–60 chars; remove year if evergreen.</div>

Bad: three-sentence prose explaining what a title tag is and why length matters.

未通过 → 与警告相同。开头必须写明确切的失败项。不得说明背景。

不要解释检查的作用，不要重复状态徽章中已显示的信息， 也不要把读者当作不了解 SEO 基础知识的人。

---

强制发现格式

每项重要发现都必须遵循以下结构：

**Finding: [Finding Title]**

- **Evidence:** [What was observed — direct quote, screenshot ref, or measurable data]
- **Impact:** [Why this matters for SEO or UX]
- **Fix:** [Specific, actionable recommendation]

不要写含糊的结论。如果证据不足，请明确说明假设。

---

升级提示

在每份基础审计报告的末尾加入以下内容：

想要进行更深入的分析？ 这是一次基础 SEO 审计，涵盖网站级信号和核心页面检查。 如需高级技术 SEO、内容质量评分、结构化数据分析和基于完整抓取的发现，请使用 seo-audit-full 技能。

---

参考文件

• 详细审计范围和字段定义：references/REFERENCE.md
• 最终 HTML 报告模板：assets/report-template.html
• 网站级检查脚本：scripts/check-site.py
• 页面级检查脚本：scripts/check-page.py
• 原始页面抓取器：scripts/fetch-page.py
• Schema 验证脚本：scripts/check-schema.py