shopify-admin-customer-note-bulk-annotator

用途

该技能按筛选条件查询匹配的客户，并向每个客户记录追加一条备注。内部备注在 Shopify Admin 中对员工可见，但客户不可见。可用于活动后标注、导入来源追踪、VIP 标记或客服上下文记录。

前置条件

需要已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_customers,write_customers

API 权限范围：read_customers、write_customers

参数

store（string，必填，无默认值）：店铺域名，例如 mystore.myshopify.com

filter（string，必填，无默认值）：客户筛选查询，例如 tag:vip、total_spent:>=500

note（string，必填，无默认值）：要追加到匹配客户的备注文本

append（bool，可选，默认 true）：追加到现有备注（true）或完全替换（false）

dry_run（bool，可选，默认 true）：预览匹配客户而不执行变更

format（string，可选，默认 human）：输出格式，human 或 json

安全提示

⚠️ 若 append: false，将完全覆盖现有客户备注，现有备注会丢失。默认 append: true 会安全地以时间戳前缀追加。建议先以 dry_run: true 运行，确认客户列表后再提交。

工作流程

OPERATION: customers — 查询输入：query: <filter>、first: 250、选择 id、displayName、note、分页游标预期输出：匹配客户及其现有备注；分页直到 hasNextPage: false
构造新备注：若 append: true，在现有备注前加上 [YYYY-MM-DD] <note>（以换行分隔）；若 append: false，则替换为 <note>
OPERATION: customerUpdate — 变更输入：id: <customer_id>、note: <new_note> 预期输出：customer { id, note }、userErrors

GraphQL 操作

customers:query — 已针对 api_version 2025-01 验证

query CustomersByFilter($query: String!, $after: String) { customers(first: 250, after: $after, query: $query) { edges { node { id displayName defaultEmailAddress { emailAddress } note tags } } pageInfo { hasNextPage endCursor } } }

customerUpdate:mutation — 已针对 api_version 2025-01 验证

mutation CustomerUpdateNote($input: CustomerInput!) { customerUpdate(input: $input) { customer { id displayName note } userErrors { field message } } }

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗ ║ SKILL: Customer Note Bulk Annotator ║ ║ 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 Customers matched: <n> Notes updated: <n> Errors: <n> Output: annotation_log_<date>.csv ══════════════════════════════════════════════

format: json 时输出：

{ "skill": "customer-note-bulk-annotator", "store": "<domain>", "started_at": "<ISO8601>", "dry_run": true, "filter": "<query>", "note": "<text>", "append": true, "outcome": { "matched": 0, "updated": 0, "errors": 0, "output_file": "annotation_log_<date>.csv" } }

输出格式

CSV 文件 annotation_log_<YYYY-MM-DD>.csv，列包括：customer_id、name、email、previous_note、new_note

错误处理

THROTTLED：API 速率限制超出。恢复方式：等待 2 秒，最多重试 3 次。

customerUpdate 上的 userErrors：输入无效或客户为只读。恢复方式：记录错误，跳过该客户，继续执行。

无客户匹配筛选条件：筛选条件过窄。恢复方式：以 0 匹配退出。

最佳实践

除非明确打算覆盖现有备注，否则始终使用 append: true——员工备注可能包含重要历史记录。

在备注文本本身包含日期戳（例如 "2026-04-11: Campaign X participant"），以便数月后备注仍可解读。

使用 dry_run: true 在标注前确认客户数量——宽泛的筛选条件可能意外匹配数千名客户。

对于导入来源追踪，在导入运行后立即标注，以保持清晰的审计轨迹。

技能介绍

customers:query — 已针对 api_version 2025-01 验证

customerUpdate:mutation — 已针对 api_version 2025-01 验证