rootsunc/cnequity

CNEquity · 中国市场金融数据基础设施 面向中国市场的开源数据底座，从 A 股开始，为人和 AI agent 提供可日更、可复查的历史

开源、免注册、自托管。一次采集，支持持续日更；用 Python、DuckDB、Polars 或 AI agent 访问同一份数据。 42 个注册数据集 · L0–L8 九类研究数据 · 复权 / 历史股票池 / PIT · 行级溯源 · MCP

上图是用于 README 的演示图，不代表当前生产数据状态。真实控制台只读，不会修改数据湖。

CNEquity 把分散在多个来源的行情、基本面、事件、资金、行业与宏观数据，沉淀为开放格式的本地数据层。当前从 A 股出发，但产品边界不止于一次取数或单一市场：同一套采集、质量、溯源和研究契约，可以继续承载更多中国市场数据。

架构

公开数据源 → 适配与编排 → 本地 Parquet 湖 → 质量、查询与只读服务

核心边界：适配器负责把多源数据取回来；编排层负责 DAG、批次和重试；数据先进入 staging，再压实为 curated 并计算 derived；质量层持续审计；查询和服务层只读消费。展开见架构说明。

先看它是否适合你

CNEquity 不是又一个”临时请求一次行情”的接口。它更适合这些场景：

• 你要反复研究多年行情，不想每次重拉、清洗和拼复权；
• 你在意退市股、历史成分股和 PIT，不能接受不知不觉使用未来数据；
• 你希望数据保存在自己电脑或服务器上，格式开放、来源可追溯；
• 你想给 Python 研究代码、DuckDB、Polars 或 AI agent 共用同一份数据。

如果只想查一只股票的最新价格，直接取数通常更轻；如果要做可复查的历史研究，这个项目才真正有价值。

第一次使用，按这条路径即可：

cne demo → cne init → cne run daily → load() / cne serve → cne mcp（可选）

30 秒跑通

需要 Python 3.10+，无需 token、积分或账号：

pip install cnequity
cne demo

cne demo 默认拉取 5 只股票最近约 30 个交易日的真实数据，写入独立目录 data/cnequity-demo/，不会覆盖正式数据湖。需要能访问 TDX 行情主机；若连接失败，先检查：

cne sources --only tdx_protocol

然后在 Python 中读取：

from cnequity.query import load

bars = load("daily_bars", data_root="data/cnequity-demo")
print(bars.tail())

想直接比较原始价格与后复权口径：

cne demo --research --symbols 600519.SH

5 分钟开始建湖

pip install cnequity
cne config init            # 生成 configs/cnequity.toml
cne init                   # 全市场标的，默认回溯最近 3 年
cne run daily              # 之后每个交易日执行这一条

默认策略是“浅而不窄”：历史先取最近 3 年，但全市场标的一个不缺。这样不会因为只保留今天仍上市的股票，提前把幸存者偏差写进数据湖。每个数据集的真实起点会记录在 coverage_start。

需要更长历史时可以一次拉满，也可以以后补深：

cne init --profile full

# 或对单个数据集补历史
cne backfill daily_bars --start 2016-01-01 --end 

默认初始化通常是小时级、GB 级，实际取决于网络、数据源状态和机器配置。详细安装说明见快速开始和安装指南。

为什么要一个数据湖

同一个等权买入持有、同样的起止日期，唯一差别是后来退市的股票是否仍在历史股票池中。用“今天还在的股票”回看历史，2016–2021 五年收益会从 5.9% 变成 12.0%，看起来几乎翻倍。

这类错误很难从结果里发现：那些股票不是收益为零，而是根本没有进入计算。CNEquity 因此把退市股、复权因子、历史成分与 PIT 当作基础能力，而不是附加字段。

复现实验：

python scripts/survivorship_gap.py --lang zh --svg docs/assets/survivorship-gap.zh.svg

能回答哪些问题

常用查询：

from cnequity.query import load

bars = load(
    "daily_bars",
    start="2020-01-01",
    end="2025-12-31",
    symbols=["600519.SH"],
    adjust="hfq",
)

roe = load(
    "financial_statement_items",
    items=["roe"],
    as_of="2024-04-30",
)

数据范围

当前注册表包含 42 个数据集：39 个 curated + 3 个 derived。按研究用途分为 L0–L8 九类；完整字段、主键、历史模式和源端限制见数据集目录。

所有 curated 行都包含 source、data_version 和 fetched_at，可以追到来源与采集批次。分钟线、5 分钟线和分笔默认关闭，按需启用；部分只能获取当日快照的数据集不会伪造成历史序列。

日常使用与运维

cne run daily                 # 执行当天全部日更分组
cne status                    # 查看 FRESH / STALE / EMPTY
cne serve                     # 打开 http://127.0.0.1:8787
cne sources                   # 检查上游数据源健康度
cne retry --run-id    # 只重试失败批次

单个 step 失败时，系统会记录 failed batch，其他步骤继续落盘；重试不会把整条任务重新跑一遍。浏览器控制台就是 README 首图中的界面，可查看覆盖、新鲜度、容量、跑批和质量结果。

挂入 crontab 即可自动日更：

# 交易日收盘后执行；非交易日会自动跳过
30 16 * * 1-5  cd /path/to/lake && cne run daily >> logs/daily.log 2>&1

更多运维方式见运行手册、数据源健康检查和故障排查。

接给 AI agent

cne mcp 以只读方式把本地湖提供给模型；采集、重试和清理仍由 CLI 完成。

cne mcp --config "$(pwd)/configs/cnequity.toml"

把上面的命令作为 MCP server 注册到任意兼容客户端即可。大多数客户端 使用等价的配置（客户端名称和界面可能不同）：

{
  "mcpServers": {
    "cnequity": {
      "command": "cne",
      "args": ["mcp", "--config", "/abs/path/to/cnequity.toml"]
    }
  }
}

因此 Codex、Claude、Cline、Cursor、Windsurf、Gemini CLI 以及其它支持 MCP stdio 的 agent 都可以复用同一条 command / args 配置；CNEquity 不依赖任何特定模型或厂商 SDK。

--config 必须使用绝对路径。接好后可以直接问：

• “茅台过去五年复权后涨了多少？”
• “茅台当前 PE 在自己五年历史里处于什么分位？”
• “计算 2018 年财报因子的 IC，不要使用未来数据。”
• “过去三年退市的股票，退市前 60 天有什么共同形态？”

还没有正式湖时，可以先运行 cne demo，再使用生成的 demo 配置。完整说明见MCP 参考。

与 AkShare、Tushare、Qlib 有什么不同

AkShare 和取数工具解决”怎样调用数据源”，Tushare 提供云端数据服务，Qlib / vn.py 更偏研究或交易平台。CNEquity 做的是中间的数据基础设施：把多源数据落成可日更、可复查、可溯源的本地 Parquet 湖。

更完整的逐项比较见项目对比。

常见问题

文档与项目状态

• 快速开始 · CLI 参考 · 完整文档索引
• 数据集目录 · MCP 参考 · 运维手册
• ROADMAP · CHANGELOG · 贡献指南 · 安全策略

这是个人维护的开源项目，issue 和 PR 都欢迎。用于论文或研究报告时，可引用仓库中的 CITATION.cff，并记录版本、覆盖范围及复权 / PIT 口径。

代码使用 Apache-2.0。仓库不附带数据湖，也不授予上游数据的再分发权。

---

如果 CNEquity 帮你省下了搭建数据底座的时间，欢迎点个 ⭐，让更多做 A 股研究的人看到它。