Files
marqdo/doc/adr/0002-browser-marqdo-wasm.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

3.2 KiB
Executable File
Raw Permalink Blame History

ADR 0002:浏览器内 Marqdo = WASM 解释器(路线 C)

状态 Accepted
日期 2026-09-01
决策者 chaungming + 协作
相关 browser-marqdo-wasm.md · roadmap/browser-wasm.md · interpreter.md · 0001

背景

ext/web 已把站点装配成「源码以 .mq.md 为主、服务端 Rust 解释执行」。作者面仍缺浏览器内的同一语言:事件、局部状态、客户端 fetch/WS 回调今天要么手写 JS,要么完全不做。

候选路线:

代号 做法
A 服务端驱动 + 极薄固定增强(类 HTMX)
B 把 Marqdo 编译/翻译成 JavaScript
C 把 Rust 解释器/字节码 VM 编成 WASM,浏览器跑同一套语义

产品叙事目标:网络项目源码树可以只有 .mq.md(JS/WASM 为生成或发行物,不是第二作者语言)。


决策

  1. 选定路线 C:浏览器内运行 与主机同构的 Marqdo 语义(parse → tree 和/或 bytecode VM),制品为 marqdo.wasm + 极薄 JS 宿主桥。
  2. 不选定 B 作为主路径:翻译到 JS 易语义漂移,长期要维护两套后端;B 至多作实验,不替代 C。
  3. A 不对立:内容站 / SSR / 表单 POST 仍以服务端 ext/web 为主;C 负责「必须在客户端执行的 Marqdo」。
  4. 同一内核、两套宿主:server(今日 CLI + axum 插件)与 browser(DOM / fetch / 定时器 / storage);不是把 axum、plugins/web、SQLite 服务端塞进浏览器。
  5. 另开设计与路线图(见相关链接);实现按 C0→C5 切片,金样对齐主机行为。
  6. 与「编译 mq.md → WASM 机器码」区分:本 ADR 是 解释器/VM 上 WASM;把 .mq.md 直接编译成独立 wasm 模块仍属 interpreter.md Phase III 可选项,另案,不替代本决策。

后果

  • 核心库必须可 feature-gate 掉 libloading / ureq / tiny_http / TTY libc 等,以便 wasm32-unknown-unknown 链接。
  • 新增公共 API:run_source(内存源码 + 可选导入图),供 WASM 与测试共用。
  • 浏览器侧宿主 API 以表驱动「交互装配」暴露(对称于 样式装配);ext/** 仍不直接调 host_*。
  • 发行物可包含 .wasm / 生成的 loader;作者仓库可不提交手写业务 JS。
  • view 断点 / 静态文档站调试可复用同一 WASM 解释器(与 next-phase.md 所述一致)。

否决 / 非目标(本 ADR)

方案 / 目标 原因
以 B(编译到 JS)为主交付 语义双轨;与「一种语言」冲突
浏览器内完整复刻 plugins/web 服务器 协议与权限模型不同;服务端仍 axum
浏览器 dlopen 原生插件 WASM 无 POSIX 动态库模型
v1 消灭一切 JS 字节 胶水与发行 loader 允许存在;禁止的是业务手写 JS
用 Daphne/ASGI 托管 Marqdo 已否决,见 web-asgi-servers-and-marqdo.md