Repository navigation
最低要求升到 Python 3.11 与 DuckDB 2.0,新增实验性的湖目录
CNEquity 0.24.0 已发布至 PyPI。开源 A 股本地数据湖,用于量化研究、回测与 AI Agent。
python -m pip install --upgrade cnequity==0.24.0- 升级步骤: 先确认环境是 Python 3.11 或更高,再
pip install -U cnequity,然后重启cne serve和已在运行的cne mcp。数据集的列、主键和分区都没有变,本版没有迁移要跑。extends = "builtin"的配置不用改;完整展开的旧配置运行cne config upgrade改写改过名的键,并手动把name_history从 core 组里去掉,否则日更仍会读 Tushare。升级后第一次日更会把option_greeks和minute_bars_15m/30m/60m的全部历史重算一遍,之后只重算内容变了的交易日。湖目录(lake/)是实验性的:不建它,读写与以前完全一样;[storage].publish = "catalog"对每个数据集单向生效,打开前先做快照,暂不建议用在不能重建的湖上。 - 发布进湖目录的一次运行现在只产生一个快照,并且这个快照本身就能按文件直接读取:替换某个分区时,持有这些行的数据文件整体换掉,文件里不属于该分区的行原样重写,不再留下删除记录等事后合并。此前一次发布要三个快照(写入、合并删除记录、登记历史),后两步之间中断会丢掉「修订对应哪个快照」的记录,而只存在于湖目录里的修订没有别处可读。修订所在的快照改由
_revisions表中该行自带的快照号给出,与数据同时提交。代价是重抓已有日期时变慢:真实湖克隆上重抓一天分钟线(所在月文件 2,970 万行)4.1 秒,旧写法 1.1 秒,全表内容逐行一致;新增日期的追加不受影响。 - 新增
cne storage verify-catalog [--dataset 名称]:发布进湖目录的每个修订现在随数据记下所改分区的行内容摘要(行数加逐行哈希的异或与求和,与文件布局和行顺序无关),这个命令在修订自己的快照上重算并比对,有不一致时退出 1。此前回执里的 SHA-256 只对应运行暂存的文件,湖目录入库时会重排重写,核对不了实际存储的内容。摘要用 DuckDB 的行哈希,换了 DuckDB 主次版本后记下的摘要报告为other_algorithm,不判为不一致;快照已过期的报告为expired。 cne snapshot create复制文件时不再持有湖锁:持锁期间只读取各数据集的状态、指针和回执并列出要复制的文件,放锁后再复制。代目录和原始响应存档写入后不再改动,所以复制到的仍是持锁时看到的内容;复制前后文件的大小或修改时间变了、或文件被清理掉,快照失败并提示重试。此前整个复制过程都持锁,原始存档放在网络盘上时会让日更和事件流等上几个小时。- 新增实验性开关
[storage].publish = "catalog":压缩步骤从湖目录取出本次要改的分区,合并后在一个目录事务里替换这些分区,同一次运行的数据集同一快照发布,不再写代目录。真实湖克隆上的同一次运行,两种方式发布的 8 个数据集逐行一致。默认仍为"generation"。开启后湖在meta/storage.json记下这一点,派生和修复此后也从核对过的工作目录发布进目录。 - 修复北交所涨跌幅越限检查自 11-05 起失效:
daily_bars改按月分区后,检查从分区目录名推算市场交易日,结果总是空,单日日更里每一行都被当成「前一交易日不明」而不判断。现在交易日取自交易日历。 - 新增
[sources.eastmoney].proxy_hosts:只让列出的主机(含子域名)走proxy,其余东财主机直连。可以只把 push2 留在代理上,数据中心、公告等直连可达的主机不再因代理停掉而失败。未设时与以前一样,所有东财主机都走代理。 - 日更不再读 Tushare:
name_history移出默认 core 组,sector_fund_flow在 push2 暂停时也不再改从 Tushare 取当日数据。Tushare 只用于按需补全历史(cne backfill <数据集>),令牌过期不会再让日更失败;所有以 Tushare 为主来源的数据集都不计入新鲜度。 - 新增
cne storage catalog-retention:湖目录为每个数据集保留最近的修订([storage.retention].keep_generations,默认 5 个)和被cne storage hold保护的修订,其余快照过期,不再引用的文件等 24 小时后才删除;cne run maintain每天执行。湖目录保存了创建时的绝对数据路径,搬迁、恢复或复制过的湖会去读原湖的文件,现在总是读湖目录自身目录下的文件。 option_greeks与minute_bars_15m/30m/60m判断哪些交易日要重算时,改为比较当天数据的内容摘要,不再比较分区文件和修改时间;只挪动文件、合并文件不会再触发重算。计算规则改用显式版本号,代码重构不再让全部历史重算。升级后第一次运行会重算一遍全部历史(期权希腊值约 50 分钟),之后只重算内容变了的交易日。- MCP
query_dataset和控制台行查看器的读取预算从「64 MiB Parquet」改为「400 万行」。内存随读取的行数增长,同样的行在湖目录里占的字节可以少 60%,按字节算会放过实际很大的读取。拒绝信息里的大小也改为行数。 load()的行顺序现在完全确定:仍按日期和代码排序,并列的行再按主键其余列排序。此前并列行的先后取决于文件和扫描顺序。- 新增实验性的湖目录(
lake/):cne storage sync-catalog --create把每个数据集的已发布版本复制进一个带快照的目录库,之后每次发布都会把变动的分区同步进目录,cne run maintain每天再核对一遍。建了湖目录的湖,读取在目录与所读版本一致时改从目录取数,否则照旧扫描;CNE_READ_CATALOG=0可关闭。质量检查、派生和日更步骤内部的扫描,以及cne query与 MCPrun_sql背后的 SQL 视图,也一样改读目录里的数据文件。读取结果的行内容不变。 - 不兼容变更:最低 Python 版本从 3.10 提高到 3.11,DuckDB 最低版本从 1.5 提高到 2.0。DuckDB 2.0 不再支持 Python 3.10;仍在 3.10 上的环境请先升级 Python 再升级 CNEquity。
- 修复
economic_calendar日更失败:回补过早年历史后,早年文件没有withdrawn列,日更读取时报SchemaError: extra column ... withdrawn。现在逐文件读取并按列名对齐,已标记撤回的事件不会被重复标记。 - 修复公告高峰日回补失败(#59):
announcement_index的某一桶按板块、行业、公告分类拆到底后仍超过巨潮 100 页上限时(如 2026-04-29 深市主板 + 制造业 + 日常经营,共 3024 条),不再报slice exceeded 100 pages退出,而是以默认翻页结果为底,按代码排序翻页补齐缺的行,凑齐即停;每页都要求总数与原查询一致,合并后仍按巨潮总数精确对账,对不上照样失败。超过两次翻页能读到的条数时直接报错。分区之间的缺口也改用同一逻辑补齐,并且凑齐即停,不再四种排序全部翻完。原始响应存档可重放这类补齐。 - 公告索引新增按股票分组的最后一级拆分(#59):排序翻页仍凑不齐,或一桶超过两次翻页能读到的条数时,按巨潮股票目录把当前板块的股票每 40 只分为一组查询,合并后同样按总数精确对账。巨潮在一次传入超过约 50 只股票时会忽略股票条件、返回整桶结果,因此一旦返回组外股票的公告就直接失败。股票目录里没有的股票(如早已退市的公司)会造成短缺,结果仍是失败,不会少数据入库。
- 修复安全问题:
cne serve未设--token时,只有操作页和存储页检查请求的 Host,数据接口(/api/datasets、/api/read、/rows、运行记录、质量、事件流等)和页面不检查。恶意网页可借 DNS 重绑定把自己的域名指向 127.0.0.1,以同源身份读取湖数据和运行记录。现在未设令牌时,Host 不是 localhost、127.0.0.1 或 ::1 的请求一律返回 403;在本机浏览器打开不受影响,远程访问仍需--token。 - 网页控制台(
cne serve)的操作页改版,先给出今天的状况,再给出要做的事:- 「今日」新增任务时间线,按北京时间画出今天或昨天每个任务的起止和结果,标出定时日更、收尾补抓和备份的时间;
- 新增近 14 个交易日的日更矩阵:每格是一个调度组在一个交易日的最后一次尝试,按成功、降级、失败着色,重试过的格子另有标记,点开进入那次运行;
- 落后的数据集直接列在操作页,按落后天数排列:按日期的数据集给出预填起止日期的回填,快照数据集给出补抓落后,并注明漏掉的日子补不回来;
- 「要做什么」只保留跑日更、补一段历史、补抓落后三个主按钮,其余收进「更多」;表单改在右侧抽屉里打开,不再把页面往下推,执行计划默认折叠;填写时当场检查:起点晚于终点、交易日晚于今天时不预览,给快照数据集填旧起点或终点晚于今天时给出提醒;
- 最近的任务把同一天的事件流合成一行,写明成功和部分交付的次数及常缺的数据集;日更任务写明哪些组失败或降级,收尾补抓等任务写明哪些数据集失败及原因;每条带耗时、写入行数和到运行的链接;可以按类型和「有问题」筛选。此前最近 50 条几乎全是每小时一次的事件流,日更和回填看不到;
- 「巡检」改成卡片,每项写明上次结果;命令模板和只能在终端运行的命令收进「命令参考」;
- 标签从四个合成三个:今日、巡检,以及定时、数据源与备份;今天是否交易日、定时会话有没有跑过只写在日更状态卡里,不再在操作区重复;
- 每个数据源开关旁标出今天的状态(开启、关闭、暂停、熔断或缺少密钥),写明东财各主机的今日请求数和预算,以及主源为它的数据集今天失败了几批;定时任务的检查时间改按北京时间显示;push2 暂停只在数据源状态卡里提示一次,不再在页面顶部重复。
- 新增只读接口
GET /api/runs/daily-matrix?sessions=N,返回每个日更调度组在最近 N 个交易日的最后一次尝试;GET /api/ops/jobs新增since、op、exclude_op参数,limit上限从 50 提高到 500,每个任务带上rows_written和failed_datasets;GET /api/ops的occupancy.sources增加各主机请求数、付费源是否配置了密钥(不含密钥本身)和今日按数据源统计的失败批次。 - 付费数据源(Tushare、同花顺官方接口)在取数设置里单列一组,默认关闭,可以单独开关,开关只改各自的
enabled,令牌和密钥不动。每个付费源标出是否配置了密钥和上次检测的结果(可用、有效但套餐不含检测接口、被拒绝或没有结果);「检测密钥」只发一次小请求,不改湖里的数据,结果记在meta/sources/key-checks.json,只存密钥的短摘要,换了密钥就重新算作未检测。新增接口POST /api/ops/sources/{source}/check-key,occupancy.sources.key_checks带上次检测结果。 - 只由
cne backfill采集的 Tushare 数据集不再算落后:没有打开 Tushare、没有令牌、令牌检测被拒绝,或者这个数据集没有排进日更时,概览、操作页和cne status都不再把它列为落后,也不按它的水位提示。此前默认安装也会把这些数据集算进落后。 cne serve在当天定时日更时间之前,仍按上一个交易日判断数据集是否落后;当天日更已经跑完则立即按当天判断。此前一到 15:05 就按当天判断,日更开始前的两个多小时里,所有日更数据集都显示为落后。cne status --datasets和网页控制台改用同一套规则判断数据集是否落后,结果一致。此前两边各有一份判断,已经不一致:- 源端已停更的数据集(如 2024-08-16 之后的
northbound_flows),cne status标为retired,控制台却显示「最新」。现在控制台显示「源已停更」,/api/health新增retired、removed、sample三个计数; - 样例湖(
profile = "sample")的合成数据,控制台此前按真实日期判断,现在与cne status一样标为样例数据; cne status --datasets也像控制台一样,在当天定时日更开始或完成之前按上一个交易日判断,不再在收盘后、日更前把所有日更数据集报为落后。
- 源端已停更的数据集(如 2024-08-16 之后的
cne check和cne audit改用同一条规则判断审计 error 是否不合格,同一份审计结果不再一个通过、一个失败。此前cne check不计「缺数据」一类的覆盖 error,核心数据集daily_bars缺了交易日时cne audit失败,cne check却给出「湖可用」。现在核心数据集的覆盖 error 也让cne check退出 1;核心之外数据集的 error 仍不计入cne check,但会报出条数,由cne audit列出。发布和日更的 audit 步骤仍只计数据本身有误的 error,缺数据不影响已有行。- 旧版本清理只保留一种规则:回补和日更后每个数据集保留最近
[storage.retention].keep_generations代(默认 5),更早的代当场删除;要提前删除选定的历史,仍在网页存储页勾选并确认。原先并存的「标记后等 7 天再删」已移除:自动清理会在 7 天到期前就删掉被标记的代,观察期形同虚设,已有的标记在读取登记时丢弃。- 只合并文件、行内容不变的版本(
cne storage merge-files发布的)不再占用保留名额:它夹在保留的代之间时一起保留,随它们一起过期。此前每次合并都会挤掉一个真实的历史版本; cne storage plan改为只读预览,输出keep、candidate_ids、logical_bytes_selected,--keep默认取配置值;--phase不再使用。cne storage apply已移除,调用时报错并说明替代做法。cne storage inspect --keep也默认取配置值;- 网页存储页去掉「检查到期项目」「检查待标记项目」,页头写明保留几代,超出保留代数的版本标为「下次回补或日更时删除」。此前页头写着「不自动删除」,与实际不符。
/api/storage不再返回grace_days和not_before,新增automatic_retention,keep取配置值;版本的status改为scheduled、deletable或protected,暂存的unmarked改为deletable;POST /api/storage/reviews必须带object_ids或resume_plan_id,不再接受phase: "mark"; cne run clean的 JSON 去掉总为 0 的revision_generations[].marked。
- 只合并文件、行内容不变的版本(
- 修复
cne repair valuation-outage每次运行都报错退出(AttributeError: 'tuple' object has no attribute 'split'),预览和--apply都无法使用。 cne backfill financial_statement_items --source tdx_fin --plan不再直接开始回补:此前--source tdx_fin先于--plan处理,加了--plan也会下载并写入。现在只打印起止日期和要下载的报告期。cne backfill的--source、--refetch、--workers是否可用,改由各数据集自己声明,回补命令和各个cne repair子命令共用同一处检查。行为不变,只有报错措辞变了:- 给不支持的数据集用
--source时,报错列出所有支持的数据集及其来源(含此前漏写的option_bars (tushare));给financial_statement_items或option_bars传了它们不接受的来源时,改为指出该数据集可用的来源,退出码由 1 变为 2(参数错误); --refetch不适用时列出的数据集按注册表顺序排列。
- 给不支持的数据集用
futures_continuous(期货连续合约)写入和体检时也按期货行情的规则校验:结算价必须为正,成交量和持仓量不能缺失或为负,有完整 K 线时最高、最低价必须包住开盘和收盘。此前只有futures_bars、option_bars、futures_minute_bars校验,连续合约照单全收。现有数据全部通过(41.5 万行),无需迁移。- 访问新浪的四处重试改用同一套规则:遇到限流(HTTP 429/456)先让所有新浪通道一起冷却 30 秒再重试,遇到 5xx 依次等 5 秒、10 秒再重试,最多 3 次。此前退市股历史恢复遇到限流只在本线程睡几秒就再次请求,容易招致更长的封禁;美元离岸人民币(USD/CNH)和国内期货行情遇到 5xx 则立即重试,不做等待。日线补缺在同一只股票第二次被限流时停止本次补缺的做法保持不变。
- 自行构造
DatasetSpec的代码不能再传pit和pit_grade:二者改由pit_quality推出(strict与reconstructed为点时数据集),读取这两个属性的结果不变,导出的数据集契约逐字节不变。每个数据集的支持级别、取值规则、单位和data_version也都写回各自的注册项,不再分散在按名字查找的旁表里。 - 复权因子的
stock_event_factor和fund_share_factor发现项补上了说明文字(哪只证券、哪天、因子是保留、按比例修正还是核对无误),此前没有message,在cne audit和网页控制台上显示为空行,而它们占了发现项的大多数。审计写入发现项前统一检查:严重级别只能是 error、warning、info,必须有检查名;缺说明的发现项改用检查名代替并记一条日志,不会让审计失败。 cne run maintain每天清理中断的提交留下的东西:复制中途断掉留下的临时目录、写完收据却没来得及切换指针的未发布代(收据保留,作为失败记录;人工保留的不删),并按当前指针重建对不上的状态文件;没有收据的代只列出不删。此前代码注释说这些由gc回收,但并没有这个命令。cne status --datasets新增--json:stdout 只输出一个 JSON(last_trading_day、各数据集的 freshness 等列,freshness 为小写,以及--hide-empty折叠掉的folded),之后的截面核对与门禁说明改走 stderr,退出码不变,脚本不必再解析表格。cne启动更快:读 Excel 和 PDF 的适配器改为用到时才导入 pandas 和 pypdf(连带 pyarrow),cne --help、cne status等不解析表格的命令不再为此等待。- 移除两个只做转发的内部模块:
cnequity.query.canonical改从cnequity.domain.canonical导入,cnequity.adapters.calendar.holidays_cn改从cnequity.domain.holidays_cn导入,内容不变。Config上旧的_backfill*和修复开关私有属性也已去掉,改用cnequity.run_scope的backfill_of/set_backfill和run_flags_of/set_run_flags;旧名字记录的重试范围仍能读取。 - 移除
cnequity.universe_profiles,改从cnequity.domain.universe_profiles导入(文档早已改用这个路径)。 cne config upgrade把改了名的配置项改成现名:[orchestrator] tdx_daily_executor→tdx_daily_backend,[derive] workers→[orchestrator] derive_workers,[sources.<名>]里的concurrency/max_in_flight/workers→max_concurrency;现名已经写了时旧名本来不起作用,直接删掉。旧名仍然有效,加载时提示运行cne config upgrade。- wheel 只带当前版本的数据集契约(
share/cnequity/contracts/v<版本>.json),不再附带全部历史契约,安装后少占约 3.3 MB;历史契约仍在仓库和源码包(sdist)的contracts/目录。运行时不读这些文件。 - 文档首页的覆盖范围卡片和「与同类项目对比」页把数据集数写成 55(47 个采集),已改为当前的 86(78 个采集 + 8 个派生)。README、首页、指南、对比页和运维手册里引用的数据集数今后由
scripts/dev/sync_docs.py按注册表生成,不再手改。 - 修复数据湖目录路径含
#或?时读不到运行记录:控制台、操作页任务、cne schedule、存储统计、发布门禁等以只读方式打开manifest.db时把路径直接拼进 SQLite URI,#/?之后被当成片段或参数,打开的是另一个空库,不报错只显示没有运行。现在统一按 URI 转义路径。 cnequity.query/cnequity.domain里画像函数的第二个名字get_universe_profile、list_profiles、show_profile、profile_json已弃用,使用时发出DeprecationWarning并指出替代(resolve_universe_profile、list_universe_profiles、show_universe_profile),0.25.0 移除;load(universe_profile=...)同样弃用,改用profile=...。- 交互终端里的
cne run clean在预览后还会分别询问是否删除过期运行日志(logs/cne-*.log,超过--log-retention-days)、过期来源快照(每个数据集和来源保留最新一份)和无人持有的过期运行锁文件,默认都不删。此前这三类只列出、没有任何删除途径,日志和锁文件会一直累积。预览 JSON 新增stale_run_locks.candidates。--force仍只扩大预览范围;它原有的“删除未合并 staging 并把成功批次降级”代码从未被调用,已移除。 - 移除只有测试在调用的函数:
cnequity.query.universe.tradable_symbols_on_date(研究选股请用load(..., profile=...)),以及内部的snapshot_daily_bars_backup、fetch_flash_news_wire、fetch_northbound_flows(单日版本,区间版本fetch_northbound_flows_range保留)、record_source_overrides、tradable_a_cash和四个Manifest方法。 - 存储生命周期登记表不再保存旧版本留下的
experiments、artifacts和experiment_pending:这些条目没有任何代码处理,指向的临时目录也早已不存在。下次写登记表时自动去掉;案例对artifact/对象的保留仍在,因为案例清单不可修改。快照导出的保护依赖也不再带这两个字段,旧快照照常可读;引用导入清单里的experiments不再读取。 - 移除 0.19.0 起弃用的
scripts/scheduler/(daily_pipeline.sh、install_scheduler.sh、health_notify.sh、backup_meta.sh等),打包定时任务cne schedule install已承担它的全部工作:日更、收尾补抓、事件流,以及cne run maintain的审计、门禁、源探针和元数据备份。还装着旧 launchd 任务的机器,先用launchctl bootout gui/$(id -u)/com.cnequity.daily(stale、events、events-news同理)卸载并删掉~/Library/LaunchAgents里对应的 plist,cron 里的条目手工删掉,再运行cne schedule install;cne schedule status仍会提示残留的旧任务。旧脚本的CNE_GATE_GROUPS、CNE_BACKUP_DIR、CNE_BACKUP_RETENTION_*改写成[job.maintenance]的gate_groups、backup_dir、backup_retention_days/backup_retention_count;按日重跑全部调度组用cne run daily --trade-date YYYY-MM-DD。 cne audit --full新增--universe-profile <画像名>,按cne profile list里的画像判定历史研究有效性,默认legacy_all_a,结果与原来的all_a相同;健康快照多一个historical_universe_profile。旧的--research-universe all_a|all_a_sh_sz仍可用,对应legacy_all_a/legacy_all_a_sh_sz,会提示改用新选项。load(universe="all_a")将在 0.25.0 移除,改用profile="legacy_all_a"可得到同样的行。cne config的 validate、create、show、diff、upgrade、path 改为真正的子命令,写法不变;cne config <子命令> --help只列出该子命令自己的选项。把选项写在子命令前面(如cne config --config X validate)不再有效,请写在子命令后面。- 网页控制台切换页面时,前一个页面晚到的请求不再覆盖当前页面:此前从概览打开操作页,地址栏停在操作页,内容却会被加载较慢的概览替换。
- 期货和期权行情的成交量、持仓量、持仓变化、成交额单元格为空时,不再读成 0:各交易所文件和新浪接口都用 0 表示没有成交或持仓,空单元格是损坏的数据。此前空成交量会让一个有成交的合约被存成无成交行,价格被清空。现在空值保持为空,成交量或持仓量为空的行按行隔离并报
futures_row_rejected警告,同一交易日的其他合约照常写入。已有数据不需要迁移:正常文件里不会出现空的计数单元格,郑商所、上期所、中金所和广期所文件还会按小计核对成交量和持仓量。 - 数据集版本号不再重复使用:一次发布若在写下版本回执之后、切换
current.json之前中断,下一次成功发布此前会沿用同一个版本号,同一编号就有两份回执,按编号固定读取的查询和dataset_revisions()可能读到从未发布的那一份。现在编号跳过中断留下的号码,dataset_revisions()沿已发布版本的链回溯,按编号或 id 固定读取一个比当前版本更新、从未发布的版本时直接报错。已有的湖不受影响,无需迁移。 - 网页控制台数据集页的「数据」一次要读超过 64 MiB Parquet、又没有填标的时,直接拒绝并提示选择时段或输入标的,与 MCP
query_dataset使用同一预算。此前分页前要把所选数据全部载入内存,一个交易日的trade_ticks就可能占用数 GB,不带时段的请求会选中整个数据集,足以让cne serve内存耗尽。 load()读取按时点数据集(financial_statement_items、top_holders、share_structure、shareholder_counts、announcement_index)时,只扫描start/end需要的分区,结果逐行相同。此前无论时段多短都先读入整个数据集、合并版本后再筛选:一个季度的financial_statement_items峰值内存 5.9 GB,一年的top_holders4.2 GB,一个季度的announcement_index4.7 GB;现在分别为 0.5 GB、0.7 GB 和 0.4 GB。announcement_index按公告日分区,end之后、as_of之前发布的更正仍会替换原行,所以扫描到as_of为止。原排序键相同的行(如同一天公告的多名股东)改按主键其余列排序,此前取决于扫描顺序。scan("financial_statement_items", start=…, end=…)不再因拿日期比较报告期字符串而报错。网页控制台数据集页的「数据」对这些数据集按所选时段计算读取量,选了时段就不必再填标的。