customer-note-bulk-annotator

用途

该技能查询符合筛选条件（标签、邮箱列表或消费阈值）的客户，并向每个客户记录追加备注。内部备注在 Shopify 后台对员工可见，但客户不可见。用于活动后标记、导入来源追踪、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 运行以在提交前确认客户列表。

工作流程步骤

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

GraphQL 操作

# customers:query — validated against 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 — validated against 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 次
userErrors on customerUpdate	输入无效或客户记录只读	记录错误，跳过该客户，继续
无客户匹配筛选条件	筛选条件过窄	以 0 匹配退出

最佳实践

除非明确打算覆盖现有备注，否则始终使用 append: true —— 员工备注可能包含重要历史记录。
在备注文本本身中包含日期戳（例如 "2026-04-11: Campaign X participant"），以便备注在数月后仍可理解。
使用 dry_run: true 在批注前确认客户数量 —— 宽泛的筛选可能意外匹配数千名客户。
对于导入来源追踪，在导入运行后立即批注，以保持清晰的审计追踪。

技能介绍