用途
该技能按订单的首次触达流量来源聚合订单数据，来源信息从每个订单的 landingPageUrl、referrerUrl 以及落地 URL 中嵌入的 UTM 参数提取。它生成归因表，展示每个来源的订单数、收入和 AOV（客单价），让商家可以看到哪些渠道真正在转化。只读——不执行任何变更。当 Shopify 原生分析看板不够细致，或需要导出原始归因数据用于外部模型时使用。
前置条件
已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders
API 权限范围：read_orders
参数
参数 | 类型 | 必填 | 默认值 | 说明
store | string | 是 | — | 店铺域名（例如 mystore.myshopify.com）
format | string | 否 | human | 输出格式：human 或 json
days_back | integer | 否 | 30 | 回溯窗口，单位为天
min_orders | integer | 否 | 1 | 人类可读摘要中每个来源至少包含的订单数
group_by | string | 否 | category | 分组层级：category（direct/organic/paid/social/email/referral）、domain（原始 referrer 主机）或 utm_source（UTM 参数值）
include_utm | bool | 否 | true | 为 true 时，从 landingPageUrl 查询字符串中解析 utm_source、utm_medium、utm_campaign
安全性
ℹ️ 只读技能——不执行任何变更。任何时候运行都安全。
工作流步骤
操作：orders — 查询 输入：query: "created_at:>='<NOW - days_back days>'", first: 250, 选取 id、name、createdAt、landingPageUrl、referrerUrl、customerJourneySummary { firstVisit { landingPage referrerUrl source sourceType utmParameters { source medium campaign term content } } }、totalPriceSet、customer { numberOfOrders }、分页游标 预期输出：带落地页/referrer/UTM 数据的订单；持续分页直到 hasNextPage: false
对每个订单推导规范化来源：
如果 customerJourneySummary.firstVisit.utmParameters.source 已设置 → 使用它（最强信号）
否则当 include_utm: true 时从 landingPageUrl 查询字符串解析 UTM 参数
否则从 referrerUrl 提取主机并映射到类别：
空/无 → direct
google.com / bing.com / duckduckgo.com → organic-search
googleads/doubleclick → paid-search
facebook.com / instagram.com / tiktok.com / x.com / twitter.com / pinterest.com / youtube.com → social-<host>
mail/gmail/outlook 主机 → email
任何其他主机 → referral-<host>
按所选 group_by 维度聚合：
订单数
收入 = Σ totalPriceSet.shopMoney.amount
AOV = 收入 / 订单数
新客占比 %（customer.numberOfOrders == 1 的订单数除以该来源订单总数）
GraphQL 操作
orders:query — 已针对 api_version 2025-01 验证
query OrdersForAttribution($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id name createdAt landingPageUrl referrerUrl totalPriceSet { shopMoney { amount currencyCode } } customer { id numberOfOrders } customerJourneySummary { firstVisit { landingPage referrerUrl source sourceType utmParameters { source medium campaign term content } } momentsCount { count } } } } pageInfo { hasNextPage endCursor } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Referral Source Attribution ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
每个步骤后输出：
[N/TOTAL] <QUERY|MUTATION> <OperationName> → Params: <关键输入的简要摘要> → Result: <数量或结果>
完成时输出：
format: human（默认）时：
══════════════════════════════════════════════ ATTRIBUTION REPORT (<days_back> days, group: <group_by>) Orders analyzed: <n> Total revenue: $<amount> Sources detected: <n>
Top sources by revenue ───────────────────────────────────────── <source> Orders: <n> Revenue: $<n> AOV: $<n> New cust: <pct>% <source> Orders: <n> Revenue: $<n> AOV: $<n> New cust: <pct>% ...
Output: attribution_<date>.csv ══════════════════════════════════════════════
format: json 时，输出：
{ "skill": "referral-source-attribution", "store": "<domain>", "period_days": 30, "group_by": "category", "totals": { "orders": 0, "revenue": 0, "currency": "USD" }, "sources": [ { "source": "<name>", "orders": 0, "revenue": 0, "aov": 0, "new_customer_pct": 0 } ], "output_file": "attribution_<date>.csv" }
输出格式
CSV 文件 attribution_<YYYY-MM-DD>.csv，包含列： order_id, order_name, created_at, source, source_category, referrer_url, landing_page_url, utm_source, utm_medium, utm_campaign, revenue, is_new_customer
错误处理
错误 | 原因 | 恢复方式
THROTTLED | 超出 API 速率限制 | 等待 2 秒，最多重试 3 次
landingPageUrl 和 referrerUrl 为空 | POS、草稿或导入订单 | 归类为 unattributed
UTM 参数格式错误 | 落地 URL 中存在未编码字符 | 跳过 UTM 解析，回退到 referrer 主机
customerJourneySummary 不可用 | 较旧订单或应用创建的订单 | 回退到顶层 landingPageUrl/referrerUrl
最佳实践
在运行具有一致 UTM 标记的结构化广告活动时，使用 group_by: utm_source——这是保真度最高的归因信号。
使用 group_by: category 做董事会级摘要；商家想先知道“有多少来自社交”，而不是“有多少来自 instagram.com/p/abc”。
与 discount-roi-calculator 交叉参考——把“哪个来源带来订单”与“订单使用了哪个折扣”结合起来，可以揭示付费获客真正在哪里产生回报。
警惕“direct”虚高——许多邮件应用和社交应用点击会丢失 referrer，被归为 direct。对出站链接使用 UTM 标记可以找回该信号。
对低销量店铺，在多月周期上运行（days_back: 90），这样百分比明细不会被少数订单主导。