lix-2026
41e958769e
- 收口 page aggregate 读取、本地状态与命令客户端\n- 接入 phase7 document ai sidecar 与前端编排入口\n- 更新 architecture 与 design 状态迁移
6.7 KiB
6.7 KiB
仓库协作指南（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只用于过渡和测试，不应继续承载长期业务语义。3000是唯一前端公开入口；3104已退役为仅显式 debug/internal 使用的边界。/tree、/document-debug等 debug 壳默认关闭，仅在显式 debug/runtime 验证时启用。- 前端主路径应消费稳定 projection，不应在 UI 层重新拼出第二份对象真相。
- 文档页默认主编辑器已切到页面内
leptos-tiptapisland；BlockNote当前是 fallback / 对照链，不再代表默认主编辑器方向。 - 当前最优先的架构收口不是继续扩编辑器 UI，而是
Page Aggregate、tree command cutover、tree realtime event stream三条主线。
组件定位
leptos-tiptapisland 是当前文档页默认主编辑区 runtime，但不是系统事实源。BlockNote是迁移期 fallback / 对照编辑器，不是系统事实源。Mindmap是tree-first graph的一种视图和编辑挂件，不是对象真相层。OnlyOffice是独立页面型编辑器，不直接嵌入BlockNote画布；正文中通常通过附件块跳转进入。
目录优先级
/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。- 涉及文档页标题、页面设置、正文保存、页头与树一致性时，优先判断是否应收口到
Page Aggregate，不要继续在页面壳或 island 外侧拼第二份页面真相。 - 涉及页面新建、重命名、移动、归档、恢复、嵌入时，优先沿
tree.*正式命名推进；documents.*只视为兼容层，不应继续扩写为长期命令面。 - 需要架构判断时，优先参考：
/mnt/Data1T/mnote/ARCHITECTURE.md/mnt/Data1T/mnote/design/01-05-current-priority-overview.md/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md/mnt/Data1T/mnote/design/04-tree-domain/process/4-6-tree-command-protocol-cutover-stage2-v1.md/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md
设计稿目录规则
design/01-*到design/07-*主线大类统一按process/与done/分层。- 主线设计稿在推进中时放到对应大类的
process/。 - 主线设计稿在当前真实代码中已完成后，必须移动到对应大类的
done/。 - 已被后续实现或更新稿明确覆盖、但又不属于
done的旧主线稿，必须移动到design/old/并标记为[recycle]，不要继续占用活跃process/。 design/old/下的历史废弃稿也统一按process/与done/分层，但标题继续标记[recycle]。design/90-reference/只放参考资料，不参与process/done状态迁移。
协作边界
- 仅修改与当前任务直接相关的文件。
- 不要擅自恢复、覆盖、删除用户已有改动。
- 若发现与当前任务无关的脏改动，保持不动；若怀疑会影响当前任务，先确认再处理。
- 若当前问题只是 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、重复请求、轮询或回链面板持续刷新，再看数据底座。
文件编码与风格
- 所有新增或修改文件统一使用 UTF-8。
- TS/TSX 默认 2 空格缩进，Python 默认 4 空格缩进。
- 注释使用简体中文。