lix/mnote

Fork 0

Files

T

liaibo af92c4b149 0.4.0 convex及界面修改

2026-02-01 08:47:40 +08:00

5.3 KiB

Raw Blame History

CLAUDE.md

本文件用于指导 Claude Code（claude.ai/code）在此仓库中进行开发与协作。

重要（防止误判）

当前已使用 Convex 完全替换 Supabase：数据读写、鉴权与权限控制以 Convex 为主线。
仓库内若仍存在 supabase/、supabase.md、wolai-frontend/src/lib/supabase/、@supabase/* 依赖或相关代码，均应视为历史遗留/兼容残留；除非任务明确要求，否则不要基于它们继续扩展实现。

项目概览

MNOTE 是一个知识管理系统，结合类 Notion 的块编辑器、思维导图与 AI 工具，支持 Web/桌面（Electron）混合形态。

技术栈（核心）

前端：Next.js（App Router）、React、BlockNote
数据层：Convex（自托管见 infra/convex/；functions 见 wolai-frontend/convex/）
后端（辅助能力）：FastAPI + Celery（OCR / OnlyOffice / 集成服务等）
桌面端：Electron（内嵌 Next.js standalone）
AI：工具型 Agent 系统（30+ 内置工具）

常用命令

快速启动（推荐）

npm run desktop:hot          # 启动前端 + 后端（Redis 可用时启 Celery）
npm run desktop:local        # 本地离线模式
npm run desktop              # 桌面端生产模式

仅前端（wolai-frontend/）

pnpm dev
pnpm build
pnpm start
pnpm lint
pnpm test

仅后端（wolai-backend/）

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
celery -A app.workers.celery_app worker --loglevel=info

Convex（自托管）

按 infra/convex/README.md 启动（Docker Compose）。

E2E 测试

cd pw-tests/scripts
python e2e_mindmap_sync.py

架构与目录

目录结构（关键）

wolai-frontend/              # 主前端（优先在这里改）
  src/                       # Next.js 源码
  convex/                    # Convex functions（schema/query/mutation/action）
  public/                    # 静态资源 + mnote-env.json 等
infra/convex/                # Convex 自托管（compose + README）
wolai-backend/               # FastAPI 后端（辅助能力）
services/                    # 配套服务（OCR/RAG 等）
pw-tests/                    # 端到端测试
desktop-electron/            # Electron 包装
supabase/                    # 历史遗留（不要当作现行架构）

**注意：**仓库根目录的 src/ 可能是历史/镜像目录；前端改动优先在 wolai-frontend/src/。

关键模式

BFF（Backend for Frontend）：Next.js Route Handlers 负责鉴权与调用 Convex（query/mutation/action），前端页面通过这些 API/或 Convex provider 获取数据。
桌面端与 Web 共用代码：桌面端通过运行期注入配置（window.__MNOTE_RUNTIME_CONFIG__）实现同一套前端在不同网络/环境下运行。
思维导图是一等公民：以结构化 JSON 存储，支持节点引用（附件、URL + 页码）、AI 扩写等。

环境变量与配置

前端（使用仓库根目录 .env.all）

至少需要：

NEXT_PUBLIC_CONVEX_URL=...           # 浏览器侧 Convex URL（云端或自托管）
NEXT_PUBLIC_USE_CONVEX=1             # 开启 Convex 模式（或 USE_CONVEX=1）
NEXT_PUBLIC_BACKEND_URL=...          # FastAPI（如启用 OCR/OnlyOffice 等）
NEXT_PUBLIC_ONLYOFFICE_BASE_URL=...  # OnlyOffice（如启用）

服务端（仅在需要服务端直连/管理权限时）

CONVEX_SELF_HOSTED_URL=...
CONVEX_SELF_HOSTED_ADMIN_KEY=...

桌面端运行期配置

桌面端会读取/合并运行期配置（如 public/mnote-env.json 与桌面配置文件）。以 Convex 为主线配置即可；若看到 Supabase 字段，默认当作历史兼容残留处理。

编码约定

文件编码：UTF-8；代码注释允许中文（建议简体）。
缩进：TS/TSX 2 空格，Python 4 空格。
命名：组件 PascalCase，hooks useXxx，测试 *.test.ts(x)。
导入：使用 @/ 作为绝对路径别名。

关键文件（快速上手）

wolai-frontend/src/app/layout.tsx：根布局与运行期配置注入（Convex provider 挂载）。
wolai-frontend/src/components/providers/convex-provider.tsx：Convex React Client 初始化与 Provider。
wolai-frontend/src/lib/convex/：Convex client/server/route 封装。
wolai-frontend/convex/：Convex functions（数据模型与后端逻辑）。
wolai-frontend/src/lib/ai-agent/runtime/runAgent.ts：AI agent 引擎。
wolai-frontend/src/lib/ai-agent/tools/builtins/registryBuiltins.ts：内置工具注册表。
scripts/desktop-hot.js：开发编排脚本。
AGENTS.md：仓库协作指南（中文）。
CODE_INDEX.md：代码索引（中文）。

其他注意事项

不要提交密钥/Token/账号；本地/生产配置统一放在仓库根目录的 .env.all（UTF-8，且要求 key 唯一）。
路由目录含 () 和 []（如 (app)、[id]），PowerShell 中操作建议用 -LiteralPath 避免通配符误匹配。

AI Agent 工具开发

新增 AI 能力时，在 wolai-frontend/src/lib/ai-agent/tools/builtins/ 注册工具，按 scope 组织：

Global：search_web、docs_search/read
Mindmap：mindmap_get、mindmap_apply_ops
Document：doc_get、doc_insert_blocks
OnlyOffice：oo_get_selection、oo_replace_selection

权限模型：{ read: "allow" | "confirm", write: "allow" | "confirm" }

5.3 KiB Raw Blame History Unescape Escape