@round2ai/r2-cli 1.0.16 → 1.0.17

package/scripts/install.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * R2-CLI 安装脚本
+ *
+ * 三种调用场景（通过 npm_lifecycle_event + npm_command 环境变量区分）：
+ *   1. npx @round2ai/r2-cli@latest install       — 全局安装 CLI（postinstall 自动装 Skills）
+ *   2. npm install -g 触发 postinstall            — 安装 Skills
+ *   3. npx 下载时触发的 postinstall                — 跳过（避免重复安装）
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = "@round2ai/r2-cli@latest";
+const argv = process.argv.slice(2);
+const isJson = argv.includes("--json");
+
+/** 根据环境变量判断安装路由（纯函数，供测试使用） */
+export function getInstallRoute(env = process.env) {
+  const isPostinstall = env.npm_lifecycle_event === "postinstall";
+  const isNpx = env.npm_command === "exec";
+
+  if (isPostinstall && isNpx) return "skip";
+  if (isPostinstall) return "skills-only";
+  return "full-install";
+}
+
+// ——— Skills 安装 ———
+
+function installSkills() {
+  const skillsDir = path.join(__dirname, "..", "skills");
+  if (!fs.existsSync(skillsDir)) return;
+  try {
+    execSync(`npx skills add "${skillsDir}" --all -g`, {
+      stdio: "inherit",
+      timeout: 60_000,
+    });
+  } catch {
+    // 网络不可用或 skills CLI 失败时静默跳过
+  }
+}
+
+// ——— 主入口（仅直接执行时运行，import 时不触发） ———
+
+const scriptPath = path.resolve(process.argv[1] ?? "");
+if (scriptPath.includes(path.basename(fileURLToPath(import.meta.url)))) {
+  const route = getInstallRoute();
+
+  if (route === "skip") {
+    process.exit(0);
+  }
+
+  if (route === "skills-only") {
+    installSkills();
+    process.exit(0);
+  }
+
+  // 完整安装：全局 npm install
+  // npm install -g 会触发 postinstall → installSkills()
+  function log(msg) {
+    if (!isJson) console.log(msg);
+  }
+
+  try {
+    log("\x1b[36m正在安装 R2-CLI...\x1b[0m");
+    execSync(`npm install -g ${PKG}`, { stdio: "inherit" });
+
+    let version = "unknown";
+    try {
+      version = execSync("r2-cli --version", { encoding: "utf-8" }).trim();
+    } catch {}
+
+    if (isJson) {
+      console.log(JSON.stringify({
+        success: true,
+        data: { version, npmInstalled: true, skillsInstalled: true },
+      }, null, 2));
+    } else {
+      console.log(`\n\x1b[32m✓ R2-CLI ${version} 安装完成\x1b[0m`);
+      console.log("\x1b[32m✓ Skills 已配置\x1b[0m");
+      console.log("\n\x1b[36m快速开始：\x1b[0m");
+      console.log("  r2-cli auth login        # 扫码登录");
+      console.log("  r2-cli goods shops       # 查看店铺");
+      console.log("  r2-cli goods xianyu up   # 开始上架\n");
+    }
+  } catch {
+    if (isJson) {
+      console.log(JSON.stringify({
+        success: false,
+        error: `安装失败`,
+        errorType: "unknown",
+        suggestion: `手动安装：npm install -g ${PKG}`,
+      }));
+    } else {
+      console.error(`\n\x1b[31m✗ 安装失败\x1b[0m\n`);
+      console.error("请尝试以下方案：");
+      console.error("  1. 手动安装：");
+      console.error(`     npm install -g ${PKG}`);
+      console.error("  2. 使用镜像：");
+      console.error(`     npm install -g ${PKG} --registry=https://registry.npmmirror.com`);
+      console.error("  3. 检查网络或代理：");
+      console.error("     export https_proxy=http://your-proxy:port");
+      console.error(`     npm install -g ${PKG}\n`);
+    }
+    process.exit(1);
+  }
+}

package/skills/r2-goods/SKILL.md

@@ -17,6 +17,7 @@ metadata:
 > **Tip**: Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。遵守「友好输出原则」：提取关键字段展示，不丢原始 JSON。
 > **Tip**: 所有 `--json` 命令统一错误格式 `{ success: false, error: "..." }`，检查 `success` 判断成败。
 > **Tip**: 查询分页建议使用 `--page 1 --size 50`。若响应含分页信息则继续翻页取完。在查询前提醒用户通过 `--status` 或 `--stock-id` 缩小范围提高效率。
+> **Tip**: **上架、改价、编辑提交前，必须提醒用户可选 `--transport-fee`（运费，默认 0 包邮）和 `--yhb`（验货宝）。不要静默使用默认值。**
 
 商品管理专家，指导 AI Agent 完成商品上架、下架、改价、挂售全流程。
 
@@ -26,19 +27,55 @@ metadata:
 
 命令执行规则见 **r2-shared** skill 的「执行规则」。安装、统一错误格式见 **r2-shared** skill。认证登录见 **r2-auth** skill。
 
-## 上架路由决策
+**Agent 必须使用带平台前缀的新路径**（`goods xianyu up` / `goods taobao up`），不要使用旧路径（`goods up`）。详见 r2-shared「命令路径」。
 
-用户说"上架"时，按以下规则选择上架方式：
+## 平台路由决策
+
+闲鱼和淘宝是两套独立体系，ID 互不通用。所有涉及商品操作的命令都需要先确定平台。
+
+### 通用平台判断规则
+
+| 条件 | 判断结果 |
+|------|----------|
+| 用户明确说了平台（"闲鱼下架"、"淘宝改价"） | 用对应平台的命令 |
+| 用户从之前的列表中选了商品 | 从数据推断：有 `jbpSpuId` → 淘宝，有 `stockGoodsId` + `status` → 闲鱼 |
+| 用户未指定且无上下文 | **先查所有平台列表**，让用户选商品，再根据商品所属平台执行 |
+
+> **禁止**：凭上下文猜测平台。刚操作过淘宝不意味着"下架"就一定是淘宝。
+
+### 上架路由
 
 | 条件 | 上架方式 | 流程 |
 |------|----------|------|
-| 用户明确说"选品上架"，或商品**在选品库**中 | `goods up`（普通上架） | 店铺 → 仓库 → 选品商品 → 输入价格 → 提交 |
-| 用户明确说"挂售"，或用户**提供了图片** | `goods hang-up`（挂售上架） | 上传图片 → AI 读图识别 → 类目/属性 → 提交 |
+| 用户明确说"选品上架"，或商品**在选品库**中 | `goods xianyu up`（闲鱼普通上架） | 店铺 → 仓库 → 选品商品 → 输入价格 → 提交 |
+| 用户明确说"挂售"，或用户**提供了图片** | `goods xianyu hang-up`（闲鱼挂售上架） | 上传图片 → AI 读图识别 → 类目/属性 → 提交 |
+| 用户明确说"阿里资产"或"alzc" | `goods taobao alzc`（淘宝阿里资产上架） | SPU 查询 → SKU 详情 → 选择 SKU + 价格 → 申请上架 |
+
+用户只说"上架"未指定方式 → **必须询问**："选品上架、挂售上架还是阿里资产上架？"
+
+### 查询路由
+
+用户说"查上架列表"/"查询上架情况"且未指定平台时：
+
+1. `r2-cli goods shops --json` → 获取所有店铺，按 `platform` 分组
+2. 有 `xianyu` 店铺 → `r2-cli goods xianyu listing --json`（查闲鱼上架列表）
+3. 有 `taobao` 店铺 → `r2-cli goods taobao listing --shop-id <id> --json`（每个淘宝店铺都要查）
+4. 分区块展示：先展示「闲鱼上架列表」，再展示「淘宝上架列表」
 
-**判断方法**：
-1. 用户**明确指定**了上架方式 → 直接走对应流程
-2. 用户提供了图片文件 → 直接走 `goods hang-up`，Agent 用 Read 工具查看图片自动识别商品信息（如果 Read 工具返回 `[Unsupported Image]`，视为不能识别，走询问路径）
-3. 用户只说"上架"未指定方式 → **必须询问用户**："选品上架还是挂售上架？"
+### 下架/改价路由
+
+用户说"下架"或"改价"且未指定平台时：
+
+1. **有上下文商品**（用户从之前的列表中选了商品）→ 直接根据商品所属平台执行
+2. **无上下文** → 先按「查询路由」查所有平台列表 → 用户选择商品 → 根据平台执行对应命令
+
+| 操作 | 闲鱼命令 | 淘宝命令 |
+|------|----------|----------|
+| 下架 | `goods xianyu down --id <id>` | `goods taobao down --jbp-spu-id <> --shop-id <>` |
+| 改价 | `goods xianyu price --id <id> --price <>` | `goods taobao price --jbp-spu-id <> --jbp-sku-id <> --shop-id <> --sub-item-id <> --price <>` |
+| 修改信息 | `goods xianyu edit --id <id> ...` | 淘宝不支持独立编辑，需通过 SPU 重新申请 |
+
+> **禁止**：凭上下文猜测平台。刚操作过淘宝不意味着"下架"就一定是淘宝。
 
 ## 命令概览
 
@@ -49,31 +86,46 @@ metadata:
 | `r2-cli goods shops [--json]` | 查看已授权店铺 | [r2-goods-query](references/r2-goods-query.md) |
 | `r2-cli goods stocks [--json]` | 查看仓库 | [r2-goods-query](references/r2-goods-query.md) |
 | `r2-cli goods list [--stock-id <id>] [--json]` | 查看选品商品 | [r2-goods-query](references/r2-goods-query.md) |
-| `r2-cli goods listing [--status <up/down/sold>] [--json]` | 查询上架列表 | [r2-goods-query](references/r2-goods-query.md) |
+| `r2-cli goods xianyu listing [--status <up/down/sold>] [--json]` | 查询闲鱼上架列表 | [r2-goods-query](references/r2-goods-query.md) |
+| `r2-cli goods taobao listing --shop-id <id> [--json]` | 查询淘宝上架列表 | [r2-goods-alzc](references/r2-goods-alzc.md) |
 
 ### 上架/下架/改价/修改
 
 | 命令 | 说明 | 详细文档 |
 |------|------|----------|
-| `r2-cli goods up --stock-goods-id <> --shop-id <> --price <> --json` | 普通上架（选品商品） | [r2-goods-listing](references/r2-goods-listing.md) |
-| `r2-cli goods down --id <id> [--json]` | 下架商品 | [r2-goods-listing](references/r2-goods-listing.md) |
-| `r2-cli goods price --id <id> --price <amount> [--json]` | 修改价格 | [r2-goods-listing](references/r2-goods-listing.md) |
-| `r2-cli goods edit --id <id> [--title ...] --json` | 修改商品信息 | [r2-goods-listing](references/r2-goods-listing.md) |
+| `r2-cli goods xianyu up --stock-goods-id <> --shop-id <> --price <> --json` | 普通上架（选品商品） | [r2-goods-listing](references/r2-goods-listing.md) |
+| `r2-cli goods xianyu down --id <id> [--json]` | 下架商品 | [r2-goods-listing](references/r2-goods-listing.md) |
+| `r2-cli goods xianyu price --id <id> --price <amount> [--json]` | 修改价格 | [r2-goods-listing](references/r2-goods-listing.md) |
+| `r2-cli goods xianyu edit --id <id> [--title ...] --json` | 修改商品信息 | [r2-goods-listing](references/r2-goods-listing.md) |
+
+### 淘宝阿里资产管理
+
+| 命令 | 说明 | 详细文档 |
+|------|------|----------|
+| `r2-cli goods taobao listing --shop-id <id> [--goods-no <no>] [--json]` | 查询已报名商品 | [r2-goods-alzc](references/r2-goods-alzc.md) |
+| `r2-cli goods taobao alzc spu-query --shop-id <id> --goods-no <no> [--json]` | 查询可申请 SPU | [r2-goods-alzc](references/r2-goods-alzc.md) |
+| `r2-cli goods taobao alzc spu-detail --shop-id <id> --jbp-spu-id <id> [--json]` | 查询 SPU 详情（含 SKU） | [r2-goods-alzc](references/r2-goods-alzc.md) |
+| `r2-cli goods taobao alzc apply --shop-id <id> --jbp-spu-id <id> --apply-skus '<json>' [--json]` | 申请上架 SKU | [r2-goods-alzc](references/r2-goods-alzc.md) |
+| `r2-cli goods taobao price --jbp-spu-id <> --jbp-sku-id <> --shop-id <> --sub-item-id <> --price <> --json` | 修改 SKU 价格 | [r2-goods-alzc](references/r2-goods-alzc.md) |
+| `r2-cli goods taobao stock --jbp-spu-id <> --jbp-sku-id <> --shop-id <> --quantity <> [--json]` | 修改 SKU 库存 | [r2-goods-alzc](references/r2-goods-alzc.md) |
+| `r2-cli goods taobao down --jbp-spu-id <> --shop-id <> [--jbp-sku-id <>] [--sub-item-id <>] [--json]` | 下架商品 | [r2-goods-alzc](references/r2-goods-alzc.md) |
 
 ### 选品上架 4 步流程
 
 1. `r2-cli goods shops --json` → 展示店铺 → 用户选择 `shopId`
 2. `r2-cli goods stocks --json` → 展示仓库 → 用户选择 `stockId`
 3. `r2-cli goods list --stock-id <id> --json` → 展示商品 → 用户选择 `stockGoodsId`
-4. `r2-cli goods up --stock-goods-id <id> --shop-id <id> --price <amount> --json` → 提交
+4. `r2-cli goods xianyu up --stock-goods-id <id> --shop-id <id> --price <amount> --json` → 提交
 
 必填参数：`--stock-goods-id`、`--shop-id`（取 `shopId` 不是 `id`）、`--price`
 
+> **提交前提醒用户**：运费默认包邮（`--transport-fee 0`），如需收运费请提供金额。可选开启验货宝（`--yhb`），但价格须在品类验货宝价格区间内。
+
 ### 修改商品信息（edit）
 
 修改已上架商品的标题、描述、品牌、类目、图片、属性等。
 
-> **注意**：`goods edit` 不支持修改价格。改价需单独使用 `r2-cli goods price --id <id> --price <amount>`。
+> **注意**：`goods xianyu edit` 不支持修改价格。改价需单独使用 `r2-cli goods xianyu price --id <id> --price <amount>`。
 
 **路由决策**：
 
@@ -86,22 +138,23 @@ metadata:
 **定位商品**：优先使用 `--id <goodsListingId>`（从上架列表获取 `id` 字段），也可用 `--stock-goods-id <id> --account <shopId>`。
 
 **关键约束**：
+- **提交前提醒用户**：可同时修改运费（`--transport-fee`，默认 0 包邮）和验货宝（`--yhb`）
 - `--category-id` 和 `--channel-cat-id` 是**必填的**（后端复用挂售 DTO），即使不改类目也要传当前类目
-- **`--item-attrs` 必须包含 props 中所有属性，不只是修改的那一个**：后端替换整个属性列表，漏传的属性会被清除。调 `goods hang-up props --channel-cat-id <id> --json` 获取全部属性后，改目标值，其他保持原样一并传入
+- **`--item-attrs` 必须包含 props 中所有属性，不只是修改的那一个**：后端替换整个属性列表，漏传的属性会被清除。调 `goods xianyu hang-up props --channel-cat-id <id> --json` 获取全部属性后，改目标值，其他保持原样一并传入
 - Agent 应自动查询类目并匹配，不需要用户手动提供
 - AI 读图识别后填充的字段需展示给用户确认，不能静默覆盖已有信息
 - `--image-ids` 接受已上传的图片 ID，用户给图片文件时需先调 `hang-up upload-images` 上传
 
 **带图片的全自动流程**（Agent 自动完成，用户只需提供图片并确认）：
 
-1. **展示列表**：`goods listing --json` → 用户选择要修改的商品
+1. **展示列表**：`goods xianyu listing --json` → 用户选择要修改的商品
 2. **上传图片**：`hang-up upload-images --shop-id <shopId> --files <paths> --json`
 3. **AI 读图识别**：Agent 用 Read 工具查看图片，识别品牌/类目/成色/描述等
 4. **自动匹配类目**：`hang-up categories --json` → 根据识别结果匹配 catId + channelCatId
 5. **自动查询属性**：`hang-up props --channel-cat-id <id> --json` → 根据识别结果匹配成色/尺码/季节等
 6. **自动搜索品牌**：`hang-up brands --channel-cat-id <> --prop-id <> --key <品牌名> --json` → 获取品牌 valueId
 7. **汇总展示**：当前值 vs 变更值，让用户确认
-8. **提交**：`goods edit --id <goodsListingId> --category-id <> --channel-cat-id <> --image-ids <> --item-attrs <> --brand-name <> --json`
+8. **提交**：`goods xianyu edit --id <goodsListingId> --category-id <> --channel-cat-id <> --image-ids <> --item-attrs <> --brand-name <> --json`
 
 **核心原则**：用户只需提供图片 + 确认。类目匹配、属性填充、品牌搜索全部由 Agent 自动完成。
 
@@ -109,11 +162,11 @@ metadata:
 
 | 命令 | 说明 | 详细文档 |
 |------|------|----------|
-| `r2-cli goods hang-up categories [--json]` | 获取闲鱼类目 | [r2-goods-hangup](references/r2-goods-hangup.md) |
-| `r2-cli goods hang-up props --channel-cat-id <id> [--json]` | 获取属性列表 | [r2-goods-hangup](references/r2-goods-hangup.md) |
-| `r2-cli goods hang-up brands --channel-cat-id <> --prop-id <> --key <> [--json]` | 品牌搜索 | [r2-goods-hangup](references/r2-goods-hangup.md) |
-| `r2-cli goods hang-up upload-images --shop-id <> --files <> --json` | 上传图片 | [r2-goods-hangup](references/r2-goods-hangup.md) |
-| `r2-cli goods hang-up submit --shop-id <> --title <> ... --json` | 提交挂售上架 | [r2-goods-hangup](references/r2-goods-hangup.md) |
+| `r2-cli goods xianyu hang-up categories [--json]` | 获取闲鱼类目 | [r2-goods-hangup](references/r2-goods-hangup.md) |
+| `r2-cli goods xianyu hang-up props --channel-cat-id <id> [--json]` | 获取属性列表 | [r2-goods-hangup](references/r2-goods-hangup.md) |
+| `r2-cli goods xianyu hang-up brands --channel-cat-id <> --prop-id <> --key <> [--json]` | 品牌搜索 | [r2-goods-hangup](references/r2-goods-hangup.md) |
+| `r2-cli goods xianyu hang-up upload-images --shop-id <> --files <> --json` | 上传图片 | [r2-goods-hangup](references/r2-goods-hangup.md) |
+| `r2-cli goods xianyu hang-up submit --shop-id <> --title <> ... --json` | 提交挂售上架 | [r2-goods-hangup](references/r2-goods-hangup.md) |
 
 ### 挂售上架流程
 
@@ -121,7 +174,7 @@ metadata:
 2. **识别商品**：Agent 用 Read 工具查看图片，自动识别品牌/成色/类目/描述。不支持读图的 Agent 走询问路径
 3. **匹配类目**：`hang-up categories --json` → 自动匹配
 4. **匹配属性**：`hang-up props --channel-cat-id <id> --json` → 自动填充。品牌需调 `hang-up brands` 搜索
-5. **汇总展示**：自动填充的字段标 ✅，缺失字段标 ❓ 让用户补充。**运费默认包邮（`--transport-fee` 默认 0），需告知用户可修改**
+5. **汇总展示**：自动填充的字段标 ✅，缺失字段标 ❓ 让用户补充。**运费默认包邮（`--transport-fee` 默认 0），可选开启验货宝（`--yhb`），需告知用户可修改**
 6. **提交**：`hang-up submit` — 必填：`shop-id`、`title`、`price`、`category-id`、`channel-cat-id`、`image-ids`、`stuff-status`、`desc`、`out-item-no`
 
 **核心原则**：**图片里能看到的，就别问用户**。只问价格和商家编码（优先用户自定义，不填则推荐自动生成），其他全部从图片自动提取。
@@ -161,7 +214,7 @@ metadata:
 | 错误信息 | 原因 | 解决方法 |
 |----------|------|----------|
 | `请先运行 r2-cli auth login 登录` | 未登录或 Token 过期 | 执行 `r2-cli auth login --json` |
-| `Agent 模式需要 --stock-goods-id, --shop-id, --price` | `goods up --json` 缺少必填参数 | 补齐三个参数 |
+| `Agent 模式需要 --stock-goods-id, --shop-id, --price` | `goods xianyu up --json` 缺少必填参数 | 补齐三个参数 |
 | `请指定下架条件：--id 或 --stock-goods-id + --shop-id` | 下架缺少定位参数 | 补充参数 |
 | `--price <amount> 为必填参数` | 改价未提供价格 | 询问用户新价格 |
 | `请提供至少一张图片` | 挂售缺少图片 | 提供本地图片路径 |
@@ -171,4 +224,5 @@ metadata:
 | `该商品已上架` | 挂售已下架商品重新提交时 out-item-no 被占用 | 更换新的 out-item-no |
 | `标题过长` | 标题超过 30 单位限制（半角 0.5/全角 1） | 缩短标题，保留品牌和核心款式 |
 | `ITEM_CONDITION_NOT_SUPPORT_SIGN` | 售后服务未开通或品类不支持 | 默认关闭售后 |
-| `轮询超时` | 上架结果查询超时 | 稍后用 `goods listing` 查看 |
+| `YHB_PRICE_NOT_SUPPORT` | 验货宝价格不在该品类允许范围内（区间因品类而异） | 根据错误信息调整价格，或关闭验货宝 |
+| `轮询超时` | 上架结果查询超时 | 稍后用 `goods xianyu listing` 查看 |

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

@@ -20,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
 ```
 
 返回：
@@ -74,7 +75,7 @@ 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 根据图片识别结果自动匹配类目（不需要用户从列表中选）。只在识别不确定时才展示列表：
@@ -89,7 +90,7 @@ Agent 根据图片识别结果自动匹配类目（不需要用户从列表中
 **获取属性 → 自动匹配**：
 
 ```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 遍历所有属性，尽量自动匹配：
@@ -105,7 +106,7 @@ Agent 遍历所有属性，尽量自动匹配：
 **品牌精确匹配规则**：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**）：
@@ -150,7 +151,7 @@ Agent 将所有自动填充和识别结果汇总展示给用户，**一次确认
 **所有参数就绪后提交**：
 
 ```bash
-r2-cli goods hang-up submit \
+r2-cli goods xianyu hang-up submit \
   --shop-id <shopId> \
   --title "商品标题" \
   --price 599 \
@@ -166,7 +167,7 @@ r2-cli goods hang-up submit \
   --json
 ```
 
-成功返回：`{ "success": true, "data": "上架成功" }`
+成功返回：`{ "success": true, "data": "挂售提交成功" }`
 
 ### 友好输出指引