@round2ai/r2-cli 1.0.15 → 1.0.17

package/skills/r2-goods/references/r2-goods-alzc.md

@@ -0,0 +1,285 @@
+# R2-Goods 阿里资产（alzc）
+
+> **Prerequisite:** 读取 [`../SKILL.md`](../SKILL.md) 了解路由决策和命令概览。
+
+阿里资产是淘宝平台的 SPU/SKU 目录上架模式。商品来自平台目录，不需要上传图片或填写类目属性。
+
+## 业务流程
+
+```
+1. SPU 查询(szc spu-query)       → 选择 SPU，获取 jbpSpuId
+2. SPU 详情(alzc spu-detail)     → 获取可申请 SKU 列表(canApplySkuList)
+3. 申请上架(alzc apply)          → 选择 SKU + 价格 + 库存 → 提交
+4. 管理已上架商品（改库存 / 改价格 / 下架）
+```
+
+---
+
+## 第 1 步：查询 SPU 列表
+
+```bash
+r2-cli goods taobao alzc spu-query --shop-id <shopId> --goods-no <no> [--json]
+```
+
+**参数**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--shop-id <id>` | 是 | 淘宝店铺 ID |
+| `--goods-no <no>` | **是** | 商品编码（**必填，不传无法查询到商品**） |
+| `--spu-id <id>` | 否 | 精确查询指定 SPU（用户通常不知道，选填） |
+| `--page <n>` | 否 | 页码（从 1 开始，默认 1） |
+| `--size <n>` | 否 | 每页条数（默认 20） |
+
+> **重要**：`--goods-no` 实际为必填参数。Agent 在调 SPU 查询前**必须先向用户询问商品编码**。如果用户不知道商品编码，提示用户提供。
+
+**响应示例**：
+
+```json
+{
+  "items": [{
+    "jbpSpuId": 12345,
+    "spuTitle": "Nike Air Jordan 1",
+    "spuImage": "https://...",
+    "itemId": 67890,
+    "itemNumber": "SP001",
+    "brandName": "Nike",
+    "categoryName": "运动鞋",
+    "categoryId": 50025445,
+    "minPrice": 29900,
+    "applyStatus": 1,
+    "spuStatus": 1
+  }],
+  "total": "100",
+  "page": 1,
+  "perPage": 20
+}
+```
+
+> Agent 展示列表时提取关键字段：`spuTitle`、`brandName`、`categoryName`、`minPrice`（分→元）。让用户选择 `jbpSpuId`。
+
+---
+
+## 第 2 步：查询 SPU 详情（获取可申请 SKU）
+
+```bash
+r2-cli goods taobao alzc spu-detail --shop-id <shopId> --jbp-spu-id <jbpSpuId> --json
+```
+
+**参数**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--shop-id <id>` | 是 | 淘宝店铺 ID |
+| `--jbp-spu-id <id>` | 是 | 聚宝盆 SPU ID（从第 1 步获取） |
+
+**响应关键字段**：
+
+```json
+{
+  "jbpSpuId": 12345,
+  "needIdentify": true,
+  "identifyOrgId": "100",
+  "canApplySkuList": [{
+    "jbpSkuId": 1001,
+    "skuVersion": 1,
+    "minPrice": 29900,
+    "maxPrice": 59900,
+    "canApply": true,
+    "pvs": [{"name": "尺码", "value": "42"}]
+  }],
+  "haveApplySkuList": [{
+    "jbpSkuId": 1001,
+    "price": 29900,
+    "quantity": 10,
+    "sales": 5,
+    "auditStatus": 1
+  }]
+}
+```
+
+> **关键字段**：
+> - `canApplySkuList` 中 `canApply=true` 的 SKU 才可以申请上架
+> - `needIdentify=true` 时提交申请需传 `--identify-org-id`
+> - 记下 `jbpSkuId` 和 `skuVersion` 传给第 3 步
+
+**Agent 展示 SKU 列表**：
+
+```
+可申请 SKU：
+1. SKU 1001 | 尺码: 42 | 价格范围: ¥299.00 ~ ¥599.00
+2. SKU 1002 | 尺码: 43 | 价格范围: ¥299.00 ~ ¥599.00
+```
+
+---
+
+## 第 3 步：申请上架 SKU
+
+```bash
+r2-cli goods taobao alzc apply \
+  --shop-id <shopId> \
+  --jbp-spu-id <jbpSpuId> \
+  --apply-skus '[{"jbpSkuId":1001,"price":299,"quantity":10,"skuVersion":1}]' \
+  --spu-version <n> \
+  --delivery-id <id> \
+  --city-code <code> \
+  --city-name <name> \
+  --pro-code <code> \
+  --pro-name <name> \
+  --json
+```
+
+**参数**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--shop-id <id>` | 是 | 淘宝店铺 ID |
+| `--jbp-spu-id <id>` | 是 | 聚宝盆 SPU ID |
+| `--apply-skus <json>` | 是 | SKU 列表 JSON（见下方格式） |
+| `--spu-version <n>` | 否 | SPU 版本号（从 spu-detail 获取，建议传入） |
+| `--delivery-id <id>` | 是 | 发货方式 ID（从 spu-detail.delivery.deliveryId 获取） |
+| `--city-code <code>` | 是 | 城市编码（默认 330100 杭州市） |
+| `--city-name <name>` | 是 | 城市名称（默认"杭州市"） |
+| `--pro-code <code>` | 是 | 省份编码（默认 330000 浙江省） |
+| `--pro-name <name>` | 是 | 省份名称（默认"浙江省"） |
+| `--sub-item-id <id>` | 否 | 子商品 ID |
+| `--identify-org-id <id>` | **禁止传** | 见下方说明 |
+
+> **关于 `--identify-org-id`**：虽然 spu-detail 返回 `needIdentify=true` 和 `identifyOrgList`，但**不要传此参数**。传了会导致"鉴定机构id填写有误"。淘宝内部会自动处理鉴定流程。
+
+> **关于城市/省份参数**：虽然 API 文档标注为"否"，但淘宝实际要求必填。不传会报 `Missing required arguments:cityCode`。如果用户未指定发货地，默认用杭州。
+
+**`--apply-skus` 格式**：
+
+```json
+[
+  {"jbpSkuId": 1001, "price": 299, "quantity": 10, "skuVersion": 1},
+  {"jbpSkuId": 1002, "price": 399, "quantity": 5, "skuVersion": 1}
+]
+```
+
+> **价格单位**：CLI 接受**元**（如 `299` = 299 元），内部自动转为分（29900）调 API。`commodityCode` 为商家自定义编码，可选。**`skuVersion` 建议始终传入**，从 canApplySkuList 中获取。
+
+**成功返回**：`{ "success": true, "data": "成功" }`
+
+**Agent 友好输出**：
+
+```
+申请上架成功！
+- SPU: [spuTitle] (jbpSpuId: 12345)
+- SKU: 1001 | 极地白/S | ¥299 x 10
+- 店铺: [shopName]
+- 发货: [delivery.name]
+```
+
+> **追加 SKU 限制**：已申请过 SKU 的 SPU，追加新 SKU 可能失败（淘宝返回 `Remote service error`）。如果追加失败，建议一次性选择所有要上架的 SKU。
+
+---
+
+## 已上架商品管理
+
+### 查询已上架列表
+
+```bash
+r2-cli goods taobao listing --shop-id <shopId> [--goods-no <no>] [--page <n>] [--size <n>] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--shop-id <id>` | 是 | 淘宝店铺 ID |
+| `--goods-no <no>` | 否 | 按商品编码过滤 |
+| `--item-id <id>` | 否 | 按淘宝商品 ID 过滤 |
+| `--goods-name <name>` | 否 | 按商品名称过滤 |
+| `--status <n>` | 否 | 按商品状态过滤 |
+| `--code <code>` | 否 | 按商家编码过滤 |
+| `--page <n>` | 否 | 页码（从 1 开始） |
+| `--size <n>` | 否 | 每页条数 |
+
+> listing 只返回 SPU 级别信息。查看每个 SKU 的价格和库存需调用 `spu-detail`。
+
+### 修改 SKU 价格
+
+```bash
+r2-cli goods taobao price \
+  --jbp-spu-id <jbpSpuId> \
+  --jbp-sku-id <jbpSkuId> \
+  --shop-id <shopId> \
+  --sub-item-id <itemId> \
+  --price <amount> \
+  --json
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--jbp-spu-id <id>` | 是 | 聚宝盆 SPU ID |
+| `--jbp-sku-id <id>` | 是 | 聚宝盆 SKU ID |
+| `--shop-id <id>` | 是 | 淘宝店铺 ID |
+| `--sub-item-id <id>` | 否 | 子商品 ID（即已上架列表的 `itemId`，从 listing 获取） |
+| `--price <amount>` | 是 | 新价格，**单位：元**（API 直接传元，不转分） |
+
+> **重要**：改价和申请上架的 price 参数单位都是**元**（CLI 直接传元，API 内部转分存储）。`--sub-item-id` 建议传入，从 `goods taobao listing` 的 `itemId` 或 `spu-detail` 的 `haveApplySkuList.subItemId` 获取。
+
+### 修改 SKU 库存
+
+```bash
+r2-cli goods taobao stock \
+  --jbp-spu-id <jbpSpuId> \
+  --jbp-sku-id <jbpSkuId> \
+  --shop-id <shopId> \
+  --sub-item-id <itemId> \
+  --quantity <n> \
+  --json
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--jbp-spu-id <id>` | 是 | 聚宝盆 SPU ID |
+| `--jbp-sku-id <id>` | 是 | 聚宝盆 SKU ID |
+| `--shop-id <id>` | 是 | 淘宝店铺 ID |
+| `--sub-item-id <id>` | 否 | 子商品 ID（从 listing 的 `itemId` 获取） |
+| `--quantity <n>` | 是 | 新库存数量 |
+
+### 下架
+
+```bash
+# 下架整个 SPU
+r2-cli goods taobao down --jbp-spu-id <jbpSpuId> --shop-id <shopId> --json
+
+# 下架单个 SKU（需传 --sub-item-id）
+r2-cli goods taobao down --jbp-spu-id <jbpSpuId> --jbp-sku-id <jbpSkuId> --shop-id <shopId> --sub-item-id <itemId> --json
+```
+
+> **注意**：下架单个 SKU 时 `--sub-item-id` **必传**，不传会报 `Missing required arguments:subItemId:null`。从 `spu-detail` 的 `haveApplySkuList` 中获取 `subItemId`，或从 `goods taobao listing` 的 `itemId` 获取。
+
+---
+
+## Agent 常见错误预防
+
+- **`--apply-skus` 传 JSON 字符串**：值必须是 `JSON.stringify()` 后的字符串，不能直接传对象
+- **价格单位统一为元**：apply、price、stock 三个命令 CLI 统一接受元，API 内部自动转分。响应中 price 字段是分（展示时需 /100）
+- **`canApply=false` 的 SKU 不能申请**：提交前确认从 `canApplySkuList` 中选择 `canApply=true` 的 SKU
+- **禁止传 `--identify-org-id`**：即使 `needIdentify=true` 也不要传，否则报"鉴定机构id填写有误"
+- **`jbpSpuId` 和 `jbpSkuId` 是数字**：从 API 返回中直接取，不要转字符串
+- **城市/省份参数实际必填**：`cityCode`/`cityName`/`proCode`/`proName` 不传会报 `Missing required arguments:cityCode`，默认用杭州
+- **`deliveryId` 必传**：从 spu-detail 的 `delivery.deliveryId` 获取
+- **`spuVersion` 和 `skuVersion` 建议传入**：从 spu-detail 获取，避免版本冲突
+- **改价必须传 `--sub-item-id`**：从 `goods taobao listing` 的 `itemId` 字段获取，不传报 `Missing required arguments:subItemId`
+- **追加 SKU 可能失败**：已上架的 SPU 追加新 SKU 时淘宝可能返回 `Remote service error`，建议一次性选完 SKU
+
+## 错误处理
+
+| 错误信息 | 原因 | 解决方法 |
+|----------|------|----------|
+| `Missing required arguments:cityCode` | 缺少城市编码 | 传 `--city-code` `--city-name` `--pro-code` `--pro-name`（默认杭州） |
+| `鉴定机构id填写有误` | 传了 `--identify-org-id -1` | **去掉 `--identify-org-id` 参数**，不要传 |
+| `Missing required arguments:subItemId` | 改价/下架缺少子商品 ID | 从 `spu-detail` 的 `haveApplySkuList.subItemId` 或 listing 的 `itemId` 获取 |
+| `Remote service error` | 追加 SKU 或淘宝 API 异常 | 已上架 SPU 追加 SKU 可能不支持，尝试一次性上架所有 SKU |
+| `Cannot invoke getBody() is null` | 淘宝 API 返回空响应 | 检查是否缺少必填参数（如 cityCode），参考上面具体错误 |
+| `暂未开通此业务` | 店铺未开通阿里资产业务权限 | 联系平台小二开通 |
+| `--apply-skus JSON 解析失败` | JSON 格式错误 | 检查 JSON 格式，确保用单引号包裹 |
+| `--jbp-spu-id 必须为有效数字` | SPU ID 格式错误 | 从 spu-query 返回中获取正确的数字 ID |
+
+## References
+
+- [r2-goods SKILL.md](../SKILL.md) — 商品管理概览和路由决策
+- [r2-shared](../../r2-shared/SKILL.md) — 认证和全局规则

package/skills/r2-goods/references/r2-goods-hangup.md

@@ -2,22 +2,7 @@
 
 > **Prerequisite:** 读取 [`../SKILL.md`](../SKILL.md) 了解路由决策和命令概览。
 
-挂售模式支持完整商品信息：图片、类目、属性等。与普通上架（`goods up`）是不同流程。
-
-**核心理念**：**图片里能看到的，就别问用户**。Agent 从图片中提取一切可识别的信息，用户只需要提供价格。
-
-## 核心原则
-
-- **图片优先**：所有字段优先从图片提取，图片无法识别时才问用户
-- 必须问用户的只有：**价格**
-- 商家编码（`out-item-no`）**优先让用户自定义**，用户不填则推荐自动生成编码（如 `GS20260512-0005`）
-- **必须问用户的条件**：价格（永远无法从图片判断）。其他一切字段都应尝试从图片获取。商家编码优先用户自定义，不填则推荐自动生成
-- **描述必须自动生成**：基于 AI 识别的品牌+款式+颜色+材质+货号自动组合，不要标记为"需要补充"
-- **品牌必须双传**：`--brand-name`（文本字段）+ itemAttrs 中的一项（含 propId/valueId/valueName/propName/channelCatId），缺一不可
-- **季节自动推断**：根据商品类型推断适用季节（夹克/风衣→春秋季，羽绒服→秋冬季，T恤/短裤→夏季），不需要问用户
-- **尺码/货号从标签读取**：如果图片中有标签/吊牌/水洗标，尝试读取尺码和货号，读不到时才问用户
-- **标题自动组合**：品牌+款式+颜色+尺码+成色，自动组合为标题
-- 提交成功后展示上架结果摘要
+挂售模式支持完整商品信息：图片、类目、属性等。核心原则见 SKILL.md 的「关键注意事项」。
 
 ## 图片识别降级策略
 
@@ -26,7 +11,7 @@
 | 能查看图片（多模态） | 用 Read 工具读图 → 自动识别品牌/成色/类目/描述 |
 | 不能查看图片 | 跳过识别 → 向用户询问品牌、类目、成色、描述等信息 |
 
-> 不同 Agent 能力不同（Claude Code / Gemini 支持读图，部分 Agent 不支持）。Agent 应自行判断是否能识别图片，不能则直接走询问路径。两条路径最终都走相同的 submit 提交。
+> 不同 Agent 能力不同。Agent 应自行判断是否能识别图片，不能则直接走询问路径。两条路径最终都走相同的 submit 提交。
 
 ---
 
@@ -35,7 +20,8 @@
 **上传图片**：
 
 ```bash
-r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/path/img2.jpg --json
+r2-cli goods xianyu hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/path/img2.jpg --json
+# 或使用 CDN URL：--urls https://cdn.example.com/img1.jpg,https://cdn.example.com/img2.jpg
 ```
 
 返回：
@@ -50,7 +36,7 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 }
 ```
 
-> 图片路径是用户本地文件路径。`--image-ids` 保持字符串，不要转数字（19 位 ID 会精度丢失）。**CLI 自动压缩超过 2MB 的图片**（使用 sharp 渐进式降低 JPEG quality 直到 < 2MB，PNG 自动转 JPEG），原文件不会被修改。多张图片**并行上传**，单张失败自动重试 1 次。
+> 图片路径是用户本地文件路径。`--image-ids` 保持字符串，不要转数字（19 位 ID 会精度丢失）。**CLI 自动压缩超过 2MB 的图片**（sharp 渐进式降低 JPEG quality 直到 < 2MB，PNG 自动转 JPEG），原文件不会被修改。多张图片**并行上传**，单张失败自动重试 1 次。
 
 返回（部分成功时带 `warning` 和 `failed` 字段）：
 
@@ -71,23 +57,6 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 
 > **多图不一致处理**：如果多张图片显示不同商品（如不同款式、不同品牌），Agent 应识别后告知用户，只保留同一商品的图片。不要把不同商品混在一起提交。
 
-**图片识别 vs 用户操作**：
-
-| 字段 | 可从图片识别？ | 处理方式 |
-|------|---------------|----------|
-| `--title`（标题） | ✅ | **自动组合**：品牌+款式+颜色+尺码+成色，汇总确认 |
-| `--desc`（描述） | ✅ | **自动生成**：品牌+系列+款式+颜色+材质+货号+成色组合，不要标记为"需要补充" |
-| `--stuff-status`（成色） | ✅ | 自动判断，汇总确认 |
-| `--brand-name`（品牌） | ✅ | 识别后调 brands 搜索确认，**同时加入 itemAttrs**，汇总确认 |
-| `--category-id` / `--channel-cat-id` | ✅ | 自动推断，汇总确认 |
-| 季节属性 | ✅ | **自动推断**：夹克/风衣→春秋季，羽绒服→秋冬季，T恤/短裤→夏季，卫衣→春秋季等 |
-| `--size`（尺码） | ⚠️ | 有标签/吊牌则读取，无则汇总时问 |
-| `--goods-no`（货号） | ⚠️ | 有标签则读取，无则留空 |
-| 款式/颜色/材质属性 | ⚠️ | 能识别则自动匹配 propsValues，不能则汇总时问 |
-| `--price`（售价） | ❌ | **必须问用户** |
-| `--out-item-no`（商家编码） | ⚠️ | 先问用户自定义编码，不填则推荐自动生成（如 `GS20260512-0005`） |
-| `--shop-id`（店铺） | ❌ | 只有一个店铺时自动选，多个则问 |
-
 **成色判断映射**：
 
 | 图片中商品状态 | `--stuff-status` 值 |
@@ -97,15 +66,6 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 | 轻微使用痕迹 | `95`（95新） |
 | 明显使用痕迹 | `90`（9新） |
 
-**季节推断映射**：
-
-| 商品类型 | 适用季节 |
-|----------|----------|
-| 夹克、风衣、卫衣、针织衫 | 春秋季 |
-| 羽绒服、棉衣、毛呢大衣 | 秋冬季 |
-| T恤、短裤、背心、凉鞋 | 夏季 |
-| 基础款衬衫、休闲裤 | 四季 |
-
 **如果用户没提供价格和商家编码，此时询问**（不要留到最后）。
 
 ---
@@ -115,15 +75,22 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 **获取类目 → 自动匹配**：
 
 ```bash
-r2-cli goods hang-up categories --json
+r2-cli goods xianyu hang-up categories --json
 ```
 
-Agent 根据图片识别结果自动匹配类目（不需要用户从列表中选）。只在识别不确定时才展示列表。
+Agent 根据图片识别结果自动匹配类目（不需要用户从列表中选）。只在识别不确定时才展示列表：
+
+```
+请选择最匹配的类目：
+1. 男士鞋靴 > 低帮鞋（推荐）
+2. 男士鞋靴 > 运动鞋
+3. 男士鞋靴 > 板鞋
+```
 
 **获取属性 → 自动匹配**：
 
 ```bash
-r2-cli goods hang-up props --channel-cat-id <channelCatId> --json
+r2-cli goods xianyu hang-up props --channel-cat-id <channelCatId> --json
 ```
 
 Agent 遍历所有属性，尽量自动匹配：
@@ -136,20 +103,14 @@ Agent 遍历所有属性，尽量自动匹配：
 
 > **props API 说明**：`props` 返回所有属性及其 `propsValues`（非品牌属性可直接从这里选值）；品牌属性需额外调用 `brands` 搜索。
 
-**品牌精确匹配规则**：brands 搜索结果中必须选**完全匹配**的官方名称（如搜 Nike → 只选 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等）
-
-**品牌搜索注意事项**：
-- **支持大小写模糊搜索**：如搜索 `nike` 也能匹配到 `Nike/耐克`，搜索 `louis` 也能匹配到 `Louis Vuitton/路易威登`
-- **搜索结果中选择精确匹配**：如搜 nike 返回多个结果，选官方名称 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等
+**品牌精确匹配规则**：brands 搜索结果中必须选**完全匹配**的官方名称（如搜 Nike → 只选 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等）。**支持大小写模糊搜索**。
 
 ```bash
-r2-cli goods hang-up brands --channel-cat-id <id> --prop-id <品牌propId> --key "Nike" --json
+r2-cli goods xianyu hang-up brands --channel-cat-id <id> --prop-id <品牌propId> --key "Nike" --json
 ```
 
 最终构建 `--item-attrs`（**5 个字段：valueName、valueId、propId、propName、channelCatId**）：
 
-**⚠️ 品牌必须同时出现在 itemAttrs 和 --brand-name 中**。只传 `--brand-name` 不会把品牌写入商品属性，品牌必须作为 itemAttrs 的一项传入（含 propId、valueId、valueName、propName、channelCatId）。
-
 ```json
 [
   { "valueName": "Nike/耐克", "valueId": "68af4e8f...", "propId": "83b8f62c...", "propName": "品牌", "channelCatId": "f4718bbb..." },
@@ -190,7 +151,7 @@ Agent 将所有自动填充和识别结果汇总展示给用户，**一次确认
 **所有参数就绪后提交**：
 
 ```bash
-r2-cli goods hang-up submit \
+r2-cli goods xianyu hang-up submit \
   --shop-id <shopId> \
   --title "商品标题" \
   --price 599 \
@@ -206,13 +167,11 @@ r2-cli goods hang-up submit \
   --json
 ```
 
-成功返回：
+成功返回：`{ "success": true, "data": "挂售提交成功" }`
 
-```json
-{ "success": true, "data": "上架成功" }
-```
+### 友好输出指引
 
-**提交后展示上架结果摘要**（让用户知道上架了什么）：
+提交成功后，Agent 从流程中已收集的参数提取关键信息**汇总展示**，不依赖响应中的字段：
 
 ```
 上架成功！
@@ -224,6 +183,14 @@ r2-cli goods hang-up submit \
 - 店铺：xxx
 ```
 
+> Agent 提交前已收集所有参数（title、price、brand-name、category、stuff-status、shop-id），提交成功后直接用这些参数构建摘要，不要翻查历史记录。
+>
+> 如果提交失败（`success: false`），直接展示 `error` 字段内容：
+> ```
+> 上架失败：[error 内容]
+> ```
+> 不要展示整个 JSON。
+
 ---
 
 ## 必填字段处理
@@ -245,6 +212,8 @@ r2-cli goods hang-up submit \
 - **`--stuff-status` 准新是数字 `-1`**：不是字符串 `"-1"`，直接传 `--stuff-status -1`
 - **`--item-attrs` 传 JSON 字符串**：值必须是 `JSON.stringify()` 后的字符串，不能直接传对象。命令行示例：`--item-attrs '[{"propId":"x","valueId":"y"}]'`
 - **`--files` 和 `--image-ids` 都是逗号分隔**：不要多次传 `--files`，用逗号拼成单个值：`--files a.jpg,b.jpg`
+- **标题长度限制**：闲鱼标题上限 30 单位（半角字符 0.5、全角字符 1）。自动组合时如品牌+款式+颜色+尺码+成色超过限制，优先保留品牌和核心款式，省略成色或尺码。CLI 会校验用户提供的标题，超长报错
+- **价格上限**：售价上限 99,999,999 元，CLI 自动校验；原价仅展示用途，不校验上限
 - **`--category-id` 取 `catId` 不是 `id`**：categories 返回的数据中 `catId`（如 50106003）是真正的类目 ID，`id`（如 865）是自增 ID，不要用错
 
 ## 必填参数
@@ -252,7 +221,7 @@ r2-cli goods hang-up submit \
 | 参数 | 说明 |
 |------|------|
 | `--shop-id <id>` | 店铺 ID（即闲鱼用户名 account） |
-| `--title <title>` | 商品标题 |
+| `--title <title>` | 商品标题（最长 30 单位：半角 0.5/全角 1） |
 | `--price <amount>` | 售价 |
 | `--category-id <id>` | 大分类 ID（从 categories 获取） |
 | `--channel-cat-id <id>` | 小分类 ID（从 categories 获取） |
@@ -261,16 +230,6 @@ r2-cli goods hang-up submit \
 | `--desc <desc>` | 商品描述 |
 | `--out-item-no <no>` | 商家编码（同店铺唯一，用户自定义） |
 
-## 成色等级
-
-| 值 | 含义 |
-|----|------|
-| `100` | 全新 |
-| `-1` | 准新 |
-| `99` | 99新 |
-| `95` | 95新 |
-| `90` | 9新 |
-
 ## 可选参数
 
 | 参数 | 默认值 | 说明 |
@@ -289,17 +248,7 @@ r2-cli goods hang-up submit \
 
 ## 售后服务（默认关闭）
 
-提交时自动附带售后服务配置，**默认全部关闭**。卖家需在闲鱼 APP 开通后才能开启（我的 → 设置 → 卖家服务 → 保障服务），未开通的服务如果传 `true` 会导致提交失败（错误：`ITEM_CONDITION_NOT_SUPPORT_SIGN`）。
-
-| 服务 | 默认值 | 说明 |
-|------|--------|------|
-| 极速发货-24小时 | 关闭 | 24小时内发货 |
-| 描述不符包邮退 | 关闭 | 描述不符退货包邮 |
-| 七天无理由退货 | 关闭 | 支持七天无理由 |
-| 极速发货-10分钟 | 关闭 | 10分钟内响应 |
-| 极速发货-48小时 | 关闭 | 48小时内发货 |
-| 正品保障 | 关闭 | 正品保障服务 |
-| 虚拟-描述不符包退 | 关闭 | 虚拟商品描述不符包退 |
+提交时自动附带售后服务配置，**默认全部关闭**。卖家需在闲鱼 APP 开通后才能开启，未开通的服务如果传 `true` 会导致提交失败（错误：`ITEM_CONDITION_NOT_SUPPORT_SIGN`）。
 
 ## 挂售错误处理
 
@@ -309,11 +258,11 @@ r2-cli goods hang-up submit \
 | 413 / `图片太大` | 图片超过服务端大小限制 | CLI 自动压缩 > 2MB 的图片，如仍失败请手动压缩 |
 | `请填写有效的商品叶子类目` | category-id 或 channel-cat-id 错误 | 重新查询 categories |
 | `找不到传入的某些图片` | 图片 ID 无效或过期 | 重新上传图片 |
-| `商家编码重复` | out-item-no 同店铺已存在 | 更换唯一编码 |
-| `该商品已上架` | 挂售已下架商品重新提交使用了相同的 out-item-no | 更换新的 out-item-no，或检查 listing 确认该商品是否已在闲鱼端恢复上架 |
 | `ITEM_CONDITION_NOT_SUPPORT_SIGN` | 售后服务未开通或品类不支持 | 默认关闭售后，或在闲鱼 APP 开通对应服务 |
+| `标题过长` | 标题超过 30 单位限制 | 缩短标题，保留品牌和核心款式 |
 
 ## References
 
 - [r2-goods SKILL.md](../SKILL.md) — 商品管理概览和路由决策
 - [r2-shared](../../r2-shared/SKILL.md) — 认证和全局规则
+- [../scenes/r2-scene-hangup-fashion.md](../scenes/r2-scene-hangup-fashion.md) — 服装鞋包挂售场景指南