@round2ai/r2-cli 1.0.15 → 1.0.16

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

@@ -0,0 +1,78 @@
+# 批量操作场景指南
+
+## 适用场景
+
+- 将同一商品上架到多个店铺
+- 查询全部上架商品
+- 批量下架/改价
+
+## 分页策略
+
+```bash
+# 获取全部上架商品（分页遍历）
+r2-cli goods listing --page 1 --size 50 --json
+r2-cli goods 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 up --stock-goods-id <id> --shop-id <shopA> --price <n> --json
+r2-cli goods up --stock-goods-id <id> --shop-id <shopB> --price <n> --json
+```
+
+## 注意事项
+
+- 每个操作独立执行，一个失败不影响其他
+- 批量提交时间隔至少 1 秒
+- Token 过期时停止工作流，重新登录后从断点继续
+
+## 汇总展示格式
+
+操作完成后，按以下格式展示结果：
+
+```
+批量上架完成！
+✅ 成功：N 个商品
+  - [商品名] → ¥[价格] → [店铺名]
+  - [商品名] → ¥[价格] → [店铺名]
+❌ 失败：N 个商品
+  - [商品名] → 错误：[错误信息]
+  - [商品名] → 错误：[错误信息]
+```
+
+## 友好输出指引
+
+每个批量操作命令的 JSON 响应结构不同，Agent 统一按以下方式处理：
+
+**批量上架**：每个 `goods up --json` 返回 `{ success, data: { listing: { id, goodsName, price, shopName, status } } }`。逐个提取，累积汇总。
+
+**批量下架**：每个 `goods down --json` 返回 `{ success, data: "下架成功" }`。Agent 从流程参数中提取商品信息展示：
+```
+[1/2] Nike 运动鞋 → ✅ 已下架
+[2/2] Adidas T恤 → ✅ 已下架
+```
+
+**批量改价**：每个 `goods 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,47 @@
+# 带图片修改商品信息
+
+用户提供了图片文件时，**Agent 自动完成所有步骤，用户只需确认**。
+
+## 全自动流程
+
+1. **展示列表**：`r2-cli goods listing --json` → 展示给用户选择要修改的商品
+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` → 根据识别结果匹配成色/尺码/季节等
+6. **自动搜索品牌**：`r2-cli goods hang-up brands --channel-cat-id <> --prop-id <> --key <品牌名> --json`
+7. **汇总确认**：展示「当前值 vs 变更值」对比表，让用户确认
+
+   ```
+   ┌──────────┬──────────────────┬──────────────────┐
+   │ 字段      │ 当前值            │ 变更值            │
+   ├──────────┼──────────────────┼──────────────────┤
+   │ 标题      │ Nike 运动鞋 白 42  │ Nike 运动鞋 黑 42  │
+   │ 图片      │ img1.jpg          │ img1.jpg,img2.jpg │
+   │ 成色      │ 95新              │ 全新               │
+   │ 价格      │ ¥299（不改价）      │ —                 │
+   └──────────┴──────────────────┴──────────────────┘
+   ```
+8. **提交**：
+
+```bash
+r2-cli goods 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。
@@ -34,6 +34,33 @@ metadata:
 - 首次使用时，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 +78,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 +93,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 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 listing`）建议使用 `--page 1 --size 50`。如果响应包含分页信息，继续翻页直到数据取完。在查询前提醒用户可以通过 `--status` 或 `--stock-id` 缩小范围提高效率。
 
 ## 统一错误格式
 

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"
 }

package/skills/r2-workflow-batch-up/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: r2-workflow-batch-up
+version: 1.0.0
+description: "批量上架工作流。将选品库中多个商品批量上架到闲鱼，支持同商品多店铺上架。触发词：批量上架、全部上架、都上架。"
+metadata:
+  requires:
+    bins: ["r2-cli"]
+  related:
+    - "r2-shared"
+    - "r2-auth"
+    - "r2-goods"
+---
+
+# 批量上架工作流
+
+**CRITICAL -- 开始前 MUST 先用 Read 工具读取 [../r2-shared/SKILL.md](../r2-shared/SKILL.md) 和 [../r2-auth/SKILL.md](../r2-auth/SKILL.md)，确保已登录并了解执行规则。商品命令详细用法见 [../r2-goods/SKILL.md](../r2-goods/SKILL.md)。**
+
+## 适用场景
+
+- "帮我把这些商品都上架"
+- "选品库全部上架到店铺"
+- "这几件都上架了吧"
+
+## 工作流
+
+1. **确认店铺**：`r2-cli goods shops --json` → 展示店铺让用户选择
+2. **确认仓库**：`r2-cli goods stocks --json` → 用户选择仓库
+3. **展示待上架商品**：`r2-cli goods list --stock-id <id> --json`
+4. **用户选择要上架的商品**（可多选）
+5. **逐商品询问价格** → 逐个执行 `goods up`
+6. **汇总结果展示**
+
+   ```
+   批量上架结果：
+   ✅ [商品A] → ¥[价格] → 成功（listing id: [id]）
+   ✅ [商品B] → ¥[价格] → 成功（listing id: [id]）
+   ❌ [商品C] → 失败：[错误原因]
+   ```
+
+## 友好输出指引
+
+批量上架过程中，每个商品独立执行 `goods up --json`，Agent 需要逐个处理响应：
+
+**每上架一个商品，及时反馈进度**：
+```
+[1/3] Nike 运动鞋 → 上架中...
+[1/3] Nike 运动鞋 → ✅ 成功（id: 12345）
+[2/3] Adidas T恤 → 上架中...
+[2/3] Adidas T恤 → ❌ 失败：商家编码重复
+...
+```
+
+**全部完成后展示汇总**：
+```
+批量上架完成！
+✅ 成功：2 个商品
+  - Nike 运动鞋 → ¥299 → 店铺A（id: 12345）
+  - LV 包 → ¥9999 → 店铺B（id: 12346）
+❌ 失败：1 个商品
+  - Adidas T恤 → 错误：商家编码重复
+```
+
+> 每个 `goods up --json` 返回 `{ success, data: { listing: { id, goodsName, price, shopName, status } } }`。Agent 从每个响应中提取 `success` 和 `data.listing` 字段，累加后汇总展示。
+>
+> 中途 Token 过期时：停止工作流，告知用户已完成的商品数，引导重新登录后从断点继续。**不要丢弃已完成的结果**。
+
+## 规则
+
+- **每个商品独立提交**：一个失败不影响其他商品
+- **批量上架间隔至少 1 秒**，避免触发限流
+- **中途 Token 过期**：停止工作流，引导重新登录后从当前商品继续
+- **提交失败 ≠ 已下架**：可能只是轮询超时，稍后用 `goods listing` 确认
+
+## 参考
+
+- [r2-goods/SKILL.md](../r2-goods/SKILL.md) — goods up 详细参数
+- [r2-shared/SKILL.md](../r2-shared/SKILL.md) — 执行规则、Token Expiry Recovery

package/skills/r2-workflow-batch-up/_meta.json

@@ -0,0 +1,5 @@
+{
+  "ownerId": "round2ai",
+  "slug": "r2-workflow-batch-up",
+  "version": "1.0.0"
+}

package/skills/r2-workflow-goods-audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: r2-workflow-goods-audit
+version: 1.0.0
+description: "商品审核上架工作流。检查待上架商品的信息完整性后批量提交。触发词：审核上架、审核通过后上架、批量上架审核。"
+metadata:
+  requires:
+    bins: ["r2-cli"]
+  related:
+    - "r2-shared"
+    - "r2-auth"
+    - "r2-goods"
+---
+
+# 商品审核上架工作流
+
+**CRITICAL -- 开始前 MUST 先用 Read 工具读取 [../r2-shared/SKILL.md](../r2-shared/SKILL.md) 和 [../r2-auth/SKILL.md](../r2-auth/SKILL.md)，确保已登录并了解执行规则。商品命令详细用法见 [../r2-goods/SKILL.md](../r2-goods/SKILL.md)。**
+
+## 适用场景
+
+- "审核通过的商品可以上架了"
+- "帮我检查一下这些商品信息有没有问题"
+
+## 工作流
+
+1. **查询待审核商品**：`r2-cli goods list --json`
+2. **AI 校验信息完整性**：检查每个商品是否具备上架所需信息
+3. **标记问题商品**：展示有问题的商品和具体缺失项
+
+   ```
+   商品完整性检查结果：
+   ✅ [商品A] — 信息完整
+   ❌ [商品B] — 缺少：价格、图片
+   ❌ [商品C] — 缺少：类目
+   ```
+4. **用户确认**：用户确认后进入批量上架
+5. **批量提交**：逐个执行 `goods up`
+
+## 友好输出指引
+
+**审核结果展示**：从 `goods list --json` 返回的 JSON 中提取每个商品的字段，逐一校验。展示时不展示原始 JSON，直接输出浓缩的审核结果：
+
+```
+正在审核 5 个商品...
+─────────────────────
+✅ 商品A — 信息完整
+❌ 商品B — 缺少：价格、图片
+   → 请补充 salePrice 和图片后再上架
+❌ 商品C — 缺少：类目
+   → 请分配类目后再上架
+─────────────────────
+结果：2 个通过，1 个缺项跳过（2 个无需处理）
+```
+
+**批量提交进度**：逐个执行 `goods up --json` 时，实时反馈进度：
+```
+正在上架通过审核的商品...
+[1/2] 商品A → ✅ 成功（listing id: 12345）
+[2/2] 商品D → ✅ 成功（listing id: 12346）
+全部上架完成！
+```
+
+> `goods list --json` 返回 `{ success, data: { list: SelectGoodsItem[], pagination: { total, pageNum, pageSize } } }`。Agent 从 `data.list` 中遍历，检查每个商品的 `goodsName`（标题）、`salePrice`（价格 > 0）、`cate1Name/cate2Name/cate3Name`（类目）、`img`（图片）。
+>
+> 缺项商品标记后**跳过不上架**，只上架信息完整的商品。结束后汇总告知用户哪些商品因缺项被跳过。
+
+## 完整性校验规则
+
+| 检查项 | 要求 |
+|--------|------|
+| 标题 | 非空，包含品牌+款式+颜色+尺码 |
+| 价格 | `salePrice > 0` |
+| 类目 | 已分配有效类目 |
+| 图片 | 至少 1 张 |
+
+## 参考
+
+- [r2-goods/SKILL.md](../r2-goods/SKILL.md) — 商品管理命令
+- [r2-goods/scenes/r2-scene-batch-operations.md](../r2-goods/scenes/r2-scene-batch-operations.md) — 批量操作指南
+- [r2-shared/SKILL.md](../r2-shared/SKILL.md) — 执行规则

package/skills/r2-workflow-goods-audit/_meta.json

@@ -0,0 +1,5 @@
+{
+  "ownerId": "round2ai",
+  "slug": "r2-workflow-goods-audit",
+  "version": "1.0.0"
+}