lix/mnote

Files

T

lix-2026 afb2a5b8a0 对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00

14 KiB

Raw Permalink Blame History

[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、外部服务编排、客户端桥与冻结兼容壳责任。

14 KiB Raw Permalink Blame History Unescape Escape

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

1. 目的

2. 状态定义

2.1 RUST_OWNER

2.2 TS_TRANSPORT_KEEP

2.3 TS_COMPAT_PENDING

2.4 TS_LEGACY_DELETE

3. 当前总盘点

3.1 页面系统

已进入 RUST_OWNER

仍是 TS_COMPAT_PENDING

3.2 块系统

已进入 RUST_OWNER

仍需冻结的兼容 helper

可删的旧逻辑

3.3 查询聚合与观测

已进入 RUST_OWNER

仍是 TS_TRANSPORT_KEEP

当前仍缺

3.4 AI 与工具面

已进入 RUST_OWNER

仍是 TS_TRANSPORT_KEEP

仍是 TS_COMPAT_PENDING

3.5 对象域

Mindmap：已进入 RUST_OWNER

Mindmap：仍是 TS_COMPAT_PENDING

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

OnlyOffice：已进入 TS_TRANSPORT_KEEP

4. Phase 8 Cutover Gate

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

Gate B：对象域只保留 transport 壳

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

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

5. 允许删除与禁止删除

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

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

5.3 必须长期保留的壳

6. 最终宣布口径

14 KiB

Raw Permalink Blame History

2.1 `RUST_OWNER`

2.2 `TS_TRANSPORT_KEEP`

2.3 `TS_COMPAT_PENDING`

2.4 `TS_LEGACY_DELETE`

已进入 `RUST_OWNER`

仍是 `TS_COMPAT_PENDING`

已进入 `RUST_OWNER`

已进入 `RUST_OWNER`

仍是 `TS_TRANSPORT_KEEP`

已进入 `RUST_OWNER`

仍是 `TS_TRANSPORT_KEEP`

仍是 `TS_COMPAT_PENDING`

Mindmap：已进入 `RUST_OWNER`

Mindmap：仍是 `TS_COMPAT_PENDING`

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

OnlyOffice：已进入 `TS_TRANSPORT_KEEP`