kraken-cli 错误处理机制解析:9 类 JSON 错误信封如何让 AI Agent 自动重试
kraken-cli 错误处理机制解析:9 类 JSON 错误信封如何让 AI Agent 自动重试
kraken-cli 是首个 AI 原生的加密货币、股票、外汇与衍生品交易命令行工具。它的错误处理机制把每一次失败都包装成结构化的 JSON 错误信封,让 AI Agent 无需解析自然语言就能判断该重试、该修正参数,还是该直接停止。
什么是「JSON 错误信封」?
传统 CLI 出错时往 stderr 打印一行文字,程序只能靠 if 猜原因。kraken-cli 采用了一套机器友好的契约:
- 退出码 0 表示成功;非 0 表示失败,此时 stdout 里一定是一个 JSON 对象
- 信封必含两个字段:
error(稳定分类)和message(可读细节) - 官方明确要求:路由基于
error字段,而不是message字符串(message 不稳定,随时可能改文案)
最小信封长这样:
{"error": "auth", "message": "Authentication failed: EAPI:Invalid key"}
这套逻辑集中在 src/errors.rs 中实现,JSON 模式下错误统一打印到 stdout 的规则见 src/output/json.rs。
9 类错误分类速查表
kraken-cli 把所有失败归入 9 个类别(ErrorCategory 枚举),每类都标注了是否可重试:
| 类别 | 含义 | 可重试 | Agent 建议动作 |
|---|---|---|---|
api |
交易所业务拒绝(余额不足、未知交易对等) | ❌ | 修正请求参数,不要原样重试 |
auth |
API key 无效、过期或权限不足 | ❌ | 停止所有操作,重新认证 |
network |
网络层故障,请求没到达服务器 | ✅ | 指数退避重试 |
rate_limit |
触发 Kraken 限流(最复杂的一类) | ✅ | 读 suggestion 字段调整策略 |
validation |
输入参数校验失败(请求还没发出) | ❌ | 修正类型、必填项、合法值 |
config |
配置文件缺失或 TOML 语法错误 | ❌ | 检查配置,优先用环境变量 |
websocket |
WebSocket 连接或协议错误 | ✅ | 退避重连 |
io |
文件系统读写失败 | ❌ | 检查路径与权限 |
parse |
API 响应不是合法 JSON(可能维护中) | ❌ | 记录原始响应,不要重试 |
完整定义可查阅 agents/error-catalog.json,这份文件被定位为 Agent 的路由契约——它明确写着:"Agents should route on the error field, not message strings."
关键设计:rate_limit 信封带三个「附加字段」
普通信封只有 error + message,但 rate_limit 是一个特例,它的信封多出三个专为 LLM 设计的字段:
{
"error": "rate_limit",
"message": "Spot REST API rate limit exceeded (EAPI:Rate limit exceeded).",
"suggestion": "Wait 5-15 seconds before retrying. ...",
"retryable": true,
"docs_url": "..."
}
suggestion:具体的分级限额和应对建议(例如 Spot REST 计数器各档位的上限与衰减速度、Futures 的成本预算池机制),Agent 可直接拿来调整请求频率retryable:布尔值,明确告诉 Agent「可以重试」docs_url:指向对应限流机制的文档页
注意一个反直觉的设计:CLI 自己不会重试限流错误,而是立刻把错误抛给 Agent。Kraken 有三种独立限流体系(Spot REST 计数器、撮合引擎逐交易对限额、Futures 成本预算池),每种的正确应对方式不同,由 Agent 结合 suggestion 内容决策是降频、换 WebSocket 流式订阅,还是使用批量下单,比 CLI 盲目重试更聪明。相关机制详解在 skills/kraken-rate-limits/SKILL.md。
CLI 内建重试:Agent 只处理「重试也没用」的错误
并非所有错误都要 Agent 操心。kraken-cli 在 src/client.rs 中已内建瞬态错误自动重试:
- 网络抖动、5xx 服务器错误:自动指数退避重试(初始 500ms,最多 3 次)
- WebSocket 断连:最多重连 12 次,带节奏化的指数退避和安全预算窗口
也就是说,只有当内建重试耗尽后,Agent 才会看到 network 或 websocket 信封。此时按目录中的推荐策略执行:指数退避(初始 1s、上限 30s)、最多 5 次。这套分层让「内网小故障」和「策略级失败」各得其所。
Agent 自动重试的决策流程
把上面的信息组合起来,一个健壮的 Agent 循环只需要三步:
- 执行命令:始终加
-o json 2>/dev/null,只信任 stdout - 读
error字段路由:network/websocket→ 退避重试rate_limit→ 读suggestion,先降频再重试,恢复前可用kraken status探活auth/validation/api/config/io/parse→ 停止重试,修正参数或报告人类
- 防重复下单:网络错误重试交易指令前,先查
open-orders和trades-history确认订单是否已到账,并全程使用--cl-ord-id做幂等标识
完整恢复模式(含部分成交处理、卡单处理)见 skills/kraken-error-recovery/SKILL.md,调用契约的权威描述在 CONTEXT.md 的 "Error Handling Contract" 章节。
相关资源索引
| 文件 | 用途 |
|---|---|
| src/errors.rs | 9 类错误枚举与 JSON 信封构建逻辑 |
| src/output/json.rs | 错误信封的输出渲染 |
| agents/error-catalog.json | 机器可读的错误分类与退避策略目录 |
| skills/kraken-error-recovery/SKILL.md | 订单失败恢复与防重复下单技能 |
| skills/kraken-rate-limits/SKILL.md | 限流机制与 Agent 应对策略 |
| README.md | 错误信封总览表格("Error envelopes" 小节) |
小结
kraken-cli 的错误处理机制本质上是一份写给 AI 看的 API 契约:稳定的 error 分类、明确的 retryable 信号、可直接执行的 suggestion 建议,加上内建重试兜底瞬态故障——这正是「AI 原生」CLI 与普通 CLI 的分水岭。上手时记住一条黄金法则:看 error,别读 message 🎯
