Files
marqdo/doc/design/tech-stack.md
cflmyandCursor f2fd4fb34e 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>
2026-09-01 10:06:56 +08:00

153 lines
6.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 参考实现:技术选型分析(尚未拍板)
| | |
|---|---|
| 状态 | **分析中 — 未定案** |
| 日期 | 2026-08-04 |
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
---
## 1. 我们在选什么
参考实现至少包含:
1. **读入** `.mq.md`(含 frontmatter 混合行)
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
4. **两遍**:收集定义 + 导入 → 求值
5. **CLI** + **金样例测试**(`tests/`)
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
---
## 2. 选型准则(按权重)
| 权重 | 准则 | 说明 |
|------|------|------|
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
| 低 | 极致性能 | v0 样例很小 |
| 低 | 浏览器内运行 | **已后置落地规划**:见 [ADR 0002](../adr/0002-browser-marqdo-wasm.md)(WASM 解释器) |
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
---
## 3. 架构共性(与语言无关)
无论选哪门实现语言,流水线应一致:
```
.mq.md 文本
→ 前端:GFM 友好解析(或事件扫描)
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
→ Marqdo AST
→ 语义:导入图、提升、作用域
→ 后端:解释器(v0)/日后编译
→ 测试:tests 金样例 → 期望 stdout
```
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
---
## 4. 候选对比
### A. TypeScript / Node + remark(mdast)
| 利 | 弊 |
|----|----|
| remark-gfm 与预览器语义接近;mdast 节点齐全 | 运行时依赖 Node;发行 CLI 需打包 |
| 迭代快、Vitest 方便 | 性能与「系统级编译器」形象偏软 |
| 与 Markdown 工具链同生态 | 需纪律:避免把业务写进插件泥潭 |
**适合:** 验证宪法、快速金样例。
**不自动等于最终生产编译器。**
### B. Rust + pulldown-cmark / comrak
| 利 | 弊 |
|----|----|
| 单静态二进制、性能好、适合日后正式编译器 | GFM 表格/细节与 GitHub 仍可能有差异,要对齐测试 |
| 类型与代数数据类型适合 AST | 前期迭代比 TS 慢 |
| 无 GC、可嵌入 | MD 生态碎片,选库要论证 |
**适合:** 中长期「真编译器」或与 TS 原型双轨。
**风险:** 首版就上 Rust 可能拖慢语法验证。
### C. Python + markdown-it-py / mistune
| 利 | 弊 |
|----|----|
| 原型极快 | 类型与工程化偏弱;双实现时易弃 |
| 文本处理友好 | 打包 CLI 体验一般 |
**适合:** 一次性语法实验。
**不推荐**作为唯一长期实现,除非团队强约束。
### D. Go + goldmark
| 利 | 弊 |
|----|----|
| 单二进制、部署简单 | 泛型/AST 表达力一般;MD 库选 goldmark 需 GFM 扩展评估 |
| 并发与工具链成熟 | 与 MD 研究生态联系弱于 JS |
**适合:** 工具型 CLI 优先的团队。
### E. 自研扫描器(任意语言)+ 仅用 GFM 做对照测试
| 利 | 弊 |
|----|----|
| 完全控制行首判别与 `+`/`-` 语义 | 重复实现表格/强调,易与渲染不一致 |
| 可强制「行分类优先于块解析」 | 工作量大 |
**适合:** 证明「行首判别」与 CommonMark 块结构冲突时的研究分支。
可与 A/B 组合:自研 lower,块结构仍喂给现成解析器。
---
## 5. 关键技术风险(与选语言正交)
1. **行首判别 vs 块解析器** — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到**源行映射**。
2. **frontmatter 非纯 YAML** — `>` 导入行是扩展;不能整块丢给严格 YAML 解析器。
3. **`+` 与 `-` 列表** — 多数解析器都认,但 lower 必须保留**项目符字符**,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。
4. **`*` else vs `*返回*` vs 强调** — 依赖 inline 解析与「整行恰好一个 `*`」的行级规则并存。
以上 4 点应作为**选型验收用例**,写进 ADR:用最小样例在候选栈上 Spike,再定案。
---
## 6. 建议的决策流程(尚未执行)
1. **Spike(各 ≤0.5–1 日)**
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
- 候选 B:Rust + comrak/pulldown — 同上。
- (可选)C 或 D 若团队有偏好再做。
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `import x:x.mq.md` 的 frontmatter 行。
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
---
## 7. 当前态度(非正式投票)
| 阶段 | 倾向(待 Spike 验证) |
|------|------------------------|
| 语法验证期 | 更可能是 **TypeScript + remark**(快、GFM 近) |
| 长期生产编译器 | **开放** Rust / Go,不与验证期绑定 |
**本文不授权开始实现。** 确认 Spike 计划或直接指定语言后,再写 `adr/0001-implementation-language.md`。
---
## 8. 与「无标记 = 注释」的关系
实现必须先做**行分类**(见 [code-vs-comment.md](code-vs-comment.md)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。