3.5 KiB
Windows 与 Linux 功能交付约定
文档版本：1.1.1
修订日期：2026-09-12
核对代码基线：22579e5；本次版本号仅标注文档，不改变模型版本或协议版本。
2026-09-12 用户明确要求：后续功能补全同时注意 Windows 平台适配。
Windows x64 与 Linux x86_64 都是当前应用的使用平台。涉及文件系统、缓存、编译器、进程、动态库、环境安装或启动脚本的功能修改，应同时检查两侧的实现和测试入口。
- 文件系统可选能力应按运行环境检测，例如
os.supports_follow_symlinks，不能因为 Linux 接受某个参数就假设 Windows 也接受。缓存目录仍需验证普通目录、符号链接与 Windows reparse point；权限和真实 I/O 错误不能当成兼容问题随意吞掉。 - 编译与运行应覆盖 Windows 的
.exe、导入库/DLL、工具链路径、带空格路径和换行行为。进程锁、并发清理、异常退出应有可在 Windows 执行的测试。 - 平台专用的小型测试夹具可以明确限定平台，但不能代替跨平台集成测试。Windows CI 中必需的工具链缺失应失败，不能以整组跳过得到成功结论。
- 交付记录分别列出兼容代码、模拟测试、实际 Windows 测试的状态。只有实际 Windows 运行通过，才能声称 Windows 验收通过。缺少 Windows 环境时继续完成可做的修复和测试准备，并明确实机验证仍待完成。
- 本地虚拟环境、编译器、便携运行时和构建缓存保留在 Git 忽略目录，不随源码提交。
当前缓存检查入口：
$env:SIMULATION_NATIVE_REQUIRE_TOOLCHAIN = '1'
.\.venv-win\Scripts\python.exe -m unittest tests.test_native_cache_storage tests.test_native_cache_platform -v
该入口使用现有 SIMULATION_NATIVE_CC / SUNDIALS_ROOT 或构建器的默认探测；CI 配置在 .github/workflows/solver-regression.yml 的 native-windows 作业。
新增组件同样适用本约定：新增 C 模块应使用现有构建抽象和严格浮点设置，检查模块导出、传递依赖、对象复用、完整模型缓存、Windows 可执行文件与 DLL 发现；不要在组件脚本中写死 Linux 编译器、路径分隔或符号链接能力。
注册演练在 Linux 使用真实浏览器和 C 工具链执行；本次没有 Windows 实机环境，未宣称演练已通过 Windows 验收。复现工具使用 sys.executable、pathlib、无 shell 的编译调用；Windows 验收仍需实际执行。
当前工具链边界（2026-09-12 核对）
构建器只接受 Windows/Linux，默认寻找 gcc，或读取 SIMULATION_NATIVE_CC；使用 GCC 风格的预处理、目标查询和编译参数，不承诺 MSVC/macOS 支持。公共参数包括 C11、-O3 -Wall -Wextra -Werror -ffp-contract=off -fno-fast-math。Windows 另加 MinGW printf 与静态 libgcc 选项，Linux 添加 POSIX 宏。
SUNDIALS_ROOT 指向开发文件根目录：Windows 使用 lib/sundials_*.lib 和 bin/sundials_*.dll，将依赖 DLL 随模型复制；Linux 使用探测目录中的 libsundials_*.a 静态链接。当前五个链接库为 cvode、core、nvecserial、sunmatrixdense、sunlinsoldense，RK45 构建也使用这套共用程序。
CI 的 native-windows 配置了 MinGW、SUNDIALS、缓存回归、后端完整回归和原生 RK45 夹具；其存在不证明任意一次修改已经在 Windows 运行通过。本次仅核对配置并运行本机可执行检查，未取得新的 Windows 实机结果。