shopify-admin-product-tag-bulk-update

用途

该技能用于在 Shopify 后台对一批商品批量添加或移除一个或多个标签，替代逐个商品手动编辑的方式。典型用途包括：

活动设置：在活动上线前为某个集合添加如 summer-sale 的标签。
活动清理：活动结束后移除如 flash-sale 的标签。
目录重组：为在分类之间移动的商品重新打标签。

标签会驱动集合规则、营销分群和报表筛选，因此批量操作的准确性很重要。该技能可替代 Shopify 后台的手动批量编辑以及 CSV 导入导出流程。

前置条件

登录命令：shopify auth login --store <domain>
API 权限范围：read_products、write_products

参数

通用参数（store、format、dry_run）之外，技能特有参数如下：

参数	类型	必填	默认值	说明
action	string	是	—	add 或 remove
tags	array	是	—	要添加或移除的一个或多个标签字符串（例如 ["summer-sale", "clearance"]）
collection_id	string	否*	—	集合的 GID，定位该集合中的所有商品
filter_tag	string	否*	—	定位当前带有该标签的所有商品
query_filter	string	否*	—	Shopify 商品搜索查询（例如 "product_type:Apparel"）

*collection_id、filter_tag、query_filter 三者必须提供其一。

安全提示

第 2 步会执行批量标签变更。tagsRemove 不可逆——如果移除了错误的标签，必须手动重新添加，或再次运行本技能并使用 action: add。建议先以 dry_run: true 运行，查看完整商品列表后再提交。对于大型目录（1000+ 商品），在任何移除操作前强烈建议先执行 dry_run。

工作流程

OPERATION: products — query
- 输入：first: 250，查询由 collection_id、filter_tag 或 query_filter 构建；分页直到获取所有匹配商品。
- 预期输出：商品 GID 列表及当前标签数组；在继续之前确认目标集合。
OPERATION: tagsAdd — mutation（当 action: add 时）
- 输入：每个商品 id: <productId>、tags: <tags array>。
- 预期输出：更新后的 node.id 及 userErrors。
或

OPERATION: tagsRemove — mutation（当 action: remove 时）
- 输入：每个商品 id: <productId>、tags: <tags array>。
- 预期输出：更新后的 node 及 userErrors。

GraphQL 操作

# products:query — validated against api_version 2025-01
query ProductsForTagUpdate($first: Int!, $after: String, $query: String) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        tags
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# tagsAdd:mutation — validated against api_version 2025-01
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

# tagsRemove:mutation — validated against api_version 2025-01
mutation TagsRemove($id: ID!, $tags: [String!]!) {
  tagsRemove(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: product-tag-bulk-update              ║
║  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, e.g., "143 records returned">

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

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Products targeted:    <count>
  Tags added/removed:   <tags list>
  Action:               <add|remove>
  Errors:               <count, 0 if none>
  Output:               <filename or "none">
══════════════════════════════════════════════

对于 format: json，输出符合以下 schema 的 JSON 对象：

{
  "skill": "product-tag-bulk-update",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query|mutation",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "action": "<add|remove>",
    "tags": ["<tag1>", "<tag2>"],
    "products_targeted": 0,
    "mutations_succeeded": 0,
    "errors": 0,
    "output_file": "<filename|null>"
  }
}

输出格式

CSV 文件 tag-update-<YYYY-MM-DD>.csv，列包括：product_id、product_title、action、tags_changed、previous_tags、result。

错误处理

错误	原因	恢复方式
未返回商品	筛选条件无匹配	检查集合 GID 或 filter_tag 拼写
tagsAdd/tagsRemove 返回 userErrors	标签字符串过长或包含无效字符	Shopify 标签最大长度为 255 个字符；不允许逗号
商品数量庞大（1000+）	分页需要大量 API 调用	属预期情况——技能会自动分页；可能耗时较长
标签不存在（移除时）	商品没有要移除的标签	静默跳过——对不存在的标签执行 tagsRemove 是无操作

最佳实践

在任何 action: remove 之前先运行 dry_run: true——CSV 预览会准确显示哪些商品将失去该标签。
为了干净地设置活动，在启动时运行 action: add，在结束时运行 action: remove——保持商品标签整洁可防止集合规则漂移。
使用 query_filter: "tag:old-campaign-name" 进行清理——它会精确找到上一次运行中打过标签的商品。
可以在一次运行中添加多个标签——传入 tags: ["sale", "homepage-featured", "clearance"] 可原子性地应用全部三个标签。
标签在 Shopify 集合规则中不区分大小写，但在 API 中保留大小写——使用一致的大小写以避免出现 Sale 和 sale 这样的重复项。