Claude Code 实战 12｜盘点跨交易所资产：CLI 包装、私钥安全与金融防错规范

让 Agent 碰真金白银的账户,和让它清磁盘、查数据库是两码事——错一步的代价不是重跑一遍,而是真实的钱。这一篇复盘用 Claude Code 盘点跨交易所资产的实战:如何用独立环境包装交易所 SDK、凭证的格式坑有多能坑人、资产为什么总是"少算了一大半",以及最关键的——金融操作的防错规范该怎么设计。核心结论只有一句:在钱面前,Agent 的默认姿势必须从"自动修复"切换成"呈现差异、等人确认"。

1. 场景:让 Agent 当"资产管家"的三道门槛

想让 Agent 一句话答出"我在各交易所一共有多少钱",要跨过三道门槛:

1. 接得上:每个交易所 SDK 有自己的安装方式、依赖、认证协议,先得让 CLI 在 Agent 环境里跑起来。
2. 算得全:现货只是冰山一角,理财、双币赢、杠杆、合约各是独立账户,漏查一个模块资产就严重偏低。
3. 不闯祸:凭证是敏感信息,操作可能不可逆(下单、划转),Agent 绝不能"自作主张"。

这三道门槛分别对应下面三节。它们的难度是递增的——接得上是体力活,算得全靠细心,不闯祸才是真正要靠规范兜底的地方。

2. 接得上:用独立环境包装交易所 SDK

第一道坎往往卡在安装。较新的 Debian/Ubuntu 对系统 Python 启用了 PEP 668 外部管理保护,直接 pip install 会报 externally-managed-environment:

# 报错:externally-managed-environment
pip install binance-connector

两条正解:优先建独立 venv(交易类工具尤其该隔离,别污染系统 Python);受限场景才用 pip install --break-system-packages。这个系列里交易所 SDK 都走独立环境包装——把认证、常用查询封进一个稳定的 CLI(如 binance-cli、okx),Agent 只调 CLI,不直接碰 SDK。好处是调用面稳定可复现,认证上下文也收敛在一处。

包装好之后还有一类"接上了却不生效"的坑:Agent 调用交易所 CLI 失败,排查下来常是技能定义太模糊。解药是在 SKILL.md 里给出确切的、可复制粘贴的命令(如 binance-cli simple-earn get-flexible-product-position),而不是只写"能查理财"。调试时的铁律是——先在终端直接把底层 CLI 命令跑通(确认工具、认证、权限都对),再回头查 Agent 为什么没调对。先分清是"工具不行"还是"Agent 没调对",能省一大半时间。

3. 凭证格式坑:三要素错位是认证失败的头号原因

交易所凭证是 Agent 最容易栽的地方,因为不同字段长得不一样,填反了不会有人提醒。一个真实 case:某交易所要三要素——API Key 是 UUID 格式、Secret 是定长 Hex、Passphrase 是自定义口令。用户把 UUID 误填进 Secret 字段、把 Hex 误填进 Passphrase 字段,还漏了一项,CLI 直接签名验证失败,报 Partial API credentials detected。

从这个坑提炼出两条可复用规范:

• 调任何资产命令前先校验三要素齐全 + 格式匹配:UUID 该是 UUID、Hex 该是定长 Hex、口令别为空。格式对不上基本就是填错了字段。
• 凭证只进 .env,代码用 os.environ 读,权限最小化:永不硬编码进代码或聊天记录;API Key 只开必要权限(能只读就别开交易权限)。

顺带一个高频运行时坑:查历史订单容易触发 HTTP 429 限流。解法是只查当前有效数据(如 --state live 的在途订单),别拉全量历史——既避限流,也让回传数据量可控(呼应第 09/11 篇"永不全量注入")。

4. 算得全:资产盲区——现货只是冰山一角

最隐蔽的错不是报错,是**"算出来了但算少了"**。一个真实数字:某账户 account balance(现货)只显示约 6k,而把理财、双币赢等模块都查全后,总资产实际约 80k——现货只占不到一成。

原因是交易所把资金分散在多个独立账户/产品里,一条现货查询命令看不到全貌:

• 现货钱包:account balance;
• 活期理财:如 earn savings balance(Binance 侧现货里还会混着 LD 前缀的 Simple Earn 活期持仓);
• 双币赢 / 结构化产品:如 earn dcd orders --state live;
• 杠杆 / 合约账户:各自独立,需分别调。

规范是:盘点资产必须遍历所有产品模块,把现货 + 理财 + 结构化 + 杠杆/合约的市值加总,再乘实时汇率折算 USD。只报现货约等于漏报九成——在金融场景,这种"沉默的少算"比报错更危险,因为它看起来是对的。

5. 防错规范:在钱面前,Agent 不许"试错"

前四节都在铺垫这一节。金融操作的防错核心,是改掉 Agent "遇到问题就自动修复"的默认反射。

最典型的一幕:凭证填错后,Agent 试图**"猜测 / 重排"密钥组合**来自动修复——把它认为填反的字段换回来。这个动作被 Claude Code 的 Credential Exploration 安全策略直接拦截。这个拦截是对的:Agent 绝不能通过试错去动敏感凭证。正确姿势是——呈现字段格式差异(这个是 UUID、那个该是 Hex),把判断权交还给人,由用户确认或提供正确值。

把这条推广成一组金融防错规范:

• 凭证不试错:密钥/私钥错了,只呈现差异、提示用户,绝不自动猜测重排。
• 不可逆操作先确认:下单、划转、提币这类动作,先亮出"要做什么、金额多少、到哪个地址",等人明确点头再执行——绝不默认自动权限一路放行(呼应第 06 篇护栏)。
• 只读优先:资产盘点这类查询,用只读权限的 Key 就够;交易权限按需、临时、最小化开。
• 金额与地址二次核对:任何带金额/地址的操作,把关键字段单独复述一遍让用户核对,防止小数点、单位、地址串位。

6. 可复用要点

• 三道门槛递增:接得上(独立环境包装 SDK,PEP 668 用 venv)→ 算得全(遍历所有产品模块)→ 不闯祸(防错规范兜底),难度和重要性都往后走。
• CLI 包装 + 确切命令:交易所 SDK 封成稳定 CLI,SKILL.md 给可复制粘贴的确切命令;调试先跑通底层 CLI 再查 Agent。
• 凭证三要素校验:调命令前查齐全 + 格式匹配(UUID/Hex/口令);只进 .env、os.environ 读、权限最小化;查历史用 --state live 避 429。
• 资产盲区:现货只是冰山一角,必须加总理财/结构化/杠杆/合约再折 USD,只报现货可能漏报九成。
• 在钱面前不试错:凭证错只呈现差异等人确认(Credential Exploration 会拦自动猜测);不可逆操作先亮金额地址、二次核对,只读优先。

---

7. Agent 可直接解析的元数据块

{
  "_meta": {
    "doc_version": "2026-07-28",
    "article_id": "claude-code-12-trading-ops",
    "profile_context": "trading",
    "estimated_setup_time": "45min"
  },
  "playbook": {
    "install": "交易所 SDK 用独立 venv 隔离;PEP 668 报 externally-managed 时优先 venv,受限才 --break-system-packages;封成稳定 CLI 只暴露 CLI 调用面",
    "credentials": "调资产命令前校验三要素齐全+格式(如 UUID key / 定长 Hex secret / 自定义 passphrase);只进 .env,os.environ 读,权限最小化",
    "full_inventory": "遍历所有产品模块:现货 account balance + 理财 earn savings + 结构化 earn dcd(--state live)+ 杠杆/合约,各市值加总再乘实时汇率折 USD",
    "rate_limit": "查历史订单易触发 HTTP 429,只查当前有效数据(--state live),别拉全量历史"
  },
  "safety_rules": [
    "凭证/私钥填错时绝不自动猜测重排(Credential Exploration 策略会拦截),只呈现字段格式差异(UUID vs Hex),交用户确认",
    "不可逆金融操作(下单/划转/提币)先亮出'做什么/金额/地址'等人明确确认,绝不靠自动权限一路放行",
    "资产盘点用只读权限 Key 即可;交易权限按需、临时、最小化开启",
    "任何带金额/地址的操作把关键字段单独复述让用户二次核对,防小数点/单位/地址串位",
    "API Key/Secret 永不硬编码进代码或聊天记录,只写 .env"
  ],
  "verification": {
    "check_1": "认证失败(Partial credentials/签名错)先按格式核对三要素是否填反字段:UUID 该在 key、定长 Hex 该在 secret",
    "check_2": "资产总额明显偏低时,回查是否只算了现货,补齐理财/结构化/杠杆/合约模块再加总",
    "check_3": "调用交易所功能失败先在终端直接跑通底层 CLI(工具/认证/权限),再排查 Agent 技能路由;SKILL.md 要给可复制粘贴的确切命令"
  }
}

AI Agent 使用指南：

• 当用户说"帮我装一下某交易所的 SDK/CLI" → 按 playbook.install,独立 venv 隔离,PEP 668 优先 venv。
• 当用户说"查一下我在某交易所的资产" → 按 playbook.full_inventory 遍历所有产品模块加总,别只报现货;历史数据用 --state live 避 429。
• 当用户说"认证失败/连不上" → 按 verification.check_1 核对三要素格式是否填反,playbook.credentials 校验齐全。
• 当凭证疑似填错 → 按 safety_rules,绝不自动猜测重排,呈现格式差异等用户确认。
• 当用户让 Agent 下单/划转/提币 → 按 safety_rules,先亮金额地址、二次核对、等明确确认,只读优先。

上一篇：Claude Code 实战 11｜Agent 当"运维值班员"：多云资产 / DBA / 监控巡检复盘 下一篇：Claude Code 实战 13（撰写中）