故障排查
诊断命令
kuaimai-cli doctor --output json
kuaimai-cli auth status --output json
kuaimai-cli auth check system --output json
kuaimai-cli auth check open --output json
kuaimai-cli --verbose <command>
提交工单时建议附带：CLI 版本、doctor / auth status 的 JSON（不要 --reveal）、报错原文、操作系统与 Node 版本。
禁止提交：完整 accessToken、appSecret、refreshToken、含凭证的截图。
安装问题
| 现象 | 处理 |
|---|---|
kuaimai-cli: command not found | 确认全局 npm bin 在 PATH；重新 npx @kuaimai-cli/cli@latest install |
| 未安装 Node / npm | 安装 Node.js（推荐 20/22 LTS） |
| Node 版本过低 | 升级到 ≥16，建议 20+ |
| 安装二进制失败 / Gitee 超时 | 检查网络；KUAIMAI_CLI_PREFER_MIRROR=1 优先镜像；见 安装 |
| checksum 失败 | 勿跳过校验；换网络重试或固定版本重装 |
| npm registry 异常 | 检查 npm config get registry |
鉴权问题
| 现象 | 处理 |
|---|---|
| 系统侧 401 | token 无效或过期 → 重新申请并 auth login system |
| 系统侧 403 | 账号无接口权限 → 联系 ERP 管理员 |
| 开放平台凭证错误 | 核对四件套；重新 auth login open |
auth refresh open 失败 | 会话过期或触达刷新限流 → 重新登录或联系实施 |
| 不确定登了没 | auth status / doctor |
接口调用问题
| 现象 | 处理 |
|---|---|
| registry 拉取失败 | 检查 registry.source 与网络；registry sync |
| 找不到 apiId | capabilities 确认是否已发布；勿手写 URL |
| 参数格式错误 | schema <apiId> 核对后用 --params / --body |
| 成功但数据为空 | 核对筛选条件与权限；不一定是故障 |
| 代理 / 公司证书 | 配置系统信任证书与代理；--verbose 看请求失败原因 |
输出解析
若脚本解析 JSON 失败：确认使用了 --output json，且只解析 stdout（stderr 可能有提示）。见 输出协议。