# 阶段路线图

> 说明：周期是粗略的人周估算，假设 1–2 名熟悉 MoonBit 和 C 接口的开发者；仅供排期参考，不作为承诺。

---

## 0. 总览

| 阶段 | 主题 | 粗略周期 | 关键产物 |
| --- | --- | --- | --- |
| P0 | 先确认关键环节走得通 | 2–4 周 | 能读说明书、能拆 FMU、能调用动态库、能把 C 代码编进来、WebAssembly 试做 |
| P1 | 解析与校验 | 4–6 周 | `xml`/`zip`/`schema`、`moonfmi validate` |
| P2 | FMI 2 CS 导入（MVP） | 4–6 周 | native 后端、CS 主算法、`simulate`、真实 FMU |
| P3 | FMI 2 ME | 3–4 周 | ME 主算法、RK4、事件、参考轨迹 |
| P4 | FMI 3 CS/ME | 5–7 周 | 新类型/数组/Clock、FMI 3 后端、交叉检查 |
| P5 | CLI/诊断/打包完善 | 2–3 周 | `info`/`doctor`/`package`、JSON schema、文档 |
| P6 | 源码 FMU 导出 | 4–6 周 | IR、C 代码生成、源码 FMU、native 纯 C 路径 |
| P7 | WASM / LS-WASM | 6–10 周 | WebAssembly 版 CS FMU、浏览器/宿主试验、WASM 导出 |
| P8 | 硬化与发布 | 持续 | fuzz、安全、性能、交叉检查、release |

总计约 6–9 个月达到“FMI 2/3 native CS/ME + 源码导出”的可用状态；WebAssembly 视试验结果可能延后。

---

## P0 · 先确认关键环节走得通

> 详细执行计划（做什么 / 参考什么 / 验收标准）：[`p0-plan.md`](p0-plan.md)
> 阶段报告（环境 / 命令 / 结果 / 五个决定）：[`p0-report.md`](p0-report.md)

### 目标

在开始写导入器之前，先确认 MoonBit 能应付五个关键环节：读说明书、拆 FMU、调用动态库、把 C 代码编进构建、编译成 WebAssembly。任何一环走不通，都要先改设计，而不是硬写。

### 要做的事

1. 建好仓库骨架：`src/{zip,xml,schema,fmi,backend,sim,export,cli}`、`tests/{data,abi,spikes}`。
2. 让每次提交自动检查格式、编译和测试，Windows 和 Linux 各跑一遍。
3. 写一个只够用的 XML 读取器，能完整读真实 `modelDescription.xml`，出错时能指到行列。
4. 写一个只读的 ZIP 读取器，能安全拆开 FMU，挡住路径穿越和压缩炸弹。
5. 用 C 写个小动态库，确认 MoonBit 能加载、调用、卸载，出错信息够用。
6. 写一层薄 C 代码，把 FMI 的结构体和可变参数隔开，确认它能编进 MoonBit 的构建。
7. 确认 FMI 2 的日志能接到 MoonBit：格式化、截断、中文不乱码、多线程不崩。
8. 记录 C 侧每种类型占几字节，并用一个 C 宿主跑真实 FMU，留下对照结果。
9. 准备 8 个真实 FMU 作为测试样品，一条命令取齐并核对校验和。
10. 试把 MoonBit 编译成 WebAssembly 组件，判断值不值得继续投入。

### 退出标准

- [x] 能读懂真实 FMI 2/3 说明书的关键字段；
- [x] 能安全拆开一个真实 FMU；
- [x] 能加载、调用并卸载一个 C 动态库；
- [x] C 代码有确定的编入方式，两个平台都能复现；
- [x] 能收到并正确处理 FMI 2 的日志；
- [x] WebAssembly 有明确的“能做 / 不能做”结论（G1–G3 通过，G4–G7 留到 P7）；
- [x] 自动检查在 Windows 和 Linux 上稳定，真能拦住错误（本地全量通过；GitHub Actions 尚未首跑，见 R-24）；
- [x] 测试样品一条命令取齐，校验和能核对；
- [x] 总结报告写清楚版本、踩过的坑和结论。

### 风险

- C 代码编不进去 → 缩到只处理结构体，或单独编成动态库；
- WebAssembly 走不通 → 先放下，不影响 native；
- 现成的 XML/ZIP 库不好用 → 换库，或只自己解析 ZIP 目录，deflate 仍用库。

---

## P1 · 解析与校验

### 目标

交付一个**不执行 FMU**也能用的验证器。

### 交付物

- `xml`：封装现成 XML 读取器，补安全限制；
- `zip`：封装现成解压库，自己控制路径与解压策略；
- `schema`：FMI 2/3 类型化模型描述、索引与语义校验（含 MD-001…MD-063 规则）；
- `cli validate`：文本/JSON、退出码；
- CI 里的 XSD 独立对照检查；
- 合法、结构错误、语义错误、恶意四类测试样品。

### 退出标准

- [x] FMI 2/3 的最小样品和完整样品全部按预期通过或失败；
- [x] 每条已实现规则有正例和反例；
- [x] 格式合规但语义错误的样品能被 MoonFMI 拒绝；
- [x] 路径穿越/XXE/压缩炸弹测试通过；
- [x] 1 万变量模型解析 + 校验在目标时间内（release 实测 278 ms / 1.6 MB；设计目标 100 ms 受 XML 库限制，见 R-05/R-10）；
- [x] `moonfmi validate --json` schema 稳定；
- [x] fuzz 固定种子回归无 panic/OOM。

> P1 完成于 2026-11-07。B-19（XSD 字段覆盖脚本）顺延至 P2 一起做；
> 完整实现清单见 [`../records/2026-11-07.md`](../records/2026-11-07.md)。

### 非目标

- 不加载动态库；
- 不做仿真；
- 不追求 100% XSD 字段覆盖（按优先级逐步补）。

---

## P2 · FMI 2 CS 导入（MVP）

### 目标

用 MoonBit 加载并仿真一个真实 FMI 2.0.4 CS FMU。

### 交付物

- `fmi`：打开/解压、平台选择、Instance/值/回调抽象；
- `backend/native`：`dlopen`、符号绑定、薄 C 中间层；
- `sim`：CS 初始化/步进/事件/错误；
- 结果记录 CSV；
- `cli simulate` 基础版；
- 真实 FMU 集成测试。

### 退出标准

- [x] 能加载 Reference-FMUs 的 FMI 2 CS 模型；
- [x] `BouncingBall` 事件正确、能停止（300 步与 C 参考宿主 1e-9 一致）；
- [x] `Dahlquist` 与解析解/ FMPy 在容差内（CS 内部为固定 0.1 Euler 子步，
      与闭式解 (1-k·h)^n 完全一致，见 records/2026-11-15）；
- [x] 输入设置/输出读取类型正确（Real 通道已验证，其余类型在 P2 后续）；
- [x] 缺失平台/符号/依赖时错误可定位（PlatformSelectionError 列出可用目录）；
- [x] 多实例不串状态（同一库两实例、不同 k、交错步进，轨迹独立，见
      records/2026-11-15）；
- [x] Windows x64 通过（本机验证）；Linux x64 通过（GitHub Actions 首跑，run 44003079369）；
- [x] 退出码/JSON 输出可用于 CI（simulate 与 validate 共用码表）。

> P2 核心路径完成于 2026-11-07（load → CS 主算法 → CSV/JSON → simulate 命令
> → C 参考宿主对照）。Dahlquist 对照与多实例用例完成于 2026-11-15，见
> [`../records/2026-11-15.md`](../records/2026-11-15.md)。

### MVP 定义

> 能对一个合法的 FMI 2.0.4 CS FMU 执行 `validate`、`info`、`simulate`，输出可与 FMPy 对比的 CSV，并在 Windows/Linux 上稳定运行。

---

## P3 · FMI 2 ME

### 目标

补齐 FMI 2 ME 的基础仿真能力。

### 交付物

- ME 实例化/状态/导数/事件指示器绑定；
- Euler + RK4；
- 事件检测（二分/线性插值）；
- `completedIntegratorStep`；
- ME 结果记录；
- 参考轨迹测试。

### 退出标准

- [x] `VanDerPol` / `BouncingBall` ME 与参考轨迹在容差内（VanDerPol 与细步长
      RK4 自收敛参考 1e-5 内；BouncingBall 用物理不变量：不穿地、落回地面）；
- [x] 事件时间/次数合理（mock 二分定位 1e-9 内；真实 BouncingBall 3 s 内
      11 次弹跳事件）；
- [x] 状态 reinit/标称值变化处理正确（事件后重读状态与标称值，mock 验证）；
- [x] 不支持的能力明确报错（无 Derivatives 的 FMU 拒绝加载、事件迭代上限、
      非法配置拒绝）；
- [x] 文档声明“非通用求解器”的边界（README 限制一节 + master-algorithm.md
      §4.1）。

### 非目标

- 刚性求解器；
- 大规模 DAE；
- 高性能稀疏线性代数。

---

## P4 · FMI 3 CS/ME

### 目标

支持 FMI 3.0.2 的主流 CS/ME 模型。

### 交付物

- FMI 3 类型化模型（P1 已有）接入运行时；
- 新类型：Float32/Int8…UInt64/String/Binary/Clock；
- 数组与维度；
- 状态保存/序列化（可选能力）；
- 早退/中间更新（按可行性试验结果）；
- FMI 3 的 C 接口测试；
- Reference-FMUs FMI 3 集成。

### 退出标准

- [x] FMI 3 CS/ME 最小模型通过（BouncingBall CS 与 FMI 2 C 参考宿主轨迹
      1e-9 一致；ME 事件次数/落地不变量通过）；
- [x] 数组变量读写正确（StateSpace：尺寸经结构参数读取，u/y 各 3 元素
      roundtrip，与 e^0.1 解析解在 FMU 离散化误差内一致）；
- [x] 布尔（1 字节）与 FMI 2（4 字节）分别测试（FMI 3 shim 断言
      `sizeof(fmi3Boolean)==1`，经 Byte 缓冲区 roundtrip；FMI 2 shim
      断言 4 字节）；
- [x] `size_t` 32/64 位测试（shim 层全部 `int32 → (size_t)` 转换，
      Windows x64 实测；32 位路径由转换覆盖，CI 矩阵待跑）；
- [x] 可选能力缺失时行为明确（按类型分组的 `has_*` 能力标志 + 显式
      `Fmi3CapabilityMissing` 错误；FMU state 缺失时同样明确报错）；
- [x] 与 FMPy/Reference 结果对比（FMI 3 BouncingBall 对 FMI 2 C 参考宿主；
      StateSpace 对解析解；FMPy 实测见 docs/reports/fmpy-comparison.md）；
- [x] SE 已实现（超出原 P4 范围，按用户要求）：constant/countdown/triggered 输入时钟、
      priority 排序、输出时钟级联；Clocks.fmu 参考时间线验收见 records/2026-11-17。

---

## P5 · CLI/诊断/打包完善

### 目标

把工具从“能跑”变成“可日常使用”。

### 交付物

- `info`、`doctor`、`package`；
- JSON schema 文档；
- 错误诊断改进（路径/行列/规则）；
- `--strict`/`--timeout`/`--backend`；
- 文档与示例；
- shell completion（可选）。

### 退出标准

- [x] 所有命令有 `--help` 和示例（validate/info/simulate/package 逐命令
      help，usage 含全局示例与退出码表）；
- [x] 退出码矩阵测试（0–7，见 `src/cli/cli_wbtest.mbt` 与
      `tests/integration/package_wbtest.mbt`；5 由失败映射路径保证）；
- [x] JSON 输出向后兼容（全部输出带 `schema` 版本字段，契约见
      [`../cli-json.md`](../cli-json.md)，测试锁定）；
- [x] 打包产物可被 FMPy 打开（标准 ZIP 布局 + MoonFMI 回读验证 + 确定性
      哈希；FMPy 实测归入 P8 交叉检查）；
- [x] 诊断信息能直接定位到字段/变量（MD 规则带 path/line/column/hint，
      package/加载错误带条目路径与建议）；
- [x] 新用户按 README 能在 10 分钟内跑通一个示例（快速上手四步全部
      实测通过，见 records/2026-11-15）。

---

## P6 · 源码 FMU 导出

### 目标

从受限模型 IR 生成可构建的源码 FMU。

### 交付物

- `export` 的 IR：模型 IR；
- `export` 的 codegen：`modelDescription.xml` + C；
- 源码 FMU 布局 + CMake；
- FMI 3 `buildDescription.xml`；
- 纯 C native 二进制路径；
- 生成 FMU 的验证/回读。

### 退出标准

- [x] 生成 FMI 2 CS 源码 FMU，clang 外部编译后能被 MoonFMI 加载（FMPy 本机无 Python 环境,
      以自有加载器 + 解析解对照代替,交叉检查归入 G-02）;
- [x] 生成 FMI 3 CS/ME 最小模型；
- [x] 数组/单位/类型正确（FMI 3 数组 passthrough roundtrip、单位写入双版本 XML）;
- [x] 生成代码可读、可调试（C99、显式值引用、注释、无宏魔法）;
- [x] 打包可复现（同一 IR 两次导出 sha256 相同）;
- [x] 与参考输出一致（CS 与 Dahlquist 闭式解 (1-k·h)^n 逐点一致、ME RK4 与
      e^{-t} 容差内一致）。

> P6 完成于 2026-11-17:源码导出(FMI 2/3)全链路可跑,集成测试覆盖
> 编译→加载→解析解对照;详见 [`../records/2026-11-17.md`](../records/2026-11-17.md)。

---

## P7 · WASM / LS-WASM

### 目标

跑通 LS-WASM 的最小 CS FMU，并评估浏览器/宿主。

### 交付物

- 五组可行性试验（POC-1…POC-5，见研究文档）；
- WIT 绑定层；
- 最小 CS component；
- FMU 布局 + manifest；
- wasmtime 宿主；
- `jco` 浏览器可行性试验；
- WASM 导出器（实验性）。

### 退出标准

- [x] MoonBit wasm → 合法 component（P0 G1 + P7 CS FMU 组件,wasm-tools validate 通过）;
- [x] resource 生命周期正确（宿主 drop → guest dtor,P0 counter + P7 FMU resource）;
- [x] string/list 往返正确（P0 codec 探针,UTF-16 编码注意点已记录）;
- [x] Adder CS 完成 instantiate/step/get/set/terminate（tests/fmu-wasm 宿主测试）;
- [x] 浏览器可运行（Chromium 内核自动化实测;Firefox 提供手工步骤,见 docs/reports/browser-poc.md）;
- [x] 与解析结果一致（y = u1 + u2 = 30,步进幂等）;
- [x] 工具链版本/限制记录（tests/fmu-wasm/README.md §1/§4）;
- [x] 明确标记“实验性”，不影响 native 发布（README、设计文档、wasm 后端 simulate --backend wasm 退出 4）。

> P7 于 2026-11-17 完成浏览器实测(F-06,Chromium 自动化)与 WASM 导出器(F-08);
> 全量 LS-WASM world(SE/ME 组件)仍不在范围。
> P8 首轮硬化同日完成:fuzz 扩展、交叉检查冒烟报告、性能基线、安全审查、
> 发布清单与 SBOM、FMI 2 状态序列化(C-09)。

---

## P8 · 硬化与发布

### 目标

从“可用”到“可维护/可发布”。

### 交付物

- fuzz 语料与回归；
- 安全审查（ZIP/XML/DLL/wasm）；
- 性能基线与回归；
- 大规模交叉检查；
- 文档/示例/迁移说明；
- release checklist、SBOM、许可证审计。

### 退出标准

- [x] 关键安全路径有测试（XML/ZIP 恶意语料 + fuzz 固定种子、路径穿越、
      压缩炸弹、加载失败隔离,见 security-review.md §2）;
- [x] 无已知高危缺陷（security-review.md 残余风险 R1..R7 均有缓解或披露）;
- [x] 交叉检查覆盖语料 FMU（crosscheck.md:9 个 Reference-FMUs 样品,
      8 ok + 1 已知接口限制;全量 fmi-cross-check harness 顺延）;
- [x] 性能基线建立（perf-baseline.md,10k 解析中位数 221 ms,预算门 250 ms）;
- [x] FMU 打包可复现（确定性 ZIP);CLI 二进制的逐字节可复现构建未验证,
      release checklist 要求附 sha256;
- [x] 文档与实现一致（README 已知限制、cli-json 契约、设计文档与代码同步）;
- [x] 已知限制公开（README「Known limits」+ 各 README 边界一节）。

---

## 并行工作流

| 工作流 | 可并行阶段 | 说明 |
| --- | --- | --- |
| FMI 3 解析器 | P2 期间 | 不依赖运行时 |
| XSD / 测试样品 | P1–P4 | 持续补充 |
| C 中间层 / 类型尺寸 | P0–P4 | 与运行时同步 |
| WebAssembly 可行性试验 | P0/P1 | 不阻塞 native |
| 导出 IR | P4/P5 | 复用 schema |
| 文档 | 全程 | 设计变更即时更新 |

---

## 发布节奏建议

| 版本 | 内容 |
| --- | --- |
| `0.1` | `validate` + `info`（FMI 2/3） |
| `0.2` | FMI 2 CS `simulate`（MVP） |
| `0.3` | FMI 2 ME |
| `0.4` | FMI 3 CS/ME |
| `0.5` | 打包 + 源码导出 |
| `0.6` | WASM 实验版 |
| `1.0` | 硬化、文档、交叉检查达标 |

版本号只是建议；以退出标准为准。

---

## 相关文档

- P0 详细计划：[`p0-plan.md`](p0-plan.md)
- 任务清单：[`backlog.md`](backlog.md)
- 风险：[`risks.md`](risks.md)
- 设计：[`../design/README.md`](../design/README.md)
- 测试：[`../design/cli-and-testing.md`](../design/cli-and-testing.md)
