用途
AI 购物智能体在解析查询（如“running shoes”“office chair”“sustainable sneakers”）时，会把查询解析到分类法中的一个节点，再检索该节点下的商品。没有标准商品分类法类别的商品对这种映射不可见，只能靠精确关键词碰运气浮现。该技能查找未分类或分类错误的商品，并从标题/类型/标签推断、对照实时分类树确认后，分配正确的 Shopify 标准分类法类别。它修复 category-taxonomy-api，提升 catalog-intent-alignment。
前置条件
已认证的 Shopify CLI 会话（shopify auth login --store <domain>）
所需 API 权限范围：read_products、write_products
参数
所有技能都接受以下通用参数：
参数 | 类型 | 必填 | 默认值 | 说明 store | string | 是 | — | 店铺域名（例如 mystore.myshopify.com） format | string | 否 | human | 输出格式：human（默认）或 json dry_run | bool | 否 | false | 预览变更但不执行
技能专属参数：
参数 | 类型 | 必填 | 默认值 | 说明 collection_id | string | 否 | — | 限定到某个 collection GID tag | string | 否 | — | 限定到某个商品标签 only_missing | bool | 否 | true | 为 true 时只分配没有分类的商品；为 false 时也复核不匹配项 confidence_floor | float | 否 | 0.7 | 跳过最佳分类匹配得分低于此值的商品
安全
⚠️ 第 4 步（productUpdate）会在线上商品上设置分类，影响店铺筛选面（storefront facets）、市场和税务。分类错误会在各处错误归档商品。请先以 dry_run: true 运行，复核“商品 → 分类”的提议映射，只自动分配高于 confidence_floor 的匹配，其余排队等待人工复核。
工作流步骤
操作：products — 查询 输入：first: 250，可选 filter；字段 title、productType、tags、category{ id fullName }；分页。 预期输出：商品及其当前分类（或 null）。
操作：taxonomy — 查询 输入：根据每个商品的 type/title 派生的候选词，搜索标准分类树。 预期输出：可供匹配的候选分类节点（id + fullName）。
计算（无 API）：对每个商品与候选节点评分；选取 ≥ confidence_floor 的最佳项。输出提议映射。
操作：productUpdate — 变更 输入：每个高置信匹配的 { id, category: <taxonomyCategoryId> }。 预期输出：更新后的商品分类；收集 userErrors。
GraphQL 操作
products:query — validated against api_version 2025-01
query TaxonomyProducts($first: Int!, $after: String, $query: String) { products(first: $first, after: $after, query: $query) { edges { node { id title productType tags category { id fullName } } } pageInfo { hasNextPage endCursor } } }
taxonomy:query — validated against api_version 2025-01
query TaxonomySearch($search: String) { taxonomy { categories(first: 20, search: $search) { edges { node { id fullName isLeaf level } } } } }
productUpdate:mutation — validated against api_version 2025-01
mutation TaxonomyAssign($input: ProductInput!) { productUpdate(input: $input) { product { id category { id fullName } } userErrors { field message } } }
会话追踪
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（product, old_category, new_category, confidence），以及低于阈值以下的“needs review”列表。json：{ categorized, needs_review, errors, output_file }。
错误处理
错误 | 原因 | 恢复 THROTTLED | API 速率限制 | 等待 2 秒，最多重试 3 次 No taxonomy match | 小众/含糊商品 | 加入 needs-review 列表，不要猜测 userErrors on update | 无效分类 id | 记录、跳过、继续
最佳实践
选择你最有把握的最具体（叶子）节点——智能体对更深层分类的匹配比顶层分类更精确。
第一遍保持 only_missing: true；重新分类已有分配风险更高，最好先人工复核。
让分类与店铺 collection 对齐会叠加收益：智能体与站内筛选器随后保持一致。
重新运行 shopify-admin-agentic-readiness-audit 以确认 Matchable 支柱有所改善。