SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场shopify-catalog-audit

shopify-catalog-audit

数据与分析

查看项目

更新于 10-16 09:17

技能介绍

用途

Shopify Catalog Audit 是目录工作中的“发现（FIND）”阶段：它产出一份经过排序、带有依据的商品数据缺陷清单，然后交接出去。修复（FIX）阶段由同级技能负责：shopify-catalog-cleanup（归档/清理残骸）、shopify-seo-metadata（缺失的 SEO 元数据）、shopify-alt-text（缺失的图片替代文本）。本技能不做任何修改。

核心原则：面对大到无法逐页肉眼检查的目录，不要读取每一个 PDP。先对整个目录构建一个廉价的确定性索引，让模型形成关于问题聚集位置的有依据假设，只深度读取那一小片，然后对照 Admin API 验证。完整方法见 references/triage-method.md，GraphQL 配方见 references/queries.md。

店铺访问

只读审计。授予最小权限 read_products，不要其他任何权限：本技能从不需要写入权限，只读令牌是它无法破坏目录的最廉价保证。

通道 A：自定义应用令牌（可脚本化）。在 Shopify 后台：Settings → Apps and sales channels → Develop apps → 创建应用 → 授予 read_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，再用 shopify store execute 运行经过验证的读取。适合店主交互式登录的无令牌店铺。

工具包预检。通道 B 依赖 Shopify CLI：先运行 shopify version，若缺失则安装。要获得完整的 Admin GraphQL schema 和经过验证的执行，可将本技能与 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 和令牌。工具包为智能体提供 API；本技能为它提供审计手册。

非破坏性原则

这是只读技能；原则自然满足，但仍约束你如何验证。

绝不修改。不执行 productUpdate、productDelete、批量写入。若某项发现需要修复，指出对应的 FIX 技能并停止。

通过 Admin API 而非 sitemap 验证存在性与状态。sitemap（/sitemap_products_1.xml）只列出已发布商品，会静默遗漏草稿、已归档和未发布商品，而这些正是数据残骸藏身之处。信任 sitemap 的审计会少报。请通过 admin/api/.../graphql.json 回读商品状态。

真实依据胜过自我评分。当重新查询 Admin API 在实时对象上确认缺陷时，发现才是真实的，而不是索引说它是。

审计循环

两层：覆盖全目录的廉价确定性索引，然后在其上进行假设驱动的分诊。切勿把整个目录粘贴给模型“以求周全”：那正是本方法要避免的成本陷阱。

  1. 构建廉价索引。分页拉取商品，只取能揭示 PDP 质量的字段（配方见 references/queries.md）。对每个商品，在代码中计算确定性标记（代码回答代码能回答的）：
  • 图片：mediaCount / image count 为 0（缺图）或为 1（偏薄，很可能是本应展示多角度的商品的占位图）。
  • 描述：descriptionHtml 为空，或去除标签后长度低于小阈值（例如低于约 20 字符 = 实际为空）。标记“偏薄”，暂不评判质量。
  • 价格异常：任何变体价格为 0.00；任何变体设置了 compareAtPrice 但 ≤ price（倒挂或虚假“促销”，显示无折扣或负折扣）。
  • 分类缺口：productType 或 vendor 为空：这些会破坏筛选集合、分面搜索和 Google Shopping feed。
  • 状态上下文：携带 status（ACTIVE/DRAFT/ARCHIVED）和 publishedAt，以便权衡标记（0 美元的草稿是噪音；0 美元的已发布活跃商品是实时缺陷）。

输出紧凑的逐商品行（handle、id、status、布尔标记）。模型推理的表面是这张表，而不是原始目录。

  1. 在索引上提出有依据的假设。模型读取标记表，对真实问题聚集处排序，每个假设附上陈述的理由：没有理由就丢弃。好的假设发现模式，而不只是行：“上个月从供应商 X 导入的每个商品都有 0 张图片，很可能是 feed 导入损坏”胜过“这 40 个商品缺图”。按实时影响加权：一个活跃、已发布且价格为 0 美元的商品是收入泄漏；同样的标记出现在草稿上则是噪音。

  2. 只深度读取目标切片。仅拉取有依据假设指向的商品完整详情（其 PDP、变体表、媒体）。真正的 token 花在这里。切勿“为保险起见”扩大回整个目录：那会破坏本方法。

  3. 对照真实依据验证。通过 Admin API 重新查询每个存活的发现，并在实时对象上确认缺陷。不是对照索引，也不是对照 sitemap。通过的真实世界读取才是证据。

纪律护栏

  • 有依据否则丢弃。模型无法解释的标记不会进入深度读取。
  • 记录覆盖范围。说明你索引了什么、没有索引什么。“发现 18 个问题商品”绝不能读作“目录是干净的”：你只针对图片、描述、价格和分类做了索引，因此对一切其他问题（损坏的变体、不匹配的选项、错误的 metafields）是盲的。明确说出盲点；分诊不是保证。
  • 重新瞄准，而非扩大。结果偏薄意味着需要更好的索引（标记不同的信号），而不是给模型喂更多原始目录。
  • 速率限制是真实的。products 连接受查询成本节流；全目录爬取前请阅读 references/queries.md 中的成本与并发说明。

交接格式

输出按缺陷类别分组的排序清单，每行：handle、商品 id、status、具体标记、依据，以及拥有补救措施的对应 FIX 技能。缺失/偏薄图片 → 一旦有照片，shopify-alt-text 也适用；作为副作用浮现的缺失 SEO 元数据 → shopify-seo-metadata；可归档残骸和 0 美元草稿 → shopify-catalog-cleanup。

参考资料

  • references/queries.md：分页商品 GraphQL 配方、索引要拉取的字段、查询成本/速率限制说明，以及 Plus 店铺并发说明。
  • references/triage-method.md：为目录工作泛化的假设驱动分诊方法。

来源与维护

最后验证：2026-07-05。GraphQL 固定为 Admin API 2025-07；Shopify 按滚动季度计划弃用版本，因此在信任版本特定声明前，请对照 shopify.dev 验证字段名和版本。陌生人可运行的只读再验证，确认令牌能到达店铺且审计字段在实时 schema 上可解析：

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:5){ edges{ node{ handle status productType vendor descriptionHtml mediaCount{count} variants(first:5){ edges{ node{ price compareAtPrice } } } } } } }"}'

权威文档：Admin GraphQL、products 查询。本技能捕捉文档未涵盖的审计方法；它不是参考文档的替代品。