Vitro 工程债务偿还维护方案

最后核对：2026-10-04（全库逐份翻新第三轮——修复追踪引言改指归档〔追踪使命随 Rust 冻结终局〕；任务 E 验收项 wasm32 进 CI 翻绿与 wasm-gc 落地注记随 09-29 批在案。前一沿革 2026-09-27 补 Rust 冻结态注记、D14/D16 销账回填） 本方案基于 2026-06-15 全面评估结果制定，目标是在不破坏现有功能的前提下，系统化偿还工程债务，提升项目长期可维护性。

2026-10-05 删区终局注记：native/ Rust 区已随 S9 工序④物理删除——下条「冻结态注记」所称维护态终止，Rust 侧历史债务（含 D11/D13/D15 活账目）随对象删除终局（载体不存在即无治理对象；条目文本保留为登记史）。MoonBit 活跃区新增债务照旧走总计划 §10.5 G 系列治理；正文大量 native/ 路径与 Rust 条目为历史口径（tag rust-oracle-freeze 可回溯）。 2026-09-27 冻结态注记〔——已被上条删区终局取代〕：native/ Rust 区已冻结为差分对照 oracle（tag rust-oracle-freeze，只收安全修复与防线维护），本方案的 Rust 侧债务治理转入维护态——D14/D16 已于 2026-09-12 重构批次 R4 销账，D11/D13/D15 仍为活账目；新增债务在 MoonBit 活跃区走总计划 §10.5 G 系列治理。§二/§三及以下正文的数字与状态保留 as-of 2026-09-11 口径（逐项现状以各条销账批注为准），历史推进记录一律不改写。本文件继续承载 TODO注释规范.md 依赖的 #DXX 债务编号体系：编号不删除、不重排，消解项保留编号并注明消解原因。

2026-09-11 前端切割口径：CideFlutter/、FRB 桥接（native/src/api/ + frb_generated）、web 部署 workflow 与全部 Flutter 构建脚本已从仓库移除，本仓库转型为纯后端「三出口一核心」（核心 = Rust workspace，出口 = C ABI / wasm32 / vitro_cli serve），决策见 后端定位与白箱计划.md。§二/§三/§四/§五/§六/§八 中凡涉及前端路径或前端任务的条目，均已改写为后端现状或标注「（前端资产，已迁出）」/「已随前端切割消解（2026-09-11）」；§七「修订记录」及所有带日期的历史推进记录一律保持原样，不改写历史。本文件继续承载 TODO注释规范.md 依赖的 #DXX 债务编号体系：编号不删除、不重排，消解项保留编号并注明消解原因。

一、背景与目标

1.1 背景

Vitro 项目已完成 Phase 0 ~ Phase 41 的大规模功能建设，C/C++ 教学子集支持度较高，测试防线基本健全。但在快速迭代过程中积累了以下工程债务：

• 超大源码文件导致审查与维护成本上升
• 生成代码与手写源码混管
• 前端大文件职责过重
• C++ 扩展模块间耦合度快速上升
• 部分文档数据口径不一致
• 缺少项目级 lint 配置
• 失败记录文件中已修复条目稀释活跃问题

1.2 目标

1.3 核心原则

1. 功能优先：所有重构必须保证现有测试防线全绿，禁止以偿还债务为名破坏功能。
2. 最小侵入：每次变更只处理一个明确的债务点，避免大范围重写。
3. 诚实记录：重构过程中发现的新问题必须立即记入对应 *_FAILURES.md 或新增 TODO 标记。
4. 持续集成：任何拆分或重构必须通过 CI 全部 job 验证后方可合并。

二、工程债务清单与优先级

三、阶段规划

第一阶段：清理与对齐（P0，预计 1 周）

目标：消除数据不一致与生成代码管理问题，为后续重构建立干净基线。

任务 1.1：统一 Shadow Verification 数字口径

• 涉及文件：
  • README.md
  • AGENTS.md
  • CHANGELOG.md
  • native/tests/TEST_REPORT.md
  • reports/three_tier_report.md（如存在）
• 执行步骤：
  1. 运行 go run ./scripts/shadow_verify 获取最新实测数据。
  2. 运行 go run ./scripts/shadow_verify_cpp 获取最新 C++ 数据（Python 版已随 D5 退役）。
  3. 运行 go run ./scripts/serve_smoke 获取 serve 冒烟断言数（自报口径）。
  4. 统计当前真实匹配数、编译缺口数、运行时缺口数、输出差异数。
  5. 统一所有文档中的数字，注明统计日期与工具版本。
• 验收标准：所有文档中 Shadow Verification 数字完全一致，CI 不因此报错。
• 风险：数字更新可能暴露新的未记录差异，需同步更新 *_FAILURES.md。

任务 1.2：将 FRB 生成文件彻底移出版本控制 ✅ 已完成（2026-09-11 随前端切割整体消解）

• 实际结果（2026-09-11 复核）：原「移动出版本控制」的对象已不存在 —— FRB 出口层 native/src/api/、生成物 native/src/frb_generated.rs 已删除，Cargo.toml 移除 flutter_rust_bridge 依赖（native/Cargo.lock 亦无该包）；前端侧生成绑定随 CideFlutter/ 一并迁出（标签 before-frontend-split）。因此无需再执行 git rm --cached。
• 核实记录：
  • Test-Path native/src/api / native/src/frb_generated.rs / CideFlutter → 均为 False；全仓 .dart 文件数为 0。
  • .github/workflows/ 仅剩 ci.yml，且只有 rust 一个 job；deploy_web.yml 已删除。
• CI 校验口径改写（纯后端三出口）：
  1. 出口 3（serve）：go run ./scripts/serve_smoke —— 已在 CI（ci.yml「vitro_cli serve smoke (Exit 3 protocol contract)」步骤）。
  2. 出口 1（C ABI）：Shadow Verification（C 675 用例 / 匹配 668；C++ 99 用例 / 匹配 95 —— 见 reports/facts.json，as_of 2026-09-15）+ scripts/ci_three_tier_check 带牙齿一致性检查 —— 已在 CI。
  3. 出口 2（wasm32）：cargo build --target wasm32-unknown-unknown --release + Node 冒烟 —— ✅ 已进 CI（2026-09-12 重构批次 R4 固化 scripts/wasm_smoke/wasm_smoke.js 并接 ci.yml wasm32 构建/冒烟步骤；见路线图 G2）。
  • 原「CI Rust job 与 Flutter job 均执行 flutter_rust_bridge_codegen generate」的要求作废（无 Flutter job，无 FRB 依赖）。
• 验收标准（改写后）：
  • git ls-files | grep -i frb_generated 无输出（生成物与依赖均已移除）。
  • CI 的 rust job 全绿，含 serve 冒烟与 Shadow 门禁。
  • wasm32 出口检查在 Phase 2a 进 CI 前，由维护者手工执行并在 CHANGELOG.md 记录结果。
• 风险：无（对象已删除）；历史产物可取回 —— 标签 before-frontend-split。

任务 1.3：归档或清理已修复的失败记录条目

• 涉及文件：
  • FUZZ_FAILURES.md
  • HOST_CONTRACT_FAILURES.md
  • BYTECODE_LIBC_FAILURES.md
  • DIFFERENTIAL_FAILURES.md
  • GOLDEN_FAILURES.md
• 执行步骤：
  1. 遍历各失败记录文件，识别标记为“已修复”的条目。
  2. 将已修复条目迁移至 docs/archive/failures_archive_2026.md，保留历史轨迹。
     • ⚠️ 2026-09-11 核对：该归档文件至今不存在（docs/archive/ 下无 failures_archive_2026.md）， 即本步骤尚未执行，各 *_FAILURES.md 仍同时承载历史与活跃条目——如实记录为此任务的未完成项。
  3. 在活跃失败记录文件中仅保留当前已知失败与边界说明。
  4. 更新 scripts/ci_three_tier_check 的解析逻辑，确保归档后仍能识别历史记录。
• 验收标准：活跃失败记录文件中至少 70% 条目为当前问题或边界说明；CI 一致性检查通过。
• 风险：归档过程可能误删仍有效的已知失败，需逐条人工复核。

任务 1.4：完成 ROADMAP_2026_Q3.md 迁移 ✅ 已完成

• 实际结果（2026-09-11 复核）：文件现位于 docs/archive/ROADMAP_2026_Q3.md（Test-Path 为 True），docs/current/ROADMAP_2026_Q3.md 已不存在 —— 迁移已落地，无需再决定存放位置。
• 验收标准（已满足）：git status 不再显示该文件相关未提交状态。

第二阶段：文件拆分与模块化（P1，预计 3 周）

目标：降低超大文件认知负荷，提升模块边界清晰度。

任务 2.1：拆分 crates/vitro_codegen/src/expr.rs

• 拆分策略：
  • 保留 expr.rs 为入口文件，导出 gen_expr 等公共函数。
  • 按表达式大类拆分为子模块：
    • codegen/expr/literal.rs：字面量、常量、字符串
    • codegen/expr/binary.rs：二元运算、逻辑运算、逗号运算符
    • codegen/expr/unary.rs：一元运算、自增自减、取地址、解引用
    • codegen/expr/call.rs：函数调用、方法调用、函数指针调用
    • codegen/expr/struct.rs：结构体/联合体访问、成员地址
    • codegen/expr/array.rs：数组索引、指针算术
    • codegen/expr/cast.rs：类型转换
    • codegen/expr/new_delete.rs：new/new[]/delete/delete[]
• 执行步骤：
  1. 提取 gen_expr 内部的 match 分支到各子模块。
  2. 保持 BytecodeGen struct 不变，子模块通过 impl BytecodeGen 添加方法。
  3. 每拆分一个子模块，运行 cargo test --workspace --all-features 验证。
• 验收标准：
  • expr.rs 行数降至 600 行以内。
  • 所有 Rust 测试通过。
  • Shadow Verification 无新增失败。
• 风险：拆分时可能破坏 self 可变借用模式，需利用 Rust 借用检查器逐步调整。

任务 2.2：拆分 crates/vitro_parser/src/lib.rs（原 native/src/compiler/parser/mod.rs）

• 拆分策略：
  • 保留 parser/mod.rs 为模块入口与核心状态机。
  • 按语法结构拆分为子模块：
    • parser/decl.rs：变量声明、函数声明、结构体/联合体/枚举声明
    • parser/stmt.rs：语句解析（if、while、for、switch、return 等）
    • parser/expr.rs：表达式解析
    • parser/type_.rs：类型说明符、声明符、抽象声明符
    • parser/cpp.rs：C++ 专属语法（class、模板、构造析构、引用）
• 执行步骤：
  1. 将 parse_xxx 方法按主题迁移到子模块。
  2. 在 parser/mod.rs 中 pub use 需要的函数。
  3. 处理 Parser 内部字段访问权限，必要时添加 getter。
• 验收标准：
  • parser/mod.rs 行数降至 1000 行以内。
  • 所有 Rust 测试通过。
  • C/C++ Shadow Verification 无新增失败。
• 风险：Parser 内部状态高度耦合，拆分可能暴露隐式依赖，需小步提交。

任务 2.3：拆分 crates/vitro_vm/src/host_funcs.rs（原 native/src/vm/host_funcs.rs）

• 拆分策略：
  • 保留 host_funcs.rs 为注册入口与公共工具函数。
  • 按功能拆分为子模块：
    • crates/vitro_vm/src/host/memory.rs：malloc/free/realloc/calloc
    • crates/vitro_vm/src/host/string.rs：strlen/strcpy/strcmp/memcpy 等
    • crates/vitro_vm/src/host/io.rs：printf/scanf/fprintf/fgets 等
    • crates/vitro_vm/src/host/file.rs：fopen/fread/fwrite/fclose 等
    • crates/vitro_vm/src/host/math.rs：sin/cos/sqrt/pow 等
    • crates/vitro_vm/src/host/misc.rs：rand/srand/exit/qsort 等
• 执行步骤：
  1. 将 host 函数按功能迁移。
  2. 提取共享工具如 parse_format_spec、write_memory 到 vm/host/utils.rs。
  3. 更新 host_func_id.rs 与注册逻辑。
• 验收标准：
  • host_funcs.rs 行数降至 600 行以内。
  • Host Contract 测试、Fuzz 测试、Shadow Verification 全绿。
• 风险：部分 host 函数共享全局状态（如 VFS、堆管理），拆分需保持状态访问路径一致。

任务 2.4：拆分 CideFlutter/lib/screens/ide_screen.dart（前端资产，已迁出）✅ 已随前端切割消解（2026-09-11）

本条关闭：对象为前端资产，已随 CideFlutter/ 整体迁出（标签 before-frontend-split）。历史成果：896 → 299 行、新增 6 个组件（见 §六 D06 备注）。以下策略与验收标准保留作历史参考，不再推进。

• 拆分策略：
  • 保留 ide_screen.dart 为页面骨架与布局组合。
  • 将内部组件提取为独立 widget：
    • lib/screens/ide/toolbar.dart：顶部工具栏
    • lib/screens/ide/template_bar.dart：模板栏
    • lib/screens/ide/editor_area.dart：编辑器区域
    • lib/screens/ide/bottom_panel.dart：底部面板
    • lib/screens/ide/floating_orb_area.dart：悬浮球区域
    • lib/screens/ide/keyboard_handler.dart：键盘与快捷键处理
• 执行步骤：
  1. 识别 ide_screen.dart 中可独立的状态块。
  2. 使用 Consumer/ref.watch 保持状态订阅。
  3. 每提取一个 widget，运行 flutter test 与 flutter analyze 验证。
• 验收标准：
  • ide_screen.dart 行数降至 300 行以内。
  • flutter analyze 0 issues。
  • 集成测试通过。
• 风险：拆分过程中可能破坏状态监听链路，需通过集成测试捕获。

第三阶段：规范与质量加固（P2，预计 2 周）

目标：建立项目级 lint 配置、代码内问题追踪机制，优化前端性能热点。

任务 3.1：建立项目级 Clippy 配置

• 涉及文件：
  • native/Cargo.toml 或新建 native/clippy.toml
  • 各模块源码
• 执行步骤：
  1. 在 Cargo.toml 中声明 [lints.clippy] 规则，例如：
     • unwrap_used = "deny"
     • expect_used = "warn"
     • missing_panics_doc = "warn"
     • too_many_lines = "warn"
     • type_complexity = "allow"（如现有类型确实复杂）
  2. 逐步修复新增 lint 报错，优先处理高优先级模块。
  3. 对暂时无法修复的地方添加显式 #[allow(...)] 并附注释说明原因。
• 验收标准：cargo clippy --all-targets -- -D warnings 仍然全绿；新增 lint 规则生效。
• 风险：unwrap_used 可能导致大量报错，建议先设为 warn，分阶段提升为 deny。

任务 3.2：引入代码内 TODO/FIXME 追踪规范

• 涉及文件：全项目
• 执行步骤：
  1. 制定注释规范：
     • // TODO(#<issue>): 说明：已知待改进点
     • // FIXME(#<issue>): 说明：已知缺陷
     • // HACK: 说明：临时 workaround
     • // NOTE: 说明：重要设计决策
  2. 扫描现有代码，补充关键位置的 TODO/FIXME 标记。
  3. 在 CI 或脚本中增加 TODO/FIXME 统计，定期 review。
• 验收标准：关键 workaround 与边界情况均有代码内标记；维护者可通过 grep 快速定位。
• 风险：过度标记会制造噪音，应聚焦真正需要跟踪的问题。

任务 3.3：前端 CustomPainter 绘制缓存优化（前端资产，已迁出）✅ 已随前端切割消解（2026-09-11）

• 涉及文件（均已随 CideFlutter/ 迁出，标签 before-frontend-split）：
  • CideFlutter/lib/editor/editor_painter.dart（前端资产，已迁出）
  • CideFlutter/lib/widgets/floating_orb_widget.dart（前端资产，已迁出）
  • CideFlutter/lib/widgets/visualizers/*.dart（前端资产，已迁出）
• 执行步骤：
  1. 对 TextPainter、ParagraphBuilder、Gradient、Blur 等对象实施缓存，仅在文本/数据变化时重建。
  2. 为动画组件添加 RepaintBoundary 隔离重绘区域。
  3. 使用 shouldRepaint 精确控制重绘。
  4. 在桌面端与移动端分别进行性能测试（观察帧率、CPU 占用）。
• 验收标准：
  • 复杂可视化场景下帧率不低于 55fps。
  • flutter test 与集成测试通过。
• 风险：缓存逻辑引入状态同步复杂度，需确保数据更新时正确失效。

任务 3.4：统一模式大状态传递优化

2026-09-11 口径：本条后端侧仍有效（StepPayload 字段瘦身、符号表/变量历史增量更新由 vitro_runtime 与 unified::stream 承担）；Dart 侧条目已随前端切割迁出并冻结。

• 涉及文件：
  • native/src/api/vitro.rs（已随前端切割移除，出口改由 native/src/capi/ + native/src/session_api.rs 承担）
  • native/src/flutter_bridge.rs（仍存在：历史会话包装层，被 vitro_cli 消费，名称待后续重构收敛）
  • CideFlutter/lib/providers/unified_notifier.dart（前端资产，已迁出）
• 执行步骤：
  1. 评估当前 StepPayload/StepPayloadDelta 字段必要性，剔除冗余字段（后端，仍有效）。
  2. 对符号表、变量历史等大对象启用增量更新或分页（后端，仍有效）。
  3. 在 Dart 端使用 compute 或 isolate 处理大状态反序列化（前端资产，已迁出，条目关闭）。
  4. 增加状态大小日志，监控异常增长（后端，仍有效）。
• 验收标准：
  • 10 万步统一模式下后端吞吐与内存表现有界（原「前端仍保持流畅」为前端指标，随前端迁出不再由本仓验收）。
  • 内存占用无明显增长。
• 风险：增量更新逻辑复杂，可能引入状态不一致。

第四阶段：C++ 扩展模块化（P3，预计 4 周）

目标：降低 C++ 扩展在 Parser/TypeChecker/CodeGen 中的耦合度，减少回归风险。

任务 4.1：建立 C++ 语法专属解析模块

• 涉及文件：
  • crates/vitro_parser/src/cpp.rs（新建）
  • crates/vitro_parser/src/lib.rs
• 执行步骤：
  1. 将 C++ class、模板、构造析构、引用等语法解析逻辑集中到 parser/cpp.rs。
  2. 在 parser/mod.rs 中通过 parse_cpp_xxx 调用入口。
  3. 保持 C 解析路径不被 C++ 逻辑污染。
• 验收标准：C 解析模块中不出现 Class、Template、Reference 等 C++ 专属分支。

任务 4.2：建立 C++ 类型检查模块边界

• 涉及文件：
  • crates/vitro_typeck/src/cpp/
  • crates/vitro_typeck/src/lib.rs
• 执行步骤：
  1. 将 C++ 类布局、方法解析、重载、引用语义迁移到 typeck/cpp/ 子模块。
  2. 明确 C++ typeck 与 C typeck 的调用边界。
  3. 提取公共工具函数到 typeck/cpp/utils.rs。
• 验收标准：typeck/mod.rs 对 C++ 逻辑的依赖通过明确接口完成。

任务 4.3：建立 C++ 字节码生成模块边界

• 涉及文件：
  • crates/vitro_codegen/src/cpp/
  • crates/vitro_codegen/src/expr.rs / stmt/
• 执行步骤：
  1. 将 C++ 构造析构调用、方法调用、引用处理、移动构造等逻辑迁移到 codegen/cpp/。
  2. 在通用 gen_expr/gen_stmt 中通过类型判断分派到 C++ 处理模块。
• 验收标准：C++ 代码生成变更不再扩散到通用表达式生成逻辑。

任务 4.4：C++ 容器布局维护流程固化

• 涉及文件：
  • native/runtime_libc/vitro/*.cpp
  • scripts/extract_cpp_builtin_layout.py
  • crates/vitro_cpp_frontend/src/builtin_layout_data.json
• 执行步骤：
  1. 文档化容器新增流程：编辑 .cpp → 运行提取脚本 → 验证 JSON → 跑测试。
  2. 在 CI 中增加 .cpp 接口声明的语法检查（clang++ -fsyntax-only）。
  3. 确保 Rust 代码中不再新增硬编码容器信息。
• 验收标准：新增容器必须仅修改 .cpp 与脚本，无需改动 Rust 源码。

第五阶段：长期健康度维护（P4，持续推进）

目标：保持文档整洁、监控工程健康度、持续消除小额债务。

任务 5.1：定期清理 docs/archive/

• 执行步骤：
  1. 每季度 review docs/archive/，删除无价值的历史交互文本。
  2. 对保留的归档文档添加摘要说明，便于后续检索。
• 验收标准：docs/archive/ 体积季度环比下降或保持稳定。

任务 5.2：建立工程健康度看板 ✅ 已完成

• 执行步骤：
  1. 新增 scripts/engineering_health.py 健康度看板脚本，统计以下指标：
     • 各 Rust 源文件行数 Top 20（Dart 项随前端切割归零：脚本现只扫描 native/src 与 native/crates，仓库内 .dart 文件数为 0）
     • TODO/FIXME/HACK 数量（按文件分布 Top 10）
     • unwrap/expect 使用数量（按文件分布 Top 10）
     • 失败记录文件中活跃问题数量
     • Shadow Verification 匹配率（C / C++）
  2. 生成报告到 reports/engineering_health.md。遗留问题（新记为 D15）：脚本仍保留前端时代残留（frb_generated.* 忽略名单、豁免注释中的 FRB 表述、「Rust/Dart」趋势文案）——2026-09-18 迁 Go（scripts/engineering_health）后复核仍在；报告已由 CI 生成并上传 artifact，但阈值门禁未启用（无红绿判定），待后续清理。
• 验收标准：维护者可定期查看工程健康度趋势。

任务 5.3：Mutex poison 处理增强

• 涉及文件：native/src/flutter_bridge.rs（历史会话包装层，被 vitro_cli 消费，名称待后续重构收敛；仍存在于本仓，非前端资产）
• 执行步骤：
  1. 在 poison 恢复路径增加日志记录。
  2. 评估是否需要 panic 而非恢复默认值。
  3. 增加指标或测试覆盖 poison 场景。
• 验收标准：poison 不再静默恢复，至少留下可观测痕迹。

四、执行节奏与里程碑

五、质量保证

5.1 每个任务必须通过的验证

1. 单元测试：cd native && cargo test --workspace --all-features 全绿。
2. Lint：cargo clippy --all-targets -- -D warnings 全绿。
3. 格式化：cargo fmt --check 通过。
4. Shadow Verification：C/C++ Shadow Verification 无新增失败。
5. 出口 3 协议冒烟：go run ./scripts/serve_smoke 通过（CI 已执行）。
6. 出口 2 构建：cargo build --target wasm32-unknown-unknown --release 通过（Phase 2a 起进 CI）。
7. 集成测试：CI 全量 workflow 通过。

5.2 变更管理

• 每个任务独立分支，禁止混合无关变更。
• 每个 PR 必须关联本方案中的债务编号（如“偿还 D03”）。
• PR 描述中必须说明：变更范围、测试验证结果、已知风险。

5.3 回退策略

• 若拆分过程中发现功能回退，立即停止拆分，回滚到上一个稳定提交。
• 若新增 lint 规则导致大量报错，先降级为 warn，分阶段修复。
• 若 wasm32 出口构建失败，先确认目标已安装（rustup target add wasm32-unknown-unknown）与 #[cfg(target_arch = "wasm32")] 门控未被破坏；历史前端构建（Flutter/Android）的回退策略随前端迁出，需要时从标签 before-frontend-split 取回脚本。

六、附录：债务追踪表

七、修订记录

八、后续计划（2026-06-17 全面评估后）

本章节基于 2026-06-17 最新全面评估结果制定，承接 工程债务维护方案 前五阶段已完成工作，聚焦长期可维护性与产品质量收尾。

8.1 评估结论摘要

当前项目处于 MoonBit 迁移期（2026-09-18 起，总计划——Rust 区冻结为差分 oracle，Phase 42 随砍 C++ 裁定冻结于 oracle〔2026-09-20〕），并已于 2026-09-11 完成前端切割、转入纯后端「三出口一核心」阶段。下表口径 as-of 2026-09-11，已剔除前端项（数据来源：reports/engineering_health.md、native/tests/shadow_verification/reports/shadow_report_latest.md、CPP_FAILURES.md；未能核实者明确标注「待核实」）：

主要短板：Workspace 拆分已进入平台期（vitro_shared/vitro_ast/vitro_runtime/vitro_vm/vitro_lexer/vitro_parser/vitro_cpp_frontend/vitro_typeck/vitro_codegen/vitro_algorithm_steps 已独立；unified/checkpoint.rs 的 CheckpointManager 已下沉到 vitro_vm::snapshot；剩余 unified/types.rs/stream.rs/root_cause.rs、engine/、diagnostics 仍保留在 vitro_native 内部，native/src/api/ 已随前端切割删除）。FRB 已移除，原有孤儿规则阻碍消失，unified/diagnostics/engine 的拆分可重新评估（尚未执行；Rust 区冻结后不再执行，等价结构已由 MoonBit 侧 L0–L9 包切分重建）；vitro_api 一项需按「C API / CLI 入口」重新界定（native/src/capi/、native/src/bin/、native/src/flutter_bridge.rs）。其余短板：编译管线三阶段镜像耦合、多入口 API 重复包装、生产代码 unwrap/expect 回升至 3 处（D14）、工程健康度脚本仍带前端时代口径且未门禁化（D15）、native/crates/vitro_typeck/src/decl.rs 871 行超出任务 B 的 800 行阈值（D16）；AGENTS.md 已知限制清单（H01~H10）已全部处理或明确记录原因；H01 参数化宏分号已作为教学子集扩展支持但与 Clang 存在差异，H03 自定义头文件 include 已支持，均已诚实记录；Phase 42（随砍 C++ 冻结于 oracle，2026-09-20）：vitro_vec<T> / vitro_list<T> 类类型模板实参均已支持，const T& 参数已支持绑定右值，cpp_monomorph.rs 已拆分为 18 行入口 + 7 个子模块，所有子文件 <800 行。

8.2 下阶段重点任务

任务 A：Rust 后端 Workspace 拆分（P1，预计 3~4 周）

目标：将 native 单 crate 拆分为多个逻辑 crate，降低编译缓存粒度与模块耦合。

建议 crate 划分：

执行步骤：

1. ✅ 在 native/Cargo.toml 中建立 workspace，已迁移 vitro_shared（SourceLoc）与 vitro_ast（AST/类型系统）。
2. ✅ 拆分 vitro_runtime：下沉 func_meta/symbol/type_utils、RuntimeState/MemoryState 及依赖类型、内存布局常量、unified_types 基础数据；session.rs 改为带 #[frb] 类型的薄包装层 + re-export（#[frb] 标记已于 2026-09-11 前端切割时清除，native/src/session.rs 仍为本仓语言中立会话状态）。
3. ✅ 拆分 vitro_vm：将 native/src/vm/ 完整迁移到 crates/vitro_vm；引入 VmContext 替代 Session 上帝对象，打破 vm 与 session 的循环依赖；vitro_native 通过 pub use vitro_vm as vm; 保持路径兼容。
4. ✅ 拆分 vitro_lexer：将 ErrorCode 下沉到 crates/vitro_shared；将 native/src/compiler/lexer.rs 与 native/src/compiler/lexer/ 子模块完整迁移到 crates/vitro_lexer；vitro_native 通过 pub use vitro_lexer as lexer; 保持路径兼容。
5. ✅ 拆分 vitro_parser：将 native/src/compiler/parser/ 全部 10 个文件完整迁移到 crates/vitro_parser；vitro_shared 新增 SourceLoc re-export；vitro_native 通过 pub use vitro_parser as parser; 保持路径兼容。
6. ✅ 拆分 vitro_cpp_frontend：将 native/src/compiler/cpp_frontend/ 完整迁移到 crates/vitro_cpp_frontend；vitro_native 通过 pub use vitro_cpp_frontend as cpp_frontend; 保持路径兼容。
7. ✅ 拆分 vitro_typeck：将 vm::host_func_id/vm::bytecode_libc_index/vm::bytecode_libc_sig 下沉到 vitro_runtime；将 native/src/compiler/typeck/ 全部 22 个文件完整迁移到 crates/vitro_typeck；vitro_native 通过 pub use vitro_typeck as typeck; 保持路径兼容。
8. ✅ 拆分 vitro_codegen：将 native/src/compiler/codegen/ 全部 26 个文件完整迁移到 crates/vitro_codegen；下沉 vitro_vm::opcode/vitro_vm::instruction 与内存布局常量到 vitro_runtime，切断 codegen 对 vitro_vm 的直接依赖。
9. ✅ 拆分 vitro_algorithm_steps：将 native/src/unified/algorithm_steps/ 完整迁移为独立 crate；通过 AlgorithmContext trait 解耦对 Session 的依赖；vitro_native 通过 pub use vitro_algorithm_steps as algorithm_steps; 保持 crate::unified::algorithm_steps 路径兼容。
10. ✅ 迁移 CheckpointManager：将 native/src/unified/checkpoint.rs 的 CheckpointManager 下沉到 vitro_vm::snapshot；重构 should_checkpoint 接收 semantic_label: &str，save 接收 &mut VmContext，彻底去除对 Session/StepMeta 的依赖；更新 unified/engine.rs、flutter_bridge.rs、bin/vitro_cli.rs、tests/test_snapshot.rs 调用点。
11. ⚠️ unified/engine/api 拆分受阻的原因已于 2026-09-11 部分失效，如实更新：

• FRB 已移除，原有孤儿规则阻碍消失：unified/types.rs 的 StepPayload/AlgorithmStepSnapshot/PointerSnapshot 等类型已不再带 #[frb] 属性，vitro_native 也不再为其生成 IntoIntoDart 实现；api 模块（native/src/api/，原 FRB 出口）已整体删除。原「必须等 FRB 跨 crate 绑定策略明确」的前提不再成立。
• 剩余阻力只有 Session 耦合：engine（compile_pipeline.rs/session_ops.rs）与 unified 仍依赖 crate::session::Session，直接拆分仍会形成 vitro_engine → vitro_native → vitro_engine 的循环依赖，需先建立独立的 vitro_session（语言中立核心状态）crate。
• 结论：unified/diagnostics/engine 的拆分可重新评估（尚未执行；Rust 区冻结后不再执行，等价结构已由 MoonBit 侧 L0–L9 包切分重建） —— 2026-09-11 复核时三者仍位于 vitro_native 内部；后续按「先 vitro_session、再 unified/engine/diagnostics」的顺序推进，工程量大，不在文档翻新范围内强制启动。

12. ⚠️ vitro_diagnostics 暂保留在 vitro_native 内部：FRB 已移除，原有孤儿规则阻碍已消失，可重新评估（尚未执行；Rust 区冻结后不再执行，等价结构已由 MoonBit 侧 L0–L9 包切分重建）；当前主要阻力是其与 Session／诊断上下文的耦合。
13. 每迁移一个 crate，执行 cargo test --workspace --all-features 与 Shadow Verification 验证无回归。
14. 评估 vitro_engine / vitro_api 独立 crate（P6）：FRB 已移除，原「含 #[frb] 类型 + 孤儿规则」的阻碍消失；当前唯一实质阻力是二者仍深度依赖 crate::session::Session/CompileState（语言中立但耦合度高）。结论：拆分可重新评估（尚未执行；Rust 区冻结后不再执行，等价结构已由 MoonBit 侧 L0–L9 包切分重建），建议路径为先建立 vitro_session 语言中立核心状态 crate，再依次迁移 unified → engine → diagnostics。vitro_api 边界需按纯后端出口（capi / CLI / flutter_bridge.rs）重新界定。

验收标准：

• cargo test --workspace --all-features 全绿。
• C/C++ Shadow Verification 无新增失败。
• 单 crate 行数不超过 1.5 万行。
• cargo check 增量编译时间下降 ≥20%。

风险：

• Workspace 拆分会改变模块间可见性，需大量调整 pub 与 use；建议小步迁移，一次一个 crate。
• 含 #[frb] 导出类型的模块（如 diagnostics）拆分为独立 crate 会触发 FRB 孤儿规则 —— 该风险已随 2026-09-11 FRB 移除而消失。当前拆分风险转为：Session 上帝对象耦合（需先抽 vitro_session）、跨 crate 可见性调整（大量 pub/use 变更），仍建议小步迁移，一次一个 crate。

任务 B：超大单体文件继续拆分（P1，预计 2~3 周）✅ 已完成

目标：将剩余超过 1000 行的核心文件拆分为职责清晰的子模块。

路径说明（2026-09-11）：下表部分路径为 crate 迁移前的历史路径，现已沉降为 —— native/src/vm/ → native/crates/vitro_vm/src/；native/src/compiler/ast.rs → crates/vitro_ast/src/；native/src/unified/algorithm_steps.rs → native/crates/vitro_algorithm_steps/src/；native/src/compiler/algorithm_detector.rs 的目录仍位于 native/src/compiler/algorithm_detector/。前端资产 CideFlutter/lib/widgets/custom_keyboard.dart 已随切割迁出，该子项关闭。

已完成拆分：

剩余待拆分队列（本次更新后）：

无。

本次新增拆分：

验收标准：

• ⚠️ 每个源文件行数降至 800 行以内 —— 2026-09-11 复核已不满足：199 个 .rs 文件中 native/crates/vitro_typeck/src/decl.rs 为 871 非空行（新记 D16），其余全部达标。
• 所有 Rust 测试通过。
• Shadow Verification 无新增失败。
• 不引入新的 unwrap/expect（注意：该条亦已回升 3 处，见 D14）。

任务 C：生产代码 unwrap/expect 收敛（P2，预计 2 周）

目标：将生产路径中的 unwrap/expect 逐步替换为显式错误处理，降低运行时 panic 风险（原始目标为当时实测的 43 处）。

重点文件（2026-09-11 复核现状，对应 D14）：

• native/crates/vitro_typeck/src/decl.rs（3 处，当前唯一残留生产代码 unwrap：L44 / L65 init.take().unwrap()、L648 default.clone().unwrap()）。
• 历史目标（已清零）：native/src/compiler/cfg.rs、native/crates/vitro_vm/src/core/executor/（原 native/src/vm/core/executor/）、native/src/compiler/data_flow.rs、native/crates/vitro_codegen/src/expr/call.rs、native/src/compiler/intent.rs——这些文件中现存的 unwrap/expect 均位于 #[cfg(test)] 测试代码内。
• 已随前端切割移除：native/src/api/vitro.rs（原 4 处）；其 apply_fix 本体已迁入语言中立的 native/src/diagnostics/auto_fix.rs。

执行步骤：

1. 对这些文件逐函数审计，区分"确实不可失败"与"可能失败"的调用点。
2. "确实不可失败"的调用添加注释说明不变量，保留 expect 并补充 #[allow(clippy::expect_used)]。
3. "可能失败"的调用改为 match / if let / ? 传播，或转换为结构化诊断错误。
4. 生产代码 unwrap/expect 曾于 2026-06-25 降至 0 处（unwrap_used 已为 deny）；2026-09-11 复核实测回升至 3 处（native/crates/vitro_typeck/src/decl.rs，已于 D14 登记），需重新收敛。统计口径以 scripts/engineering_health 排除 #[cfg(test)] / #[test] 后的结果为准（脚本中的 frb_generated.rs 豁免项为前端时代残留，见 D15）。

验收标准：

• ⚠️ 当前不满足：生产代码 unwrap/expect 实为 3 处（原「0 处」结论已过期）；重新收敛至 0 处后，engineering_health.md 与维护计划数字需再次对齐。
• ✅ cargo clippy --all-targets -- -D warnings 全绿（unwrap_used = deny 生效中）。
• 新增错误路径均有单元测试覆盖。

任务 D：失败记录文件口径整理（P2，预计 1 周）

目标：澄清"活跃失败记录"统计口径，区分历史已修复条目与当前已知失败。

执行步骤：

1. 统一 scripts/engineering_health 的统计口径：仅统计标记为 KNOWN_FAILURE / KNOWN_DIVERGENCE / KNOWN_LIMITATION 的条目。
2. 在 KR_FAILURES.md 顶部明确说明：当前 0 个活跃已知失败，文件主体为历史修复记录。
3. 修正 CPP_FAILURES.md 中"60 个 E2E 实际用例"的笔误，统一为 61 个。
4. 检查其他 *_FAILURES.md 是否也存在类似口径不一致，统一修正。
5. 2026-09-11 新增口径问题（待同步）：CPP_FAILURES.md 现记「C++ E2E 74 个用例」，而 native/tests/cases/cpp/ 实际有 78 个 .cpp 文件（vitro_e2e.rs::load_cpp_cases 加载目录下全部 .cpp）；两处数字需对账后统一。

验收标准：

• engineering_health.md 中"活跃失败记录条目"数字与文件中 KNOWN_* 标记数一致。
• 所有 *_FAILURES.md 数字口径与 TEST_REPORT.md 一致。
• scripts/ci_three_tier_check 一致性检查通过。

任务 E：CI 与构建系统加固（P2）✅ 已完成（前端子项已随切割消解，wasm32 子项转入 Phase 2a）

目标：降低 CI 对 Windows-only runner 与 Flutter 工具 patch 的依赖，提升构建鲁棒性。

执行步骤（2026-09-11 口径改写）：

1. 对齐本地与 CI 的测试 / lint 命令 ✅：
   • 原入口 scripts/build_flutter.py --test 已随前端切割删除；现行本地与 CI 统一命令为 cargo test --workspace --all-features 与 cargo clippy --workspace --all-targets --all-features -- -D warnings（ci.yml 的 rust job 已如此执行）。
2. Flutter generator 问题根治 ✅ 已随前端切割消解：scripts/patch_flutter_windows_generator.py 与相关 patch 需求随 Flutter 构建整体迁出（标签 before-frontend-split）。
3. Android job 增加基础测试 ✅ 已随前端切割消解：ci.yml 已无 android / ios / flutter job，CI 收缩为纯后端 rust job。
4. 依赖版本锁定 ✅：serde / serde_json / libm 已做小版本锁定（现行写法为 ~1.0.228 / ~1.0.149 / ~0.2.16）。
5. binaryen/wasm-opt 稳定性（wasm 冒烟已于 2026-09-12 固化进 CI〔R4 G2〕；binaryen/wasm-opt 优化链未见——Rust 区冻结后随 MoonBit wasm-gc 出口另行裁定）：
   • 将 binaryen 版本与 wasm-opt 参数文档化。
   • 考虑将 wasm-opt 步骤改为可选，避免阻塞主 CI。
   • 现状：wasm32-unknown-unknown 已冒烟实证（零修改构建 3.75MB），scripts/wasm_smoke/wasm_smoke.js 已固化并进 CI（2026-09-12 R4，见路线图 G2）。

验收标准（改写后）：

• ✅ CI 全绿且不依赖临时 patch（Flutter patch 需求已消失）。
• ✅ 本地与 CI 使用同一套 cargo test / cargo clippy 命令（不再有 Flutter 构建脚本作为本地入口）。
• ✅ wasm32 出口检查进 CI（2026-09-12 R4 G2 固化：scripts/wasm_smoke/wasm_smoke.js + ci.yml 构建/冒烟步骤）；MoonBit 侧 wasm-gc 单出口已落地（2026-09-29 S7 批五号，Node 宿主 host.js 断言入 CI——优化链〔wasm-opt 等〕仍属后续裁定项）。

任务 F：性能收尾（P2，预计 2 周）

目标：完成 Phase 42 未完全落地的性能优化。

执行步骤：

1. Dart Visualizer 缓存落地 ✅ 已随前端切割消解（前端资产，已迁出）：
   • ✅ array_visualizer.dart 缓存 parsed numbers。
   • ✅ tree_visualizer.dart、linked_list_visualizer.dart 将 TextPainter 创建上提到 State 并复用，通过 saveLayer 应用动态透明度。
   • ✅ RepaintBoundary 已在动画组件就位。
   • ✅ shouldRepaint 已基于 nodes/isDark/progress 精确判定。
   • 以上成果随 CideFlutter/ 迁出（标签 before-frontend-split），本仓无对应验收对象。
2. 统一模式差分编码落地（已完成，后端侧仍有效）：
   • ✅ 变量级差分（var_deltas / new_vars / removed_var_name_indices）已在位。
   • ✅ 符号表全局去重字符串池已在位。
   • ✅ Dart 端大 batch（>50 units）切到 isolate 解码（Dart 侧已迁出，条目关闭）。
   • ✅ call_stack / vis_events / accessed_vars 改为 Option<Vec<T>>：无变化时不再全量传输。
   • ✅ array_snapshots / pointer_snapshots 实现按名索引的新增/替换/删除差分（removed_*_name_indices）。
   • 🚧 大对象（符号表、变量历史）分页或懒加载待进一步评估（后端侧）。
3. 性能基线（后端已实测；前端项已随切割迁出）：
   • ✅ 完成后端统一模式 10 万步基准实测：新增 native/benches/unified_perf_baseline.c（50 个逆序元素冒泡排序，约 10 万 VM 步）与 scripts/unified_perf_baseline.py，release 模式下后端吞吐约 18,500 步/秒，生成 reports/unified_perf_baseline.md。
   • ✅ 为支持长程序性能测试，UnifiedEngine 新增 with_max_steps 构造函数；vitro_cli unified 新增 --max-steps <n> 选项（默认 100_000）。
   • 📦 前端 55fps 回放基线（Flutter 桌面端 Release 实测：40 元素冒泡排序回放 5 秒，等效 FPS 825.1；报告 reports/frontend_fps_baseline.md）为前端资产历史成果，已迁出，不再由本仓验收（报告文件仍留在 reports/ 作为历史记录）。

验收标准（改写后）：

• ✅ cargo test --workspace --all-features 与后端 Shadow 防线全绿（依据 2026-09-11 批次 H 记录：全量 0 failed、clippy 全绿、C Shadow 636 例 0 非预期差异、C++ Shadow 0 非预期差异、serve 冒烟通过）；原「flutter test」验收项随前端迁出，条目关闭。
• 📦 复杂可视化场景帧率 ≥55fps —— 前端指标，已随前端切割迁出并冻结，不再由本仓验收。
• ✅ 10 万步统一模式后端无明显卡顿与内存泄漏（后端基线实测约 18,500 步/秒）。

任务 G：教学场景与内容深化（P3，持续推进）

目标：在工程加固基础上，扩展教学内容与真实场景覆盖。

执行步骤：

1. LeetCode 逐步填充：在 0~30 道中等题目标达成后，继续 all in 混合难度题目。✅ 2026-06-18 新增 15 道混合难度题（含 5 道困难题），当时 LeetCode 用例总数 92 道，均通过 Shadow Verification（截至 2026-09-11：native/tests/cases/leetcode/ 共 138 道，全绿）。
2. K&R 进阶章覆盖：
   • ✅ 第 7 章 7 个用例（kr_7_1~kr_7_7）已纳入，当时 K&R 防线扩展至 76/76 全绿（截至 2026-09-11：native/tests/cases/knr/ 共 81 个用例，全绿）。
   • ⚠️ 第 8 章（UNIX 系统接口）因 Vitro 教学子集不支持 POSIX 系统调用（read/write/open/close/unlink/lseek/opendir 等），原始习题无法直接适配。可适配部分（如 8-7 自己实现 malloc/free）与 Vitro 内置内存管理冲突，且失去教学对比意义。结论：第 8 章暂不纳入常规回归测试，作为文档中的已知限制保留；后续可考虑编写使用 Vitro VFS 接口的变体用例，但不强求覆盖。
3. 学生常见错误用例库扩展：基于 docs/current/04-标准库与防线/学生错误用例集.md 持续补充。
4. 诊断知识卡片扩展：针对 C++ 常见错误（内存泄漏、悬垂引用、对象切片、浅拷贝双重释放、引用绑定临时对象）新增知识卡片。

本次推进记录（2026-06-18）：

• 第一批新增 5 道 LeetCode 中等题源码与 golden：
  • lc_3 Longest Substring Without Repeating Characters
  • lc_33 Search in Rotated Sorted Array
  • lc_48 Rotate Image
  • lc_62 Unique Paths
  • lc_64 Minimum Path Sum
• 第二批新增 5 道 LeetCode 中等题源码与 golden：
  • lc_2 Add Two Numbers
  • lc_11 Container With Most Water
  • lc_19 Remove Nth Node From End of List
  • lc_31 Next Permutation
  • lc_34 Find First and Last Position of Element in Sorted Array
• 第三批新增 5 道 LeetCode 中等题源码与 golden：
  • lc_15 3Sum
  • lc_39 Combination Sum
  • lc_46 Permutations
  • lc_75 Sort Colors
  • lc_198 House Robber
• 第四批新增 5 道 LeetCode 中等题源码与 golden：
  • lc_55 Jump Game
  • lc_142 Linked List Cycle II
  • lc_152 Maximum Product Subarray
  • lc_200 Number of Islands
  • lc_221 Maximal Square
• 第五批新增 5 道 LeetCode 中等题源码与 golden：
  • lc_49 Group Anagrams
  • lc_56 Merge Intervals
  • lc_78 Subsets
  • lc_102 Binary Tree Level Order Traversal
  • lc_139 Word Break
• 第六批新增 5 道 LeetCode 中等题源码与 golden：
  • lc_153 Find Minimum in Rotated Sorted Array
  • lc_162 Find Peak Element
  • lc_300 Longest Increasing Subsequence
  • lc_394 Decode String
  • lc_560 Subarray Sum Equals K
• 第七批新增 15 道 LeetCode 混合难度题源码与 golden（7 困难 / 7 中等 / 1 简单）：
  • lc_4 Median of Two Sorted Arrays（困难；实现中发现 Vitro 函数返回 double 值异常，已改用整数返回值通过）
  • lc_23 Merge k Sorted Lists（困难）
  • lc_25 Reverse Nodes in k-Group（困难）
  • lc_42 Trapping Rain Water（困难）
  • lc_45 Jump Game II（中等）
  • lc_53 Maximum Subarray（简单）
  • lc_73 Set Matrix Zeroes（中等）
  • lc_76 Minimum Window Substring（困难）
  • lc_84 Largest Rectangle in Histogram（困难）
  • lc_91 Decode Ways（中等）
  • lc_98 Validate Binary Search Tree（中等）
  • lc_124 Binary Tree Maximum Path Sum（困难）
  • lc_146 LRU Cache（中等）
  • lc_207 Course Schedule（中等）
  • lc_322 Coin Change（中等）
• 修复发现的问题：JIT 统计信息原通过 output_lines 混入用户 stdout，导致 lc_3 在 Shadow Verification 中出现 output_gap。已移除该输出并新增 vitro_get_jit_stats C API，jit_unit_test.rs 改为通过 API 验证 JIT。
• 诚实记录的新发现：lc_4 原始实现使用 double findMedianSortedArrays(...) 返回值时，Vitro VM 输出全为 0.00000，与 Clang 行为不一致。已改用整数返回值（结果 × 100000）规避，并在 AGENTS.md / LEETCODE_FAILURES.md 中记录该限制。
• C Shadow Verification 从 549/555 更新为 555/562，C++ Shadow Verification 保持 83/83。
• 2026-06-25 修复 double 函数返回值异常：vitro_typeck::decl.rs 在 return 语句 check_assignable 成功后调用 insert_implicit_cast；新增 baseline/float_func_return.c 回归用例；lc_4.c 恢复为原始 double 返回实现；C Shadow Verification 更新为 556/563。
• 新增 C++ 教学知识卡片：在 native/crates/vitro_shared/src/error_codes.rs 与 native/src/diagnostics/error_catalog.rs 中新增 E4100~E4106：
  • E4100：C++ 内存泄漏（new 未 delete）
  • E4101：C++ 悬垂引用（返回局部变量引用）
  • E4102：C++ 对象切片（派生类赋值给基类值对象）
  • E4103：C++ unique_ptr 所有权混乱
  • E4104：C++ move 后继续使用源对象
  • E4105：C++ 隐式浅拷贝导致双重释放
  • E4106：C++ 引用绑定到临时对象
• 扩展学生错误用例库：在 docs/current/04-标准库与防线/学生错误用例集.md 中新增 9.1~9.7 七个 C++ 常见错误教学用例。

本次推进记录（2026-06-26）：

• 第八批新增 15 道 LeetCode 混合/简单/中等题源码与 golden：
  • lc_16 3Sum Closest
  • lc_17 Letter Combinations of a Phone Number
  • lc_22 Generate Parentheses
  • lc_24 Swap Nodes in Pairs
  • lc_29 Divide Two Integers
  • lc_38 Count and Say
  • lc_40 Combination Sum II
  • lc_50 Pow(x, n)
  • lc_54 Spiral Matrix
  • lc_168 Excel Sheet Column Title
  • lc_242 Valid Anagram
  • lc_509 Fibonacci Number
  • lc_704 Binary Search
  • lc_746 Min Cost Climbing Stairs
  • lc_977 Squares of a Sorted Array
• K&R 防线补充 5 个变体/基础用例：
  • kr_1_hello Hello World
  • kr_2_celsius 摄氏度转华氏度
  • kr_4_atoi 自定义 atoi
  • kr_5_itoa 自定义 itoa（含 reverse）
  • kr_6_getword 基于 getchar/ungetc/ctype 的单词读取
• C++ E2E 防线补充 9 个 Stage 0~6 用例：
  • cpp_pair_template 多类型参数模板类
  • cpp_template_func_multi 函数模板多类型实例化
  • cpp_reference_member 成员函数返回引用并作为左值赋值
  • cpp_template_array 模板类固定大小数组
  • cpp_template_stack 模板类栈
  • cpp_unique_ptr_reset unique_ptr reset 语义
  • cpp_class_array 类对象数组（stdout 不依赖析构计数）
  • cpp_ctor_init_list 构造函数初始化列表
  • cpp_reference_param_chain 引用参数链式修改
  • cpp_function_overload_template 普通函数与函数模板共存
• 探索用例 cpp_move_semantics 因触发 Vitro 内存泄漏报告（移动构造后源对象未正确标记 region 转移），未纳入 E2E，已删除
• 诚实记录的新发现：Vitro C++ 子集当前不支持类类型作为模板实参传入 vector<T> / list<T>（push_back 无法匹配以类为参数的构造函数），也不支持非类型模板参数、嵌套类 Outer::Inner 实例化、const 引用参数、默认参数、自定义拷贝构造等特性。这些用例未纳入 E2E/Shadow。（注：vitro_list<T> 类类型模板实参与 const T& 参数绑定右值已于后续 4.40 支持）
• C Shadow Verification 更新为 585/589，C++ Shadow Verification 更新为 93/93；cargo test --workspace --all-features / cargo clippy --workspace --all-targets --all-features -- -D warnings / cargo fmt --check / flutter analyze / flutter test 全绿。

本次推进记录（2026-06-26 继续 all in）：

• 第九批新增 10 道 LeetCode 简单题源码与 golden：
  • lc_7 Reverse Integer
  • lc_83 Remove Duplicates from Sorted List
  • lc_190 Reverse Bits
  • lc_191 Number of 1 Bits
  • lc_202 Happy Number
  • lc_205 Isomorphic Strings
  • lc_231 Power of Two
  • lc_263 Ugly Number
  • lc_292 Nim Game
  • lc_389 Find the Difference
• lc_412 Fizz Buzz 同步更新 golden
• LeetCode 防线扩展至 118 题；C Shadow Verification 更新为 596/600，C++ Shadow Verification 保持 93/93；cargo test --workspace --all-features / cargo clippy --workspace --all-targets --all-features -- -D warnings / cargo fmt --check / flutter analyze / flutter test 全绿。

本次推进记录（2026-06-26 继续 all in 第二批）：

• 第十批新增 10 道 LeetCode 简单题源码与 golden：
  • lc_67 Add Binary
  • lc_219 Contains Duplicate II
  • lc_345 Reverse Vowels of a String
  • lc_349 Intersection of Two Arrays
  • lc_367 Valid Perfect Square
  • lc_383 Ransom Note
  • lc_392 Is Subsequence
  • lc_401 Binary Watch
  • lc_409 Longest Palindrome
  • lc_415 Add Strings
• LeetCode 防线扩展至 128 题；C Shadow Verification 更新为 606/610，C++ Shadow Verification 保持 93/93；cargo test --workspace --all-features / cargo clippy --workspace --all-targets --all-features -- -D warnings / cargo fmt --check / flutter analyze / flutter test 全绿。

验收标准：

• ✅ 新增 30 道中等题及额外 15 道混合难度题均通过 Shadow Verification 与 cargo test test_vitro_e2e_leetcode。
• ✅ 知识卡片覆盖 C++ Stage 0~6 常见错误（E4100~E4106）。

任务 H：AGENTS.md 已知限制逐项修复（P2，持续推进）

目标：按优先级逐个修复 AGENTS.md 中记录的已知限制与行为差异，缩小 Vitro 与 Clang 的行为差距，提升教学子集真实场景可用性。

当前已知限制清单（来自 AGENTS.md）：

执行步骤：

1. 对每个限制项建立最小复现用例，确认根因范围（Lexer/Parser/TypeChecker/BytecodeGen/VM）。
2. 评估修复成本与教学价值，优先处理 P1 行为差异（影响 Shadow Verification 用例覆盖与真实代码迁移）。
3. 修复后补充回归用例，更新 AGENTS.md 与 CHANGELOG.md [Unreleased]。
4. 对暂无法修复的限制项，在 AGENTS.md 中保留诚实记录，并在本任务清单中标注原因。

验收标准：

• 每修复一项，C/C++ Shadow Verification 无新增失败。
• 新增回归用例通过 cargo test --workspace --all-features。
• AGENTS.md 与 CHANGELOG.md 同步更新。

本次推进记录（2026-06-25）：

• H06 复合副作用数组索引触发 NULL 指针陷阱（P1）：crates/vitro_codegen/src/expr/unary.rs 的 gen_mem_inc_dec 改用 temp_slot3 保存新值，避免与 gen_assign 的 Index 赋值复用 temp_slot0；新增 baseline/side_effect_index.c 回归用例。
• H07 函数返回 double 值异常（P1）：vitro_typeck::decl.rs 在 return 语句 check_assignable 成功后调用 insert_implicit_cast；新增 baseline/float_func_return.c 回归用例；lc_4.c 恢复为原始 double 返回实现。
• H08 scanf/sscanf 的 %s 格式符不支持（P1）：crates/vitro_vm/src/host/io.rs 的 host_scanf_n/host_sscanf 新增 's' 分支处理；新增 baseline/scanf_string.c 回归用例。
• H01 参数化宏调用后带分号无法解析（P2）：vitro_lexer::expand_macros_inner 在参数化宏展开时，若宏体为大括号块且调用位置后紧跟分号，则动态将宏体包装为 do { ... } while(0)，使 SWAP(int,x,y); 在 if/else 等语句中可正确解析；新增 end_to_end_extra_test::test_e2e_parametric_macro_swap_semicolon 回归测试。诚实记录此为 Vitro 教学子集扩展，Clang 标准模式对未包装的 { ... }; 形式仍会报错。
• H02 VLA 数组索引缺失边界检查（P2）：vitro_codegen::expr::gen_index 对首维为变量表达式的 VLA 生成运行时边界检查；新增 TrapBoundsVla opcode（值为 129），索引前将 VLA 维度表达式求值并压栈；vitro_vm::core::executor::debug.rs 在 VM 运行时将索引与运行时边界比较，越界时触发教学诊断；新增 baseline/vla_bounds.c 回归用例。参数退化为指针的 VLA 形参仍无法在调用点获知边界，保持跳过。
• H10 fclose 后 VFS FILE* 被误报为内存泄漏（P2）：新增 vitro_runtime::MemoryState::free_region 方法；crates/vitro_vm/src/host/file.rs 的 host_fclose 在关闭 VFS 文件描述符后调用 session.memory.free_region(stream)，释放 host_fopen 为 FILE* 结构体分配的 4 字节内存；stdout/stderr 等非堆分配 stream 找不到对应 region 时安全忽略；vfs.rs 的 free_raw 改为复用 MemoryState::free_region；新增 baseline/fclose_leak.c 回归用例。
• H03 #include 非标准库路径（P3）：vitro_lexer::Lexer 新增 base_path 字段与 with_mode_and_path 构造函数；compile_pipeline.rs 从首个编译单元文件名提取目录作为 base_path；preprocessor.rs 在 load_stub 失败后调用 load_include_file 从 base_path 读取自定义头文件；自定义头文件内容保留原始换行以支持 #ifndef / #define / #endif 等预处理指令。shadow_verify.py 与 vitro_e2e.rs 改用真实源文件路径调用 vitro_compile_unit，保证 Shadow Verification 与 E2E 测试中的 include 行为与 Clang 一致。新增 baseline/include_custom_header.c / include_custom_header.h 回归用例。绝对路径、系统 include 搜索路径（<> 非标准库）及递归 include 仍待扩展。
• H04 va_list / va_start / va_arg / va_end 自定义变参函数（P3）：根因是 Parser 把所有函数调用解析为 Expr::CallPtr，而 CallVar 指令只在 gen_call 中生成，变参数据未被写入栈帧。修复方案：
  • vitro_codegen::expr::call 在 gen_call 与 gen_call_ptr 中同步识别变参函数，生成 PushConst total_arg_words + CallVar；total_arg_words 按实参真实 type_size 折算 word 数，支持 double / long long 等 8 字节类型。
  • 调用方对 8 字节变参实参直接按小端布局顺序压栈，不再依赖 SplitD/SplitQ，__vitro_va_arg 返回对应地址，宏展开为 *(type*)__vitro_va_arg(...) 按目标类型位模式读取。
  • vitro_typeck::decl 对超出命名参数的变参实参应用 C 默认实参提升（float→double、char/short→int）。
  • 附带修复：vitro_codegen::expr::cast 重写 gen_expr_with_cast，以目标 Type 选择转换指令，修复 long long 目标被错误截断为 int；vitro_codegen::expr::assign 修复复合赋值对 long long 使用 32 位运算的问题。
  • 新增 baseline/variadic.c 回归用例，覆盖 int / double / long long 三种类型的自定义变参求和；修复 ast_unit_test.rs、b10_new_array_rollback.rs 中因新增 is_variadic 字段导致的编译错误。
• H05 全局 VLA（P3）：按 C99 标准评估，文件作用域 VLA 被明确禁止（Clang 报 "variable length array declaration not allowed at file scope"）。Vitro 保持不支持，与标准一致，无需修复；已在 AGENTS.md 中明确记录。
• P1/P2 行为差异与 H01~H05 已全部处理，H04 自定义变参函数已修复，H05 明确为标准限制无需修复；AGENTS.md 已知限制清单全部处理完毕。

8.3 执行节奏与里程碑

8.4 质量保证

每项任务必须通过以下验证：

1. cd native && cargo test --workspace --all-features 全绿。
2. cargo clippy --all-targets -- -D warnings 全绿。
3. cargo fmt --check 通过。
4. C/C++ Shadow Verification 无新增失败。
5. 出口 3 协议冒烟：go run ./scripts/serve_smoke 通过（CI 已执行）。
6. 出口 2 构建：cargo build --target wasm32-unknown-unknown --release 通过（Phase 2a 起进 CI）。
7. CI 全量 workflow 通过。

8.5 风险与回退策略

本方案应与 AGENTS.md、CHANGELOG.md、代码审阅与修复追踪20260906.md（已归档的历史修复追踪——Rust 区冻结后活跃缺陷由 GitHub issue 体系承接）共同维护，任何新发现的工程债务应及时追加到本方案中（编号延续 #DXX，不重排）。