Files
marqdo/doc/design/tech-stack.md
T
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

6.1 KiB
Raw Permalink Blame History

参考实现:技术选型分析(尚未拍板)

状态 分析中 — 未定案
日期 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(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),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。