---
name: cai-shared
version: 0.1.0
description: "使用 cai-cli 操作爱采购 B2B 平台时，必须先加载本 Skill。包含凭据配置、全局参数、输出格式、退出码和错误处理规范。同时适用于更新爱采购SKILL"
metadata:
  requires:
    bins: ["cai-cli"]
  cliHelp: "cai-cli --help"
---

# cai-cli 通用使用规范

## 前置检查

执行任何 `cai-cli` 命令前，先检测命令是否存在：

```bash
command -v cai-cli >/dev/null 2>&1
```

如果 `cai-cli` 不存在，直接执行以下命令安装：

```bash
npm install -g @aicaigou/cli
```

安装完成后执行 `cai-cli --version` 验证。验证成功后继续原任务；如果安装失败，则停止当前任务并向用户说明失败原因，不得跳过安装继续执行或编造业务结果。同一会话内已经确认 `cai-cli` 可用后，不要重复安装。

## 认证配置

cai-cli 使用 `X-Cai-Token` 进行接口认证。Token 通过以下优先级解析：

1. **环境变量**（优先级最高）：`CAI_CLI_TOKEN=<your-token>`
2. **本地凭据存储**（keychain）：通过 `cai-cli auth login` 保存
3. 若均无效，返回 `NeedAuthorizationError`（exit code 3）

### 配置 Token

```bash
# 交互式配置
cai-cli auth login

# 或设置环境变量（临时）
export CAI_CLI_TOKEN=your_token_here

# 或直接写入配置
cai-cli config set token your_token_here
```

### 验证 Token 状态

```bash
# 本地 JWT 过期检测（无网络请求）
cai-cli auth status

# 调用服务端接口验证
cai-cli auth status --verify
```

---

## 全局参数

所有命令支持以下全局参数：

| 参数 | 说明 | 示例 |
|------|------|------|
| `--format` | 输出格式：`json`（默认）\|`table`| `--format table` |
| `--jq` | jq 过滤表达式，作用于 `data` 字段 | `--jq '.shopName'` |
| `--dry-run` | 打印请求描述，不实际发送 | `--dry-run` |

---

## 输出格式

所有命令的 stdout 为标准 JSON Envelope：

```json
{
  "ok": true,
  "data": { ... }
}
```

错误时（stderr）：

```json
{
  "ok": false,
  "error": {
    "type": "auth_error",
    "code": 212011,
    "message": "Token 无效",
    "hint": "logId: xxx"
  }
}
```

---

## 退出码

| 代码 | 含义 |
|------|------|
| 0 | 成功 |
| 1 | 通用错误 |
| 2 | 参数错误 |
| 3 | 认证错误（Token 未配置/无效/过期）|
| 4 | 网络错误 |

---

## 错误处理

**认证错误（exit 3）**：
```bash
cai-cli auth login  # 重新配置 Token
```

**网络错误（exit 4）**：
```bash
cai-cli doctor  # 检查网络连通性
```

**调试技巧**：
```bash
# 查看原始请求（不发送）
cai-cli shop +info --dry-run

# 直接调用任意接口
cai-cli api GET /gcli/cliapi/shop/info

# 过滤输出
cai-cli shop +info --jq '.shopName'
```

---

## 环境变量

| 变量 | 说明 |
|------|------|
| `CAI_CLI_TOKEN` | API Token（覆盖 keychain 配置）|
| `CAI_CLI_CONFIG_DIR` | 配置目录（默认 `~/.cai-cli`）|

---

## 更新skill

Skills 独立于 CLI 二进制发布，更新时执行以下命令重新拉取（会覆盖为最新）：

```bash
npx -y skills add https://b2b-material.bj.bcebos.com -y
```

命令会自动安装到 `~/.agents/skills/`，并额外同步到你的 Skill 用户目录，完成后告诉用户。
如需同时更新 CLI 本体，另执行 `npm install -g @aicaigou/cli`。