mnote/design/04-tree-domain/done/4-3-tree-first-graph-kernel-phase4-task-breakdown-v1.md

4-3 [done] Tree-First Graph Kernel Phase 4 专项任务拆分 v1

更新时间：2026-04-16

关联文档：

• /mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md
• /mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-1-tree-first-graph-kernel-checklist-v2.md
• /mnt/Data1T/mnote/design/04-tree-domain/process/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md

1. 文档目的

这份文档只处理一件事：

把 Kernel Phase 4：Sidebar / 页面树 / 文件树切到 kernel projection 单独拆开，按当前真实代码重写成可执行任务。

这个阶段的目标不是：

• 直接重写整个 Sidebar
• 直接把树 UI 改成 Leptos
• 直接启动树域 Rust Web shell 替换

这个阶段只负责：

把树域的 truth、projection、consumer 协议先统一。

也就是先把树“变对”，再谈“换壳”。

---

2. Phase 4 的准确定位

在 tree-first graph kernel 里：

• 树是主骨架
• 页面树 / 文件树都只是 projection
• Sidebar 是树域承载壳，不是事实源

所以 Phase 4 的本质不是普通前端整理，而是：

让树域 consumer 不再自己拼树，而是统一消费稳定的 kernel projection。

如果这一步不先完成，后面的 Rust Web tree shell 重构就会在协议未冻结前重复返工。

---

3. 当前真实完成情况

基于当前 git，Phase 4 已经有一些关键前置。

3.1 已有 projection 起点

• sidebar.dataset.list 已能产出：
  • kernel_sidebar_projection
  • kernelSidebarTree
• 对应文件：
  • sidebar-data.ts
  • kernel-sidebar.ts

3.2 Sidebar 主树已切到统一 tree consumer

• 主 Sidebar 已以 sidebarData.kernelSidebarTree 作为主树来源
• PrivateTree 已改为直接消费 page_tree projection 可见行
• 对应文件：
  • sidebar.tsx
  • private-tree.tsx

3.3 文件树已收口为统一 projection consumer

• 文件树当前不再直接走嵌套 SidebarTreeNode[] 递归拼树
• 它已经建立在：
  • page_tree projection rows
  • assetsByDoc
  • buildVisibleRows(...) 之上
• 对应文件：
  • rows.ts
  • types.ts
  • file-tree.tsx

3.4 picker 已退出旧拼树主路径

• move-embed picker 空查询态已不再读取 documents[] -> buildDocumentTree(...)
• 它现在直接消费 kernelSidebarTree -> page_tree projection -> picker rows
• 对应文件：
  • move-embed-picker-dialog.tsx
  • tree-projection.ts

---

4. 本轮完成后的保留边界

4.1 旧拼树 helper 已退出主路径，但仍保留兼容边界

• buildDocumentTree(...) 仍保留在兼容 helper 与旧单测里
• 但运行时主路径已不再由它构造 Sidebar / 页面树 / 文件树 / picker

4.2 文件树仍不是 Rust 直接输出的完整 file_tree projection

• 当前文件树已经消费统一 page_tree projection
• 但 asset-folder / asset / index 仍由前端 adapter 基于现有数据集补齐

4.3 Sidebar 壳仍然过重

当前 Sidebar 仍是超大客户端组件。

这不是 Phase 4 的阻塞项，但它解释了为什么下一个任务必须单列为独立 Rust Web tree shell 重构。

---

5. Phase 4 的重新定义

建议把 Phase 4 重新定义成下面这个最小目标：

统一树域 projection protocol，让 Sidebar 主树、页面树、文件树、move/embed picker 都只消费同一套 kernel projection family，并让旧拼树 helper 退出主路径。

这版定义刻意不包含：

• 树域独立 Rust Web shell
• Leptos/Dioxus UI 重写
• Sidebar 整体壳替换

这些是 Phase 4 完成后的下一层任务。

---

6. Phase 4 拆分原则

原则 1

先冻结协议，再收 consumer。

原则 2

先收掉旧 helper 的主路径依赖，再谈树域 UI 重构。

原则 3

文件树不是第二套树，而是更宽对象范围的 projection。

原则 4

每一条树域 consumer 都必须能明确回答：

• 它消费的 projection 是什么
• 它本地状态只剩什么
• 它是否还在自己定义结构真相

---

7. Phase 4 任务拆分

建议把 Phase 4 拆成 6 个子任务。

---

8. P4-1：冻结树域 projection protocol

状态：DONE

目标

先把 Sidebar / 页面树 / 文件树要共同使用的 tree protocol 冻结下来。

要做的事

• 明确最小 tree item / tree row 字段
• 明确 sidebar_tree、page_tree、file_tree 的共用字段与差异字段
• 明确：
  • node_id
  • parent_node_id
  • node_type
  • projection_kind
  • depth
  • position
  • capabilities
  • resource_meta
• 明确哪些字段属于 projection
• 明确哪些字段只能留在 UI 本地状态

交付物

• 树域 projection protocol 文档与类型：
  • tree-projection.ts
• 当前前端类型定义对齐方案

完成判定

• 后续所有树域 consumer 都有统一协议可依赖

---

9. P4-2：统一 Sidebar 主树与页面树 consumer

状态：DONE

目标

让主 Sidebar、页面树相关视图都明确只消费 kernelSidebarTree / projection protocol。

要做的事

• 盘点 Sidebar 主树的所有树读取入口
• 清理仍然从 documents[] 直接拼主树的路径
• 把排序、层级、childCount、expand hint 统一收口到 projection
• 让主树 consumer 只保留：
  • expanded
  • selected
  • hover
  • DnD 中间态

交付物

• Sidebar 主树消费边界收口
• PrivateTree / 顶部树列表统一改读 page_tree projection

完成判定

• 主 Sidebar 不再自己定义页面树结构

---

10. P4-3：把文件树收口为统一 projection consumer

状态：DONE

目标

让文件树从“前端继续拼装的树行系统”收口为统一 tree protocol 的 consumer。

要做的事

• 明确文件树和页面树的关系：
  • 文件树 = 页面树骨架 + 更宽对象投影
• 把 asset-folder / asset / index 的协议层次化
• 收紧 buildVisibleRows(...) 的职责
  • 它只负责 projection -> visible rows
  • 不再负责定义结构真相
• 明确哪些对象后续应由 Rust projection 直接输出：
  • mindmap
  • table
  • asset
  • book
  • pdf

交付物

• 文件树 row model 收口方案
• 文件树 projection consumer 边界

完成判定

• 文件树不再被视为独立第二套树系统

---

11. P4-4：统一 move / embed picker 等兼容树域

状态：DONE

目标

把兼容树域 consumer 也切到 projection，结束双轨树模型。

要做的事

• 改成直接消费 projection tree / flat rows
• 搜索态和空查询态统一到同一目标对象口径
• 明确 picker 只消费 page tree，不再自带另一套树构造逻辑

交付物

• picker 树域消费统一

完成判定

• buildDocumentTree(...) 退出 picker 主路径

---

12. P4-5：收敛旧 helper 与兼容逻辑

状态：DONE

目标

让旧树 helper 不再占据主路径，只保留必要过渡边界。

要做的事

• 盘点 buildDocumentTree(...) 所有 consumer
• 区分：
  • 主路径必须替换
  • 过渡路径可暂留
• 收敛 lib/documents.ts 在树域中的责任
• 给保留的兼容 helper 标明过渡边界

交付物

• 树域旧 helper 清单
• 主路径替换完成

完成判定

• 树域主路径不再依赖旧对象数组拼树

---

13. P4-6：Phase 4 验收矩阵与下一阶段交接

状态：DONE

目标

避免 Phase 4 再被提前写成“树域已重构完成”。

要做的事

• 建立 Phase 4 验收矩阵：
  • Sidebar 主树 consumer
  • 页面树 consumer
  • 文件树 consumer
  • picker consumer
  • 旧 helper 退出主路径
  • tree protocol 冻结
• 回写 checklist
• 明确 Phase 4 完成后才能进入：
  • sidebar-pagetree-filetree-rust-web-rebuild-v1.md

交付物

• Phase 4 验收矩阵
• 下一阶段交接说明

完成判定

• 能明确回答“为什么现在可以做树域 Rust Web shell 重构”

验收矩阵

验收项	当前状态	说明
Sidebar 主树 consumer	DONE	主 Sidebar 与 PrivateTree 已统一消费 kernelSidebarTree -> page_tree projection
页面树 consumer	DONE	顶部树列表、页面树扁平化视图不再各自 flatten 嵌套树
文件树 consumer	DONE	文件树只消费 page_tree projection + asset 映射，buildVisibleRows(...) 只做 visible rows
picker consumer	DONE	move-embed picker 空查询态已改读 projection family
旧 helper 退出主路径	DONE	运行时树域主路径不再调用 buildDocumentTree(...)
tree protocol 冻结	DONE	rowId/nodeId/parentNodeId/projectionKind/depth/position/capabilities/resourceMeta 已固定

下一阶段交接

• 本阶段完成后，下一步唯一合理的大任务是：
  • sidebar-pagetree-filetree-rust-web-rebuild-v1.md
• 原因不是“树域 UI 已重写完成”，而是：
  • 协议已经冻结
  • consumer 已经统一
  • 旧拼树 helper 已退出主路径
  • 现在可以稳定做一次“换壳”，而不是边改协议边重写 UI

---

14. 建议执行顺序

建议顺序如下：

1. P4-1 冻结协议
2. P4-2 收主 Sidebar / 页面树 consumer
3. P4-3 收文件树 consumer
4. P4-4 收 picker / 兼容树域
5. P4-5 收旧 helper
6. P4-6 做验收矩阵和下一阶段交接

原因：

• 如果不先冻结协议，后面的 consumer 收口会一边做一边改字段
• 如果不先收主树和文件树，picker 再怎么改也只是边角修补
• 如果不收掉旧 helper，后面的 Rust Web tree shell 会继续背着双轨数据模型前进

---

15. 暂不纳入 Phase 4 的内容

下面这些先不要塞进 Phase 4：

• 用 Leptos / Dioxus 重写树域 UI
• 独立 Rust Web tree shell
• Sidebar 全量业务壳替换
• 搜索主面板迁移
• AI 主面板迁移
• Mindmap 主画布迁移

这些都属于 Phase 4 之后的阶段。

---

16. Phase 4 完成的最终标准

只有同时满足下面几条，才建议把 Phase 4 标成完成：

• Sidebar 主树、页面树、文件树、picker 都直接消费 kernel projection family
• buildDocumentTree(...) 不再处于树域主路径
• 文件树被正式定义为更宽对象投影，而不是第二套树
• tree protocol 已冻结
• React/Next 树域只保留渲染与局部交互状态，不再定义树结构真相

当前已经满足上述标准，因此 Phase 4 可以标记为完成；但这不意味着树域 Rust Web shell 已经完成。

---

17. 最终结论

Phase 4 当前最准确的职责是：

先把树域 consumer、协议、旧 helper 边界全部统一，确保树域真正只剩一个 truth 和一套 projection family。

现在这一步已经完成，所以下一步的：

• Sidebar / 页面树 / 文件树 Rust Web tree shell 重构

才会变成一次稳定的“换壳”，而不是一次边重写协议边重写 UI 的高风险返工。