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

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

@@ -0,0 +1,284 @@
+# R2-Goods 闲鱼挂售（hang-up）
+
+> **Prerequisite:** 读取 [`../SKILL.md`](../SKILL.md) 了解路由决策和命令概览。
+
+挂售模式支持完整商品信息：图片、类目、属性等。与普通上架（`goods up`）是不同流程。
+
+**核心理念**：**图片里能看到的，就别问用户**。Agent 从图片中提取一切可识别的信息，用户只需要提供价格和商家编码。
+
+## 核心原则
+
+- **图片优先**：所有字段优先从图片提取，图片无法识别时才问用户
+- 必须问用户的只有：**价格、商家编码**
+- **必须问用户的条件**：价格（永远无法从图片判断）和商家编码（用户自定义）。其他一切字段都应尝试从图片获取
+- **描述必须自动生成**：基于 AI 识别的品牌+款式+颜色+材质+货号自动组合，不要标记为"需要补充"
+- **品牌必须双传**：`--brand-name`（文本字段）+ itemAttrs 中的一项（含 propId/valueId/valueName），缺一不可
+- **季节自动推断**：根据商品类型推断适用季节（夹克/风衣→春秋季，羽绒服→秋冬季，T恤/短裤→夏季），不需要问用户
+- **尺码/货号从标签读取**：如果图片中有标签/吊牌/水洗标，尝试读取尺码和货号，读不到时才问用户
+- **标题自动组合**：品牌+款式+颜色+尺码+成色，自动组合为标题
+- 提交成功后展示上架结果摘要
+
+## 图片识别降级策略
+
+| Agent 能力 | 处理方式 |
+|------------|----------|
+| 能查看图片（多模态） | 用 Read 工具读图 → 自动识别品牌/成色/类目/描述 |
+| 不能查看图片 | 跳过识别 → 向用户询问品牌、类目、成色、描述等信息 |
+
+> 不同 Agent 能力不同（Claude Code / Gemini 支持读图，部分 Agent 不支持）。Agent 应自行判断是否能识别图片，不能则直接走询问路径。两条路径最终都走相同的 submit 提交。
+
+---
+
+## 第 1 步：上传图片 + 识别商品信息（并行）
+
+**上传图片**：
+
+```bash
+r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/path/img2.jpg --json
+```
+
+返回：
+
+```json
+{
+  "success": true,
+  "images": [
+    { "value": "1086608743767730915" },
+    { "value": "1086608743823622409" }
+  ]
+}
+```
+
+> 图片路径是用户本地文件路径。`--image-ids` 保持字符串，不要转数字（19 位 ID 会精度丢失）。
+
+**同时尝试识别图片**：如果 Agent 支持多模态（如 Claude Code、Gemini），用 Read 工具查看用户图片文件，识别以下信息。不支持则跳过，全部改为向用户询问。
+
+> **多图不一致处理**：如果多张图片显示不同商品（如不同款式、不同品牌），Agent 应识别后告知用户，只保留同一商品的图片。不要把不同商品混在一起提交。
+
+**图片识别 vs 用户操作**：
+
+| 字段 | 可从图片识别？ | 处理方式 |
+|------|---------------|----------|
+| `--title`（标题） | ✅ | **自动组合**：品牌+款式+颜色+尺码+成色，汇总确认 |
+| `--desc`（描述） | ✅ | **自动生成**：品牌+系列+款式+颜色+材质+货号+成色组合，不要标记为"需要补充" |
+| `--stuff-status`（成色） | ✅ | 自动判断，汇总确认 |
+| `--brand-name`（品牌） | ✅ | 识别后调 brands 搜索确认，**同时加入 itemAttrs**，汇总确认 |
+| `--category-id` / `--channel-cat-id` | ✅ | 自动推断，汇总确认 |
+| 季节属性 | ✅ | **自动推断**：夹克/风衣→春秋季，羽绒服→秋冬季，T恤/短裤→夏季，卫衣→春秋季等 |
+| `--size`（尺码） | ⚠️ | 有标签/吊牌则读取，无则汇总时问 |
+| `--goods-no`（货号） | ⚠️ | 有标签则读取，无则留空 |
+| 款式/颜色/材质属性 | ⚠️ | 能识别则自动匹配 propsValues，不能则汇总时问 |
+| `--price`（售价） | ❌ | **必须问用户** |
+| `--out-item-no`（商家编码） | ❌ | **必须问用户** |
+| `--shop-id`（店铺） | ❌ | 只有一个店铺时自动选，多个则问 |
+
+**成色判断映射**：
+
+| 图片中商品状态 | `--stuff-status` 值 |
+|----------------|---------------------|
+| 带吊牌/未拆封 | `100`（全新） |
+| 几乎无使用痕迹 | `-1`（准新）或 `99`（99新） |
+| 轻微使用痕迹 | `95`（95新） |
+| 明显使用痕迹 | `90`（9新） |
+
+**季节推断映射**：
+
+| 商品类型 | 适用季节 |
+|----------|----------|
+| 夹克、风衣、卫衣、针织衫 | 春秋季 |
+| 羽绒服、棉衣、毛呢大衣 | 秋冬季 |
+| T恤、短裤、背心、凉鞋 | 夏季 |
+| 基础款衬衫、休闲裤 | 四季 |
+
+**如果用户没提供价格和商家编码，此时询问**（不要留到最后）。
+
+---
+
+## 第 2 步：自动匹配类目 + 属性
+
+**获取类目 → 自动匹配**：
+
+```bash
+r2-cli goods hang-up categories --json
+```
+
+Agent 根据图片识别结果自动匹配类目（不需要用户从列表中选）。只在识别不确定时才展示列表。
+
+**获取属性 → 自动匹配**：
+
+```bash
+r2-cli goods hang-up props --channel-cat-id <channelCatId> --json
+```
+
+Agent 遍历所有属性，尽量自动匹配：
+
+| 属性 | 处理方式 |
+|------|----------|
+| 图片可识别的（款式/成色/颜色/材质等） | 自动匹配 `propsValues` 中的对应值 |
+| 品牌 | 用识别结果调 `brands` 搜索，自动选取精确匹配 |
+| 图片无法识别的（季节/裙长等） | 留空，汇总时让用户补充 |
+
+> **props API 说明**：`props` 返回所有属性及其 `propsValues`（非品牌属性可直接从这里选值）；品牌属性需额外调用 `brands` 搜索。
+
+**品牌精确匹配规则**：brands 搜索结果中必须选**完全匹配**的官方名称（如搜 Nike → 只选 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等）
+
+```bash
+r2-cli goods hang-up brands --channel-cat-id <id> --prop-id <品牌propId> --key "Nike" --json
+```
+
+最终构建 `--item-attrs`（**注意 propId 和 valueId 是不同字段**）：
+
+**⚠️ 品牌必须同时出现在 itemAttrs 和 --brand-name 中**。只传 `--brand-name` 不会把品牌写入商品属性，品牌必须作为 itemAttrs 的一项传入（含 channelCatId、propId、valueId、valueName）。
+
+```json
+[
+  { "channelCatId": "xxx", "propId": "83b8f62c...", "valueId": "68af4e8f...", "valueName": "Nike/耐克" },
+  { "channelCatId": "xxx", "propId": "1d6d7611...", "valueId": "af8266ea...", "valueName": "吊带" },
+  { "channelCatId": "xxx", "propId": "3b9f06b2...", "valueId": "d114e6ab...", "valueName": "全新" }
+]
+```
+
+---
+
+## 第 3 步：汇总展示 → 补充缺失 → 提交
+
+Agent 将所有自动填充和识别结果汇总展示给用户，**一次确认**：
+
+```
+商品信息（自动识别 + 需要你补充）：
+✅ 标题：Nike 低帮运动鞋 白色 42码 全新（自动生成）
+✅ 品牌：Nike/耐克（图片识别）
+✅ 类目：男士鞋靴 → 低帮鞋（自动匹配）
+✅ 成色：全新（图片识别）
+✅ 描述：Nike 低帮运动鞋...（自动生成）
+✅ 款式：运动鞋（图片识别）
+✅ 鞋码：42（图片识别）
+❓ 季节：？（无法识别，请选择：春季/夏季/秋季/冬季/四季）
+💰 价格：？（必填）
+📋 商家编码：？（必填）
+```
+
+**处理顺序**：
+1. 展示汇总信息
+2. 让用户补充缺失字段（价格、商家编码、无法识别的属性）
+3. 用户确认后直接提交
+
+**所有参数就绪后直接提交，不需要用户确认**：
+
+```bash
+r2-cli goods hang-up submit \
+  --shop-id <shopId> \
+  --title "商品标题" \
+  --price 599 \
+  --category-id <catId> \
+  --channel-cat-id <channelCatId> \
+  --image-ids "id1,id2" \
+  --stuff-status 95 \
+  --desc "商品描述（自动生成，包含品牌/款式/颜色/材质/货号）" \
+  --out-item-no "商家编码" \
+  --brand-name "Nike/耐克" \
+  --size "42" \
+  --item-attrs '[{"channelCatId":"xxx","propId":"83b8f62c...","valueId":"品牌valueId","valueName":"Nike/耐克"},{"channelCatId":"xxx","propId":"3b9f06b2...","valueId":"d114e6ab...","valueName":"全新"},{"channelCatId":"xxx","propId":"6562df9f...","valueId":"尺码valueId","valueName":"42"}]' \
+  --json
+```
+
+成功返回：
+
+```json
+{ "success": true, "data": "上架成功" }
+```
+
+**提交后展示上架结果摘要**（让用户知道上架了什么）：
+
+```
+上架成功！
+- 标题：Nike 低帮运动鞋 白色 42码
+- 价格：¥99999
+- 品牌：Nike/耐克
+- 类目：男士鞋靴 → 低帮鞋
+- 成色：全新
+- 店铺：xxx
+```
+
+---
+
+## 必填字段处理
+
+缺少时**在流程中尽早询问用户**，不要等所有信息都收集完再问：
+
+| 缺失字段 | 何时询问 | 询问方式 |
+|----------|----------|----------|
+| `--price`（售价） | 上传图片时 | "这个商品上架价格是多少？" |
+| `--out-item-no`（商家编码） | 上传图片时 | "商家编码是什么？（同店铺唯一标识）" |
+| `--shop-id`（店铺） | 流程开始时 | 展示店铺列表让用户选择 |
+| `--title`（标题） | 图片识别无法生成时 | "商品标题用什么？" |
+| `--desc`（描述） | 图片识别无法生成时 | "商品描述？" |
+
+## 必填参数
+
+| 参数 | 说明 |
+|------|------|
+| `--shop-id <id>` | 店铺 ID（即闲鱼用户名 account） |
+| `--title <title>` | 商品标题 |
+| `--price <amount>` | 售价 |
+| `--category-id <id>` | 大分类 ID（从 categories 获取） |
+| `--channel-cat-id <id>` | 小分类 ID（从 categories 获取） |
+| `--image-ids <ids>` | 图片 ID 列表，逗号分隔（保持字符串） |
+| `--stuff-status <n>` | 成色等级 |
+| `--desc <desc>` | 商品描述 |
+| `--out-item-no <no>` | 商家编码（同店铺唯一，用户自定义） |
+
+## 成色等级
+
+| 值 | 含义 |
+|----|------|
+| `100` | 全新 |
+| `-1` | 准新 |
+| `99` | 99新 |
+| `95` | 95新 |
+| `90` | 9新 |
+
+## 可选参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--brand-name <name>` | — | 品牌名称 |
+| `--size <size>` | — | 尺码 |
+| `--goods-no <no>` | — | 货号 |
+| `--original-price <amount>` | — | 原价 |
+| `--trade-type <n>` | `0` | 交易方式：0 仅在线 / 1 仅线下 / 2 线上或线下 |
+| `--transport-fee <amount>` | `0` | 运费（0 = 包邮） |
+| `--division-id <id>` | `330100` | 行政区划 ID（市级，默认杭州） |
+| `--item-attrs <json>` | — | 商品属性列表 JSON（来自 props/brands） |
+| `--yhb` | `false` | 是否开启验货宝 |
+
+> 内部默认值：`itemBizType=2`（普通商品）、`spBizType="16"`（奢品）
+
+## 售后服务（默认关闭）
+
+提交时自动附带售后服务配置，**默认全部关闭**。卖家需在闲鱼 APP 开通后才能开启（我的 → 设置 → 卖家服务 → 保障服务），未开通的服务如果传 `true` 会导致提交失败（错误：`ITEM_CONDITION_NOT_SUPPORT_SIGN`）。
+
+| 服务 | 默认值 | 说明 |
+|------|--------|------|
+| 极速发货-24小时 | 关闭 | 24小时内发货 |
+| 描述不符包邮退 | 关闭 | 描述不符退货包邮 |
+| 七天无理由退货 | 关闭 | 支持七天无理由 |
+| 极速发货-10分钟 | 关闭 | 10分钟内响应 |
+| 极速发货-48小时 | 关闭 | 48小时内发货 |
+| 正品保障 | 关闭 | 正品保障服务 |
+| 虚拟-描述不符包退 | 关闭 | 虚拟商品描述不符包退 |
+
+## 挂售错误处理
+
+| 错误信息 | 原因 | 解决方法 |
+|----------|------|----------|
+| `请提供至少一张图片` | upload-images 无图片 | 提供本地图片路径 |
+| `请填写有效的商品叶子类目` | category-id 或 channel-cat-id 错误 | 重新查询 categories |
+| `找不到传入的某些图片` | 图片 ID 无效或过期 | 重新上传图片 |
+| `商家编码重复` | out-item-no 同店铺已存在 | 更换唯一编码 |
+| `ITEM_CONDITION_NOT_SUPPORT_SIGN` | 售后服务未开通或品类不支持 | 默认关闭售后，或在闲鱼 APP 开通对应服务 |
+
+## References
+
+- [r2-goods SKILL.md](../SKILL.md) — 商品管理概览和路由决策
+- [r2-shared](../../r2-shared/SKILL.md) — 认证和全局规则

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

@@ -0,0 +1,137 @@
+# R2-Goods 普通上架/下架/改价
+
+> **Prerequisite:** 读取 [`../SKILL.md`](../SKILL.md) 了解路由决策和命令概览。
+
+## Agent 上架 4 步流程
+
+**每一步 Agent 获取数据后，必须展示给用户让用户做选择。**
+
+1. `r2-cli goods shops --json` → 展示店铺 → 用户选择 `shopId`
+2. `r2-cli goods stocks --json` → 展示仓库 → 用户选择 `stockId`
+3. `r2-cli goods list --stock-id <stockId> --json` → 展示商品 → 用户选择 `stockGoodsId`
+4. `r2-cli goods up --stock-goods-id <id> --shop-id <id> --price <amount> --json` → 提交上架
+
+命令自动轮询上架进度（每 2 秒，最多 10 秒），返回：
+
+```json
+{
+  "success": true,
+  "data": {
+    "submit": { "...提交结果..." },
+    "listing": { "id": "上架记录ID", "status": "up", "goodsName": "...", "price": 299 }
+  }
+}
+```
+
+状态值：`init`（处理中）、`up`（已上架）、`down`（已下架）、`fail`（失败，查看 `errorMsg`）
+
+## 上架参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--stock-goods-id <id>` | 是 | 库存商品 ID（来自 `stockGoodsId`） |
+| `--shop-id <id>` | 是 | 第三方店铺 ID（来自 `shopId`，**不是 `id`**） |
+| `--price <amount>` | 是 | 上架价格 |
+| `--json` | 否 | JSON 输出（Agent 推荐） |
+
+> 缺少必填参数时返回 `{ "success": false, "error": "Agent 模式需要 --stock-goods-id, --shop-id, --price" }`，不会进入交互模式。
+
+## 下架（down）
+
+**Agent 必须先向用户确认后再执行下架。**
+
+```bash
+# 方式 1：上架记录 ID
+r2-cli goods down --id <goodsListingId> --json
+
+# 方式 2：库存商品 ID + 店铺 ID
+r2-cli goods down --stock-goods-id <id> --shop-id <id> --json
+```
+
+## 改价（price）
+
+**Agent 必须先询问用户新价格，不能自行决定。**
+
+```bash
+# 方式 1：上架记录 ID
+r2-cli goods price --id <goodsListingId> --price <新价格> --json
+
+# 方式 2：库存商品 ID + 店铺 ID
+r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --json
+```
+
+## 修改商品信息（edit）
+
+修改已上架商品的标题、描述、品牌、类目、图片、属性等。
+
+### 定位商品（二选一）
+
+| 方式 | 参数 | 推荐度 |
+|------|------|--------|
+| 上架记录 ID | `--id <goodsListingId>` | 推荐，从 listing 的 id 字段取 |
+| 库存商品 + 店铺 | `--stock-goods-id <id> --account <shopId>` | 备选，挂售商品 stockGoodsId 可能为 0 |
+
+### 必填参数
+
+| 参数 | 说明 |
+|------|------|
+| `--id <id>` 或 `--stock-goods-id + --account` | 定位商品（二选一） |
+| `--category-id <id>` | 大分类 ID（**后端必填**，即使不改类目也要传当前值） |
+| `--channel-cat-id <id>` | 小分类 ID（**后端必填**，即使不改类目也要传当前值） |
+
+> 后端复用了挂售 DTO，缺少 `category-id` 会报 `getCategoryId() is null` 错误。
+
+### 可修改字段（全部可选）
+
+| 参数 | 说明 |
+|------|------|
+| `--title <title>` | 商品标题 |
+| `--desc <desc>` | 商品描述 |
+| `--image-ids <ids>` | 图片 ID（逗号分隔，需先上传） |
+| `--item-attrs <json>` | 属性列表 JSON |
+| `--brand-name <name>` | 品牌名称 |
+| `--stuff-status <n>` | 成色：100=全新 -1=准新 99=99新 95=95新 90=9新 |
+| `--goods-no <no>` | 货号 |
+| `--original-price <n>` | 原价（元） |
+| `--size <size>` | 尺码 |
+
+### 带图片修改的全自动流程
+
+用户提供了图片文件时，**Agent 自动完成所有步骤，用户只需确认**：
+
+1. **展示列表**：`r2-cli goods listing --json` → 展示给用户选择要修改的商品（获取 stockGoodsId、shopId）
+2. **上传图片**：`r2-cli goods hang-up upload-images --shop-id <shopId> --files <paths> --json`
+3. **AI 读图识别**：Agent 用 Read 工具查看图片，识别品牌/类目/成色/描述/材质等
+4. **自动匹配类目**：`r2-cli goods hang-up categories --json` → 根据识别结果匹配 catId + channelCatId（如"运动夹克" → 男士服装>夹克）
+5. **自动查询属性**：`r2-cli goods hang-up props --channel-cat-id <id> --json` → 根据识别结果自动匹配：
+   - 成色（全新/99新/95新等） → 查找对应 valueId
+   - 尺码（XL/L/M 等） → 查找对应 valueId
+   - 适用季节 → 查找对应 valueId
+   - 其他属性 → 根据识别结果匹配
+6. **自动搜索品牌**：`r2-cli goods hang-up brands --channel-cat-id <> --prop-id <> --key <品牌名> --json` → 获取品牌 valueId
+7. **汇总确认**：展示「当前值 vs 变更值」对比表，用户确认
+8. **提交修改**：
+
+```bash
+r2-cli goods edit \
+  --id <goodsListingId> \
+  --category-id <catId> --channel-cat-id <channelCatId> \
+  --image-ids "id1,id2,id3" \
+  --item-attrs '[{...品牌...},{...成色...},{...尺码...},{...季节...}]' \
+  --brand-name "Louis Vuitton/路易威登" \
+  --json
+```
+
+### 只改文字字段（无图片）
+
+```bash
+# 改标题
+r2-cli goods goods edit --id 5 \
+  --category-id 50106003 --channel-cat-id "f4718bbb04d7ed1facde29f76907b07f" \
+  --title "新标题" --json
+
+# 改品牌+描述
+r2-cli goods edit --id 5 \
+  --category-id 50106003 --channel-cat-id "f4718bbb04d7ed1facde29f76907b07f" \
+  --brand-name "Nike" --desc "全新描述" --json
+```

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

@@ -0,0 +1,63 @@
+# R2-Goods 查询命令
+
+> **Prerequisite:** 读取 [`../SKILL.md`](../SKILL.md) 了解路由决策和命令概览。
+
+## 店铺（shops）
+
+```bash
+r2-cli goods shops --json
+```
+
+返回字段：
+
+| 字段 | 说明 |
+|------|------|
+| `shopId` | 第三方店铺 ID（**上架参数取这个，不是 `id`**） |
+| `shopName` | 店铺名称 |
+| `platform` | 平台（xianyu / douyin 等） |
+
+> `--json` 输出会自动过滤敏感字段（`accessToken`、`refreshExpireIn`），Agent 可直接展示。
+
+## 仓库（stocks）
+
+```bash
+r2-cli goods stocks --json
+```
+
+返回字段：`stockId`（仓库 ID）、`stockName`（仓库名称）
+
+## 选品商品（list）
+
+```bash
+# 按仓库过滤（推荐）
+r2-cli goods list --stock-id <stockId> --json
+
+# 按商品 ID 精确查询
+r2-cli goods list --stock-goods-id <id> --json
+
+# 翻页
+r2-cli goods list --stock-id <stockId> --page 2 --size 20 --json
+```
+
+返回字段：
+
+| 字段 | 说明 |
+|------|------|
+| `stockGoodsId` | 库存商品 ID（**上架参数取这个**） |
+| `goodsName` | 商品名称 |
+| `brand` | 品牌 |
+| `size` | 尺码 |
+| `salePrice` | 建议售价 |
+| `cate1Name` / `cate2Name` / `cate3Name` | 分类 |
+
+## 上架列表（listing）
+
+```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              # 精确查询
+```
+
+过滤参数：`--id`、`--stock-goods-id`、`--shop-id`、`--stock-id`、`--status`（init/up/down/fail）、`--platform`

package/skills/r2-shared/SKILL.md

@@ -1,25 +1,42 @@
 ---
 name: r2-shared
-version: 1.0.0
-description: "R2-CLI 共享基础技能。安装、统一错误格式、命令概览。r2-auth 和 r2-goods 的前置依赖。触发词：r2-cli、安装、install、错误格式。"
+version: 1.1.0
+description: "R2-CLI 共享基础技能。安装、版本检查、统一错误格式、命令概览。r2-auth 和 r2-goods 的前置依赖。触发词：r2-cli、安装、install、错误格式。"
 metadata:
   requires:
     bins: ["r2-cli"]
   cliHelp: "r2-cli --help"
+  minVersion: "1.0.12"
   related:
     - "r2-auth"
     - "r2-goods"
+  supersededSkills:
+    - name: "r2-cli"
+      action: "已更名为 r2-shared，请删除旧 skill：rm -rf ~/.agents/skills/r2-cli"
 ---
 
-# R2-Shared (v1)
+# R2-Shared (v1.1)
 
-> **Tip**: 始终使用 `--json` 获取结构化输出。所有 `--json` 命令统一错误格式 `{ success: false, error: "..." }`，检查 `success` 判断成败。
+> **Tip**: 始终使用 `--json` 获取结构化输出。所有 `--json` 命令统一错误格式 `{ success: false, error: "..." [, status: number] }`，检查 `success` 判断成败。`status` 字段在 HTTP 错误（ApiError）和参数校验失败（400）时包含。
 > **Tip**: Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。
 
 二手潮奢交易命令行工具，由 Round2AI 团队维护。覆盖商品上架、认证登录等核心业务域。
 
 ## CRITICAL
 
+**执行规则**（所有 r2-* skills 通用）：
+- 所有命令**必须**通过已安装的 `r2-cli` 二进制执行（`r2-cli goods ...`、`r2-cli auth ...`）
+- **禁止**读取项目源码或用 `tsx`/`node` 直接运行源文件
+- 如果 `r2-cli` 命令不可用，提示用户先安装：`npm install -g @round2ai/r2-cli@latest`
+
+**版本检查**：
+- 首次使用时，Agent 应运行 `r2-cli --version` 检查当前版本
+- 最低要求版本：`1.0.12`，低于此版本提示用户更新：`npm install -g @round2ai/r2-cli@latest`
+
+**旧 Skill 清理**：
+- 如果发现 `~/.agents/skills/r2-cli/`（已废弃的旧名称），提示用户删除：`rm -rf ~/.agents/skills/r2-cli`
+- 当前正确的 skill 名称：`r2-shared`、`r2-auth`、`r2-goods`
+
 本 skill 是 r2-auth 和 r2-goods 的共享基础。认证登录详情见 **r2-auth** skill，商品管理详情见 **r2-goods** skill。
 
 ## 安装
@@ -53,29 +70,29 @@ npm install -g @round2ai/r2-cli@latest
 | 上架 | `r2-cli goods up --stock-goods-id <> --shop-id <> --price <> --json` | 普通上架（选品商品） |
 | | `r2-cli goods down --id <id> [--json]` | 下架商品 |
 | | `r2-cli goods price --id <id> --price <amount> [--json]` | 修改价格 |
+| 修改 | `r2-cli goods edit --id <> --category-id <> --channel-cat-id <> ... --json` | 修改商品信息（定位推荐 `--id`） |
 | 挂售 | `r2-cli goods hang-up categories [--json]` | 获取闲鱼类目 |
 | | `r2-cli goods hang-up props --channel-cat-id <id> [--json]` | 获取属性列表 |
 | | `r2-cli goods hang-up brands --channel-cat-id <> --prop-id <> --key <> [--json]` | 品牌搜索 |
 | | `r2-cli goods hang-up upload-images --shop-id <> --files <> --json` | 上传图片 |
 | | `r2-cli goods hang-up submit --shop-id <> --title <> ... --json` | 提交挂售上架 |
 
-## Agent 上架路由（概要）
-
-用户说"上架商品"时需要选择正确的方式：
-- **商品在选品库** → `goods up`（店铺 → 仓库 → 选品商品 → 提交价格）
-- **用户提供了图片** → `goods hang-up`（上传图片 → AI 读图识别 → 类目/属性 → 提交）
-- **不确定** → 问用户
+## 其他命令
 
-> 详细决策规则见 **r2-goods** skill「上架路由决策」章节。
+| 命令 | 说明 |
+|------|------|
+| `r2-cli update` | 一键更新 CLI 和技能 |
+| `r2-cli uninstall` | 卸载并清除配置 |
 
-## Agent 上架 4 步流程（概要）
+## Agent 上架路由（概要）
 
-1. `r2-cli goods shops --json` → 展示店铺 → 用户选择
-2. `r2-cli goods stocks --json` → 展示仓库 → 用户选择
-3. `r2-cli goods list --stock-id <id> --json` → 展示商品 → 用户选择
-4. `r2-cli goods up --stock-goods-id <id> --shop-id <id> --price <amount> --json` → 提交上架
+用户说"上架"时需要选择正确的方式：
+- **用户明确指定方式或提供了图片** → 直接走对应流程
+- **未指定方式** → **必须询问用户**："选品上架还是挂售上架？"
+  - 选品上架 → `goods up`（店铺 → 仓库 → 选品商品 → 提交价格）
+  - 挂售上架 → `goods hang-up`（上传图片 → AI 读图识别 → 类目/属性 → 提交）
 
-> 完整参数说明、挂售流程、错误处理见 **r2-goods** skill。
+> 详细决策规则和完整操作流程见 **r2-goods** skill。
 
 ## 统一错误格式
 
@@ -85,6 +102,12 @@ npm install -g @round2ai/r2-cli@latest
 { "success": false, "error": "错误信息" }
 ```
 
+API 错误和参数校验失败时额外包含 `status` 字段：
+
+```json
+{ "success": false, "error": "错误信息", "status": 400 }
+```
+
 常见错误：
 
 | 错误信息 | 原因 | 解决方法 |