shopify-catalog-audit

Shopify 目录审计

找出问题，而不是修复问题。这是目录工作的 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 架构并执行经过验证的操作，请将此技能与 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；此技能则为其提供审计指南。

不可破坏原则

这是一个只读技能；虽然遵循这一原则轻而易举，但核实方式仍受其约束。

• 绝不修改数据。 不使用 productUpdate、不使用 productDelete，也不执行批量写入。如果发现的问题需要修复，请指出对应的 FIX 技能，然后停止。
• 通过 Admin API 核实商品是否存在及其状态，不要依赖站点地图。 站点地图（/sitemap_products_1.xml）只列出已发布的商品，会悄无声息地漏掉草稿、已归档商品和未发布商品，而数据残留恰恰藏在这些地方。依赖站点地图的审计会低估问题。通过 admin/api/.../graphql.json 读取商品状态。
• 以事实为准，不以自我评估为准。 只有重新查询 Admin API，并确认线上对象确实存在缺陷，才能认定发现属实；索引中的记录本身并不足以证明问题存在。

审计循环

分为两层：先对整个目录建立一个成本低、确定性的索引，再在此基础上进行假设驱动的分诊。切勿为了“面面俱到”而把整个目录粘贴到模型中：这正是此方法要避免的成本陷阱。

1. 建立低成本索引。 对 products 分页查询，仅提取能反映 PDP 质量的字段（查询示例见 references/queries.md）。对每个产品，在代码中计算确定性标记（代码能回答的问题就交给代码）：

• 图片： mediaCount / 图片数为 0（缺少照片）或 1（图片不足，可能只是本应展示多个角度的产品的占位图）。
• 描述： descriptionHtml 为空，或剥离 HTML 后的长度低于较小的阈值（例如少于约 20 个字符，基本等同于空）。标记为“内容不足”，暂不判断质量。
• 定价异常： 任一变体的 price 为 0.00；或任一变体设置了 compareAtPrice，但该值 ≤ price（价格倒挂或虚假的“促销”，没有折扣或折扣为负）。
• 分类缺失： productType 为空或 vendor 为空：这会导致筛选集合、分面搜索和 Google Shopping 商品 Feed 出错。
• 状态背景： 保留 status（ACTIVE/DRAFT/ARCHIVED）和 publishedAt，以便评估标记的影响（$0 草稿只是噪声；已发布的 $0 ACTIVE 产品则是线上缺陷）。

为每个产品生成一行简明记录（handle、id、status、布尔标记）。模型应基于这张表进行推理，而不是原始目录。

2. 对索引提出有依据的假设。 模型读取标记表，并对真正的问题可能集中在哪里进行排序，每个假设都必须说明理由：没有理由，就舍弃。 好的假设能发现“模式”，而不只是列出行：“上个月从供应商 X 导入的所有产品都没有图片，可能是导入 Feed 出错”，胜过“这 40 个产品缺少图片”。根据线上影响评估：价格为 $0 的 ACTIVE 且已发布产品会导致收入流失；同样的标记出现在草稿上则只是噪声。

3. 仅深入读取目标子集。 只为有依据的假设所指向的产品提取完整详情（其 PDP、变体表、媒体）。真正消耗令牌的环节就在这里。切勿为了“保险起见”又扩大到整个目录：那会破坏这一方法。

4. 对照事实核验。 通过 Admin API 重新查询每项待确认的发现，并在实时对象上确认缺陷。不能对照索引，也不能对照 sitemap。通过核验的真实读取结果才是证据。

执行准则

• 说明理由，否则舍弃。 如果模型无法解释某个标记，就不对其进行深入读取。
• 记录覆盖范围。 说明你索引了什么，以及没有索引什么。“发现 18 个问题产品”绝不能被解读为“目录没有其他问题”：你索引了图片、描述、定价和分类，因此对其他所有问题都一无所知（例如变体损坏、选项不匹配、metafield 不正确）。明确指出盲区；分诊不等于全面保障。
• 调整目标，不要扩大范围。 结果不足说明需要改进索引（标记其他信号），而不是向模型输入更多原始目录内容。
• 速率限制确实存在。 products 连接会受查询成本限制；在抓取完整目录前，请阅读 references/queries.md 中有关查询成本和并发的说明。

交接格式

输出按缺陷类别分组的排序列表，每行包含：handle、product id、status、具体标记、理由，以及负责修复的关联 FIX skill。图片缺失/不足 → 照片存在后也适用 shopify-alt-text；顺带发现缺少 SEO meta → shopify-seo-metadata；可归档的冗余数据和 $0 草稿 → shopify-catalog-cleanup。

参考资料

• references/queries.md：分页查询 products 的 GraphQL 示例、索引所需字段、查询成本/速率限制说明，以及 Plus 商店的并发说明。
• references/triage-method.md：面向目录工作的通用假设驱动分诊方法。

来源与维护

最后验证时间：2026-07-05。GraphQL 固定为 Admin API 2025-07；Shopify 按滚动季度计划弃用版本，因此在信任特定版本的声明之前，请通过 shopify.dev 验证字段名称和版本。陌生人可以运行以下只读复核，确认令牌能够访问商店，并且审计字段可在实时架构中解析：

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 查询。 本技能记录了文档未涵盖的审计方法；它不能替代参考文档。