# MoonMatBridge 后续小版本计划：v0.0.6—v0.0.9

制定日期：2026-10-16。基线：已发布的 v0.0.5，提交 `b9df1eddaacdefebc2e32eee468fada8cc9e6020`。

本文件保留 2026-10-16 制定的开发与验收计划。以下分版本日期是最迟检查点，完成即可提前推进；性能数字是工程目标，实际结果以对应版本报告为准。优先顺序为：**初审问题闭环 → 正确性与兼容性 → 可复现的性能改善 → 科研工作流与展示**。10 月 29—30 日保留给复审跟进、最终验收提交与必要修正。

## 本轮交付索引（2026-10-17 更新）

| 版本 | 实质工作 | 验收证据 |
| --- | --- | --- |
| v0.0.6 | 全部公开基本类混合矩阵、Octave 双向互通、v0.0.5 固定基准 | `compatibility-v0.0.6.json`、`octave-v0.0.6.json`、`performance-baseline-v0.0.5.json` |
| v0.0.7 | 预检尺寸和共享固定缓冲写入，消除嵌套复制 | `performance-v0.0.7.json`、`performance-evaluation-v0.0.7.json` |
| v0.0.8 | 严格按需读取、根变量目录、未选数据仍完整校验 | `selection-v0.0.8.json`、`performance-v0.0.8.json` |
| v0.0.9 | 冻结 API、global 扩展矩阵、三个科研场景、公开消费复验与技术附件 | `workflows-v0.0.9.json`、公开下载流程回执、[复审索引](REVIEW_EVIDENCE-v0.0.9.md) |

表中是证据入口；通过状态、版本、哈希和运行环境以报告为准。源码、公开发布、报名回执、主办方验收与获奖分别记录。尚未关闭的标准变体继续阻止 v1.0 发布，详见 [兼容矩阵](COMPATIBILITY_MATRIX.md)。

## 1. 官方要求如何落实到版本

2026-10-16 核对了[十月黑客松官网](https://moonbitlang.github.io/Hackathon2026/)及其[官方页面源码](https://github.com/moonbitlang/Hackathon2026/blob/main/src/App.tsx)。本期报名与验收均在 **2026-10-31** 截止；通过验收的月度新项目进入当季度评选范围。官网列明十月最多提交 3 次，修改的时间会影响有效报名时间，因此应一次准备完整材料并核对已用次数。

| 当前官方要求或项目专项反馈 | 项目中的落实方式 |
| --- | --- |
| MoonBit 为主要实现语言 | 读写、压缩、选择读取和差异比较继续在 MoonBit 核心实现；宿主仅承担文件与进程接口 |
| 公开、连续、可追踪的开发 | 每项实质变更对应问题、提交、测试和更新记录，版本号与提交数量不作为贡献本身 |
| 可运行，具备清晰 README、示例与必要测试 | 三目标检查、独立工具交叉验证、干净环境安装及三个完整科研场景 |
| 本期工作实质有效，避免重复、拆分或简单修改 | 每版交付一项可验证改善，同一仓库持续演进；性能版提交原始测量结果 |
| 许可证及参考来源合规，参赛者理解成果 | 保持 LICENSE、THIRD_PARTY、接口边界一致；准备能够解释设计与测试的演示 |
| 本项目初审要求：明确最终范围，补充混合类型案例 | 以 [COMPATIBILITY.md](COMPATIBILITY.md) 的全部公开基本类 1—15 为终点，cell、struct、char、sparse 均属必交 |

官网强调工程边界、测试质量、可维护性和实际可用性。下文的性能数字、样例规模及发布检查是本项目制定的工程标准，**不是主办方公布的评分权重或获奖门槛**。

[正式章程](https://bxup9uklfcb.feishu.cn/wiki/Dx4Bwd6D1i3GfHkajQCcF7SznEd)本次无法重新读取。此前保存的正文含九月时间信息，因此不将其中的旧日期或未经复核的细则作为十月新增要求。最终以当前章程及主办方通知为准。

## 2. v0.0.5 基线与优先缺口

- 当前版本已有递归 cell/struct/char/legacy object、密集及 CSC、压缩读写。版本报告记录 JS、wasm-gc、native 各 59 项测试通过，SciPy/NumPy 独立验证 62 组通过；见 [版本报告](../verification/reports/v0.0.5.json)及[互操作报告](../verification/reports/interop-v0.0.5.json)。这些是 v0.0.5 对应提交的历史验证结果。
- 已有[混合文件](../examples/mixed/README.md)，但 MATLAB/Octave 实际生产、消费尚无运行回执；Unicode 维度、legacy object、非规范 CSC、旧名称编码需要逐项解决。基本类已具备代码入口，不等于全部标准变体已验证。
- 尚无正式耗时、吞吐量或峰值内存基准。不能把测试数量、压缩后的文件大小当作运行性能证据。
- [read_tree](../src/tree.mbt) 会构造全部根变量；当前 `select` 先完整读取，再挑选。只提取小部分数据时有优化空间。
- [encoded_node/write_tree](../src/tree.mbt) 为子节点建立临时缓冲，再逐层复制到父节点；[numeric_payload](../src/reader.mbt) 与解压路径也有临时数据复制。它们是待测热点，尚未通过剖析证明贡献比例。
- 原快照和 diff 仅支持数值/CSC，尚未覆盖完整混合树。扩展这一流程有辨识度，但不能挤占兼容性修复和提交时间。

## 3. 版本安排与退出条件

### v0.0.6：兼容性证据与性能基线（10 月 17—20 日）

**目的：优先消除初审拒绝理由，建立后续优化的可信起点。**

交付：

1. 建立基本类 1—15 的逐项读、写矩阵，列出大小端、压缩、空数组、多维、全局标记、嵌套关系、字符编码和字段顺序。只统计语义合法的组合；不适用项给出理由，未验证项单列。
2. 为 Unicode 代理项/维度、旧名称编码、legacy object、CSC 顺序与容量分别建立问题记录。标准允许且实际工具产生的文件应兼容；无法解决的合法变体不得记为“拒绝成功”。
3. 启动真实 MATLAB 或 GNU Octave 双向实验：工具产生 → MoonBit 读取/写回 → 原工具验证。工具无法覆盖的项保持未验证；legacy object 不能仅以该工具缺少类定义而判为本库通过。
4. 加入混合容器畸形字段表、截断、重复字段、深度/节点/元素预算等边界检查。独立验证不能只用本库自读自写。
5. 建立第 4 节的固定基准、原始结果格式和复现入口，保存 v0.0.5 的耗时、吞吐量、峰值内存与输出大小。

验收：所有公开基本类都有独立读取和消费输出的案例或明确未完成记录；三目标原有功能无回归；基准能够在同机重复运行。复审材料需明确“当前已完成”与“最终承诺”，随附混合文件和哈希。

**优先门槛：**10 月 20 日检查仍未完成的标准变体，先安排修复。MATLAB/Octave 实际回执最晚以 10 月 24 日为检查点；未完成时不得进入 v1.0 验收。当前 v0.0.5 已有的复审材料可先整理，不必等全部性能版完成。

### v0.0.7：减少读写复制（10 月 21—23 日）

**目的：在保持数据和错误语义的前提下降低耗时、内存。**

交付：

1. 根据 v0.0.6 的测量先优化占比最大的路径。优先尝试利用已有尺寸预检结果，为未压缩写入预分配输出、按位置写入，减少逐层构造临时字节数组。
2. 读取中的内部视图、字节序转换和必要的所有权复制分别处理；不为追求“零复制”改变公开接口的生命周期或可变性语义。
3. 检查解压中间缓冲和重复校验的成本。保留校验和、长度检查、资源限额与写出前验证，不以放宽检查换速度。

性能目标：在固定的 16 MiB 密集数组和 4 MiB 嵌套混合数组两个写入场景中，未压缩写入中位耗时较 v0.0.5 **下降至少 30%**、对应进程峰值内存 **下降至少 25%**；native、JS 分别报告，不能平均后掩盖某个目标退化。

验收：独立工具验证输出；原始 IEEE 位、整数、形状、字段顺序、全局标记及 CSC 存储语义保持。全部固定基准无可重复的超过 10% 的耗时或内存退化。压缩输出另外报告压缩率和耗时，不把文件变小直接计作速度改善。

### v0.0.8：按需读取（10 月 24—26 日）

**目的：解决只需要少量变量时仍构造整份文件的问题。**

交付：

1. 首先为未压缩 Level 5 增加根变量目录和选择读取接口；减少未选变量的数据复制与对象构造。以 16 个变量各 1 MiB、仅取其中一个为固定场景。
2. 根目录不对外暴露可缓存的偏移；所有变量继续完整验证，只减少未选数据的分配。本轮不提供跳过未选负载检查的快速模式。
3. 压缩文件继续有界解压。不能承诺“直接跳到压缩变量内部”；获取名称也可能需要解压。压缩选择读取作为单独场景披露成本，不纳入未压缩的速度承诺。
4. 核心接口仍接收内存字节时，报告中明确整个输入文件已在内存，不能称作流式读取或按需磁盘 I/O。

性能目标：上述未压缩选择场景，选择读取并输出的中位耗时相对 v0.0.5 至少 **加速 2 倍**，进程峰值内存 **下降至少 40%**。对选择全部变量、大量小变量和压缩文件分别检查退化。

验收：所选结果与完整读取后选择的数据完全一致；未选变量损坏、超限或不支持仍明确失败。输入整体驻留内存与压缩解码成本如实报告。

### v0.0.9：科研场景、证据和发布冻结（10 月 27—28 日）

**目的：让评委从安装到结果复现均可操作，并保留最终提交缓冲。**

必交：

1. 冻结接口、兼容矩阵、缺陷清单和性能报告；统一 README、申报材料、Mooncakes 文档和 release 说明中的能力范围。
2. 提供第 5 节三个完整场景及一个短演示；新环境使用公开包和下载文件复现，不依赖本机源码路径。
3. 保留三目标检查、构建、测试与独立交叉验证；生成与该提交绑定的报告、资产和校验值。
4. 核对有效报名记录与剩余修改次数，完成复审/最终验收材料包；表单提交和主办方审核结果分别留存回执。

后续功能版安排：**混合树精确 diff**。覆盖 cell/struct/char 与数值/CSC 叶子，报告根变量、字段、cell 下标、数组坐标和实/虚部分量；所有索引明确为零基。保持退出码 0/2/1，并用全局样本上限控制报告大小。

按确认后的执行计划，上述 diff、完整混合树快照/恢复、容差 diff、压缩随机读取和流式文件接口均放入后续功能版；本轮使用已有数值/CSC diff 完成科研场景验收。通过 v1.0 后为 v1.1；未通过 v1.0 时继续 0.x。

## 4. 性能验收方法

### 固定场景

| 编号 | 输入与操作 | 用途 |
| --- | --- | --- |
| D1 | float64，1/16/24 MiB 有效负载，小端和大端；读、写、往返分开 | 密集数组吞吐与字节序成本 |
| D2 | 16 MiB 总负载的 complex64/128，含独立的 NaN、负零、uint64 精确性样例 | 复数与保真路径 |
| M1 | 4 MiB 有效负载，cell/struct/char 混合，深度 1/8/32；另设大量小节点案例 | 嵌套复制和对象数量成本 |
| S1 | 1,000,000 × 1,000 CSC，100,000 个活动条目，实数/逻辑/复数分别生成 | 随 nnz 增长的开销，不按稠密尺寸分配 |
| C1 | 16 MiB 的全零、重复序列、固定种子随机数据；压缩与解压分别测量 | 压缩速度、展开内存及输出大小的取舍 |
| P1 | 16 个根变量，各 1 MiB；选择 1/16 与选择全部分别测量 | 按需读取收益与最坏情况 |

每份输入保存生成器、种子、维度、类型、字节数和 SHA-256；压缩用例同时记录展开大小。生成器须确认文件大小、总元素及树节点在配置限额内，不能因超限拒绝很快而记为高性能。更大文件需单独说明限额及机器条件，不混入默认配置成绩。

### 测量规则

1. 同机、同工具链、同优化等级、同输入，使用 v0.0.5 固定提交重新构建作为对照。新兼容场景若基线无法正确处理，标为无可比基线；不能把失败时间当性能。必要时使用 v0.0.6 的正确实现作为该场景的独立对照并标注。
2. 分两层测量：核心编解码计时排除文件生成、读写盘和进程启动；CLI 另测端到端耗时并包含这些真实运行成本。核心输出在计时外校验/消耗，防止测量无效调用。
3. 核心预热 5 次，每个版本、目标、场景测量 3 批、每批 10 次；两版本交错运行，保存全部样本，报告中位数与 p95。运行环境繁忙或波动明显时标为不稳定，查明后复测，不只取最快值。
4. 内存用独立子进程测量，Windows 记录进程峰值工作集，Linux 记录峰值 RSS；同时保存指标名称和采样方式。不能使用父进程内存，也不能把不同操作系统的绝对值合并比较。JS 主机开销计入其进程指标。
5. native 和 JS 均测性能；wasm-gc 继续验证正确性，未测其性能时明确标注。基准包含机器、操作系统、MoonBit/编译器、Node、构建参数和提交 SHA。
6. 吞吐量按处理的有效负载 MiB/秒计算；压缩读取另外列文件字节与展开字节。报告输出大小，避免以严重增大文件为代价却仅展示更快的压缩结果。
7. 正确性失败直接判为该组不合格。性能目标未达时如实标注；允许发布兼容性修复，但不得将其记为性能版完成，也不能临时删除不利样例。

产物：`benchmarks/manifest.json`、可复现运行入口、`verification/reports/performance-vX.Y.Z.json` 和 [结果摘要](PERFORMANCE.md)。原始计划制定时尚无正式性能成绩；后续结果与目标是否达到由每版报告分别记录。

## 5. 展示实际价值的三个完整场景

1. **混合实验数据归档。** 从实验参数 struct、分组 cell、中文标签 char、复数信号和 uint64 样本编号组成的文件开始；MoonBit 检查与写回；独立工具核对类型、维度、字段顺序、字符存储单位和有效数据。提供原件、输出、验证结果。
2. **大型稀疏仿真结果交换。** 读取大形状、少量非零项的 CSC，与配置元数据放在同一文件，选择所需变量再写回；独立工具确认容量及有效条目。报告峰值内存，证明操作保持稀疏；保留显式 densify 超限检查。
3. **NumPy 与 MoonBit 计算流程验收。** 从 NPY 数值数组进入 MAT，执行切片/整形/轴置换，导出并由 NumPy 核对；对相同与人为改变的两个结果运行现有数值 diff，验证坐标和退出码。完整混合树 diff 仅在实际完成后加入演示。

三个场景都附输入来源/生成步骤、安装方式、一键复现入口、预期结果和失败示例。真实外部采用或反馈如存在则附证据；没有时表述为可复现示例，不假称用户数量、下载热度或同类项目绝对不存在。

## 6. v1.0 与比赛提交门槛

继续保留 [COMPATIBILITY.md](COMPATIBILITY.md) 中 **10 月 28 日目标 v1.0** 的安排；它是验收节点，不是按日期自动升级版本。达成全部范围承诺后可发布 v1.0.0，未达则保留 0.x 和剩余问题。

必须同时具备：

- 公开基本类 1—15 的合法读写范围与逐项证据；任何已知标准变体缺口均已解决，或者明确仍未达到完整兼容终点。
- 真正执行过的 MATLAB/Octave 双向回执，以及独立验证对工具差异的解释；不能将 SciPy 的成功写成 MATLAB 已验证。
- 三目标检查、构建、测试成功；公开包的干净消费者与下载资产校验成功。
- 已承诺的性能结果可复现，全部测试和性能报告绑定准确提交；没有通过关闭必要验证获得的收益。
- 混合案例、文档、发行说明、申报范围一致，问题与限制可查。

v1.0 的兼容终点不要求某个自定加速倍数，也不要求 P1 的混合树 diff；这些成果影响性能/功能版是否完成，应分别如实报告。不能因性能目标未达而缩减标准类型范围，也不能用漂亮的性能图替代兼容性证据。

复审安排：先核对已有提交和可修改入口，在材料足以回应初审意见时尽早更新；不要等 10 月 31 日才操作。10 月 29—30 日用于最终验收和补正，具体渠道按主办方通知。报名/验收回执、审核通过与获奖是三个不同状态，公开发布不自动代表其中任何一个。

## 7. 时间不足时的取舍

优先级：标准兼容与复审 > 测试及真实互操作 > 经测量的热点优化 > 按需读取 > 混合树 diff > 其他新格式。

10 月 20 日若兼容问题未收敛，v0.0.7 先处理兼容修复；10 月 24 日若真实工具验证仍未完成，暂停 P1 功能并集中补证；10 月 27 日冻结新能力，仅处理已知缺陷和交付问题。版本日期可以调整，必交范围与验证真实性不能调整。

本轮不安排 MAT v7.3/HDF5、GUI、NPZ 大扩展、云服务或 MATLAB 私有运行时对象。资源优先用于把已承诺的 Level 5 科研交换流程做到可靠、可测、可复现。