docs: lock browser Marqdo WASM plan (ADR 0002, C0–C5)

Accept route C: ship the interpreter/VM on wasm32 with a thin JS host
bridge, not transpile-to-JS. Add design, roadmap, and cross-links.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-01 10:06:56 +08:00
1 parent 2079577314
commit f2fd4fb34e
8 files changed
+454 -4

No files matched your search

+3
View File
@@ -2,6 +2,9 @@
## Unreleased
### Added
- **浏览器 Marqdo(路线 C)设计锁定**:[ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [design/browser-marqdo-wasm.md](doc/design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md)(WASM 解释器,非编译到 JS)。
### Fixed
- **Admin UI**:主区取消 `max-width:56rem` 限制,表格外包可横向滚动的 `.table-wrap`,单元格完整展示并自动换行;表单加宽且 textarea 可随内容增高。
- **`marqdo ext add`**:安装含原生插件的扩展时**先**定位/自动 `cargo build` 再拷贝 `.mq.md`,避免只装上文稿、运行时报 `native plugin not found`;扩大 `.so` 搜索路径。
+1 -1
View File
@@ -117,7 +117,7 @@ marqdo catalog public -o .marqdo
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM 解释器](doc/adr/0002-browser-marqdo-wasm.md)(路线 C,实现中见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))
### 如何使用最新 Marqdo(v0.3.1)
+57
View File
@@ -0,0 +1,57 @@
# ADR 0002:浏览器内 Marqdo = WASM 解释器(路线 C)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-09-01 |
| 决策者 | chaungming + 协作 |
| 相关 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) · [interpreter.md](../roadmap/interpreter.md) · [0001](0001-implementation-language.md) |
---
## 背景
`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](../design/web-asgi-servers-and-marqdo.md) |
+254
View File
@@ -0,0 +1,254 @@
# 浏览器 Marqdo(WASM 解释器)设计
| | |
|---|---|
| 状态 | **Accepted(设计锁定)** · 实现见路线图 C0–C5 |
| 日期 | 2026-09-01 |
| ADR | [0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) |
| 路线图 | [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) |
| 相关 | [ext-web.md](ext-web.md) · [bytecode.md](bytecode.md) · [web-assets-and-images.md](web-assets-and-images.md) · [table-cell-expressions.md](table-cell-expressions.md) |
---
## 0. 一句话
**源码只有 `.mq.md`;浏览器跑与 CLI 同构的 Marqdo VM(WASM);JS 只做宿主桥与加载器,不做业务语言。**
---
## 1. 目标与非目标
### 1.1 目标
| # | 目标 |
|---|------|
| G1 | 浏览器内执行合法 `.mq.md`(至少 `# main` + 打印/绑定/分支/循环/表/调用) |
| G2 | 与主机 **tree**(及后续 **bytecode**)金样在共享子集上 stdout/返回值一致 |
| G3 | 作者用 GFM 表声明交互(选择器 / 事件 / 调用),对称于 `样式装配` |
| G4 | 仓库源码树可不含业务 `.js`;允许提交或由工具生成 `marqdo.wasm` + 官方 loader |
| G5 | `import lib/…` 在浏览器可用(嵌入式 `lib/` 或打包进 wasm) |
### 1.2 非目标(本波 / C0–C3)
| # | 非目标 |
|---|--------|
| N1 | 在浏览器复刻 axum、`web_listen`、SQLite 服务端、admin UI |
| N2 | `plugin.load` 加载原生 `.so` / 浏览器内 dlopen |
| N3 | 把整站 `plugins/web` ABI 原样搬进 WASM |
| N4 | 把 `.mq.md` 编译成独立机器码 WASM(异于「解释器上 WASM」) |
| N5 | 强制内容站必须加载 WASM(纯 SSR 站可继续零客户端逻辑) |
---
## 2. 架构
```
┌─────────────────────────────────────────────────────────┐
│ Page (HTML shell from ext/web SSR or static) │
│ ┌──────────────┐ ┌─────────────────────────────────┐ │
│ │ DOM / CSS │ │ Official JS loader (thin) │ │
│ └──────▲───────┘ │ - WebAssembly.instantiate │ │
│ │ bridge │ - marqdo_run_source / on_event │ │
│ │ └──────────────┬──────────────────┘ │
│ │ │ │
│ │ ┌──────────▼──────────┐ │
│ │ │ marqdo.wasm │ │
│ │ │ parse → load → │ │
│ └──────────────│ Interpreter | Vm │ │
│ host_dom_* │ HostContext(browser)│ │
│ host_fetch_* │ embedded lib/ │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Server (unchanged):
marqdo run / plugins/web (axum) — SSR, DB, auth, full site
```
**原则:** 一套语言语义;**HostContext 分型**(`native` vs `browser`),不是两套语法。
---
## 3. 与现有流水线对齐
主机今日(见 `src/lib.rs`):
```
path → fs::read → load_module → Interpreter|Vm → HostContext(native)
```
浏览器目标:
```
source: &str (+ optional import map)
→ load_module_from_memory
→ Interpreter|Vm (capture stdout)
→ HostContext(browser caps)
→ { ok, stdout, value_json, error }
```
公共库 API(C0/C1 必须落地):
| API | 职责 |
|-----|------|
| `run_source(source, opts) -> Result<RunCapture>` | 无路径入口;cwd/fs_root 虚拟 |
| `RunOptions` 浏览器默认 | `allow_fs_write=false`, `allow_exec=false`, `allow_net=false`(net 经显式 bridge 再开) |
| `load` 导入 | `lib/**` → `embedded_lib`;用户模块 → JS 注入的 `HashMap<path, source>` |
后端优先级:
1. **C1:tree**(与默认 CLI 一致,调试简单)
2. **C2+:bytecode** 可选(体积/性能;金样双后端)
---
## 4. Cargo / 制品布局
### 4.1 Feature 门(核心 crate `marqdo`)
| Feature | 默认(native) | `wasm-core` | 作用 |
|---------|----------------|-------------|------|
| `cli` | on | off | `main` / clap 仅 bin |
| `view` | on | off | `tiny_http` 文档浏览器 |
| `net-host` | on | off | `ureq` HTTP 客户端 |
| `plugin-host` | on | off | `libloading` 原生插件 |
| `exec-host` | on | off | `std::process` / foreign |
| `fs-host` | on | off | 真实磁盘读写(可读可后续经 VFS 桥) |
| `wasm-core` | off | on | 浏览器子集编译开关 |
`wasm32-unknown-unknown` 构建:**不得**链接 `libloading`、`ureq`、`tiny_http`、TTY `libc`。
### 4.2 包
| 路径 | 角色 |
|------|------|
| `marqdo`(根) | 核心;feature-gate |
| `crates/marqdo-wasm` | `cdylib` + `wasm-bindgen` 导出 |
| `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) |
| `examples/browser-hello/` | 静态页 + wasm 冒烟 |
| `tests/browser/` 或金样脚本 | Node/wasmtime 跑 `run_source` 对齐 |
发行:`marqdo wasm build`(C2 CLI 糖)或 `wasm-pack build crates/marqdo-wasm`。
---
## 5. 宿主能力矩阵
| 能力 | Native | Browser C1 | Browser C3+ |
|------|--------|------------|-------------|
| `print` / 捕获 stdout | ✓ | ✓ → 可镜像 `console` | ✓ |
| `input` | stdin / preset | **仅 preset / JS 喂入** | 可选 prompt 桥 |
| builtins / 表 / 算术 | ✓ | ✓ | ✓ |
| `lib/math` `lib/json` `lib/collection` | ✓ | ✓(embedded) | ✓ |
| `lib/fs` 真磁盘 | ✓ | ✗ 明确报错 | 可选 OPFS/VFS 桥 |
| `lib/net` ureq | ✓ | ✗ | `fetch` 桥(异步模型见 §7) |
| `plugin.load` | ✓ | ✗ | ✗(改 L1 浏览器专用) |
| `exec` / foreign | ✓ | ✗ | ✗ |
| DOM / 事件 | ✗ | stub | **交互装配** |
| `sleep` | thread | 0 或 JS timer(异步) | timer |
错误策略:**显式失败**(诊断字符串含 `unavailable in browser wasm`),禁止静默空成功。
---
## 6. 交互装配(C3,对称样式装配)
作者面(示意,关键字以落地时 `ext` 双语名为准;**不在核心发明 `if`/`on` 关键字**):
```markdown
`交互` =
| 选择器 | 事件 | 调用 |
|--------|------|------|
| "#btn" | click | handle_click |
| ".item" | click | select_item |
*`_`` = > 浏览器.交互装配 表=`交互` *
```
语义:
1. 装配函数把表登记到 WASM 侧 registry。
2. Loader 在 DOM 上 `addEventListener`;触发时调用导出 `marqdo_dispatch(event_id, payload_json)`。
3. 调用解析为 Marqdo 函数(同页已 `load` 的模块内 `## handle_click`)。
4. 返回值约定(C3 最小):`None` / 文本 / Map(如 `{dom:…}` 指令列表)由桥执行,**避免在核心写死 React**。
值列含 `/` 的 CSS 等仍遵守 [table-cell-expressions.md](table-cell-expressions.md):**引号优先**(`"16/9"`)。
---
## 7. 异步模型(C4 才深化)
Marqdo 今日调用多为**同步**。浏览器 `fetch` / 定时器是异步的。
C1–C3 约定:
- 同步子集先完整。
- `fetch`:C4 引入 **宿主 Promise → 续体** 或 **显式 `> 浏览器.请求` 返回 future 句柄 + 轮询/回调表**;需短 ADR 补丁,不在 C1 假装同步阻塞整个页面。
在续体方案落地前:网络仍以**服务端** `ext/web` / `lib/net`(native)为主。
---
## 8. 安全
| 项 | 规则 |
|----|------|
| 默认能力 | 无磁盘写、无 exec、无任意 net |
| 源码来源 | 同源或构建时嵌入;不默认 `eval` 远程不可信脚本除非站点显式开启 |
| DOM | 仅经装配表/白名单 API;不暴露任意 `innerHTML` 字符串执行第三方脚本 |
| CSRF / Cookie | 浏览器 Marqdo **不替代**服务端鉴权;cookie 仍走 HTTP |
---
## 9. 与 `ext/web` 分工
| 层 | 负责 |
|----|------|
| 服务端 `plugins/web` | 路由、DB、会话、SSR HTML、样式/头/图装配 |
| 页面壳 | 输出时可选嵌入 `<script type="module" src="marqdo-loader.js">` + wasm |
| 浏览器 L1 | `运行` / `交互装配` /(后)`请求` |
| 核心 | 可移植 VM + `run_source` + browser `HostFn` 子集 |
W8 资源表可增加「挂 wasm / module」行(既有 `page.head` / `头装配`),属 C2/C3 集成,不阻塞 C1。
---
## 10. 测试与验收
| 级 | 内容 |
|----|------|
| 单元 | `run_source("…# main\n> print…")` native 与 wasm 同测 |
| 金样子集 | `tests/structure/hello.mq.md` 等无 fs/net/plugin 的样例 |
| 浏览器冒烟 | `examples/browser-hello`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
| 回归 | CI:`cargo test` native;另 job `wasm-pack build` / `cargo check --target wasm32-unknown-unknown --no-default-features --features wasm-core` |
---
## 11. 文档与技能同步
- ADR 0002、本文、路线图 C0–C5。
- `.cursor/skills/marqdo/SKILL.md`:补充「浏览器 WASM / 交互装配 / 引号 CSS」。
- `CHANGELOG`:Unreleased 记录设计锁定与各 C 完成项。
---
## 12. 风险
| 风险 | 缓解 |
|------|------|
| wasm 体积过大 | 裁剪 feature;后期 `wasm-opt`;bytecode 路径评估 |
| 异步拖垮语言 | C4 单独立项;此前不承诺同步 `fetch` |
| Feature-gate 伤 native | 默认 features = 今日行为;CI 全绿再合 |
| 作者误以浏览器替代服务器安全 | 文档强调鉴权在服务端 |
---
## 13. 决策摘要
| 问题 | 答案 |
|------|------|
| 路线? | **C**:解释器/VM → WASM |
| 作者语言? | 仅 `.mq.md` |
| JS 角色? | Loader + 宿主桥 |
| 服务端? | 保留;不塞进浏览器 |
| 第一步实现? | C0 门控可编译 + C1 `run_source` 打印闭环 |
+1 -1
View File
@@ -34,7 +34,7 @@
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
| 低 | 极致性能 | v0 样例很小 |
| 低 | 浏览器内运行 | 可后置 |
| 低 | 浏览器内运行 | **已后置落地规划**:见 [ADR 0002](../adr/0002-browser-marqdo-wasm.md)(WASM 解释器) |
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
+135
View File
@@ -0,0 +1,135 @@
# 路线图:浏览器 Marqdo(WASM)
| | |
|---|---|
| 状态 | **进行中**(设计已锁定) |
| 日期 | 2026-09-01 |
| ADR | [0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) |
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) |
| 相关 | [interpreter.md](interpreter.md) · [ext-web.md](../design/ext-web.md) · [next-phase.md](next-phase.md) |
实现阶段编号 **C0–C5**(Client / WASM)。每阶段结束须:文档状态更新 + CHANGELOG + 可演示验收。
---
## 总览
| 阶段 | 内容 | 状态 |
|------|------|------|
| **C0** | 设计锁定;Cargo feature 骨架;`wasm32` **check** 通过(可空跑) | **docs done · impl next** |
| **C1** | `run_source` + wasm-bindgen 导出;hello 打印;无 DOM | pending |
| **C2** | 官方 loader + `examples/browser-hello`;可选 `marqdo wasm build`;head 挂载约定 | pending |
| **C3** | 交互装配(事件表 → 回调);最小 DOM 读写宿主 | pending |
| **C4** | `fetch`/定时器异步模型 ADR + 首版桥 | pending |
| **C5** | bytecode 后端可选;体积优化;与 view 调试对齐 | pending |
---
## C0 — 可移植骨架
**目标:** native 默认行为不变;存在 `--features wasm-core --no-default-features` 使核心在 `wasm32-unknown-unknown` 上 `cargo check`。
**任务:**
1. ADR + 设计文(本文相关)已合入。
2. `Cargo.toml` features:`cli`/`view`/`net-host`/`plugin-host`/`exec-host`/`fs-host`/`wasm-core`。
3. `cfg` 隔离:`view`、`ext_cli`、`version_check`(ureq)、`host::{net,plugin,foreign,subtask}` 等。
4. `input_feed` TTY/`libc` 仅非 wasm。
5. CI 或本地脚本:`rustup target add wasm32-unknown-unknown && cargo check -p marqdo --target wasm32-unknown-unknown --no-default-features --features wasm-core`。
**验收:** 上述 check 退出 0;全量 `cargo test`(默认 features)仍绿。
---
## C1 — 内存执行闭环
**目标:** JS/wasm 调用 `run_source`,跑 `# main` + `> print`,拿回 stdout。
**任务:**
1. `pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture>`(及可选虚拟 imports)。
2. crate `crates/marqdo-wasm`:`#[wasm_bindgen] pub fn run(source: &str) -> String`(JSON:`{ok,stdout,error}`)。
3. 嵌入 `lib/` 只读导入可用。
4. 拒绝 fs/exec/plugin/net 并返回明确错误字符串。
5. 金样:至少 `hello` 结构子集在 native `run_source` 单测通过。
**验收:** wasm 实例化后 `run(hello_source)` 得到 `Hello World!`。
---
## C2 — 示例页与挂载
**目标:** 静态 HTML 打开即可跑 Marqdo;文档说明如何嵌入站点。
**任务:**
1. `examples/browser-hello/`:`index.html` + loader + 构建说明。
2. (可选)`marqdo wasm build` 包装 `wasm-pack`。
3. 与 W8 `page.head`:文档示例挂 `type=module` + wasm(实现可后置)。
4. README / tutorial 短节。
**验收:** 按 README 本地 `python -m http.server`(或等价)打开示例见打印结果。
---
## C3 — 交互装配
**目标:** 无手写业务 JS 的点击 → Marqdo 函数 → 改页面。
**任务:**
1. 宿主:`dom_text_set` / `dom_text_get` / `add_listener`(经 bindgen)。
2. L1 `ext/web` 或 `ext/browser`:`交互装配` / `wire_events`。
3. 示例:按钮计数或问候。
4. 设计补一节返回值指令格式(若 Map 驱 DOM)。
**验收:** 示例页点击按钮,DOM 文本变化;网络面板无第三方业务脚本(仅官方 loader)。
---
## C4 — 异步 I/O
**目标:** 受控 `fetch`(及 sleep)不阻塞语言谎言。
**任务:**
1. 短 ADR:续体 / 回调表 / Promise 桥选型。
2. `浏览器.请求` 首版 + 金样/示例。
3. 能力开关默认关,示例显式开。
**验收:** 示例请求公共 HTTP(或 mock)并把正文写回 DOM。
---
## C5 — 硬化
**目标:** 可选项生产化。
**任务:**
1. `--backend bytecode` 在 wasm 对齐。
2. `wasm-opt`、code splitting 评估。
3. view / 静态页调试:加载同一 wasm 跑片段(呼应 `next-phase.md`)。
4. 体积与启动预算写入设计文。
**验收:** 文档中的预算表 + CI 双后端子集金样。
---
## 依赖关系
```
C0 ──► C1 ──► C2 ──► C3 ──► C4
│ │
└──── C5 ◄─────┘(可与 C4 部分并行)
```
服务端 `ext/web` W0–W8 **不阻塞** C0–C2;C3 与 head/assets 集成最顺。
---
## 进度记录
| 日期 | 记录 |
|------|------|
| 2026-09-01 | ADR 0002 + 设计锁定;路线图开篇;开始 C0/C1 实现 |
+2 -1
View File
@@ -109,7 +109,8 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
- 更完整表达式文法、错误模型、外联围栏 FFI
- 生成 OKF 依赖目录
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
- **浏览器内运行(路线 C)**:解释器/VM 上 WASM(**非**把 `.mq.md` 译成 JS)——已锁定 [ADR 0002](../adr/0002-browser-marqdo-wasm.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](browser-wasm.md)
---
+1 -1
View File
@@ -174,7 +174,7 @@ flowchart LR
### 风险与边界
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或 [浏览器 WASM 解释器](browser-wasm.md) C5)。
- 字节码调试可晚于树遍历一个迭代。
---