用途
该技能通过成对的库存调整（源地点扣减、目标地点增加）将指定数量的库存从源地点转移到目标地点。适用于仓库间库存再平衡、促销前预先备货，或地点变更后的库存重新分配，可替代 Shopify 后台中的手动库存转移操作。
前置条件
需要已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,write_inventory,read_inventory
API 权限范围：read_products、read_inventory、write_inventory
源地点与目标地点均须为活跃的 Shopify 地点。
参数
store（string，必填）：店铺域名，例如 mystore.myshopify.com
source_location_id（string，必填）：要移出库存的地点 GID
destination_location_id（string，必填）：要移入库存的地点 GID
transfers（array，必填）：要转移的 {sku, quantity} 对象列表
dry_run（bool，可选，默认 true）：仅预览调整而不执行变更
format（string，可选，默认 human）：输出格式，human 或 json
安全性
inventoryAdjustQuantities 会直接修改库存水平。如果数量超过可用库存，源地点可能被扣减为负数——该技能会发出警告，但 Shopify 不会阻止负数调整。建议先以 dry_run: true 运行，在提交前核实源地点的可用数量。该操作不会在 Shopify 中创建转移单记录，而是直接调整。
工作流程步骤
操作：locations — 查询 输入：first: 50 预期输出：所有地点的 id、name——用于验证源与目标 ID 是否存在
操作：inventoryItems — 查询 输入：按 SKU 批量查询，获取每个转移 SKU 的 inventoryItem.id 预期输出：库存项目及其在源地点的当前数量
验证：对每个 SKU 确认源地点可用数量 >= 转移数量。若不满足则警告，但在 dry_run: false 时仍继续执行
操作：inventoryAdjustQuantities — 变更 输入：每个 SKU 两项变更：{ inventoryItemId, locationId: source, delta: -quantity, reason: "correction" } 与 { inventoryItemId, locationId: destination, delta: +quantity, reason: "correction" } 预期输出：inventoryAdjustmentGroup { changes { delta, location } }、userErrors
GraphQL 操作
locations:query — 已针对 api_version 2025-01 验证
query ActiveLocations { locations(first: 50, includeInactive: false) { edges { node { id name isActive fulfillsOnlineOrders } } } }
inventoryItems:query — 已针对 api_version 2025-01 验证
query InventoryLevelsAtLocation($ids: [ID!]!) { nodes(ids: $ids) { ... on InventoryItem { id sku inventoryLevels(first: 20) { edges { node { location { id name } quantities(names: ["available", "on_hand"]) { name quantity } } } } } } }
inventoryAdjustQuantities:mutation — 已针对 api_version 2025-01 验证
mutation InventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) { inventoryAdjustQuantities(input: $input) { inventoryAdjustmentGroup { createdAt reason changes { delta quantityAfterChange item { id sku } location { id name } } } userErrors { field message } } }
会话跟踪
Claude 必须在每个阶段输出以下内容，此为强制要求。
启动时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Inventory Transfer Between Locations ║ ║ 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 SKUs transferred: <n> Total units moved: <n> Warnings (low stock): <n> Errors: <n> Output: inventory_transfer_<date>.csv ══════════════════════════════════════════════
format: json 时输出：
{ "skill": "inventory-transfer-between-locations", "store": "<domain>", "started_at": "<ISO8601>", "dry_run": true, "source_location": "<name>", "destination_location": "<name>", "outcome": { "skus_transferred": 0, "units_moved": 0, "warnings": 0, "errors": 0, "output_file": "inventory_transfer_<date>.csv" } }
输出格式
CSV 文件 inventory_transfer_<YYYY-MM-DD>.csv，包含列：sku, product_title, inventory_item_id, source_location, destination_location, quantity_transferred, source_qty_before, source_qty_after, destination_qty_before, destination_qty_after
错误处理
THROTTLED：API 速率限制超出——等待 2 秒，最多重试 3 次
SKU not found：SKU 不在目录中——记录警告，跳过该 SKU 的转移
userErrors on adjustment：地点未备货该商品——记录错误，跳过该 SKU，继续执行
Quantity would go negative：转移数量超过可用量——记录警告；若 dry_run: false 则中止该 SKU
最佳实践
始终先以 dry_run: true 运行——该技能会核实可用数量并准确显示将要发生的变更。
该操作创建的是原始库存调整，而非转移单。出于审计追踪目的，可在 reason 字段添加备注，并单独记录转移情况。
对于大批量转移（50+ SKU），建议在非高峰时段运行，以免干扰店铺前台对实时库存的读取。
可搭配 multi-location-inventory-audit 使用，在决定转移数量前先识别哪些地点有超量库存。