Refresh ADR 0001 after successful Python spike.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-04 11:01:56 +08:00
1 parent 23fa4284a8
commit 8f44f10bc9
1 file changed
+27 -49
+27 -49
View File
@@ -5,28 +5,24 @@
| 状态 | **Spike 通过(Python)** — 参考实现语言待勾选 |
| 日期 | 2026-08-04 |
| 决策者 | chaungming + 协作 |
| 相关 | [tech-stack.md](../design/tech-stack.md) · [markdown-mapping.md](../design/markdown-mapping.md) |
| 相关 | [tech-stack.md](../design/tech-stack.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [spike/REPORT.md](../../spike/REPORT.md) |
---
## 背景
语法宪法 v0.1 已定。需要选定**第一版参考实现**的实现语言与 GFM 解析前端,以便:
语法宪法 v0.1 已定。需要选定第一版参考实现的实现语言与 Markdown 前端,以便跑通 `examples/*.mq.md`,并用测试锁定行首判别、`*`/`**`、`+`/`-`、表格、frontmatter `>`。
- 跑通 `examples/*.mq.md`
- 用测试锁定行首判别、`*`/`**`、`+`/`-`、表格、frontmatter `>`
- **不**在未论证前把某语言脚手架当成既成事实
目标是**验证宪法**,不是一次定终身的生产编译器。
目标是验证宪法,不是一次定终身的生产编译器。
---
## 约束(验收必须满足)
1. 能区分无序列表的 **`-` vs `+`** 项目符(分支/循环)。
2. GFM **表格**、**emphasis / strong**(`*` / `**`)边界可映射回源位置。
3. 能做**行预分类**(无标记=注释)再 lower 到 Marqdo AST。
4. frontmatter 中非纯 YAML 的 **`> file.mq.md` 行**可解析。
1. 能区分无序列表的 `-` vs `+` 项目符(分支/循环)。
2. GFM 表格、emphasis / strong(`*` / `**`)可解析。
3. 能做行预分类(无标记=注释)再 lower 到 Marqdo AST。
4. frontmatter 中非纯 YAML 的 `> file.mq.md` 行可解析。
5. CLI + 自动化测试可对照 `examples/` 期望输出。
---
@@ -35,58 +31,40 @@
| ID | 方案 | 验证期适配 | 长期编译器适配 |
|----|------|------------|----------------|
| A | **TypeScript + remark/rehype(mdast)+ Vitest** | 高 | 中(可留作工具链) |
| B | **Rust + comrak 或 pulldown-cmark + 集成测试** | 中 | 高 |
| C | Python + mistune/markdown-it-py | 高(原型) | 低 |
| A | TypeScript + remark/mdast + Vitest | 高 | 中 |
| B | Rust + comrak / pulldown-cmark | 中 | 高 |
| C | Python + markdown-it-py + pytest | 高 | 中(可作参考实现) |
| D | Go + goldmark | 中 | 中 |
详见对比:[tech-stack.md](../design/tech-stack.md)。
详见 [tech-stack.md](../design/tech-stack.md)。
---
## 提议决策(请确认)
## 已执行:Python Spike
### 验证期(现在 → 跑通 examples)
因 npm 过慢,Spike **改用选项 C(Python)**,目录 [`spike/`](../../spike/)。
**Spike 优先采用 Python(快速验证),不默认上 npm/TypeScript 脚手架。**
结果:**S1–S5 全部通过**(`pytest` 6 passed)。见 [REPORT.md](../../spike/REPORT.md)。
| 步骤 | 选择 |
|------|------|
| **Spike(进行中)** | **Python 3.11+** + 轻量 Markdown 库(如 `markdown-it-py`)+ `pytest` |
| 验证通过后的参考实现 | 另议:可继续 Python,或再评 TypeScript / Rust(见原选项 A/B) |
关键发现:
理由:npm 安装过慢会阻塞 Spike;Python 足以验收 S1–S5 与「行分类 / bullet 区分」风险。
**原选项 A(TypeScript + remark)降为验证通过后的候选实现,不再作为 Spike 必经之路。**
### 长期(宪法稳定后)
**不绑定 A。** 另开 ADR 评估 Rust(选项 B)作正式编译器/单二进制;TS 实现可降级为兼容测试预言机或弃用。
### 明确不选(验证期)
- **C Python** 作唯一实现:易成抛弃原型,双维护差。
- **未 Spike 就写死 B**:怕拖慢验证。若你更熟 Rust且愿意先 Spike B,可对调。
- `-` / `+` 必须用**行扫描**保留项目符。
- frontmatter 导入行不能整块丢给严格 YAML。
- `markdown-it-py` 足够解析强调与表格;勿开缺依赖的 linkify。
---
## Spike 清单(定案前 ≥ 完成 A;可选 B)
## 待确认:参考实现语言
| # | 用例 | 通过标准 |
|---|------|----------|
| S1 | `*a*` vs `**a**` | 得到 emphasis / strong,且能还原源码切片 |
| S2 | `- item` vs `+ item` | AST **能区分** bullet(或源行补救成功) |
| S3 | 单列表格 | 表头+单元格可遍历 |
| S4 | 文件头 `---` + 正文内 `---` | 能分开 frontmatter 与可选框线 |
| S5 | frontmatter 行 `> x.mq.md` | 不被 YAML 解析掐死,可抽出导入 |
Spike 已证明 Python 路径可行。请勾选正式参考实现:
**提议流程:** 先做 **Python Spike(本目录 `spike/`,≤1 日)** → 记录 S1–S5 通过/补救 → 再决定参考实现语言(Python 延续 / TS / Rust)→ Accepted 后才建正式 `src/`。
- [ ] **继续 Python**(推荐:与 Spike 同栈,立刻可写 `marqdo run`)
- [ ] 改选 TypeScript(选项 A)
- [ ] 改选 Rust(选项 B)
- [ ] 其它:________
---
确认后将本 ADR 标为 **Accepted**,再建立正式包(非 `spike/` 玩具目录)。
## 确认栏
### 长期
- [x] Spike 使用 Python(进行中)
- [ ] Spike 通过后:参考实现继续 Python
- [ ] Spike 通过后:改选 TypeScript
- [ ] Spike 通过后:改选 Rust
- [ ] 其它:________
不排除日后用 Rust 做生产编译器;与验证期/参考实现可以分离。