# 阶段 0 · 技术选型报告

> 项目：new-markdown（Windows Markdown 所见即所得编辑器）
> 日期：2026-11-13 · 状态：阶段 0 已实测，待大王拍板后进入阶段 1

## 1. 结论先行

| 层 | 选型 | 版本（已核查） | 许可证 |
|---|---|---|---|
| 桌面框架 | **Tauri 2** | @tauri-apps/api 2.12.4 | Apache-2.0 OR MIT |
| 前端 | **React 18 + TypeScript 5 + Vite 5** | 与原型一致 | MIT |
| UI | **Tailwind CSS + 自定义组件**（阶段 1 接入） | — | MIT |
| 编辑器内核 | **Milkdown 7（基于 ProseMirror）** | @milkdown/kit 7.23.0 | MIT |
| Markdown 解析 | **unified / remark（remark-gfm）**（Milkdown 内置管线） | remark-gfm 4.0.1 / unified 11.0.5 | MIT |
| 数学公式 | **KaTeX**（阶段 3 接入） | 0.19.1 | MIT |
| 图表 | **Mermaid**（阶段 3 接入） | 12.3.0 | MIT |
| 代码高亮 | **Shiki**（阶段 3 接入；编辑态高亮走 ProseMirror 装饰） | 4.6.0 | MIT |
| 本地数据库 | **SQLite**（rusqlite，随 Tauri 后端，阶段 4 接入） | — | MIT/公有领域 |
| 自动更新 | **Tauri Updater**（阶段 7） | — | Apache-2.0 OR MIT |

全部依赖为 MIT / Apache-2.0，无 GPL 类传染性许可证，无商业授权风险。

## 2. 编辑器内核对比（本项目成败点，重点核查）

候选均围绕 ProseMirror 生态或源码编辑生态逐项核查：

| 维度 | Milkdown 7 ✅ 选用 | 裸 ProseMirror 自研 | Tiptap 3 | CodeMirror 6 |
|---|---|---|---|---|
| 底层模型 | ProseMirror 文档模型（事务/选区/历史完整） | 同左，但一切自己造 | ProseMirror | 自有文本模型 |
| Markdown 双向转换 | **原生**：remark 解析 → PM 文档；serializerCtx 序列化回 md，阶段 0 实测保真（见 03 号报告） | 需自研 parser/serializer 全套，工作量与风险最高 | 官方 Markdown 支持仍属扩展层，往返保真弱于 Milkdown（标题/表格/任务列表需逐项补） | 无文档模型，等于源码模式，做不到 Typora 式即时渲染 |
| GFM（表格/任务列表/删除线/脚注） | preset-gfm 开箱，实测全保真 | 自研 | 扩展拼装 | 仅高亮 |
| Typora 式输入规则（`# `→标题、`- [ ]`→任务） | commonmark/gfm 预设内置 input rules | 自研 | 部分扩展 | 无 |
| IME 组合输入 | 继承 ProseMirror View 的 composition 处理，上层未覆盖（代码核查；真实输入法须 Windows 人工验） | 同左 | 同左 | 另一套机制 |
| 撤销/重做 | plugin-history，实测通过 | 自接 history 插件 | 内置 | 内置 |
| 表格编辑 | gfm 表格节点 + prosemirror-tables 体系，可扩展浮动工具栏 | 自研 | 扩展 | 无 |
| 维护与体积 | 活跃维护（7.23.0，2026 年在更）；原型 gzip 194KB（未分包） | — | 活跃；部分高级扩展商业化 | 活跃 |
| 风险 | 序列化首轮会规范化个别写法（见 §3）；大文档全量加载性能须阶段 6 实测 | 周期不可控，直接违反「先验证再开发」的风险控制目标 | 为达同等 md 保真需自补大量转换逻辑，等于半自研 | 不满足产品定位，排除 |

**决策：Milkdown 7.23.0（@milkdown/kit 单包入口）**。理由：它是唯一「Markdown 双向转换即产品级能力」的现成内核，且阶段 0 已用与产品同一条代码路径实测通过核心验收项；裸 ProseMirror 自研只在 Milkdown 出现不可绕过的缺陷时作为后备（文档模型同源，迁移成本可控）。

**不采用 Milkdown Crepe**（官方开箱组件版）：其预置 UI/主题与本产品自定义界面、主题系统冲突，阶段 1 起直接用 Kit 组装自己的编辑器装配层。

## 3. 已知限制与对策（选型时即登记，不等踩坑）

1. **首轮序列化规范化**：打开一份非规范写法的 md 并保存，个别写法会被规范化（实测：表格对齐 `| :--- |` → `| :- |`、脚注/HTML 等不受影响、无序列表符号已通过 `remarkStringifyOptionsCtx: { bullet: '-' }` 对齐 Typora 习惯）。内容与语义零丢失，第二轮起逐字稳定（自动化测试硬断言）。阶段 2 评估是否引入「未修改段落不重序列化」的原文保真策略。
2. **数学/Mermaid/代码高亮不在阶段 0 范围**：实测其原始文本（`$E = mc^2$`、mermaid 代码块）在往返中完整保留，不会丢内容；渲染与编辑插件按需求排在阶段 3（KaTeX/Mermaid/Shiki 均为 MIT，已核查）。
3. **脚注**：不在 Milkdown 官方预设宣传清单内，但阶段 0 实测探针显示 remark-gfm 管线可完整往返脚注（定义与引用均保留），阶段 3 复测后转正。
4. **大文档性能**：158KB 文档在 jsdom（无布局引擎、显著慢于真实 WebView2）下全量加载约 3.6s、序列化约 0.27s——仅作悲观下界参考，不作为产品指标。编辑期走 ProseMirror 增量事务，不整篇重渲染（架构性质）。真实指标按需求 §20 在阶段 6 用 WebView2 实测 100KB/1MB/5MB 并记录。
5. **Tauri 本机验证缺口**：本开发沙箱（Linux）无 Rust 工具链，Tauri 壳层无法在此编译验证；阶段 1 在 Windows 上完成首次 Tauri 构建并作为阶段 1 验收前置（需 Rust stable + VS Build Tools + WebView2，均为 Windows 常规组件）。

## 4. 桌面与系统层选型说明

- **Tauri 2 而非 Electron**：安装体量与内存占用显著更小，WebView2 为 Windows 10/11 系统组件；文件/对话框/更新均走官方插件与 Rust 侧命令，符合需求 §2 表格原定方案，无变更。
- **SQLite 只存应用数据**（设置/最近文件/工作区/恢复记录），正文永远以 .md 文件为唯一事实源（需求 §18），阶段 4 落地。
- **源码模式**：CodeMirror 6（MIT，已核查）承担，阶段 2 与即时渲染共用同一文档入口、切换不丢内容。