SKILL.md
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 通过以下优先级解析：
- 环境变量（优先级最高）：
CAICLITOKEN=<your-token> - 本地凭据存储（keychain）：通过
cai-cli auth login保存 - 若均无效，返回
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'环境变量
| 变量 | 说明 |
|---|---|
CAICLITOKEN |
API Token（覆盖 keychain 配置） |
CAICLICONFIG_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。