# [recycle] mnote Rust 内核替换剩余目标清单

> 更新时间：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/ARCHITECTURE.md`

## 1. 本文目的

本文不再回答“Rust 内容是否已经回迁到主仓”，而是直接回答：

> **距离“用 Rust 内核替换原有内核，并让绝大部分功能 CLI 化、可供 AI 自主编辑”这一最终目标，我们现在还差什么。**

当前结论很明确：

- **单仓收口已经基本完成**
- **Rust workspace 与 P0 crate 已经落位**
- **部分前端 API 已经接入 Rust 风格协议与 bridge 接缝**
- **但“Rust 真正成为唯一执行内核”这件事还没有完成**

也就是说，当前更接近：

> **“前端/Node 先学会说 Rust 协议”**

而不是：

> **“产品已经由 Rust 内核统一执行”**

---

## 2. 当前已经完成的基础

截至目前，已经完成的只是替换前的基础设施准备：

- `/mnt/Data1T/mnote/rust/` 已成为主仓内唯一 Rust workspace 根。
- `core-domain`、`core-protocol`、`event-log`、`storage-convex-bridge`、`index-fts` 已落位。
- `rust/design/core/01~04` 核心设计文档已落位。
- 文档内容、标题、统计、Sidebar 等链路，已经开始使用统一 envelope、`request_id`、`trace_id`、`idempotency_key` 等 bridge 元信息。
- `command_logs`、`domain_events` 已有首批落账能力。

这些工作解决的是：

- 单仓问题
- 协议问题
- 目录问题
- 第一批接缝问题

**它们还没有解决“原内核是否已经被 Rust 取代”的问题。**

---

## 3. 还差的核心目标

## 3.1 还没有形成“Rust 唯一执行内核”

这是当前最大的缺口。

虽然已有一部分 route 在构造 Rust 风格 request，但真实执行主链仍然大量停留在 `Next.js route + TypeScript + Convex client`。

当前仍明显属于旧执行面的代表链路包括：

- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/documents/create/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/documents/delete/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/documents/move/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/documents/restore/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/documents/duplicate/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/search/documents/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/mindmap/[docId]/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/onlyoffice/*.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/media/*.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/tables/*.ts`

这说明目前还没有做到：

- 所有核心读写先进入 Rust `Command / Query / Tool` 层
- 所有执行规则由 Rust 决定
- Node/Next 只做 transport、auth、session、streaming、UI 适配

最终目标需要变成：

- Web route 只负责接请求、鉴权、转发、回流结果
- Rust 负责真正的命令执行、查询聚合、约束校验、冲突处理、日志和事件生成

验收标准：

- 文档、块、Sidebar、搜索、页面树、Mindmap、OnlyOffice、媒体、表格等主链路都有 Rust 执行入口
- 前端 route 不再手写业务规则和数据聚合
- TypeScript 侧不再直接成为业务真内核

## 3.2 还没有完成“全域能力模型”的 Rust 化

当前 Rust workspace 只有 P0 通用内核 crate，缺的不是“再多几个通用 crate”，而是产品能力域本身还没被吸进 Rust。

还没有真正完成 Rust 化的能力域至少包括：

- 页面树与层级操作
- 页面创建、移动、复制、删除、恢复、清空回收站
- BlockNote block 级操作全量协议
- 搜索与召回
- 引用、反链、嵌入
- 媒体与附件
- 在线表格
- Mindmap
- OnlyOffice 会话、签名、回调、强制保存
- AI 调用的写入工具面

当前 `core-domain` 和 `core-protocol` 更像底层骨架，但还没长成完整产品内核。

验收标准：

- 每个产品域都有明确 Rust domain model、command、query、tool contract
- 前端不再自行定义第二套 payload 形状
- “页面系统”和“对象系统”不再由不同 TS route 各自发明规则

## 3.3 CLI 入口还没有建立起来

你的目标里有一条是关键约束：

> **绝大部分功能 CLI 化**

这件事当前还远未完成。

直接证据是：

- `mnote-cli` 已并入主仓 workspace，但当前还只是最小命令面与 `--json` 计划输出协议
- `/mnt/Data1T/mnote/rust/scripts/` 还未初始化
- `/mnt/Data1T/mnote/rust/bridge/` 已初始化最小说明目录，且 `crates/bridge-runtime` 已提供 Phase 1 最小真实执行样板
- `/mnt/Data1T/mnote/rust/tests/`、`/mnt/Data1T/mnote/rust/fixtures/` 还未形成 CLI 驱动的验收体系

这意味着目前仍然缺少：

- 真正可执行而不止输出计划的统一 CLI 二进制入口
- 可脚本化的命令集
- 稳定的 stdout/stderr/json 输出协议
- 面向 AI 的非交互调用模式
- dry-run / plan / apply / rollback 风格能力

最终至少应该具备的 CLI 面包括：

- `page create/get/update/move/delete/restore/list`
- `block insert/replace/move/delete/get`
- `search query`
- `sidebar dataset`
- `mindmap get/put/op`
- `onlyoffice sign/callback/forcesave/session`
- `media upload/list/get/delete`
- `table create/get/update`
- `tool run <tool-name> --json`

验收标准：

- 核心功能可以不经过浏览器完成
- 核心功能可以稳定返回 JSON
- shell、脚本、AI agent 都能直接调用
- CLI 和 Web 不再各维护一套业务实现

## 3.4 AI 还没有真正建立在 Rust 工具面之上

当前已经有 AI 入口：

- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/ai-agent/run/route.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.tsx`

但这套 AI 执行仍主要建立在前端/Node 工具注册表与页面侧 bridge 上，不是建立在 Rust 原生 tool protocol 上。

这会带来四个问题：

- AI 能调用的工具面和 Web 内部实现强耦合
- AI 与 CLI 不是同一执行平面
- AI 写入行为缺少统一事务语义
- AI 很难获得稳定、可审计、可回放的编辑能力

为了实现“AI 可自行编辑”，至少还差以下目标：

- Rust 提供稳定的 `Tool` 执行协议，而不是只提供 `Command/Query` 壳
- AI 调用和 CLI 调用共享同一工具注册面
- 每个写入工具都支持明确的目标对象、权限校验、冲突返回、审计日志
- 支持 `validate_only`、`dry_run`、`explain_plan` 之类的安全模式
- 支持机器可消费的错误码，而不是前端文案式错误

最终目标不是“AI 像用户点按钮一样绕进前端”，而是：

> **AI 直接调用 Rust 工具内核完成读写，Web 只是展示层。**

验收标准：

- AI agent 使用的写入工具与 CLI 使用的工具完全同源
- AI 的每次编辑都能追踪到 command、event、trace、目标对象和 actor
- AI 可稳定执行页面编辑、块编辑、检索、结构化改写、批处理操作

## 3.5 观测、审计、幂等和失败恢复还只完成了首批链路

现在已有 `command_logs`、`domain_events`，但仍是首批写链路覆盖，不是全域治理。

仍缺的能力包括：

- 所有命令统一落账
- 所有失败态统一编码
- 统一重试与幂等语义
- 统一冲突模型
- 统一补偿与回放
- 统一事件重建和索引重放

如果没有这一层，CLI 和 AI 即使能写，也不够稳定。

验收标准：

- 任一写操作都能查 request、trace、command、domain event
- 幂等 key 在 CLI、AI、Web 三侧语义一致
- 冲突、拒绝、权限不足、对象不存在等错误有统一 code
- 可从事件或命令日志重建关键派生层

2026-04-15 进展补记：

- `rust/crates/core-protocol` 与 `bridge-runtime` 已新增 `bridge_request_get`、`bridge_trace_get`、`bridge_command_get`、`event_replay`、`index_rebuild` 这组统一观测/恢复能力；当前 `/api/bridge/request` 与 `/api/bridge/trace` 也已切到 Rust query plan + TS transport 的同一路径，不再各自直连 Convex 查询。
- `src/lib/documents/bridge-log.ts` 已把命令日志与领域事件的状态语义显式化，支持 `pending/succeeded/failed/rolled_back` 与 `pending/committed/rejected/failed` 两套状态模型，为后续冲突、失败和补偿写回提供稳定落点。

当前仍未关闭的缺口：

- 失败态、冲突态虽然已经在页面主写链与 AI/Mindmap 写链补上第一批落账，但仍未覆盖所有对象域写链。
- `event_replay` / `index_rebuild` 目前已成为正式命令面，但还主要停留在 runtime/工具层，尚未形成完整的持久化游标、任务调度和断点续跑体系。
- workspace 级总览、分页、按对象范围筛选等观测 UI 仍未完善。

## 3.6 搜索、索引和派生视图仍在持续切换中

2026-04-15 进展补记：

- `search.documents` 已不再把核心 ranking / snippet / filter 留在 TS route。当前 `/mnt/Data1T/mnote/wolai-frontend/src/app/api/search/documents/route.ts` 只保留参数校验、原始数据装载与 HTTP 回传；标题/正文/思维导图/表格/附件的匹配合并、高亮 snippet 与 OCR 待补队列决策已进入 `rust/crates/index-fts/src/lib.rs`。
- `search.recent` 已补齐独立 Rust query 名称，并通过 runtime 返回最近访问结果；当前保留 `/api/search/recent` 作为“打开页面后写最近访问记录”的 side-effect 接口，不与搜索召回混在一条写链里。
- `sidebar.dataset.list` 已从“只在 route 上挂一个 Rust queryName”推进为真实 runtime query transport，`/api/sidebar` 现会先经过 Rust runtime，再调用 `sidebar:datasetList`。

当前仍未完全关闭的缺口：

- 索引重建、校验与回放命令还未落到产品主路径。
- `src/app/(app)/layout.tsx` 的 SSR 侧边栏初始数据仍复用现有 `loadSidebarDataFromConvex` helper，没有一并切到 runtime transport。

更新后的验收标准：

- `search_web`、`image_read`、`slash_run` 这类 AI 核心工具必须保持 `RUST_OWNER`，不能回退到 TS 真执行兜底。
- `builtins/**` 中已被 Rust 替代的服务端真入口必须进入第一批 `TS_LEGACY_DELETE`，清单以 `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-legacy-delete-list.md` 为准。

- 搜索结果由 Rust query / index 层给出。
- TS 前端只做 UI 投影，不做核心排序与召回逻辑。
- 索引可重建、可校验、可回放。

## 3.7 Mindmap 和 OnlyOffice 还没有进入真正的 Rust adapter 执行层

现在对这两个对象域，文档上已经明确了边界，但执行层仍主要在现有 TS/Convex 逻辑。

现状更接近：

- **边界想清楚了**
- **前端形态保住了**
- **但 Rust adapter 还没真正接管**

缺口主要包括：

- `adapter-mindmap` 尚未并入主仓
- `adapter-onlyoffice` 尚未并入主仓
- Mindmap 节点操作还没有稳定的 Rust ops 协议
- OnlyOffice 的 sign / proxy / callback / forcesave 还没统一进入 Rust 对象适配层

验收标准：

- Mindmap 的结构操作可由 CLI 与 AI 直接调用
- OnlyOffice 的对象能力具备统一 session/asset 边界
- 不需要依赖前端 route 才能操作这些对象

## 3.8 仍缺一条“从旧内核切换到新内核”的明确割接路线

目前已有 backport plan，也有 phase checklist，但还缺一个更硬的最终割接视角：

- 哪些旧 TS route 会被逐步下线
- 哪些功能先双写、再单写
- 哪些功能允许长期保留在前端侧
- 哪些功能必须强制进入 Rust
- 何时可以宣布“原内核不再是主执行面”

如果没有这一条，项目会长期停留在“看起来在迁移，实际上双内核并存”的状态。

验收标准：

- 列出旧执行面的退役清单
- 每个能力域有 cutover milestone
- 明确宣布 Rust 成为唯一业务执行平面时的准入条件

2026-04-15 进展补记：

- 本轮已新增 `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md`，首次把页面系统、块系统、查询聚合、AI、Mindmap、OnlyOffice、兼容接口统一盘点为 `RUST_OWNER / TS_TRANSPORT_KEEP / TS_COMPAT_PENDING / TS_LEGACY_DELETE` 四类状态。
- 当前“不明确”的问题已经收口为“执行尚未完成”的问题：退役清单、阶段 gate 与最终宣布口径都已写清，但旧接口的物理删除和 AI 工具面的完全统一还未完成。

---

## 4. 对最终目标的重新拆解

如果目标是：

> **Rust 内核替换原有内核，绝大部分功能 CLI 化，AI 可以自行编辑**

那么最终至少要同时满足下面四件事。

## 4.1 Rust 是唯一业务执行平面

要求：

- Web、CLI、AI 都调用同一 Rust command/query/tool 内核
- 前端不再是业务规则主载体

## 4.2 CLI 是一等公民，不是调试附属品

要求：

- 大部分核心能力都能通过 CLI 完成
- 输出稳定 JSON
- 支持脚本化、批处理和非交互执行

## 4.3 AI 只是 CLI/Tool 的智能调度者

要求：

- AI 不再依赖页面私有 bridge 才能编辑
- AI 调用的每一步都可审计、可回放、可限权

## 4.4 Convex 继续是事实层，但不再直接暴露产品规则

要求：

- Convex 主要承担持久化与事实保存
- 规则、协议、工具、索引、对象适配统一收进 Rust

---

## 5. 建议按优先级补齐的剩余里程碑

按最终目标倒推，接下来最应该补的不是 UI，而是下面六个里程碑。

### M1. 建立真实 Rust 执行入口

- 初始化 `rust/bridge/`
- 让 Web route 可以调用真实 Rust 运行时，而不是只在 TS 中模拟 Rust request
- 先覆盖 `documents.create/get/save/title/options/stats/sidebar/search`

### M2. 并入 `mnote-cli`

- 在主仓加入 CLI crate
- 先定义稳定命令面和 JSON 输出协议
- 让页面、块、搜索、Sidebar 至少先能命令行操作

### M3. 完成页面系统与块系统的 Rust 接管

- 页面创建、移动、删除、恢复、复制
- block 插入、替换、移动、删除
- 页面树与回收站

### M4. 完成搜索/索引/派生视图 Rust 化

- 把搜索、snippet、排序、Sidebar 数据集聚合切到 Rust
- 建立索引重建与校验命令

### M5. 完成对象域 adapter

- `adapter-mindmap`
- `adapter-onlyoffice`
- 后续再看媒体、表格等对象域

### M6. 让 AI 与 CLI 共用同一 Tool 面

- AI 不再调用前端私有写入逻辑
- 改为直接使用 Rust tool protocol
- 加入 dry-run、权限、审计、回放能力

---

## 6. 一句话结论

当前不是“还差一点点就完成 Rust 内核替换”，而是：

> **我们已经完成了 Rust 内核替换前的单仓收口、协议奠基和首批接缝，但距离“Rust 真正取代旧内核，并让 CLI 与 AI 成为一等执行入口”还差一整层执行面重构。**

最关键的剩余目标只有三条：

- **把业务执行权从 TS route 真正移交给 Rust**
- **把核心能力系统化地做成 CLI**
- **让 AI 与 CLI 共用同一套 Rust tool 内核**

只要这三条没完成，就还不能说“原有内核已经被 Rust 替换”。