add-seo

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果输出了消息，请先将其显示给用户，再继续。

添加 SEO

为 Power Pages SPA 网站添加必要的 SEO 资源：robots.txt、sitemap.xml 和 meta 标签。

**前提条件：**此技能要求已通过 /create-site 创建 Power Pages SPA 网站。如果网站尚不存在，请先运行该技能。

核心原则

• **首先确保可抓取性：**在进行其他 SEO 工作之前，必须通过有效的 robots.txt 和 sitemap.xml，确保搜索引擎能够发现所有公开页面。
• **元数据准确无误：**meta 标签（标题、描述、Open Graph）必须如实反映页面内容——误导性元数据会损害排名。
• **根据框架选择正确位置：**SEO 资源必须放在检测到的框架对应的正确位置（public 目录、布局组件等）。
• **保留本地化元数据：**阅读 ${PLUGIN_ROOT}/references/site-modification-integrity.md。如果存在本地化，请保持各语言的标题、描述、社交元数据、替代链接和静态语言区域路由同步，并且不要声明不可用的语言区域。

初始请求： $ARGUMENTS

工作流

1. 阶段 1：验证网站是否存在 → 定位 Power Pages 项目
2. 阶段 2：收集 SEO 配置 → 网站 URL、页面、偏好设置
3. 阶段 3：规划并审批 → 内联展示 SEO 新增内容，并获得用户批准
4. 阶段 4：添加 robots.txt → 在 public 目录中创建 robots.txt
5. 阶段 5：添加 sitemap.xml → 根据网站路由生成 sitemap.xml
6. 阶段 6：添加 Meta 标签 → 在 index.html 中添加标题、描述、视口、Open Graph 和网站图标
7. 阶段 7：验证并提交 → 使用 Playwright 验证并提交更改

---

阶段 1：验证网站是否存在

**目标：**确认 Power Pages SPA 网站已存在，并了解其结构。

操作

1.1 定位项目

在当前目录或其直接子目录中查找 powerpages.config.json，以确定项目根目录。请使用文件搜索工具（例如，使用模式 powerpages.config.json 和 */powerpages.config.json 执行 Glob），而不要使用特定于 shell 的命令。

如果未找到：告知用户先使用 /create-site 创建网站。

1.2 读取现有配置

读取 powerpages.config.json，获取网站名称和配置。

1.3 检测框架并发现路由

读取 package.json 以确定框架并定位关键文件。完整的“框架 → public 目录 → index HTML”映射及路由发现模式，请参阅 ${PLUGIN_ROOT}/references/framework-conventions.md。

列出所有路由（例如 /、/about、/contact、/blog）。

输出

• 已确定项目根目录路径
• 已检测到框架（React、Vue、Angular 或 Astro）
• 完整的可发现路由列表

---

阶段 2：收集 SEO 配置

**目标：**在进行任何更改之前，收集用户的所有 SEO 偏好。

操作

使用 AskUserQuestion 收集 SEO 偏好：

调用 1

问题	标题	选项
您网站的生产环境 URL 是什么？（例如：https://contoso.powerappsportals.com）	网站 URL	（自由文本——仅使用一个通用选项，让用户通过“其他”输入）
哪些页面应排除在搜索引擎索引之外？	排除项	无——为所有页面编制索引（推荐），仅限管理/身份验证页面，让我指定

调用 2

问题	标题	选项
您希望在搜索结果中显示什么 meta 描述？	描述	（自由文本——仅使用一个通用选项，让用户通过“其他”输入）
是否添加用于社交媒体分享的 Open Graph 标签？	OG 标签	是——添加 Open Graph 和 Twitter Card 标签（推荐），否——跳过社交标签

输出

• 已确认生产环境 URL
• 已确定排除列表
• meta 描述文本
• Open Graph 标签偏好（是/否）

---

第 3 阶段：规划与批准

目标： 向用户展示完整的 SEO 计划，并在进行更改前获得明确批准。

操作

以清晰的内联摘要形式展示将添加的 SEO 内容：

1. robots.txt 内容 — 将允许或禁止访问哪些路径
2. sitemap.xml 内容 — 所有已发现的路由及其生产环境 URL 和优先级分配
3. 要添加到 index.html 的元标签 — title、description、viewport、charset、Open Graph、Twitter Card
4. Favicon — 链接标签和占位 SVG

🚦 关卡（计划 · add-seo:3.plan-approval）： 在写入任何 robots.txt / sitemap.xml / index.html 之前，对 SEO 添加内容进行最终确认。

触发条件： 第 3 阶段已内联展示完整计划（robots.txt、sitemap.xml、元标签、favicon）。 询问原因： SEO 资源写入磁盘后，可能包含错误的生产环境 URL、错误的排除项或不需要的 OG 标签——虽然可以修复，但会给 git 历史带来不必要的干扰。 取消后状态： 无——尚未写入任何文件。

展示计划后，使用 AskUserQuestion 获取批准：

问题	标题	选项
以下是 SEO 计划。你想如何继续？	SEO 计划审批	批准并继续（推荐），我想进行更改

如果用户选择“我想进行更改”，询问他们想更改哪些内容，相应更新计划，并再次展示修订后的计划以供批准。

输出

• 已获用户批准、可供实施的 SEO 计划

---

第 4 阶段：添加 robots.txt

目标： 创建有效的 robots.txt，告知搜索引擎要抓取哪些页面。

操作

在公共目录中创建 robots.txt（<PROJECT_ROOT>/public/robots.txt）：

User-agent: *
Allow: /

Sitemap: <PRODUCTION_URL>/sitemap.xml

如果用户指定了要排除的页面，请添加 Disallow 指令：

User-agent: *
Allow: /
Disallow: /admin/
Disallow: /auth/

Sitemap: <PRODUCTION_URL>/sitemap.xml

输出

• 已在 public/robots.txt 中创建正确的指令

---

第 5 阶段：添加 sitemap.xml

目标： 生成完整的 sitemap.xml，列出所有可发现的路由并设置适当的优先级。

操作

在公共目录中创建 sitemap.xml（<PROJECT_ROOT>/public/sitemap.xml）。

使用生产环境 URL 为每个已发现的路由生成条目：

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc><PRODUCTION_URL>/</loc>
    <lastmod><TODAY_DATE></lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc><PRODUCTION_URL>/about</loc>
    <lastmod><TODAY_DATE></lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.8</priority>
  </url>
  
</urlset>

优先级规则：

• 主页（/）：1.0
• 顶级页面：0.8
• 子页面：0.6

排除项： 不要包含用户选择排除的路由（例如 /admin/*、/auth/*）。

输出

• 已在 public/sitemap.xml 中创建包含所有路由和正确 URL 的文件，且没有占位符

---

第 6 阶段：添加元标签

目标： 为网站的 HTML 添加全面的元标签、Open Graph 标签和 favicon。

操作

6.1 必要元标签

在网站的 index.html 中添加或更新元标签（位置取决于框架，见第 1.3 阶段）：

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title><SITE_TITLE></title>
  <meta name="description" content="<META_DESCRIPTION>" />
  <meta name="robots" content="index, follow" />
  <link rel="canonical" href="<PRODUCTION_URL>/" />
  <link rel="sitemap" type="application/xml" href="/sitemap.xml" />
</head>

6.2 Open Graph 标签（如果用户选择启用）

在 <head> 中添加 Open Graph 和 Twitter Card 元标签：

<meta property="og:type" content="website" />
<meta property="og:title" content="<SITE_TITLE>" />
<meta property="og:description" content="<META_DESCRIPTION>" />
<meta property="og:url" content="<PRODUCTION_URL>/" />
<meta property="og:site_name" content="<SITE_TITLE>" />


<meta name="twitter:card" content="summary" />
<meta name="twitter:title" content="<SITE_TITLE>" />
<meta name="twitter:description" content="<META_DESCRIPTION>" />

6.3 Favicon

检查公共目录中是否已存在 favicon。如果不存在，添加简单的 SVG favicon 链接：

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

使用网站的主色创建最简占位文件 public/favicon.svg：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <rect width="100" height="100" rx="20" fill="<PRIMARY_COLOR>"/>
  <text x="50" y="70" font-size="50" text-anchor="middle" fill="white" font-family="system-ui, sans-serif" font-weight="bold"><FIRST_LETTER></text>
</svg>

其中，<FIRST_LETTER> 是网站名称的首字母，<PRIMARY_COLOR> 是网站配置中的主题主色。

6.4 Astro 专属处理

对于 Astro 网站，应将元标签添加到基础布局组件（例如 src/layouts/Layout.astro），而不是根目录的 index.html。Astro 使用基于组件的 <head> 管理方式。

输出

• 已将元标签添加到 index.html（或等效的 Astro 布局文件）
• 已添加 Open Graph 和 Twitter Card 标签（如果用户选择启用）
• 已创建并关联 Favicon SVG（如果此前不存在）

---

第 7 阶段：验证并提交

目标： 确认所有 SEO 资源均已就位，通过 Playwright 验证，并提交更改。

操作

7.1 验证文件是否存在

确认已创建或更新以下文件：

• public/robots.txt
• public/sitemap.xml
• public/favicon.svg（如果已创建）
• index.html 或等效文件（已添加元标签）

7.2 通过 Playwright 验证

如果开发服务器正在运行（或启动一个）：

1. 导航到网站根目录，并使用 browser_snapshot 验证页面源代码中是否存在 meta 标签
2. 导航到 /robots.txt 并验证其是否成功加载
3. 导航到 /sitemap.xml 并验证其是否成功加载

7.2b 最终网站完整性门槛

完成所有 SEO 源代码和元数据更改以及浏览器验证后，运行：

node "${PLUGIN_ROOT}/scripts/validate-site-integrity.js" --projectRoot "<PROJECT_ROOT>"

在记录完成或创建最终提交前，修复所有阻塞错误。双向检查并报告审查结果，并扩展内容。此后如有任何源代码更改，请重新运行此门槛。

7.3 记录技能使用情况

参考：${PLUGIN_ROOT}/references/skill-tracking-reference.md

按照参考文档中的技能跟踪说明记录此技能的使用情况。使用 --skillName "AddSeo"。

7.4 Git 提交

重要 — 此步骤为必做项。完成前必须提交 SEO 更改。不要跳过此步骤。

暂存指定的 SEO 文件并提交：

git add public/robots.txt public/sitemap.xml public/favicon.svg index.html
git commit -m "Add SEO: robots.txt, sitemap.xml, meta tags, favicon"

根据实际创建的文件调整文件路径（例如，对于 Astro 网站，使用 src/layouts/Layout.astro 代替 index.html；如果未创建 favicon.svg，则省略它）。仅暂存此技能创建或修改的文件。

7.5 提供摘要

总结添加的内容：

资源	状态	详情
robots.txt	已创建	允许所有爬虫访问，并引用站点地图
sitemap.xml	已创建	映射 X 个 URL 并设置优先级
Meta 标签	已添加	title、description、viewport、canonical、robots
Open Graph	已添加/已跳过	og:title、og:description、og:url、Twitter Card
Favicon	已创建/已跳过	带有网站首字母的 SVG favicon

7.6 建议后续步骤

摘要之后，建议：

• 部署网站以使 SEO 更改生效：/deploy-site
• 如果需要数据模型：/setup-datamodel
• 若要实现更高级的 SEO：可考虑结构化数据（JSON-LD）、性能优化和无障碍审查

输出

• 所有文件均已在磁盘上验证
• Playwright 验证已通过
• 已创建包含所有 SEO 更改的 Git 提交

---

重要说明

进度跟踪

开始时使用 TaskCreate 跟踪各个阶段：

任务	描述
阶段 1	验证网站是否存在并检测框架
阶段 2	从用户处收集 SEO 配置
阶段 3	提交计划并征得用户批准
阶段 4	创建 robots.txt
阶段 5	生成 sitemap.xml
阶段 6	添加 meta 标签、Open Graph 和 favicon
阶段 7	通过 Playwright 验证并提交

每项任务完成后，使用 TaskUpdate 更新状态。

关键决策点

• 阶段 1： 如果未找到 powerpages.config.json，则停止并引导用户前往 /create-site。
• 阶段 2： 如果用户指定了自定义排除项，请在继续前确认确切路径。
• 阶段 3： 在用户明确批准计划前，不要开始实施。
• 阶段 6.4： 如果框架为 Astro，meta 标签应放入布局组件，而不是 index.html。
• 阶段 7.2： 如果 Playwright 验证失败（例如，robots.txt 无法加载），请在提交前诊断并修复。

从阶段 1 开始：验证网站是否存在