mnote/design/04-tree-domain/done/4-20-vscode-explorer-file-tree-alignment-v1.md

# 4-20 [process] VSCode Explorer 文件树对标设计 v1

> 更新时间：2026-05-06
>
> 关联：
> - `/mnt/Data1T/mnote/tmp/image copy 47.png`
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-2-sidebar-pagetree-filetree-product-interaction-contract-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-4-tree-projection-protocol-contract-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-7-tree-shell-ui-state-boundary-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-14-task-005-file-tree-final-renderer-capability-checklist-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`
> - `/mnt/Data1T/mnote/design/90-reference/90-1-filetree.md`

## 1. 目的

这份文档只处理 `filesystem / Explorer` 文件树下一阶段怎么对标 VSCode Explorer。

它不重新定义树域协议。已有结论继续成立：

- `tree-first graph kernel` 是长期对象真相层。
- `Convex` 继续作为本地自托管存储、实时、文件协作底座。
- `mnote-web` 是 Rust Web 主执行面，负责 projection、command、transport 与 realtime stream。
- 前端和 tree shell 只消费稳定 projection，并持有本地交互态。

本设计补的是此前文档没有写细的 Explorer 级显示和操作合同：行模型、选择/焦点、打开、右键、键盘、拖放、剪贴板、新建、重命名、删除、上传、资源移动和验收清单。

## 2. 当前截图判断

`/mnt/Data1T/mnote/tmp/image copy 47.png` 显示当前文件树已经有 Explorer 入口，但仍不像 VSCode Explorer：

- `我的页面` 下直接混排页面节点和 `index.md`，但没有清晰的 workspace root / resource root 语义。
- 页面行使用小菱形 / 折叠箭头，文件行使用蓝色文档图标，信息密度接近，但行列网格不稳定。
- 当前选中态落在 `index.md` 文件行，和右侧文档页 `新页面` 的 active / focus / selection 关系不够清楚。
- `Explorer` 标题像 tab 文案，不像 VSCode Explorer 的 section header + toolbar。
- hover 操作只看到 `+`，缺少新建文件、新建文件夹、刷新、全部折叠、更多等容器级动作。
- 长列表中大量重复 `新页面/index.md`，缺少资源装饰、路径 disambiguation、命名冲突处理和 reveal 规则。

结论：当前不是“样式再修一点”的问题，而是 Explorer 行为合同还没有写到足够细。

## 3. 唯一真源

### 3.1 结构显示真源

文件树显示的唯一真源固定为：

`kernel.project_view(file_tree)` 产出的 `KernelProjectionResult`。

当前代码证据：

- 首屏 query 会从 Convex `sidebar.datasetList` 取数据，再通过 `resolveKernelFileTreeProjection` 调 Rust `kernel.project_view(file_tree)` 附加 `kernel_file_tree_projection`。
- 实时链路 `/api/mnote-web/stream` snapshot 也会附加同一份 file tree projection。
- Rust 侧生成点是 `bridge-runtime` 的 `build_file_tree_projection_result`。
- projection item 的核心字段已经在 `core-protocol/src/kernel.rs` 与前端 `tree-protocol.ts` 固定。

因此，Explorer 不能在 UI 层重新推导层级、排序、资源类型、child count、capabilities 或合法性。UI 只能把 projection item materialize 成 row。

### 3.2 持久化操作真源

持久化动作的唯一正式命令面固定为：

- 页面：`tree.node.*`、`tree.subtree.*`
- 资源：`tree.resource.*`
- 文件树预检：`tree.filetree.*.preflight`

当前已经成立：

- 页面新建、重命名、移动、归档、恢复、永久删除、嵌入、复制子树已经接到 `tree.*`。
- 文件树 `drop/delete/paste/upload-target` 已有 Rust preflight。
- 资源 `copy/move/upload` 已有 `tree.resource.copy/move/upload`。

当前仍未完成：

- 资源 `rename/delete/restore` 仍经过 legacy `/api/media/batch` 直接 patch / restore。
- `cut` 还没有成为剪贴板动作。
- 资源“移动到...”仍有 `prompt("输入目标页面 ID")` 的临时 UX。

### 3.3 本地交互态

这些状态只能属于 tree shell / runtime 本地态，不得写进 projection：

- `expanded`
- `selected`
- `focused`
- `hovered`
- `editingName`
- `clipboard`
- `dragging`
- `dropTarget`
- `contextMenuOpen`
- `keyboardAnchor`
- `revealPending`

`expandedByDefault` 只是 projection 给初始展开的建议，不是展开态真相。

## 4. VSCode Explorer 对标边界

### 4.1 必须对齐

文件树必须对齐 VSCode Explorer 的资源管理器模型：

- 一行就是一个资源命中目标。
- `twistie` 只负责展开/折叠，打开资源是另一种动作。
- 图标来自 `rowKind/resourceMeta/iconHint/assetKind`，不是装饰。
- `selection`、`focus`、`hover`、`active` 分离。
- 右键点击已选区内资源时保留选区，右键点击未选资源时切换到该资源。
- 键盘能完整操作可见行。
- 内部拖拽、外部文件拖入、剪贴板和 context menu 都基于同一 selection/focus 状态。
- 所有危险或跨资源类型动作先走 preflight plan，再落正式 command。

### 4.2 不能照搬

文件树不能照搬 VSCode 的真实文件系统语义：

- mnote 的文件树是页面、`index.md`、附件、mindmap 文件夹、导图子资源、table/book/pdf 等复合资源投影，不是磁盘目录树。
- `page -> index.md -> asset-folder -> asset` 这类多语义链路不能用 VSCode `compact folders` 强行压成一行。
- “在终端打开”“Reveal in Finder/Explorer”“文件比较”等 OS 动作不进入默认合同，除非资源模型已有明确承载。
- VSCode 的单击预览 / 双击固定标签页节奏不能直接照搬。mnote 的打开必须服从当前文档页、Page Aggregate、附件打开链路和权限边界。
- Explorer 是 sidebar 中的创新视图，不是整个产品的唯一主导航。`section` 页面树仍保留 Wolai / Notion 方向。

## 5. 显示合同

### 5.1 Row Grid

每个 file tree row 固定为以下视觉列：

| 列 | 说明 |
| --- | --- |
| indent | 只由 `depth` 决定，步长固定 |
| twistie | 仅 `expandable=true` 时可见并可点击 |
| icon | 由 `iconHint/assetKind/resourceKind` 决定 |
| label | 主名称，单行截断 |
| decoration | 条件性 badge、状态色、资源提示 |
| actions | hover / focus 时出现的轻量动作 |

不得让 label 长度、hover 按钮或选中态改变行高和缩进。

### 5.2 Row Kind

当前稳定行类型继续保留：

- `doc`
- `index`
- `asset-folder`
- `asset`

后续如果需要真实目录或资源组，必须先扩展 Rust projection 的 `rowKind/resourceKind`，不能在 UI 层把某类 asset 临时伪装成目录。

### 5.3 Root

Explorer 顶部应有明确 root：

- 单工作区：显示 workspace root，root 下再进入页面/资源树。
- 多工作区：允许多个 workspace root。
- root 行是否可折叠由 projection capability 决定。

当前截图中 `我的页面 -> Explorer` 的组合不够清晰，后续应改为：

- section header：`EXPLORER`
- root row：当前 workspace 名称
- toolbar：新建页面 / 新建资源 / 刷新 / 全部折叠 / 更多

### 5.4 Icon 与 Decoration

图标语义至少覆盖：

- workspace / folder / page / index
- asset
- image / video / audio
- pdf / book
- table
- mindmap
- unknown

Decoration 只表达轻量状态，例如：

- stale / indexing / uploading
- read-only / shared / public
- conflict / invalid target
- cut clipboard visual

Decoration 不得变成第二行副标题。

### 5.5 Active、Selection、Focus

三者必须分离：

- `active`：右侧主区域正在打开的 document / asset。
- `selection`：Explorer 当前选中集合，支持多选。
- `focus`：键盘焦点所在 row。

截图中 `index.md` 选中与右侧 `新页面` active 的关系不清晰。目标规则：

- 打开文档时，`doc` 与 `index` 可共享 active 文档语义，但只能有一个 focused row。
- 如果 active document 映射到 `index.md`，应显式定义 active 高亮落在 `index` 还是 `doc`。建议：active 落 `index.md`，doc 行只作为目录/页面容器。
- 多选时 active 不覆盖 selection，selection 背景优先。

## 6. 操作合同

### 6.1 打开

P0：

- `Enter` 打开 focused row。
- 双击 row 打开资源。
- 单击只负责 selection/focus，不自动打开重资源。
- `index.md` 打开对应文档页。
- asset 打开对应资源 viewer / editor。

P1：

- 支持“Reveal active resource in Explorer”。
- 页面切换后自动展开祖先链并定位 active row。
- 搜索过滤后保留 active/reveal 的路径上下文。

说明：当前代码已明确与 VSCode 单击打开不同，这是合理差异，但必须写成正式合同，避免后续反复摇摆。

### 6.2 展开 / 折叠

P0：

- 点击 twistie 只展开/折叠，不打开。
- `ArrowRight`：可展开行未展开则展开；已展开或叶子则可进入打开动作，具体由 runtime 定义。
- `ArrowLeft`：已展开则折叠；未展开则焦点移动到父节点。
- `Home/End` 跳到第一/最后可见行。

P1：

- `Collapse All` 容器动作。
- 外部拖拽悬停到可展开目标一段时间后自动展开。

### 6.3 选择与右键

P0：

- 单击：单选并设置 anchor/focus。
- `Ctrl/Cmd + Click`：切换选中。
- `Shift + Click`：从 anchor 到目标做范围选。
- 右键已选区内 row：保留选区并打开菜单。
- 右键未选 row：切换 selection 到该 row，再打开菜单。
- 空白区点击：清空 selection/focus。

P1：

- `Ctrl/Cmd + A` 选中当前 Explorer 可见资源。
- 过滤态下范围选只覆盖可见 row。

### 6.4 键盘

P0 最小按键：

| 按键 | 动作 |
| --- | --- |
| `ArrowUp/ArrowDown` | 上下移动 focus |
| `ArrowLeft/ArrowRight` | 折叠 / 展开 / 父子导航 |
| `Home/End` | 首尾行 |
| `Enter` | 打开 focused row |
| `F2` | 重命名 |
| `Delete/Backspace` | 删除 / 归档 |
| `Ctrl/Cmd+C` | copy |
| `Ctrl/Cmd+X` | cut |
| `Ctrl/Cmd+V` | paste |
| `Esc` | 取消 inline rename / 关闭菜单 / 清理 drag feedback |

当前缺口：已有 copy/paste，但缺 `cut`；键盘能力需要以 runtime contract 覆盖 file tree，而不是散在 `sidebar.tsx`。

### 6.5 新建

P0：

- `New Page`：映射 `tree.node.create`，在目标 doc/root 下创建页面，并进入 inline rename。
- `New File`：只允许创建 mnote 资源模型内真实存在的资源类型；如果当前没有通用文件创建命令，入口应隐藏或置灰。
- `New Folder`：当前没有真实目录语义，不提供默认入口；mindmap asset-folder 不是通用文件夹。

P1：

- 支持上传文件作为 `New File` 的可用替代路径，走 `tree.filetree.upload-target.preflight -> tree.resource.upload`。
- 如果未来引入通用资源目录，先扩展 kernel projection / command，再开启 `New Folder`。

### 6.6 重命名

P0：

- `F2` 和 context menu `Rename` 进入 inline rename，不再使用 `prompt`。
- doc / index 重命名最终落 `tree.node.rename` 或 Page Aggregate title command 的正式命名面。
- asset 重命名必须从 legacy `/api/media/batch` 收口到 `tree.resource.rename` 或等价正式命令。
- `Enter` 提交，`Esc` 取消。
- 空名、重名、非法字符、只读资源必须由 preflight / command 返回可解释错误。

P1：

- 文件型 asset 默认只选中文件名 stem，不误选扩展名。
- rename 期间保留 row 高度和缩进，不触发布局跳动。

### 6.7 删除 / 恢复 / 永久删除

P0：

- doc 删除走 `tree.node.archive`。
- doc 恢复走 `tree.node.restore`。
- doc 永久删除走 `tree.node.purge`，必须是更强确认路径。
- asset 删除 / 恢复必须补正式 `tree.resource.archive/restore` 或等价命令，不能长期停留在 legacy `/api/media/batch`。
- 多选删除先走 `tree.filetree.delete.preflight`，展示将影响的 doc/asset 集合。

P1：

- 支持删除后 undo / toast action，命令结果仍以 kernel event 和 projection resync 为准。

### 6.8 剪贴板

P0：

- `copy`：复制选中 doc subtree / asset resource。
- `cut`：进入 cut clipboard 状态，源 row 降噪显示；paste 成功后清空 cut 状态。
- `paste`：目标由 focused row / context target / active doc 推导，必须先走 `tree.filetree.paste.preflight`。
- 多选 paste 保持原有可见顺序，并过滤父子重复选择。

P1：

- 系统剪贴板只保存安全 payload，不暴露敏感内部 token。
- 跨窗口 paste 需要校验 workspace 和权限。

### 6.9 拖放

P0：

- 内部拖放支持 move/copy，修饰键控制 copy。
- 外部文件拖入支持 upload target preflight。
- 非法目标即时反馈，不发持久化命令。
- doc 拖到自身或后代节点必须拒绝。
- asset-folder / asset 的可投放能力由 `capabilities` 和 preflight 决定。

P1：

- 拖到可展开目标 hover 延迟后自动展开。
- 显示 before / inside / after 三种 drop indicator，而不是只有整行背景。
- 多选拖放过滤已被父节点包含的子节点。

### 6.10 Context Menu

菜单按 `rowKind/resourceKind/selection` 裁剪：

| 目标 | P0 动作 |
| --- | --- |
| root | 新建页面、上传文件、刷新、全部折叠 |
| doc | 打开、新建子页面、重命名、复制、剪切、粘贴、移动到、归档、复制链接 |
| index | 打开、复制、剪切、粘贴、Reveal 页面 |
| asset-folder | 打开、复制、剪切、粘贴、重命名、删除、移动到 |
| asset | 打开、复制、剪切、重命名、删除、下载、移动到 |
| 多选 | 打开禁用、复制、剪切、删除、移动到 |

当前缺口：

- mindmap rename 提示不支持。
- table move/download 提示不支持。
- asset 移动仍靠输入页面 ID。

这些必须进入 P0/P1 差异清单，不得被样式修复掩盖。

## 7. 资源排序与混排规则

P0 固定当前最小规则：

1. workspace root
2. doc row
3. doc 的 `index.md`
4. doc 的 direct assets / asset folders
5. child documents

排序由 Rust projection 的 `position` 与 preorder 决定。UI 只渲染。

需要新增到 projection meta 的候选规则：

- `ordering: "kernel_file_tree_preorder"`
- `folderPolicy: "mnote_composite_resource"`
- `indexPlacement: "first_child"`
- `assetPlacement: "after_index_before_child_documents"`

这样可以避免 UI 通过 hardcode 解释为什么 `index.md` 总是出现在页面下第一行。

## 8. Search / Filter / Reveal

P0：

- Explorer filter 只改变可见 row，不改变 projection truth。
- filter 命中子节点时必须补全祖先链。
- active row 在 filter 后不可见时，保留 active 状态但不强制显示。
- `Reveal in Explorer` 必须展开祖先链、滚动到目标 row、设置 focus，不破坏 selection，除非调用者明确要求 select。

P1：

- 支持 `maxResults` 下的 ancestor completion。
- 支持 indexing visibility，展示 stale / refreshing 状态。

当前 `KernelFileTreeProjection.meta.search.indexingVisibility` 已有雏形，后续应把它用于 UI 状态，而不是在 Explorer 自行发明刷新状态。

## 9. 分阶段任务

### P0：让当前 Explorer 行为不再含糊

- 固定 active / selection / focus 的视觉优先级。
- 补齐 file tree keyboard runtime：`Arrow/Home/End/Enter/F2/Delete/Cut/Copy/Paste/Esc`。
- 补 `cut` clipboard 状态和 cut row decoration。
- 把 doc / index / asset / asset-folder 的 context menu 动作裁剪成合同。
- 移除资源移动的 `prompt("输入目标页面 ID")`，改用 tree picker / move target picker。
- asset rename/delete/restore 制定 `tree.resource.*` 正式命令或等价 bridge 命名，并保留 legacy alias。
- 写 smoke 固化当前截图中重复页面 + `index.md` 场景的 active/selection/reveal 行为。

### P1：让资源管理器达到 VSCode 常用操作预期

- inline rename 全面替代 prompt。
- root toolbar 对齐 Explorer：新建页面、上传文件、刷新、全部折叠、更多。
- 拖放支持 before / inside / after indicator 与 hover auto expand。
- 上传 target preflight 失败时在 drop target 上显示明确反馈。
- 多选 delete / move / copy 的 preflight plan 显示影响集合。
- mindmap/table 的 rename/move/download 能力从“不支持”变为可解释菜单状态或正式实现。

### P2：高级 Explorer 能力

- compact folders 只用于未来真实目录链，不用于页面/附件复合链。
- git-like / sync-like decorations，如果未来有对应数据源再加入。
- 多 workspace root。
- 大树虚拟化和增量加载。
- 跨窗口剪贴板。

## 10. 验收

### 10.1 单元 / 合同测试

必须覆盖：

- projection item 到 row model 的稳定映射。
- active / selection / focus 分离。
- `Ctrl/Cmd` 多选、`Shift` 范围选、右键保留选区。
- 可见 row 变化后的 selection normalize。
- `cut/copy/paste` payload encode/decode 与目标推导。
- drop preflight payload 构造。
- illegal drop：自身、后代、跨 workspace、只读资源。
- inline rename submit/cancel。

### 10.2 Rust 测试

必须覆盖：

- `kernel.project_view(file_tree)` 输出 `doc/index/asset-folder/asset`。
- `resourceMeta`、`capabilities`、`iconHint` 稳定。
- `tree.filetree.*.preflight` 对多选和非法目标返回 plan。
- 新增 `tree.resource.rename/archive/restore` 或等价命令后，覆盖 command event 与 projection resync。

### 10.3 浏览器 smoke

必须覆盖：

- 当前截图同类数据：多个同名 `新页面`，每个页面下有 `index.md`。
- 点击 `index.md` 后右侧打开对应页面，Explorer active/focus/selection 可解释。
- 右键已选区保留多选。
- `F2` inline rename，`Esc` 取消，`Enter` 提交。
- `Ctrl/Cmd+X` 后 cut decoration 出现，paste 成功后消失。
- 外部文件拖入 doc / index / asset-folder 的目标差异。
- 资源移动不再弹 `prompt`。

## 11. 非目标

- 不把文件树改成真实磁盘文件系统。
- 不把 `Explorer` 替代 `section` 页面树作为唯一导航。
- 不在 UI 层重新拼排序、层级、资源类型或权限。
- 不为了像 VSCode 而绕过 Page Aggregate、tree projection 或 `tree.*` 命令。
- 不把 `90-1-filetree.md` 的 Rust 生态调研当作实现模板；它只作为参考资料。

## 12. 完成判定

这份设计进入 done 的条件：

- P0 项全部有代码和 smoke 覆盖。
- file tree 的 active / selection / focus / keyboard / context menu / clipboard / DnD 有稳定 runtime contract。
- 资源 rename/delete/restore 不再只依赖 legacy `/api/media/batch` 主路径。
- 当前截图暴露的 Explorer 行为歧义能通过测试说明和验证。
- 新增能力没有制造第二套树真相。