@round2ai/r2-cli 1.0.15 → 1.0.16

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,13 +14,16 @@ 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` 缩小范围提高效率。
 
 商品管理专家，指导 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。
 
 ## 上架路由决策
@@ -128,7 +131,7 @@ metadata:
 - **描述自动生成**：品牌+款式+颜色+材质+货号自动组合，不要标记为"需要补充"
 - **季节自动推断**：夹克→春秋季，羽绒服→秋冬季，T恤→夏季等，不需要问用户
 - **尺码/货号从标签读取**：图片中有标签时自动提取，读不到才问用户
-- **标题自动组合**：品牌+款式+颜色+尺码+成色
+- **标题自动组合**：品牌+款式+颜色+尺码+成色，**最长 30 单位**（半角字符 0.5、全角字符 1，约 30 汉字或 60 英文）。超长时优先保留品牌和核心款式，省略成色或尺码
 - **stuff-status 与 itemAttrs 成色映射**：
 
 | stuff-status | itemAttrs 成色 valueName |
@@ -143,6 +146,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": "错误信息" }`
@@ -158,5 +169,6 @@ 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` 查看 |

package/skills/r2-goods/_meta.json

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

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

@@ -2,22 +2,7 @@
 
 > **Prerequisite:** 读取 [`../SKILL.md`](../SKILL.md) 了解路由决策和命令概览。
 
-挂售模式支持完整商品信息：图片、类目、属性等。与普通上架（`goods up`）是不同流程。
-
-**核心理念**：**图片里能看到的，就别问用户**。Agent 从图片中提取一切可识别的信息，用户只需要提供价格。
-
-## 核心原则
-
-- **图片优先**：所有字段优先从图片提取，图片无法识别时才问用户
-- 必须问用户的只有：**价格**
-- 商家编码（`out-item-no`）**优先让用户自定义**，用户不填则推荐自动生成编码（如 `GS20260512-0005`）
-- **必须问用户的条件**：价格（永远无法从图片判断）。其他一切字段都应尝试从图片获取。商家编码优先用户自定义，不填则推荐自动生成
-- **描述必须自动生成**：基于 AI 识别的品牌+款式+颜色+材质+货号自动组合，不要标记为"需要补充"
-- **品牌必须双传**：`--brand-name`（文本字段）+ itemAttrs 中的一项（含 propId/valueId/valueName/propName/channelCatId），缺一不可
-- **季节自动推断**：根据商品类型推断适用季节（夹克/风衣→春秋季，羽绒服→秋冬季，T恤/短裤→夏季），不需要问用户
-- **尺码/货号从标签读取**：如果图片中有标签/吊牌/水洗标，尝试读取尺码和货号，读不到时才问用户
-- **标题自动组合**：品牌+款式+颜色+尺码+成色，自动组合为标题
-- 提交成功后展示上架结果摘要
+挂售模式支持完整商品信息：图片、类目、属性等。核心原则见 SKILL.md 的「关键注意事项」。
 
 ## 图片识别降级策略
 
@@ -26,7 +11,7 @@
 | 能查看图片（多模态） | 用 Read 工具读图 → 自动识别品牌/成色/类目/描述 |
 | 不能查看图片 | 跳过识别 → 向用户询问品牌、类目、成色、描述等信息 |
 
-> 不同 Agent 能力不同（Claude Code / Gemini 支持读图，部分 Agent 不支持）。Agent 应自行判断是否能识别图片，不能则直接走询问路径。两条路径最终都走相同的 submit 提交。
+> 不同 Agent 能力不同。Agent 应自行判断是否能识别图片，不能则直接走询问路径。两条路径最终都走相同的 submit 提交。
 
 ---
 
@@ -50,7 +35,7 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 }
 ```
 
-> 图片路径是用户本地文件路径。`--image-ids` 保持字符串，不要转数字（19 位 ID 会精度丢失）。**CLI 自动压缩超过 2MB 的图片**（使用 sharp 渐进式降低 JPEG quality 直到 < 2MB，PNG 自动转 JPEG），原文件不会被修改。多张图片**并行上传**，单张失败自动重试 1 次。
+> 图片路径是用户本地文件路径。`--image-ids` 保持字符串，不要转数字（19 位 ID 会精度丢失）。**CLI 自动压缩超过 2MB 的图片**（sharp 渐进式降低 JPEG quality 直到 < 2MB，PNG 自动转 JPEG），原文件不会被修改。多张图片**并行上传**，单张失败自动重试 1 次。
 
 返回（部分成功时带 `warning` 和 `failed` 字段）：
 
@@ -71,23 +56,6 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 
 > **多图不一致处理**：如果多张图片显示不同商品（如不同款式、不同品牌），Agent 应识别后告知用户，只保留同一商品的图片。不要把不同商品混在一起提交。
 
-**图片识别 vs 用户操作**：
-
-| 字段 | 可从图片识别？ | 处理方式 |
-|------|---------------|----------|
-| `--title`（标题） | ✅ | **自动组合**：品牌+款式+颜色+尺码+成色，汇总确认 |
-| `--desc`（描述） | ✅ | **自动生成**：品牌+系列+款式+颜色+材质+货号+成色组合，不要标记为"需要补充" |
-| `--stuff-status`（成色） | ✅ | 自动判断，汇总确认 |
-| `--brand-name`（品牌） | ✅ | 识别后调 brands 搜索确认，**同时加入 itemAttrs**，汇总确认 |
-| `--category-id` / `--channel-cat-id` | ✅ | 自动推断，汇总确认 |
-| 季节属性 | ✅ | **自动推断**：夹克/风衣→春秋季，羽绒服→秋冬季，T恤/短裤→夏季，卫衣→春秋季等 |
-| `--size`（尺码） | ⚠️ | 有标签/吊牌则读取，无则汇总时问 |
-| `--goods-no`（货号） | ⚠️ | 有标签则读取，无则留空 |
-| 款式/颜色/材质属性 | ⚠️ | 能识别则自动匹配 propsValues，不能则汇总时问 |
-| `--price`（售价） | ❌ | **必须问用户** |
-| `--out-item-no`（商家编码） | ⚠️ | 先问用户自定义编码，不填则推荐自动生成（如 `GS20260512-0005`） |
-| `--shop-id`（店铺） | ❌ | 只有一个店铺时自动选，多个则问 |
-
 **成色判断映射**：
 
 | 图片中商品状态 | `--stuff-status` 值 |
@@ -97,15 +65,6 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 | 轻微使用痕迹 | `95`（95新） |
 | 明显使用痕迹 | `90`（9新） |
 
-**季节推断映射**：
-
-| 商品类型 | 适用季节 |
-|----------|----------|
-| 夹克、风衣、卫衣、针织衫 | 春秋季 |
-| 羽绒服、棉衣、毛呢大衣 | 秋冬季 |
-| T恤、短裤、背心、凉鞋 | 夏季 |
-| 基础款衬衫、休闲裤 | 四季 |
-
 **如果用户没提供价格和商家编码，此时询问**（不要留到最后）。
 
 ---
@@ -118,7 +77,14 @@ r2-cli goods hang-up upload-images --shop-id <shopId> --files /path/img1.jpg,/pa
 r2-cli goods hang-up categories --json
 ```
 
-Agent 根据图片识别结果自动匹配类目（不需要用户从列表中选）。只在识别不确定时才展示列表。
+Agent 根据图片识别结果自动匹配类目（不需要用户从列表中选）。只在识别不确定时才展示列表：
+
+```
+请选择最匹配的类目：
+1. 男士鞋靴 > 低帮鞋（推荐）
+2. 男士鞋靴 > 运动鞋
+3. 男士鞋靴 > 板鞋
+```
 
 **获取属性 → 自动匹配**：
 
@@ -136,11 +102,7 @@ Agent 遍历所有属性，尽量自动匹配：
 
 > **props API 说明**：`props` 返回所有属性及其 `propsValues`（非品牌属性可直接从这里选值）；品牌属性需额外调用 `brands` 搜索。
 
-**品牌精确匹配规则**：brands 搜索结果中必须选**完全匹配**的官方名称（如搜 Nike → 只选 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等）
-
-**品牌搜索注意事项**：
-- **支持大小写模糊搜索**：如搜索 `nike` 也能匹配到 `Nike/耐克`，搜索 `louis` 也能匹配到 `Louis Vuitton/路易威登`
-- **搜索结果中选择精确匹配**：如搜 nike 返回多个结果，选官方名称 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等
+**品牌精确匹配规则**：brands 搜索结果中必须选**完全匹配**的官方名称（如搜 Nike → 只选 `Nike/耐克`，忽略 BACHNIKE、NIKE 7 等）。**支持大小写模糊搜索**。
 
 ```bash
 r2-cli goods hang-up brands --channel-cat-id <id> --prop-id <品牌propId> --key "Nike" --json
@@ -148,8 +110,6 @@ r2-cli goods hang-up brands --channel-cat-id <id> --prop-id <品牌propId> --key
 
 最终构建 `--item-attrs`（**5 个字段：valueName、valueId、propId、propName、channelCatId**）：
 
-**⚠️ 品牌必须同时出现在 itemAttrs 和 --brand-name 中**。只传 `--brand-name` 不会把品牌写入商品属性，品牌必须作为 itemAttrs 的一项传入（含 propId、valueId、valueName、propName、channelCatId）。
-
 ```json
 [
   { "valueName": "Nike/耐克", "valueId": "68af4e8f...", "propId": "83b8f62c...", "propName": "品牌", "channelCatId": "f4718bbb..." },
@@ -206,13 +166,11 @@ r2-cli goods hang-up submit \
   --json
 ```
 
-成功返回：
+成功返回：`{ "success": true, "data": "上架成功" }`
 
-```json
-{ "success": true, "data": "上架成功" }
-```
+### 友好输出指引
 
-**提交后展示上架结果摘要**（让用户知道上架了什么）：
+提交成功后，Agent 从流程中已收集的参数提取关键信息**汇总展示**，不依赖响应中的字段：
 
 ```
 上架成功！
@@ -224,6 +182,14 @@ r2-cli goods hang-up submit \
 - 店铺：xxx
 ```
 
+> Agent 提交前已收集所有参数（title、price、brand-name、category、stuff-status、shop-id），提交成功后直接用这些参数构建摘要，不要翻查历史记录。
+>
+> 如果提交失败（`success: false`），直接展示 `error` 字段内容：
+> ```
+> 上架失败：[error 内容]
+> ```
+> 不要展示整个 JSON。
+
 ---
 
 ## 必填字段处理
@@ -245,6 +211,8 @@ r2-cli goods hang-up submit \
 - **`--stuff-status` 准新是数字 `-1`**：不是字符串 `"-1"`，直接传 `--stuff-status -1`
 - **`--item-attrs` 传 JSON 字符串**：值必须是 `JSON.stringify()` 后的字符串，不能直接传对象。命令行示例：`--item-attrs '[{"propId":"x","valueId":"y"}]'`
 - **`--files` 和 `--image-ids` 都是逗号分隔**：不要多次传 `--files`，用逗号拼成单个值：`--files a.jpg,b.jpg`
+- **标题长度限制**：闲鱼标题上限 30 单位（半角字符 0.5、全角字符 1）。自动组合时如品牌+款式+颜色+尺码+成色超过限制，优先保留品牌和核心款式，省略成色或尺码。CLI 会校验用户提供的标题，超长报错
+- **价格上限**：售价上限 99,999,999 元，CLI 自动校验；原价仅展示用途，不校验上限
 - **`--category-id` 取 `catId` 不是 `id`**：categories 返回的数据中 `catId`（如 50106003）是真正的类目 ID，`id`（如 865）是自增 ID，不要用错
 
 ## 必填参数
@@ -252,7 +220,7 @@ r2-cli goods hang-up submit \
 | 参数 | 说明 |
 |------|------|
 | `--shop-id <id>` | 店铺 ID（即闲鱼用户名 account） |
-| `--title <title>` | 商品标题 |
+| `--title <title>` | 商品标题（最长 30 单位：半角 0.5/全角 1） |
 | `--price <amount>` | 售价 |
 | `--category-id <id>` | 大分类 ID（从 categories 获取） |
 | `--channel-cat-id <id>` | 小分类 ID（从 categories 获取） |
@@ -261,16 +229,6 @@ r2-cli goods hang-up submit \
 | `--desc <desc>` | 商品描述 |
 | `--out-item-no <no>` | 商家编码（同店铺唯一，用户自定义） |
 
-## 成色等级
-
-| 值 | 含义 |
-|----|------|
-| `100` | 全新 |
-| `-1` | 准新 |
-| `99` | 99新 |
-| `95` | 95新 |
-| `90` | 9新 |
-
 ## 可选参数
 
 | 参数 | 默认值 | 说明 |
@@ -289,17 +247,7 @@ r2-cli goods hang-up submit \
 
 ## 售后服务（默认关闭）
 
-提交时自动附带售后服务配置，**默认全部关闭**。卖家需在闲鱼 APP 开通后才能开启（我的 → 设置 → 卖家服务 → 保障服务），未开通的服务如果传 `true` 会导致提交失败（错误：`ITEM_CONDITION_NOT_SUPPORT_SIGN`）。
-
-| 服务 | 默认值 | 说明 |
-|------|--------|------|
-| 极速发货-24小时 | 关闭 | 24小时内发货 |
-| 描述不符包邮退 | 关闭 | 描述不符退货包邮 |
-| 七天无理由退货 | 关闭 | 支持七天无理由 |
-| 极速发货-10分钟 | 关闭 | 10分钟内响应 |
-| 极速发货-48小时 | 关闭 | 48小时内发货 |
-| 正品保障 | 关闭 | 正品保障服务 |
-| 虚拟-描述不符包退 | 关闭 | 虚拟商品描述不符包退 |
+提交时自动附带售后服务配置，**默认全部关闭**。卖家需在闲鱼 APP 开通后才能开启，未开通的服务如果传 `true` 会导致提交失败（错误：`ITEM_CONDITION_NOT_SUPPORT_SIGN`）。
 
 ## 挂售错误处理
 
@@ -309,11 +257,11 @@ r2-cli goods hang-up submit \
 | 413 / `图片太大` | 图片超过服务端大小限制 | CLI 自动压缩 > 2MB 的图片，如仍失败请手动压缩 |
 | `请填写有效的商品叶子类目` | category-id 或 channel-cat-id 错误 | 重新查询 categories |
 | `找不到传入的某些图片` | 图片 ID 无效或过期 | 重新上传图片 |
-| `商家编码重复` | out-item-no 同店铺已存在 | 更换唯一编码 |
-| `该商品已上架` | 挂售已下架商品重新提交使用了相同的 out-item-no | 更换新的 out-item-no，或检查 listing 确认该商品是否已在闲鱼端恢复上架 |
 | `ITEM_CONDITION_NOT_SUPPORT_SIGN` | 售后服务未开通或品类不支持 | 默认关闭售后，或在闲鱼 APP 开通对应服务 |
+| `标题过长` | 标题超过 30 单位限制 | 缩短标题，保留品牌和核心款式 |
 
 ## References
 
 - [r2-goods SKILL.md](../SKILL.md) — 商品管理概览和路由决策
 - [r2-shared](../../r2-shared/SKILL.md) — 认证和全局规则
+- [../scenes/r2-scene-hangup-fashion.md](../scenes/r2-scene-hangup-fashion.md) — 服装鞋包挂售场景指南

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

@@ -11,7 +11,16 @@
 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 秒），返回：
+命令自动轮询上架进度（每 2 秒，最多 10 秒），返回 `{ success, data: { submit, listing } }`。
+
+**提交成功展示模板**：
+```
+上架成功！
+- 商品：[goodsName]
+- 店铺：[shopName]
+- 价格：¥[price]
+- 上架 ID：[listing.id]（用于后续改价/下架）
+```
 
 ```json
 {
@@ -42,6 +51,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 提取这些字段展示给用户。
+
 ## 上架参数
 
 | 参数 | 必填 | 说明 |
@@ -57,6 +90,14 @@
 
 **Agent 必须先向用户确认后再执行下架。**
 
+**确认模板**：
+```
+确认下架？
+商品：[goodsName] | [brandName] | ¥[price]
+店铺：[shopName]
+输入 yes 确认，其他取消
+```
+
 ```bash
 # 方式 1：上架记录 ID
 r2-cli goods down --id <goodsListingId> --json
@@ -65,6 +106,16 @@ r2-cli goods down --id <goodsListingId> --json
 r2-cli goods down --stock-goods-id <id> --shop-id <id> --json
 ```
 
+### 友好输出指引
+
+下架响应 `{ "success": true, "data": "下架成功" }`。Agent 提取展示：
+```
+下架成功！
+- 商品：[goodsName]
+- 店铺：[shopName]
+- 上架 ID：[id]
+```
+
 ## 改价（price）
 
 **Agent 必须先询问用户新价格，不能自行决定。**
@@ -77,6 +128,15 @@ r2-cli goods price --id <goodsListingId> --price <新价格> --json
 r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --json
 ```
 
+### 友好输出指引
+
+改价响应 `{ "success": true, "data": "修改成功" }`。Agent 提取展示：
+```
+改价成功！
+- 商品：[goodsName]
+- 原价：¥[原价] → ¥[新价格]
+```
+
 ## 修改商品信息（edit）
 
 修改已上架商品的标题、描述、品牌、类目、图片、属性等。
@@ -121,32 +181,9 @@ r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --js
 | `--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
-```
+用户提供了图片文件时，参见场景指南：[../scenes/r2-scene-edit-with-images.md](../scenes/r2-scene-edit-with-images.md)
 
 ### 只改文字字段（无图片）
 
@@ -165,3 +202,20 @@ r2-cli goods edit --id 5 \
 ```
 
 > **注意**：改品牌时建议同时传 `--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,6 +66,14 @@ 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
@@ -63,3 +87,10 @@ r2-cli goods 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）
+
+**Agent 展示格式**：
+```
+上架商品列表：
+1. [goodsName] | [brandName] | ¥[price] | [status] | id: [id]
+2. [goodsName] | [brandName] | ¥[price] | [status] | id: [id]
+```