shopify-admin-order-notes-and-attributes-report

用途

该技能查询近期订单，提取订单级备注（order-level notes）与行项目自定义属性（custom line item attributes），例如礼品留言、个性化文字、特殊说明、刻字文本等。它生成一份报表，供运营与履约团队在拣货、打包环节处理特殊请求时使用。整个技能为只读，不执行任何变更操作。

主要能力

查询订单并提取订单备注与自定义属性。
支持提取行项目级别的自定义属性，可按指定属性键过滤（如 gift_message、engraving）。
可仅筛选出含有备注或属性的订单。
输出人类可读文本或 JSON 格式，并生成 CSV 文件。
分页查询，直到 hasNextPage 为 false。

使用方式

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	1	回溯窗口（默认最近 24 小时，适合日常运营）
attribute_keys	array	否	[]	要提取的特定行项目属性键（例如 ["gift_message", "engraving"]）；为空表示全部
only_with_notes	bool	否	false	仅包含有备注或属性的订单
format	string	否	human	输出格式：human 或 json

工作流程

操作：orders — 查询。输入：query: "created_at:>='<NOW - days_back days>'", first: 250, select note, customAttributes, lineItems { customAttributes }, 分页游标。预期输出：带备注与自定义属性的订单；分页直到 hasNextPage: false。
若 only_with_notes: true：筛选出备注非空或 customAttributes 非空的订单。
若指定 attribute_keys：仅保留匹配键的行项目属性。

GraphQL 操作

# orders:query — validated against api_version 2025-01
query OrderNotesAndAttributes($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFulfillmentStatus
        note
        customAttributes {
          key
          value
        }
        lineItems(first: 20) {
          edges {
            node {
              id
              title
              quantity
              variant {
                sku
              }
              customAttributes {
                key
                value
              }
            }
          }
        }
        shippingAddress {
          firstName
          lastName
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，此为强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Order Notes and Attributes 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（默认）：

══════════════════════════════════════════════
ORDER NOTES & ATTRIBUTES REPORT  (<days_back> day(s))
  Orders queried:         <n>
  Orders with notes:      <n>
  Orders with attributes: <n>

  #<name>  <customer>  [<status>]
    Note: "<note text>"
    Line: "<product>"  gift_message: "Happy Birthday!"
  Output: order_notes_<date>.csv
══════════════════════════════════════════════

format: json：

{
  "skill": "order-notes-and-attributes-report",
  "store": "<domain>",
  "period_days": 1,
  "orders_queried": 0,
  "orders_with_notes": 0,
  "orders_with_attributes": 0,
  "output_file": "order_notes_<date>.csv"
}

输出格式

CSV 文件 order_notes_<YYYY-MM-DD>.csv，列包括： order_name, order_id, created_at, fulfillment_status, customer_name, order_note, line_item_title, line_sku, attribute_key, attribute_value

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
No orders with notes	静默期或未收集备注	若 only_with_notes: true，以 0 结果退出

适用场景

在每个履约班次开始时运行（例如 days_back: 1），让拣货/打包人员在开始前拿到特殊说明的打印清单。
节假日期间使用 attribute_keys: ["gift_message"] 聚焦礼品订单。
同时有备注和行项目属性的订单表示高接触履约需求，可标记给资深员工复核。
打印或导出 CSV 并附在拣货单上，以便在履约过程中高效处理特殊需求。

限制

该技能为只读，不执行任何变更操作。
需要已认证的 Shopify CLI 会话与 read_orders 权限。
其他限制暂未提供。