r2-shared - SKILL.md Agent Skill

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 每次执行自动对比线上最新版本：

被动检查：--json 命令输出中 _notice.update 表示有新版本
主动检查：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 无感知：

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

友好输出

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