mnote/design/05-editor-mainline/reference/5-14-zed-lapce-vscode-reference-adoption-matrix-v1.md

5-14 [reference] Zed / Lapce / VS Code 参考采用矩阵 v1

更新时间：2026-05-19

当前状态：reference。本文是参考实现采用矩阵，不是当前执行 checklist；具体实现任务应拆到对应 domain 的 process/done 文档。

关联背景：

• /mnt/Data1T/mnote/ARCHITECTURE.md（CURRENT_ARCHITECTURE.md 为兼容指针）
• /mnt/Data1T/mnote/design/05-editor-mainline/reference/5-5-page-aggregate-single-truth-alignment-v1.md
• /mnt/Data1T/mnote/design/05-editor-mainline/done/5-6-page-aggregate-alignment-checklist-v1.md
• /mnt/Data1T/mnote/design/old/07-ai/process/7-14-local-first-ai-markdown-editing-convergence-v1.md
• /mnt/Data1T/mnote/design/04-tree-domain/done/4-24-resource-tree-filetree-pagetree-source-contract-checklist-v1.md

本地参考源码：

• VS Code：/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/vscode
• Zed：/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/zed
• Lapce：/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/lapce
• SideX：/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/sidex-main

1. 文档目的

这份文档回答一个工程路线问题：

MNote 当前 Rust 主线应继续从 VS Code 源码里参考什么，又应该从哪些 Rust 编辑器项目里借鉴现成结构，避免把 VS Code TypeScript / Electron 代码大量转译到 Rust。

当前结论是：

Zed 作为主架构参考，Lapce 作为辅助实现参考，SideX 作为 VS Code 行为迁移到 Rust 后端的桥接参考，VS Code 官方源码作为行为规格参考。

这不是说 MNote 要改造成通用 IDE，也不是要复制 Zed / Lapce 的桌面产品形态。MNote 的主线仍然是：

• tree-first graph kernel
• local-first Markdown workspace
• Rust mnote-web Web shell
• Page Aggregate / File Tree / Resource Tree 投影
• Hermes / Reasonix agent 在授权目录内进行文件编辑

Zed、Lapce、SideX、VS Code 只用于补齐“编辑器工作区基础设施”的成熟参考，尤其是文件树、打开态 buffer、dirty/save、搜索、外部文件变更、agent 文件编辑权限这些层。

---

2. 总体判断

2.1 不建议把 VS Code 源码作为转译目标

VS Code 官方源码仍然是 TypeScript / Electron 架构。它对 MNote 有很强的产品行为参考价值，但不适合作为 Rust 代码转译目标。

主要风险：

• VS Code 的 workbench、service、contribution、lifecycle 与 Electron / DOM / Node 绑定很深。
• 大量接口依赖 TypeScript DI、事件模型、extension host 和 workbench contribution 体系，转到 Rust 后会变成重建一套框架。
• 文件服务、保存冲突、watcher、context key 等模块很有价值，但它们的价值在行为合同和边界划分，不在逐行代码。
• MNote 当前不是通用 IDE，而是 local-first Markdown workspace + agent 编辑器，直接转译会把产品边界拉宽。

因此，VS Code 的定位应固定为：

行为规格参考，不作为 Rust 实现蓝本。

2.2 Zed 是当前最接近 MNote 长期主线的 Rust 参考

Zed 的价值不在 UI 壳，而在这条 Rust 原生编辑器链路：

Worktree / Snapshot -> WorktreeStore -> Project / ProjectPath -> BufferStore / MultiBuffer / Editor -> Search / FileFinder -> AgentTool / ToolPermission

这与 MNote 的长期方向高度重合：

• 多 workspace root / local folder。
• 稳定的 {root + relative path} 文件身份。
• 文件树扫描、ignore、watch 增量更新。
• 打开态 buffer、dirty/save、路径到 buffer 的索引。
• 全文搜索、快速打开。
• agent 文件读写、patch、权限与 allowed roots。

Zed 应作为：

workspace / project / buffer / search / agent 文件编辑权限的主参考。

2.3 Lapce 是轻量实现与边界拆分的辅助参考

Lapce 的价值不在“产品完整度超过 Zed”，而在它更轻、更容易抽取工程模式：

UI -> typed RPC -> proxy -> watcher / search / plugin / terminal -> doc / buffer delta / save

这对 MNote 有两类价值：

• typed command / request / response 如何拆到 proxy / backend 执行层。
• 文档 rev / delta / dirty / save 生命周期如何保持简单。

Lapce 应作为：

typed RPC、proxy 边界、doc delta/save、file explorer state machine、配置和 keymap 的辅助参考。

2.4 SideX 不替代 Zed，但应加入参考矩阵

SideX 的 README 明确写的是：

VSCode's workbench, without Electron.

也就是说，SideX 不是 Rust 原生重写 VS Code。它更接近：

保留 VS Code TypeScript workbench / Monaco / service 模型，把 Electron main process、Node fs、node-pty、sqlite、watcher、search 等系统能力替换为 Tauri + Rust command / crate。

因此 SideX 不能替代 Zed 成为 MNote 的主架构参考，原因是：

• 它仍保留 VS Code 的 TypeScript workbench、DI、service、contrib 体系。
• 它的目标是“移植 VS Code”，不是建立 projection-first 的 local-first Markdown workspace。
• 它会把 MNote 拉回通用 IDE / extension host / desktop shell 的复杂度。

但 SideX 很适合作为一类新参考：

VS Code 行为如何落到 Rust 后端的迁移样本。

它比官方 VS Code 更接近 MNote 的地方在于：

• Rust sidex-workspace 已经抽出 file tree、watcher、search、path util、dirty diff、multi-root 等 workspace crate。
• Rust sidex-keymap 已经实现接近 VS Code when clause 的 context key evaluator。
• Rust sidex-settings 已经实现 default / user / workspace 的分层 settings。
• Tauri command 层把 fs、terminal、git、search、storage 等 Node/Electron 能力转换成 Rust command 边界。

所以本矩阵应把 SideX 放在：

“VS Code 行为规格”和“MNote Rust 实现”之间的桥接参考。

2.5 Helix 不作为主参考

Helix 是优秀的 Rust 终端编辑器，适合参考 LSP、Tree-sitter、文本核心和配置理念，但它不是 workbench / Web shell / local-first workspace 主参考。

---

3. 参考源职责划分

3.1 Zed：主架构参考

重点参考：

• crates/worktree/src/worktree.rs
• crates/project/src/worktree_store.rs
• crates/project/src/project.rs
• crates/project/src/buffer_store.rs
• crates/project/src/project_search.rs
• crates/file_finder/src/file_finder.rs
• crates/agent/src/tools/edit_file_tool.rs
• crates/agent/src/tools/read_file_tool.rs
• crates/agent/src/tools/write_file_tool.rs
• crates/agent/src/tools/edit_session.rs
• crates/agent/src/tool_permissions.rs

不重点采用：

• GPUI / Entity / App / Window 渲染壳。
• pane / dock / desktop lifecycle。
• collab / remote / diagnostics 的完整产品线。
• 与 MNote local-first Markdown 主线无关的通用 IDE 复杂度。

3.2 Lapce：辅助实现参考

重点参考：

• lapce-app/src/doc.rs
• lapce-rpc/src/proxy.rs
• lapce-proxy/src/dispatch.rs
• lapce-proxy/src/watcher.rs
• lapce-app/src/file_explorer/data.rs
• lapce-app/src/global_search.rs
• lapce-app/src/command.rs
• lapce-app/src/main_split.rs
• lapce-core/src/syntax/mod.rs
• lapce-core/src/language.rs
• lapce-core/src/encoding.rs
• lapce-app/src/config.rs
• defaults/settings.toml
• lapce-app/src/keypress/loader.rs
• defaults/keymaps-common.toml
• lapce-proxy/src/plugin/mod.rs

不重点采用：

• Lapce 自身 UI 框架选择。
• 完整插件生态重建。
• 终端、调试器等 MNote 当前阶段不需要的 IDE 面。

3.3 VS Code：行为规格参考

继续参考：

• src/vs/platform/files
• src/vs/platform/commands
• src/vs/platform/contextkey
• src/vs/workbench/contrib/files
• src/vs/workbench/services/filesConfiguration
• src/vs/base/browser/ui/list
• src/vs/base/browser/ui/tree

重点看行为：

• file service 的能力边界。
• save / save as / revert / conflict 的用户体验。
• workspace watcher 与外部文件变更处理。
• context key / command enablement。
• file import / export / open editors。
• tree/list 的选择、焦点、键盘导航和 DnD 行为。

不采用：

• TypeScript service 体系逐行转译。
• Electron workbench lifecycle。
• VS Code extension host 作为 MNote 当前插件模型。

3.4 SideX：VS Code 行为到 Rust 后端的桥接参考

重点参考：

• ARCHITECTURE.md
• src-tauri/src/lib.rs
• src-tauri/src/commands/fs.rs
• src-tauri/src/commands/validation.rs
• crates/sidex-workspace/src/lib.rs
• crates/sidex-workspace/src/file_tree.rs
• crates/sidex-workspace/src/watcher.rs
• crates/sidex-workspace/src/search.rs
• crates/sidex-workspace/src/path_util.rs
• crates/sidex-keymap/src/context.rs
• crates/sidex-keymap/src/resolver.rs
• crates/sidex-settings/src/settings.rs
• crates/sidex-settings/src/jsonc.rs
• crates/sidex-terminal/src/pty.rs
• crates/sidex-terminal/src/manager.rs

重点看边界：

• Electron / Node 能力如何映射为 Rust command。
• 文件系统 command 如何先做 path validation，再进入 workspace crate。
• Rust watcher / search / file tree 如何对外输出可序列化事件和结果。
• VS Code when clause / context key 如何在 Rust 侧建模。
• default / user / workspace settings 如何分层合并。
• PTY / terminal manager 如何从 Node native 模块迁移到 Rust。

不采用：

• VS Code TypeScript workbench 的整体移植路线。
• Tauri desktop shell 作为 MNote 当前 Web 主壳。
• extension host / debugger / terminal / git 的完整 IDE 产品面。
• SideX 当前对绝对路径 command 的简单安全模型；MNote 必须继续使用 allowed roots、workspace root、symlink escape 和文件版本仲裁。

---

4. 采用矩阵

主题	主参考	MNote 当前缺口	采用方式	优先级
ProjectPath / 文件身份	Zed ProjectPath	local folder、page .md、resource asset 需要稳定 {workspace/root + rel path} 身份	借鉴模式，映射到 KernelObjectIdentity / File Tree row	P0
Worktree / root 管理	Zed worktree + worktree_store，SideX sidex-workspace	local-first workspace 需要扫描、ignore、watch、root id、路径归一	Zed 做主模型，SideX 补充 Rust workspace crate 拆分参考	P0
BufferStore / 打开态文件	Zed buffer_store，Lapce doc.rs	tiptap、AI、外部编辑器会同时触碰同一 .md，需要统一 dirty/save/version	Zed 做架构，Lapce 做简化实现参考	P0
dirty / save / external change	VS Code file save 行为，Zed buffer，Lapce doc，SideX dirty diff / watcher	/api/documents/save 兼容面仍未完全退出，文件版本冲突模型待收口	VS Code 校准行为，Zed/Lapce 定模型，SideX 看 Rust watcher / dirty diff 落点	P0
agent 文件编辑权限	Zed edit_file_tool / tool_permissions	Hermes / Reasonix 需要 allowed roots、symlink escape、防脏 buffer 覆盖	直接作为权限模型主参考	P0
workspace search	Zed project_search，Lapce global_search，SideX sidex-workspace/search.rs	MNote 需要本地全文搜索与 Page Aggregate / File Tree 对齐	Zed 做主搜索模型，Lapce 做结果投影，SideX 补充 Rust 并行搜索实现参考	P1
file finder / quick open	Zed file_finder	工作区文件快速打开与 object tab host 尚未成体系	借鉴候选生成与排序，不复制 UI	P1
file explorer 状态机	Lapce file_explorer/data.rs，SideX file_tree.rs，VS Code tree 行为	File Tree / Page Tree / Resource Tree 需要选择、展开、刷新、右键命令一致性	Lapce 状态机 + SideX Rust file tree 能力 + VS Code 行为规格	P1
command / context key	VS Code commands / contextkey，SideX sidex-keymap/context.rs，Lapce command.rs	tree/page/object tab 命令 enablement 仍容易散落到 UI	VS Code 给语义，SideX 给 Rust when-clause evaluator 参考	P1
typed RPC / backend proxy	Lapce lapce-rpc + lapce-proxy，SideX Tauri commands	Rust Web、worker、local FS executor、agent runtime 需要 typed request 边界	Lapce 参考协议拆分，SideX 参考 Node/Electron 能力迁移到 Rust command	P2
config / settings	SideX sidex-settings，Lapce config.rs + settings.toml，VS Code settings 行为	workspace / user / page options / AI policy 需要层级合并规则	SideX 分层 settings 更接近 Rust 落地，Lapce/VS Code 校准行为	P2
keymap	SideX sidex-keymap，Lapce keypress loader，VS Code keybinding 行为	editor shell、file tree、command palette 后续需要统一快捷键	SideX 参考 Rust context/when 解析，Lapce 参考 loader，VS Code 校准行为	P2
terminal / PTY 边界	SideX sidex-terminal，VS Code terminal 行为	MNote 当前不是 IDE 终端优先，但 agent/local workspace 后续可能需要受控命令执行面	只参考 Rust PTY manager 和安全边界，不进入当前主线	P3
MultiBuffer / excerpts	Zed MultiBuffer	AI review、搜索结果、跨文件上下文需要多片段视图	Phase C 之后采用，当前不前置	P3
review diff / streaming apply	Zed agent edit session，VS Code diff 行为	AI suggest/review 仍设计冻结	只保留为后续参考，不当前实施	P3
插件运行时	Lapce plugin，SideX WASM extension，VS Code extension host	MNote 当前插件是 simplemindmap / office / local tool，不需要通用扩展平台	暂不采用，只保留观察	P3

---

5. P0 实施建议

P0 不应从 UI 开始，而应先把文件身份、打开态 buffer 和 agent 文件权限三个底座定住。

5.1 固定 MNote 的 WorkspacePath

目标：

用一个 Rust 侧稳定结构表达“哪个 workspace root 下的哪个相对路径”。

参考：

• Zed ProjectPath
• Zed WorktreeStore

建议语义：

• workspace_id
• root_id
• source_kind
• relative_path
• object_identity
• resource_kind

约束：

• 不允许 UI 只拿绝对路径当对象身份。
• 不允许 Page Tree / File Tree / AI 工具各自生成不同 path key。
• symlink、..、case sensitivity、ignore 规则必须由 Rust workspace 层处理。

5.2 建立 BufferStore / DocumentBuffer 最小模型

目标：

让 tiptap autosave、AI 文件写入、外部编辑器修改都围绕同一份文件版本和 dirty 状态仲裁。

参考：

• Zed buffer_store.rs
• Lapce doc.rs
• VS Code save conflict 行为

建议最小字段：

• workspace_path
• file_version
• base_content_hash
• current_content_hash
• dirty_state
• last_loaded_at
• last_saved_at
• external_change_state

当前必须避免：

• 继续把 /api/documents/save 当长期正文写入主入口。
• tiptap 和 AI 分别维护互不知情的 revision。
• 外部文件变更直接覆盖前台 dirty buffer。

5.3 收口 agent 文件编辑权限

目标：

MNote 只负责计算授权范围和同步投影，Hermes / Reasonix 在 allowed roots 内用自身 patch/diff 能力编辑文件。

参考：

• Zed edit_file_tool.rs
• Zed edit_session.rs
• Zed tool_permissions.rs

必须具备：

• allowed roots。
• 当前文件引用。
• selection / range。
• symlink escape 防护。
• dirty buffer 写入前检查。
• 写后 watcher / projection refresh。

这条线与当前 7-14 online/local AI Markdown editing convergence 一致：普通 local-first Markdown 编辑优先走 agent 原生文件编辑能力，mnote.doc.markdown_edit 只作为 cloud / remote agent / compat fallback。

---

6. P1 / P2 / P3 实施建议

6.1 P1：搜索、文件树、命令上下文

P1 解决的是 workspace 产品体验闭环：

• 本地全文搜索。
• 快速打开。
• File Tree / Resource Tree / Page Tree 展开、选择、刷新、右键命令。
• command enablement / context key。

参考组合：

• Zed project_search + file_finder
• Lapce global_search + file_explorer/data.rs
• VS Code tree/list/contextkey 行为

验收口径：

• 搜索结果能回到稳定 WorkspacePath / ObjectIdentity。
• 文件树操作只发 command，不直接改真实对象。
• 右键菜单和快捷键基于统一 command context，不在 UI 分支里临时判断。

6.2 P2：typed RPC、配置、keymap

P2 解决的是边界清晰和长期可维护：

• UI 到 Rust executor 的 typed request / response。
• user / workspace / page / runtime policy 的配置合并。
• 编辑器、树、command palette 的 keymap 加载和冲突处理。

参考组合：

• Lapce lapce-rpc/src/proxy.rs
• Lapce lapce-proxy/src/dispatch.rs
• Lapce config.rs
• Lapce keypress/loader.rs
• VS Code settings / keybinding 行为

验收口径：

• route / compat / worker 不再各自定义一套命令 payload。
• 配置合并顺序可解释、可测试。
• 快捷键归属到 command，不直接绑定到某个 DOM 事件分支。

6.3 P3：MultiBuffer、review diff、插件运行时

P3 只作为后续能力，不进入当前最前排。

可参考：

• Zed MultiBuffer：搜索结果、AI 上下文、多文件 excerpt。
• Zed agent edit session：review / apply / reject。
• VS Code diff：冲突、review、保存体验。
• Lapce plugin：轻量插件隔离。

当前边界：

• 不实施流式 apply + suggest/review。
• 不重建 VS Code extension host。
• 不把 MNote 拉成通用 IDE。

6.4 SideX 专项采用边界

SideX 可以补强 P1 / P2，但不改变 P0 主线。

可以参考的部分：

• sidex-workspace 的 crate 拆分：file_tree / watcher / search / path_util / dirty_diff / multi_root。
• src-tauri/src/commands/fs.rs 的 command facade：前端请求先进入窄 command，再进入 Rust workspace 能力。
• src-tauri/src/commands/validation.rs 的输入校验意识，但 MNote 需要更强的 workspace root / allowed roots / symlink escape 校验。
• sidex-keymap/context.rs 的 when clause AST 和 evaluator，可作为 MNote command context 的 Rust 参考。
• sidex-settings/settings.rs 的 default / user / workspace settings 分层，可作为 MNote user / workspace / page / AI policy 合并规则的早期参考。
• sidex-workspace/search.rs 的 ignore-aware、rayon 并行全文搜索，可作为本地 Markdown workspace 搜索实现参考。

不应采用的部分：

• 不采用“把 VS Code TypeScript workbench 原样移植到 Tauri”的产品路线。
• 不把 MNote 3000 Rust Web 主壳替换成 Tauri desktop shell。
• 不把 extension host / debugger / terminal / git 做成当前默认产品能力。
• 不直接沿用 SideX 的绝对路径 command 安全模型；MNote 必须以 workspace identity、allowed roots、file version 和 agent permission 为准。

对 MNote 的实际帮助是：

当我们从 VS Code 学到一个行为时，可以先看 SideX 是否已有 Rust crate / Tauri command 级别的落地方式；如果有，就用 SideX 校准“这个行为如何从 Node/Electron 能力迁移到 Rust 后端”，再按 MNote 的 kernel / projection / command contract 重写。

---

7. VS Code 仍应继续看的源码

虽然不建议转译 VS Code，但下面这些仍值得继续深读，因为它们定义了成熟编辑器的行为边界。

7.1 文件服务与保存冲突

重点：

• src/vs/platform/files
• src/vs/workbench/services/filesConfiguration
• textFileSaveErrorHandler

关注问题：

• 文件不存在、权限失败、外部修改、编码变化、只读文件如何呈现。
• dirty buffer 与磁盘版本冲突时如何让用户选择。
• save / save as / revert 的命令边界。

7.2 Watcher 与外部变更

重点：

• workspaceWatcher
• file service event。

关注问题：

• 外部编辑器修改 .md 后如何刷新投影。
• 当前 buffer dirty 时如何避免静默覆盖。
• rename / delete / move 对打开 tab 和 file tree 的影响。

7.3 Context Key 与 Command Enablement

重点：

• src/vs/platform/contextkey
• src/vs/platform/commands

关注问题：

• 命令是否可用不应散落在 UI 条件判断里。
• File Tree / Page Tree / Object Tab / Editor selection 应贡献统一 context。
• 右键菜单、快捷键、command palette 应消费同一套 command context。

7.4 Tree / List 行为

重点：

• src/vs/base/browser/ui/list
• src/vs/base/browser/ui/tree
• src/vs/workbench/contrib/files

关注问题：

• 展开、收起、选择、焦点、键盘导航。
• DnD 和 rename 的边界。
• open editors / file explorer 如何处理打开态与磁盘态。

---

8. 风险与边界

8.1 许可与代码来源边界

Zed、Lapce、VS Code 都只能作为参考来源。后续实现应遵循：

• 不直接复制大段源码。
• 不把第三方项目的 UI 壳、生命周期和产品概念搬进 MNote。
• 引用具体设计时在设计稿或实现注释中标明“参考模式”，避免伪装成原创推导。

8.2 产品边界风险

MNote 不应因为参考 Zed / Lapce / VS Code 而变成通用 IDE。

必须保持：

• 页面正文真相仍是 local-first .md。
• Rust kernel 持有树、资源、投影、命令语义。
• Page Aggregate 是页面主投影。
• File Tree 是 local workspace 的组织投影。
• Hermes / Reasonix agent 文件编辑必须受 allowed roots 和文件版本模型约束。

8.3 技术路线风险

最大风险不是“参考不够”，而是参考源混用后边界变模糊。

固定规则：

• Zed 负责主架构参考。
• Lapce 负责轻量实现参考。
• SideX 负责 VS Code 行为到 Rust 后端的迁移参考。
• VS Code 负责行为规格参考。
• MNote 自己的 Rust kernel / projection / command contract 负责最终真相。

---

9. 当前建议结论

后续推进顺序建议固定为：

1. P0：WorkspacePath / ProjectPath、WorktreeStore、BufferStore、agent file edit permission。
2. P1：workspace search、file finder、file explorer state machine、command context。
3. P2：typed RPC / proxy、SideX-style Rust command facade、config、keymap。
4. P3：terminal / PTY 边界、MultiBuffer excerpt、review diff、插件运行时。

一句话结论：

不要把 VS Code TypeScript 源码转译成 Rust；应以 Zed 的 Rust workspace / buffer / agent 架构为主参考，以 Lapce 的 typed RPC / proxy / doc delta 为辅助参考，以 SideX 校准 VS Code 行为迁移到 Rust 后端的落地方式，再用官方 VS Code 校准成熟编辑器行为。