mnote/CLAUDE.md

# 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" }`