kraken-cli 错误处理机制解析:9 类 JSON 错误信封如何让 AI Agent 自动重试

原创2026-10-27 09:54:131,929 阅读

kraken-cli 错误处理机制解析:9 类 JSON 错误信封如何让 AI Agent 自动重试

kraken-cli 是首个 AI 原生的加密货币、股票、外汇与衍生品交易命令行工具。它的错误处理机制把每一次失败都包装成结构化的 JSON 错误信封,让 AI Agent 无需解析自然语言就能判断该重试、该修正参数,还是该直接停止。

kraken-cli 项目标识

什么是「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 循环只需要三步:

  1. 执行命令:始终加 -o json 2>/dev/null,只信任 stdout
  2. 读 error 字段路由:
    • network / websocket → 退避重试
    • rate_limit → 读 suggestion,先降频再重试,恢复前可用 kraken status 探活
    • auth / validation / api / config / io / parse → 停止重试,修正参数或报告人类
  3. 防重复下单:网络错误重试交易指令前,先查 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 🎯

登录后查看全文
kraken-cli