cai-shared

cai-cli 通用使用规范

前置检查

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

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

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

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

# 交互式配置
cai-cli auth login

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

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

验证 Token 状态

# 本地 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：

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

错误时（stderr）：

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

---

退出码

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

---

错误处理

认证错误（exit 3）：

cai-cli auth login  # 重新配置 Token

网络错误（exit 4）：

cai-cli doctor  # 检查网络连通性

调试技巧：

# 查看原始请求（不发送）
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 二进制发布，更新时执行以下命令重新拉取（会覆盖为最新）：

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

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