@round2ai/r2-cli 1.0.11 → 1.0.12-beta.1

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@round2ai/r2-cli",
-  "version": "1.0.11",
+  "version": "1.0.12-beta.1",
   "description": "R2-CLI，向 AI 开放二手潮奢交易全链路能力",
   "main": "dist/r2-cli.js",
   "type": "module",
   "bin": {
-    "r2-cli": "./dist/r2-cli.js"
+    "r2-cli": "dist/r2-cli.js"
   },
   "scripts": {
     "postinstall": "node scripts/install-skills.js",
     "build": "cross-env NODE_ENV=development node scripts/build.js",
     "build:prod": "cross-env NODE_ENV=production node scripts/build.js",
-    "dev": "node scripts/dev.js"
+    "dev": "node scripts/dev.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "round2ai",
@@ -25,7 +27,7 @@
   ],
   "files": [
     "dist",
-    "scripts",
+    "scripts/install-skills.js",
     "skills",
     "package.json",
     "README.md"
@@ -37,7 +39,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Round2AI/r2-cli"
+    "url": "git+https://github.com/Round2AI/r2-cli.git"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
@@ -56,6 +58,7 @@
     "cross-env": "^10.1.0",
     "dotenv": "^17.4.2",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.5"
   }
 }

package/scripts/install-skills.js

@@ -1,5 +1,5 @@
 /**
- * postinstall: 将 skills/ 复制到 ~/.agents/skills/ + 确保 ~/.claude/skills/ 符号链接存在
+ * postinstall: 将 skills/ 复制到 ~/.agents/skills/
  */
 
 import fs from "node:fs";
@@ -10,7 +10,6 @@ import { fileURLToPath } from "node:url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkgSkillsDir = path.join(__dirname, "..", "skills");
 const agentsDir = path.join(os.homedir(), ".agents", "skills");
-const claudeDir = path.join(os.homedir(), ".claude", "skills");
 
 if (!fs.existsSync(pkgSkillsDir)) process.exit(0);
 
@@ -18,37 +17,47 @@ fs.mkdirSync(agentsDir, { recursive: true });
 
 for (const name of fs.readdirSync(pkgSkillsDir)) {
   const rawSrc = path.join(pkgSkillsDir, name);
-  // npm 包内是真实目录，本地开发可能是 symlink → 解析真实路径
   let src;
   try { src = fs.realpathSync(rawSrc); } catch { continue; }
   if (!fs.statSync(src).isDirectory()) continue;
 
   const dest = path.join(agentsDir, name);
-  // 清空目标目录中的旧残留文件
   if (fs.existsSync(dest)) {
     for (const old of fs.readdirSync(dest)) {
-      fs.unlinkSync(path.join(dest, old));
+      const oldPath = path.join(dest, old);
+      fs.statSync(oldPath).isDirectory()
+        ? fs.rmSync(oldPath, { recursive: true })
+        : fs.unlinkSync(oldPath);
     }
   }
   fs.mkdirSync(dest, { recursive: true });
 
   for (const file of fs.readdirSync(src)) {
-    fs.copyFileSync(path.join(src, file), path.join(dest, file));
+    const fileSrc = path.join(src, file);
+    const fileDest = path.join(dest, file);
+    if (fs.statSync(fileSrc).isDirectory()) {
+      copyDir(fileSrc, fileDest);
+    } else {
+      fs.copyFileSync(fileSrc, fileDest);
+    }
   }
+}
 
-  // 确保 ~/.claude/skills/<name> 指向 ~/.agents/skills/<name>
-  const link = path.join(claudeDir, name);
-  if (!fs.existsSync(link)) {
-    fs.mkdirSync(claudeDir, { recursive: true });
-    const target = dest;
-    try {
-      fs.symlinkSync(target, link, "junction");
-    } catch {
-      // Windows 权限不足时 fallback：直接复制
-      fs.mkdirSync(link, { recursive: true });
-      for (const file of fs.readdirSync(dest)) {
-        fs.copyFileSync(path.join(dest, file), path.join(link, file));
-      }
+function copyDir(src, dest) {
+  if (fs.existsSync(dest)) {
+    for (const old of fs.readdirSync(dest)) {
+      const oldPath = path.join(dest, old);
+      fs.statSync(oldPath).isDirectory()
+        ? fs.rmSync(oldPath, { recursive: true })
+        : fs.unlinkSync(oldPath);
     }
   }
+  fs.mkdirSync(dest, { recursive: true });
+  for (const file of fs.readdirSync(src)) {
+    const fileSrc = path.join(src, file);
+    const fileDest = path.join(dest, file);
+    fs.statSync(fileSrc).isDirectory()
+      ? copyDir(fileSrc, fileDest)
+      : fs.copyFileSync(fileSrc, fileDest);
+  }
 }

package/skills/r2-auth/SKILL.md

@@ -1,21 +1,31 @@
 ---
 name: r2-auth
-description: R2-CLI 认证登录专家。扫码登录和闲鱼店铺授权。用于登录、login、auth、扫码、二维码、授权、xianyu、logout、登出、状态查询场景。Agent 使用 auth login --json 一步完成登录。Agent 必须先将 qrUrl 链接展示给用户，再等待扫码结果。
+version: 1.0.0
+description: "R2-CLI 认证登录专家。扫码登录和闲鱼店铺授权。用于登录、login、auth、扫码、二维码、授权、xianyu、logout、登出、状态查询场景。Agent 使用 auth login --json 一步完成登录。Agent 必须先将 qrUrl 链接展示给用户，再等待扫码结果。"
+metadata:
+  requires:
+    bins: ["r2-cli"]
+  cliHelp: "r2-cli auth --help"
+  related:
+    - "r2-shared"
 ---
 
-# R2-Auth Skill
+# R2-Auth (v1)
+
+> **Tip**: Agent 使用 `--json` 一步完成登录：生成二维码 + 自动打开浏览器 + 自动轮询。**必须先将 qrUrl 展示给用户**，再等待扫码结果。
+> **Tip**: 二维码 5 分钟过期，超时需重新执行命令。Token 存储在 `~/.r2-cli/config.json`。
 
 扫码登录 + 闲鱼店铺授权，专为 AI Agent 设计。
 
-## 命令前缀
+## CRITICAL
 
-见 **r2-cli** skill 的"命令前缀自动检测"章节。以下文档使用 `r2-cli` 作为前缀，根据检测结果替换。
+命令执行规则见 **r2-shared** skill 的「执行规则」。安装、统一错误格式见 **r2-shared** skill。
 
 ---
 
-## 扫码登录（一步式，推荐）
+## 扫码登录（auth login）
 
-一条命令完成：生成扫码页面 + 自动打开浏览器 + 自动轮询登录状态：
+### 一步式（推荐）
 
 ```bash
 r2-cli auth login --json
@@ -23,7 +33,7 @@ r2-cli auth login --json
 
 命令会依次输出两段 JSON：
 
-### 第 1 段：二维码信息（立即输出）
+**第 1 段：二维码信息（立即输出）**
 
 ```json
 {
@@ -39,24 +49,15 @@ r2-cli auth login --json
 |------|------|
 | `qrToken` | 二维码 token（轮询用，不需要手动使用） |
 | `expireTimeMs` | 二维码过期时间（毫秒），默认 5 分钟 |
-| `pollIntervalMs` | 轮询间隔（毫秒），不需要手动使用 |
 | `url` | 扫码链接（用户也可手动访问） |
 | `qrUrl` | 本地浏览器扫码页面链接 |
 
-### 第 2 段：登录结果（用户扫码确认后输出）
-
-成功：
+**第 2 段：登录结果（用户扫码确认后输出）**
 
 ```json
 { "success": true, "userInfo": { "nickname": "...", "mobile": "..." } }
 ```
 
-失败：
-
-```json
-{ "success": false, "error": "二维码已过期" }
-```
-
 ### Agent 操作步骤
 
 1. 用 Bash 工具 `run_in_background: true` 启动命令
@@ -73,11 +74,9 @@ r2-cli auth login --json
 
 **为什么必须先展示链接**：自动打开浏览器在某些环境下可能失败（远程服务器、SSH、无头终端）。链接是用户扫码的唯一保障，必须优先展示。
 
-> 旧版两步式流程（先 `auth login qr` 再 `auth login poll`）已废弃。如需手动轮询，可使用 `auth login poll --token <>`。
-
 ---
 
-## 闲鱼店铺授权
+## 闲鱼店铺授权（auth xianyu）
 
 流程与登录类似，同样一步完成：
 
@@ -85,7 +84,7 @@ r2-cli auth login --json
 r2-cli auth xianyu --json
 ```
 
-### 第 1 段：授权二维码信息（立即输出）
+**第 1 段：授权二维码信息（立即输出）**
 
 ```json
 {
@@ -100,28 +99,15 @@ r2-cli auth xianyu --json
 |------|------|
 | `state` | 授权状态 token（轮询用） |
 | `expireTimeMs` | 过期时间（毫秒），默认 5 分钟 |
-| `pollIntervalMs` | 轮询间隔（毫秒） |
 | `qrUrl` | 本地浏览器授权页面链接 |
 
-### 第 2 段：授权结果（用户扫码确认后输出）
-
-成功：
+**第 2 段：授权结果（用户扫码确认后输出）**
 
 ```json
 { "success": true, "shopId": "...", "shopName": "..." }
 ```
 
-失败：
-
-```json
-{ "success": false, "error": "授权链接已过期" }
-```
-
-Agent 操作步骤与登录相同：
-1. 获取第 1 段 JSON
-2. **先展示 `qrUrl` 链接给用户**（单独一行，醒目格式）
-3. 告知用户浏览器会尝试自动打开，如未打开请手动点击链接
-4. 等待第 2 段 JSON
+Agent 操作步骤与登录相同：获取第 1 段 JSON → **先展示 `qrUrl`** → 等待第 2 段 JSON。
 
 ---
 
@@ -129,20 +115,20 @@ Agent 操作步骤与登录相同：
 
 | 命令 | 说明 |
 |------|------|
-| `r2-cli auth login` | 扫码登录（自动打开浏览器，人类使用） |
-| `r2-cli auth login --json` | 扫码登录（输出 JSON + 自动打开浏览器，Agent 推荐） |
+| `r2-cli auth login` | 扫码登录（人类使用，自动打开浏览器） |
+| `r2-cli auth xianyu` | 闲鱼店铺授权（人类使用，自动打开浏览器） |
 | `r2-cli auth login poll --token <>` | 手动轮询登录状态（备选，不推荐） |
-| `r2-cli auth xianyu` | 闲鱼店铺授权（自动打开浏览器，人类使用） |
-| `r2-cli auth xianyu --json` | 闲鱼店铺授权（输出 JSON + 自动打开浏览器，Agent 推荐） |
 | `r2-cli auth xianyu poll --state <>` | 手动轮询授权状态（备选，不推荐） |
 | `r2-cli auth status` | 查看登录状态 |
 | `r2-cli auth logout` | 退出登录 |
 
 ---
 
-## 注意事项
+## 错误处理
 
-- 命令会尝试自动打开浏览器展示扫码页面，但链接始终会输出到终端，确保即使浏览器未打开用户也能手动访问
-- 二维码默认 5 分钟过期，超时需重新执行命令
-- 登录成功后 Token 存储在 `~/.r2-cli/config.json`（原子写入，防止中断导致丢失），后续 `goods` 等命令可直接使用
-- 内存缓存的 Token 带过期检查（5 分钟安全边际），过期自动重新读取
+| 错误信息 | 原因 | 解决方法 |
+|----------|------|----------|
+| `请先运行 r2-cli auth login 登录` | 未登录或 Token 过期 | 执行 `r2-cli auth login --json` |
+| `二维码已过期` | 扫码超时（5 分钟） | 重新执行命令 |
+| `授权链接已过期` | 授权扫码超时（5 分钟） | 重新执行命令 |
+| `网络连接失败` | API 服务不可达 | 检查网络连接，确认 SERVER_BASEURL 配置 |

package/skills/r2-goods/SKILL.md

@@ -1,206 +1,147 @@
 ---
 name: r2-goods
-description: R2-CLI 商品管理专家。用于商品上架/下架/改价、查看店铺/仓库/选品商品/上架列表。Agent 获取数据后展示给用户选择，完成 4 步上架流程。触发词：上架、下架、改价、商品列表、goods、up、down、price、shops、stocks、listing、list。
+version: 1.1.0
+description: "R2-CLI 商品管理专家。用于商品上架/下架/改价/修改信息/挂售、查看店铺/仓库/选品商品/上架列表。Agent 获取数据后展示给用户选择，完成 4 步上架流程。触发词：上架、下架、改价、修改商品、挂售、商品列表、goods、up、down、price、edit、hang-up、shops、stocks、listing、list。"
+metadata:
+  requires:
+    bins: ["r2-cli"]
+  cliHelp: "r2-cli goods --help"
+  minVersion: "1.0.12"
+  related:
+    - "r2-shared"
+    - "r2-auth"
 ---
 
-# R2-Goods Skill
+# R2-Goods (v1)
 
-商品管理专家，指导 AI Agent 完成商品上架、下架、改价全流程。
+> **Tip**: Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。
+> **Tip**: 所有 `--json` 命令统一错误格式 `{ success: false, error: "..." }`，检查 `success` 判断成败。
 
-## 命令前缀
+商品管理专家，指导 AI Agent 完成商品上架、下架、改价、挂售全流程。
 
-见 **r2-cli** skill 的"命令前缀自动检测"章节。
+## CRITICAL
 
-## 命令概览
-
-| 命令 | 说明 |
-|------|------|
-| `r2-cli goods shops [--json]` | 查看所有已授权店铺（跨平台） |
-| `r2-cli goods stocks [--json]` | 查看所有仓库 |
-| `r2-cli goods list [--stock-id <id>] [--stock-goods-id <id>] [--json]` | 查看选品商品（两个过滤参数均为可选，支持 `--page <n>` 和 `--size <n>`） |
-| `r2-cli goods listing [--json]` | 查询上架列表（支持多种过滤参数，见下方详细说明） |
-| `r2-cli goods up` | 交互式上架（人类使用，自动轮询上架结果） |
-| `r2-cli goods up --stock-goods-id <id> --shop-id <id> --price <amount> --json` | Agent 直接上架（自动轮询上架结果） |
-| `r2-cli goods down --id <id> [--json]` | 下架商品（也可用 `--stock-goods-id <id> --shop-id <id>`） |
-| `r2-cli goods price --id <id> --price <amount> [--json]` | 修改上架价格（也可用 `--stock-goods-id <id> --shop-id <id>`） |
-
----
-
-## Agent 上架流程（4 步）
-
-**每一步 Agent 获取数据后，必须展示给用户让用户做选择。不要让用户自己提供 ID。**
-
-### 第 1 步：获取店铺 → 用户选择
-
-```bash
-r2-cli goods shops --json
-```
-
-返回店铺列表，每个店铺包含：
-
-| 字段 | 说明 |
-|------|------|
-| `shopId` | 第三方店铺 ID（**上架参数取这个，不是 `id`**） |
-| `shopName` | 店铺名称 |
-| `platform` | 平台（xianyu / douyin 等） |
-
-展示给用户选择后记录 `shopId`。
-
-### 第 2 步：获取仓库 → 用户选择
-
-```bash
-r2-cli goods stocks --json
-```
-
-返回仓库列表，每个仓库包含：
+命令执行规则见 **r2-shared** skill 的「执行规则」。安装、统一错误格式见 **r2-shared** skill。认证登录见 **r2-auth** skill。
 
-| 字段 | 说明 |
-|------|------|
-| `stockId` | 仓库 ID（用于第 3 步过滤商品） |
-| `stockName` | 仓库名称 |
+## 上架路由决策
 
-### 第 3 步：获取选品商品 → 用户选择
+用户说"上架"时，按以下规则选择上架方式：
 
-```bash
-# 按仓库过滤（推荐，展示该仓库下所有可选商品）
-r2-cli goods list --stock-id <stockId> --json
+| 条件 | 上架方式 | 流程 |
+|------|----------|------|
+| 用户明确说"选品上架"，或商品**在选品库**中 | `goods up`（普通上架） | 店铺 → 仓库 → 选品商品 → 输入价格 → 提交 |
+| 用户明确说"挂售"，或用户**提供了图片** | `goods hang-up`（挂售上架） | 上传图片 → AI 读图识别 → 类目/属性 → 提交 |
 
-# 按商品 ID 精确查询单个商品
-r2-cli goods list --stock-goods-id <id> --json
+**判断方法**：
+1. 用户**明确指定**了上架方式 → 直接走对应流程
+2. 用户提供了图片文件 → 直接走 `goods hang-up`，Agent 用 Read 工具查看图片自动识别商品信息
+3. 用户只说"上架"未指定方式 → **必须询问用户**："选品上架还是挂售上架？"
 
-# 翻页查看更多商品
-r2-cli goods list --stock-id <stockId> --page 2 --size 20 --json
-```
-
-返回商品列表，每个商品包含：
-
-| 字段 | 说明 |
-|------|------|
-| `stockGoodsId` | 库存商品 ID（**上架参数取这个**） |
-| `goodsName` | 商品名称 |
-| `brand` | 品牌 |
-| `size` | 尺码 |
-| `salePrice` | 建议售价 |
-| `cate1Name` / `cate2Name` / `cate3Name` | 分类 |
-
-### 第 4 步：提交上架
-
-```bash
-r2-cli goods up --stock-goods-id <stockGoodsId> --shop-id <shopId> --price <amount> --json
-```
-
-命令会自动轮询上架进度（每 2 秒查询一次，最多 10 秒），最终返回：
-
-```json
-{
-  "success": true,
-  "data": {
-    "submit": { "...提交结果..." },
-    "listing": {
-      "id": "上架记录ID",
-      "status": "up",
-      "goodsName": "...",
-      "price": 299,
-      "...": "..."
-    }
-  }
-}
-```
-
-检查 `data.listing.status` 判断最终状态：
+## 命令概览
 
-| status | 含义 |
-|--------|------|
-| `init` | 待上架（处理中，正常不应出现在最终结果） |
-| `up` | 已上架成功 |
-| `down` | 已下架 |
-| `fail` | 上架失败，查看 `errorMsg` 了解原因 |
+### 查询
 
-### 上架参数说明
+| 命令 | 说明 | 详细文档 |
+|------|------|----------|
+| `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 [--json]` | 查询上架列表 | [r2-goods-query](references/r2-goods-query.md) |
 
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--stock-goods-id <id>` | 是 | 库存商品 ID（来自第 3 步的 `stockGoodsId`） |
-| `--shop-id <id>` | 是 | 第三方店铺 ID（来自第 1 步的 `shopId`，**不是 `id`**） |
-| `--price <amount>` | 是 | 上架价格（正数） |
-| `-p, --platform <platform>` | 否 | 平台，默认 xianyu |
-| `--json` | 否 | JSON 输出（Agent 推荐使用） |
+### 上架/下架/改价/修改
 
----
+| 命令 | 说明 | 详细文档 |
+|------|------|----------|
+| `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) |
 
-## 下架商品
+### 选品上架 4 步流程
 
-**Agent 必须先向用户确认后再执行下架操作。**
+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` → 提交
 
-支持两种方式指定商品（二选一）：
+必填参数：`--stock-goods-id`、`--shop-id`（取 `shopId` 不是 `id`）、`--price`
 
-```bash
-# 方式 1：通过上架记录 ID（来自 listing 列表的 id 字段）
-r2-cli goods down --id <goodsListingId> --json
+### 修改商品信息（edit）
 
-# 方式 2：通过库存商品 ID + 店铺 ID
-r2-cli goods down --stock-goods-id <id> --shop-id <id> --json
-```
+修改已上架商品的标题、描述、品牌、类目、图片、属性等。
 
-参数校验：必须提供 `--id` 或同时提供 `--stock-goods-id` 和 `--shop-id`，否则返回错误。
+**路由决策**：
 
----
+| 用户意图 | 流程 |
+|----------|------|
+| 提供了图片文件 | 全自动：读图识别 → 上传图片 → 匹配类目/属性/品牌 → 展示变更 → 用户确认 → 提交 |
+| 指定了具体字段（如"改标题为X"） | 直接修改指定字段，不动图片 |
+| 说"修改/更新商品信息"但没给细节 | 提示：可以提供图片自动识别商品信息，也可以指定要修改的具体字段 |
 
-## 修改价格
+**定位商品**：优先使用 `--id <goodsListingId>`（从上架列表获取 `id` 字段），也可用 `--stock-goods-id <id> --account <shopId>`。
 
-**Agent 必须先询问用户新价格，不能自行决定价格。** 用户说"修改价格"时，先问"要改成多少？"。
+**关键约束**：
+- `--category-id` 和 `--channel-cat-id` 是**必填的**（后端复用挂售 DTO），即使不改类目也要传当前类目
+- Agent 应自动查询类目并匹配，不需要用户手动提供
+- AI 读图识别后填充的字段需展示给用户确认，不能静默覆盖已有信息
+- `--image-ids` 接受已上传的图片 ID，用户给图片文件时需先调 `hang-up upload-images` 上传
 
-```bash
-# 方式 1：通过上架记录 ID
-r2-cli goods price --id <goodsListingId> --price <新价格> --json
+**带图片的全自动流程**（Agent 自动完成，用户只需提供图片并确认）：
 
-# 方式 2：通过库存商品 ID + 店铺 ID
-r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --json
-```
+1. **展示列表**：`goods 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`
 
-`--price` 为必填参数。同样需要提供 `--id` 或 `--stock-goods-id + --shop-id`。
+**核心原则**：用户只需提供图片 + 确认。类目匹配、属性填充、品牌搜索全部由 Agent 自动完成。
 
----
+### 挂售（hang-up）
 
-## 查询上架列表
+| 命令 | 说明 | 详细文档 |
+|------|------|----------|
+| `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) |
 
-```bash
-# 查看所有上架记录
-r2-cli goods listing --json
+### 挂售上架流程
 
-# 过滤查询
-r2-cli goods listing --status up --json                    # 只看已上架
-r2-cli goods listing --shop-id <id> --json                  # 按店铺过滤
-r2-cli goods listing --stock-goods-id <id> --json           # 按商品过滤
-r2-cli goods listing --id <id> --json                       # 精确查询
-```
+1. **上传图片**：`hang-up upload-images --shop-id <> --files <paths> --json`
+2. **识别商品**：Agent 用 Read 工具查看图片，自动识别品牌/成色/类目/描述。不支持读图的 Agent 走询问路径
+3. **匹配类目**：`hang-up categories --json` → 自动匹配
+4. **匹配属性**：`hang-up props --channel-cat-id <id> --json` → 自动填充。品牌需调 `hang-up brands` 搜索
+5. **汇总展示**：自动填充的字段标 ✅，缺失字段标 ❓ 让用户补充
+6. **提交**：`hang-up submit` — 必填：`shop-id`、`title`、`price`、`category-id`、`channel-cat-id`、`image-ids`、`stuff-status`、`desc`、`out-item-no`
 
-支持的过滤参数：
+**核心原则**：**图片里能看到的，就别问用户**。只问价格和商家编码，其他全部从图片自动提取。
 
-| 参数 | 说明 |
-|------|------|
-| `--id <id>` | 上架记录 ID |
-| `--stock-goods-id <id>` | 库存商品 ID |
-| `--shop-id <id>` | 店铺 ID |
-| `--stock-id <id>` | 仓库 ID |
-| `-s, --status <status>` | 状态过滤：`init` / `up` / `down` / `fail` |
-| `-p, --platform <platform>` | 平台，默认 xianyu |
+**关键注意事项**：
+- **品牌必须双传**：`--brand-name` + itemAttrs 中的一项（含 propId/valueId/valueName），缺一不可
+- **描述自动生成**：品牌+款式+颜色+材质+货号自动组合，不要标记为"需要补充"
+- **季节自动推断**：夹克→春秋季，羽绒服→秋冬季，T恤→夏季等，不需要问用户
+- **尺码/货号从标签读取**：图片中有标签时自动提取，读不到才问用户
+- **标题自动组合**：品牌+款式+颜色+尺码+成色
 
----
+> Agent 执行具体操作时，用 Read 工具读取对应的 reference 文件获取完整参数和流程说明。
 
 ## 错误处理
 
-所有 `--json` 命令统一错误格式：
-
-```json
-{ "success": false, "error": "错误信息" }
-```
-
-检查 `success` 字段判断成败。常见错误：
+所有 `--json` 命令统一错误格式：`{ "success": false, "error": "错误信息" }`
 
 | 错误信息 | 原因 | 解决方法 |
 |----------|------|----------|
 | `请先运行 r2-cli auth login 登录` | 未登录或 Token 过期 | 执行 `r2-cli auth login --json` |
-| `请指定下架条件：--id 或 --stock-goods-id + --shop-id` | 缺少必要参数 | 补充参数 |
-| `--price <amount> 为必填参数` | 改价时未提供价格 | 询问用户新价格后传入 |
-| `轮询超时` | 上架结果查询超时 | 建议用户稍后用 `goods listing` 查看 |
+| `Agent 模式需要 --stock-goods-id, --shop-id, --price` | `goods up --json` 缺少必填参数 | 补齐三个参数 |
+| `请指定下架条件：--id 或 --stock-goods-id + --shop-id` | 下架缺少定位参数 | 补充参数 |
+| `--price <amount> 为必填参数` | 改价未提供价格 | 询问用户新价格 |
+| `请提供至少一张图片` | 挂售缺少图片 | 提供本地图片路径 |
+| `商品不存在` | edit 用了无效的 `--id` 或商品已被删除 | 确认 listing 列表中的 id 值 |
+| `getCategoryId() is null` | edit 缺少 `--category-id` | 必须传 `--category-id` 和 `--channel-cat-id` |
+| `商家编码重复` | out-item-no 同店铺已存在 | 更换唯一编码 |
+| `ITEM_CONDITION_NOT_SUPPORT_SIGN` | 售后服务未开通或品类不支持 | 默认关闭售后 |
+| `轮询超时` | 上架结果查询超时 | 稍后用 `goods listing` 查看 |