用途
该技能查询 Shopify 内置分析引擎（ShopifyQL），获取限定于产品页和集合页的会话级流量数据。它展示哪些页面吸引最多流量、多少会话转化为订单、访客在何处跳出，可作为 SEO 优先级排序、商品运营重点和 A/B 测试目标选择的输入。该技能为只读操作，不执行任何变更。
前置条件
已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_reports
Shopify 套餐：ShopifyQL 分析在 Basic 及以上套餐可用；将会话作为数据源需要 Shopify 套餐或更高版本
参数
store（字符串，必填，无默认值）：店铺域名（例如 mystore.myshopify.com）
format（字符串，可选，默认 human）：输出格式，human 或 json
dry_run（布尔，可选，默认 false）：预览操作而不执行变更
days_back（整数，可选，默认 30）：回溯窗口天数（例如 30 表示最近 30 天）
page_type（字符串，可选，默认 both）：筛选范围，products、collections 或 both
top_n（整数，可选，默认 25）：排名输出中显示的页面数量
sort_by（字符串，可选，默认 sessions）：排名指标，sessions、conversion_rate 或 bounce_rate
工作流程
操作：shopifyqlQuery — 查询（所有落地页） 输入：ShopifyQL 语句 FROM sessions SHOW sessions, conversion_rate GROUP BY landing_page_path SINCE -<days_back>d UNTIL today ORDER BY sessions DESC LIMIT 250；sessions 和 conversion_rate 是该数据源已确认可用的指标 预期输出：所有落地页及其会话数和转化率；若结果数等于 250，则通过 OFFSET 分页
内存中筛选：筛选 landing_page_path 以 /products/（产品页）或 /collections/（集合页）开头的行；应用 page_type 参数；按 sort_by 排序；截断至 top_n；将会话数高于中位数且 conversion_rate < 0.02 的页面标记为 high_traffic_low_conversion
注意：ShopifyQL 不支持 LIKE、WHERE 字符串前缀筛选，也不支持会遮蔽保留列名（sessions、conversion_rate）的聚合别名。所有页面类型筛选必须在获取全部行后在内存中完成。
GraphQL 操作
shopifyqlQuery:query（页面流量）— 已针对 api_version 2025-01 验证
query TrafficByPage($query: String!) { shopifyqlQuery(query: $query) { parseErrors tableData { columns { name dataType displayName } rows } } }
$query 变量（单次调用 — 所有落地页，在内存中筛选）：
FROM sessions SHOW sessions, conversion_rate GROUP BY landing_page_path SINCE -<days_back>d UNTIL today ORDER BY sessions DESC LIMIT 250
随后在内存中筛选行：
产品页：landing_page_path.startsWith('/products/')
集合页：landing_page_path.startsWith('/collections/')
conversion_rate 以小数返回（例如 0.016 = 1.6%）— 显示时乘以 100
已针对 2025-01 实测确认：sessions（INTEGER）和 conversion_rate（PERCENT）是可用指标。在 ShopifyQL FROM sessions 中不支持 WHERE … LIKE、bounce_rate、converted_sessions，以及会遮蔽保留名称的聚合别名。
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制要求。
启动时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: traffic-by-page-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（默认）时：
══════════════════════════════════════════════ OUTCOME SUMMARY Lookback window: <days_back> days Page type: <products|collections|both> Pages analysed: <n> Top session page: <path> (<n> sessions) Top converting page: <path> (<pct>%) Errors: 0 Output: traffic_by_page_<date>.csv ══════════════════════════════════════════════
format: json 时输出：
{ "skill": "traffic-by-page-report", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "ProductPageTraffic", "type": "query", "params_summary": "products, last <days_back> days", "result_summary": "<n> product pages returned", "skipped": false }, { "step": 2, "operation": "ProductPageTraffic", "type": "query", "params_summary": "collections, last <days_back> days", "result_summary": "<n> collection pages returned", "skipped": false } ], "outcome": { "days_back": 30, "page_type": "both", "pages_analysed": 0, "results": [], "errors": 0, "output_file": "traffic_by_page_<date>.csv" } }
输出格式
CSV 文件 traffic_by_page_<YYYY-MM-DD>.csv，每页一行：
page_type：product 或 collection
page_path：URL 路径（例如 /products/red-sneaker）
sessions：落地到该页面的总会话数
conversion_rate_pct：转化率百分比（API 返回小数；乘以 100）
optimisation_flag：若 sessions > 中位数且 conversion_rate < 2%，则为 high_traffic_low_conversion
format: human 时，内联打印截断至 top_n 的排名表，随后列出标记为 high_traffic_low_conversion 的优化候选页面。
错误处理
parseErrors 非空：ShopifyQL 语法无效 — 每个错误为纯字符串。记录每个字符串并呈现给用户；常见原因：为保留列名（sessions、conversion_rate）设置别名、使用 LIKE，或引用不存在的列如 converted_sessions 或 bounce_rate。
tableData 为 null：该时段无分析数据。延长 days_back；确认店铺有流量。
ACCESS_DENIED / 缺少 read_reports 权限：认证时未授予该权限。重新认证并添加 read_reports 权限。
THROTTLED：分析查询速率限制。等待 2 秒，最多重试 3 次。
筛选后无产品/集合行：开发/测试店铺，或目录页无直接落地流量。扩大 days_back；注意大多数流量可能通过首页进入。
最佳实践
高流量产品页转化率低于 1% 值得调查 — 检查商品是否缺货、图片是否不佳，或缺少明确的行动号召。
跳出率高的集合页通常表明驱动会话的广告或搜索词与集合内容不匹配 — 检查集合 SEO 标题。
新产品发布后使用 page_type: products 跟踪早期表现，避免集合流量的干扰。
与 top-product-performance 结合，将高转化页面与产生最多实际收入的产品关联起来。
在页面修改（文案、图片、定价）后每周重新运行报告以衡量影响 — 7 天窗口（days_back: 7）可干净地隔离修改后的行为。