Python接入美股本地数据从中概股列表到行情与F10的完整管道
最近把研究环境里美股这一块补齐了。起因很简单：A股的本地数据管道我已经跑了大半年，数据以 JSON 文本文件落在本地磁盘，程序直接读文件，批处理脚本从不担心限流和并发限制，用得很顺手。但每次看中概股都要切回网页查资料，行情一个地方、财报一个地方，体验割裂得难受。这次干脆把美股也纳入同一套环境，从代码清单、实时行情、历史K线到 F10 基本面，一次性把管道铺完。数据源用的是本地数据引擎 ig50，它的美股数据和A股共用同一套落盘思路，所以我基本是用迁移的思路在做这件事。
先说结论：美股管道和A股管道八成是同构的，真正要花心思的只有三件事——代码怎么组织、时区怎么对齐、增量怎么合并。下面按我实际搭建的顺序分六步讲。
第一步，先把代码清单固定下来。美股列表接口是base/gpus，一次拿全，大约1.3万只，字段很简单：dm是股票代码，TSLA、BABA 这种字母写法，mc是股票名称。这里有个小坑：字母代码里偶尔出现带点、带横杠的写法，直接拿去做文件名会出问题。我在落盘前做了一层字符替换，把非字母数字字符统一映射成下划线，清单里另存一列原始代码做映射表，读数据时再还原回来。中概股在这个体系里不需要任何特殊处理，它们就是美股清单里的普通成员，我用mc里的中文公司名做关键词筛出中概股子集，单独维护一张关注表，比预想的省事。
第二步，设计落盘目录，把美股和A股物理隔离。目录按 base/time/us 三层分：base/放低频的列表类数据，time/放按时间滚动的高频数据，美股的实时、历史、F10 再挂到us/子树下。代码层面统一加us_前缀，比如阿里巴巴的落盘标识是us_BABA，与sh600519这类A股代码永远不会撞车。这样做最大的好处是后处理脚本可以放心按前缀分发，不用在逻辑里到处判断市场归属。目录建好之后我补了一个清单核对脚本，定期比对base/gpus的最新快照和本地目录的差集，新上市公司第一时间补目录，退市的做归档标记但不删除，保留历史研究的完整上下文。
第三步，接实时行情。接口是time/us/real/us_{代码}，每只股票一个文件，3秒落盘一次。字段沿用我熟悉的简写体系：cjsj成交时间、cjjg成交价格、cjl成交量、jyzd交易方向（0中性、1买入、2卖出），资金面看zlJlr主力净流入，L2 指标是ddx、ddy、ddz。3秒级文件的写入频率不低，我的策略是行情文件只追加不修改，按交易日切文件，收盘后把当天文件压缩归档。这样哪怕脚本半夜崩掉，已落盘的数据也是完整的，恢复成本几乎为零。行情文件的命名我把交易日编进去，目录里按文件名排序就是时间线，排查断点时肉眼一扫就能定位到具体某天。日内复盘时我把zlJlr的分时曲线和cjjg叠在一张图上看，主力资金的进出节点一目了然，这是我从A股管道里直接搬过来的老习惯。
第四步，补历史K线。接口是time/us/history/trade/us_{代码}/{级别}，级别按需选，分钟和日线我都建了目录，分析时按粒度加载。量级先给大家一个体感：单只股票的全量K线大约几MB，1.3万只全量建仓是几十GB的盘子，一次性灌完可以接受，之后每天增量补尾部即可。增量规则我统一定为只补缺口：读现有文件的最后一条时间戳，从那之后追加新数据，绝不整段重写，既省磁盘也省时间，回测取数时再按日期范围切片。级别取舍上我的经验是：做事件研究用日线足够，做执行层面的观察才需要分钟级，不必一上来就全级别建仓，先把日线灌满、分钟按需补，能省下不少初期时间。
第五步，铺 F10 层，这是美股和A股信息差异最大的部分。F10 全部挂在time/us/f10/下，我用到九张表：orgprofile公司资料、maincompose主营构成、income利润表、balance资产负债表、cashflow现金流量表、executive高管研究、dividend分红派息、gsds大事提醒，以及研究中概股绕不开的short卖空明细。每张表按公司代码分文件，一表一个 JSON。我自己的常用组合是：用maincompose拆收入结构，把income和cashflow拼起来看利润的现金含量，财报季前后用gsds做事件核对，executive用来查管理层变动，short表则盯卖空量的异动。orgprofile虽然只是一页公司资料，但上市地、主营业务、行业归类都在本地，做批量打标签时比翻网页快得多；balance我主要看商誉和有息负债两个科目，中概股的问题不少埋在这两处。这些表后续做复权也用得上，dividend里的分红派息就是公司行动的原始素材，这也是我把 F10 和行情放在同一套目录体系下的原因。
第六步，收尾：时区对齐和加载函数定型。美股数据的更新节奏是美东时间：列表每天0点更新，F10 每天18:00更新，落盘时间和北京时间差12小时。我把所有时间字段统一转成北京时间入库，另存一列原始美东时间做对账，后来夏令时切换那两天，就是靠这列原始时间排掉了两个"数据迟到了一小时"的假警报。增量策略最终定成两条：行情文件追加、F10 整文件覆盖——F10 单表不大，覆盖最简单，而且天然幂等，重跑不会产生脏数据。pandas 的加载函数我没有做得花哨：入口参数是代码加数据类别，内部按目录约定拼出路径，读入后把dm、mc这些字段名映射成可读列名，再留一个按日期范围过滤的参数。全市场批量分析就是循环调用加 concat，1.3万只的列表类数据秒级载入，体验和读A股完全一致。
管道跑了两周，最大的感受是：美股不是另一套系统，只是同一套本地化思路换了命名空间。把清单、目录、增量策略这三件事先定死，剩下的就是安心灌数据。
接口说明
base/gpus：美股股票列表，约1.3万只，字段dm（股票代码，如 TSLA）、mc（股票名称）。
time/us/real/us_{代码}：美股实时行情，3秒落盘，字段cjsj（成交时间）、cjjg（成交价格）、cjl（成交量）、jyzd（交易方向，0中性/1买入/2卖出）、zlJlr（主力净流入）、ddx/ddy/ddz（L2指标）。
time/us/history/trade/us_{代码}/{级别}：美股历史K线，级别自选，单只全量约几MB。
time/us/f10/下的九张表：orgprofile公司资料、maincompose主营构成、income利润表、balance资产负债表、cashflow现金流量表、executive高管研究、dividend分红派息、gsds大事提醒、short卖空明细。
资料参考：ig50
gitee开源地址
github开源地址
