product-tag-bulk-update

用途

该技能用于在 Shopify 后台对一组商品批量添加或移除一个或多个标签，替代逐一手动编辑商品的方式。典型用途包括：活动上线前为某个集合添加 summer-sale 标签、活动结束后移除 flash-sale 标签，或在商品跨分类迁移时重新打标签。由于标签会驱动集合规则、营销分群和报表筛选，批量操作的准确性很重要。它可替代 Shopify 后台的手动批量编辑以及 CSV 导入导出流程。

主要能力

支持 action: add 或 action: remove 两种操作。
支持一次传入多个标签，例如 ["summer-sale", "clearance"]。
支持三种目标筛选方式（三选一）：collection_id（集合 GID，定位该集合内全部商品）、filter_tag（定位当前带有该标签的全部商品）、query_filter（Shopify 商品搜索查询，例如 "product_type:Apparel"）。
自动分页，直到获取全部匹配商品。
支持 dry_run 预览，在提交前查看完整商品列表。
输出 CSV 文件 tag-update-<YYYY-MM-DD>.csv，列为 product_id、product_title、action、tags_changed、previous_tags、result。
支持 human（默认）与 json 两种输出格式，并输出分阶段会话跟踪信息。

使用方式

前置条件：

shopify auth login --store <domain>

API 权限范围：read_products、write_products。

参数：

通用参数（store、format、dry_run）以及技能专属参数：

action：字符串，必填，取值为 add 或 remove。
tags：数组，必填，要添加或移除的一个或多个标签字符串。
collection_id：字符串，非必填（三选一），集合的 GID，定位该集合内全部商品。
filter_tag：字符串，非必填（三选一），定位当前带有该标签的全部商品。
query_filter：字符串，非必填（三选一），Shopify 商品搜索查询。

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

工作流程：

执行 products 查询：first: 250，query 由 collection_id、filter_tag 或 query_filter 构建，分页直到获取全部匹配商品。预期输出为商品 GID 列表及当前标签数组，在继续前确认目标集合。
若 action 为 add，执行 tagsAdd 变更；若 action 为 remove，执行 tagsRemove 变更。每个商品传入 id 与 tags 数组，预期输出为更新后的 node.id 及 userErrors。

GraphQL 操作（已针对 api_version 2025-01 验证）：

# products:query
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
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

# tagsRemove:mutation
mutation TagsRemove($id: ID!, $tags: [String!]!) {
  tagsRemove(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪：技能在每个阶段输出跟踪信息。开始时输出包含技能名、店铺域名和开始时间的方框；每步之后输出 [N/TOTAL] 及操作名、参数摘要、结果摘要；若 dry_run 为 true，每个变更步骤前加 [DRY RUN] 前缀且不执行；完成时按 human 格式输出结果摘要，或按 json 格式输出包含 skill、store、started_at、completed_at、dry_run、steps、outcome 的 JSON 对象。

适用场景

活动上线：在发布前为某个集合批量添加活动标签。
活动下线：活动结束后批量移除活动标签。
目录整理：为在分类之间迁移的商品重新打标签。
清理旧活动：使用 query_filter: "tag:old-campaign-name" 精确定位上一次运行打过标签的商品。

限制与注意事项

tagsRemove 不可逆：若移除了错误的标签，必须手动重新添加，或再次运行本技能并设置 action: add。
对于大型目录（1000+ 商品），在任何移除操作前强烈建议先使用 dry_run。
标签最大长度为 255 个字符，且不允许包含逗号。
若筛选条件未匹配到任何商品，需检查集合 GID 或 filter_tag 拼写。
移除不存在的标签时会被静默跳过（对不存在的标签执行 tagsRemove 是无操作）。
商品数量很大（1000+）时需要多次 API 调用进行分页，属于预期行为，可能耗时更长。
Shopify 集合规则中的标签不区分大小写，但 API 中保留大小写，建议使用一致的大小写以避免出现 Sale 与 sale 这类重复。
建议在活动开始时运行 action: add、结束时运行 action: remove，以保持商品标签整洁，防止集合规则漂移。
可一次传入多个标签，例如 tags: ["sale", "homepage-featured", "clearance"]，原子性地应用全部三个标签。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项