shoplazza-products

shoplazza CLI — 产品模块

重要 — 首先使用 Read 读取 ../shoplazza-common/SKILL.md。 该文件涵盖所有通用机制：三个访问层级、输出封装（.data）、 --dry-run、--jq（包括“不要传入 -r”）、--fields、schema、api rest、身份验证 / 配置文件， 以及安全协议。本文件仅介绍产品领域，不会重复这些内容。

概述

products 模块用于管理产品目录：产品及其变体、价格、 库存、标签、图片、系列、礼品卡、客户评价、仓库位置、 供应商和采购。三个访问层级均适用（层级选择规则见 shoplazza-common — 优先选择 +shortcut）。

没有 +update 或 +delete 快捷方式 — 更新和删除均为 spec 叶子项。 Products 是一个大型领域：本文件是路由指南，并介绍高频操作； 各子资源的详细内容见 references/（变体、库存 / 位置、 系列 / 收集项、图片、礼品卡、评论、采购 / 供应商）。

命令索引

意图 → 命令，按最匹配的层级优先。权威标志 / 参数请查阅 shoplazza products <cmd> --help 和 shoplazza schema products.<cmd>，而非本表。

用户意图	命令
搜索／筛选商品	products +search [--keyword <title-word>] [--vendor <exact>] [--published published|unpublished|any] [--collection-id <id>] [--fields id,title]
统计商品数量	products +count [--published …]
创建单规格商品	products +create --title <name> --price <n> --image <url> [--published]
创建多规格商品（规格矩阵：颜色 × 尺寸 × …）	分两步：products +create --title <name> --price <n> --image <url>，然后执行 products +set-variants --id <new-id> --add "Color:Red,Blue" [--add "Size:S,M"]（已创建的规格会成为第一个组合；其他组合会复制其价格）
添加／移除／替换／重命名规格值或规格维度、设置规格价格——可在一次调用中混合执行	products +set-variants --id <product-id> [--add|--remove|--set "Name:v1,v2"] [--drop "Name[=value]"] [--rename "Name:old=new"] [--new-price …] [--set-price …]
发布商品	products +publish --id <product-id>
下架商品	products +unpublish --id <product-id>
更改规格价格	products +set-price (--variant-id <id> | --sku <sku> [--all] | --product-id <id>) --price <n>
调整库存（增加或减少）	products +stock (--variant-id <id> | --sku <sku> | --product-id <id>) (--adjust <±n> | --set <n>) [--location-id <id>]
添加／移除／替换标签	products +tag --id <product-id> (--add a,b | --remove c,d | --set x,y)
获取单个商品	products get --params '{"product_id":"<id>"}'
列表（+search 不支持的筛选条件：ID、handle、日期范围、SPU 等）	products list --params '{…}'
完全控制创建（快捷命令不支持的字段）	products create --data '{"product":{…}}'（参见 schema products.create）
更新商品字段	products update --params '{"product_id":"<id>"}' --data '{"product":{…}}'
删除单个商品	products delete --params '{"product_id":"<id>"}'
删除多个商品	products batch-delete --params '{"product_ids":["<id>",…]}'
列出商品规格	products variants list --params '{"product_id":"<id>"}' → 参考文档／variants.md
更新规格（选项、SKU、重量等）	products variants update --params '{"variant_id":"<id>"}' --data '{"variant":{…}}'
按 SKU 查找规格	products variants list-by-sku --params '{"sku":"<sku>"}'
创建精选系列	products collections create --data '{"collection":{"title":"…"}}' → 参考文档／collections-collects.md
将商品添加到系列	products collects create --data '{"collect":{"collection_id":"<cid>","product_id":"<pid>"}}'
为商品添加图片	products images create --params '{"product_id":"<id>"}' --data '{"image":{"src":"<url>"}}' → 参考文档／images.md
创建礼品卡（储值金额 = 资金 → 先使用 --dry-run）	products gift-cards create --data '{"gift_card":{"code":"…","initial_value":"…","expires_on":"YYYY-MM-DD"}}' --dry-run → 参考文档／gift-cards.md
查看礼品卡余额	products gift-cards get --params '{"id":"<id>"}' --jq '.data.gift_card.balance'
停用／“删除”礼品卡（不可撤销 → 先使用 --dry-run 并获得确认）	products gift-cards disable --params '{"id":"<id>"}' --dry-run（不存在删除端点；停用后将永久无法兑换）
库存水平／商品、地点	products inventory … ／ products locations … → 参考文档／inventory-locations.md
客户评价	products comments {list,create,batch-create} → 参考文档／comments.md
供应商／采购订单	products suppliers … ／ products procurement … → 参考文档／procurement-suppliers.md
店面分类	products categories list

处理请求

“新建商品 / 上架 / 调价 / 补货 / create a product / restock”是一个操作，而不是问题：

1. 通过下面的触发表匹配意图和快捷命令。
2. 检查必填字段（每个快捷命令中标记为 no-default 的标志）。缺失或含糊 → 使用 AskUserQuestion 询问，绝不编造——尤其是 --price（金额）和 --image（无法凭空编造的资源 URL）。将缺失字段合并到一个问题批次中，不要分多次询问。
3. **不要询问具有 CLI 默认值或可省略以禁用的标志。**采用默认值即可。
4. 所有必填字段均已提供 → 执行命令。+shortcuts 可以安全地直接运行；删除、批量操作和创建礼品卡（储值 = 金额）前，先使用 --dry-run，遵循 shoplazza-common → Safety protocol。
5. 如实说明限制：如果平台无法执行某项操作（例如，在非默认位置或多位置商品上减少库存——参见 references/inventory-locations.md），则不发出任何写入 命令；说明限制并提供合理的替代方案。

触发短语 → 快捷命令

用户说法	快捷方式	如何提取值
搜商品 / 找一下商品 / find / list products	+search	标题关键词 → --keyword（仅匹配标题）；供应商/vendor → --vendor（精确匹配，原样传入）；未上架 → --published unpublished；已上架 → --published published
有多少商品 / 商品总数 / how many products do I sell	+count	已上架 → --published published；数量取自 .data.count——绝不要手动计数
新建商品 / 建品 / 上新 / create a new product	+create	商品名称 → --title，原样传入；售价 → --price；主图/图片 URL → --image；包含“上架”字样 → 添加 --published；“存草稿/draft” → 省略 --published
建多规格商品 / 有颜色和尺码的商品 / create a product with color & size options	+create 然后 +set-variants --add	步骤 1：按上述方式执行 +create（草稿）；步骤 2：每个维度对应一个 --add "Name:v1,v2,…"（最多 3 个，顺序 = 店面顺序），在一次调用中执行（不指定价格：每个组合都会复制 +create 设置的价格；不指定 --existing：创建的规格会采用第一个值）；每个组合的 SKU → 使用带有 {Name} 占位符的 --sku-template；最后上架
加一个颜色 / 加几个码 / add a spec value	+set-variants --add	--id（或按名称解析）；维度 + 新值 → --add "Color:White"；每个其他维度的现有组合都会新增一个规格（之前删除的组合仍保持删除状态）；新组合需要指定 --new-price（按值设置：--new-price "Color:White=19,Black=21"），对于要求规格图片的商品，还需要指定 --new-image
加一个规格维度 / add a whole new dimension (e.g. 加个尺码规格)	+set-variants --add + --existing	未知的维度名称 = 新维度。现有规格会采用 --existing "Size:<value>" 指定的值（维度有多个值时必填），并保留 id/sku/库存/图片；其他值会创建新规格，并复制价格/划线价/重量/图片——不复制 SKU，也不复制库存（可通过 --new-stock 设置库存）。无需设置价格。执行前询问现有规格采用哪个值
删掉某个颜色/码 / remove a spec value	+set-variants --remove	--remove "Color:Red"；受影响的规格会被删除，并列在输出中。值必须完全拼写一致（区分大小写；仅大小写不同会被拒绝，并提示“did you mean”）。不存在的名称/值会报错——修正拼写，绝不要声称操作成功
不按某规格分了 / drop a whole dimension	+set-variants --drop	--drop "Size" 会保留每个规格（保留 id）；如果规格会合并成同一组合，则操作会被拒绝——询问要保留哪个值的规格，然后执行 --drop "Size=M"（其他值的规格会被删除）
规格值只保留… / 整个换成… / set one dimension's values	+set-variants --set	--set "Color:Red,Blue" 会将该维度的值精确设为这些值（顺序 = 店面顺序）；未列出的值会连同其规格一起删除，新值会创建规格
改名 / 把 Red 改成酒红 / rename a value or dimension	+set-variants --rename	值 → --rename "Color:Red=Wine Red"（多个值："Color:Red=Wine Red,Blue=Navy"）；维度 → --rename "Color=Colour"；原位重命名——每个规格都会保留 id/sku/库存/图片。新名称已被占用时会拒绝（要交换两个值，请先改成临时名称）；重复操作会提示旧名称不存在（“was it renamed already?”）——这表示重命名已完成。绝不要把重命名模拟成删除后再添加
规格改动一句话说了好几处（去掉某规格、只留某些值、改名、统一价…）	一次 +set-variants 调用	将所有编辑放在同一次调用中（--drop/--set/--rename/--set-price …）：它们会按固定顺序应用（remove、drop、set、add、rename），并在一个请求中写入；所有名称都使用当前名称（新名称只出现在 --rename 的右侧）；输出中的 changes 列表会说明将执行的操作
各规格值价格不同 / S 卖 20、M 卖 30	+set-variants --set-price "Size:S=20,M=30"	为每个规格设置对应值的价格；如果这些值是新值，可与 --add 一起使用。单个数字会为每个规格重新定价
上架商品 X / publish product X	+publish	id → --id；如果只有名称，先通过 +search --keyword 查找
下架 / 隐藏商品 / unpublish	+unpublish	id → --id
改价 / 调价 / change the price to X	+set-price	目标：规格 id → --variant-id；SKU → --sku；商品 id → --product-id（解析该商品唯一的规格；多规格商品会被拒绝，并列出候选项）；如果只有名称，先执行 +search --keyword。新价格 → --price，原样传入；--price 0 会清除价格（不会显示 ¥0）——说明这个区别，并在传入 0 之前征得用户确认
划线价 / compare-at price	+set-price --compare-price	仅在用户明确提及时使用
库存加 N / 补货 N 件 / add N stock	+stock --adjust N	加/增加 N = 正向增量 → --adjust N。目标：规格 id → --variant-id；SKU → --sku；商品 id → --product-id（适用于单规格商品；多规格商品会被拒绝并列出候选项）；如果只有名称，先执行 +search --keyword——绝不要向用户索要规格 id
库存设为 N / set stock to N	+stock --set N	绝对目标值（≥ 0），可增加或减少；仅当商品位于单个地点时，才允许在默认地点减少库存；目标标志与“库存加 N”一行相同
减库存 / 库存扣掉 N / reduce stock	+stock --adjust -N	减/扣掉 N = 负向增量 → --adjust -N；如果结果会低于 0、--location-id 不是默认地点，或商品在多个地点有库存，CLI 会拒绝操作——此时请说明原因，并提供 +unpublish / 库存策略 deny 作为替代；目标标志与“库存加 N”一行相同
加标签（保留原有）/ add tags	+tag --add	标签以逗号分隔；保留现有标签
去掉某标签 / remove a tag	+tag --remove	忽略不存在的标签
标签整个换成… / replace all tags	+tag --set	替换整个标签列表——仅在用户明确说“replace/换成/只保留”时使用
如果有多行匹配，询问用户要哪一行。不要猜。

必须询问 vs. 可询问矩阵

只有没有默认值的标志才需要询问。

快捷命令	用户未指定时必须询问	尽可能推断	静默使用默认值
+create	--price、--image（一次询问；绝不编造价格或图片 URL）	根据用户话语中的产品名称推断 --title；根据上架/publish 相关措辞推断 --published	--published（省略 = 草稿）、--sku、--stock、--stock-policy（默认 deny）、--compare-price、--tags、--collection-ids
+set-variants	仅当出现全新值时询问 --new-price（向已有维度添加值；添加维度会复制价格，删除或重命名不需要）；同样，仅当 CLI 指明产品需要变体图片时才询问 --new-image（必须是产品已有图片之一）；当向已有维度的产品添加包含多个值的维度时，询问 --existing；当 --drop 会合并变体时，询问要保留的值；询问维度 + 值（绝不编造规格值；原样保留用户的值拼写——值区分大小写）	根据措辞推断编辑标志（加→--add，删/去掉→--remove，不按…分→--drop，只保留/换成→--set，改名/改成→--rename，统一价/都卖→--set-price）；通过按名称执行 +search 推断 --id	--sku-template、--set-stock、--new-stock（可选；省略 = SKU/库存不变）
+set-price	--price（绝不编造数字）	根据用户提供的信息确定目标：变体 ID → --variant-id，SKU → --sku，产品 ID → --product-id（解析为该产品唯一的变体）。绝不询问变体 ID——应自行解析	--compare-price；--all（仅当用户明确要求匹配 SKU 的所有变体时）
+stock	数量——除此之外不问任何内容。绝不询问变体 ID 或库存项目 ID；应自行解析	根据措辞判断使用 --adjust 还是 --set（加 N = --adjust N；减/扣 N = --adjust -N；设为 N = --set N）；目标与 +set-price 完全相同：变体 ID → --variant-id，SKU → --sku，产品 ID → --product-id。这里没有 --all——库存写入只针对一个变体	--location-id（默认为默认地点）
+publish / +unpublish	--id（或通过按名称执行 +search 解析）	—	—（仅接受 --id）
+tag	--id、标签值	根据措辞推断添加/删除/设置模式	—
+search / +count	（无需询问——所有筛选条件均为可选）	根据措辞推断筛选条件	--page-limit、--fields

标识符阶梯——自行解析，不要询问。 商家知道产品名称和产品 ID。 变体 ID 和库存项目 ID 是他们从未见过的内部实现细节。以下每一阶都对应一条命令，因此应逐阶向下查找，而不是询问用户没有的 ID：

name  --(+search --keyword)-->  product id  --(--product-id, single-variant)-->  variant id
                                product id  --(products variants list)-------->  variant id
                                variant id  --(+stock resolves it internally)->  inventory item id

只有当某一阶确实存在歧义时才询问——产品有多个变体，而用户的描述没有说明要选哪一个。--product-id 遇到这种情况会拒绝执行并列出候选项：请用户从该列表中选择。绝不代替用户选择 variants[0]。

子资源询问（末端层级，遵循相同原则）：

• gift-cards create——缺少 code 和 initial_value 时必须询问（储值 = 货币金额；绝不编造）。customer_id / send_email 为可选项：可以询问以澄清客户，但不能编造。
• variants update——只发送用户要求更改的字段；绝不填充请求体。

永不询问列表

带有 CLI 默认值或可通过省略来禁用的标志——绝不会出现在问题中： --location-id（默认位置）· --stock-policy（默认 deny）· --published （省略 = 草稿；仅在用户明确表示要发布时设置）· --compare-price · --sku / --stock / --tags / --collection-ids 用于 +create（可选）· --page-limit · --fields（仅在用户要求指定字段时使用）· --all（仅用于明确要求批量操作的情况）· --sku-template / --set-stock / --new-stock 用于 +set-variants （可选）· +set-variants 的编辑标志（根据措辞推断：加 = --add，删 = --remove， 不按…分 = --drop，只保留 = --set，改名 = --rename）。

决策示例

用户说	判定
"新建一个商品：Lycra 瑜伽裤，售价 39.99，主图用 https://…/yoga.jpg，先存草稿"	CREATE — +create --title "Lycra 瑜伽裤" --price 39.99 --image https://…/yoga.jpg；存草稿 = 省略 --published
"帮我上架一个新的 T恤 商品"	ASK — 缺少价格和图片（同一批次询问）；标题 T恤 可用；计划设置 --published（用户说了上架）
"把 SKU TSHIRT-RED-M 的价格改成 24.99"	CREATE — +set-price --sku TSHIRT-RED-M --price 24.99；单个变体意图不使用 --all
"给变体 998877 调一下价格"	ASK — 新价格；目标 --variant-id 998877 已知
"给变体 12345 的库存加 50 件"	CREATE — +stock --variant-id 12345 --adjust 50
"把变体 88664 的库存减少 30 件"	CREATE — +stock --variant-id 88664 --adjust -30；如果 CLI 拒绝（低于 0 / 非默认位置 / 多位置商品），转达原因并提供替代方案
"给老客户发一张礼品卡"	ASK — initial_value + code（金额；绝不编造）
"建一个文胸套装，3 个颜色、15 个胸围码、6 个内裤码，统一 29.99"	先询问 --image，然后分两步：+create --title … --price 29.99 --image … → +set-variants --id <new> --add "Color:…" --add "Bra Size:…" --add "Brief Size:…"（每种组合的价格都为 29.99）
"给这个商品加个 White 色"	CREATE — +set-variants --id <id> --add "Color:White" --new-price <n>；如果价格未知则询问（新组合需要设置价格）
"给已上架的 T 恤加一个尺码维度 S/M/L"	先询问 — 当前变体的尺码是什么（它们会保留 id/sku/stock）；其他尺码会使用每种颜色的价格创建，但没有 sku 且库存为零。然后执行 +set-variants --id <id> --add "Size:S,M,L" --existing "Size:<answer>"
"把红色改名叫酒红"	CREATE — +set-variants --id <id> --rename "Color:Red=酒红"（原地修改；保留 id/sku/stock）
"不要 lenses 规格了只留 6lenses 的，款式只要 Ocean 改叫 2 lenses，价格全部 19.9"	先确认（会删除变体）——单次调用：+set-variants --id <id> --drop "lenses=6lenses" --set "Style:Ocean" --rename "Style:Ocean=2 lenses" --set-price 19.9 --dry-run，转达其 changes，然后执行
"不按 lenses 分了"（lenses 有多个值）	ASK — 询问要保留哪个 lenses 值对应的变体；然后使用 --drop "lenses=<value>"

边界

看起来属于商品功能，实际上属于其他地方（以及本域拥有的相似功能）：

听起来像	实际属于	命令
优惠码 / 折扣码 / 满减 / 限时促销 / 折扣码与优惠券	shoplazza-discounts	discounts +*
礼品卡 / 储值卡 / 礼品卡（可兑换为店铺余额）	本域（不属于折扣或账单）	products gift-cards …
上传文件到媒体库 / 店铺媒体库资源	shoplazza-shop	shop files / shop +upload-file
给商品挂图 / 附加到商品的图片	本域	products images create
首页轮播图 / 卡片配图 / 主题卡片中的图片	shoplazza-themes	themes +page → themes +edit
商品详情页模板 / 自定义商品详情页模板	shoplazza-themes	themes template create
商品元字段 / 商品或店铺上的元字段	shoplazza-shop	shop metafields-resource / metafields-definition
库存同步 / 补货 / 库存与仓库库存	本域（不属于订单或履约）	products +stock / products inventory
买家评价 / 评论 / 商品评价	本域（不属于店铺博客或页面内容）	products comments …
博客 / 自定义页面 / 店面内容页面	shoplazza-shop	shop blogs / shop pages

Collections 与 collects 的区别——域内易混淆项：collections 是精选合集对象本身（标题、图片、SEO、智能规则）；collects 是将商品关联到合集的关联记录。“把商品加进合集” = collects create，绝不是 collections update。请参阅 references/collections-collects.md。

权限 · Scope

授权按域（即 --domain 的单位）进行，而非按命令进行。授权流程见 shoplazza-common → Authentication。

操作	需要	授权方式
读取（get / list / +search / +count / 子资源读取）	products 读取权限	auth login --domain products
写入（+create / +publish / +set-price / +stock / +tag / create / update / delete / 子资源写入）	products 写入权限	auth login --domain products

使用 shoplazza auth scopes 查询具体的 scope 字面值；--domain products 会展开为这些权限。

注意事项

仅列出特定于本域的易错点（通用事项——.data 前缀、使用 --jq 时不加 -r——见 shoplazza-common）。

症状	原因	修复方法
库存减少被拒绝	inventory_levels 写入叶子命令（set-stock / update-level）只能增加库存；减少库存会通过 variant.inventory_quantity 操作，但它仅适用于默认地点，且在多地点商品上未经验证——因此 +stock 会进行相应限制	使用 +stock --adjust -N / --set N；触发限制时，说明原因并提供替代方案（取消发布、库存策略）
用户想要草稿，结果商品却已发布	+create 上的 --published 是纯布尔标志——传入它就会发布	草稿时完全省略 --published（草稿为默认值）
+count / 其他快捷命令出现 unknown flag: --fields	在此模块中，只有 +search 支持 --fields	在其他位置使用 --jq 投影
+search --fields 结果缺少你指定的字段	字段名是响应键（primary_image、price_min 等）；拼写错误或未知名称会被 API 静默忽略。id、title、created_at、updated_at 可能无论如何都会返回	对照默认输出或 schema products.list --view response 检查字段名；或者省略 --fields，改用 --jq 投影
更新后标签全部消失	products update（叶子命令）会替换整个标签列表；+tag --set 也一样	使用 +tag --add / --remove——现有标签会保留
使用包含 variants 数组的 products update（叶子命令）后，变体消失	该数组会完整替换：未列出的任何变体都会被删除；列出的变体若没有 id，则会按选项值匹配（精确匹配，区分大小写），未匹配时会重新创建（sku/库存会重置）	切勿在叶子命令中手写 variants 数组——使用 +set-variants（包含按值设置价格），它会映射现有变体（保留 id），并报告每项删除
大型矩阵的 products update / create 出现 “Result too large”	响应会回显完整商品——数百个变体 × 约 25 个字段	使用 +set-variants（输出有界摘要）。使用叶子命令时，务必用 --jq 缩小结果范围，并通过 --data @file 传入请求体
写入操作报告 “result too large”，你正打算重试	请求很可能已经成功——只是回显内容过大	不要重新发送。先验证：products variants count --params '{"product_id":"<id>"}'
添加规格维度后，库存只在一个尺码上	添加维度时，每个现有变体（id、sku、库存、图片）都会保留在 --existing 值上；其他值会创建新变体，复制价格，但不带 sku/库存	这是预期行为。使用 --new-stock、+stock 或 --sku-template 设置其余值。输出中的 remapped_detail / created_detail 会说明各变体对应到哪里
+set-variants 被拒绝：“would merge variants that differ only by it”	删除该维度会让两个变体（例如 Red/S 和 Red/M）落在同一个组合上——只能有一个变体保留其数据	询问要保留哪个值的变体，然后在同一次调用中使用 --drop "Size=<value>" 并执行其他任何编辑
通过删除再添加“重命名”一个值后，sku/库存丢失	删除再添加会删除旧变体并创建新变体	使用 --rename "Color:Red=红色"——值会原地更改
+set-variants 输出列出 sku_may_be_stale	保留的变体仍使用一个已不再包含的值作为其 sku 名称（维度已删除 / 值已重命名）	告知用户；如果用户想要新的 sku，则使用 --sku-template 重新生成
+set-variants 将 S 和 s 视为不同值	服务端的值区分大小写；新增值若仅大小写不同于同一维度中的另一个值，则会被拒绝（添加、更新、新建维度均如此），删除时也必须使用完全一致的拼写	使用完全一致的拼写；通过 --rename 更改拼写
商品上列出了某个规格值，但该值没有变体	其他编辑不会影响它；指定该值的 --add / --set 会创建其变体（每个现有的其他维度组合创建一个——需要 --new-price）	这是预期行为；如果不应提供该值，则使用 --remove 删除
将 --new-price 传给 +set-variants 后，部分价格没有变化	--new-price 只会为没有可复制价格的新变体设置价格；不会更改现有价格（输出中的 price_applied / warnings 会说明）	使用 --set-price 重新定价（所有变体，或按值指定，例如 "Size:S=20"）
新商品无法下单；即使已设置库存，API 仍提示 “Out-of-stock”	商品处于草稿状态（+create 的默认值）——草稿无法下单，错误消息具有误导性	先执行 products +publish --id <id>
+set-price --sku 被拒绝并列出候选项	该 SKU 匹配了多个变体——CLI 会拒绝多重匹配	从列出的候选项中选择正确的 --variant-id；只有在明确表示“全部”时才传入 --all
在 --variant-id 中传入商品 id 后返回 404 No variants found（或 “no inventory item found for that variant”）	--variant-id 的作用范围是变体（PUT /variants/{variant_id}）；商品 id 与之永远无法匹配	改为传给 --product-id——错误中的 hint 会说明。或者先列出变体：products variants list --params '{"product_id":"<id>"}'
--product-id 被拒绝：“product … has N variants”	多变体商品没有唯一的价格或库存目标	根据 hint 中的候选项询问用户要选哪个（候选项最多列出 10 个，并会指出列出其余项的命令），然后使用 --variant-id 或 --sku 重新运行。切勿猜测 variants[0]
使用 +set-price --price 0 后价格消失	'0' / '0.00' 会清除价格，而不是将其设为零	仅当用户想清除价格时才传入 0
想要执行 gift-cards delete	不存在删除端点（子命令：batch-create / create / disable / get / list / update）	gift-cards disable 会停止兑换；告知用户这是停用而非删除
variants update 的路径中带有 product_id，结果返回 404	variants get / update 的作用范围是变体：/variants/{variant_id}——不使用 product_id	只有 variants list / create / delete 的作用范围是商品（delete 需要两个 id）
inventory set-stock 拒绝变体 id	库存级别使用 inventory_item_id 作为键，它与变体 id 不同	先进行映射：inventory list-by-variant --params '{"variant_ids":["<id>"]}'
comments create 因缺少字段而被拒绝	star、like、created_at、user_name、content、product_id 全部必填	参见 references/comments.md；未知时使用 like: 0
尝试通过 collections update 执行“加进合集”	商品与合集之间的关联由 collect 记录表示	使用 collects create（一个）/ collects batch-create（多个）
臆造了 +delete / +update 快捷命令	这些命令不存在	delete / batch-delete / update 是规格定义中的叶子命令（参见 Command map）

食谱

# 1. All unpublished products from vendor Nike
products +search --vendor Nike --published unpublished

# 2. Ids, titles and main image only, of products with "hoodie" in the title
products +search --keyword hoodie --fields id,title,primary_image

# 3. How many published products?
products +count --published published --jq '.data.count'

# 4. Create a draft product (draft = no --published)
products +create --title "Lycra 瑜伽裤" --price 39.99 --image https://cdn.example.com/yoga.jpg

# 5. Publish a product you only know by name
ID=$(products +search --keyword "瑜伽裤" --jq '.data.products[0].id')
products +publish --id "$ID"

# 6. Restock / reprice a product you only know by product id (single-variant product)
#    --product-id resolves the one variant. A multi-variant product is refused with
#    its candidates listed — show them to the user and let them pick.
products +stock --product-id 7ab09fcd-2ee7-4118-8c4d-e44a10d51caf --adjust 50
products +set-price --product-id 7ab09fcd-2ee7-4118-8c4d-e44a10d51caf --price 24.99

# 7. Multi-variant product: resolve the variant the user actually named, then write.
#    Pick by the option the user said (XL), never by position. If the user named no
#    option, ask which variant — don't take variants[0].
VID=$(products variants list --params '{"product_id":"9036f033-c605-4b6f-8a08-1b7ae090791c"}' \
  --jq '.data.variants[] | select(.option2=="XL") | .id')
products +stock --variant-id "$VID" --set 20

# 8. Append tags without clobbering the existing ones
products +tag --id 445566 --add summer,sale

# 9. Delete one product — dry-run, restate, wait for the user's go-ahead, then run
products delete --params '{"product_id":"778899"}' --dry-run
products delete --params '{"product_id":"778899"}'          # only after the user agrees (next turn)

# 10. Batch delete — always dry-run first and restate the count
products batch-delete --params '{"product_ids":["111222","333444","555666"]}' --dry-run
products batch-delete --params '{"product_ids":["111222","333444","555666"]}'

# 11. Change one variant's size option (partial body — only the field to change)
products variants update --params '{"variant_id":"24680"}' --data '{"variant":{"option1":"XL"}}'

# 12. Create a multi-spec product: draft first, then add the dimensions (3 colors × 2 sizes = 6 variants)
ID=$(products +create --title "Yoga Set" --price 29.99 --image https://cdn.example.com/yoga.jpg \
  --jq '.data.product.id')
products +set-variants --id "$ID" --add "Color:Black,White,Pink" --add "Size:S,M" \
  --sku-template "YS-{Color}-{Size}"

# 13. Add one color to an existing product (existing variants untouched)
products +set-variants --id 7ab09fcd-…  --add "Color:White" --new-price 29.99

# 14. Add a whole dimension — existing variants become 70B (id/sku/stock kept); 70A/70C copy the
#     price with no sku/stock: ask which value the current variants are first
products +set-variants --id 7ab09fcd-… --add "Bra Size:70A,70B,70C" --existing "Bra Size:70B"

# 15. Drop one value / a whole dimension (deleted variants are listed in the output)
products +set-variants --id 7ab09fcd-… --remove "Color:Pink"
products +set-variants --id 7ab09fcd-… --drop "Size=M"

# 15b. Rename a value / a dimension in place (every variant keeps its id, sku and stock)
products +set-variants --id 7ab09fcd-… --rename "Color:Red=Wine Red"
products +set-variants --id 7ab09fcd-… --rename "Color=Colour"

# 15c. Several edits in one call — preview, relay "changes", then run
products +set-variants --id 7ab09fcd-… --drop "lenses=6lenses" --set "Style:Ocean" \
  --rename "Style:Ocean=2 lenses" --set-price 19.9 --dry-run

# 15d. Prices per value
products +set-variants --id 7ab09fcd-… --set-price "Size:S=20,M=25,L=30"

# 16. Put a product into a collection
products collects create --data '{"collect":{"collection_id":"999000","product_id":"555777"}}'

# 17. "Delete" a gift card you only know by code — resolve the id, preview the disable
#     (irreversible) in the SAME reply, then wait for the user's go-ahead
ID=$(products gift-cards list --params '{"keyword":"GC9988"}' --jq '.data.gift_cards[0].id')
products gift-cards disable --params '{"id":"'$ID'"}' --dry-run

参考资料

• references/variants.md — 变体的 CRUD、SKU 查询/更新、选项处理
• references/inventory-locations.md — 库存商品与库存水平、数量递减限制、位置
• references/collections-collects.md — 精选集与智能集合、收藏、类别
• references/images.md — 商品图片 CRUD
• references/gift-cards.md — 礼品卡生命周期（不可删除；可停用）
• references/comments.md — 客户评价（导入、列表）
• references/procurement-suppliers.md — 供应商、采购订单
• 各命令的标志：shoplazza products <cmd> --help
• 规格叶节点的参数/正文/响应：shoplazza schema products.<cmd>（嵌套：schema products.variants.update）
• 跨领域机制（认证/层级/输出封装/--dry-run/--jq/安全性）：../shoplazza-common/SKILL.md
• 快捷方式的权威来源：shortcuts/products/*.go