- 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。
6.1 KiB
Executable File
6.1 KiB
Executable File
参考实现:技术选型分析(尚未拍板)
| 状态 | 分析中 — 未定案 |
| 日期 | 2026-08-04 |
| 说明 | 对比候选与约束;不在本文直接开写实现仓库脚手架 |
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,最终实现语言须单开 ADR 确认后再动工。
1. 我们在选什么
参考实现至少包含:
- 读入
.mq.md(含 frontmatter 混合行) - 对齐 GFM 的结构:标题、列表(
-/+/1.)、强调、表格、围栏、链接 - Lower:行首判别、标题树作用域、列表符语义、注释剥离
- 两遍:收集定义 + 导入 → 求值
- 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. 关键技术风险(与选语言正交)
- 行首判别 vs 块解析器 — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到源行映射。
- frontmatter 非纯 YAML —
>导入行是扩展;不能整块丢给严格 YAML 解析器。 +与-列表 — 多数解析器都认,但 lower 必须保留项目符字符,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。*else vs*返回*vs 强调 — 依赖 inline 解析与「整行恰好一个*」的行级规则并存。
以上 4 点应作为选型验收用例,写进 ADR:用最小样例在候选栈上 Spike,再定案。
6. 建议的决策流程(尚未执行)
- Spike(各 ≤0.5–1 日)
- 候选 A:TS + remark-gfm — 能否区分
-/+bullet、解析单列表格、读 strong/emphasis。 - 候选 B:Rust + comrak/pulldown — 同上。
- (可选)C 或 D 若团队有偏好再做。
- 候选 A:TS + remark-gfm — 能否区分
- 对照验收用例(固定):
tests/structure/hello.mq.md、branch.mq.md(+)、collection.mq.md(表)、含import x:x.mq.md的 frontmatter 行。 - 出 ADR:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
- 再建仓库脚手架与测试——禁止在 ADR 前默认生成
package.json/Cargo.toml当既成事实。
7. 当前态度(非正式投票)
| 阶段 | 倾向(待 Spike 验证) |
|---|---|
| 语法验证期 | 更可能是 TypeScript + remark(快、GFM 近) |
| 长期生产编译器 | 开放 Rust / Go,不与验证期绑定 |
本文不授权开始实现。 确认 Spike 计划或直接指定语言后,再写 adr/0001-implementation-language.md。
8. 与「无标记 = 注释」的关系
实现必须先做行分类(见 code-vs-comment.md),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。