shopify-catalog-cleanup

Shopify 商品目录清理

修复审计发现的问题。这是 shopify-catalog-audit（用于发现问题）和 shopify-seo-metadata（用于补全缺失元数据）的修改型对应工具。这里的所有操作都会写入商品目录，因此整个技能都遵循一条规则：先预览数量，再执行修改。

店铺访问

途径 A：自定义应用令牌（可编写脚本）。 在 Shopify 后台中：设置 → 应用和销售渠道 → 开发应用 → 创建应用 → 授予 read_products 和 write_products 权限，安装应用，然后复制 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，然后运行 shopify store execute。适用于无令牌的店铺，店主会以交互方式登录。

工具包预检。 途径 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/recipes.md 中的每个操作方案都将只读的计数／预览查询与其对应的修改操作配对。必须遵循以下步骤：

1. 先运行计数查询。 products(query:"…") 配合筛选条件会返回 count 和一页商品标题。请阅读结果。
2. 根据预期检查数量是否合理。 如果你预计有约 40 个无效商品，但计数显示 900，请停止并重新调整范围：筛选条件有误，而不是店铺有问题。计数远超预期，说明查询存在错误。
3. 只有完成上述步骤后才能执行修改， 并优先选择可撤销的方式（见下文）。

非破坏性原则

• 归档，不要删除。 归档商品（status: ARCHIVED）会将其从店面和销售渠道隐藏，但保留记录、句柄、历史记录以及 URL 重定向的可能性。此操作完全可撤销：将状态改回 ACTIVE 或 DRAFT 即可。删除无法撤销：商品、其变体和元字段都会消失。默认采用归档；只有店主明确提出要求并了解这是永久操作时，才删除。
• 为处理过的商品添加标签。 批量归档时，在同一次修改中添加带日期的标签 （archived-2026-07-05）。该标签就是撤销清单：若要恢复，查询 tag:archived-2026-07-05 并将状态改回原值。如果没有此标签，就无法准确区分本批商品和此前已归档的商品。
• 先读后写。 读取查询成本很低；未限定范围的修改无法撤销。请通过 Admin API 重新读取对象来验证写入是否生效，而不要查看店面（店面由 CDN 缓存，无法准确反映最新状态）。
• 切勿打印或提交 Admin API 访问令牌。

操作方案，而非脚本

参考内容中的 GraphQL 代码块是可复制并调整的起点：你的 Agent 会根据当前架构，为每次任务编写临时代码，运行后再丢弃。批量修改应分批执行并遵守限流：读取 extensions 块中的 throttleStatus，当 currentlyAvailable 减少时降低请求频率，而不要以固定速率持续发送请求。

三类修复操作

1. 批量归档已停用的产品

动手前先设计好筛选条件。常见的“已停用”信号需要用 AND 组合（单凭一个信号，产品很少会被判定为已停用）：

• 所有变体的总库存为零，并且
• 在一段追溯时间内（例如 12 个月）没有销量，并且
• 创建或更新的时间足够久，不属于新上架产品，并且
• 不在你关注的产品系列中，或已添加停产标签。

将这些条件转化为 products(query: …) 搜索筛选条件，运行 count 查询，查看样例标题，确认数量大致符合预期，然后运行 productUpdate，将 status: ARCHIVED 设为归档状态，并添加带日期的标签。取消归档时，使用相同的标签查询，将状态改回即可。操作示例：references/recipes.md。

2. 孤立的 metafield 残留（幽灵星级问题）

典型症状：商店卸载了产品评价应用（通常是 Shopify 自带的 Product Reviews），但主题仍会在每个产品上显示空星级。应用留下了 metafield：Product Reviews 应用写入的 spr.reviews 字段，以及包含 reviews.rating 和 reviews.rating_count 的 reviews 命名空间。主题的星级代码片段读取这些字段，发现值为 0，于是显示五颗空星。

安全修复：

1. 确认应用确实已卸载。 检查“设置” →“应用”；该命名空间必须属于已卸载的应用，而不只是已暂停的应用。删除已安装应用拥有的 metafield，只会导致应用重新写入它们。
2. 盘点孤立的命名空间。 查询产品 metafield 定义，并抽查每个可疑命名空间下的产品（Product Reviews 应用对应 spr 和 reviews），以便准确了解要删除哪些 namespace.key，以及有多少产品包含这些字段。
3. 通过 metafieldsDelete 删除，使用所有者 GID + 命名空间 + 键作为标识，涵盖 spr.reviews 和 reviews.rating / reviews.rating_count 字段。先预览受影响的数量，做法与归档时相同；对标识符分批处理，避免超出速率或成本限制。
4. 重新读取几款产品，确认这些字段已删除，然后重新加载店面中的产品页面：空星级应已消失（主题代码片段中也可能需要移除现在已失效的引用；请告知主题负责人）。

Matrixify 警告： Matrixify 更新中的空白单元格会删除该 metafield，而不是跳过它。这既可能导致意外删除，也可用于有意批量移除；无论如何，都要清楚自己正在执行哪种操作。有关通过电子表格批量处理及这一陷阱，请参阅 shopify-matrixify。

3. 描述中的 HTML 伪影

编辑器、应用注入和复制粘贴会在 descriptionHtml 中留下残留内容： 重复嵌套的 <strong><strong>…、整个段落被加粗、空的 <p></p> / <span></span> 标签，以及多余的内联样式。对目标范围提取 descriptionHtml，用正则匹配伪影模式，通过索引扫描快速检测，而不是逐个检查产品。 通过 productUpdate 按产品重写 descriptionHtml 来修复：使用有针对性的字符串转换， 而不是从头重写，以免丢失实际格式。

每次重写都记录旧内容和新内容。 处理过程中，将每次重写（产品 ID、旧 descriptionHtml、新 descriptionHtml、状态）写入 CSV，遵循 shopify-seo-metadata 对元数据写入的同样规范。这份日志有两个用途：作为差异审查依据 （完成前抽查一些旧内容→新内容的记录），也是唯一的撤销清单。归档会添加带日期的标签，便于查询和恢复； 重写则没有，因此如果没有日志，一旦转换出错就无法恢复。这也会影响后续处理：基于正文 HTML 生成内容的技能（例如 SEO 元数据）会继承错误重写留下的内容。

编辑后扫描原则。 每次批量编辑内容后，都要再次扫描受影响的范围，检查残留内容： 重复加粗、孤立标签、只完成一半的转换，然后才能宣布完成。批量正则修复经常会在 3% 标记未符合预期的产品上留下新的伪影。通过复扫才是证据；“转换已运行”不是。

参考资料

• references/recipes.md：变更前计数的归档查询 + 修改、元字段命名空间清单 + metafieldsDelete、 描述伪影扫描 + 安全重写。

来源与维护

最后验证日期：2026-07-05。GraphQL 固定使用 Admin API 2025-07；Shopify 按季度滚动弃用 API 版本，因此在信任特定版本的说法之前，请对照 shopify.dev 进行验证。陌生人也能运行的只读复核（元字段命名空间清单和归档产品计数，均不会修改数据）：

# how many products are already archived, and a metafield namespace sample
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":"{ productsCount(query:\"status:archived\") { count } products(first:5) { nodes { title metafields(first:20) { nodes { namespace key } } } } }"}'

规范文档：productUpdate、 metafieldsDelete。 这些技能记录了文档未涵盖的操作经验；它们不能替代参考资料。