docs/current/06-出口与协议/出口分档与宿主策略.md
GitHub ↗
当前有效

出口分档与宿主策略（2026-09-25）

3471 字·约 9 分钟 阅读 2026-10-10 17:07

性质：出口承诺面的口径契约 + 宿主接入策略。本文档收敛 2026-09-25 出口议题多轮讨论的终局结论，取代此前散落在对话与零散记录中的"桌面端/C API 怎么办"口径。 上游裁定：本档是 MoonBit迁移总计划 F-5（wasm-gc 单出口、多宿主、砍 capi 45 导出）的展开与执行口径；不推翻任何上游裁定。 适用边界：MoonBit 引擎（vitro/engine）对外交付面。Rust 冻结区的 capi 按 F-1 冻结纪律服役至全量切换，不在本文档约束范围内。

1. 出口三分档

档 内容 口径
承诺出口 ① wasm-gc 制品（4 函数导出 + 21 方法表，F-5）；② 冻结协议（NDJSON 帧协议 + StepPayload schema v0.1，版本化、semver 下限语义）；③ 生成宿主 SDK（gen_bindings，按 schema 生成，排 S7 后启动）；④ .mbti 接口面（mooncakes vitro/engine，0.5.0 起带版本化弃期义务） 版本承诺 + 兼容负担 + 双向对账纪律
可用不承诺 ① native 出口（引擎自家 CLI 与开发工具的载体：cmd/dump_compile 等）；② js 出口 可用，但不进承诺面——无性能/稳定性承诺，无跨目标一致性义务（F4 栈深三出口各异、F6 Hasher 种子 wasm=0 是结构性理由：每个出口都有性格，收窄承诺面 = 卸掉对账义务）
不提供 C ABI（新引擎无此导出面） 不是"不推荐"，是不存在——见 §2

承诺出口②（冻结协议）的完整导览——单源派生链、对拍与冒烟防线、双侧实现锚、消费者拓扑与协议演化纪律三条（由 go run ./scripts/gen_svg panorama 生成）：

落地状态（2026-09-29 核对）：承诺出口①②④ 已交付——① wasm-gc 制品（S7 批五号：gateway + gateway/wasm，Node 宿主 host.js 16 断言入 CI）；② 冻结协议（protocol 包权威载体 + gen_protocol_ts 权威源切 MoonBit）；④ .mbti 面（0.6.0 / 0.7.0 在架，0.7.0 发版件就绪 publish 待令）；③ 生成宿主 SDK 仍排 S7 后启动。详见发布档案 0.7.0。

vitro 冻结协议层全景

措辞纪律：「不提供」≠「不推荐」。「不推荐」暗示"等一等会有"，会诱导消费者押注一个不存在的面；「不提供」是契约边界，文档与对外沟通一律用后者。

2. 为什么不提供 C ABI（三条硬理由）

  1. 物理前提薄弱：C ABI 导出依赖月兔 C 后端产出 C 源码，而 C 后端正被新 native 后端替换（MOONBIT_NEW_NATIVE 开关，官方发布说明见探测档案），存活期无官方承诺。把对外契约押在一个供应商正在退役的接口上，承诺即负债。新 native 后端能否导出 C ABI 属未探针事项——即使探针可行，也只值得做探针记录，不值得做承诺。
  2. 消费史已判过：旧 capi 45 导出中 28 个无消费者（亲证，总计划 F-5 依据）。C ABI 面的膨胀惯性大于消费牵引，本仓自己就是反例。下游第二批 capi 已裁不做、改道 wasm/serve（见 wasm多实例并发模型与U2拍板）。
  3. 替代面已全覆盖且宿主门槛消失：
    • 协议面扛得住每步交互——step.next 每步投递一帧是 serve 现役形态，StepPayload v0.1 冻结（61/61 回放，见 STEP_PAYLOAD_SCHEMA_V0_1）；id 关联帧是异步对账基础，waiting_input 状态机承载交互输入（喂入不重置运行态），协议层即异步接口，无需任何编译层异步动作（JSPI 等不进依赖清单）。
    • wasm-gc 嵌入门槛已消失：WebView2/V8 原生支持，Node 原生。.NET 有官方 Wasmtime NuGet 绑定（部署须显式 -W gc，门 2 教训）——2026-10-05 实测不成立并修正（判定书探针④）：Wasmtime .NET 绑定 48.0.2 对本仓制品编译期即拒（support for non-externref and non-funcref references is not implemented，与 GC 开关无关）；wasmtime CLI v48 引擎核心可编译 GC 类型（差距在绑定层），但 js-string builtins 提案两侧均无支持（本仓 3467 条 imports 无满足捷径，Node 一行配置对照 16/16 绿）。.NET 下游现实通道 = 协议 sidecar（serve）或 WebView2 内嵌；Wasmtime 形态归外部条件（绑定层补齐），非本仓工程。详见 S9脱钩与裁定批判定书 §1.3。
    • 教学负载毫秒级（用户场景 compile/run 中位 8–10ms，见 性能探究实录），进程边界延迟不可感。

触发线条款：未来若出现真实进程内原生消费者（画像：非 .NET 非 web、协议延迟实测不可接受、需深度内存集成），先做月兔 native C ABI 导出探针（可行/不可行都是档案价值），再议是否开承诺面。当前零消费者，不预建。

3. 宿主策略：四条通道与默认推荐

通道 适用宿主 载体 默认推荐
WebView 内嵌 wasm-gc 图形宿主（桌面 IDE、浏览器） wasm-gc 制品 + TS 呈现层 ✅ 图形宿主首选
协议 sidecar / serve 非图形宿主、工具链、CI spawn 进程 + NDJSON 帧 ✅ 非图形宿主首选
mooncakes 源码级集成 MoonBit 宿主 moon add vitro/engine MoonBit 宿主唯一通道；出口跟随宿主——引擎不替宿主选制品形态
生成 SDK（协议客户端） 任意语言宿主 gen_bindings 按冻结 schema 生成 随协议面配套，宿主语言只决定生成模板数量

数据源单源论（引擎与下游的分界）：引擎画数据，下游画像素（2026-09-11 前端切割裁定：「本仓库只做后端，前端交给社区」，见 后端定位与白箱计划）。引擎侧义务 = 数据源完备性：每个教学增值画面——时间旅行可视化、内存面板、栈展开逐帧动画、ARC refcount 面板——所需的输入在协议帧里必须齐全（步进帧序列 / memory.regions / 逐帧栈序列 / region 表 refcount），且呈现契约清单全有引擎侧数据源；教学画面扩展 = schema 只增字段，引擎永远不做像素。下游义务 = 渲染（UI 是各宿主的产品差异化，本就不应单源）。TS 侧实际交付物 = @vitro/protocol npm 包（生成的 TS 类型 + 字段元数据运行时校验 + 最小消费者示例），下游渲染层免手抄 schema、免理解引擎内部。

桌面端推荐形态：桌面壳（窗口/文件/系统集成为宿主原生）+ WebView 内下游自建画布（消费 @vitro/protocol 类型包 + wasm-gc 制品，渲染生态现成）+ wasm-gc 引擎（WebView 内或宿主侧协议 SDK）。web 技术栈的价值是让下游自建画布最便宜且桌面与浏览器共享同一套消费代码；WPF 宿主用 WebView2 控件（官方一等公民支持）。

4. 桌面端唯一真实义务：SharpTutor 迁移路径

SharpTutor（WPF/.NET）是已存在的锚定桌面客户（立项三条件与 capi/serve 对接史见 CSharp前端引入计划）。其迁移路径三段：

  1. 迁移期：继续用 Rust 冻结区 capi（F-1 冻结纪律，服役至全量切换）；
  2. 协议切换：迁到 gen_bindings 生成的 C# 协议 SDK（首个真实消费者；vitro_capi.h 19 声明阻塞项由 SDK 生成接管，总计划 U2 闭环）；
  3. 画布渲染升级（下游自择）：教学画布继续 WPF 自绘消费协议 SDK，或迁 WebView2 内自建 web 画布（消费 @vitro/protocol + wasm-gc）——两条路的画面数据源同为冻结协议帧（与 C# 前端链路的双轨：Roslyn 管真编译与编辑器服务，引擎管白箱执行——Roslyn 不进引擎的裁定见 CSharp前端引入计划 §1）。数据源单源论——引擎画数据，下游画像素。建议使用web栈便于接入。

5. 与既有裁定的关系

  • F-5（总计划）：本文档 = F-5 的执行展开，无推翻。
  • A-03（架构审阅 v2）：出口表述沿其修正口径——月兔有 wasm/wasm-gc/js/native 四个稳定目标，"收窄"的是项目承诺的出口，非语言能力。
  • A-04（架构审阅 v2）：维持引擎语言排除裁定不变；本文档不涉及实现语言选型。
  • 语言版图：见 §6.4 终态口径（2026-09-25 裁定：双核 MoonBit + Go，TS 待命）。

6. TS 层职责、待命时序与语言版图（2026-09-25 裁定）

依据：2026-09-21 TS 职责宪章讨论（源：架构审阅 v2 D-14/E-08、总计划 F-4/F-5、U2 拍板）+ 2026-09-25 本文档讨论收敛的用户裁定。

6.1 三层拆解与义务归属

层 载体 现状 义务归属
协议类型层 @vitro/protocol npm 包 已交付——index.d.ts / fields.mjs 为 Go 生成器 gen_protocol_ts 生成物（与 STEP_PAYLOAD_SCHEMA 双向对账入 CI），TS 人力零依赖，协议扩字段重跑生成器即可 Go（生成器）+ MoonBit（权威源结构体）
宿主脚本层 scripts/wasm_smoke、S7 双宿主对拍的 Node 侧 最低限度维护——Node 是 wasm-gc 原生宿主，冒烟与对拍依赖它 工具脚本，非"TS 层工程"
UI 载体层 教学画布 / 可视化组件 从未在场——2026-09-11 前端切割裁定「本仓库只做后端，前端交给社区」 下游/社区（自绘）

6.2 待命职责宪章（UI 重建时生效的边界）

  • 免役层性质：TS 侧一切代码只依赖三面冻结（StepPayload schema / NDJSON 帧协议 / .mbti），引擎全量迁移当天零改动穿过。
  • 宿主双份（设计储备，非活跃工程）：浏览器 IBrowserHost（wasm-gc 编译一次实例化 N 次、Worker 结构隔离、可杀性执行者）+ Node engine-host（spawn / 超时 kill / RSS 采样）；第三宿主 Wasmtime 归 .NET 下游。
  • 呈现契约清单（= §3 数据源完备性的对面清单）：步进动画、变量面板、播放控制状态机、根因提示、学习路径、概念图谱等——每一项对应协议帧字段，引擎侧数据已实现、UI 载体待下游重建。
  • 禁令：不重算编译语义（E-07）；推断算法不迁（algorithm_steps 留引擎核心）；不改 schema 语义；不可信代码不放主线程（D-03）。
  • 防线义务（E-08）：「golden payload → 渲染输出」快照测试，快照不得由当前实现生成（E-04 假绿纪律）——UI 重建启动时立即生效。

6.3 时序裁定

  1. TS/UI 侧全面暂缓至引擎迭代完毕后。当下唯一维持项 = 宿主脚本层的最低限度存在（wasm_smoke / S7 对拍）。
  2. UI 重建主体默认 = 下游/社区（SharpTutor WPF 自绘或 web 宿主自建）；Vitro 出参考画布 = 引擎全量切换后的可选决策，走触发线（真实需求命中再议），非排期义务。
  3. 引擎侧对"将来的画面"的全部义务 = §3 数据源完备性，已由协议冻结自动满足，无额外工作。

6.4 语言版图（终态口径）

语言 工种 状态
MoonBit 唯一引擎实现语言（C 前端 + C# 前端 vitro/engine/csharp 四包 + VM/字节码/协议/诊断——单引擎核多语言前端，见 CSharp前端引入计划 v4） 双核之一，全速迭代
Go 司法语言：生成器、对拍驱动、归一化；禁写引擎、引擎禁写生成器（双向禁令） 双核之一
TS 待命：未来 UI 载体 + wasm 宿主脚本 待命（§6.3 时序）
C# 对象语言 + 下游宿主（SharpTutor）+ 防线 golden 生成（dotnet/Roslyn） 对象语言与宿主侧
C 对象语言（语料与记录），实现侧零角色 对象语言

TS 留版图的理由：UI 迟早要建且 web 呈现生态的默认语言是它——移除再恢复的成本高于挂"待命"牌。宿主侧语言不进版图，引擎侧只认协议。

状态记录：2026-09-25 会话收敛落档。涉及数字出处：45/28 导出（总计划 F-5）、门 2 -W gc（总计划 §3）、61/61 回放（STEP_PAYLOAD_SCHEMA_V0_1）、8–10ms（性能探究实录）。gen_bindings 与 C# SDK 未启动，开工时序随 S7。