mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md

# [recycle] Rust 内核总割接方案 v1

> 更新时间：2026-04-16
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-replacement-roadmap-v1.md`
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-missing-targets.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/done/release-readiness-source-audit.md`

## 1. 目的

本文只回答一个问题：

> **什么时候可以宣布“Rust 已成为 mnote 唯一业务执行平面”，以及宣布前必须退役哪些旧 TS 执行面。**

这里的“退役”不等于“把所有 Next route 全删掉”。

真正要退役的是：

- TS route 内部承载的业务规则
- TS 私有工具注册表里的第二套执行语义
- 绕过 Rust command/query/tool 的直连 Convex 主链

允许长期保留的是：

- transport
- auth
- session
- streaming
- SSR / BFF
- 第三方对象服务回调壳

---

## 2. 状态定义

为了避免后续再出现“看起来迁了，实际上没迁”的模糊表述，本文统一使用下面四类状态。

### 2.1 `RUST_OWNER`

定义：

- 核心业务规则已经进入 Rust command/query/tool/runtime
- TS route 只做参数校验、鉴权、HTTP 包装、Convex transport 或第三方请求转发

处理策略：

- 允许继续保留 route 壳
- 不允许再往 route 内加业务规则

### 2.2 `TS_TRANSPORT_KEEP`

定义：

- 这条 route 本身不是业务真规则入口
- 但因为浏览器会话、回调、上传下载、SSE、客户端桥等原因，需要长期保留在 Web 层

处理策略：

- 永久保留或长期保留
- 只能承载 transport / session / proxy / callback

### 2.3 `TS_COMPAT_PENDING`

定义：

- 当前已经有部分 Rust 接缝
- 但仍存在 TS 业务拼接、对象规则或直连 Convex 的旧执行逻辑

处理策略：

- 不能宣布总割接完成
- 必须继续迁到 Rust 后，才能降级为 `RUST_OWNER` 或 `TS_TRANSPORT_KEEP`

### 2.4 `TS_LEGACY_DELETE`

定义：

- 该 route 或旧逻辑只服务于历史兼容、诊断、临时过渡或旧 UI
- 一旦对应能力完成 Rust cutover 并切完调用方，就应删除

处理策略：

- 先停写
- 再切调用
- 最后物理删除

---

## 3. 当前总盘点

## 3.1 页面系统

### 已进入 `RUST_OWNER`

- `wolai-frontend/src/app/api/documents/meta/route.ts`
- `wolai-frontend/src/app/api/documents/content/route.ts`
- `wolai-frontend/src/app/api/documents/title/route.ts`
- `wolai-frontend/src/app/api/documents/stats/route.ts`
- `wolai-frontend/src/app/api/documents/options/route.ts`
- `wolai-frontend/src/app/api/documents/save/route.ts`
- `wolai-frontend/src/app/api/documents/create/route.ts`
- `wolai-frontend/src/app/api/documents/move/route.ts`
- `wolai-frontend/src/app/api/documents/delete/route.ts`
- `wolai-frontend/src/app/api/documents/restore/route.ts`
- `wolai-frontend/src/app/api/documents/duplicate/route.ts`
- `wolai-frontend/src/app/api/documents/copy-tree/route.ts`
- `wolai-frontend/src/app/api/documents/create-child/route.ts`
- `wolai-frontend/src/app/api/documents/empty-trash/route.ts`
- `wolai-frontend/src/app/api/documents/purge/route.ts`
- `wolai-frontend/src/app/api/documents/template/route.ts`

判定依据：

- 已统一走 `buildDocument(Command|Query)Envelope`
- 已切到共享 page/metadata/save adapter 或 `resolveRustBridge*`
- route 只剩 transport、鉴权、参数整理与 HTTP 返回
- `create-child` 已改为复用 `documents.create`
- `template`、`empty-trash`、`purge` 已补齐 Rust runtime/transport 映射，不再由 `page-command-adapter.ts` 直接调用 Convex mutation

### 仍是 `TS_COMPAT_PENDING`

- `wolai-frontend/src/app/api/documents/embed/route.ts`

原因：

- `embed` 已不再直接调用 `api.documents.updateContent`，最终写入已改走 `documents.save`。
- 但目标页面插入点计算、`pageReference` block 组装仍在 TS 侧完成，尚未进入独立 Rust command 面。
- 因此它已经摆脱“直连 Convex mutation”的假完成状态，但还不能宣布为完全 `RUST_OWNER`。

处理结论：

- 页面旧面中，`create-child`、`template`、`empty-trash`、`purge` 已转为统一 Rust transport。
- `embed` 仍是 Phase 8 前需要继续清理的剩余页面旧面。
- 当前仍不可直接物理删除这些 route 文件，必须先切完调用方并确认不再承载 TS 内容编排。

---

## 3.2 块系统

### 已进入 `RUST_OWNER`

- `wolai-frontend/src/app/api/blocks/get/route.ts`
- `wolai-frontend/src/app/api/blocks/patch/route.ts`
- `wolai-frontend/src/app/api/blocks/move/route.ts`
- `wolai-frontend/src/app/api/blocks/embed/route.ts`

判定依据：

- 现网 route 实际统一走 `wolai-frontend/src/lib/blocks/block-command-adapter.ts`
- `patch/move/embed` 已通过 `documents.save` 主链落盘，不再依赖 route 内直连 Convex mutation
- route 仅保留 transport、参数校验与 HTTP 返回

### 仍需冻结的兼容 helper

- `wolai-frontend/src/lib/documents/block-command-adapter.ts`

说明：

- 该文件当前不再是 `/api/blocks/*` 的主调用链。
- 它仍保留旧桥接 helper 语义，因此需要明确按兼容层冻结，不能再被当成“现网主执行面”继续扩展。

### 可删的旧逻辑

- 旧 `loadBlocks/saveBlocks` 私有执行路径
- 任何绕过共享 block adapter 的 AI 文档写入旧实现

处理结论：

- 块系统主链已经满足“route 保留、旧业务逻辑退役”的前提
- 后续只允许在 Rust block ops 上继续扩展

---

## 3.3 查询聚合与观测

### 已进入 `RUST_OWNER`

- `wolai-frontend/src/app/api/sidebar/route.ts`
- `wolai-frontend/src/app/api/search/documents/route.ts`
- `wolai-frontend/src/app/api/bridge/request/route.ts`
- `wolai-frontend/src/app/api/bridge/trace/route.ts`

### 仍是 `TS_TRANSPORT_KEEP`

- `wolai-frontend/src/app/api/search/recent/route.ts`

说明：

- `search/recent` 当前只承担“打开页面后写最近访问记录”的 side-effect，不再承担搜索召回
- 它可以长期保留在 Web 层，但必须明确不是搜索业务真入口

### 当前仍缺

- workspace 级统一观测总览
- 分页、按对象过滤、按状态过滤
- 完整失败态和冲突态的全链路落账

---

## 3.4 AI 与工具面

### 已进入 `RUST_OWNER`

- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `doc_get`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `doc_find`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `doc_insert_blocks`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `doc_replace_range`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `docs_search`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `docs_read`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `search_web`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `image_read`
- `wolai-frontend/src/app/api/ai-agent/run/route.ts` 中的 `slash_run`

说明：

- Convex 主链下，`ai-agent/run` 已直接通过 `executeRustBridgeTool(...)` 执行 `docs_search`、`docs_read`、`search_web`、`image_read`、`slash_run`。
- `docsServerTools` 当前只保留非 Convex / fallback 模式，不再承担 Convex 主链真执行。
- `search_web`、`image_read`、`slash_run` 已切到 Rust Tool runtime，`ai-agent/run` 不再保留 TS 真执行兜底。

### 仍是 `TS_TRANSPORT_KEEP`

- `wolai-frontend/src/app/api/ai-agent/client-tool-result/route.ts`
- `wolai-frontend/src/lib/ai-agent/tools/builtins/onlyoffice/onlyofficeServerTools.ts` 中的 `asset_extract_outline`
- `wolai-frontend/src/lib/ai-agent/tools/builtins/onlyoffice/onlyofficeServerTools.ts` 中的 `asset_to_mindmap`
- `wolai-frontend/src/lib/ai-agent/tools/builtins/onlyoffice/onlyofficeServerTools.ts` 中的 `oo_*`
- `wolai-frontend/src/lib/ai-agent/tools/builtins/rag/**`

说明：

- `client-tool-result` 只负责浏览器内客户端工具回传，不承担业务决策。
- `asset_extract_outline` 仍依赖附件下载与 MinerU 解析，因此长期保留 TS transport / 外部服务编排。
- `asset_to_mindmap` 当前属于“TS 提纲提取 + Rust 导图写入”的明确编排边界：附件解析仍在 TS/MinerU，但导图应用已改走 Rust `mindmap_apply_ops`。
- `oo_*` 继续保持客户端插件边界，不再尝试下沉为第二套服务端真执行入口。

### 仍是 `TS_COMPAT_PENDING`

- `wolai-frontend/src/app/api/mindmap-ai/agent/route.ts`
- `wolai-frontend/src/app/api/mindmap-ai/assets/route.ts`
- `wolai-frontend/src/app/api/mindmap-ai/expand-node/route.ts`
- `wolai-frontend/src/app/api/mindmap-ai/outline-to-mindmap/route.ts`

处理结论：

- AI builtins 主链已经完成从 `TS_COMPAT_PENDING` 到 `RUST_OWNER` / `TS_TRANSPORT_KEEP` 的最终归类。
- `mindmap-ai/**` 若继续保留，必须明确只是上层产品编排，不能成为对象规则真入口。
- AI 工具矩阵与第一批旧面删除清单分别见：
  - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/ai-tool-cutover-matrix.md`
  - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-legacy-delete-list.md`

---

## 3.5 对象域

### Mindmap：已进入 `RUST_OWNER`

- `wolai-frontend/src/app/api/mindmap/[docId]/route.ts`
- `wolai-frontend/src/app/api/mindmap/[docId]/[mindmapId]/route.ts`

说明：

- `GET/POST` 之前已在 Rust query/command 主链上。
- 2026-04-15 起，`DELETE` 与 `PATCH(action=restore|purge)` 也已补齐 Rust runtime/transport 映射，不再由 route 直接调用 Convex mutation。

### Mindmap：仍是 `TS_COMPAT_PENDING`

- `wolai-frontend/src/app/api/mindmap-ai/**`

### Mindmap：已进入 `RUST_OWNER` 的补充兼容入口

- `wolai-frontend/src/app/api/mindmap-trash/empty/route.ts`

说明：

- `mindmap-trash/empty` 现已切到 `mindmaps.emptyTrashByWorkspace` Rust runtime/transport。
- 该 route 仍保留为 Web transport 壳，但不再直接持有 TS 真执行。

### OnlyOffice：已进入 `TS_TRANSPORT_KEEP`

- `wolai-frontend/src/app/api/onlyoffice/sign/route.ts`
- `wolai-frontend/src/app/api/onlyoffice/proxy/route.ts`
- `wolai-frontend/src/app/api/onlyoffice/callback/route.ts`
- `wolai-frontend/src/app/api/onlyoffice/forcesave/route.ts`

说明：

- 这四条路由因为 JWT、proxy、下载上传、第三方回调等原因会长期保留
- 但对象规则、session 边界、签名、回写准备、forcesave 计划已进入 Rust adapter

处理结论：

- OnlyOffice 当前不是“可删除 route”，而是“保留 route 壳、禁止再长业务规则”

---

## 4. Phase 8 Cutover Gate

只有下面四组 gate 同时满足，才能宣布“Rust 成为唯一业务执行平面”。

### Gate A：页面、块、查询主链全部 Rust 持有

要求：

- `documents.*` 主链不再存在 TS 业务路由
- `blocks.*` 主链不再存在第二套执行逻辑
- `search.documents`、`sidebar.dataset.list`、`bridge request/trace/command` 全部走 Rust query/runtime

### Gate B：对象域只保留 transport 壳

要求：

- Mindmap 主读写统一进入 Rust adapter
- OnlyOffice 只保留签名、代理、回调、forcesave 等 transport 壳
- 任何对象域规则都不再从 route 直连 Convex mutation 发展

### Gate C：AI 与 CLI 共用同一工具面

要求：

- `ai-agent/run` 不再为核心工具保留 `builtins/**` 私有真入口
- CLI 与 AI 调用同一组 Rust `Tool`
- `event_replay`、`index_rebuild`、`bridge_*_get` 这组观测/恢复命令对 CLI、AI、Web 等价可用
- `docs_search`、`docs_read`、`search_web`、`image_read`、`slash_run` 必须保持 `RUST_OWNER`

### Gate D：旧 TS 兼容面完成物理退役或明确降级

要求：

- `create-child`、`embed`、`empty-trash`、`purge`、`template`、`mindmap-trash/empty` 等旧接口要么迁入 Rust，要么标记为废弃并从 UI 脱钩
- `mindmap-ai/**` 若继续保留，必须明确只是上层产品编排，不能成为对象规则真入口
- 旧 `docTools` / `mindmapTools` / 页面私有写入胶水不再允许继续扩展

---

## 5. 允许删除与禁止删除

## 5.1 现在就禁止继续扩展的旧面

- `documents/create-child`
- `documents/embed`
- `documents/empty-trash`
- `documents/purge`
- `documents/template`
- `mindmap-trash/empty`
- `mindmap-ai/**` 私有写入逻辑
- `ai-agent` 中非 Rust 的核心编辑工具真入口

规则：

- 这些路径可以暂时存在
- 但不允许再加新业务逻辑
- 第一批 `TS_LEGACY_DELETE` 冻结清单见 `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-legacy-delete-list.md`

## 5.2 完成 cutover 后允许删除的旧面

- 上述旧接口本身
- 被 Rust adapter 替代后的旧 `builtins/**` 服务端工具实现
- 任何只为过渡期保留的直接 Convex 业务拼接 helper

当前已冻结的第一批删除对象：

- `documents/create-child`
- `documents/embed`
- `documents/empty-trash`
- `documents/purge`
- `documents/template`
- `mindmap-trash/empty`
- `builtins/**`

## 5.3 必须长期保留的壳

- `/api/onlyoffice/sign`
- `/api/onlyoffice/proxy`
- `/api/onlyoffice/callback`
- `/api/onlyoffice/forcesave`
- `/api/ai-agent/client-tool-result`
- 其他承担 auth/session/streaming/proxy/callback 的 Web route

这些接口可以保留，但只能承担 Web transport 责任。

---

## 6. 最终宣布口径

只有当本文第 4 节四组 gate 在主链范围内同时满足时，才允许对外使用下面这句话：

> **Rust 已成为 mnote 的唯一业务执行平面；Web route 只保留 transport、auth、session、streaming、proxy、callback 与少量明确冻结的产品编排壳。**

截至 2026-04-16：

- `docs_search`、`docs_read`、`search_web`、`image_read`、`slash_run` 已满足 Gate C 的主链要求。
- `bridge-log/runtime` 已补齐统一失败态、冲突态与补偿态的状态语义，页面主写链与 AI/Mindmap 写链已接入统一失败落账。
- `mnote-cli` 已通过仓库内真实执行 smoke，CLI 与 AI 现在可以共用同一组 Rust Tool / runtime。
- `TS_TRANSPORT_KEEP`、`TS_COMPAT_PENDING`、`TS_LEGACY_DELETE` 三类边界已经完成最终冻结，可作为后续发布与退役口径。

现在可以统一表述为：

> **Rust 已成为 mnote 的主业务执行平面；仍保留的 TS 代码只承担 transport、外部服务编排、客户端桥与冻结兼容壳责任。**