@round2ai/r2-cli 1.0.15 → 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-auth/SKILL.md

@@ -19,6 +19,8 @@ metadata:
 
 ## CRITICAL
 
+**CRITICAL -- 开始前 MUST 先用 Read 工具读取 [../r2-shared/SKILL.md](../r2-shared/SKILL.md)**，其中包含执行规则、版本检查、统一错误格式、网络重试策略和 Token 过期恢复流程。
+
 命令执行规则见 **r2-shared** skill 的「执行规则」。安装、统一错误格式见 **r2-shared** skill。
 
 ---
@@ -119,14 +121,14 @@ Agent 操作步骤与登录相同：启动命令 → 获取第 1 段 JSON → **
 
 ## 其他命令
 
-| 命令 | 说明 |
-|------|------|
-| `r2-cli auth login` | 扫码登录（人类使用，自动打开浏览器） |
-| `r2-cli auth xianyu` | 闲鱼店铺授权（人类使用，自动打开浏览器） |
-| `r2-cli auth login poll --token <>` | 手动轮询登录状态（备选，不推荐） |
-| `r2-cli auth xianyu poll --state <>` | 手动轮询授权状态（备选，不推荐） |
-| `r2-cli auth status` | 查看登录状态 |
-| `r2-cli auth logout` | 退出登录 |
+| 命令 | 说明 | 详细文档 |
+|------|------|----------|
+| `r2-cli auth login` | 扫码登录（人类使用，自动打开浏览器） | [r2-auth-login](references/r2-auth-login.md) |
+| `r2-cli auth xianyu` | 闲鱼店铺授权（人类使用，自动打开浏览器） | [r2-auth-login](references/r2-auth-login.md) |
+| `r2-cli auth login poll --token <>` | 手动轮询登录状态（备选，不推荐） | [r2-auth-login](references/r2-auth-login.md) |
+| `r2-cli auth xianyu poll --state <>` | 手动轮询授权状态（备选，不推荐） | [r2-auth-login](references/r2-auth-login.md) |
+| `r2-cli auth status` | 查看登录状态 | [r2-auth-status](references/r2-auth-status.md) |
+| `r2-cli auth logout` | 退出登录 | [r2-auth-logout](references/r2-auth-logout.md) |
 
 ---
 

package/skills/r2-auth/_meta.json

@@ -1,5 +1,5 @@
 {
   "ownerId": "round2ai",
   "slug": "r2-auth",
-  "version": "0.1.0"
+  "version": "1.0.0"
 }

package/skills/r2-auth/references/r2-auth-login.md

@@ -0,0 +1,68 @@
+# r2-auth-login — 扫码登录 / 闲鱼授权
+
+## `auth login --json` — 扫码登录
+
+```bash
+r2-cli auth login --json
+```
+
+**两段 JSON 输出：**
+
+第 1 段（立即输出，二维码信息）：
+
+| 字段 | 说明 |
+|------|------|
+| `qrToken` | 二维码 token（内置轮询使用） |
+| `expireTimeMs` | 二维码过期时间（毫秒），默认 5 分钟 |
+| `qrUrl` | 本地扫码页面链接，需展示给用户 |
+| `pollIntervalMs` | 轮询间隔（毫秒） |
+
+第 2 段（用户扫码后输出）：
+
+```json
+{ "success": true, "userInfo": { "nickname": "...", "mobile": "..." } }
+```
+
+## `auth xianyu --json` — 闲鱼店铺授权
+
+```bash
+r2-cli auth xianyu --json
+```
+
+第 1 段（立即输出）：
+
+| 字段 | 说明 |
+|------|------|
+| `state` | 授权状态 token |
+| `expireTimeMs` | 过期时间，默认 5 分钟 |
+| `qrUrl` | 本地授权页面链接 |
+| `pollIntervalMs` | 轮询间隔（毫秒） |
+
+第 2 段（用户扫码后输出）：
+
+```json
+{ "success": true, "shopId": "...", "shopName": "..." }
+```
+
+## 手动轮询（不推荐）
+
+`auth login` 和 `auth xianyu` 的 `--json` 模式已内置自动轮询，通常不需要手动调用 poll 命令。仅在命令中断需要恢复时使用：
+
+```bash
+r2-cli auth login poll --token <qrToken>
+r2-cli auth xianyu poll --state <state>
+```
+
+## 错误处理
+
+| 错误信息 | 原因 | 解决方法 |
+|----------|------|----------|
+| `二维码已过期` | 扫码超时（5 分钟） | 重新执行命令 |
+| `授权链接已过期` | 授权扫码超时（5 分钟） | 重新执行命令 |
+| `网络连接失败` | API 服务不可达 | 检查网络连接，确认 SERVER_BASEURL 配置 |
+| `请先运行 r2-cli auth login 登录` | Token 过期或未登录 | 执行 `r2-cli auth login --json` |
+
+## 参考
+
+- [../SKILL.md](../SKILL.md) — 认证命令完整流程
+- [../../r2-shared/SKILL.md](../../r2-shared/SKILL.md) — 执行规则和错误格式

package/skills/r2-auth/references/r2-auth-logout.md

@@ -0,0 +1,29 @@
+# r2-auth-logout — 退出登录
+
+## 命令
+
+```bash
+r2-cli auth logout [--json]
+```
+
+## 说明
+
+清除本地存储的登录凭证（`~/.r2-cli/config.json`）。
+
+**安全确认**：Agent 执行前必须先询问用户确认，不要静默执行。
+
+## 输出
+
+```json
+{ "success": true, "message": "已退出登录" }
+```
+
+## 注意事项
+
+- 退出后需要重新执行 `auth login --json` 才能继续操作
+- 退出不会影响已上架的商品
+
+## 参考
+
+- [../SKILL.md](../SKILL.md) — 认证命令
+- [r2-auth-login](r2-auth-login.md) — 重新登录流程

package/skills/r2-auth/references/r2-auth-status.md

@@ -0,0 +1,27 @@
+# r2-auth-status — 查看登录状态
+
+## 命令
+
+```bash
+r2-cli auth status [--json]
+```
+
+## 输出
+
+不传 `--json` 时输出人类可读状态信息。传 `--json` 时：
+
+```json
+{ "success": true, "data": { "loggedIn": true, "userInfo": { ... } } }
+```
+
+## 常见状态
+
+| 状态 | 含义 | Agent 操作 |
+|------|------|-----------|
+| `loggedIn: true` | 已登录，Token 有效 | 可继续执行业务命令 |
+| `loggedIn: false` | 未登录或 Token 过期 | 引导用户执行 `auth login --json` |
+
+## 参考
+
+- [../SKILL.md](../SKILL.md) — 认证命令
+- [../../r2-shared/SKILL.md](../../r2-shared/SKILL.md) — Token Expiry Recovery

package/skills/r2-goods/SKILL.md

@@ -14,28 +14,68 @@ metadata:
 
 # R2-Goods (v1)
 
-> **Tip**: Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。
+> **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 完成商品上架、下架、改价、挂售全流程。
 
 ## CRITICAL
 
+**CRITICAL -- 开始前 MUST 先用 Read 工具读取 [../r2-shared/SKILL.md](../r2-shared/SKILL.md)**（执行规则、版本检查、错误格式、网络重试、Token 恢复），然后读取 [../r2-auth/SKILL.md](../r2-auth/SKILL.md) 确保已登录。
+
 命令执行规则见 **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 重新申请 |
+
+> **禁止**：凭上下文猜测平台。刚操作过淘宝不意味着"下架"就一定是淘宝。
 
 ## 命令概览
 
@@ -46,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>`。
 
 **路由决策**：
 
@@ -83,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 自动完成。
 
@@ -106,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) |
 
 ### 挂售上架流程
 
@@ -118,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`
 
 **核心原则**：**图片里能看到的，就别问用户**。只问价格和商家编码（优先用户自定义，不填则推荐自动生成），其他全部从图片自动提取。
@@ -128,7 +184,7 @@ metadata:
 - **描述自动生成**：品牌+款式+颜色+材质+货号自动组合，不要标记为"需要补充"
 - **季节自动推断**：夹克→春秋季，羽绒服→秋冬季，T恤→夏季等，不需要问用户
 - **尺码/货号从标签读取**：图片中有标签时自动提取，读不到才问用户
-- **标题自动组合**：品牌+款式+颜色+尺码+成色
+- **标题自动组合**：品牌+款式+颜色+尺码+成色，**最长 30 单位**（半角字符 0.5、全角字符 1，约 30 汉字或 60 英文）。超长时优先保留品牌和核心款式，省略成色或尺码
 - **stuff-status 与 itemAttrs 成色映射**：
 
 | stuff-status | itemAttrs 成色 valueName |
@@ -143,6 +199,14 @@ metadata:
 
 > Agent 执行具体操作时，用 Read 工具读取对应的 reference 文件获取完整参数和流程说明。
 
+## 场景指南
+
+| 场景 | 说明 | 指南 |
+|------|------|------|
+| 服装/鞋包挂售 | 服装、鞋类、包袋的季节推断与属性指南 | [scenes/r2-scene-hangup-fashion.md](scenes/r2-scene-hangup-fashion.md) |
+| 带图片修改商品 | 用户提供图片时自动修改商品信息的全流程 | [scenes/r2-scene-edit-with-images.md](scenes/r2-scene-edit-with-images.md) |
+| 批量操作 | 多商品上架、跨店铺操作与分页策略 | [scenes/r2-scene-batch-operations.md](scenes/r2-scene-batch-operations.md) |
+
 ## 错误处理
 
 所有 `--json` 命令统一错误格式：`{ "success": false, "error": "错误信息" }`
@@ -150,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> 为必填参数` | 改价未提供价格 | 询问用户新价格 |
 | `请提供至少一张图片` | 挂售缺少图片 | 提供本地图片路径 |
@@ -158,5 +222,7 @@ metadata:
 | `getCategoryId() is null` | edit 缺少 `--category-id` | 必须传 `--category-id` 和 `--channel-cat-id` |
 | `商家编码重复` | out-item-no 同店铺已存在 | 更换唯一编码 |
 | `该商品已上架` | 挂售已下架商品重新提交时 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/_meta.json

@@ -1,5 +1,5 @@
 {
   "ownerId": "round2ai",
   "slug": "r2-goods",
-  "version": "0.1.0"
+  "version": "1.1.0"
 }