用途
扫描所有客户记录，报告电子邮件和短信营销同意状态的分布情况（已订阅、已退订、待确认、从未询问）。用于合规审计、GDPR/CAN-SPAM 审查，以及了解可触达的营销受众规模。只读——不执行任何变更。
前置条件
已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_customers
API 权限范围：read_customers
参数
store（字符串，必填，无默认值）：店铺域名（例如 mystore.myshopify.com）
channel（字符串，可选，默认 both）：要审计的同意渠道，可选 email、sms 或 both
format（字符串，可选，默认 human）：输出格式，可选 human 或 json
安全性
只读技能——不执行任何变更，可随时安全运行。
工作流程
-
操作 customers——查询。输入：first: 250，选择 emailMarketingConsent { marketingState, consentUpdatedAt }、smsMarketingConsent { marketingState, consentUpdatedAt }、分页游标。预期输出：所有客户的同意状态；持续分页直到 hasNextPage: false。
-
按每个渠道的同意状态统计客户数量。
-
计算：可触达受众（已订阅）、风险中（待确认）、不可触达（已退订/未询问）。
GraphQL 操作
customers:query——已针对 api_version 2025-01 验证：
query MarketingConsentAudit($after: String) { customers(first: 250, after: $after) { edges { node { id displayName defaultEmailAddress { emailAddress } emailMarketingConsent { marketingState consentUpdatedAt marketingOptInLevel } smsMarketingConsent { marketingState consentUpdatedAt } } } pageInfo { hasNextPage endCursor } } }
会话跟踪
Claude 必须在每个阶段输出以下内容，这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Marketing Consent Report ║ ║ 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>
完成时输出：
format 为 human（默认）时：
══════════════════════════════════════════════ MARKETING CONSENT REPORT Total customers: <n>
Email Marketing: Subscribed: <n> (<pct>%) ← addressable Unsubscribed: <n> (<pct>%) Pending: <n> (<pct>%) Not asked: <n> (<pct>%)
SMS Marketing: Subscribed: <n> (<pct>%) Unsubscribed: <n> (<pct>%) Not asked: <n> (<pct>%) Output: consent_audit_<date>.csv ══════════════════════════════════════════════
format 为 json 时输出：
{ "skill": "marketing-consent-report", "store": "<domain>", "total_customers": 0, "email": { "subscribed": 0, "unsubscribed": 0, "pending": 0, "not_asked": 0 }, "sms": { "subscribed": 0, "unsubscribed": 0, "not_asked": 0 }, "output_file": "consent_audit_<date>.csv" }
输出格式
CSV 文件 consent_audit_<YYYY-MM-DD>.csv，包含列：customer_id, email, email_marketing_state, email_consent_updated_at, sms_marketing_state, sms_consent_updated_at
错误处理
THROTTLED：API 速率限制超出。恢复方式：等待 2 秒，最多重试 3 次。
No customers：空店铺。恢复方式：以 0 结果退出。
最佳实践
“已订阅”是可触达的营销受众——订阅率低可能表明结账时的选择加入不够醒目。
“待确认”表示客户提供了电子邮件但尚未确认同意——这在双重选择加入流程中很常见。
在重大营销活动前运行，以获取可触达受众的准确数量；如果你的 ESP（如 Klaviyo）有未同步回 Shopify 的额外退订，其显示的数字会不同。
GDPR 合规说明：位于欧盟且 marketingOptInLevel: SINGLE_OPT_IN 的客户，根据你的处理法律依据，可能需要重新征得同意的活动。