shopify-admin-agentic-metafields-setup

用途

AI 智能体通过结构化属性来回答受限查询，例如“60 美元以下的防深蹲走光紧身裤”“桉树材质一脚蹬”“可机洗羊毛”。如果这些属性只存在于商品描述文本中（或根本不存在），智能体就无法进行筛选，商品会从结果集中掉出。本技能建立一套小而标准的智能体元字段定义（材质、关键特性、护理、合身度、规格），并从现有商品信号中推断并填充到整个商品目录，使智能体能够将商品与需求匹配。它修复了商品列表元字段、变体元数据和结构化尺码规格等问题。

前置条件

已认证的 Shopify CLI 会话（shopify auth login --store <domain>）
所需 API 权限范围：read_products、write_products、read_metaobject_definitions、write_metaobject_definitions（用于定义）

参数

所有技能都接受以下通用参数：

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human（默认）或 json
dry_run	bool	否	false	预览变更而不实际执行

技能专属参数：

参数	类型	必填	默认值	说明
namespace	string	否	agentic	要创建/填充的元字段命名空间
keys	string	否	material,features,care,fit,specs	需确保存在的元字段键的逗号列表
collection_id	string	否	—	将填充范围限制到某个集合 GID
tag	string	否	—	将填充范围限制到某个商品标签
populate_from	string	否	tags,options,description	用于推断值的来源（不得超出这些来源进行编造）

安全性

⚠️ 第 2 步（metafieldDefinitionCreate）和第 4 步（metafieldsSet）会写入店铺架构和商品数据。添加定义成本低，但如果命名空间错误会弄乱后台；从推断写入的值可能出错。请运行 dry_run: true，审查建议的定义和值预览，只填充高置信度推断出的值——其余留空供人工填写。

工作流步骤

OPERATION: metafieldDefinitions — 查询
- 输入：ownerType: PRODUCT, namespace: <namespace>
- 预期输出：哪些目标键已有定义（跳过这些）。
OPERATION: metafieldDefinitionCreate — 变更
- 输入：每个缺失的键一条：{ namespace, key, name, ownerType: PRODUCT, type: "single_line_text_field" | "list.single_line_text_field" }
- 预期输出：已创建的定义；收集 userErrors（例如已被占用）。
OPERATION: products — 查询
- 输入：first: 250，可选 filter；字段 tags、options、descriptionHtml、existing metafields(namespace)；分页。
- 预期输出：商品 + 用于推断属性值的信号。
OPERATION: metafieldsSet — 变更
- 输入：批量 { ownerId, namespace, key, value, type }，针对高置信度推断且当前为空的值。
- 预期输出：设置元字段；收集 userErrors。

GraphQL 操作

# metafieldDefinitions:query — validated against api_version 2025-01
query AgenticMetafieldDefs($namespace: String!) {
  metafieldDefinitions(first: 50, ownerType: PRODUCT, namespace: $namespace) {
    edges { node { id namespace key name type { name } } }
  }
}

# metafieldDefinitionCreate:mutation — validated against api_version 2025-01
mutation AgenticMetafieldDefCreate($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition { id namespace key }
    userErrors { field message code }
  }
}

# products:query — validated against api_version 2025-01
query AgenticMetafieldProducts($first: Int!, $after: String, $query: String, $namespace: String!) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        tags
        options { name values }
        descriptionHtml
        metafields(first: 20, namespace: $namespace) {
          edges { node { key value } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# metafieldsSet:mutation — validated against api_version 2025-01
mutation AgenticMetafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields { id namespace key }
    userErrors { field message code }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容。这是强制性的。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: <skill name>                         ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每一步之后输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

如果 dry_run: true，则在每个变更步骤前加 [DRY RUN] 前缀，并且不执行它。

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  <Metric label>:   <value>
  Errors:           0
  Output:           <filename or "none">
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "<skill-slug>",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "metric_key": 0,
    "errors": 0,
    "output_file": null
  }
}

输出格式

human：已创建的定义 + 已填充值的 CSV（商品、键、值、来源）。
json：{ definitions_created, metafields_set, products_touched, errors, output_file }。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制	等待 2 秒，最多重试 3 次
TAKEN on definition	键已在别处定义	复用现有定义，继续填充
userErrors on set	类型不匹配（例如列表 vs 单值）	将值强制转换为定义的类型，重试一次，否则跳过

最佳实践

保持命名空间小而标准（agentic），键集合紧凑——智能体和店面筛选器都能从一致性中受益。
只写入能从真实信号中高置信度推断的值；错误的“material: leather”会误导每一个智能体。低置信度字段留空。
对多值属性（特性、材质）使用 list.single_line_text_field，以便筛选器作为 OR 集合工作。
随后使用 shopify-admin-agentic-description-enrichment，使描述文本与结构化数据保持一致。