mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-replacement-roadmap-v1.md

# [recycle] mnote Rust 内核替换总路线图 v1

> 更新时间：2026-04-15
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-backport-plan.md`
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-backport-phase-checklist.md`
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-missing-targets.md`
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`

## 1. 目标定义

本路线图对应的最终目标只有一句话：

> **用 Rust 内核取代当前 TypeScript/Next route 主导的业务执行面，让 Web、CLI、AI 共享同一套 Rust Command / Query / Tool 内核。**

这里包含三个同时成立的条件：

- Rust 成为唯一业务执行平面
- 绝大部分核心能力都能通过 CLI 调用
- AI 编辑能力建立在与 CLI 同源的 Rust 工具面上

如果只完成其中一部分，都不能算“Rust 内核已经替换原有内核”。

---

## 2. 当前阶段判断

当前仓库已经完成的是：

- 单仓收口
- Rust workspace 落位
- P0 crate 与核心设计文档落位
- 首批 bridge 协议接缝
- 首批日志与事件落账

当前仓库还没有完成的是：

- Rust 真实执行入口
- `mnote-cli`
- 全域能力域建模
- AI/CLI 共用 Tool 面
- 旧 TS 执行面的系统性退役

因此当前阶段应定义为：

> **Phase 0 完成，Phase 1 即将开始。**

其中：

- `Phase 0` = 单仓收口 + 协议奠基
- `Phase 1` 以后才是“真正的内核替换”

---

## 3. 总体迁移原则

整个替换过程必须遵守下面六条原则。

### 3.1 Web 不再承载业务真规则

Next route 可以保留 transport、auth、session、streaming、SSR/BFF 职责，但不再长期承载核心业务执行规则。

### 3.2 CLI 与 AI 必须共用同一执行面

不能出现：

- CLI 走一套实现
- AI 走一套实现
- Web 再走第三套实现

最终只能保留一套 Rust 内核，三种入口共享。

### 3.3 Convex 继续是事实层，不是业务规则层

Convex 继续负责主事实保存，但对象规则、命令语义、查询聚合、索引、工具协议应逐步收回 Rust。

### 3.4 先做执行面替换，再做旧面退役

不能先删旧链路再补 Rust，也不能长期停留在双内核并行。

正确顺序是：

1. 建立 Rust 执行链
2. 双入口对齐
3. 完成回归
4. 退役旧 TS 业务执行逻辑

### 3.5 先覆盖高频主链路，再覆盖对象域

优先级应是：

1. 页面系统
2. 块系统
3. Sidebar / 搜索 / 索引
4. AI 写入工具面
5. Mindmap / OnlyOffice / Media / Table

### 3.6 每一阶段都必须有割接标准

每个阶段都要明确：

- 哪些功能已由 Rust 接管
- 哪些 TS route 仍是临时面
- 哪些旧实现可退役

---

## 4. 分阶段路线

## Phase 1：建立真实 Rust 执行入口

目标：

- 在主仓内建立最小 Rust bridge/runtime
- Web route 能调用真实 Rust 执行器
- 不再只是在 TypeScript 中构造 Rust 风格 request

优先覆盖：

- `documents.meta`
- `documents.content`
- `documents.save`
- `documents.title`
- `documents.options`
- `documents.stats`
- `sidebar.dataset.list`
- `search.documents`

阶段产出：

- `/mnt/Data1T/mnote/rust/bridge/`
- 最小 runtime executor
- Web -> Rust -> Convex 的真实样板链

阶段完成标准：

- 至少 1 条读链和 2 条写链真实经过 Rust 执行
- 对应 TS route 不再直接持有业务拼装逻辑

## Phase 2：引入 `mnote-cli` 并冻结 JSON 协议

目标：

- 把 CLI 变成一等入口
- 定义稳定的 machine-readable 输出
- 为后续 AI 共用工具面打基础

首批 CLI 面：

- `page`
- `block`
- `search`
- `sidebar`
- `tool`

阶段产出：

- `rust/crates/mnote-cli/`
- 统一 exit code 约定
- `--json` 输出契约
- `dry-run` / `validate-only` 基础能力

阶段完成标准：

- 核心页面和块操作能脱离浏览器完成
- CLI 与 Web 调用同一 Rust 执行面

## Phase 3：页面系统 Rust 化

目标：

- 页面创建、移动、复制、删除、恢复、回收站等能力收口到 Rust
- 页面树、父子关系、排序、引用更新不再由 TS route 零散实现

优先覆盖：

- `documents.create`
- `documents.move`
- `documents.delete`
- `documents.restore`
- `documents.duplicate`
- `documents.empty-trash`
- `documents.copy-tree`

阶段完成标准：

- 页面生命周期操作统一走 Rust command
- 旧 TS route 只保留 transport 包装

## Phase 4：块系统 Rust 化

目标：

- 把 BlockNote 正文相关的结构化编辑命令真正变成 Rust 内核能力
- AI/CLI 可直接调用块操作，不依赖浏览器交互细节

优先覆盖：

- `blocks.get`
- `blocks.patch`
- `blocks.move`
- `blocks.embed`
- `doc_insert_blocks`
- `doc_replace_range`

阶段完成标准：

- Rust 拥有稳定的 block ops 协议
- Web 编辑器只负责快照采集、渲染与交互

## Phase 5：搜索、索引与派生视图 Rust 化

目标：

- 把搜索、排序、snippet、Sidebar 数据集聚合统一移入 Rust
- 建立索引重建和派生视图回放能力

优先覆盖：

- `search.documents`
- `search.recent`
- `sidebar.dataset.list`
- 索引重建与校验命令

阶段完成标准：

- TS route 不再做核心召回和 ranking
- `index-fts` 真正进入产品主路径

  2026-04-15 Phase 5 第一刀补记：`search.documents`、`search.recent`、`sidebar.dataset.list` 已补齐到主仓 Rust query/runtime 主链。`rust/crates/core-protocol` 新增 `SearchDocuments/SearchRecent` 契约，`storage-convex-bridge` 新增 query name -> Convex function 映射，`bridge-runtime` 现同时支持 query plan 输出与“携带原始 dataset 时直接在 Rust 内执行并返回 result”。其中 `search.documents` 的召回后排序、snippet、高亮、OCR 待补队列决策已迁入 `rust/crates/index-fts` 的 `evaluate_search_documents`；`/api/search/documents` route 现仅保留参数归一化、Convex 原始数据拉取与 HTTP 回传，不再持有标题/正文/思维导图/表格/附件的打分合并逻辑。`/api/sidebar` 也已改为先经 Rust runtime 生成 `sidebar.dataset.list` plan，再通过统一 query transport 调用 `sidebar:datasetList`，不再只是挂一个 queryName 元信息。

## Phase 6：AI 与 CLI 共用 Rust Tool 面

目标：

- 让 AI 直接调用 Rust tool protocol
- Web 中的 AI Agent 只成为对话和流式展示层

能力要求：

- `Tool` 注册表
- 统一权限与对象目标
- 统一错误码
- 统一审计
- `dry-run` / `validate-only` / `explain-plan`

阶段完成标准：

- AI 与 CLI 调用同一 Tool 面
- AI 编辑结果可追踪到 command、event、trace

  2026-04-15 Phase 6 补记：已把统一观测面补进 Rust `Tool` 注册表与 `bridge-runtime`。当前 `bridge_request_get`、`bridge_trace_get`、`bridge_command_get` 三条观测查询，以及 `event_replay`、`index_rebuild` 两条恢复/重建任务，已经成为 Rust 正式能力面；`/api/bridge/request`、`/api/bridge/trace` 也已改为先经 Rust runtime 生成 query plan，再由 TS 仅做 Convex transport。后续 CLI 与 AI 若要稳定运行，必须以这组能力为统一回查/恢复前置，不再允许各入口各自手写 trace 查询与索引恢复脚本。

## Phase 7：对象域 adapter 接入

目标：

- 在不改变当前前端形态的前提下，把对象域执行层移入 Rust adapter

优先对象域：

- `adapter-mindmap`
- `adapter-onlyoffice`
- 后续再扩展 media / table

阶段完成标准：

- Mindmap 与 OnlyOffice 都可由 CLI / AI 直接操作核心对象能力
- 前端 route 不再是对象域业务真入口

## Phase 8：旧内核退役与总割接

目标：

- 明确哪些旧 TS route 只剩 transport
- 明确哪些旧业务实现可删除
- 正式宣布 Rust 成为唯一业务执行平面

阶段完成标准：

- Web、CLI、AI 全部指向同一 Rust 内核
- 核心域不再存在第二套业务执行实现

  2026-04-15 Phase 8 补记：当前主仓已新增 `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md` 作为最终割接文档。后续 Phase 8 不再接受“按感觉判断是否可以退役”的说法，而统一按该文档中的四组 gate 执行：页面/块/查询主链全部 Rust 持有，对象域只剩 transport 壳，AI/CLI 共用同一 Tool 面，以及旧 TS 兼容接口完成物理退役或明确降级。

---

## 5. 建议的切换顺序

为了降低风险，建议按下面顺序切换，而不是全面铺开。

### 批次 A：文档基础链

- `documents.meta`
- `documents.content`
- `documents.save`
- `documents.title`
- `documents.options`
- `documents.stats`

### 批次 B：页面结构链

- `documents.create`
- `documents.move`
- `documents.delete`
- `documents.restore`
- `documents.duplicate`
- `documents.copy-tree`

### 批次 C：块编辑链

- `blocks.get`
- `blocks.patch`
- `blocks.move`
- `blocks.embed`

### 批次 D：查询聚合链

- `sidebar.dataset.list`
- `search.documents`
- `search.recent`

### 批次 E：AI/CLI 工具链

- `doc_get`
- `doc_find`
- `doc_insert_blocks`
- `doc_replace_range`
- `slash_run`

### 批次 F：对象域链

- Mindmap
- OnlyOffice
- Media
- Table

---

## 6. 每阶段统一验收口径

无论哪个阶段，验收都应统一看下面六项。

### 6.1 执行入口是否真的进了 Rust

不是“TS 构造了 Rust 风格对象”，而是“Rust 真正执行了这条链”。

### 6.2 Web/CLI/AI 是否同源

如果一个能力还存在两套或三套实现，就不算完成。

### 6.3 是否具备 JSON 级输出与错误码

没有稳定 JSON 和错误码，就无法支撑 CLI 与 AI。

### 6.4 是否具备审计与回放

没有 command/event/trace，就无法长期稳定运行。

这里的“具备”不是指只落了一批日志表，而是至少同时满足：

- 任一写链都能回查 `request_id`、`trace_id`、`command_id`
- 命令、事件、冲突、失败态使用统一状态语义
- 至少有一条正式的 `event_replay` / `index_rebuild` 命令可被 CLI / AI / Web 复用
- TS route 不再私有维护第二套排障与恢复入口

### 6.5 是否补了自动化验证

每阶段都必须至少补：

- Rust 单测
- Web smoke
- 必要时的浏览器回归
- 对应 CLI smoke

### 6.6 是否明确了可退役旧面

必须显式标注：

- 哪些 TS 逻辑只剩壳
- 哪些逻辑仍是临时态
- 哪些代码已允许删除

---

## 7. 风险与防漂移要求

整个路线最容易失败的点有四个。

### 7.1 长期停留在“桥接完成即算完成”

这会导致项目永远停留在半替换状态。

### 7.2 CLI 迟迟不建立

如果不尽早建立 CLI，AI 最终还是会绕回 Web 私有逻辑。

### 7.3 对象域长期例外化

Mindmap、OnlyOffice、Media、Table 如果一直被当例外处理，最终不会形成统一内核。

### 7.4 旧 TS 执行面没有退役时点

如果不定义退役清单，旧逻辑会持续存活并反向污染新内核。

---

## 8. 一句话结论

这条路线不是“继续补几条 bridge”就能结束，而是要完成一次完整的执行面替换：

> **先把 Rust 变成真实执行器，再把 CLI 变成一等入口，最后让 AI 与 Web 共同收口到这套 Rust 内核。**

在这三个条件同时成立之前，都还不能宣布“Rust 内核已经替换原有内核”。