@round2ai/r2-cli 1.0.15 → 1.0.17

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

@@ -9,9 +9,20 @@
 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` → 提交上架
+4. `r2-cli goods xianyu up --stock-goods-id <id> --shop-id <id> --price <amount> --json` → 提交上架
 
-命令自动轮询上架进度（每 2 秒，最多 10 秒），返回：
+> **提交前提醒用户**：运费默认包邮（`--transport-fee 0`），如需收运费请提供金额。可选开启验货宝（`--yhb`），但价格须在品类验货宝价格区间内。
+
+命令自动轮询上架进度（每 2 秒，最多 10 秒），返回 `{ success, data: { submit, listing } }`。
+
+**提交成功展示模板**：
+```
+上架成功！
+- 商品：[goodsName]
+- 店铺：[shopName]
+- 价格：¥[price]
+- 上架 ID：[listing.id]（用于后续改价/下架）
+```
 
 ```json
 {
@@ -42,6 +53,30 @@
 | `platform` | 平台（xianyu） |
 | `gmtCreate` / `gmtModified` | 创建/修改时间戳 |
 
+### 友好输出指引
+
+上架响应 JSON 示例：
+```json
+{
+  "success": true,
+  "data": {
+    "submit": { "id": 12345, "status": "init" },
+    "listing": { "id": 12345, "goodsName": "Nike 运动鞋", "price": 299, "shopName": "店铺A", "status": "up" }
+  }
+}
+```
+
+Agent 提取展示：
+```
+上架成功！
+- 商品：Nike 运动鞋
+- 店铺：店铺A
+- 价格：¥299
+- 上架 ID：12345（用于后续改价/下架）
+```
+
+> **`data.listing` 中的字段**：`id`（上架记录 ID）、`goodsName`（商品名）、`price`（价格）、`shopName`（店铺名）、`status`（状态）。Agent 提取这些字段展示给用户。
+
 ## 上架参数
 
 | 参数 | 必填 | 说明 |
@@ -49,49 +84,87 @@
 | `--stock-goods-id <id>` | 是 | 库存商品 ID（来自 `stockGoodsId`） |
 | `--shop-id <id>` | 是 | 第三方店铺 ID（来自 `shopId`，**不是 `id`**） |
 | `--price <amount>` | 是 | 上架价格 |
+| `--yhb` | 否 | 开启验货宝（价格区间因品类而异） |
+| `--transport-fee <amount>` | 否 | 运费（元，默认 0 = 包邮） |
 | `--json` | 否 | JSON 输出（Agent 推荐） |
 
+> **验货宝约束**：开启 `--yhb` 时，价格须在该品类的验货宝价格区间内（不同品类区间不同，如 100~20,000、1,000~50,000 等）。超出区间会返回 `YHB_PRICE_NOT_SUPPORT` 错误，错误信息中包含具体的价格范围。Agent 应在上架失败时根据错误信息提示用户调整价格或关闭验货宝。
+
 > 缺少必填参数时返回 `{ "success": false, "error": "Agent 模式需要 --stock-goods-id, --shop-id, --price" }`，不会进入交互模式。
 
 ## 下架（down）
 
 **Agent 必须先向用户确认后再执行下架。**
 
+**确认模板**：
+```
+确认下架？
+商品：[goodsName] | [brandName] | ¥[price]
+店铺：[shopName]
+输入 yes 确认，其他取消
+```
+
 ```bash
 # 方式 1：上架记录 ID
-r2-cli goods down --id <goodsListingId> --json
+r2-cli goods xianyu down --id <goodsListingId> --json
 
 # 方式 2：库存商品 ID + 店铺 ID
-r2-cli goods down --stock-goods-id <id> --shop-id <id> --json
+r2-cli goods xianyu down --stock-goods-id <id> --shop-id <id> --json
+```
+
+### 友好输出指引
+
+下架响应 `{ "success": true, "data": "下架成功" }`。Agent 提取展示：
+```
+下架成功！
+- 商品：[goodsName]
+- 店铺：[shopName]
+- 上架 ID：[id]
 ```
 
 ## 改价（price）
 
 **Agent 必须先询问用户新价格，不能自行决定。**
 
+> **提交前提醒用户**：可同时修改运费（`--transport-fee`，默认 0 包邮）。
+
 ```bash
 # 方式 1：上架记录 ID
-r2-cli goods price --id <goodsListingId> --price <新价格> --json
+r2-cli goods xianyu price --id <goodsListingId> --price <新价格> --json
 
 # 方式 2：库存商品 ID + 店铺 ID
-r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --json
+r2-cli goods xianyu price --stock-goods-id <id> --shop-id <id> --price <新价格> --json
+
+# 同时修改运费
+r2-cli goods xianyu price --id <goodsListingId> --price <新价格> --transport-fee <运费> --json
+```
+
+### 友好输出指引
+
+改价响应 `{ "success": true, "data": "修改成功" }`。Agent 提取展示：
+```
+改价成功！
+- 商品：[goodsName]
+- 原价：¥[原价] → ¥[新价格]
 ```
 
 ## 修改商品信息（edit）
 
 修改已上架商品的标题、描述、品牌、类目、图片、属性等。
 
-> **注意**：`goods edit` 不支持修改价格。改价需单独使用 `r2-cli goods price --id <id> --price <amount>`。
+> **注意**：`goods xianyu edit` 不支持修改价格。改价需单独使用 `r2-cli goods xianyu price --id <id> --price <amount>`。
 
-### 定位商品（二选一）
+### 定位商品（三选一）
 
 | 方式 | 参数 | 推荐度 |
 |------|------|--------|
 | 上架记录 ID | `--id <goodsListingId>` | 推荐，从 listing 的 id 字段取 |
 | 库存商品 + 店铺 | `--stock-goods-id <id> --account <shopId>` | 备选，挂售商品 stockGoodsId 可能为 0 |
+| 商家编码 | `--outer-id <outItemNo>` | 通过商家编码匹配商品 |
 
 ### Agent 注意事项
 
+- **提交前提醒用户**：可同时修改运费（`--transport-fee`，默认 0 包邮）和验货宝（`--yhb`）
 - **`--image-ids` 保持字符串**：图片 ID 是 19 位数字，`Number()` 会精度丢失
 - **`--item-attrs` 传 JSON 字符串**：必须是 `JSON.stringify()` 后的结果，不能直接传对象
 - **即使不改类目也要传 `--category-id` 和 `--channel-cat-id`**：后端必填，缺少会报 `getCategoryId() is null`
@@ -101,7 +174,7 @@ r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --js
 
 | 参数 | 说明 |
 |------|------|
-| `--id <id>` 或 `--stock-goods-id + --account` | 定位商品（二选一） |
+| `--id <id>` 或 `--stock-goods-id + --account` 或 `--outer-id` | 定位商品（三选一） |
 | `--category-id <id>` | 大分类 ID（**后端必填**，即使不改类目也要传当前值） |
 | `--channel-cat-id <id>` | 小分类 ID（**后端必填**，即使不改类目也要传当前值） |
 
@@ -120,33 +193,12 @@ r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --js
 | `--goods-no <no>` | 货号 |
 | `--original-price <n>` | 原价（元） |
 | `--size <size>` | 尺码 |
+| `--yhb` | 是否开启验货宝 |
+| `--transport-fee <amount>` | 运费（元，默认 0 = 包邮） |
 
-### 带图片修改的全自动流程
-
-用户提供了图片文件时，**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
-```
+用户提供了图片文件时，参见场景指南：[../scenes/r2-scene-edit-with-images.md](../scenes/r2-scene-edit-with-images.md)
 
 ### 只改文字字段（无图片）
 
@@ -154,14 +206,31 @@ r2-cli goods edit \
 
 ```bash
 # 改标题
-r2-cli goods edit --id 5 \
+r2-cli goods xianyu edit --id 5 \
   --category-id 50106003 --channel-cat-id "f4718bbb04d7ed1facde29f76907b07f" \
   --title "新标题" --json
 
 # 改品牌+描述
-r2-cli goods edit --id 5 \
+r2-cli goods xianyu edit --id 5 \
   --category-id 50106003 --channel-cat-id "f4718bbb04d7ed1facde29f76907b07f" \
   --brand-name "Nike" --desc "全新描述" --json
 ```
 
 > **注意**：改品牌时建议同时传 `--item-attrs`（含所有属性，品牌项用最新 valueId），因为只传 `--brand-name` 可能不会更新属性列表中的品牌值。
+
+### 友好输出指引
+
+edit 响应 `{ "success": true, "data": "修改成功" }`。Agent 提取展示修改摘要：
+```
+修改成功！
+商品：[goodsName]
+┌──────────┬──────────────────┐
+│ 修改项    │ 新值              │
+├──────────┼──────────────────┤
+│ 标题      │ [新标题]           │
+│ 品牌      │ [新品牌]           │
+│ 描述      │ [新描述摘要]        │
+└──────────┴──────────────────┘
+```
+
+> 只展示**实际修改的字段**，未修改的字段不展示。`--item-attrs` 中如有多个属性修改，只列属性名+新值。

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

@@ -18,6 +18,14 @@ r2-cli goods shops --json
 
 > `--json` 输出会自动过滤敏感字段（`accessToken`、`refreshExpireIn`），Agent 可直接展示。
 
+**Agent 展示格式**：
+```
+店铺列表：
+1. [shopName]（[platform]）— shopId: [shopId]
+2. [shopName]（[platform]）— shopId: [shopId]
+请选择店铺（输入编号）：
+```
+
 ## 仓库（stocks）
 
 ```bash
@@ -26,6 +34,14 @@ r2-cli goods stocks --json
 
 返回字段：`stockId`（仓库 ID）、`stockName`（仓库名称）
 
+**Agent 展示格式**：
+```
+仓库列表：
+1. [stockName]（stockId: [stockId]）
+2. [stockName]（stockId: [stockId]）
+请选择仓库（输入编号）：
+```
+
 ## 选品商品（list）
 
 ```bash
@@ -50,16 +66,31 @@ r2-cli goods list --stock-id <stockId> --page 2 --size 50 --json
 | `salePrice` | 建议售价 |
 | `cate1Name` / `cate2Name` / `cate3Name` | 分类 |
 
+**Agent 展示格式**：
+```
+选品商品列表：
+1. [goodsName] | [brand] | [size] | ¥[salePrice] | [cate3Name]（stockGoodsId: [id]）
+2. [goodsName] | [brand] | [size] | ¥[salePrice] | [cate3Name]（stockGoodsId: [id]）
+请选择商品（输入编号）：
+```
+
 ## 上架列表（listing）
 
 ```bash
-r2-cli goods listing --json
-r2-cli goods listing --status up --json            # 只看已上架
-r2-cli goods listing --status sold --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              # 精确查询
-r2-cli goods listing --page 2 --size 50 --json     # 翻页
+r2-cli goods xianyu listing --json
+r2-cli goods xianyu listing --status up --json            # 只看已上架
+r2-cli goods xianyu listing --status sold --json          # 只看已售出
+r2-cli goods xianyu listing --shop-id <id> --json         # 按店铺过滤
+r2-cli goods xianyu listing --stock-goods-id <id> --json  # 按商品过滤
+r2-cli goods xianyu listing --id <id> --json              # 精确查询
+r2-cli goods xianyu listing --page 2 --size 50 --json     # 翻页
 ```
 
-过滤参数：`--id`、`--stock-goods-id`、`--shop-id`、`--stock-id`、`--status`（init/up/down/fail/sold）、`--platform`、`--page`（默认 1）、`--size`（默认 20，最大 50）
+过滤参数：`--id`、`--stock-goods-id`、`--shop-id`、`--stock-id`、`--status`（init/up/down/fail/sold）、`--page`（默认 1）、`--size`（默认 20，最大 50）
+
+**Agent 展示格式**：
+```
+上架商品列表：
+1. [goodsName] | [brandName] | ¥[price] | [status] | id: [id]
+2. [goodsName] | [brandName] | ¥[price] | [status] | id: [id]
+```

package/skills/r2-goods/scenes/r2-scene-batch-operations.md

@@ -0,0 +1,79 @@
+# 批量操作场景指南
+
+## 适用场景
+
+- 将同一商品上架到多个店铺
+- 查询全部上架商品
+- 批量下架/改价
+
+## 分页策略
+
+```bash
+# 获取全部上架商品（分页遍历）
+r2-cli goods xianyu listing --page 1 --size 50 --json
+r2-cli goods xianyu listing --page 2 --size 50 --json
+```
+
+- 建议使用 `--size 50`（最大值），减少请求次数
+- 用 `--status` 过滤特定状态的商品（up/down/sold）
+- 用 `--shop-id` 限定店铺范围
+
+## 跨店铺操作
+
+```bash
+# 查看所有店铺
+r2-cli goods shops --json
+
+# 切换到另一个店铺的库存
+r2-cli goods list --stock-id <stockId> --json
+
+# 上架到不同店铺
+r2-cli goods xianyu up --stock-goods-id <id> --shop-id <shopA> --price <n> --json
+r2-cli goods xianyu up --stock-goods-id <id> --shop-id <shopB> --price <n> --json
+```
+
+## 注意事项
+
+- 每个操作独立执行，一个失败不影响其他
+- 批量提交时间隔至少 1 秒
+- Token 过期时停止工作流，重新登录后从断点继续
+- **上架/改价前提醒用户**：运费默认包邮（`--transport-fee` 默认 0），如需收运费请提供金额；可选开启验货宝（`--yhb`）
+
+## 汇总展示格式
+
+操作完成后，按以下格式展示结果：
+
+```
+批量上架完成！
+✅ 成功：N 个商品
+  - [商品名] → ¥[价格] → [店铺名]
+  - [商品名] → ¥[价格] → [店铺名]
+❌ 失败：N 个商品
+  - [商品名] → 错误：[错误信息]
+  - [商品名] → 错误：[错误信息]
+```
+
+## 友好输出指引
+
+每个批量操作命令的 JSON 响应结构不同，Agent 统一按以下方式处理：
+
+**批量上架**：每个 `goods xianyu up --json` 返回 `{ success, data: { listing: { id, goodsName, price, shopName, status } } }`。逐个提取，累积汇总。
+
+**批量下架**：每个 `goods xianyu down --json` 返回 `{ success, data: "下架成功" }`。Agent 从流程参数中提取商品信息展示：
+```
+[1/2] Nike 运动鞋 → ✅ 已下架
+[2/2] Adidas T恤 → ✅ 已下架
+```
+
+**批量改价**：每个 `goods xianyu price --json` 返回 `{ success, data: "修改成功" }`。从流程参数中提取信息展示：
+```
+[1/3] Nike 运动鞋 → ¥299 → ¥249 ✅
+[2/3] Adidas T恤 → ¥199 → ¥149 ✅
+```
+
+> 即使某个操作失败（`success: false`），也不影响其他商品继续执行。每完成一个商品就反馈进度，全部完成后展示汇总。
+
+## 参考
+
+- [../SKILL.md](../SKILL.md) — 商品管理概览
+- [../references/r2-goods-query.md](../references/r2-goods-query.md) — 查询命令

package/skills/r2-goods/scenes/r2-scene-edit-with-images.md

@@ -0,0 +1,51 @@
+# 带图片修改商品信息
+
+用户提供了图片文件时，**Agent 自动完成所有步骤，用户只需确认**。
+
+## 全自动流程
+
+1. **展示列表**：`r2-cli goods xianyu listing --json` → 展示给用户选择要修改的商品
+2. **上传图片**：`r2-cli goods xianyu hang-up upload-images --shop-id <shopId> --files <paths> --json`
+3. **AI 读图识别**：Agent 用 Read 工具查看图片，识别品牌/类目/成色/描述/材质等
+4. **自动匹配类目**：`r2-cli goods xianyu hang-up categories --json` → 根据识别结果匹配 catId + channelCatId
+5. **自动查询属性**：`r2-cli goods xianyu hang-up props --channel-cat-id <id> --json` → 根据识别结果匹配成色/尺码/季节等
+6. **自动搜索品牌**：`r2-cli goods xianyu hang-up brands --channel-cat-id <> --prop-id <> --key <品牌名> --json`
+7. **汇总确认**：展示「当前值 vs 变更值」对比表，让用户确认
+
+   ```
+   ┌──────────┬──────────────────┬──────────────────┐
+   │ 字段      │ 当前值            │ 变更值            │
+   ├──────────┼──────────────────┼──────────────────┤
+   │ 标题      │ Nike 运动鞋 白 42  │ Nike 运动鞋 黑 42  │
+   │ 图片      │ img1.jpg          │ img1.jpg,img2.jpg │
+   │ 成色      │ 95新              │ 全新               │
+   │ 运费      │ 包邮               │ 包邮（可修改）      │
+   │ 验货宝    │ 未开启             │ 未开启（可开启）    │
+   │ 价格      │ ¥299（不改价）      │ —                 │
+   └──────────┴──────────────────┴──────────────────┘
+   ```
+
+   > 运费默认包邮（`--transport-fee` 默认 0），验货宝默认关闭（`--yhb`）。确认时提醒用户可修改。
+8. **提交**：
+
+```bash
+r2-cli goods xianyu edit \
+  --id <goodsListingId> \
+  --category-id <catId> --channel-cat-id <channelCatId> \
+  --image-ids "id1,id2,id3" \
+  --item-attrs '[{...品牌...},{...成色...},{...尺码...},{...季节...}]' \
+  --brand-name "品牌名" \
+  --json
+```
+
+## 约束
+
+- `--category-id` 和 `--channel-cat-id` 后端必填，即使不改类目也要传当前值
+- `--item-attrs` 必须包含 props 中所有属性，不只是修改的那一个
+- `--image-ids` 保持字符串，不要转数字
+- `--item-attrs` 传 JSON 字符串（`JSON.stringify()` 后）
+
+## 参考
+
+- [../references/r2-goods-listing.md](../references/r2-goods-listing.md) — edit 命令参数
+- [../references/r2-goods-hangup.md](../references/r2-goods-hangup.md) — 图片上传和属性查询

package/skills/r2-goods/scenes/r2-scene-hangup-fashion.md

@@ -0,0 +1,32 @@
+# 服装/鞋包挂售场景指南
+
+## 季节推断
+
+| 商品类型 | 适用季节 |
+|----------|----------|
+| 夹克、风衣、卫衣、针织衫 | 春秋季 |
+| 羽绒服、棉衣、毛呢大衣 | 秋冬季 |
+| T恤、短裤、背心、凉鞋 | 夏季 |
+| 基础款衬衫、休闲裤 | 四季 |
+
+## 图片识别字段
+
+| 字段 | 可识别性 | 说明 |
+|------|---------|------|
+| 品牌 | ✅ | 从 Logo/标签读取，调 brands 搜索确认 |
+| 款式 | ✅ | 从整体外观判断 |
+| 成色 | ✅ | 根据磨损/污渍/起球程度判断 |
+| 尺码 | ⚠️ | 从标签/吊牌/水洗标读取 |
+| 货号 | ⚠️ | 从标签/吊牌读取 |
+| 颜色/材质 | ⚠️ | 能识别则识别，否则汇总时问 |
+
+## 品牌搜索建议
+
+- 奢侈品（LV、Gucci、Chanel 等）：搜完整英文名
+- 运动品牌（Nike、Adidas 等）：搜英文名，小写即可
+- 国内品牌：搜中文名
+
+## 参考
+
+- [../SKILL.md](../SKILL.md) — 挂售流程
+- [../references/r2-goods-hangup.md](../references/r2-goods-hangup.md) — 挂售参数详解

package/skills/r2-shared/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: r2-shared
-version: 1.1.0
+version: 1.2.0
 description: "R2-CLI 共享基础技能。安装、版本检查、统一错误格式、命令概览。r2-auth 和 r2-goods 的前置依赖。触发词：r2-cli、安装、install、错误格式。"
 metadata:
   requires:
@@ -15,7 +15,7 @@ metadata:
       action: "已更名为 r2-shared，请删除旧 skill：rm -rf ~/.agents/skills/r2-cli"
 ---
 
-# R2-Shared (v1.1)
+# R2-Shared (v1.2)
 
 > **Tip**: 始终使用 `--json` 获取结构化输出。所有 `--json` 命令统一错误格式 `{ success: false, error: "..." [, status: number] }`，检查 `success` 判断成败。`status` 字段在 HTTP 错误（ApiError）和参数校验失败（400）时包含。
 > **Tip**: Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。
@@ -30,10 +30,42 @@ metadata:
 - 如果 `r2-cli` 命令不可用，提示用户先安装：`npm install -g @round2ai/r2-cli@latest`
 - **不要在命令末尾加 `&`**：如果用 Bash 工具的 `run_in_background: true`，不要额外加 `&`，否则 shell 立即返回导致输出丢失
 
+**命令路径（重要）**：
+- Agent **必须使用新路径**：`goods xianyu up/down/price/edit/listing/hang-up` 和 `goods taobao ...`
+- 旧路径（`goods up`、`goods down` 等）仍可执行但已标记 `[已废弃]`，Agent 不要使用旧路径
+- 跨平台命令（`goods shops`、`goods stocks`、`goods list`）保持不变，无平台前缀
+
 **版本检查**：
 - 首次使用时，Agent 应运行 `r2-cli --version` 检查当前版本
 - 最低要求版本：`1.0.12`，低于此版本提示用户更新：`npm install -g @round2ai/r2-cli@latest`
 
+**更新通知（`_notice.update`）**：
+`_notice.update` 会出现在所有 `--json` 命令的输出中（包含成功和失败输出），格式如下：
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "_notice": {
+    "update": {
+      "message": "Update available: 1.0.15 → 1.0.16",
+      "command": "npm update -g @round2ai/r2-cli && npx skills add Round2AI/r2-cli --all -y"
+    }
+  }
+}
+```
+
+**当你在输出中看到 `_notice.update` 时，完成用户当前请求后，主动提议帮用户更新**：
+
+1. 告知用户当前版本和最新版本号
+2. 提议执行更新（CLI 和 Skills 需要同时更新）：
+   ```bash
+   npm update -g @round2ai/r2-cli && npx skills add Round2AI/r2-cli --all -y
+   ```
+3. 更新完成后提醒用户：**退出并重新打开 AI Agent** 以加载最新 Skills
+
+**规则**：不要静默忽略更新提示。即使当前任务与更新无关，也应在完成用户请求后补充告知。
+
 **旧 Skill 清理**：
 - 如果发现 `~/.agents/skills/r2-cli/`（已废弃的旧名称），提示用户删除：`rm -rf ~/.agents/skills/r2-cli`
 - 当前正确的 skill 名称：`r2-shared`、`r2-auth`、`r2-goods`
@@ -51,32 +83,13 @@ npm install -g @round2ai/r2-cli@latest
 - 先登录：`r2-cli auth login`（支持第二回合 APP / 微信 / 支付宝扫码）
 - 检查状态：`r2-cli auth status`
 
-## 认证命令（详见 r2-auth skill）
+## 认证命令
 
-| 命令 | 说明 |
-|------|------|
-| `r2-cli auth login --json` | 扫码登录（Agent 推荐，一步完成） |
-| `r2-cli auth xianyu --json` | 闲鱼店铺授权（Agent 推荐，一步完成） |
-| `r2-cli auth status` | 查看登录状态 |
-| `r2-cli auth logout` | 退出登录 |
-
-## 商品管理命令（详见 r2-goods skill）
-
-| 分类 | 命令 | 说明 |
-|------|------|------|
-| 查询 | `r2-cli goods shops [--json]` | 查看已授权店铺 |
-| | `r2-cli goods stocks [--json]` | 查看仓库 |
-| | `r2-cli goods list [--stock-id <id>] [--json]` | 查看选品商品 |
-| | `r2-cli goods listing [--status <up/down/sold>] [--json]` | 查询上架列表 |
-| 上架 | `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` | 提交挂售上架 |
+认证登录和闲鱼店铺授权的完整流程与参数详见 **r2-auth** skill。
+
+## 商品管理命令
+
+商品上架、下架、改价、修改、挂售以及查询的完整流程与参数详见 **r2-goods** skill。
 
 ## 其他命令
 
@@ -85,15 +98,51 @@ npm install -g @round2ai/r2-cli@latest
 | `r2-cli update` | 一键更新 CLI 和技能 |
 | `r2-cli uninstall` | 卸载并清除配置 |
 
-## Agent 上架路由（概要）
+## 上架路由
+
+详见 **r2-goods** skill 的「上架路由决策」章节。
+
+## Network & Retry
+
+Agent 处理命令失败时的策略：
+
+- **网络错误**（`TypeError`、`fetch failed`）：最多自动重试 2 次，间隔 3 秒。连续失败则提示用户检查网络
+- **超时错误**（`timeout`）：重试 1 次。仍超时则建议检查网络或 SERVER_BASEURL 配置
+- **认证错误**（`请先运行 r2-cli auth login 登录`、`401`）：**不重试**，直接引导用户重新登录（见下方 Token Expiry Recovery）
+- **轮询超时**（`轮询超时`）：说明提交已接受但结果未回，建议稍后用 `goods xianyu listing` 查看
+
+## Token Expiry Recovery
+
+当命令返回认证错误时：
+
+1. **立即停止当前工作流**，不要继续执行其他命令
+2. 告知用户 Token 已过期，引导重新登录：`r2-cli auth login --json`
+3. 重新登录成功后，**从上次成功的步骤继续**（不要从头开始）
+
+## 友好输出原则
+
+Agent 执行 `--json` 命令后，**不要直接把原始 JSON 丢给用户**。应从 JSON 中提取关键字段，整理为易读格式：
+
+```
+❌ 错误：直接把 JSON 丢给用户
+{ "success": true, "data": [{ "shopId": "10086", "shopName": "xxx", "platform": "xianyu" }] }
+
+✅ 正确：提取关键字段，整理展示
+店铺列表：
+1. xxx（xianyu）— shopId: 10086
+```
+
+具体规则：
+- **查询结果**：用编号列表展示（参见各 reference 的"Agent 展示格式"模板），末尾提示用户选择
+- **操作结果**：提取关键字段（listing ID、价格、状态等），一行一个字段简洁展示
+- **错误信息**：直接展示 `error` 字段内容，不展示整个 JSON 结构
+- **确认提示**：展示商品关键信息（名称/价格/店铺）后，引导用户输入 yes/no
+
+始终遵守：**Agent 看 JSON，用户看友好文本。**
 
-用户说"上架"时需要选择正确的方式：
-- **用户明确指定方式或提供了图片** → 直接走对应流程
-- **未指定方式** → **必须询问用户**："选品上架还是挂售上架？"
-  - 选品上架 → `goods up`（店铺 → 仓库 → 选品商品 → 提交价格）
-  - 挂售上架 → `goods hang-up`（上传图片 → AI 读图识别 → 类目/属性 → 提交）
+## 分页建议
 
-> 详细决策规则和完整操作流程见 **r2-goods** skill。
+查询类命令（`goods list`、`goods xianyu listing`、`goods taobao listing`）建议使用 `--page 1 --size 50`。如果响应包含分页信息，继续翻页直到数据取完。在查询前提醒用户可以通过 `--status` 或 `--stock-id` 缩小范围提高效率。
 
 ## 统一错误格式
 
@@ -115,4 +164,4 @@ API 错误和参数校验失败时额外包含 `status` 字段：
 |----------|------|----------|
 | `请先运行 r2-cli auth login 登录` | 未登录或 Token 过期 | 执行 `r2-cli auth login --json` |
 | `二维码已过期` / `授权链接已过期` | 扫码超时（5 分钟） | 重新执行命令 |
-| `轮询超时` | 上架结果查询超时 | 稍后用 `r2-cli goods listing` 查看 |
+| `轮询超时` | 上架结果查询超时 | 稍后用 `r2-cli goods xianyu listing` 查看 |

package/skills/r2-shared/_meta.json

@@ -1,5 +1,5 @@
 {
   "ownerId": "round2ai",
-  "slug": "r2-cli",
-  "version": "0.1.0"
+  "slug": "r2-shared",
+  "version": "1.2.0"
 }