产品方向与边界¶
CNEquity 面向希望自行管理中国市场研究数据的用户：在本地持续采集，使用统一的数据口径查询，并能发现缺口、追溯来源和恢复失败任务。项目方向与功能范围由维护者统一规划；用户可以通过 Issue 反馈场景、问题与建议。
核心能力¶
- 本地数据湖：用 Parquet 保存数据，通过 Python、DuckDB、Polars、控制台或只读 MCP 读取。
- 持续更新：初始化、日更、事件采集和历史回填使用明确的配置与范围。
- 质量可见：来源、单位、覆盖范围与失败状态可检查；新鲜度不等于历史完整。
- 版本可追溯：修正通过新数据版本发布；需要长期复现时保存研究快照、查询参数与软件版本。
使用前应了解的边界¶
安装不附带市场数据，采集依赖上游可用性和授权。可选凭证来源需要自行配置。当前支持范围见数据集目录与数据源限制。
历史回填不能证明数据在过去已被观察到。严格研究应显式选择 PIT、股票池与复权校验；证据不足可能导致查询拒绝返回。见查询指南。
数据集分别发布，不提供整个湖的跨表原子事务。固定版本读取、版本保留与快照的边界见Python API。
从哪里开始¶
快速开始 → 初始化与续跑 → 运行手册。遇到问题先按故障排查定位失败范围。
是否适合我¶
CNEquity 适合持续积累、反复查询和复查历史口径的数据工作。选择时先判断你需要一次取数、长期数据层，还是研究与交易应用。
按工作方式选择¶
| 需求 | 合适的工作方式 | CNEquity 在其中的位置 |
|---|---|---|
| 偶尔取一个报价或一张表 | 直接使用所需来源的 API 或取数库 | 建湖成本可能超过收益 |
| 同一份历史数据反复用于多个研究 | 本地持久存储、增量采集、版本与质量检查 | 这是项目的主要用途 |
| 获取有明确授权或服务承诺的数据 | 按供应商合同选择数据服务 | 公共来源采集不能替代授权或 SLA |
| 做模型训练、回测或交易执行 | 使用相应研究 / 交易框架 | 湖可作为其输入；集成与策略逻辑由下游负责 |
| 让 agent 查询历史数据 | 先准备数据与证据，再暴露只读工具 | cne mcp 提供只读工具（stdio 或 HTTP） |
AkShare、efinance、Tushare、Baostock、Qlib、vn.py 等名字常出现在这些工作流中；这里不对它们的当前功能、价格或授权做静态评分。选择时以相应项目和服务的实际接口、版本与条款为准。与 AKShare、Tushare 在工作方式上的区别和配合用法见对比说明。
CNEquity 已负责什么¶
- 统一数据集、主键、单位与来源列，落地为开放 Parquet。
- 按批次采集、维护水位、保留失败范围并支持续跑。
- 对候选数据和已发布数据分别提供质量检查，发布新 revision 保留修订证据。
- 提供复权、历史股票池与 PIT 查询语义；严格模式显式暴露缺口。
- 提供 Python / SQL、控制台和 MCP 入口。回环地址上的控制台可以预览并启动白名单内的初始化、日更、补抓、巡检和备份；MCP 仍然只读。
使用成本与边界¶
需要自己承担磁盘、运行调度和上游可达性。快照数据只能从启用后积累；历史回填不自动具备严格 PIT 证据。版本保留有上限，长期重现需保存快照、依赖与软件版本。
项目不提供托管行情、回测引擎、交易信号或下单。代码许可不授予上游数据再分发权，见数据许可。