lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
afb2a5b8a0ab4234034ff1f592e4e881cb2e072c
mnote/design/old/08-legacy-rust-kernel/process/rust-kernel-missing-targets.md
T

15 KiB
Raw Blame History

[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 替换”。

Reference in New Issue View Git Blame Copy Permalink