取数、速度与源保护¶
怀疑网络或安装问题时，先跑离线的 cne doctor，或用 cne init --profile sample 离线验证安装。全市场初始化和历史回填可能持续数小时。不要用全市场任务测试网络，也不要通过不断重试健康探测判断是否恢复。
cne sources limits # 离线查看冷却、预算与续跑入口
cne sources probe --list # 离线列出可探测名称
cne sources probe --only tdx_protocol --vantage local
cne backfill daily_bars --symbols 000001.SZ --start 2026-09-01 --end 2026-09-04 --plan
--plan 不联网、不创建湖或运行记录。普通数据集显示生效的源开关、共享冷却、限速/并发、修复模式、已知欠账与切片；显式股票日线范围另给冷缓存的最低请求数及全板块快照是否跳过。衍生品按交易所能力估算请求数。分页、连接发现、缓存和缺口会改变真实成本，未知数量显示为 null，不把一天说成一个请求。去掉 --plan 才执行。
定向补历史¶
所有用户都通过同一个 backfill 入口使用这些策略；--config 指向自己的配置，
写入该配置的 data.root，不依赖维护者的本地脚本或数据湖。
# 先离线检查标的、日期、来源开关和请求策略
cne backfill daily_bars --config configs/cnequity.toml \
--symbols 000001.SZ,600519.SH --start 2018-01-01 --end 2018-01-31 --plan
# 确认范围后，去掉 --plan 执行
daily_bars、minute_bars 和 minute_bars_5m 支持显式证券列表与日期窗口；
分钟数据需要先在配置中启用，并且起点必须在源的保留期内。
--symbols 并非所有数据集都支持，其他数据集以 backfill --help 为准。
--outstanding 根据本湖的欠账台账修复，不能同时传 --symbols/--start/--end。
它先核对已发布行情并销掉已存在的 key，再对真正缺失的月份请求来源；
仍缺失的 key 不会因这次离线核对增加重试次数。无法取得行情前先检查上市、退市和停牌证据，
不要反复请求本来不应有交易的日期。
TDX K 线只有记录偏移量，没有按日期过滤的服务器参数。回填较早窗口时，项目先按日期 扩大探测间隔、二分定位，再连续读取目标窗口；本次定位读过的页直接复用。 因此请求量由“每只证券读取从最新到起点的全部页”，降为“每只证券的定位页 + 窗口页”。 定位随历史深度对数增长；完整多年历史仍须读取全部需要的记录，不能承诺任意窗口一个请求。 靠近最新的窗口和从最新往前补整段历史沿用顺序读取，不额外定位。 跳页后会再检查一次最新页的时间戳；位置变化或请求失败时该标的报错，避免提交错位的部分结果。 日期无法解析时退回顺序读取；限速、历史边界和完整性检查继续生效。
减少请求时，优先缩小证券范围，并把同一证券相邻日期合成一次回填；分钟回填已按证券切片， 不需要手动按日循环。THS 年度文件、交易所日文件等仍按各自文件粒度读取和缓存。 证券数量通常线性增加请求；时间跨度决定窗口数据量；目标日期距今多远主要增加 TDX 的定位成本。 被暂停或拒绝的源不会因日期定位而恢复，已过保留期的分钟数据和缺失的历史快照也不会因此变得可补。
哪些 CLI 会联网¶
下表覆盖全部叶命令。离线指不向数据源请求；写报告、索引、快照或配置仍属于本地写入。
| 命令 | 联网与副作用 |
|---|---|
config create/validate/diff、doctor |
离线；create 写个人配置，doctor 可能测试目录可写性 |
init |
quick/full 抓历史；demo 抓小样；sample 离线合成；--layout-only 只创建本地目录和元数据 |
run daily/events/retry |
联网采集，写 staging、元数据并按步骤发布；retry 应指定失败 run/组 |
run compact/clean |
离线；compact 发布暂存数据，clean 删除符合条件的本地数据。clean 的 --dry-run 预览删除范围，不能与会改运行状态的 --reconcile-runs 同用 |
backfill |
通常联网补历史；已完成的切片/证券按各数据集 checkpoint 续跑；退市范围使用 backfill daily_bars --profile delisted；backfill --plan 离线。--shfe-annual-archive 是显式本地 ZIP 导入，不请求数据源，但会保存原包并发布缺字段行 |
derive |
adj_factors 会刷新外部因子及备源；其他派生模式主要读本地数据、写派生结果或映射。不要把 derive 整体视为离线命令 |
verify |
默认检查本地覆盖；--repair 才执行联网回填 |
audit |
run 审计可能向 NBS/交易所做启用的外部对照；--full 读取湖和已有证据，不等同于主动源探测 |
query --sql |
查询湖；可更新本地 DuckDB 视图 |
query --dataset … --symbol … |
缓存命中则读取；缺失/--refresh 时联网。受 [on_demand].enabled 和源开关约束；失败非零退出 |
mcp、serve |
默认查询湖；mcp --live 显式启用有限的源查询。不会自动运行全市场采集 |
sources probe |
逐源有界探测并写报告；--list 离线。DCE 官方、THS 目录、Baostock、国证历史文件仅在 --only 显式指定时主动探测；握手、分页、下载各计一次 |
sources substitutes |
默认读已有报告；--probe 才联网 |
sources slo/resilience/policy/limits |
读取本地源策略、历史探测、冷却、预算和统计；可写报告，不触发取数 |
status、delisted status、profile list/show、contract show/diff/validate |
本地状态、目录或契约检查 |
decision-data payment-gaps/stock-terms/cash-rights |
从已提交数据生成本地决策清单，不采集 |
stats show/rebuild |
读本地 Parquet/统计；可能刷新统计文件 |
snapshot create/verify/restore/export/import、snapshot delta create/verify/apply |
本地快照、校验、复制；不向行情源取数，restore/apply 会写目标 |
ths-official capture/backfill/repair-bars/resource-sectors |
可选凭证源；capture 写对照证据，backfill 补空缺。repair/resource 的默认预演也会联网，--apply 控制写入，不表示联网许可或配额无限 |
数据源选择与请求成本¶
选择顺序以数据口径、覆盖与可复查性为前提；同一厂商换域名不算独立备源。不能用快照冒充历史，也不能直接拼接不同厂商的板块指数。完整字段与例外见数据源说明和数据集目录。
公开默认配置启用 EastMoney，且 push2_paused=false。push2 用于快照数据、日线缺口补充和独立对照，并非所有数据集的统一主源：股票日线以 TDX 为主，估值优先使用有日期且提供 TTM 口径的东财 datacenter，尚未发布或不可用时再尝试 push2。出口被封时，仅在该部署的个人配置中暂停 push2；普通日更与晚间补跑使用同一源策略、预算和熔断账本。
| 数据族 | 当前获取方式 | 速度与风险取舍 |
|---|---|---|
| 沪深日线、指数、分钟、分笔 | TDX 连接复用与分页；日线按缺口使用 EM 等兜底 | 全市场当日优先利用交易所板块快照；显式历史或最多 4 只的日线回填跳过全板块快照，直接走限定范围；分钟按证券切片，避免按日期重复拉 tip 页 |
| 北京日线 | BSE 官方当日板块快照；历史以 TDX/Sina 按覆盖路由，字段修复按来源证据执行 | 全市场当日按页取板块，避免逐证券多次请求；显式历史或最多 4 只的回填跳过全板块快照，不制造 Sina 未提供的成交额 |
| 公司行动、复权、历史 ST/估值 | EM/TDX 公司行动；Sina 因子、Baostock 备援与历史证据；发行人公告补付款日 | 因子缓存只刷新需要更新的证券；显式 BJ 修复使用的 THS 公司行动页面仅在识别出已实施事件后缓存 24 小时，缓存复用的原始响应归档保留首次抓取时间；Baostock 串行、批次休息；缺失事件仍保留缺口 |
| 财务、股东、资金、新闻及快照 | EM datacenter / push2 / 新闻接口；THS 资金流另存独立表 | push2 快照复用、按源预算；快照丢失日不能靠今天重抓补成历史；财报按报告期×报表、前十大股东按季度切片；同一 run 续跑跳过已验证并暂存的完整时间窗。股东分页后期失败时，已验证页中的正向事实可以标记部分覆盖后发布，失败窗口留在欠账并重抓；不能把不同时点的页拼成完整快照 |
| 公告、监管 | CNINFO 分页 POST，按日期与发布板块细分 | 有界重试、按窗口 checkpoint；不能靠更高并发解决页数上限 |
| 融资融券、龙虎榜、大宗交易 | 融资以交易所为默认；龙虎榜/大宗交易 EM 主、交易所备 | 按日批量获取；交易所未发布字段留空，不能为了字段齐全伪造数据 |
| 行业、指数成分、板块行情 | 当前快照 + SW/CNI 历史文件；THS 同口径板块 K 线 | 文件优先、目录缓存；SW 行业文件与 CNI 各指数调整文件校验后缓存 24 小时；THS 板块、股票和指数的有效年度 K 线文件按 URL 分别复用，旧年度最多缓存 30 天、最近两年最多 1 天，空文件不缓存，板块 last.js 保持实时读取；指数/板块换源需显式审核 |
| 宏观、商品研究序列 | EM、PBOC 发布文件、Sina 连续行情；NBS 做有限对照 | 文件和完整序列一次下载后切窗口；NBS PMI 索引校验后缓存 1 小时、已解析正文缓存 24 小时；主连研究序列不能代替真实合约生命周期 |
| 期货、期权 | 交易所文件；DCE 的配置路由、Sina 有限分钟窗口 | 按交易所文件缓存、完成收据和缺口续跑；不突破源历史边界，见衍生品指南 |
| 可选 keyed API | ths_official / Tushare，仅启用后调用 |
不成为免费核心链的强依赖；大文件优先于逐标的，公开 THS 网站与 keyed 服务独立限流；Tushare 2016 年 bak_basic 的完整有效交易日结果按凭证隔离缓存 7 天，复用时保留原始 fetched_at；空结果、错日结果不作为正常状态证据，失败后优先复用先前成功日期 |
共享限速与冷却¶
请求同时受两种约束：每源最大在途数、相邻请求的最短间隔。先取得并发名额，再在实际网络调用前等待间隔，慢请求结束不会释放一批提前取得时隙的请求。同一公共站点的端点别名还共用源族基础间隔，避免各守一次间隔却合计超速；更慢的页面/历史接口仍单独守自己的间隔，不拖慢同厂商的普通接口。等待者每次醒来重新检查共享时间，能看到其他进程后来设置的冷却。
代码内也为已接入源设置了保守的默认间隔和在途数：使用最小 TOML 或直接构造 Config 时，省略 [sources.*].min_interval_seconds 和源并发上限不会让请求失去节流。公开示例给出相同的常用值；一般源的显式配置值（包括 0 秒间隔）仍优先。TDX 同时设置 tdx_protocol.min_interval_ms 和源间隔时取较严值。无法归入已知源族的新源默认间隔 1 秒，接入时仍应按源特性补充专用策略。sources limits 显示实际默认值与当日生效值。
HTTP 429 与没有认证质询的 403、412、456 会在已接入的请求边界记录至少 300 秒的共享冷却；服务端 Retry-After 更长时按它执行，支持秒数与 HTTP 日期。401 或带 WWW-Authenticate 的 403 按凭证问题交由调用者报告，不把另一套凭证所在的整个出口封住。普通 404 不作为封禁。预期 JSON 的端点遇到明确验证码/挑战 HTML，以及东财 datacenter 的“请求过于频繁”和 keyed THS 的业务限流码，也会冷却。
一般 5xx 按服务端临时故障走适配器已有的有界重试与退避，不直接判为整个出口遭封禁；东财 host 熔断还有单独的、较严格的 5xx 规则。真实源请求量可能包含连接发现或分页，不能只凭 HTTP 状态推断 IP 风险。
冷却期内后续请求在本地失败。期满后，同一源族只放行一个恢复请求；失败则重新冷却，成功才放开。公开 THS 页面返回 401 时也作为该公共站点的拒绝处理，不与需要凭证的 ths_official 混淆。Baostock 按源方规则执行：上海自然日最多 5 万次 API 请求（登录、查询、退出各计一次），同一时刻只保持一条连接；10001011 或黑名单响应按本自然年累计次数 × 6 小时冻结，响应没有待释放时间时至少 5 分钟内不再刷新，冷却结束前不再登录。扫描在限额或黑名单处停下时，已经取到的标的会留下；冷却结束后重跑同一命令，从尚未完成的标的继续。可选 Tushare 的明确业务限流消息和 keyed THS 的 HTTP 429 也不连续重试。由适配器识别的业务拒绝才会进入此流程，无法保证识别所有 HTTP 200 中的反爬页面。每次拒绝保留失败/缺口以供续跑。
cne sources limits 只读取账本，显示配置值与当日跨进程实际生效的最严间隔/并发、恢复探测状态、东财剩余预算、Baostock 当日剩余请求，以及最近一次 run 已记录的请求与重试；交易所期货文件的逐主机 lane 也单独列出。metered_attempts_today 在共享限流放行后、网络调用前按源族和 lane 记一次；本地冷却或禁用拒绝不计。它覆盖已接入的请求作用域，包括 TDX 连接发现和分页，但一个作用域可能发送多次底层请求，不能把它当精确 HTTP/TCP 包数。wire_responses_today 汇总已接入响应钩子的返回次数、HTTP 状态、解码后正文大小和端点路径哈希；不保存查询参数，也不计没有返回响应的请求。cache_reuse_today 记录已接入响应缓存的复用次数，不算新源观察。request_events_today 记录已标记的期货文件、BSE、东财 datacenter 与 Tushare 的额外重试，以及东财直连 fallback；其他路径尚未统一标记。运行 metrics.requests 仍只覆盖适配器传入的遥测，部分预取和实际传输字节尚未统一，不能据此宣称全项目真实请求降幅。
[sources.eastmoney].daily_budget 可为 push2 与 datacenter 设置同一出口的共享日上限；默认 0 只计数，部署前应根据实际请求账本选择保守值。两个 lane 的间隔和各自预算仍独立生效。
这遵循 HTTP 对限流与重试时间的表达方式；300 秒是本项目保守策略，不是源方公布的配额，也不保证 IP 永不被封。HTTP 429、Retry-After。
已有的 EM push2 当日熔断/预算、datacenter 熔断，以及衍生品主机 challenge 熔断继续生效。东财的日预算与熔断现在共用出口账本；首次使用时会合并本湖当天的旧账本。多个进程设定不同时，选已见过的最严格正数预算与熔断阈值。冷却不会清除这些更严格的限制。不要删除状态文件、轮换 IP、增加 worker 或关闭熔断来应对拒绝；暂停受影响源，等冷却后做一次小范围验证，并修复失败范围。
默认限流与冷却放在 {data.root}/meta/rate_limits。同一个出口上多个湖/CLI 进程必须共用目录：
export CNE_RATE_LIMIT_ROOT="$HOME/.local/state/cnequity/egress"
HTTP、TDX 和 EM 日预算/熔断都读取这个变量。所有进程应使用相同、保守的源设置；目录要支持可靠的本地文件锁。这个机制不协调不同机器，也不限制浏览器或其他程序的流量；同一出口优先用一个采集调度器。
操作顺序¶
- 离线
doctor、config validate、config upgrade --dry-run；先确认配置与绝对data.root，再看backfill --plan。 - 小范围验证可达性和数据口径；范围参数不能是空字符串。健康探测源名可用
--list查询，拼错会报错。 - 日常用增量
run daily/run events；只为失败窗口回填。verify --repair、--force、--refresh的成本不同，执行前看帮助。 - 被拒时保留日志、run ID 和 checkpoint，暂停同源任务。恢复后续跑缺口，避免重复初始化或全量扫描。
- 性能比较记录源、范围、缓存冷热、请求数和耗时；个人出口观测放本地过程文档，不转化成公共速率保证。