mnote/REASONIX.md

MNOTE — Reasonix working knowledge

Current Baseline

• MNote 已进入 local-first MVP 后阶段：最小可用闭环已建立，后续重点是底座统一、compat 瘦身和产品化闭环。
• 产品形态固定为：VSCode 简化版工作区 + tiptap 的 Markdown 前端编辑器 + Hermes/Reasonix agent + simplemindmap/office 插件 + Wolai 主题 Web 壳 + 鉴权控制面。
• 本地 workspace folder 是默认数据真相；本地 .md 是页面正文真相；Page Aggregate、tiptap state、AI context 都是投影或工作副本。
• Rust kernel / projection / command 持有树、页面、资源和权限语义；新增树规则不要散落到前端、Next route 或临时 compat 层。
• Rust SQLite control-plane 已承接默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 等控制面；Convex / 服务端不再是默认正文、附件、AI 会话全文主存储，只保留历史迁移源、显式 cloud source、compat 和 sync replica 边界。
• mnote-web 是当前 3000 owner；旧 Next / React / wolai-frontend 已移入 recycle/，默认不作为当前实现依据。
• 前端 runtime 已完成第一轮模块级拆分；查浏览器 JS 功能默认先看 rust/crates/mnote-web/browser/*.js，查 tiptap island 行为默认先看 rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs。不要把 layout.rs / tree.rs / web_shell.rs 的历史 raw string 当作当前符号定位入口。
• Knowledge RAG 当前统一到 LightRAG：LiteParse、旧 OCR sidecar、旧 evidence search / local-index agent tools 不再作为默认 fallback；LightRAG 负责 OCR / parse / index / RAG，MNote 负责 source registry、权限、FileTree 灯号、资料库 UI、dashboard/status 和 citation/open-reference。当前模型口径为 aigc/qwen-3.5。

Stack

• Rust — workspace of 11 crates, edition 2021, resolver 2, wasm32 target (rust/rust-toolchain.toml)
• Axum 0.8 — HTTP/WebSocket server in mnote-web crate
• Leptos 0.8.14 — SSR island rendering in mnote-web
• Convex 1.x — retired root functions source plus optional cloud/compat/sync replica service boundary, not the default control plane or document/media/session full-text store
• Playwright — browser smoke tests in scripts/task-*.js

Layout

Path	Contents
rust/crates/mnote-web/	Rust web gateway (axum + Leptos SSR, :3000)
rust/crates/mnote-web/browser/	Browser runtime modules for sidebar, filetree, document adapter, tree shell, Page AI panel host
rust/crates/mnote-web/src/routes/knowledge_rag.rs	MNote LightRAG connector routes: status, ingest, query, delete, prune, open-reference
rust/crates/mnote-web/src/hermes_tools/knowledge_rag.rs	Hermes / Reasonix-facing knowledge RAG tool facade
rust/crates/core-protocol/	Kernel types, projection protocol, tree/graph terms
rust/crates/bridge-runtime/	Kernel query/command, projection bridge, source normalization
rust/spikes/leptos-tiptap-spike/src/editor_runtime/	Leptos-tiptap island runtime modules; use before editing root lib.rs
rust/crates/mnote-cli/	CLI tool (sidebar dataset, page get/create/title/save/move, block insert/patch)
rust/crates/storage-convex-bridge/	Convex compat / cloud source / sync-replica bridge for Rust
recycle/20260522-convex-runtime-retirement/convex/	Retired root Convex functions source retained for audit / migration reference
recycle/20260522-convex-runtime-retirement/infra/convex/	Retired self-hosted Convex backend compose kept only for historical cloud/compat/sync-replica reference
infra/onlyoffice/	Docker Compose for OnlyOffice
scripts/	Node.js dev/build scripts + Playwright smoke tests
design/	Architecture design documents organized by domain
bugs/	Bug tracking mirroring design domain structure
recycle/	Retired code (old frontend, deprecated design drafts)

Commands

• npm run desktop:hot — hot-reload dev start (Rust gateway + optional FastAPI backend + optional Celery)
• npm run dev:hot — same but with cargo-watch for Rust auto-recompile
• npm run desktop — production start
• cargo test -p <crate> — test a specific Rust crate
• cargo run -p mnote-web --bin mnote-web — run the web server binary directly
• codegraph sync . — refresh CodeGraph after normal code changes
• codegraph index . --force — rebuild CodeGraph after large refactors, ignore-rule changes, or stale index behavior

CodeGraph MCP

• Reasonix has codegraph=codegraph serve --mcp configured in /home/lix/.reasonix/config.json.
• Prefer CodeGraph for structural code questions: symbol lookup, definitions, callers/callees, impact analysis, and focused cross-file context.
• Use codegraph_search for symbol names, codegraph_callers / codegraph_callees for call flow, codegraph_impact before risky edits, codegraph_context for focused task context, and codegraph_files / codegraph_status for index inspection.
• Use native search only for literal text, comments, log messages, or after a specific file is already identified.
• Keep the project index fresh in development: run codegraph sync . after code changes; use codegraph index . --force when the index looks stale or after broad restructuring.
• Runtime split is the current CodeGraph baseline: JS functions should be found in browser/*.js and editor runtime symbols in editor_runtime/*.rs. If search results point to recycle/, historical design docs, or old Rust raw strings, treat them as historical context unless the task explicitly targets legacy code.

Reasonix Worker Boundary

• Reasonix is a leaf worker, not a main controller.
• Do not start nested Reasonix runners, subagents, extra worktrees, or rewrite task prompts from inside a Reasonix task.
• Coding tasks must use an explicitly assigned write scope and report every modified file.
• Read-only and browser tasks must leave modified_files empty and prove it with git status --short / git diff --stat.
• Browser verification must produce the artifact contract from design/07-ai/process/7-35-reasonix-browser-test-contract-v1.md: result.json, final.md, handoff files, screenshots, console/network evidence, and environment preconditions.
• Codex/Hermes main controller accepts Reasonix output only after checking handoff/result files, diff, validation evidence, and current repo status. Natural-language conclusions without artifacts are leads, not verification.

Reference-Code Comparison

• Reference implementations live under /mnt/Data1T/mnote/reference-code/; prefer /mnt/Data1T/mnote/reference-code/sidex-main for VSCode workbench comparisons because it contains the fuller src/vs/workbench tree, while reference-code/vscode is a smaller auxiliary snapshot.
• Compare one feature slice at a time, such as explorer open target, editor tabs, resource lifecycle, drag-and-drop ordering, keybindings, or overlay placement.
• Fast workflow: check codegraph_status for both projects, locate reference entry points with codegraph_search/context, inspect callers/callees, inspect the matching MNote chain, then map the result onto Rust kernel / mnote-web / frontend host boundaries.
• Always classify findings as: reusable interaction/state model, reference-only implementation detail, or incompatible with MNote local-first / tree-first architecture.

Conventions

• Local-first default: start from Rust mnote-web, LocalFS/local_folder projection, Page Aggregate, File Tree, Resource Tree, and SQLite control-plane auth/session/actor. Use Convex paths only for explicit cloud source, compat, sync-replica, migration, or rollback work.
• Smoke test pattern: standalone Playwright scripts under scripts/task-*.js using a shared harness (ensureAuthenticated, createTempDocument, cleanupDocuments). All use "use strict" and require("playwright") (scripts/task110-page-title-single-truth-smoke.js:1-4).
• Smoke baseline: use scripts/TESTING_REFERENCE.md for current/compat/manual/retired classification. Default browser baseline is 3000 Rust SSR + leptos-tiptap island + local-first workspace + SQLite control-plane auth.
• Rust workspace: edition 2021, resolver "2", MIT license. All crates inherit workspace version (rust/Cargo.toml:2-8).
• Convex boundary: root convex/ has been retired to recycle/20260522-convex-runtime-retirement/convex/; infra/convex/ has been retired to recycle/20260522-convex-runtime-retirement/infra/convex/; do not recreate either as an active deploy source without a new architecture decision. recycle/wolai-frontend/convex is also historical. Keep Rust transport/convex.rs and storage-convex-bridge as explicit cloud/compat boundaries; do not mechanically delete them with the retired functions source.
• AI editing path: local-first Markdown editing should prefer currentFile + selection + allowedRoots / aiAccessScope + agent native patch/diff + watcher sync. mnote.doc.* / mnote.block.* are cloud, remote, compat, or complex-structure helpers.
• Knowledge RAG path: use mnote.knowledge_rag.status/query/open_reference and /api/knowledge-rag/*. Do not use mnote.evidence.*, LiteParse, or local OCR sidecar as the default retrieval/indexing path. Image sources enter LightRAG through a Markdown wrapper; MNote status bridge/backoff syncs LightRAG background completion back to the registry and FileTree.
• Bug tracking: bugs organized by design domain directory (e.g. bugs/04-tree-domain/process/), moved to done/ when fixed (bugs/README.md).
• Design docs: organized by domain in design/, with process/ (in-progress) and done/ (completed) subdirs (design/README.md).

Watch out for

• write_file path rule: paths are sandbox-relative; leading / is stripped. Use path: "design/..." not /mnt/Data1T/mnote/design/....
• .aionrs/, .claw/, .codex/, .gemini/ — session data from other AI tools, not project code. Don't read or edit.
• recycle/ — retired code, not current implementation. Don't use as evidence for current behavior.
• Convex availability: local-folder / Rust projection smoke should not require Convex. Auth, share grants, ACP/Hermes runtime state, and AI policy default to SQLite control-plane; Convex is required only for tests that explicitly cover legacy cloud source, compat, sync replica, migration, or rollback behavior.
• LightRAG boundary: LightRAG storage is derived cache, not user source truth. MNote registry is the mapping authority for source path, doc id, stale/deleted state, FileTree lights, and citation routing.
• MVP 后阶段优先级: prefer WorkspacePath/ObjectIdentity runtime consumption, DocumentBuffer/BufferStore, Page Aggregate compat slimming, tree command context/context key, live cache unification, agent diff audit, conflict merge, local lightweight search, and share/sync productization. Knowledge RAG belongs to LightRAG, not a revived local evidence/LiteParse index.
• Rust wasm32 target required (rust/rust-toolchain.toml), needed for tree-shell-runtime-wasm crate.
• rust/target/ is gitignored and large — cargo build runs from scratch if cache is missing.