r2-shared

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

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 必须提示更新

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

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

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

安装与认证

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

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

# 查看状态
r2-cli auth status

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

统一错误格式

所有 --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）到终端
• 变更类操作前确认用户意图（上架、下架、改价等）