故障排查

下面每一节都从你看到的现象出发，再给出原因。若症状未被覆盖，消息文本与帧形状是让问题可处理的两样东西 —— 请都附上。

配置或构建失败

CMake 3.25 or higher is required。 项目使用 C++23 与现代 CMake 特性。请升级 CMake，而不是降低要求。

编译器报 cxx_std_23 特性错误。 需要 MSVC 19.4+、Clang 17+ 或 GCC 13+。在 Windows 上请从 Visual Studio 开发者命令行运行 CMake，以便找到编译器。

add_subdirectory ... does not contain a CMakeLists.txt。 固定子模块缺失：

git submodule update --init --recursive

自带的 DataFrame 被忽略。 用 -DFINCORE_DATAFRAME_SOURCE_DIR=... 指向它，或让 find_package(DataFrame CONFIG) 能在 CMAKE_PREFIX_PATH 中找到。

运行时错误

消息

原因与修复

Invalid date values

日历值超出可表示范围、月/日/小时非法，或 ISO 字符串字段格式错误。解析器最多接受九位小数，并拒绝尾随文本。

column name must not contain an embedded NUL

std::string_view 的长度包含了 '�'。请传入真实名称；库拒绝在终止符处截断。

stress testing does not accept NaN returns

压力情景拒绝非有限输入而不是跳过。请先清洗或丢弃这些观测。

unknown viz renderer 'x'

渲染器名称会被裁剪并转成 ASCII 小写；注册与查找要用同一个名字。

input_error from a risk API

多数风险估计要求严格升序且无重复的索引。调用前先排序去重。

让你意外的数字

  • 得到 NaN 而不是数值。 通常是可用观测太少、窗口不完整，或统计量本身无定义（零偏差、无回撤）。用 std::isnan 判断，而不要假定为零。

  • calmar_ratio 返回 NaN。 序列从未下跌，最大回撤为零，比率无定义 —— 不是无穷大。

  • 回测给出 inconclusive。 配对观测少于三个，或期望例外少于五个。250 天 99% 只期望 2.5 个例外，因此不可能通过；这是样本量结论，不是模型结论。

  • 回撤符号不一致。 max_drawdown 返回负数小数；gen_drawdown_table 报告相对前高的正百分比。

  • 夏普比率看起来太高。 检查年化：日频数据使用 252。用 365 计算会相差 sqrt(365 / 252)。

文档构建失败

Breathe 报告缺少 compound。 Doxygen 没跑，或 XML 已过期。顺序是 doxygen Doxyfile → normalize_doxygen_xml.py → sphinx-build。先跑 Sphinx，或在重新生成前先归一化，都会留下原始 XML，严格构建随后会以两个警告失败。

sphinx.domains.cpp 内部报 AssertionError。 doctree 过期：复用的环境仍持有上一次 XML 的 C++ 域符号。用 -E 构建或删除输出目录。

check_built_site.py 拒绝运行。 缺少一种语言的构建。请构建两种语言（中文用 FINCORE_DOCS_LANGUAGE=zh_CN）；检查器现在会直接失败，而不是把单语言结果当成绿色。

中文构建里某个标题仍是英文。 以数字开头的章节标题（## 1. ...）会被 MyST 以某种方式解析，即使目录里有条目也不会被翻译。请写成普通标题。

编辑页面后出现 fuzzy 条目。 sphinx-intl update 会把改动过的源字符串标记为 fuzzy。请翻译并清除标记；fuzzy 条目计为未翻译，会让站点检查失败。

发布问题

Pages 部署任务以零步骤、无日志失败。 github-pages 环境拒绝了该分支。白名单只含 master，因此通过合并到 master 发布。

构建通过但 deploy-pages 失败。 Pages 源必须是 "GitHub Actions"（build_type: workflow）。切换到分支源会破坏 Actions 部署；改动设置后请重新读取 GET /repos/.../pages。

Read the Docs 只显示一种语言。 这是设计：一个 RTD 项目构建英文源，语言切换把中文读者带到同一页面的 GitHub Pages 构建。

报告问题

附上提交、编译器与平台、能复现问题的最小帧形状、确切消息，以及 debug 与 release 构建是否有差异。文档问题请附页面 URL 与期望的句子。