PMXT Sidecar 架构完整拆解一个Node.js进程如何让Python和TypeScript SDK零重复接入所有预测市场交易所【免费下载链接】pmxtCCXT for prediction markets. PMXT is a unified API for trading on Polymarket, Kalshi, and more.项目地址: https://gitcode.com/gh_mirrors/pm/pmxtPMXT是一个预测市场领域的统一 API自称ccxt for prediction markets用一个接口聚合 Polymarket、Kalshi、Limitless 等十几个交易所的数据与交易能力。它的核心架构是一个Sidecar伴生服务模式Python 与 TypeScript 两套 SDK 都不自己实现任何交易所逻辑而是自动拉起同一个 Node.js 进程pmxt-core把请求转发给它。本文从源码层面完整拆解这套架构——为什么这样做、锁文件如何协调多语言、又是如何做到零重复的。一、Sidecar 架构的核心思路 传统做法是每个语言 SDK 各自适配一遍交易所N 个交易所 × M 种语言 N×M 份适配代码维护成本随两个维度同时爆炸。PMXT 的解法是把矩阵压扁Python SDK ─┐ ├─→ pmxt-coreNode.js Sidecar 进程localhost:3847─→ Polymarket / Kalshi / Limitless / … TypeScript SDK ┘交易所适配只写一遍所有适配、鉴权、签名、行情归一化都封装在 Node.js 的 core/src/exchanges/ 中13 个交易所各有一个独立模块SDK 退化成进程管家 HTTP 客户端Python 侧的管家是 sdks/python/pmxt/server_manager.pyTypeScript 侧是 sdks/typescript/pmxt/server-manager.ts两者的逻辑几乎逐行同构SDK 代码大部分由 OpenAPI 规范自动生成pmxt-core以 core/src/server/openapi.yaml 为唯一事实来源generate:sdk:python与generate:sdk:typescript两个脚本见 core/package.json直接生成客户端。规范一改两种语言的 SDK 同步更新这是零重复的根基。组件位置职责pmxt-corecore/src/server/index.tsNode.js Sidecar 进程本体交易所适配层core/src/exchanges/各交易所 API / 签名 / 归一化Python ServerManagersdks/python/pmxt/server_manager.py拉起并监督 SidecarPython 侧TS ServerManagersdks/typescript/pmxt/server-manager.ts拉起并监督 SidecarTS 侧锁文件~/.pmxt/server.lock跨进程、跨语言的共享状态契约二、从 SDK 调用到交易所 API 的完整链路 以第一次调用为例整个启动过程完全自动用户代码里看不到任何起服务的动作探测存活SDK 读取锁文件~/.pmxt/server.lock拿到pid和port验证进程是否还活着并向http://localhost:{port}/health发健康检查查找启动器按包内捆绑 仓库本地开发路径 系统 PATH的优先级寻找pmxt-ensure-server启动器Python 侧逻辑见 server_manager.py#L399-L453拉起 Sidecar调用启动器pmxt-core进程以独立子进程方式启动TypeScript 侧用detached unref让 Sidecar 与 SDK 进程解耦见 server-manager.ts#L218-L232健康检查等待轮询/health直到返回status: ok超时默认 10 秒则抛出明确错误。Sidecar 本体启动时做了两件关键的事见 core/src/server/index.ts#L45-L54端口探测默认从 3847 开始探测可用端口最多向后尝试 100 个避免与本机其他进程冲突。实现见 core/src/server/utils/port-manager.ts写锁文件把port、pid、accessToken、version、timestamp写入锁文件然后才监听端口。注意顺序先写锁、后监听。这保证任何读到锁文件的 SDK都能拿到正确的端口和访问令牌不会打到陌生服务上。三、锁文件跨语言零重复的共享内存 Python 和 Node.js 是两个完全独立的进程怎么共享状态PMXT 的答案是一个 JSON 锁文件由 core/src/server/utils/lock-file.ts 维护{ port: 3847, pid: 12345, accessToken: uuid, version: 2.17.1, timestamp: 1750000000000 }port实际监听端口可能与默认值不同因为发生过端口探测pid进程号SDK 用它做进程是否还活着的跨平台检测accessToken随机生成的访问令牌SDK 之后每个请求都携带它防止本机其他进程误操作你的 Sidecarversion用于版本漂移检测下文展开。LockFile类只有 76 行却定义了整条通用模式读取 → 验证 pid 存活 → 清理失效锁 → 返回状态。Python 与 TypeScript 的 ServerManager 都是按这份契约实现的sdks/python/pmxt/server_manager.py 文件头注释直说了这一点——This pattern implemented here is universal and can be replicated in any language SDK。也就是说未来加 Go、Java SDK只需要再写一个 ServerManager 生成的 HTTP 客户端交易所逻辑一行不用动。四、并发、版本漂移与孤儿进程的工程细节 ⚙️真正决定架构质量的是对三类脏现场的处理。1. 并发启动竞态同时创建 5 个交易所实例5 个 ServerManager 可能同时判定没有 Sidecar并各自拉起一个进程锁文件被最后写入者覆盖先拿到 base URL 的实例全部 401。两边的解法本质相同、实现各取所长Python 用类级threading.Lock串行化ensure_server_running()并在锁内二次检查存活状态server_manager.py#L40-L54TypeScript 用进程级共享 Promise合并并发调用所有调用方 await 同一个启动中Promiseserver-manager.ts#L35-L56。源码注释详细记录了不加锁时每个实例拿到不同 base URL → 全量 401的故障现场这是非常典型的 sidecar 竞态教训。2. 版本漂移SDK 升级后自动换服务锁文件里的version与本机安装的pmxt-core版本比对不一致就杀掉旧进程重新拉起Python 侧 server_manager.py#L119-L159。比对只比major.minor.patch允许1.0.0与开发态的1.0.0-b4共存。开发模式下服务端版本还会附带代码时间戳哈希改完代码重启 SDK 即可让 Sidecar 热重载。3. 孤儿进程清理Python 进程直接退出比如kill -9时detach 出来的 Sidecar 会变成孤儿霸占端口。SDK 在拉起新 Sidecar 之前会用pgrep -f pmxt.*bundled.js清扫孤儿server_manager.py#L258-L297正常退出则靠SIGTERM优雅关闭并删除锁文件core/src/server/index.ts#L62-L80。五、这套架构给 SDK 作者留下的启发 PMXT Sidecar 架构可以浓缩为三个可复用的设计决策重逻辑集中在单一运行时进程交易所 API 的签名、归一化、WebSocket 等脏活累活只在 Node.js 里写一遍新语言 SDK 的成本从实现 N 个交易所降为实现一个进程管家锁文件即跨语言契约port pid token version四个字段就把进程发现、鉴权、版本管理全部解决了比 IPC/IPC 库简单得多且天然支持Sidecar 先于 SDK 独立运行把竞态当成一等公民并发启动、版本漂移、孤儿进程这三类问题在源码里都有显式的锁、版本比对与清扫逻辑而不是留给用户在 issue 里踩坑。对只想用它的开发者这套机制则意味着零心智负担pip install pmxt或npm install pmxtjs之后直接构造交易所客户端首次调用自动完成 Sidecar 拉起后续调用复用同一进程生命周期管理start/stop/restart/status/logs也可随时手动介入官方文档见 docs/sdk/server.mdx 与 docs/guides/self-hosted.mdx。【免费下载链接】pmxtCCXT for prediction markets. PMXT is a unified API for trading on Polymarket, Kalshi, and more.项目地址: https://gitcode.com/gh_mirrors/pm/pmxt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考