order-lookup-and-summary

用途

该技能用于在不进入 Shopify 后台界面的情况下，检索客户的完整订单详情。它适合客服人员回答客户关于订单状态、物流追踪和退款的咨询，可替代手动后台搜索或 Gorgias、Zendesk 等专用客服应用集成——该技能直接作用于 Shopify 原生数据层，在单次操作中返回完整订单上下文。

前置条件

已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_orders、read_customers

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
lookup_by	string	是	—	order_number、email 或 phone
lookup_value	string	是	—	要搜索的值（例如 #1001、jane@example.com、+15551234567）
limit	integer	否	5	返回订单的最大数量

工作流程

操作：orders — 查询

输入：first: <limit>，query: "name:<order_number>" 或 "email:<email>" 或 "phone:<phone>"（取决于 lookup_by）

预期输出：完整订单对象，包含财务状态、履约状态、行项目、收货地址、物流追踪、退款。

GraphQL 操作

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

query OrderLookup($first: Int!, $query: String) {
  orders(first: $first, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        processedAt
        displayFinancialStatus
        displayFulfillmentStatus
        totalPriceSet {
          shopMoney { amount currencyCode }
        }
        subtotalPriceSet {
          shopMoney { amount currencyCode }
        }
        totalShippingPriceSet {
          shopMoney { amount currencyCode }
        }
        totalRefundedSet {
          shopMoney { amount currencyCode }
        }
        customer {
          id
          email
          firstName
          lastName
          phone
        }
        shippingAddress {
          address1
          address2
          city
          province
          country
          zip
          phone
        }
        lineItems(first: 50) {
          edges {
            node {
              title
              quantity
              variant {
                sku
                price
              }
              fulfillmentStatus
            }
          }
        }
        fulfillments {
          trackingInfo {
            number
            url
            company
          }
          status
          createdAt
        }
        refunds {
          createdAt
          totalRefundedSet {
            shopMoney { amount currencyCode }
          }
        }
        note
        tags
      }
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容。这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: order-lookup-and-summary             ║
║  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
  Orders found:   <n>
  Errors:         0
  Output:         none
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "order-lookup-and-summary",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrderLookup", "type": "query", "params_summary": "lookup_by: <type>, lookup_value: <value>, limit: <n>", "result_summary": "<n> orders", "skipped": false }
  ],
  "outcome": {
    "orders_found": 0,
    "errors": 0,
    "output_file": null
  }
}

输出格式

对找到的每个订单生成人类可读的格式化摘要（不是 CSV）。对每个订单，Claude 呈现：订单号、日期、财务与履约状态、客户详情、行项目、收货地址、物流追踪号以及任何退款。对于 format: json，输出原始订单对象数组。

错误处理

错误	原因	恢复方式
未返回订单	查找值无匹配	验证查找值格式（订单号必须包含 #，例如 #1001）
lookup_by 无效	值不是 order_number、email 或 phone	使用三个可接受值之一
速率限制（429）	请求过多	减少 limit 或等待后重试

最佳实践

订单号查找需要 # 前缀（例如 #1001），它映射到 GraphQL 查询中的 name 字段。
电话查找必须使用 E.164 格式（例如 +15551234567）；部分号码不会匹配。
邮箱查找会返回该客户的所有订单——如果客户订单较多，请设置 limit 以检索超过默认值 5 的数量。
对于 format: json，可将输出通过管道传给 jq，以便为下游脚本提取特定字段。
该技能为只读——如果需要在查找订单后处理退款，请使用 refund-and-reorder 技能。