仓库协作指南（AGENTS）

当前主线

当前长期方向以 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 层重新拼出第二份对象真相。

/mnt/Data1T/mnote/wolai-frontend/src/ 页面、编辑器、Sidebar、树视图、阅读态、交互壳默认先看这里。
/mnt/Data1T/mnote/wolai-frontend/convex/ 仍在使用的 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 静态资源、插件或兼容问题时进入。
/mnt/Data1T/mnote/recycle/ 默认视为历史回收区，不作为当前实现依据，除非任务明确要求。

涉及树、页面结构、文件树、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

仅修改与当前任务直接相关的文件。
不要擅自恢复、覆盖、删除用户已有改动。
若发现与当前任务无关的脏改动，保持不动；若怀疑会影响当前任务，先确认再处理。
若当前问题只是 UI 表现异常，先确认是否是实验性 tree shell、compat 路径、轮询或 fallback 混入首屏主链，而不是直接怀疑 Convex 本身。

根目录热启动：npm run desktop:hot
前端开发：cd /mnt/Data1T/mnote/wolai-frontend && pnpm dev
前端检查：cd /mnt/Data1T/mnote/wolai-frontend && pnpm lint && pnpm test
后端开发：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、重复请求、轮询或回链面板持续刷新，再看数据底座。