Skip to content

0.17.0 · 首次建湖更快更稳

Choose a tag to compare

@rootSunc rootSunc released this 17 Oct 16:47
· 211 commits to main since this release

首次建湖更快更稳

CNEquity 0.17.0 已发布至 PyPI。开源 A 股本地数据湖,用于量化研究、回测与 AI Agent。

python -m pip install --upgrade cnequity==0.17.0
  • 升级步骤: pip install -U cnequity 后重启 cne serve 和已在运行的 cne mcp。除 institutional_holdings 的单位声明外,数据集契约没有变化,不需要迁移数据或改配置。经历过东财中断的湖,升级后对受影响窗口运行一次 cne repair status-outages --start <起> --end <止>(先预览,再加 --apply);补跑过估值的湖运行 cne repair misdated-valuation。两条命令都发布新版本,旧版本保留。
  • 数据契约变化: institutional_holdings schema 升至 2,holding_ratio 的单位声明由比例改为百分数(8.5 即 8.5%),与已存值及字段文档一致;已存值不缩放,需要比例的读者自行除以 100,见迁移与回滚说明。
  • 第一次建湖不再被非关键阶段挡住:公司行为、指数日线或交易状态阶段失败时,cne init 照常抓日线、入湖并派生复权因子,退出码为 0,结束时列出没完成的步骤;重跑同一条 cne init 只补这些。证券目录、交易日历或日线失败仍停在原处并保留已下载的部分。
  • 全市场 cne init 先抓日线、再扫公司行为:公司行为逐只拉取全部除权除息记录,与窗口长短无关,以前让日线多等很久。原样保留旧默认阶段顺序的配置自动换成新顺序,自定义顺序和已开始的 init 不受影响。
  • cne init(quick / full)开跑前做最多 8 秒的网络预检:通达信连不上时几秒内停下并给出中文原因,交易所和东财只报告不阻断;--no-preflight 或 CNE_SKIP_PREFLIGHT=1 跳过。通达信选主机改为第一个可用主机即返回,不再等最慢的候选超时。
  • 证券目录步骤(instruments)逐段打印进度:开始取通达信列表、北交所、基金与股票上市日期、退市名录和写入时各打一行,并带已用时间,全市场初始化里不再静默数分钟。
  • 日线入湖之后的复权因子、行业指数、质量审计或停牌派生出错,不再把已发布的湖判为不可用,也不再跳过后面的阶段;摘要列出没完成的步骤,重跑 cne init 只补它们。
  • 修复交易日历在节假日表最后一年(2027 年)内必然失败的问题:日历步骤要向后多写一年,超出内置表就报错,从 2027-01-01 起每次 cne init 第一阶段和日更日历都会失败;现在写到表的最后一天为止,剩余天数不足时由审计提示。
  • 证券目录取通达信列表时,连接和每个市场的请求失败各重试一次,一次网络抖动不再让 cne init 在第一步就停下;Baostock 证券基础信息在同一步内只查询一次(以前补上市日期和补退市名录各查一次)。
  • macOS 和 Windows 上 cne init 运行期间阻止系统空闲睡眠(合盖或手动睡眠仍生效,进程结束即解除);设 CNE_ALLOW_SLEEP=1 关闭。
  • 修复同一窗口里第二次向 Baostock 核对停牌时覆盖第一次暂存的停牌证据:日线已据第一次结果判为「停牌、无需补」,证据却被替换掉,这些证券既没有停牌记录也不进欠账,cne check 因此对整月停牌的证券判覆盖不全。现在每次核对单独暂存。
  • 调度脚本在仓库没有 .venv 时改用 PATH 上的 python3(可用 CNE_PYTHON 指定),不再因找不到解释器而拿不到调度锁。
  • Windows 上 serve 存储页删除 staging 的计划与记录统一用 / 分隔路径,同一计划在各平台一致。
  • cne init 不再在终端打印 Baostock 的 login success! / logout success!;--json 的 stdout 只剩结果。
  • 修复周末或节假日运行 cne init 建出的湖缺北交所证券和交易状态:此前以当天日期为准,北交所板块和交易所状态页对非交易日不返回数据,cne check 报「新鲜度证明不了」。不带 --trade-date 时现在以最近一个已收盘交易日为准,与 demo 一致。
  • 全市场 cne init 在抓日线和扫公司行为期间于后台把复权因子预取到本地缓存,收尾派生改读缓存,没取完的部分由派生接着请求。此前收尾时才逐只请求新浪,受限速约束耗时很长;现在收尾派生大幅缩短。预取不写入数据湖,失败的证券由派生时再请求,也不计入初始化的完成条件。
  • 没开基金采集时,全量公司行为扫描不再请求 ETF/LOF,全市场少约四分之一请求。以后开启基金采集,日更的公司行为步骤会自动补扫从没扫过历史的基金,每次最多 500 只,扫完前告警(fund_history_unswept)列出还缺历史的基金;新上市基金同样补扫一次。
  • 公司行为全市场扫描改为多条 TDX 连接并行(按 [source_concurrency].tdx_protocol,最多 4 条),请求仍受原有 TDX 限速和并发上限约束,全市场扫描明显加快。失败分块照常留待重跑,Ctrl-C 后各连接在下一只证券前停下。
  • 复权因子日常派生提速并停止整表重写:以前每天把全部日期分区重写一遍(只为更新 fetched_at),每个修订都另存整表一份;现在只写真正变化的分区,平常一天只新增一个分区。股票事件修正按证券一次性分组、只取用到的价格,日线日期少读一遍。派生耗时约减半,输出与原来逐行一致。
  • 证券目录每天不再重新向 Baostock 查询全部上市日期:湖里已有的日期(包括人工修复的)直接沿用,只为还没有日期的证券查询,各来源都给不出日期的证券 7 天内不重复查询。日常证券目录因此明显加快。
  • 修复日线每天都按深度对账跑的问题:daily_bars 走自己的取数路径,从未记录每周深度复核已完成,自 2026-10-08 起每次日更都逐只重抓最近一周,而不是用交易所整版行情和 TDX 批量报价只取新交易日。现在深度复核跑完即记录,平时恢复只取新交易日,每周一次深度复核;未结清的证券仍由欠账账本单独补抓。配置说明里 deep_reconciliation_dow 的取值也更正为 1=周一 … 7=周日,0 表示每次都深度对账。
  • 日线的无数据证据(负缓存)不再每次逐行哈希全部交易状态历史来判断是否失效:以前每次日线运行要做三次;现在以交易状态的修订号和已提交文件的路径、大小、修改时间判断,结果只会更保守。只取新交易日的日线因此明显加快。旧的负缓存会在升级后失效一次。
  • 期权 IV 与 Greeks 派生(option_greeks)只重算真正受影响的交易日:以前合约表或利率表任一重发都会让全部交易日失效,每次全量重算耗时很长,并在整个计算期间持有湖锁,其他任务的入湖发布只能排队等待。现在每个交易日只记录它用到的合约条款和适用利率,计算期间不持锁,只在写入时加锁;平常一天只算新交易日。升级后第一次运行会全量重算一次。
  • 期货期权交易所文件的磁盘缓存(meta/derivatives/http_cache)自动清除超过最长有效期(30 天)的条目:这些条目不会再被复用,以前从不删除,一次回补就会留下大量缓存文件。每个进程第一次请求时扫描一次。
  • 原始归档里的 PDF(如 cne repair financial-originals 归档的巨潮定期报告)改为不压缩保存:gzip 只能缩小约 1%,却要花大量 CPU。已经压缩保存的 PDF 保持原样,读取不受影响。
  • cne init 结束时改为打印简短摘要:湖是否可用、还差哪些步骤、日志位置和下一步命令(cne check、cne serve、Python 读取、MCP 接入)。完整结果不再刷屏(全市场可达数万行),改存到 {data.root}/logs/cne-init-<run_id>.json;脚本需要时加 --json,serve 操作页已自动使用。
  • cne check 只列有数据或已陈旧的数据集,还没有数据的折成一行,新湖不再显示几十行 empty;cne status --datasets --hide-empty 提供同样的视图。
  • 终端里的进度日志改为简短格式:只留时分秒,警告和错误前加标记,不再带日志器名;中文环境下步骤开始与结束、心跳、批次进度、初始化阶段和重试提示显示中文。只在交互终端生效,重定向到文件或被调度器捕获的输出、以及日志目录里的日志文件仍是完整英文格式。
  • CLI 改为中英双语:帮助、提示、报错和 cne init 结束摘要按语言显示,依次取环境变量 CNE_LANG(en 或 zh_CN)、系统语言,都没有时用英文。中文系统上看到的中文与以前一致;系统语言是英文、但想继续看中文的,设 CNE_LANG=zh_CN。JSON 输出(含 --plan 和 --json 里的说明文字)、HEALTHY/STALE 等标记词、退出码和日志文件不随语言变化,说明文字统一为英文。
  • cne serve 控制台没有选过语言时跟随浏览器语言(简体中文显示中文,其余显示英文);服务端的报错、提示和后台任务输出按页面所选语言返回,英文页面不再夹带中文提示。
  • 定时任务沿用安装时的语言:cne init --schedule 和控制台设置的定时任务会记下当时的语言,由 launchd、cron 或任务计划程序拉起时照用,不再因为这些环境没有 LANG 而变成英文。仓库里的 scripts/scheduler 安装脚本会把安装时 shell 里的 CNE_LANG 写进 launchd 任务;已安装的定时任务重新保存一次设置即可。
  • 诊断、质量、研究包、配置对照和存储运维的提示也改为中英双语:cne doctor、cne sources probe/substitutes、/source-health 页面、cne check --pack、cne config diff 和存储清理的报错在中文环境下与以前一致,英文环境不再夹带中文。写进湖里的探测报告、cne doctor --json、cne sources limits 的说明、衍生品质量发现和 MCP 返回的数据集分层名改为英文,cne config upgrade 写进配置文件的注释也改为英文。
  • 修复 Windows 中文环境下 cne mcp(stdio)的中文乱码:管道固定按 UTF-8 读写,不再跟随 GBK 控制台编码;中文名称查询恢复命中,非 UTF-8 的请求行返回解析错误而不中断会话。
  • cne serve 操作页显示当前使用的数据目录。配置文件里的 data.root 被改成别的目录时,每页顶部对照显示两个目录并给出可复制的重启命令;文件读不出来时指出出错的行和列。在那之前控制台继续使用启动时的数据湖,但不能启动任务、修改取数设置或定时任务,避免任务按新配置写入页面看不到的湖。
  • 新增 cne repair index-snapshots:回放或显式采集沪深 300、科创 50、深证成指、创业板指的官方带日期成分与权重文件;--apply 按文件实际日期替换完整快照,百分数权重转为比例。成分与权重不跨日期互补,不把当前名单倒推到历史。
  • 新增 cne repair index-history:回放已核验的深证成指(默认)或科创50(--index-symbol 000688.SH)官方调样公告目录,--refresh-sources 只补采未归档附件。--apply 在每个实际生效日写完整名单,未知历史权重为空,同日已验证的官方权重保留;附件缺失、内容摘要变化或与既有官方名单冲突时停止更新。
  • 新增 cne repair stock-listing-dates:以有成交但上市日期未知的股票首日或可重复的 --event-date 定位巨潮 IPO 日历,只接受代码、日期匹配且不与更早成交矛盾的上市事件;默认回放归档,--max-sessions 分批。--apply 保留已有日期,并在同一修订中清除早于官方上市日期的残留退市日期。
  • 新增 cne repair financial-originals:按股票、年份和报告期(--quarter,默认年报)回放巨潮原始定期报告,--refresh-sources 归档完整查询与原始 PDF,--max-reports / --after 分批接续。--apply 只追加能明确识别科目和人民币单位的合并报表当期数与累计数;--reparse 重放旧报告并保留未变行的首次观测时间,未识别的布局或科目保留缺口,不回填采集时间。
  • 新增 cne repair fund-volume:用上交所行情服务的完整历史 K 线修复沪深场内基金零成交量、正成交额的行;默认离线回放,--apply 只替换上市窗口内价格及舍入金额一致的行并保留旧版本。湖中金额冲突时须有归档的东财未复权日线同时证实价格和金额才替换整行;不用成交额倒算成交量,之后重抓的零量行不会覆盖已恢复的成交量。
  • 新增 cne repair fund-no-print:回放或显式采集沪深交易所历史基金报表;深交所以明确零成交额、上交所以明确不存在的竞价开高低提供日线覆盖证明(不否认汇总口径成交),结清对应日线欠账。证据可回放,失效时重新打开欠账;不把无成交当作停牌,不生成行情数值。
  • 新增 cne repair adj-factors:离线预览、显式联网采证、分批历史进度、计划复查及版本化发布;统一基金份额折算、股票事件修正和原始来源覆盖恢复,证据不足时保留原值。独立证据随修订保留,重复应用不累乘。
  • 复权读收据、MCP 和行浏览提供所读版本的因子来源及非阻断历史诊断,诊断出错时读取照常返回;普通 load() 不做诊断,不增加开销;strict_adj / adj_is_exact 仅表示覆盖,不承诺历史准确性。
  • 混合 Parquet 历史按连续相同 schema 合并扫描,保持文件次序并避免大量优化器分支。
  • serve 存储运维页支持勾选删除已成功 compact、无未完成批次的终态 staging。网页确认时复查运行锁、引用保留和逐文件指纹;中断可凭收据重新审核并恢复。未完成、未合并和 orphan 暂存继续保留,CLI 与定时清理仍只预览。
  • 通达信和东财日线不再把有成交额、手数取整为零的尾单写成零成交量;该键继续向其他来源补查,不能据此判定停牌。
  • 日线采集规划和批次缺口检查与覆盖报告统一停牌证据要求:推断、沿用和回溯套用的状态不能让缺失行情免于补查;相互矛盾的一手记录也不能证明停牌。
  • 历史因子派生排除退市日后的零成交占位日期,保留退市前历史;实际成交与退市日期冲突时保留数据供核查。
  • 旧 staging 合并时拦截退市日之后的正常交易状态;成交记录否定目录退市日期时保留该证券供核查。
  • 已上市基金采集启用时,证券目录从交易所完整 ETF/LOF 名录补未知上市日期,并归档来源响应;新增 cne repair fund-listing-dates 用于旧湖。确认上市日期后,覆盖对账结清上市前的日线请求,未知或被成交历史否定的日期不能销账。
  • 日线补缺和停牌核验只向 Baostock 请求其覆盖的沪深股票;基金、指数及北交所代码不再贡献该来源的空响应证据,旧负缓存自动失效。
  • cne backfill daily_bars --outstanding 每个月度修复后也同步受影响的复权因子和停牌派生,派生失败即使日线已销账也会显示未完整完成。
  • 新浪日线窗口统一用上海日期,serve token 使用常量时间比较。
  • 调度脚本和操作页统一使用含主机、进程启动身份及释放 token 的锁标记。自动回收已退出或 PID 已被复用的本机所有者,只有 PID 的旧格式标记在进程退出后同样回收,无标记的锁目录超过 60 秒后回收;远程主机的锁须由维护者核验后移除。Mac 以硬件 UUID 标识主机,换网络改主机名不会让锁卡住。
  • 生命周期引用扫描补充排除湖自动写入的修复与派生收据、因子仲裁缓存和统计缓存,日常更新不再使清理登记失效;人工审查引用仍须重新登记。
  • 重审保留采集步骤的告警,重新计算的湖检查结果单独更新;cne audit --run-id 可重复指定,定时健康检查合并本轮各组及补抓运行的证据。旧格式报告的未分类证据在首次重审时保留。
  • 初始化恢复先重开运行,再完成剩余阶段,重试汇总不会提前关闭父运行。
  • 东财 K 线和新闻接口的 data: null、缺失列表不再认证为空数据或分页完成;只有结构有效的空列表可作为空响应。日线旧负缓存随响应契约升级自动失效,后续采集重新核验。
  • 新增 cne repair missing-values valuation_metrics|index_constituents:把估值源以零表示缺失的 PE、PB、PS 和总/流通市值,以及东财、国证快照缺失的指数权重改为空值,负估值比率保留。预览同时列出各指数、来源的快照起止与数量;--apply 经修复门禁发布并保留旧版本,不制造缺失的历史成分或权重。
  • 新增 cne repair financial-announcements:财报 NOTICE_DATE 可能是再公告日,原始披露日改从 LICO 解析;--apply 只为有原始公告日证据的已有科目追加 eastmoney_backfill 重建版本,保留实际公告版本和旧湖版本。重建值在 best_effort 读取时返回 pit_is_exact=false,strict 排除;缺少的历史科目仍需 cne backfill financial_statement_items 补采。
  • 新增 [universe].ingest_listed_funds:按证券目录采集已上市 ETF/LOF,研究资格只用于筛选;上市区间仍受检查,未知上市日期单独报告。基金目录失败、缺失或过期(含旧的研究资格采集开关)时,当天只暂停基金日线并记为 warning(fund_bar_scope_unavailable),股票日线照常采集;重试已计划的基金批次不会因此被撤销。
  • ETF/LOF 日常因子派生补入已记录的拆分和转增;历史漏跳可用 cne repair fund-factors 预览、--apply 发布修正版本,来源为 derived_fund_actions。从原始来源序列重建,保留其他台阶和现金分红口径,旧版本保留。
  • 日线发布后按已提交的正成交量日线或独立停牌证据结清已补齐的北交所整日欠账。旧湖可用 cne repair daily-bar-coverage --apply 刷新覆盖水位;未知上市日期仍是逐证券覆盖报告中的未核实项。
  • Python load() 省略 pit_mode 或传 None 时,默认使用 best_effort,在 as_of 之后采集的历史回填不再被采集时间过滤为空,返回的重建行标为 pit_is_exact=false;读取收据记录实际模式。公告及已知可用/发布时间仍受截止日约束。依赖旧默认采集时间过滤的研究调用,升级后应显式传 pit_mode="strict"。
  • 修复东财不可用时 trading_status 把正常交易的证券记成停牌。兜底现在只沿用每只证券前 5 个交易日内最近的一手记录(按交易日计,长假不再让缓存过期),不再沿用兜底自己写的缓存行;没有一手记录的证券不写行,而不是记成停牌,严格模式的股票池会因此拒绝这一天。用到兜底的运行记为 warning,有证券没有记录时覆盖记为 partial,告警逐日列出交易所板块、沿用和缺失的数量。
  • 东财中断时沿用的状态行(eastmoney_cached)一律按转述排序。此前兜底在收盘后写入的沿用行会被当成当日一手记录,压过日线缺口推断的停牌,并被日线覆盖检查当作可信停牌。
  • trading_status 不再写证券上市日之前的行。东财会把尚未上市的代码报成正常交易,追赶多个交易日时这些行此前会写入;instruments 上的退市日早于上市日时也不再当作退市。cne repair status-outages 不再把状态沿用到上市日之前。
  • 新增 cne repair status-listing-window:删除上市日之前的状态行,以及当前 instruments 已不记退市的 derived_delisted 行。旧版合并曾把尚无日线的新证券推断为退市,它们上市后的头几个交易日因此被记成已退市。日线在上市日之前就有成交时,上市日视为有误,行保留。升级后运行一次(先预览,再加 --apply)。
  • 新增 cne repair status-traded --start --end:离线预览用正成交量日线补缺失股票/ETF 状态键,--apply 发布 derived_traded 行并保留旧版本;不覆盖已有状态,ST 保持未知。显式的 risk_warning=null 在状态规范化及合并后保持未知,不再转成 false。全湖检查增加按类别和月份的成交状态覆盖报告,包含首次状态记录之前的历史,单列 ST 未知及上市日期等排除原因。
  • staging 清理预览列出完整运行清单、大小和保留原因;清理执行器在删除期间持有运行锁,正在重试的运行即使指定 force 也保留。未完成批次不按年龄自动淘汰。
  • 合并旧 staging 的状态批次时重新检查上市窗口及退市依据,防止已修复的错误行在重试后重新入湖;被实际成交否定的上市日期仍保留供核查。
  • 修复以湖的 meta 目录为引用根导入生命周期清单后,staging、来源快照和日志的清理(包括每晚的 cne run clean 预览)从下一次运行起一律报「References changed」。以该目录为根时,湖每次运行都会改写的内容(来源缓存、state、checkpoints、quality、source_snapshots、衍生品抓取记录等)不再计入引用。这样导入过的湖升级后要重新生成引用清单并运行一次 cne storage import;其他引用根不受影响。集成程序调用 reference_files() / reference_fingerprint() 时传 meta_root=。
  • MCP query_fundamentals 与 serve 行浏览带 as_of 时默认 pit_mode="best_effort",回填的历史行以 pit_is_exact=false 返回,不再因 fetched_at 晚于 as_of 被整段滤空;MCP 新增 pit_mode 参数,strict 结果为空时提示被排除的回填行数。/api/read 仍默认 strict。
  • 修订发布的持久性:生成目录里的每个副本及其目录项在 current.json 切换前落盘,状态文件写入先 fsync 再替换,原子替换后同步所在目录;崩溃后不会留下指向未落盘文件的指针。
  • cne check 把全湖审计快照(或 --full 刚跑的全湖审计)里的 error 计入退出码并列出,不再只看最近一次 run 的审计;只记录了计数的旧快照按计数计。
  • staging 清理把 degraded 视为终态:批次都已成功且 compact 成功的 degraded run 可以清理,仍有 degraded 或失败批次的 run 继续保留。
  • 最近 10 个交易日内的因子漏跳通过统一修复入口采集独立证据,能够判定的事件自动修正;无法判定及来源不可用均保留非阻断提示。历史因子矛盾不再阻断审计、发布或修复。无效数值、损坏文件和主键错误仍执行结构门禁。
  • 东财公司行为缺除权日时不再用股权登记日顶替,该方案不生成事件。登记日比除权日早一个交易日,顶替会把复权台阶提前一天。
  • 估值的 push2 兜底只用于最近一个已收盘的交易日。此前补跑多个历史交易日时,同一份实时快照会被盖上每一天的日期;现在其他日期报来源不可用,留待 datacenter 或 Baostock 补齐。
  • 湖审计新增 trading_status_contradicts_bars 与 trading_status_missing_traded:用最近 5 个状态日对照 daily_bars,报出记为停牌却有成交、以及有成交却没有状态记录的证券。单日超过 5 只为 warning,超过 50 只为 error。证券首次出现在状态数据之前的交易日不计入。
  • 不跑 audit 的运行(例如定时的 cne run daily --group ...)也把步骤告警写入 meta/quality/findings/<run_id>.json,此前这些告警只在跑了审计的运行里落盘。同一条告警只记一次。
  • 新增 cne repair status-outages:按现行规则重建窗口内东财中断期间写入的状态行。只在主源当天答复的证券不到前几个交易日一半的交易所沿用记录;沿用的行保留原始抓取时间,Baostock 历史与日线缺口推断的停牌仍然优先。
  • 新增 cne repair misdated-valuation:找出抓取时刻对应的交易日与行上日期不一致的 push2 估值行,--apply 时换成东财 datacenter 按日期发布的估值;datacenter 没有的键不再保留错误的行。