用途
该技能对通过查询过滤器（例如 total_spent:>=500、tag:newsletter）或显式客户 GID 列表选中的客户，批量应用标签变更（添加、移除或两者兼有）。标签是 Shopify 用于折扣、营销和支持工作流中划分客户群的方式；该技能使批量变更安全、可预演且可审计。适用于从一种标签分类法迁移到另一种、淘汰特定活动标签，或应用由分析报告识别出的新分群标签。
前置条件
已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_customers,write_customers
API 权限范围：read_customers、write_customers
参数
store：字符串，必填，无默认值，店铺域名（例如 mystore.myshopify.com）。
format：字符串，可选，默认 human，输出格式：human 或 json。
dry_run：布尔值，可选，默认 true，预览匹配客户与计划标签变更而不执行变更。
filter：字符串，条件必填，无默认值，客户查询过滤器（例如 tag:newsletter、total_spent:>=500）；省略 customer_ids 时必填。
customer_ids：数组，条件必填，无默认值，显式客户 GID 列表；省略 filter 时必填。
add_tags：数组，可选，默认 []，要添加的标签（与现有标签取并集）。
remove_tags：数组，可选，默认 []，要移除的标签（集合差集）。
mode：字符串，可选，默认 merge，标签写入模式：merge（在现有标签上应用添加/移除）或 replace（仅用 add_tags 完全覆盖标签）。
max_customers：整数，可选，默认 1000，运行规模上限；若过滤器匹配数量超过此值则中止。
安全性
⚠️ 第 2 步会对匹配集合中的每个客户执行一次 customerUpdate 变更。标签变更立即生效，并对员工以及任何读取客户标签的应用（忠诚度、营销自动化、分群）可见。mode: replace 会完全覆盖现有标签——手动应用的操作标签将丢失。默认值为 dry_run: true 和 mode: merge。务必先运行 dry-run，检查匹配数量，并确认 add_tags/remove_tags 拼写正确——Shopify 标签区分大小写。
工作流步骤
OPERATION: customers — query 输入：当设置 filter 时：query: <filter>、first: 250、分页游标。当设置 customer_ids 时：使用 query: "id:<id1> OR id:<id2> ..." 进行批量查询（按 25 个 ID 分块）。选择 id、displayName、defaultEmailAddress { emailAddress }、tags。 预期输出：带当前标签的客户列表。若 match_count > max_customers 则中止。
对每个匹配客户计算目标标签集：
若 mode: merge：target = (existing ∪ add_tags) \ remove_tags
若 mode: replace：target = add_tags（忽略 remove_tags） 若 target == existing（无操作）则跳过该客户。
OPERATION: customerUpdate — mutation 输入：对每个存在非空差异的客户：input: { id: <customer_id>, tags: <target_tag_array> } 预期输出：customer.id、customer.tags、userErrors；收集失败项。
GraphQL 操作
customers:query — validated against api_version 2025-01
query CustomersForBulkTagging($query: String!, $after: String) { customers(first: 250, after: $after, query: $query) { edges { node { id displayName firstName lastName defaultEmailAddress { emailAddress } tags numberOfOrders amountSpent { amount currencyCode } } } pageInfo { hasNextPage endCursor } } }
customerUpdate:mutation — validated against api_version 2025-01
mutation CustomerTagsUpdate($input: CustomerInput!) { customerUpdate(input: $input) { customer { id displayName tags } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制性的。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Bulk Customer Tag 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>
若 dry_run: true，则为每个变更步骤添加 [DRY RUN] 前缀，且不执行它。
完成时输出：
对于 format: human（默认）：
══════════════════════════════════════════════ BULK TAG UPDATE OUTCOME Filter: <filter or "<n> explicit IDs"> Mode: <merge|replace> Add tags: <list> Remove tags: <list> Customers matched: <n> Customers updated: <n> (or "skipped — dry_run") No-op (already in state): <n> Errors: <n> Output: bulk_tag_update_<date>.csv ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "bulk-customer-tag-update", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": true, "mode": "merge", "outcome": { "matched": 0, "updated": 0, "noop": 0, "errors": 0, "add_tags": [], "remove_tags": [], "output_file": "bulk_tag_update_<date>.csv" } }
输出格式
CSV 文件 bulk_tag_update_<YYYY-MM-DD>.csv，包含列： customer_id, name, email, previous_tags, tags_added, tags_removed, new_tags, status
status 列报告 updated、noop 或 error: <message>。
错误处理
THROTTLED：API 速率限制超出。恢复：等待 2 秒，最多重试 3 次。
customerUpdate 上的 userErrors：无效输入或只读客户。恢复：记录错误，跳过客户，继续。
match_count > max_customers：过滤器过于宽泛。恢复：细化过滤器或有意识地提高 max_customers。
filter 和 customer_ids 均为空：无选择。恢复：以参数错误中止。
标签为空字符串：仅空白条目。恢复：去除空白并跳过空值。
大小写不匹配的 remove_tag：标签区分大小写。恢复：使用精确大小写重新运行。
最佳实践
始终先以 dry_run: true 运行——在提交前检查匹配数量以及 previous_tags → new_tags 差异的样本。
几乎所有用例都优先使用 mode: merge（默认）——mode: replace 仅适用于完全重置客户的标签分类法，并且你拥有先前标签的审计备份。
标签区分大小写：VIP 和 vip 在 Shopify 中不同。在分类法中标准化大小写。
对于持续运营的分群，优先使用带日期的标签名（例如 cohort-2026-Q2），以便在新标签累积时历史群组仍可识别。
与 vip-customer-identifier 或 customer-spend-tier-tagger 配合，将分析输出中的分群标签写入客户记录。
在活动结束后使用 remove_tags 作为清理步骤——遗留的过时活动标签会扰乱营销工具中的分群。
当直接提供 customer_ids 时（例如来自另一技能的 CSV），运行完全确定——没有过滤器歧义。