astro-seo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro SEO

Audits and improves the SEO setup of an Astro site against the full stack described in Astro SEO: the definitive guide. The skill covers nine areas — technical foundation, structured data, content, site structure, performance, sitemaps and indexing, agent discovery, redirects, and analytics — and produces drop-in code for anything missing or weak.

The opinionated spine of this skill is

@jdevalk/astro-seo-graph

. Most of the fixes route through it. If the project doesn't use it yet, installing it is the first recommendation.

Code recipes live in
AGENTS.md
— read it when you need to implement a specific fix. This file has the workflow and audit checklist.

根据《Astro SEO：权威指南》（https://joost.blog/astro-seo-complete-guide/）中描述的完整体系，审核并优化Astro站点的SEO配置。本工具涵盖九大领域——技术基础、结构化数据、内容、站点结构、性能、站点地图与索引、Agent发现、重定向和分析，并针对缺失或薄弱环节生成可直接嵌入的代码。

本工具的核心依赖是

@jdevalk/astro-seo-graph

。大多数修复方案都基于该包实现。如果项目尚未安装该包，第一步就是建议安装它。

代码示例位于
AGENTS.md
——当你需要实现特定修复时请查阅该文件。本文件包含工作流程和审核清单。

Workflow

工作流程

Detect the project — confirm this is an Astro site and understand its shape.
Audit — score nine categories and produce actionable findings.
Improve — generate or modify files to close the gaps. Recipes are in
```
AGENTS.md
```
.
Metadata pass — invoke
```
metadata-check
```
on every short string the skill generated (titles, descriptions, schema
```
description
```
fields, FAQ answers, frontmatter excerpts).
Verify — run the build, check validations pass, remind the user about non-file tasks (Search Console, Bing Webmaster Tools, IndexNow key verification).

项目检测 — 确认这是一个Astro站点并了解其结构。
审核 — 对九个类别进行评分，并生成可执行的检测结果。
优化 — 生成或修改文件以填补漏洞。具体示例见
```
AGENTS.md
```
。
元数据校验 — 对本工具生成的所有短字符串（标题、描述、Schema
```
description
```
字段、FAQ答案、前置内容摘要）调用
```
metadata-check
```
工具。
验证 — 执行构建，检查验证是否通过，提醒用户完成非文件类任务（Search Console、Bing Webmaster Tools、IndexNow密钥验证）。

Phase 0: Detect the project

阶段0：项目检测

Confirm the basics before auditing:

```
astro.config.mjs
```
/
```
astro.config.ts
```
exists.
```
package.json
```
has
```
astro
```
as a dependency.
site:
is set in
astro.config
— canonicals, sitemaps, and OG image URLs all derive from this. If it's missing, empty, or
```
http://localhost
```
, flag it as a blocking issue before anything else. This is the single most common misconfiguration.
Content collections in
```
src/content/
```
(or legacy
```
src/pages/
```
markdown).
Deployment target — read
```
package.json
```
,
```
vercel.json
```
,
```
netlify.toml
```
,
```
wrangler.toml
```
, or
```
public/_headers
```
to determine the host. This drives redirect and header syntax in Phase 2.
Is
@jdevalk/astro-seo-graph
already installed? If yes, record the version and which features are wired (grep for
```
<Seo
```
,
```
seoGraph(
```
,
```
createSchemaEndpoint
```
,
```
createSchemaMap
```
,
```
FuzzyRedirect
```
,
```
createIndexNowKeyRoute
```
,
```
createMarkdownEndpoint
```
,
```
createApiCatalog
```
,
```
gitLastmod
```
). Check the installed version against the latest on npm with
```
npm view @jdevalk/astro-seo-graph version
```
. If the project is behind, recommend an upgrade in Phase 2 before auditing feature gaps — the package ships new defaults and fixes regularly, and an outdated version is a plausible cause for any audit finding. Phase 2 branches on this.
Is the site multilingual? Check for
```
i18n
```
in
```
astro.config
```
or multiple locale directories under
```
src/content/
```
. If yes, hreflang matters; if no, skip it.

Ask only what you can't detect. Don't ask the user what the site is about — read

astro.config.mjs

and the homepage content.

审核前先确认基础信息：

存在
```
astro.config.mjs
```
/
```
astro.config.ts
```
文件。
```
package.json
```
中包含
```
astro
```
依赖。
astro.config
中已设置
site:
— 规范URL、站点地图和OG图片URL均由此派生。如果缺失、为空或设为
```
http://localhost
```
，需将其标记为阻塞问题优先处理。这是最常见的配置错误。
```
src/content/
```
中存在内容集合（或旧版
```
src/pages/
```
中的markdown文件）。
部署目标 — 读取
```
package.json
```
、
```
vercel.json
```
、
```
netlify.toml
```
、
```
wrangler.toml
```
或
```
public/_headers
```
以确定托管平台。这将决定阶段2中的重定向和头部语法。
是否已安装
@jdevalk/astro-seo-graph
？如果已安装，记录其版本及已启用的功能（搜索
```
<Seo
```
、
```
seoGraph(
```
、
```
createSchemaEndpoint
```
、
```
createSchemaMap
```
、
```
FuzzyRedirect
```
、
```
createIndexNowKeyRoute
```
、
```
createMarkdownEndpoint
```
、
```
createApiCatalog
```
、
```
gitLastmod
```
）。使用
npm view @jdevalk/astro-seo-graph version
检查已安装版本是否为npm上的最新版本。如果项目版本落后，在阶段2审核功能漏洞前建议先升级——该包会定期更新默认配置和修复问题，过时版本可能是审核发现问题的原因。阶段2会根据此结果分支处理。
站点是否为多语言？ 检查
```
astro.config
```
中是否有
```
i18n
```
配置，或
```
src/content/
```
下是否有多个语言环境目录。如果是，hreflang配置很重要；如果不是，则跳过。

仅询问无法自动检测的信息。不要询问用户站点的主题——直接读取

astro.config.mjs

和首页内容即可。

Phase 1: Audit

阶段1：审核

Score each category out of 10. For each, give 2–4 specific findings that quote the actual code or config. Within each category, checks are tiered:

Must — ship blockers. A failure here causes visible SEO regression.
Should — standard practice. Skipping costs reach.
Nice — forward-looking or situational. Useful but not baseline for every site.

Skip Nice checks for small personal blogs unless the user asks for the full treatment.

每个类别按10分制评分。每个类别需给出2-4个引用实际代码或配置的具体检测结果。每个类别内的检查分为三个层级：

必须 — 上线阻塞项。此处失败会导致明显的SEO倒退。
应该 — 标准实践。忽略会影响覆盖范围。
建议 — 前瞻性或场景化配置。有用但并非所有站点的基线要求。

对于小型个人博客，除非用户要求全面检查，否则跳过建议层级的检查。

<Seo>

component and head metadata (/10)

<Seo>

组件与头部元数据 (/10)

Must — single component for all head metadata (not scattered across layouts).
Must —
```
site:
```
in
```
astro.config
```
is set to the production origin.
Must — canonical URLs derived from
```
site
```
config with tracking params stripped.
Must — canonical omitted when
```
noindex
```
is true (per Google's recommendation).
Must — fallback chain for missing SEO fields:
```
seo.title → title → siteName
```
;
```
seo.description → excerpt → first paragraph
```
. Pages with blank titles or descriptions are the most common symptom of a broken fallback.

Should —

robots

meta includes

max-snippet:-1

max-image-preview:large

max-video-preview:-1

Should — Twitter tags suppressed when they duplicate Open Graph (Twitter falls back automatically).
Should —
```
hreflang
```
alternates present on multilingual sites. Skip if monolingual.
Nice — uses
```
@jdevalk/astro-seo-graph
```
's
```
<Seo>
```
component rather than hand-rolled. (Hand-rolled that covers everything above is fine; this skill nudges toward the package because it handles the fallback chain and robots rules by default.)

必须 — 使用单个组件管理所有头部元数据（而非分散在多个布局中）。
必须 —
```
astro.config
```
中的
```
site:
```
已设置为生产环境源地址。
必须 — 规范URL由
```
site
```
配置派生，并去除跟踪参数。
必须 — 当
```
noindex
```
为true时省略规范URL（遵循Google建议）。
必须 — 缺失SEO字段的回退链：
```
seo.title → title → siteName
```
；
```
seo.description → excerpt → 第一段内容
```
。页面标题或描述为空是回退链失效的最常见症状。

应该 —

robots

元标签包含

max-snippet:-1

、

max-image-preview:large

、

max-video-preview:-1

。

应该 — 当Twitter标签与Open Graph重复时禁用Twitter标签（Twitter会自动回退到Open Graph）。
应该 — 多语言站点包含
```
hreflang
```
替代链接。单语言站点跳过。
建议 — 使用
```
@jdevalk/astro-seo-graph
```
提供的
```
<Seo>
```
组件而非手动实现。（如果手动实现已覆盖上述所有要求也可；本工具倾向于使用该包，因为它默认处理回退链和robots规则。）

2. Structured data / JSON-LD graph (/10)

2. 结构化数据 / JSON-LD图谱 (/10)

Single flat
```
Article
```
object, or a linked
```
@graph
```
with multiple entities?
Entities wired with
```
@id
```
references?

WebSite

Blog

WebPage

Person

Organization

BlogPosting

Article

BreadcrumbList

ImageObject

all present where relevant?

Trust signals:

publishingPrinciples

copyrightHolder

copyrightYear

knowsAbout

SearchAction

Validates in Rich Results Test and ClassySchema?

使用单个扁平
```
Article
```
对象，还是包含多个实体的关联
```
@graph
```
？
实体是否通过
```
@id
```
引用关联？

3. Content collections and SEO schema (/10)

3. 内容集合与SEO Schema (/10)

Content collections defined with Zod schemas?
```
seoSchema
```
from
```
@jdevalk/astro-seo-graph
```
enforcing title (5–120) and description (15–160) lengths?
Required fields (
```
publishDate
```
,
```
title
```
,
```
excerpt
```
) enforced at build time?
Markdown-stripped
```
articleBody
```
exposed in schema endpoints (up to 10K chars)?

内容集合是否使用Zod Schema定义？
是否使用
```
@jdevalk/astro-seo-graph
```
的
```
seoSchema
```
强制标题（5-120字符）和描述（15-160字符）长度？
是否在构建时强制要求必填字段（
```
publishDate
```
、
```
title
```
、
```
excerpt
```
）？
Schema端点是否暴露去除Markdown格式的
```
articleBody
```
（最多10000字符）？

4. Open Graph images (/10)

4. Open Graph图片 (/10)

Every page has an OG image, or many missing?
1200×675 (Google Discover minimum 1200px wide, 16:9 ratio)?
Generated at build time via satori + sharp, or manual?
JPEG (social platforms don't reliably support WebP/AVIF)?
Route derives OG URL from the slug automatically?
Every
```
<img>
```
in rendered HTML has an
```
alt
```
attribute (or
```
alt=""
```
/
```
role="presentation"
```
for decorative images)?
```
validateImageAlt
```
on
```
seoGraph()
```
catches this at build time in ≥ 1.1.0.

是否每个页面都有OG图片，还是大量缺失？
尺寸是否为1200×675（Google Discover要求最小宽度1200px，16:9比例）？
是否在构建时通过satori + sharp生成，还是手动制作？
是否为JPEG格式（社交平台无法可靠支持WebP/AVIF）？
是否自动根据slug派生OG图片URL？
渲染后的HTML中每个
```
<img>
```
是否都有
```
alt
```
属性（装饰性图片使用
```
alt=""
```
/
```
role="presentation"
```
）？
```
seoGraph()
```
中的
```
validateImageAlt
```
在≥1.1.0版本中会在构建时检测此问题。

5. Sitemaps and indexing (/10)

5. 站点地图与索引 (/10)

Must —
```
@astrojs/sitemap
```
installed, sitemap index reachable.
Must —
```
robots.txt
```
references the sitemap index.
Must — RSS feed exists (
```
@astrojs/rss
```
), advertised via
```
<link rel="alternate" type="application/rss+xml">
```
, contains full post content (not truncated excerpts).
Should — split per-collection via
```
chunks
```
option (
```
sitemap-posts-0.xml
```
, etc.) — much easier to debug indexing in GSC.
Should —
```
lastmod
```
populated from git commit timestamps, not frontmatter dates or CI file timestamps.
```
@jdevalk/astro-seo-graph
```
≥ 1.4.0 exports
```
gitLastmod(filePath, { excludeCommits, depth })
```
for this — it returns the committer date of the most recent non-excluded commit that touched the file, or
```
null
```
if git is unavailable. Wire it into the sitemap
```
serialize
```
callback. If the codebase has a hand-rolled
```
execSync('git log ...')
```
helper, replace it with the package export — the export handles bulk-commit exclusion (imports, reformats) which a naïve
```
-1
```
lookup can't.
Should — IndexNow integrated and submitting on each build, with key verification route at
```
/[key].txt
```
. ≥ 1.0.1 excludes
```
/404
```
from submissions by default. Gate submission on the production host (e.g.
```
process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main'
```
,
```
VERCEL_ENV === 'production'
```
,
```
CONTEXT === 'production'
```
). Unconditional submission pings the endpoint on every local
```
npm run build
```
and preview deploy with URLs the production host hasn't served yet, which gets the key marked invalid (403) and forces rotation.

必须 — 已安装
```
@astrojs/sitemap
```
，站点地图索引可访问。
必须 —
```
robots.txt
```
引用站点地图索引。
必须 — 存在RSS订阅源（
```
@astrojs/rss
```
），通过
```
<link rel="alternate" type="application/rss+xml">
```
声明，包含完整文章内容（而非截断摘要）。
应该 — 通过
```
chunks
```
选项按集合拆分（如
```
sitemap-posts-0.xml
```
等）——在GSC中调试索引问题会更简单。
应该 —
```
lastmod
```
从git提交时间戳获取，而非前置内容日期或CI文件时间戳。
```
@jdevalk/astro-seo-graph
```
≥1.4.0版本导出
```
gitLastmod(filePath, { excludeCommits, depth })
```
用于此功能——它返回最近一次非排除提交的提交者日期，如果git不可用则返回
```
null
```
。将其接入站点地图的
```
serialize
```
回调。如果代码库中有手动实现的
```
execSync('git log ...')
```
工具，替换为该包的导出函数——该导出函数可批量排除提交（如导入、格式化），而简单的
```
-1
```
查询无法实现此功能。
应该 — 集成IndexNow并在每次构建时提交，在
```
/[key].txt
```
处设置密钥验证路由。≥1.0.1版本默认排除
```
/404
```
页面的提交。仅在生产环境触发提交（例如
```
process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main'
```
、
```
VERCEL_ENV === 'production'
```
、
```
CONTEXT === 'production'
```
）。无条件提交会在每次本地
```
npm run build
```
和预览部署时向端点发送请求，而这些URL尚未在生产环境上线，会导致密钥被标记为无效（403）并需要轮换。

6. Agent discovery (/10)

6. Agent发现 (/10)

Should — schema endpoints (
```
/schema/*.json
```
) exposing corpus-wide JSON-LD.
Should — schema map (
```
/schemamap.xml
```
) listing all endpoints, with
```
Schemamap:
```
directive in
```
robots.txt
```
.
Should —
```
llms.txt
```
at the site root listing pages (title + description) for LLM consumers.
```
@jdevalk/astro-seo-graph
```
≥ 0.9.0 generates this via the
```
llmsTxt
```
integration option.
Should — markdown-alternate URLs (
```
/blog/post.md
```
next to
```
/blog/post/
```
) serving clean markdown with YAML frontmatter for AI agents to consume without HTML parsing.
```
@jdevalk/astro-seo-graph
```
≥ 1.2.0 ships
```
createMarkdownEndpoint
```
for the route and a
```
markdownAlternate: true
```
integration option that emits
```
<link rel="alternate" type="text/markdown">
```
on every page. ≥ 1.3.0 adds post-build verification: the integration walks the build output and strips any link whose
```
.md
```
target isn't on disk (with a
```
warn
```
per occurrence) — so a misconfigured endpoint surfaces as a build warning instead of a shipped 404. Pair with a Cloudflare Transform Rule (URL rewrite via
```
wildcard_replace
```
, no
```
Vary: Accept
```
header — CF strips custom Vary values) for content negotiation on
```
Accept: text/markdown
```
without needing SSR.
Should — API catalog at
```
/.well-known/api-catalog
```
per RFC 9727.
```
@jdevalk/astro-seo-graph
```
≥ 1.4.0 ships
```
createApiCatalog
```
, which auto-types schema endpoints to their
```
https://schema.org/<Type>
```
URLs and absolutizes paths against
```
siteUrl
```
. List the schema endpoints, schemamap, and any site-specific APIs (
```
/ask
```
,
```
/feed.xml
```
, etc.). The RFC is finalized so the format is stable; adoption is early but the cost is one route file.
Should — Content Signals directive in
```
robots.txt
```
(e.g.
```
Content-Signal: ai-train=yes, search=yes, ai-input=yes
```
). Declares preferences for AI training, search grounding, and AI input use independently of crawl access. The spec is an IETF draft and adoption is early, but it's one line in a file every site already has.
Should —
```
Link
```
header on
```
/*
```
pointing to discovery files (sitemap, llms.txt, api-catalog, schemamap, and any MCP / A2A cards the site publishes). Agents reading response headers find them without parsing HTML. On Cloudflare Pages / Netlify this is
```
public/_headers
```
; on Vercel it's
```
vercel.json
```
.
Nice — MCP server card at
```
/.well-known/mcp/server-card.json
```
(SEP-1649) and / or A2A agent card at
```
/.well-known/agent-card.json
```
(A2A protocol). Only relevant when the site actually exposes an MCP server or A2A agent. Both are static JSON files declaring the endpoint, capabilities, and skills. Skip otherwise.
Nice —
```
<link rel="nlweb">
```
pointing to a conversational endpoint. NLWeb is early; the tag is one line and worth having, but it's not a scoring blocker in 2026.

应该 — 提供Schema端点（
```
/schema/*.json
```
）暴露全站JSON-LD数据。
应该 — 提供Schema映射（
```
/schemamap.xml
```
）列出所有端点，并在
```
robots.txt
```
中添加
```
Schemamap:
```
指令。
应该 — 在站点根目录放置
```
llms.txt
```
，列出供LLM消费的页面（标题+描述）。
```
@jdevalk/astro-seo-graph
```
≥0.9.0版本可通过
```
llmsTxt
```
集成选项生成该文件。
应该 — 提供Markdown替代URL（
```
/blog/post.md
```
与
```
/blog/post/
```
并存），提供带有YAML前置内容的纯净Markdown，供AI Agent无需解析HTML即可消费。
```
@jdevalk/astro-seo-graph
```
≥1.2.0版本提供
```
createMarkdownEndpoint
```
用于创建该路由，并提供
```
markdownAlternate: true
```
集成选项，在每个页面添加
```
<link rel="alternate" type="text/markdown">
```
标签。≥1.3.0版本添加了构建后验证：集成工具会遍历构建输出，删除目标
```
.md
```
文件不存在的链接（每个缺失链接会发出
```
warn
```
警告）——这样配置错误的端点会在构建时发出警告，而非上线后出现404错误。可配合Cloudflare转换规则（通过
```
wildcard_replace
```
重写URL，无需
```
Vary: Accept
```
头——CF会移除自定义Vary值），在无需SSR的情况下实现
```
Accept: text/markdown
```
的内容协商。
应该 — 根据RFC 9727在
```
/.well-known/api-catalog
```
提供API目录。
```
@jdevalk/astro-seo-graph
```
≥1.4.0版本提供
```
createApiCatalog
```
，可自动将Schema端点与
```
https://schema.org/<Type>
```
URL关联，并根据
```
siteUrl
```
绝对化路径。列出Schema端点、Schema映射和任何站点特定API（如
```
/ask
```
、
```
/feed.xml
```
等）。该RFC已定稿，格式稳定；目前采用率较低，但实现成本仅需一个路由文件。
应该 — 在
```
robots.txt
```
中添加Content Signals指令（例如
```
Content-Signal: ai-train=yes, search=yes, ai-input=yes
```
）。独立于爬取权限，声明AI训练、搜索 grounding和AI输入使用的偏好。该规范是IETF草案，目前采用率较低，但仅需在每个站点都已有的文件中添加一行。
应该 — 在
```
/*
```
路径添加
```
Link
```
头指向发现文件（站点地图、llms.txt、api-catalog、schemamap，以及站点发布的任何MCP / A2A卡片）。读取响应头的Agent无需解析HTML即可找到这些文件。在Cloudflare Pages / Netlify上可通过
```
public/_headers
```
实现；在Vercel上可通过
```
vercel.json
```
实现。
建议 — 在
```
/.well-known/mcp/server-card.json
```
添加MCP服务器卡片（SEP-1649）和/或在
```
/.well-known/agent-card.json
```
添加A2A Agent卡片（A2A协议）。仅当站点实际暴露MCP服务器或A2A Agent时才需要。两者均为静态JSON文件，声明端点、功能和工具。否则跳过。
建议 — 添加
```
<link rel="nlweb">
```
指向对话端点。NLWeb尚处于早期阶段；该标签仅需一行代码，值得添加，但在2026年不会作为评分阻塞项。

7. Performance (/10)

7. 性能 (/10)

Static output by default (no SSR on pages that don't need it)?
Zero client-side JS unless an island requires it?
Astro
```
<Image>
```
component used for all content images (responsive srcset, WebP, lazy, async)?
Primary web font preloaded in woff2?

<ClientRouter />

with

defaultStrategy: 'viewport'

for prefetch?

Hashed assets under

/_astro/

serve

Cache-Control: public, max-age=31536000, immutable

```
No-Vary-Search
```
response header stripping UTM parameters from cache key?

默认是否为静态输出（不需要SSR的页面不使用SSR）？
是否仅在需要时才引入客户端JS？
所有内容图片是否使用Astro
```
<Image>
```
组件（响应式srcset、WebP、懒加载、异步）？
主网页字体是否以woff2格式预加载？

是否使用

defaultStrategy: 'viewport'

的

<ClientRouter />

进行预取？

/_astro/

下的哈希资源是否设置

Cache-Control: public, max-age=31536000, immutable

？

是否设置
```
No-Vary-Search
```
响应头从缓存键中去除UTM参数？

8. Redirects and error handling (/10)

8. 重定向与错误处理 (/10)

```
public/_redirects
```
(or equivalent) maintained for every URL that ever existed and moved?
301 not 302 for permanent moves?
```
FuzzyRedirect
```
component from
```
@jdevalk/astro-seo-graph
```
wired into the 404 page?
404 page itself returns a 404 status, not 200?

是否为所有已变更的历史URL维护
```
public/_redirects
```
（或等效文件）？
永久移动是否使用301而非302？
404页面是否接入
```
@jdevalk/astro-seo-graph
```
的
```
FuzzyRedirect
```
组件？
404页面本身是否返回404状态码，而非200？

9. Build-time validation and content quality (/10)

9. 构建时验证与内容质量 (/10)

Must —
```
seoGraph()
```
integration running on each build with
```
validateH1
```
and
```
validateUniqueMetadata
```
enabled. For JSON-LD validation, pass
```
warnOnDanglingReferences: true
```
to
```
assembleGraph()
```
in
```
seo-graph-core
```
— that's the assembly-time check, not an integration option.
Should —
```
validateImageAlt
```
,
```
validateMetadataLength
```
, and
```
validateInternalLinks
```
enabled on
```
seoGraph()
```
(all default
```
true
```
in ≥ 1.1.0). They catch missing alt text, titles or descriptions outside SERP bounds (defaults: title 30–65, description 70–200), and internal links that 404 or hit a trailing-slash mismatch. Upgrade to ≥ 1.1.1 if the project is on 1.1.0 — that patch release fixes two validator bugs:
```
validateInternalLinks
```
now recognises
```
public/
```
assets as valid targets (no more false positives on
```
/images/*
```
or
```
/fonts/*
```
), and
```
validateMetadataLength
```
no longer truncates descriptions containing a raw apostrophe. Use
```
skip
```
only for SSR-only routes, wildcards, and
```
[slug]
```
params.
Should — broken link checker in CI for external links. A lychee GitHub Action on every push to content files catches dead links before they go live; a weekly scheduled run catches link rot as external sites move or disappear. Broken outbound links are a bad UX and a negative trust signal. Internal links are covered by
```
validateInternalLinks
```
at build time; lychee handles everything else.
Should — SEO strings (titles, descriptions, FAQ answers) audited for metadata quality — front-loading, concreteness, truncation fit, no title/description duplication. Phase 2.5 chains this in via
```
metadata-check
```
. Individual post prose can be audited separately via
```
readability-check
```
.

必须 — 每次构建时运行
```
seoGraph()
```
集成，并启用
```
validateH1
```
和
```
validateUniqueMetadata
```
。对于JSON-LD验证，在
```
seo-graph-core
```
的
```
assembleGraph()
```
中传入
```
warnOnDanglingReferences: true
```
——这是组装时的检查，而非集成选项。
应该 — 在
```
seoGraph()
```
上启用
```
validateImageAlt
```
、
```
validateMetadataLength
```
和
```
validateInternalLinks
```
（≥1.1.0版本默认均为
```
true
```
）。它们会检测缺失的alt文本、超出SERP范围的标题或描述（默认：标题30-65字符，描述70-200字符），以及指向404或尾部斜杠不匹配的内部链接。如果项目使用1.1.0版本，建议升级到≥1.1.1版本——该补丁修复了两个验证器bug：
```
validateInternalLinks
```
现在会将
```
public/
```
资源识别为有效目标（不再对
```
/images/*
```
或
```
/fonts/*
```
产生误报），
```
validateMetadataLength
```
不再截断包含原始撇号的描述。仅对仅SSR路由、通配符和
```
[slug]
```
参数使用
```
skip
```
。
应该 — 在CI中使用断链检查工具检测外部链接。每次推送到内容文件时运行lychee GitHub Action，可在上线前发现死链；每周定时运行可检测外部站点变更或消失导致的链接失效。失效的外部链接会影响用户体验，并传递负面信任信号。内部链接已在构建时由
```
validateInternalLinks
```
覆盖；lychee处理其他所有链接。
应该 — 审核SEO字符串（标题、描述、FAQ答案）的元数据质量——前置关键词、具体性、截断适配、标题/描述不重复。阶段2.5通过
```
metadata-check
```
工具关联此检查。单篇文章的 prose 质量可单独通过
```
readability-check
```
工具审核。

Phase 2: Improve

阶段2：优化

Based on the audit, produce the concrete code. Always ask before overwriting. Read
AGENTS.md
for detailed recipes.

Branch on the Phase 0 findings. If

@jdevalk/astro-seo-graph

is already installed, skip the install step and focus on wiring the features the audit flagged as missing (IndexNow, FuzzyRedirect, schema endpoints, build validation). If the user has a hand-rolled setup that already satisfies the Must checks in category 1, don't rip it out — add only what's missing. Replacement is a last resort, not the default.

AGENTS.md

sections: Install/upgrade, Integration config, BaseHead.astro, Content collection schema, Sitemap + git lastmod, OG image route, Schema endpoints, llms.txt, Markdown alternates, API catalog, Content Signals in robots.txt, MCP and A2A discovery cards, Link headers for agent discovery, RSS feed, Redirects + FuzzyRedirect, Performance headers, Broken link checker in CI.

根据审核结果生成具体代码。覆盖文件前务必先询问用户。详细示例请查阅
AGENTS.md
。

根据阶段0的检测结果分支处理。如果已安装

@jdevalk/astro-seo-graph

，跳过安装步骤，专注于接入审核中标记为缺失的功能（IndexNow、FuzzyRedirect、Schema端点、构建验证）。如果用户的手动实现已满足类别1中的必须检查项，不要替换它——仅添加缺失的内容。替换是最后的手段，而非默认操作。

AGENTS.md

包含以下章节：安装/升级、集成配置、BaseHead.astro、内容集合Schema、站点地图 + git最后修改时间、OG图片路由、Schema端点、llms.txt、Markdown替代链接、API目录、robots.txt中的Content Signals、MCP和A2A发现卡片、Agent发现的Link头、RSS订阅源、重定向 + FuzzyRedirect、性能头、CI中的断链检查工具。

Phase 2.5: Metadata and readability pass

阶段2.5：元数据与可读性校验

Invoke the

metadata-check

skill on every short string the skill generated or modified: page titles, meta descriptions, schema

description

fields, FAQ answers, and any blog post frontmatter

excerpt

values you wrote. It checks front-loading, concreteness, filler, active voice, title/description duplication, difficult words, SERP-truncation fit (title 30–65, description 70–200 — the same bounds

validateMetadataLength

enforces), and one-idea-per-field. Apply the fixes directly. Skip the pass entirely for technical strings (URLs, schema

@id

values, enum values).

If the project has a blog or docs content collection, mention to the user as a follow-up that the

readability-check

skill can audit individual posts for multi-paragraph prose quality — but don't audit the entire content corpus yourself.

对本工具生成或修改的所有短字符串调用

metadata-check

工具：页面标题、元描述、Schema

description

字段、FAQ答案，以及你编写的任何博客文章前置内容

excerpt

值。该工具会检查前置关键词、具体性、冗余内容、主动语态、标题/描述重复、难词、SERP截断适配（标题30-65字符，描述70-200字符——与

validateMetadataLength

强制执行的范围一致），以及每个字段单一主题。直接应用修复方案。技术字符串（URL、Schema

@id

值、枚举值）可跳过此校验。

如果项目包含博客或文档内容集合，后续可提醒用户

readability-check

工具可审核单篇文章的多段落prose质量——但不要自行审核整个内容库。

Phase 3: Verify

阶段3：验证

Run
```
npm run build
```
. If
```
seoGraph()
```
is wired, this also runs H1 validation, duplicate-meta detection, and schema validation — surface any warnings.
Spot-check the built HTML: one page's
```
<head>
```
should now be clean, canonical correct, JSON-LD graph present and linked.
Run the homepage through Rich Results Test and ClassySchema.
Confirm
```
/sitemap-index.xml
```
exists and references per-collection sitemaps.
If IndexNow is wired, confirm the key verification route returns the key at
```
/[key].txt
```
.
Remind the user about tasks that can't be automated:
- Register the site in Google Search Console and Bing Webmaster Tools.
- Submit the sitemap index in both.
- Generate an IndexNow key and commit it to config.
- Install Plausible or equivalent privacy-friendly analytics.

执行
```
npm run build
```
。如果已接入
```
seoGraph()
```
，构建时还会运行H1验证、重复元数据检测和Schema验证——展示所有警告信息。
抽查构建后的HTML：某一页的
```
<head>
```
应简洁规范，规范URL正确，JSON-LD图谱存在且关联正确。
将首页通过富结果测试和ClassySchema验证。
确认
```
/sitemap-index.xml
```
存在并引用按集合拆分的站点地图。
如果已接入IndexNow，确认密钥验证路由
```
/[key].txt
```
返回密钥。
提醒用户完成无法自动化的任务：
- 在Google Search Console和Bing Webmaster Tools注册站点。
- 在两者中提交站点地图索引。
- 生成IndexNow密钥并提交到配置中。
- 安装Plausible或其他隐私友好型分析工具。

Output format

输出格式

markdown

undefined

markdown

undefined

Astro SEO audit: [site name]

Astro SEO审核报告: [站点名称]

Score

评分

Category	Score
1. `<Seo>` component and head	x/10
2. Structured data / JSON-LD graph	x/10
3. Content collections and schema	x/10
4. Open Graph images	x/10
5. Sitemaps and indexing	x/10
6. Agent discovery	x/10
7. Performance	x/10
8. Redirects and error handling	x/10
9. Build-time validation and content	x/10
Total	xx/90

类别	得分
1. `<Seo>` 组件与头部元数据	x/10
2. 结构化数据 / JSON-LD图谱	x/10
3. 内容集合与Schema	x/10
4. Open Graph图片	x/10
5. 站点地图与索引	x/10
6. Agent发现	x/10
7. 性能	x/10
8. 重定向与错误处理	x/10
9. 构建时验证与内容质量	x/10
总分	xx/90

Findings

检测结果

[Grouped by category. Quote actual code/config. Be specific.]

[按类别分组。引用实际代码/配置。内容需具体。]

Files generated or changed

生成或修改的文件

[List with short description of each.]

[列出每个文件及简短描述。]

Next steps

后续步骤

[Non-file tasks: GSC, Bing Webmaster Tools, IndexNow key generation, analytics.]

---

[非文件类任务：GSC、Bing Webmaster Tools、IndexNow密钥生成、分析工具。]

---

Key principles

核心原则

Opinionated defaults over optionality. The guide picks a stack; this skill applies it. Don't offer five alternatives when one works.
@jdevalk/astro-seo-graph
is the spine. Route the
```
<Seo>
```
component, schema endpoints, IndexNow, FuzzyRedirect, and build validation through it unless the user has a strong reason to hand-roll.
Topics, not keyphrases. When reviewing content, focus on topical coverage and readability, not keyword density.
Static, CDN-served HTML is the baseline. Don't add SSR to solve problems static builds already don't have.
Agent discovery matters now. Schema endpoints, schema map, NLWeb tags — the crawler is no longer the only consumer.

优先使用预设默认值而非可选配置。指南已选定技术栈；本工具直接应用该栈。当一种方案可行时，不要提供五种替代选项。
@jdevalk/astro-seo-graph
是核心依赖。
```
<Seo>
```
组件、Schema端点、IndexNow、FuzzyRedirect和构建验证均通过该包实现，除非用户有充分理由手动实现。
关注主题而非关键词。审核内容时，聚焦主题覆盖范围和可读性，而非关键词密度。
静态CDN托管HTML是基线。不要为静态构建已解决的问题添加SSR。
Agent发现至关重要。Schema端点、Schema映射、NLWeb标签——爬虫不再是唯一的消费者。

astro-seo

Original

Translation

Astro SEO

Astro SEO

Workflow

工作流程

Phase 0: Detect the project

阶段0：项目检测

Phase 1: Audit

阶段1：审核

1. <Seo> component and head metadata (/10)

1. <Seo>组件与头部元数据 (/10)

2. Structured data / JSON-LD graph (/10)

2. 结构化数据 / JSON-LD图谱 (/10)

3. Content collections and SEO schema (/10)

3. 内容集合与SEO Schema (/10)

4. Open Graph images (/10)

4. Open Graph图片 (/10)

5. Sitemaps and indexing (/10)

5. 站点地图与索引 (/10)

6. Agent discovery (/10)

6. Agent发现 (/10)

7. Performance (/10)

7. 性能 (/10)

8. Redirects and error handling (/10)

8. 重定向与错误处理 (/10)

9. Build-time validation and content quality (/10)

9. 构建时验证与内容质量 (/10)

Phase 2: Improve

阶段2：优化

Phase 2.5: Metadata and readability pass

阶段2.5：元数据与可读性校验

Phase 3: Verify

阶段3：验证

Output format

输出格式

Astro SEO audit: [site name]

Astro SEO审核报告: [站点名称]

Score

评分

Findings

检测结果

Files generated or changed

生成或修改的文件

Next steps

后续步骤

Key principles

核心原则

1.
`<Seo>`
component and head metadata (/10)

1.
`<Seo>`
组件与头部元数据 (/10)