# 参考实现:技术选型分析(尚未拍板) | | | |---|---| | 状态 | **分析中 — 未定案** | | 日期 | 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 样例很小 | | 低 | 浏览器内运行 | 可后置 | 非准则:跟风、先写再选、与「生成 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`(表)、含 `> 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)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。