shopify-category-taxonomy

Shopify 类目分类体系

两个衔接的任务：分配产品的标准产品分类体系类目（第 1 部分），然后填写该类目提供的类目元字段（第 2 部分）。只有完成第 1 部分后才能进行第 2 部分：只有在产品分配到某个类目后，才会显示“类目元字段”面板。批量 CSV 数据处理请使用同级目录中的 shopify-matrixify；Matrixify 无法创建第 2 部分所需的保留值元对象，这正是此技能存在的全部原因。

店铺访问权限

方式 A：自定义应用令牌（可脚本化）。 Shopify 管理后台 → 设置 → 应用和销售渠道 → 开发应用 → 创建应用 → 授予以下四项权限 → 安装 → 复制 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 } }"}'

最低权限范围：read_products、write_products、read_metaobjects、write_metaobjects。 元对象权限不可省略（参见 null 陷阱）。

方式 B：Shopify CLI OAuth（不存储令牌）。 运行 shopify store auth --store $SHOPIFY_STORE --scopes read_products,write_products,read_metaobjects,write_metaobjects ，然后运行 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；此技能为其提供操作指南。

操作示例，而非脚本

将每个 GraphQL 代码块视为由 Agent 重新编写、运行后即丢弃的复制改编示例。遵循两条规则，确保安全：

1. 先预览，再修改。 每次写入前，都要只读统计目标类目中的产品数量并进行合理性检查。如果数量远超预期，请停止操作并重新限定范围。
2. 默认不破坏现有数据。 仅填写缺失值；metafieldsSet 中的空值会删除元字段，因此只输出非空值。首批数据出现 userErrors 时立即中止运行。

请通过 Admin API 而非店面验证实际数据（CDN 缓存会导致数据不够新）。切勿打印或提交令牌。

第 1 部分：分配类目

通过 productUpdate 将每个产品的 category 字段设为标准产品分类体系中的类目（如果只是纯批量加载，也可以使用 Matrixify 的 Category 列）。

关键：务必根据官方分类体系来源核实每个类目 ID；切勿猜测 ID。 猜测的分类体系 ID 会对应到错误类目或已失效的节点，而且会静默失败：产品看起来已经分类，但后续所有属性、筛选器和商品 Feed 映射都会出错。错误猜测的 ID 已导致真实商品 Feed 出现问题。请通过 search: 在 taxonomy { categories } 中查询 ID（第 2 部分的步骤 1 展示了查询语句），或从“来源”部分链接的官方分类体系仓库中查找。

分类信号优先级（从高置信度到低置信度）： 标签（对于按类目打标签的店铺，置信度最高：标记为 black-tea 的“Mango”茶是调味红茶，而非水果浸泡茶；标题可能误导，但标签能说明这一点）> 产品类型（店铺有填写时很有用，但很多店铺不会填写）> 标题 / 供应商（词汇层面的后备依据；单一产品线的供应商可以锁定类目，多产品线的则不能）> 描述（最后手段；描述冗长，容易被口味相关词语误导）。

为每个产品标注置信度，并将商品目录分成高置信度和有歧义两类（套装、试用装、跨类目商品）。发布高置信度的行；将有歧义的行交给人工审核表处理，而不是猜测。请参阅下方 SOP 中的“先提取，再分类”步骤。

# preview (read-only): how many products your classifier targets, before any write
query { productsCount(query: "tag:black-tea status:active") { count } }

# then, per high-confidence product, assign the category
mutation Assign($id: ID!, $cat: ID!) {
  productUpdate(product: {id: $id, category: $cat}) {
    product { id category { id fullName } }
    userErrors { field message }
  }
}

第 2 部分：填写类别元字段

类别元字段不是纯文本／选项值。它是保留在 shopify 命名空间中的元字段，类型为 list.metaobject_reference，其值是一个包含 Metaobject GID 的 JSON 数组。每个此类元对象都是 保留的分类法值（type: "shopify--<attribute>"），包含 label，以及一个指向全局 TaxonomyValue 的 taxonomy_reference。其关联链如下：

Product
  └─ metafield  shopify.<attribute>  (list.metaobject_reference)
       └─ value: ["gid://shopify/Metaobject/…"]
            └─ Metaobject  type: shopify--<attribute>   label: "Decaf"
                 └─ taxonomy_reference ─▶ TaxonomyValue/26137  (global)

这些值元对象会按需创建：商店只保存实际用过的值对应的元对象。必须先创建全新的值，才能引用它。Matrixify 无法完成的正是这一步先创建、再引用的流程。

最容易踩的 5 个坑（更完整的列表请参阅参考资料）：

1. 空值／权限范围陷阱。 没有 read_metaobjects 权限时，node()、references 和 metaobjectDefinitions 会返回 null：整个功能看起来都像是只读的。添加该权限后，这些对象才会正常解析。创建对象需要 write_metaobjects 权限。
2. 写入时会拒绝 TaxonomyValue GID。 metafieldsSet 要求的是 Metaobject GID，而不是分类法值 GID（否则会报错 “Value require that you select a metaobject”）。只有在创建元对象时，才会将 TaxonomyValue GID 作为 taxonomy_reference 传入。
3. 产品必须已归入该类别，否则元字段不会显示为类别元字段。范围筛选依据是 product.category，而不是产品类型或标题。
4. GID 是商店专属的。 在一个商店中创建的元对象 GID 无法迁移到另一个商店。每个商店都要重新创建。
5. Matrixify 无法创建这些对象。 它无法创建保留的元对象，也无法解析值名称。Admin API 是唯一可靠的途径。

标准操作流程

1. 查找类别、其属性和允许的值。

query {
  taxonomy {
    categories(first: 1, search: "Tea & Infusions > Tea") {
      nodes {
        id fullName
        attributes(first: 50) {
          nodes {
            ... on TaxonomyChoiceListAttribute {
              id name
              values(first: 50) { nodes { id name } }   # id = TaxonomyValue GID
            }
            ... on TaxonomyMeasurementAttribute { id name }
          }
        }
      }
    }
  }
}

对每个属性记录：元字段键（属性句柄，转换为小写并以连字符分隔；在第 6 步中读取一个已设置该属性的产品进行确认；Color 属性的键是 color-pattern，不是 color），以及值名称 → TaxonomyValue GID 映射。

2. 拉取目录，并限定在目标类别范围内。 不要在未充分了解的情况下分类：先遍历每个候选产品，采集分类器会读取的信号。

query($cursor: String) {
  products(first: 100, after: $cursor, query: "status:active") {
    pageInfo { hasNextPage endCursor }
    nodes {
      id handle title vendor productType tags
      category { id fullName }
      options { name optionValues { name } }
      metafields(namespace: "shopify", first: 25) { nodes { key jsonValue } }
    }
  }
}

如果目录很大，可将此操作改为通过 bulkOperationRunQuery 导出，而不是实时分页；此导出同时也是写入前的备份。

3. 分类为高置信度和有歧义的产品。 按信号优先级处理（先看标签）。为每个产品输出一个置信度标记；高置信度的产品直接处理，有歧义的产品（捆绑产品、采样套装、跨类别产品、标题信号较弱的产品）则放入审核表格，由人工在写入任何内容之前进行修正。正是这种拆分方式，让一家茶叶零售商无需猜测，就能将 717 件产品中的 583 件 作为高置信度产品处理，并将剩余 134 件留待审核。现在为高置信度产品分配类别（第 1 部分）；然后继续执行下文的创建和设置步骤。

4. 创建每个缺失的值元对象（每个商店只需一次）。 如果现有元对象的 label 已匹配，则重复使用；只有确实不存在时才创建。

mutation M($m: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $m) {
    metaobject { id displayName } userErrors { field message code }
  }
}
# variables:
# {"m":{"type":"shopify--caffeine-content","handle":"decaf",
#   "fields":[{"key":"label","value":"Decaf"},
#             {"key":"taxonomy_reference","value":"gid://shopify/TaxonomyValue/26137"}]}}

根据结果和现有条目构建 值名称 → Metaobject GID 映射。

5. 使用 metafieldsSet 应用设置，每次调用最多处理 25 个元字段。

mutation S($m: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $m) {
    metafields { id } userErrors { field message code }
  }
}
# each entry: {ownerId, namespace:"shopify", key:"tea-variety",
#   type:"list.metaobject_reference",
#   value:"[\"gid://shopify/Metaobject/…\"]"}

只输出非空值。第一批出现错误时立即中止。

6. 读取并验证解析后的标签，不要仅凭写入结果中的 userErrors: [] 就认定成功。

query { product(id: "gid://shopify/Product/…") {
  metafields(namespace: "shopify", first: 10) { nodes {
    key references(first: 5) { nodes { ... on Metaobject { displayName } } } } } } }

抽查若干产品；确认每个名称都解析为预期值。

参考资料

• references/gotchas-and-scoping.md： 陷阱 6–10（自由填写的标签、按类型设置的创建字段、多类别范围）， 各属性会出现在哪些位置（Google 商品 Feed、Search & Discovery 还是 JSON-LD），以及两个包含实际数字的完整示例。

来源与维护

最后验证日期：2026-07-05。GraphQL 固定使用 Admin API 2025-07；Shopify 按季度滚动计划弃用版本，因此在信任特定版本的声明之前，请对照 shopify.dev 以及 metafields/metaobjects 文档核实字段结构。类别 ID 和分类值来自 Shopify 的 Standard Product Taxonomy：这是核实 ID 的权威来源；切勿猜测。

任何人都可以运行的只读复核（不执行写入）：

# 1. token reaches the store and reads a product's assigned category
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:1){ nodes{ category { id name } } } }"}'

# 2. taxonomy discovery resolves (confirms the taxonomy API + your read scope)
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":"{ taxonomy { categories(first:1, search:\"Tea\"){ nodes{ id fullName } } } }"}'

这些技能记录了文档未涵盖的操作经验；它们不能替代参考文档。