125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
# 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+ 内置工具）
|
||
|
||
## 常用命令
|
||
|
||
### 快速启动（推荐）
|
||
```bash
|
||
npm run desktop:hot # 启动前端 + 后端（Redis 可用时启 Celery）
|
||
npm run desktop:local # 本地离线模式
|
||
npm run desktop # 桌面端生产模式
|
||
```
|
||
|
||
### 仅前端（wolai-frontend/）
|
||
```bash
|
||
pnpm dev
|
||
pnpm build
|
||
pnpm start
|
||
pnpm lint
|
||
pnpm test
|
||
```
|
||
|
||
### 仅后端（wolai-backend/）
|
||
```bash
|
||
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 测试
|
||
```bash
|
||
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）
|
||
至少需要：
|
||
```bash
|
||
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（如启用）
|
||
```
|
||
|
||
### 服务端（仅在需要服务端直连/管理权限时）
|
||
```bash
|
||
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" }`
|