shopify-seo-metadata

Shopify SEO 元数据

以安全模式回填产品、产品系列、页面和博客文章中缺失的搜索展示元数据（Google 在搜索结果摘要中显示的 SEO 标题和元描述）。核心原则：只填空，不覆盖。商家手写的元标题比模型生成的任何内容都更有价值；此技能只会修改空字段。

配套技能 shopify-alt-text 会对产品图片替代文本执行同样的“只填缺失项”回填；shopify-json-ld 负责处理结构化数据。若要先衡量整个商店缺失了多少元数据，shopify-catalog-audit 是用于确定此修复范围的 FIND 阶段。

商店访问权限

每个调用 Admin API 的技能都会先使用此代码段（此技能所需的最低权限范围见下文）。有两种方式，任选其一。

方式 A：自定义应用令牌（可编写脚本）。 在 Shopify 管理后台中，依次前往 Settings → Apps and sales channels → Develop apps → 创建应用 → 授予以下权限范围，然后安装应用并复制 Admin API 访问令牌。导出该令牌；切勿将其写入已提交的文件：

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env, not disk

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

方式 B：Shopify CLI OAuth（不存储令牌）。 运行 shopify store auth --store $SHOPIFY_STORE --scopes read_products,write_products,read_content,write_content ，然后使用 shopify store execute 运行经过验证的操作。适用于商店所有者通过交互方式登录的无令牌商店。

此技能所需的最低权限范围： read_products + write_products 可访问产品和产品系列（两者都属于 products 权限范围）。页面和博客文章需要 read_content + write_content。只申请本次运行会用到的权限范围。

工具包预检。 方式 B 依赖 Shopify CLI：先运行 shopify version，如果尚未安装，则安装它。要获取完整的 Admin GraphQL 架构并执行经过验证的操作，请将此技能与 Shopify 官方 AI 工具包插件配合使用。在 Claude Code 中，运行 claude plugin list 检查；如果未安装：

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

建议但非必需：方式 A 只需要 curl 和令牌。工具包为 Agent 提供 API；此技能则为其提供操作指南。

操作示例，而非脚本

references/queries-and-prompts.md 中的每个 GraphQL 代码块都是可复制并按需调整的起点。每次任务都应针对当前架构编写临时代码，运行后将其丢弃。遵循两条规则，确保元数据回填安全。

安全模式就是全部工作

每次运行前都要明确说出这一点，并将其视为不可妥协的要求：

1. 只填缺失项。绝不覆盖已有值。 对于每个实体，必须先读取 seo { title description }（产品/产品系列）或 global.title_tag / global.description_tag 元字段（页面/文章）。非空字段一律跳过，不得例外。“覆盖所有内容”模式是另一项需要刻意执行的工作：它绝不是默认模式，陌生人运行此技能也不会自动获得执行权限。
2. 分别填充这两个字段。 产品可能有标题但没有描述。只生成并写入空字段；已有内容必须逐字节保持不变。

先预览，再修改

开始批量写入前，必须先明确知道涉及的数量。

1. 运行只读 COUNT（每种实体的查询见参考资料），统计缺失字段的条目数。这就是修改循环将处理的确切数量，且会使用相同的跳过逻辑。
2. 根据预期核对数量是否合理。 一家有 40 个产品的商店却报告有 3,000 个条目需要 SEO，说明跳过逻辑有误，或者你访问了错误的商店。如果数量远超预期，立即停止并重新确认范围：不要为了“看看会发生什么”而开始修改。对整个目录进行未限定范围的写入，后果并非可以轻易撤销。
3. 只有在数量合理后，才能生成并写入。

使用真实补全预检大模型密钥

批量运行前，向生成模型发送一次真实的 1 个 token 补全，而不是调用 models.list() / 列出模型。拥有读取模型列表权限的密钥，实际补全时仍可能失败（账单逾期、组织配额不足、项目错误）。如果运行中途才发现密钥失效，整个队列都会变成失败行，爬取工作也会白费。提前进行一次微小的补全，是最划算的保障。

逐个实体生成、写入并验证

每种实体的流程都相同，只有读取查询、写入 mutation 和内容源字段不同（参考文档中列出了全部四种）：

• **产品：**内容源 = 产品标题 + 正文 HTML。通过 productUpdate 写入，并使用 input.seo { title description }。
• **集合：**内容源 = 集合标题 + 描述。通过 collectionUpdate 写入，使用相同的 seo 输入。
• **页面：**内容源 = 标题 + bodySummary。SEO 存储在 global.title_tag（单行）和 global.description_tag（多行）元字段中；通过 metafieldsSet 写入。
• **博客文章：**内容源 = 标题 + summary（以及作为上下文的父级博客标题）。使用相同的 global.*_tag 元字段，并通过相同的 metafieldsSet 写入。

**源数据决定了输出质量的上限。**产品内容根据正文 HTML 生成：如果刚刚对该目录进行了批量描述清理或改写（例如使用 shopify-catalog-cleanup），请先确认编辑后的重新扫描已通过，再开始生成；否则，转换过程中标记被破坏的产品，其错误内容就会被大规模写入新的 meta 字段。丰富内容无法修复错误的源数据，只会把它洗进新字段。

进行每次写入时，都要将其记录到 CSV 或逐行日志中（资源 ID、字段、旧值、新值、状态）。这份日志是你的凭证，也是重试清单。

写入后验证：通过 Admin API，而非店面

mutation 未返回 userErrors 只是一个声明，不是证明。请确认写入结果：

• 运行结束后，通过 admin/api/2025-07/graphql.json 重新读取 2–3 个已写入资源的 seo { title description }（或 global.*_tag 元字段），并确认值与写入内容一致。
• **通过 Admin API 读回，而不是查看店面。**店面的 <meta> 标签会被 CDN 缓存，无法反映最新状态：过时的边缘页面会在写入完成很久之后仍显示旧标签（或空标签），让你误以为存在一个实际上并不存在的问题。Admin API 才是事实来源。

提示词指南

生成的 meta 质量取决于模型无法自行推断的三点：

• **在每条提示词中加入商店的定位。**一段简短的品牌描述（目标客户、品牌语气、所属品类）能让文案贴合品牌，而不是流于泛泛之谈。描述过于简略或有误，会导致大规模生成的 meta 偏离品牌定位；批量运行前，请先认真撰写一段描述。
• **长度目标。**SEO 标题约为 50–60 个字符（Google 会截断超过约 60 个字符的标题）；meta 描述约为 150–160 个字符。模型无法可靠地统计字符，因此要在代码中验证长度，并对超出限制的内容重新生成，不要相信模型会遵守要求。
• **不要堆砌关键词。**把买家真正会搜索的一个主要关键词放在前面，面向阅读搜索结果的人来写，到此为止。重复关键词和全大写的促销用语读起来像垃圾信息，毫无益处。

完整的查询、mutation 和提示词详情： references/queries-and-prompts.md。

来源与维护

最后验证日期：2026-07-05。GraphQL 固定使用 Admin API 2025-07；Shopify 按滚动季度计划弃用版本，因此在信任特定版本的声明之前，请通过 shopify.dev 验证 seo 字段和资源变更操作。任何人都可以运行以下只读复核，以确认令牌能够访问商店，并且产品上的 seo 字段可以解析：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(first: 3) { nodes { title seo { title description } } } }"}'

规范文档：资源上的 seo 字段和 Admin GraphQL 中的元字段模型。此技能记录了参考文档未涵盖的安全模式操作规范；它不能替代参考文档。