mnote/AGENTS.md

仓库协作指南（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-tiptap island；BlockNote 当前是 fallback / 对照链，不再代表默认主编辑器方向。
• 当前最优先的架构收口不是继续扩编辑器 UI，而是 Page Aggregate、tree command cutover、tree realtime event stream 三条主线。

组件定位

• leptos-tiptap island 是当前文档页默认主编辑区 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、重复请求、轮询或回链面板持续刷新，再看数据底座。

Wolai-aline 对标流程

• 凡任务涉及 wolai-aline、Wolai 对标、复刻 Wolai 体验或把 3000 行为与 Wolai 页面比对，必须启用 /home/lix/.codex/skills/wolai-aline skill，并参考 /mnt/Data1T/mnote/design/08-wolai-aline-test-flow/process/wolai-aline-test-flow-v1.md。
• Wolai-aline 任务默认采用“Wolai 基线取证（默认只读，编辑器任务可用 Hermes editable-test mode）-> 本地 RED smoke -> 小范围实现 -> 本地验证 -> subagent 浏览器对标复测 -> 主线程截图复核 -> 汇报剩余差异”的流程。
• 浏览器对标测试必须使用 subagent 执行；subagent 只做浏览器验证和截图，不修改源码、不还原文件、不清理证据；编辑器任务可在明确声明的 Hermes editable-test mode 下做最小编辑验证。
• Wolai 默认优先只读；当前 Hermes 测试页 https://www.wolai.com/liaibo/ikFSSM1a4GgvmHBYFCNfVd 已授权用于 Wolai-aline 编辑器对标，可做最小范围编辑测试。其他 Wolai 页面写入仍需沙盒页 URL 和明确授权。
• 即使在 Hermes 测试页，也禁止未经确认地删除、移动、归档、发布、评论、改权限或批量修改既有非测试内容；编辑测试必须记录前后截图、动作链、输入内容和清理状态。
• 对标验收不能只看文案或 DOM 是否存在；必须检查截图中的控件形态、开启/关闭状态、hover/active 状态、快捷键行为、URL 是否跳转等真实体验差异。
• 发现截图或实测行为与本地实现不一致时，先把差异补进 smoke 形成可复现失败，再修改实现并复测。
• Wolai owner 登录态优先复用 /mnt/Data1T/mnote/tmp/wolai-playwright-profile；遇到登录或滑块验证，不绕过，记录阻塞并让用户介入。

文件编码与风格

• 所有新增或修改文件统一使用 UTF-8。
• TS/TSX 默认 2 空格缩进，Python 默认 4 空格缩进。
• 注释使用简体中文。