@round2ai/r2-cli 1.0.9 → 1.0.11

package/skills/r2-auth/SKILL.md

@@ -1,80 +1,148 @@
 ---
 name: r2-auth
-description: R2-CLI 认证登录专家。两步式扫码登录和闲鱼店铺授权。用于登录、login、auth、扫码、二维码、授权、xianyu、logout、登出、状态查询场景。Agent 生成二维码后同时展示 unicodeQR 和 qrUrl 给用户。
+description: R2-CLI 认证登录专家。扫码登录和闲鱼店铺授权。用于登录、login、auth、扫码、二维码、授权、xianyu、logout、登出、状态查询场景。Agent 使用 auth login --json 一步完成登录。Agent 必须先将 qrUrl 链接展示给用户，再等待扫码结果。
 ---
 
 # R2-Auth Skill
 
-两步式扫码登录 + 闲鱼店铺授权，专为 AI Agent 设计。
+扫码登录 + 闲鱼店铺授权，专为 AI Agent 设计。
 
 ## 命令前缀
 
-见 **r2-cli** skill 的"命令前缀自动检测"章节。
+见 **r2-cli** skill 的"命令前缀自动检测"章节。以下文档使用 `r2-cli` 作为前缀，根据检测结果替换。
 
-## 扫码登录（两步）
+---
+
+## 扫码登录（一步式，推荐）
 
-### 第 1 步：生成二维码
+一条命令完成：生成扫码页面 + 自动打开浏览器 + 自动轮询登录状态：
 
 ```bash
-r2-cli auth login qr
+r2-cli auth login --json
 ```
 
-输出 JSON：
+命令会依次输出两段 JSON：
+
+### 第 1 段：二维码信息（立即输出）
+
 ```json
 {
   "qrToken": "xxx",
   "expireTimeMs": 300000,
   "pollIntervalMs": 800,
-  "unicodeQR": "█▀▀▀▀▀█ ...",
   "url": "https://m.puresnake.com/r2/auth/login?qrToken=xxx&from=wechat",
   "qrUrl": "http://127.0.0.1:52173/login/"
 }
 ```
 
-**Agent 必须同时展示以下两种方式**：
+| 字段 | 说明 |
+|------|------|
+| `qrToken` | 二维码 token（轮询用，不需要手动使用） |
+| `expireTimeMs` | 二维码过期时间（毫秒），默认 5 分钟 |
+| `pollIntervalMs` | 轮询间隔（毫秒），不需要手动使用 |
+| `url` | 扫码链接（用户也可手动访问） |
+| `qrUrl` | 本地浏览器扫码页面链接 |
 
-1. 将 `unicodeQR` 直接输出到聊天窗口（unicode 半块字符 █▀▄ 可显示为 QR 码）
-2. 输出 `qrUrl` 链接供用户点击在浏览器中打开
+### 第 2 段：登录结果（用户扫码确认后输出）
 
-两种方式缺一不可。用户可使用**第二回合 APP / 微信 / 支付宝**扫码。
+成功：
 
-### 第 2 步：立即轮询登录状态
+```json
+{ "success": true, "userInfo": { "nickname": "...", "mobile": "..." } }
+```
 
-**关键**：输出二维码后，Agent 必须立即在后台启动轮询，不要等待用户回复。
+失败：
 
-```bash
-r2-cli auth login poll --token <qrToken> --expire <expireTimeMs> --interval <pollIntervalMs>
+```json
+{ "success": false, "error": "二维码已过期" }
 ```
 
-使用 Bash 工具的 `run_in_background: true` 启动，然后用 `TaskOutput` 阻塞等待。参数取自第 1 步返回的 JSON。
+### Agent 操作步骤
 
-成功：`{ "success": true, "userInfo": { "nickname": "...", "mobile": "..." }, "token": "..." }`
-失败：`{ "success": false, "error": "轮询超时 ..." }`
+1. 用 Bash 工具 `run_in_background: true` 启动命令
+2. 用 `TaskOutput(block=true, timeout=5000)` 获取第 1 段 JSON
+3. **必须先**将 `qrUrl` 以醒目格式单独一行展示给用户：
 
-## 闲鱼店铺授权（两步）
+   ```
+   扫码登录：http://127.0.0.1:PORT/login/
+   ```
 
-流程与登录相同。
+4. 告知用户：浏览器会尝试自动打开扫码页面，如未打开请手动点击上方链接。用户可使用**第二回合 APP / 微信 / 支付宝**扫码。
+5. 用 `TaskOutput(block=true, timeout=300000)` 等待第 2 段 JSON（登录结果）
+6. 检查 `success` 字段判断登录是否成功
+
+**为什么必须先展示链接**：自动打开浏览器在某些环境下可能失败（远程服务器、SSH、无头终端）。链接是用户扫码的唯一保障，必须优先展示。
+
+> 旧版两步式流程（先 `auth login qr` 再 `auth login poll`）已废弃。如需手动轮询，可使用 `auth login poll --token <>`。
+
+---
+
+## 闲鱼店铺授权
+
+流程与登录类似，同样一步完成：
 
 ```bash
-# 第 1 步
-r2-cli auth xianyu qr
-# → { "state": "xxx", "expireTimeMs": 300000, "pollIntervalMs": 1000, "unicodeQR": "...", "qrUrl": "..." }
+r2-cli auth xianyu --json
+```
+
+### 第 1 段：授权二维码信息（立即输出）
+
+```json
+{
+  "state": "xxx",
+  "expireTimeMs": 300000,
+  "pollIntervalMs": 1000,
+  "qrUrl": "http://127.0.0.1:PORT/login-xianyu/"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `state` | 授权状态 token（轮询用） |
+| `expireTimeMs` | 过期时间（毫秒），默认 5 分钟 |
+| `pollIntervalMs` | 轮询间隔（毫秒） |
+| `qrUrl` | 本地浏览器授权页面链接 |
+
+### 第 2 段：授权结果（用户扫码确认后输出）
+
+成功：
 
-# 第 2 步
-r2-cli auth xianyu poll --state <state> --expire <expireTimeMs> --interval <pollIntervalMs>
-# → 成功：{ "success": true, "shopId": "...", "shopName": "..." }
+```json
+{ "success": true, "shopId": "...", "shopName": "..." }
+```
+
+失败：
+
+```json
+{ "success": false, "error": "授权链接已过期" }
 ```
 
-Agent 同样必须同时展示 `unicodeQR` 和 `qrUrl`。
+Agent 操作步骤与登录相同：
+1. 获取第 1 段 JSON
+2. **先展示 `qrUrl` 链接给用户**（单独一行，醒目格式）
+3. 告知用户浏览器会尝试自动打开，如未打开请手动点击链接
+4. 等待第 2 段 JSON
+
+---
 
 ## 其他命令
 
 | 命令 | 说明 |
 |------|------|
+| `r2-cli auth login` | 扫码登录（自动打开浏览器，人类使用） |
+| `r2-cli auth login --json` | 扫码登录（输出 JSON + 自动打开浏览器，Agent 推荐） |
+| `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 分钟过期，超时需重新执行第 1 步
-- 登录成功后，后续 goods 等命令可直接使用
+- 命令会尝试自动打开浏览器展示扫码页面，但链接始终会输出到终端，确保即使浏览器未打开用户也能手动访问
+- 二维码默认 5 分钟过期，超时需重新执行命令
+- 登录成功后 Token 存储在 `~/.r2-cli/config.json`（原子写入，防止中断导致丢失），后续 `goods` 等命令可直接使用
+- 内存缓存的 Token 带过期检查（5 分钟安全边际），过期自动重新读取

package/skills/r2-cli/SKILL.md

@@ -5,7 +5,7 @@ description: R2-CLI 二手潮奢交易 CLI 工具。用于认证登录、商品
 
 # R2-CLI Skill
 
-二手潮奢交易命令行工具。
+二手潮奢交易命令行工具，由 Round2AI 团队维护。覆盖商品上架、认证登录等核心业务域。
 
 ## 安装
 
@@ -34,37 +34,37 @@ npm install -g @round2ai/r2-cli@latest
 
 | 命令 | 说明 |
 |------|------|
-| `r2-cli auth login` | 扫码登录（交互式，人类用） |
-| `r2-cli auth login qr` | 生成登录二维码 JSON（Agent 第1步） |
-| `r2-cli auth login poll --token <>` | 轮询登录状态 JSON（Agent 第2步） |
-| `r2-cli auth xianyu` | 闲鱼店铺授权（交互式） |
-| `r2-cli auth xianyu qr` | 获取授权二维码 JSON（Agent 第1步） |
-| `r2-cli auth xianyu poll --state <>` | 轮询授权状态 JSON（Agent 第2步） |
+| `r2-cli auth login` | 扫码登录（自动打开浏览器，人类使用） |
+| `r2-cli auth login --json` | 扫码登录（自动打开浏览器 + JSON 输出，Agent 推荐） |
+| `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` | 退出登录 |
 
-> 认证登录的 Agent 两步式流程见 **r2-auth** skill。
+> 认证登录的详细 Agent 操作流程见 **r2-auth** skill。
 
 ## 商品管理命令
 
 | 命令 | 说明 |
 |------|------|
-| `r2-cli goods shops [--json]` | 查看所有已授权店铺 |
+| `r2-cli goods shops [--json]` | 查看所有已授权店铺（跨平台） |
 | `r2-cli goods stocks [--json]` | 查看所有仓库 |
-| `r2-cli goods list --stock-id <id> [--json]` | 查看仓库中的选品商品 |
-| `r2-cli goods listing [--json]` | 查询上架列表（支持 --id/--shop-id/--status 过滤） |
-| `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]` | 下架商品（**必须先确认**） |
-| `r2-cli goods price --id <id> --price <amount> [--json]` | 修改上架价格（**必须先询问用户新价格**） |
+| `r2-cli goods list [--stock-id <id>] [--stock-goods-id <id>] [--json]` | 查看选品商品（两个过滤参数均为可选，支持 `--page` 和 `--size`） |
+| `r2-cli goods listing [--json]` | 查询上架列表（支持 `--id` / `--shop-id` / `--stock-goods-id` / `--stock-id` / `--status` / `--platform` 过滤） |
+| `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 上架 4 步流程
 
-**核心理念：Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。**
+**核心原则：Agent 获取数据后展示给用户选择，不要让用户自己提供 ID。**
 
-1. `r2-cli goods shops --json` → 展示店铺（shopId、shopName、platform）→ 用户选择
-2. `r2-cli goods stocks --json` → 展示仓库（stockId、stockName）→ 用户选择
-3. `r2-cli goods list --stock-id <id> --json` → 展示商品（stockGoodsId、goodsName、brand、size、salePrice）→ 用户选择
+1. `r2-cli goods shops --json` → 展示店铺（`shopId`、`shopName`、`platform`）→ 用户选择
+2. `r2-cli goods stocks --json` → 展示仓库（`stockId`、`stockName`）→ 用户选择
+3. `r2-cli goods list --stock-id <id> --json` → 展示商品（`stockGoodsId`、`goodsName`、`brand`、`size`、`salePrice`）→ 用户选择（也可用 `--stock-goods-id <id>` 查询单个商品）
 4. `r2-cli goods up --stock-goods-id <id> --shop-id <id> --price <amount> --json` → 提交上架（自动轮询结果）
 
-> 完整流程和参数说明见 **r2-goods** skill。
+> 完整流程、参数说明和注意事项见 **r2-goods** skill。

package/skills/r2-goods/SKILL.md

@@ -15,20 +15,20 @@ description: R2-CLI 商品管理专家。用于商品上架/下架/改价、查
 
 | 命令 | 说明 |
 |------|------|
-| `r2-cli goods shops [--json]` | 查看所有已授权店铺 |
+| `r2-cli goods shops [--json]` | 查看所有已授权店铺（跨平台） |
 | `r2-cli goods stocks [--json]` | 查看所有仓库 |
-| `r2-cli goods list --stock-id <id> [--json]` | 查看仓库中的选品商品 |
-| `r2-cli goods listing [--json]` | 查询上架列表（支持 --id/--shop-id/--status 过滤） |
-| `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]` | 下架商品（**必须先确认**） |
-| `r2-cli goods price --id <id> --price <amount> [--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。
+**每一步 Agent 获取数据后，必须展示给用户让用户做选择。不要让用户自己提供 ID。**
 
 ### 第 1 步：获取店铺 → 用户选择
 
@@ -36,7 +36,15 @@ description: R2-CLI 商品管理专家。用于商品上架/下架/改价、查
 r2-cli goods shops --json
 ```
 
-展示 `shopId`（第三方店铺 ID，**上架参数取这个，不是 `id`**）、`shopName`、`platform`。
+返回店铺列表，每个店铺包含：
+
+| 字段 | 说明 |
+|------|------|
+| `shopId` | 第三方店铺 ID（**上架参数取这个，不是 `id`**） |
+| `shopName` | 店铺名称 |
+| `platform` | 平台（xianyu / douyin 等） |
+
+展示给用户选择后记录 `shopId`。
 
 ### 第 2 步：获取仓库 → 用户选择
 
@@ -44,15 +52,36 @@ r2-cli goods shops --json
 r2-cli goods stocks --json
 ```
 
-展示 `stockId`、`stockName`。`stockId` 用于第 3 步过滤商品。
+返回仓库列表，每个仓库包含：
+
+| 字段 | 说明 |
+|------|------|
+| `stockId` | 仓库 ID（用于第 3 步过滤商品） |
+| `stockName` | 仓库名称 |
 
 ### 第 3 步：获取选品商品 → 用户选择
 
 ```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`（**上架参数取这个**）、`goodsName`、`brand`、`size`、`salePrice`。支持翻页（`--page 2`）。
+返回商品列表，每个商品包含：
+
+| 字段 | 说明 |
+|------|------|
+| `stockGoodsId` | 库存商品 ID（**上架参数取这个**） |
+| `goodsName` | 商品名称 |
+| `brand` | 品牌 |
+| `size` | 尺码 |
+| `salePrice` | 建议售价 |
+| `cate1Name` / `cate2Name` / `cate3Name` | 分类 |
 
 ### 第 4 步：提交上架
 
@@ -60,47 +89,118 @@ r2-cli goods list --stock-id <stockId> --json
 r2-cli goods up --stock-goods-id <stockGoodsId> --shop-id <shopId> --price <amount> --json
 ```
 
-命令自动轮询上架进度（每 2 秒，最多 10 秒），返回 `{ success, data: { submit, listing } }`。检查 `data.listing.status` 判断最终状态（init/up/down/fail）。
+命令会自动轮询上架进度（每 2 秒查询一次，最多 10 秒），最终返回：
+
+```json
+{
+  "success": true,
+  "data": {
+    "submit": { "...提交结果..." },
+    "listing": {
+      "id": "上架记录ID",
+      "status": "up",
+      "goodsName": "...",
+      "price": 299,
+      "...": "..."
+    }
+  }
+}
+```
+
+检查 `data.listing.status` 判断最终状态：
+
+| status | 含义 |
+|--------|------|
+| `init` | 待上架（处理中，正常不应出现在最终结果） |
+| `up` | 已上架成功 |
+| `down` | 已下架 |
+| `fail` | 上架失败，查看 `errorMsg` 了解原因 |
 
-### 上架参数
+### 上架参数说明
 
-| 参数 | 必填 | 来源 |
+| 参数 | 必填 | 说明 |
 |------|------|------|
-| `--stock-goods-id <id>` | 是 | 第 3 步 `stockGoodsId` |
-| `--shop-id <id>` | 是 | 第 1 步 `shopId`（不是 `id`） |
-| `--price <amount>` | 是 | 用户输入 |
-| `-p, --platform` | 否 | 默认 xianyu |
-| `--json` | 否 | Agent 推荐 |
+| `--stock-goods-id <id>` | 是 | 库存商品 ID（来自第 3 步的 `stockGoodsId`） |
+| `--shop-id <id>` | 是 | 第三方店铺 ID（来自第 1 步的 `shopId`，**不是 `id`**） |
+| `--price <amount>` | 是 | 上架价格（正数） |
+| `-p, --platform <platform>` | 否 | 平台，默认 xianyu |
+| `--json` | 否 | JSON 输出（Agent 推荐使用） |
 
 ---
 
 ## 下架商品
 
-**Agent 必须先向用户确认后再下架。**
+**Agent 必须先向用户确认后再执行下架操作。**
+
+支持两种方式指定商品（二选一）：
 
 ```bash
+# 方式 1：通过上架记录 ID（来自 listing 列表的 id 字段）
 r2-cli goods down --id <goodsListingId> --json
-# 或 --stock-goods-id <id> --shop-id <id>
+
+# 方式 2：通过库存商品 ID + 店铺 ID
+r2-cli goods down --stock-goods-id <id> --shop-id <id> --json
 ```
 
+参数校验：必须提供 `--id` 或同时提供 `--stock-goods-id` 和 `--shop-id`，否则返回错误。
+
+---
+
 ## 修改价格
 
-**Agent 必须先询问用户新价格，不能自行决定。** 用户说"修改价格"时，先问"要改成多少？"。
+**Agent 必须先询问用户新价格，不能自行决定价格。** 用户说"修改价格"时，先问"要改成多少？"。
 
 ```bash
+# 方式 1：通过上架记录 ID
 r2-cli goods price --id <goodsListingId> --price <新价格> --json
-# 或 --stock-goods-id <id> --shop-id <id>
+
+# 方式 2：通过库存商品 ID + 店铺 ID
+r2-cli goods price --stock-goods-id <id> --shop-id <id> --price <新价格> --json
 ```
 
+`--price` 为必填参数。同样需要提供 `--id` 或 `--stock-goods-id + --shop-id`。
+
+---
+
 ## 查询上架列表
 
 ```bash
+# 查看所有上架记录
 r2-cli goods listing --json
-# 支持 --id / --shop-id / --stock-goods-id / --status <init|up|down|fail> / --platform 过滤
+
+# 过滤查询
+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 <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 |
+
 ---
 
 ## 错误处理
 
-所有命令统一格式：`{ "success": false, "error": "错误信息" }`。检查 `success` 判断成败。
+所有 `--json` 命令统一错误格式：
+
+```json
+{ "success": false, "error": "错误信息" }
+```
+
+检查 `success` 字段判断成败。常见错误：
+
+| 错误信息 | 原因 | 解决方法 |
+|----------|------|----------|
+| `请先运行 r2-cli auth login 登录` | 未登录或 Token 过期 | 执行 `r2-cli auth login --json` |
+| `请指定下架条件：--id 或 --stock-goods-id + --shop-id` | 缺少必要参数 | 补充参数 |
+| `--price <amount> 为必填参数` | 改价时未提供价格 | 询问用户新价格后传入 |
+| `轮询超时` | 上架结果查询超时 | 建议用户稍后用 `goods listing` 查看 |