13 min read

实操记录:用 Claude Code 一晚上把 IBKR API Client 重构成 TypeScript

Source: http://x.com/i/article/2033036583763587077

起因

OpenAlice 是一个 TypeScript 工程。

现在主流的 Agent SDK 框架——Claude Agent SDK,OpenClaw,Vercel AI SDK——基本都是 TypeScript 生态。 甚至 Claude Code 本身就是拿 TypeScript 写的。

我们从第一天就选了 TS,因为 AI agent 这个领域,基本就只能选 TS 和 Python。而Alice 是个大软件,需要前后端一把梭,那就只能选 TS 了。

但 IBKR 的 TWS SDK 只提供 Java、C++ 和 Python 版本。AI 说提供过 C#版本我没找到,但不重要了。

社区有一个 TS 的包,思路和完成度都一般,而且很久没更新了。——说到底,我不敢用。那玩意连个文档都没有,而且还是人手写的,鬼知道里面到底有什么问题。

所以只剩一条路:自己用 TypeScript 重写一个。

SDK: https://github.com/TraderAlice/OpenAlice/tree/master/packages/ibkr Repo: https://github.com/TraderAlice/OpenAlice ## 再生产:已经干过一次了

这不是我们第一次面对"关键组件是 Python 写的"这个问题。

之前 OpenAlice 用 OpenBB 当数据源。OpenBB 是 Python 的,结果我们不得不单独起一个 Python 进程来跑它。

这意味着:用户每次启动 Alice,除了 Alice 本身,还得等一个 Python 环境起来。在此之前还得配一遍 Python 环境。配 Python 环境有多讨厌我已经在上一篇骂过了,这里就不

对于一个追求"开箱即用"的产品来说,这种体验是不可接受的。

Image

所以我们当时就把 OpenBB 需要的部分重构成了 TypeScript 版本,把 Python 进程彻底干掉了。

现在 IBKR TWS API Client 的问题本质上一模一样。老活新整。

为什么不用官方的 REST API

IBKR 的架构是这样的:用户本地跑一个 TWS(Trader Workstation),然后外部程序通过 SDK 连上去做交易。

如果我用 Python 或者 Java 的 SDK,那就意味着:我得再起一个 Python/Java 进程 → 这个进程连到 TWS → 然后这个进程再开一个端口出来 → Alice 用 RESTful 跟这个端口通信。

Image

中间多了一层完全没必要的进程和端口转换。这跟脱裤子放屁一样,还会丢类型,还需要单独做一遍语义化工作。我肯定不这么干。

IBKR 也提供了一个类似 Alpaca 风格的 RESTful API,但有两个问题:

第一,功能不全。 很多 TWS SDK 能做的事,REST API 做不了。就算大部分功能能做,也一定有做不了的功能,未来扩展压力会非常大。

第二,我们在 Alpaca 上已经吃过亏了: 1. Alpaca 用 RESTful 连云端,它会断。

  1. 断了之后,不到下一次请求你根本不知道它断了。
  2. Keep-alive 的处理非常烦,你得自己做一套心跳和重连逻辑。

一个本地已经在跑的 TWS 实例,用 Socket 直连,比任何 REST 方案都稳定。所以我们的选择很明确:直接用 TypeScript 实现 TWS 的 Socket 协议。

产品愿景:挂机小精灵

还有一个决定性的原因:其实我觉得 IBKR 的 TWS 前端做得挺好的。

Image

我们理想中的使用场景是这样的:

用户已经在跑 IBKR 的 TWS,用它做专业分析和手动交易。Alice 挂在后台,像一个游戏里的挂机小精灵,帮你盯盘、做策略执行、处理那些你不想盯着屏幕做的事情。

TWS 是你的主操作台,Alice 是你的自动辅助。两者通过本地 Socket 直连,零延迟、零中间层。

这也是为什么倾向于鼓励用户在本地开一个 IBKR, 哪怕是模拟盘——我们想做一个能和任何专业工具共存的 AI 层。

其实就跟 AI 桌宠、AI 陪玩差不多啦。我连玩游戏都要开挂机精灵,更别说做交易了。

先做调研:三个官方实现

决定自己写之后,第一步不是上来就让 AI 开干,而是先去 IBKR 官网把三个官方 SDK 的包体全都下下来看了一遍——Java、C++、Python。

社区里虽然有一个 TypeScript 的重构包,但它有个根本性的问题:它是纯靠人工对着 Java 版本逐行翻译的。而实际上在 IBKR 的体系里,Java 版是最早的实现,代码相当陈旧。

后来官方用 Python 重写的那个版本,结构清晰得多,抽象层次也更合理。

所以我们做了一个判断:照 Python 版来写,不照 Java 版。

Image

社区那个包因此也就没法参考了——它的翻译源头就不对。

还有一个更重要的原因:我们对外部维护的东西不信任。

像 TWS API Client SDK 这种复杂度的东西,如果自己对每一行代码没有百分之百的把握,后续的维护就是灾难。

社区包万一不更新了、文档写得太糊了、有个边界情况没处理——这些风险全是Alice的。

而且说到底我对人类写的代码信任度也没那么高。我自己写个一两千行都要吐血了,我觉得任何一个对着 IBKR TWS API 写翻译的人都会吐血的,难免有质量下降。

就算拉屎也得是我们自己拉的,这样才能自己擦。

深入工程:Peterffy 的屎山

把 Python 版的包体拉下来之后,真正进到工程里看,才发现它比表面复杂。

IBKR 最早的前后端通信用的是一种纯位置编码的消息流。乍一看你会觉得它的理念跟 FIX(Financial Information eXchange)有点像——都是用字符串来传结构化的金融数据。

但仔细看就会发现,它跟 FIX 有一个根本性的区别。

FIX 协议的消息是自编码的:每个字段前面都带着自己的索引号(tag),后面跟着值。比如 35=D 表示"第 35 号字段的值是 D"。

你不需要知道这个字段在消息里排第几个,tag 本身就告诉你它是什么。这意味着字段的顺序可以变、可以缺省、可以扩展——解析器只需要读 tag 就行。

IBKR 的消息流把这个自编码给抠掉了。字段的含义完全由位置决定。

你读一条消息的字符串,第 1 个字段是什么、第 2 个字段是什么、第 N 个字段是什么——全靠数位置来定。没有 tag,没有标签,纯靠 index。

这个设计决策在当时看起来可能是"简化"——少传几个字节,解析快一点。但它犯了一个协议设计里最致命的错误:没有意识到位置自编码到底有多重要。

后果就是:极其难以扩展。

一旦要在中间加一个字段,或者某个字段在某个版本里变成可选的,整个解析逻辑就会变得极其脆弱。

要维护一张巨大的"第几个位置是什么意思"的映射表,而且不同 API 版本的映射还可能不一样。写到后面,整个 SDK 的维护就变成了灾难。

这就是 Peterffy 拉的屎山。

IBKR 自己显然也意识到了这个问题,所以他们新版本的设计已经在逐步迁移到 Protobuf 来做前后端通信——Protobuf 本质上就是自编码的,每个字段都有 field number,跟 FIX 的 tag 是同一个思路。

某种意义上,他们绕了二十年,终于回到了 FIX 一开始就做对了的那个设计决策上。

在 Python 版的包体里,你能看到他们用 Proto 文件来做类型化约束——定义消息结构、字段类型、嵌套关系,然后编译成目标语言的代码。

这就产生了一个具体的技术问题:怎么把这些 Proto 定义编译成 TypeScript 代码?

我对 Protobuf 的工程细节不算特别熟,Proto 文件的编译配置、TypeScript 代码生成的选型(protobuf-ts?ts-proto?buf?)、生成代码的风格和集成方式——这些具体的事情,就是让 Claude Code 去处理的。

实操中的坑:七八千行的大文件和 AI 的理解极限

说完大框架,说说实际动手时遇到的问题。

IBKR 的 Python SDK 很明显是人写的——这听起来像废话,但它直接决定了代码的组织方式。

对于这种字段多、结构重复、写法非常标准化的东西,人类工程师更倾向于把它们全维护在一个文件里。结果就是那个 SDK 动不动一个文件就有五六千行、七八千行。

这种规模对 AI 的理解来说是灾难性的。

Image

别说 AI 了,就我们自己写软件到现在,七八千行的单文件我也维护不了。

所以第一步,我们没有直接让 AI 对着大文件开翻译,而是先把大文件拆小——按功能模块做单文件的小重构,让每个文件实现各自的功能,再统一导出。

这步看起来不大,但它对后面整个 AI 开发进程的加速作用是巨大的。拆完之后,AI 每次只需要理解一个几百行的小模块,而不是在七千行的上下文里迷路。

核心方法论:自上而下 + 测试驱动

拆完文件之后,第二个关键问题是:怎么确保 AI 写出来的东西是"正确的产物",而不仅仅是"能跑的代码"。

这两个东西的区别非常大。

AI 写代码有一个非常常见的倾向:当它发现缺少字段或类型不匹配时,它不会停下来告诉你"这里有问题",而是会用启发式的方式把问题"糊弄"过去。具体表现比如:

随便打个占位符。 缺一个字段,塞个默认值。类型对不上,加个 as any。

抹掉关键逻辑。 某个分支处理起来太复杂?直接简化掉,或者用一个简单的 fallback 替代。

在当前上下文里,这样改动可能看上去无所谓——代码能跑,测试能过。

但当你换一个新窗口、让另一个 AI 来接手时,这种代码就变成了地雷:你不知道哪些地方是"故意这么写的",哪些地方是"AI 偷懒糊弄的",而且完全无法追溯。

所以我们需要一种方法论来约束 AI 的行为。

Image

IBKR 官方写代码的逻辑是自上而下的:先有一个最原始版本的 Java SDK,然后对照这个版本,自上而下地翻译成 Python、C++ 等其他语言。这是最正统的写法——每一行代码都有对应的"原版",每一个行为都有可追溯的来源。

我们的重构也应当遵循这种思路:自上而下地对照原版构建,而不是让 AI 启发式地自下而上探索。

那种"一边摸索一边写"的方式,在错误边界处理、异常分支覆盖这些地方都会留下巨大的隐患。

确定了这个原则之后,具体的执行流程就变得很清晰了:

第一步:测试驱动开发(TDD)。

官方给出的测试案例虽然不算多,但至少是有的。先把测试搬过来,让 AI 知道"正确的输出长什么样"。

第二步:从测试文件自上而下,把功能按照原版一个一个搬过来。

不是让 AI 自由发挥,而是给它明确的参照——Python 版的实现就是 spec,照着翻译。

第三步:在搬的过程中,把大文件拆成小模块。

翻译和重构同步进行,而不是先翻译完再重构。

这三步循环下来,最终就一步一步把整个重构做完了。

这个方法论其实不仅适用于 IBKR TWS 的重构,它适用于所有"用 AI 做大型代码翻译/重构"的场景:给 AI 明确的参照源、明确的验证标准、小颗粒度的工作单元。

回顾一下这个决策链:

  • Agent 生态是 TypeScript 的 → 所以 OpenAlice 是 TypeScript 工程
  • IBKR 官方不提供 TS SDK → 社区的包不行 → 只能自己写
  • Python/Java 桥接方案是脱裤子放屁 → 多一层进程和端口 → 不干
  • REST API 功能不全,而且我们被 Alpaca 的断连坑过 → 要用本地 Socket 直连
  • TWS 前端本身很好 → Alice 不取代它,而是当挂机小精灵
  • Claude Code 一晚上搞定 → AI 处理边界清晰的重构任务,效率碾压

一步步走上了折磨自己和 AI 的路上,当然啦,我觉得这么做也是对的。

对于 OpenAlice 来说,这意味着我们离"真正的一键启动、本地运行、全 TypeScript 栈"又近了一步。

clone 下来,跑一个命令,Alice 就开始工作了。不需要 Python 环境,不需要 Java 运行时,不需要额外的端口桥接。

以上。希望能对大家做代码工作有一些参考,也希望 OpenAlice 能在开箱即用的路上越走越远。