# R2 Shared

> R2-CLI 共享基础规则。任何涉及 r2-cli 命令的操作（商品、认证、上架、下架、改价、挂售、查询、批量、审核）都必须先读取此 skill。包含：执行规则、版本检查与更新通知、统一错误格式、网络重试策略、Token 过期恢复、友好输出原则、分页建议。即使你只是帮用户执行一条 r2-cli 命令，也应该先读这个 skill。

- Skill: `round2ai/r2-shared` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add round2ai/r2-shared`
- Raw SKILL.md: https://api.skillmd.com/api/skills/round2ai/r2-shared/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: round2ai (https://skillmd.com/u/round2ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/round2ai/r2-shared

---


# R2-Shared (v1.3)

二手潮奢交易命令行工具，覆盖闲鱼、淘宝两大平台的商品上架、认证登录等核心业务。

## 执行规则

- 所有命令**必须**通过已安装的 `r2-cli` 二进制执行
- **禁止**读取项目源码或用 `tsx`/`node` 直接运行源文件
- `r2-cli` 不可用时，提示安装：`npm install -g @round2ai/r2-cli@latest`
- **不要在命令末尾加 `&`**：用 `run_in_background: true` 时不要额外加 `&`

## 命令路径

- Agent 使用平台化命令路径：`goods xianyu up/down/price/edit/listing/hang-up`、`goods taobao ...`
- 跨平台命令（`goods shops`、`goods stocks`、`goods list`）无平台前缀

## 版本检查

CLI 每次执行自动对比线上最新版本：

1. **被动检查**：`--json` 命令输出中 `_notice.update` 表示有新版本
2. **主动检查**：`r2-cli --version` 查看当前版本，低于 `minVersion` 必须提示更新

发现新版本时，完成当前请求后告知并提议更新：

```bash
r2-cli update
# 或：npm update -g @round2ai/r2-cli && npx skills add Round2AI/r2-cli --all -y
```

更新后提醒用户**重启 Agent** 以加载最新 Skills。

## 安装与认证

```bash
# 首次安装
npx @round2ai/r2-cli@latest install

# 登录（支持第二回合 APP / 微信 / 支付宝扫码）
r2-cli auth login --json

# 查看状态
r2-cli auth status
```

认证登录和第三方平台授权的完整流程见 **r2-auth** skill。

## 统一错误格式

所有 `--json` 命令统一格式：

```json
{ "success": false, "error": "错误信息" }
// API 错误和参数校验失败时额外包含：
{ "success": false, "error": "错误信息", "status": 400 }
```

常见错误及恢复方式：

| 错误 | 恢复 |
|------|------|
| `请先运行 r2-cli auth login 登录` | Token 过期且自动刷新失败 → 执行 `r2-cli auth login --json` |
| `二维码已过期` / `授权链接已过期` | 扫码超时 → 重新执行命令 |
| `轮询超时` | 提交已接受 → 稍后用 listing 命令查看 |

## Network & Retry

- **网络错误**（`TypeError`、`fetch failed`）：最多重试 2 次，间隔 3 秒
- **超时错误**（`timeout`）：重试 1 次
- **认证错误**（`401`、`请先登录`）：CLI 会**自动用 refreshToken 刷新**并重试；若命令最终返回 `登录已过期`，说明刷新也失败，需引导重新登录
- **轮询超时**：提交已接受，建议稍后查看

## Token 过期恢复

CLI 在收到 401 时会自动用本地 `refreshToken` 调 `/user/refresh` 换新 token 并透明重试，正常情况下 Agent 无感知：

1. **绝大多数情况**：401 由 CLI 自动恢复，无需干预，原工作流继续。
2. **若命令最终返回 `登录已过期` / `请重新登录`**：说明 refreshToken 也失效（自动刷新失败）→ **立即停止当前工作流**
3. 引导重新登录：`r2-cli auth login --json`
4. 登录成功后**从断点继续**，不要从头开始

## 友好输出

Agent 执行 `--json` 命令后，提取关键字段整理展示，不要直接丢原始 JSON：

```
❌ { "success": true, "data": [{ "shopId": "10086", "shopName": "xxx", "platform": "xianyu" }] }

✅ 店铺列表：
   1. xxx（xianyu）— shopId: 10086
```

规则：**Agent 看 JSON，用户看友好文本。** 查询用编号列表，操作提取关键字段，错误只展示 `error` 内容。

## 分页建议

查询类命令建议 `--page 1 --size 50`，有分页则继续翻页取完。

## 安全

- **禁止输出凭证**（token、config.json）到终端
- **变更类操作前确认用户意图**（上架、下架、改价等）