feat: 收口 tree-first graph 主链与前端测试修复

AGENTS.md

@@ -1,48 +1,59 @@
 # 仓库协作指南（AGENTS）
 
-## 当前主线事实
+## 当前主线
 
-- 当前仓库已经做过精简，旧设计稿已移动到 `/mnt/Data1T/mnote/recycle/design/`。
-- 当前主前端在 `/mnt/Data1T/mnote/wolai-frontend/`，这是默认优先修改的位置。
-- 当前辅助后端在 `/mnt/Data1T/mnote/wolai-backend/`。
-- 当前 Convex 自托管配置在 `/mnt/Data1T/mnote/infra/convex/`。
-- 根目录历史 `/mnt/Data1T/mnote/src/` 已只保留 `/mnt/Data1T/mnote/src/components/onlyoffice/`，这里仍然属于运行相关资源，不要误删。
-- `/mnt/Data1T/mnote/ARCHITECTURE.md` 是当前仓库结构与嵌入关系的最新说明，涉及 BlockNote、Mindmap、OnlyOffice 时优先参考它。
+- 当前长期方向以 `tree-first graph kernel` 为准，不以 `BlockNote-first` 或 `Mindmap-first` 为准。
+- `Convex` 继续保留为本地自托管的存储、实时、文件协作底座，不因为推进 Rust 主线而先拆掉。
+- `Rust kernel` 持有树、子树、边、projection、query、command 的语义主导权；新增树规则不要继续散落到前端、Next route 或临时 compat 层。
+- `mnote-web` 是当前 Rust Web 承载层，负责 transport、projection 分发、兼容切流；`compat` 与 `fixture` 只用于过渡和测试，不应继续承载长期业务语义。
+- 前端主路径应消费稳定 projection，不应在 UI 层重新拼出第二份对象真相。
 
-## 目录约定
+## 组件定位
+
+- `BlockNote` 是当前文档页编辑器内核，但不是系统事实源。
+- `Mindmap` 是 `tree-first graph` 的一种视图和编辑挂件，不是对象真相层。
+- `OnlyOffice` 是独立页面型编辑器，不直接嵌入 `BlockNote` 画布；正文中通常通过附件块跳转进入。
+
+## 目录优先级
 
 - `/mnt/Data1T/mnote/wolai-frontend/src/`
-  当前前端主源码目录。
+  页面、编辑器、Sidebar、树视图、阅读态、交互壳默认先看这里。
 - `/mnt/Data1T/mnote/wolai-frontend/convex/`
-  当前 Convex functions 目录。
+  仍在使用的 Convex functions 与数据侧逻辑先看这里。
+- `/mnt/Data1T/mnote/rust/crates/core-protocol/`
+  Kernel 类型、projection 协议、树/图核心术语先看这里。
+- `/mnt/Data1T/mnote/rust/crates/bridge-runtime/`
+  Kernel query / command / subtree / graph traversal 入口先看这里。
+- `/mnt/Data1T/mnote/rust/crates/mnote-web/`
+  Rust Web route、transport、compat、tree shell、projection 分发先看这里。
 - `/mnt/Data1T/mnote/wolai-backend/app/`
-  当前后端主源码目录。
+  辅助后端、异步处理、接口配合先看这里。
+- `/mnt/Data1T/mnote/infra/convex/`
+  Convex 自托管部署与本地基础设施先看这里。
 - `/mnt/Data1T/mnote/src/components/onlyoffice/`
-  当前保留的 OnlyOffice 静态资源、插件与相关数据目录。
+  只在处理 OnlyOffice 静态资源、插件或兼容问题时进入。
 - `/mnt/Data1T/mnote/recycle/`
-  已废弃或已下线内容的回收区，默认不要基于这里继续扩展实现。
+  默认视为历史回收区，不作为当前实现依据，除非任务明确要求。
 
-## 开发优先级
+## 架构约束
 
-1. 涉及页面、编辑器、块系统、思维导图、OnlyOffice 页面时，优先检查 `/mnt/Data1T/mnote/wolai-frontend/src/`。
-2. 涉及数据模型、查询、动作、任务编排时，优先检查 `/mnt/Data1T/mnote/wolai-frontend/convex/`。
-3. 涉及辅助服务、接口配合、异步处理时，检查 `/mnt/Data1T/mnote/wolai-backend/app/`。
-4. 只有在处理 OnlyOffice 静态资源、插件或兼容问题时，才进入根目录 `/mnt/Data1T/mnote/src/components/onlyoffice/`。
-
-## 关键架构认知
-
-- `BlockNote` 是当前文档页主编辑器内核。
-- `Mindmap` 是 BlockNote 的自定义 block，同时支持内嵌和独立全屏页，两者共用同一核心组件。
-- `OnlyOffice` 是独立页面型编辑器，不直接嵌入 BlockNote 编辑画布；正文中通常通过附件块跳转进入。
+- 涉及树、页面结构、文件树、Sidebar、阅读投影、搜索投影、引用边语义时，优先判断是否应落到 Rust kernel，而不是直接改前端拼装逻辑。
+- 前端可以做展示、交互和局部适配，但不要新增第二套树真相、排序真相或 projection 契约。
+- `mnote-web` 的 `compat route` 可以承接过渡流量，但不要把新的长期业务逻辑继续堆进 compat。
+- 需要架构判断时，优先参考：
+  - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+  - `/mnt/Data1T/mnote/design/tree-first-graph-kernel-v1.md`
+  - `/mnt/Data1T/mnote/design/tree-first-graph-kernel-checklist-v2.md`
+  - `/mnt/Data1T/mnote/design/tree-first-graph-convex-rust-long-term-architecture-v1.md`
 
 ## 协作边界
 
 - 仅修改与当前任务直接相关的文件。
 - 不要擅自恢复、覆盖、删除用户已有改动。
-- 看到 `/mnt/Data1T/mnote/recycle/` 中的内容时，默认视为历史资料，不作为当前实现依据，除非任务明确要求。
-- 若任务涉及架构判断，优先以当前代码与 `/mnt/Data1T/mnote/ARCHITECTURE.md` 为准，不要依赖旧文档记忆。
+- 若发现与当前任务无关的脏改动，保持不动；若怀疑会影响当前任务，先确认再处理。
+- 若当前问题只是 UI 表现异常，先确认是否是实验性 tree shell、compat 路径、轮询或 fallback 混入首屏主链，而不是直接怀疑 Convex 本身。
 
-## 常用开发命令
+## 常用命令
 
 - 根目录热启动：`npm run desktop:hot`
 - 前端开发：`cd /mnt/Data1T/mnote/wolai-frontend && pnpm dev`
@@ -50,6 +61,14 @@
 - 后端开发：`cd /mnt/Data1T/mnote/wolai-backend && uvicorn app.main:app --reload --port 8000`
 - Convex 自托管：参考 `/mnt/Data1T/mnote/infra/convex/README.md`
 
+## 前端测试方法
+
+- 看页面当前真实渲染结果、登录态下实际内容、JS 渲染后的 `localhost` 页面时，优先用 `/doko`；它适合读取真实 Chrome 中已经渲染完成的页面。
+- 做交互测试、文件创建/删除/移动、上传、快速登录、侧边栏展开、回归断言时，优先用浏览器自动化测试工具；这类任务不要只靠 `/doko`。
+- 推荐顺序是：先用 `/doko` 快速确认页面是否正常渲染，再用浏览器自动化测试工具验证关键交互链路。
+- 影响主页入口、Sidebar、tree shell、文档页首屏时，优先补或复用 `scripts/task*-smoke.js` 这类 smoke 脚本。
+- 排查高 CPU / 高内存 / 卡顿时，先看是否存在首屏误走实验性 tree shell、compat fallback、重复请求、轮询或回链面板持续刷新，再看数据底座。
+
 ## 文件编码与风格
 
 - 所有新增或修改文件统一使用 UTF-8。