用途
该技能用于在不进入 Shopify 后台界面的情况下，按库存水平重新排列手动（自定义）集合中的商品顺序。它会查询集合中的全部商品，按 totalInventory 计算期望的排序，并通过一次 collectionReorderProducts 变更应用。注意：仅适用于手动（自定义）集合，由 Shopify 规则管理的智能集合不受支持。
前置条件
已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_products、write_products
参数
store：字符串，必填，无默认值，店铺域名（例如 mystore.myshopify.com）
format：字符串，可选，默认 human，输出格式：human 或 json
dry_run：布尔值，可选，默认 false，仅预览操作而不执行变更
collection_id：字符串，必填，无默认值，手动集合的 GID（例如 gid://shopify/Collection/123）
sort_by：字符串，可选，默认 inventory_desc，可选 inventory_desc（库存最多在前）或 inventory_asc（库存最少在前）
安全性
⚠️ 第 2 步执行 collectionReorderProducts，会立即更改商品展示顺序。排序可逆——用相反的 sort_by 再运行一次即可恢复之前的顺序——但原始自定义顺序一旦被覆盖便无法恢复。传给变更的 moves 数组必须完整；部分移动会产生未定义的排序。务必先以 dry_run: true 运行，在提交前查看计算出的排序顺序。
collectionReorderProducts 仅适用于手动（自定义）集合。如果集合的 sortOrder 不是 MANUAL，技能必须中止并给出明确信息：“Cannot reorder: collection sort order is not MANUAL. Switch the collection to manual sorting in the Shopify admin first.”
工作流步骤
操作：collection — 查询 输入：id: <collection_id>、first: 250、分页游标 预期输出：集合元数据（title、sortOrder）以及所有带 totalInventory 的商品节点；验证 sortOrder == "MANUAL"，否则中止；持续分页直到获取全部商品
操作：collectionReorderProducts — 变更 输入：id: <collection_id>、按 sort_by 参数依据 totalInventory 排序的 moves 数组——每个 move 为 {id: <product_id>, newPosition: "<index>"}（从 0 开始的字符串索引） 预期输出：job.id 和 job.done；userErrors
GraphQL 操作
collection:query — 已针对 api_version 2025-01 验证
query CollectionProducts($id: ID!, $first: Int!, $after: String) { collection(id: $id) { id title sortOrder products(first: $first, after: $after) { edges { node { id title totalInventory variants(first: 100) { edges { node { inventoryQuantity } } } } } pageInfo { hasNextPage endCursor } } } }
collectionReorderProducts:mutation — 已针对 api_version 2025-01 验证
mutation CollectionReorderProducts($id: ID!, $moves: [MoveInput!]!) { collectionReorderProducts(id: $id, moves: $moves) { job { id done } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: collection-reorganization ║ ║ 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>
如果 dry_run: true，为每个变更步骤加上 [DRY RUN] 前缀，并且不执行它。
完成时输出：
对于 format: human（默认）：
══════════════════════════════════════════════ OUTCOME SUMMARY Collection: <title> Products reordered: <n> Sort order: <inventory_desc|inventory_asc> Errors: 0 Output: none ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "collection-reorganization", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "CollectionProducts", "type": "query", "params_summary": "collection_id: <gid>, first: 250", "result_summary": "<n> products fetched", "skipped": false }, { "step": 2, "operation": "CollectionReorderProducts", "type": "mutation", "params_summary": "sort_by: inventory_desc, <n> moves", "result_summary": "job submitted", "skipped": false } ], "outcome": { "collection_title": "<title>", "products_reordered": 0, "sort_by": "inventory_desc", "errors": 0, "output_file": null } }
输出格式
无 CSV 输出。技能在会话完成摘要中报告新的排序顺序。使用 dry_run: true 可在不提交的情况下预览计算出的位置列表。
错误处理
sortOrder 不是 MANUAL：原因是集合为智能/自动集合；恢复方式是在 Shopify 后台将集合切换为手动排序。
变更中出现 userErrors：原因是商品 ID 或位置无效；恢复方式是检查所有商品 ID 是否属于该集合。
找不到集合：原因是集合 GID 无效；恢复方式是在 Shopify 后台核实 GID。
速率限制（429）：原因是分页请求过多；恢复方式是将 first 减少到 100 并重试。
最佳实践
始终先运行 dry_run: true——技能会打印建议的商品顺序，便于你在提交前核实。
collectionReorderProducts 是异步的——job.done 可能立即为 false。排序会在几秒内完成；刷新店面以验证。
使用 sort_by: inventory_asc 可将缺货商品推到集合页面底部，减少顾客的挫败感。
对于大型集合（250 件以上商品），分页是自动的，但会增加执行时间。考虑在非高峰时段运行。
该技能仅从 products 节点读取 totalInventory——它不会按地点聚合。如果你需要按地点排序，请使用 low-inventory-restock 技能来确定应优先处理哪些商品。