---
name: xianxin_cli
description: 闲芯系统 CLI 工具。通过 xxweb_cli 登录鉴权、管理业务数据。
metadata: {"openclaw": {"requires": {"bins": ["xxweb_cli"]}}}
---

# 闲芯 CLI 使用指南（供 AI Agent 使用）

## 工具信息

- 二进制名称：`xxweb_cli`
- 线上地址：`https://www.chipsresale.com`
- 所有业务命令均需登录鉴权
- 无需鉴权的命令：`--help`、`-h`、`--version`、`-v`、`login sendcode`、`login login`、`login logout`、`search`（检索本身无需登录）
- 需鉴权的命令：`sc`（收藏）、`cj`（出价）、`up`（BOM上传，工厂库存/工厂现货角色）、`mys`（单条BOM录入，贸易商角色）、`login role`（查看/修改角色）
- 所有命令均支持 `--format` 参数：`markdown`（默认）或 `json`

## 前置：登录鉴权

执行任何业务命令前，必须先完成登录。

### 登录流程（两步）

**第一步：发送验证码（短信）**
```bash
xxweb_cli login sendcode --mobile <手机号>
```
- 验证码通过短信发送至该手机号
- 有效期 5 分钟
- 双重限流（60 秒内均只能触发一次，否则报错「请1分钟后重试」）：
  - 同一手机号 60 秒内只能发送一次
  - 同一台设备（本机持久化的 `cliDeviceId`）60 秒内只能发送一次，**不论是否更换手机号**

**第二步：验证码登录/注册**
```bash
xxweb_cli login login --mobile <手机号> --code <4位验证码>
```
- 登录成功后 JWT 自动保存本地，后续命令自动携带
- 老用户成功输出示例：`登录成功！欢迎，张三（有效期至 2027-09-13）`
- 新用户（首次注册）会提示选择角色，需执行 `login role --type <1|2|3>` 完成角色设置

### 退出登录
```bash
xxweb_cli login logout
```

### 查看或修改用户角色（需登录）

```bash
# 查看当前角色
xxweb_cli login role

# 修改角色
xxweb_cli login role --type 1   # 我要卖货（工厂库存）
xxweb_cli login role --type 2   # 我要买货/贸易商
xxweb_cli login role --type 3   # 我要买货（工厂现货）
```

角色说明：
| 类型 | 名称 | 说明 |
|---|---|---|
| 1 | 我要卖货 | 工厂库存（有闲置芯片需要出售） |
| 2 | 我要买货/贸易商 | 贸易商（撮合交易，浏览库存） |
| 3 | 我要买货 | 工厂现货（工厂缺货，需要采购） |

## 错误处理

| 错误码 | 含义 | 处理方式 |
|---|---|---|
| 401 | 授权验证失败 | 执行登录流程 |
| 415 | 必填参数缺失 | 检查必填参数 |
| 426 | CLI 版本不匹配 | 重新下载安装最新版 CLI 和 SKILL.md：macOS 下载 `https://www.chipsresale.com/api_cli/download/xxweb_cli`，Windows 下载 `https://www.chipsresale.com/api_cli/download/xxweb_cli.exe`，SKILL.md 下载 `https://www.chipsresale.com/api_cli/download/SKILL.md`，覆盖安装后重新执行命令 |
| 500 | 系统异常 | 联系开发者 |
| 510 | 业务错误 | 根据 message 判断 |
| 511 | 参数值不合法 | 检查参数格式 |

## 命令索引

### search — 型号检索（无需登录）

| 命令 | 说明 | 参数 |
|---|---|---|
| `search <modelKey>` | 根据型号关键字检索型号列表，对应网站 `/search/1/<modelKey>` | `--page`（选填）页码，默认1 |

> `modelKey` 至少需要 4 个字符，否则报错（错误码 511）：「请输入至少4个字符的型号关键字」。

说明：检索结果根据角色返回不同列：

| 角色 | 返回列 |
|---|---|
| 未登录 | 序号、料号、品牌、D/C、库存数量 |
| 卖货(1) | 序号、料号、品牌、D/C、库存数量、**求购记录数**、收藏、我的报价（卖价） |
| 贸易商(2) | 序号、料号、品牌、D/C、库存数量、收藏、我的报价 |
| 买货(3) | 序号、料号、品牌、D/C、库存数量、收藏、我的报价（买价） |

> 卖货角色额外返回「求购记录数」，用于判断市场需求；贸易商/买货角色关注库存供给。未登录仅返回基础列。

```bash
xxweb_cli search ad78
xxweb_cli search ad78 --page 2
xxweb_cli search ad78 --format json
```

### sc — 收藏管理（需登录）

| 命令 | 说明 | 参数 |
|---|---|---|
| `sc <modelName>` | 收藏/取消收藏型号 | `--sc`（选填）默认收藏，`--sc=false` 取消 |

```bash
xxweb_cli sc AD78
xxweb_cli sc AD78 --sc=false
```

### cj — 型号出价（需登录）

| 命令 | 说明 | 参数 |
|---|---|---|
| `cj <modelName>` | 对指定型号提交报价，每条型号仅可出价一次 | `--price`（必填）报价金额、`--money`（选填）货币：￥=人民币、usd=美元，默认￥ |

```bash
xxweb_cli cj AD78 --price 1.23
xxweb_cli cj AD78 --price 1.23 --money usd
```

### up — BOM上传AI估价+自动人工报价（需登录，工厂库存/工厂现货）

| 命令 | 说明 | 参数 |
|---|---|---|
| `up <file>` | 上传BOM单返回逐型号AI估价，并自动提交人工报价（相当于网站首页「上传bom单ai免费报价」+点击「获取人工报价」） | 无（file 为 .xls/.xlsx 文件路径） |

返回内容：用户角色、每个型号的 品牌、型号、D/C、数量、目标价、**AI预报价**，预估总价（=Σ预报价×数量），以及人工报价单号。上传后服务端会先对每行做 AI 自动整理（校正型号/品牌/批号/封装，失败保留原值），估价与保存均基于整理后的数据。

**重要**：估价完成后会**自动提交保存并进入人工报价流程**（无需额外操作）。预估价仅供参考，我们已收到您的BOM信息，正在人工报价，完成后会与您联系。上传来源统一标记为「网站cli」（入库 source 列）。

**角色差异**（不同角色上传逻辑不同，共用同一命令，处理不同）：

| 角色 | 是否可用 | 场景与处理 |
|---|---|---|
| 卖货(1 工厂库存) | ✅ 可用 | **库存上架**：展示贸易商参考价，提交后按工厂库存收购口径重估价入库（单号 GCKC 开头），等待人工收购报价 |
| 买货(3 工厂现货) | ✅ 可用 | **采购询价**：展示工厂现货预估价，提交后入库（单号 MYS 开头），等待人工采购报价 |
| 贸易商(2) | ❌ up 不可用 | 请使用 `mys` 命令（单条录入，见下节） |

> 非开放角色执行会报错（错误码 510）：「此功能暂时无法运行…」。可先 `xxweb_cli login role --type 1|3` 切换角色。

> 预报价为 `-` 的行表示暂无该型号价格数据，不代表闲芯没有库存/需求，已一并提交人工报价；重复上传同一文件会生成多张报价单；大BOM含 AI 整理与估价可能耗时较长（CLI 已留 120 秒）。

```bash
xxweb_cli up ./bom.xlsx
xxweb_cli up ./bom.xlsx --format json
```

### mys — 贸易商单条BOM录入（需登录，仅贸易商角色）

| 命令 | 说明 | 参数 |
|---|---|---|
| `mys <modelName>` | 录入单条BOM型号（贸易商代客户录入，单条直存不估价，等待人工跟进） | `--company`（必填）客户公司、`--user`（必填）客户联系人、`--mobile`（必填）客户手机号、`--email`（选填）、`--source`（选填）来源属性默认 xxweb_cli 可自定义、`--manufacturer`/`--batch`/`--number`/`--price`（选填）型号信息 |

与 `up` 的区别：up 走 Excel 整表上传+AI估价（工厂库存/工厂现货）；mys 为**单条**录入（贸易商专用），不估价、不发通知，直存记录等待人工跟进。

**来源属性**：每条记录写入 source 列（默认 `网站cli`），可用 `--source 渠道名` 标记真实来源渠道。

> 客户公司/联系人不存在时会自动建档；同一客户可重复录入多条（每次生成新单号）。

```bash
xxweb_cli mys STM32F103C8T6 --company 客户公司 --user 张三 --mobile 13800138000
xxweb_cli mys STM32F103C8T6 --company 客户公司 --user 张三 --mobile 13800138000 --number 1000 --price 8 --source 渠道A
xxweb_cli mys STM32F103C8T6 --company 客户公司 --user 张三 --mobile 13800138000 --format json
```

### login — 登录管理

| 命令 | 说明 | 参数 |
|---|---|---|
| `login sendcode` | 发送短信验证码 | `--mobile`（必填）手机号 |
| `login login` | 验证码登录/注册 | `--mobile`（必填）手机号、`--code`（必填）验证码 |
| `login logout` | 退出登录，清除本地凭证 | 无 |
| `login role` | 查看或修改用户角色 | `--type`（选填）1=卖货 2=贸易商 3=买货，不填则查看当前角色 |