快速开始

August 15, 2026 · View on GitHub

本指南覆盖两条路径：

  1. 一分钟试玩（推荐新手）：cne demo，小宇宙、独立目录，几分钟出真数
  2. 全量数据湖：cne config init → cne init → cne run daily（耗时长、占磁盘）

详细选项见 CLI 参考。安装见 installation。

0. 一分钟试玩（可选）

不必 clone 仓库：

pip install cnequity
cne demo
# 可选：再看一根完整 1m 会话
# cne demo --intraday

会写入独立的 data/cnequity-demo/ 与 configs/cnequity.demo.toml。
不要把 demo 的 data_root 拿去跑全量 cne init。

接着可查：

cne query --config configs/cnequity.demo.toml --sql "
  SELECT symbol, trade_date, close, volume, source
  FROM daily_bars
  ORDER BY trade_date DESC
  LIMIT 10
"

只想验证复权研究口径，不必初始化全市场：

cne demo --research --symbols 600519.SH

research demo 会把窗口扩展到约三年，读取 Sina 的 hfq 因子，并打印 raw return 与 hfq return 的对照。 它需要额外访问 Sina；网络受限时，先使用不带 --research 的基础 demo。

下面从第 1 步起是全量湖路径。

1. 准备全量配置

pip install cnequity   # 若尚未安装
cne config init                 # → configs/cnequity.toml；macOS / Windows 自动 workers=1
# 可选：cne config init --data-root /abs/path/to/lake
cne config validate

按需编辑 configs/cnequity.toml 里的 data.root（生产建议绝对路径）。

源码开发：也可 cp configs/cnequity.example.toml configs/cnequity.toml，与 cne config init 等价。

2. 初始化数据湖

cne init --config configs/cnequity.toml

init 会：

  1. 创建 {data.root} 下 staging / curated / derived / meta / duckdb 目录
  2. 初始化 meta/manifest.db（SQLite WAL）与 DuckDB 视图
  3. 按 [job.init.phases] 执行分阶段全量回填（默认最近 3 年、全市场标的）

需要从 2016 年起的完整初始化时，使用 cne init --profile full；也可以先用默认窗口建湖，再按需回填。

仅建目录、不跑回填：

cne init --layout-only --config configs/cnequity.toml

中断后续跑：

cne init --resume --config configs/cnequity.toml
# 或指定 run_id
cne retry --run-id <run_id> --config configs/cnequity.toml

init 耗时较长（全市场日线分页回填），建议在稳定网络下运行。阶段定义见 数据流 — Init。

3. 回填验收（推荐，需仓库脚本）

验收脚本在 GitHub 仓库的 scripts/，不随 PyPI 包安装。有 checkout 时：

git clone https://github.com/rootSunc/cnequity.git
cd cnequity
python scripts/accept_backfill.py snapshot --out /tmp/curated-counts.json
# 同窗口重跑 daily 后对比
python scripts/accept_backfill.py check --compare /tmp/curated-counts.json

验收项：幂等性、覆盖起点、消费层可读。详见 回填完成验收。

纯 PyPI 用户可先用 cne status --datasets / cne catalog 做粗检。

4. 每日增量

cne run daily --config configs/cnequity.toml

非交易日自动跳过（skipped_non_trading_day，退出码 0）。

按调度组分批跑（与生产 pipeline 一致）：

cne run daily --group core --config configs/cnequity.toml
cne run daily --group capital --config configs/cnequity.toml
# signals / fundamentals / macro_risk / research

每组末尾含 compact，数据会写入 curated。组定义见 配置 — 调度组。

5. 查看状态

cne status --config configs/cnequity.toml              # 最近一次 run 摘要
cne status --datasets --config configs/cnequity.toml   # 各数据集新鲜度
cne catalog --config configs/cnequity.toml             # 行数统计

6. 读取数据

Python API（推荐）

from cnequity.query import load

bars = load(
    "daily_bars",
    start="2024-01-01",
    end="2024-12-31",
    adjust="hfq",
    universe="all_a",
)

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

见 查询指南 与 Python API。

DuckDB SQL

cne query --sql "
  SELECT symbol, trade_date, adj_close
  FROM daily_bars_adj
  WHERE trade_date >= '2025-01-01'
" --config configs/cnequity.toml

数据库文件：{data.root}/duckdb/cnequity.duckdb。

直读 Parquet

import polars as pl
df = pl.scan_parquet("data/cnequity/curated/daily_bars/**/*.parquet")
df.filter(pl.col("symbol") == "600519.SH").collect()

7. 失败重试

cne status --config configs/cnequity.toml    # 找到 failed run_id
cne retry --run-id <run_id> --config configs/cnequity.toml

retry 只重跑失败 batch；全部成功后自动 compact → derive_adj_factors → audit。

8. 生产调度（可选，需仓库脚本）

# 需 clone 仓库后：
scripts/install_scheduler.sh   # macOS launchd，Helsinki 每天 11:15

见 运维 Runbook。

常见陷阱

问题说明
load() 读不到新数据确认 run 已 compact；分组 run 必须含 compact step
universe="all_a" 未剔历史 STtrading_status 仅覆盖日更起点之后；2016→上线日回测需注意
init 中途失败勿重新 init，用 --resume 或 retry
TDX 连接失败cne servers test；检查 [tdx_protocol.hosts] 与网络
缺配置报错先跑 cne config init
demo 与全量混用demo 用独立 data/cnequity-demo/，全量另配 data.root

更多排障：troubleshooting · runbook。