用途
该技能按订单数量和累计消费金额筛选出最高价值客户，在 Shopify 中为其打标签，并导出可直接用于忠诚度计划注册或 VIP 营销活动的联系人列表。它只负责数据层；管理奖励积分或发送忠诚度邮件需要外部工具。
主要能力
- 按最低订单数（min_orders，默认 3）和最低累计消费（min_spend，默认 200，店铺货币）筛选客户。
- 对符合条件的客户应用指定标签（tag，默认 loyalty-vip）。
- 支持 dry_run 预览，不实际打标签。
- 输出 CSV 文件 loyalty_segment_<YYYY-MM-DD>.csv，列包括 customer_id、email、first_name、last_name、orders_count、total_spent、currency、tag_applied。
- 支持 human 或 json 输出格式。
- 分页查询客户，直到 hasNextPage 为 false。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：shopify auth login --store <domain>
- API 权限范围：read_customers、write_customers
参数：
- store（字符串，必填）：店铺域名。
- format（字符串，可选，默认 human）：human 或 json。
- dry_run（布尔，可选，默认 false）：预览而不打标签。
- min_orders（整数，可选，默认 3）：最低累计订单数。
- min_spend（浮点数，可选，默认 200）：最低累计消费（店铺货币）。
- tag（字符串，可选，默认 loyalty-vip）：应用于符合条件客户的标签。
工作流程：
- customers 查询：使用过滤条件 orders_count:>=(min_orders)、total_spent:>=(min_spend)，first: 250，分页获取客户列表，字段包括 id、defaultEmailAddress { emailAddress }、firstName、lastName、ordersCount、totalSpentV2，直到 hasNextPage: false。
- tagsAdd 变更：对每个客户 ID 应用 tag 参数中的标签，收集 userErrors。
GraphQL 操作：
customers:query — validated against api_version 2025-04
query LoyaltyCustomers($first: Int!, $after: String, $query: String) { customers(first: $first, after: $after, query: $query) { edges { node { id defaultEmailAddress { emailAddress } firstName lastName ordersCount totalSpentV2 { amount currencyCode } 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 } } }
会话跟踪： Claude 必须在每个阶段输出以下内容，这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Loyalty Segment Export ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
每步之后输出：
[N/TOTAL] <QUERY|MUTATION> <OperationName> → Params: <brief summary> → Result: <count or outcome>
如果 dry_run: true，则在变更步骤前加 [DRY RUN] 前缀，且不执行。
完成时，对于 format: human：
══════════════════════════════════════════════ OUTCOME SUMMARY VIP customers found: <n> Customers tagged: <n> Errors: <n> Output: loyalty_segment_<date>.csv ══════════════════════════════════════════════
对于 format: json，输出标准 JSON schema，包含 outcome 键：vip_customers_found、customers_tagged、errors、output_file。
错误处理：
- THROTTLED（速率限制）：等待 2 秒，最多重试 3 次。
- tagsAdd 上的 userErrors（无效客户 ID）：记录、跳过、继续。
适用场景
- 识别高 LTV 客户并为其打标签，用于忠诚度计划注册或 VIP 营销活动。
- 结合 customer-win-back 技能，将高 LTV 流失客户同时打上 loyalty-vip 和 win-back 标签，识别最高优先级的重新互动目标。
限制
- 该技能仅处理数据层；管理奖励积分或发送忠诚度邮件需要外部工具。
- 需要已认证的 Shopify CLI 会话和 read_customers、write_customers 权限。
- 运行前建议检查客户是否已有 loyalty 标签，可在查询过滤条件中添加 NOT tag:loyalty-vip 以跳过已注册客户。
- 如果不确定阈值，建议先使用 dry_run: true 查看数量，再调整 min_orders 和 min_spend 后提交。