0.3.3 外网下载修复

2026-01-21 18:21:10 +08:00
parent f13de35321
commit 71de56850b
45 changed files with 2499 additions and 476 deletions
@@ -1,167 +1,124 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+本文件用于指导 Claude Code（claude.ai/code）在此仓库中进行开发与协作。

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

-MNOTE is a knowledge management system combining Notion-like block documents, mind mapping, and AI-powered productivity tools. Built as a hybrid web/desktop application with local-first capabilities.
+## 项目概览
+MNOTE 是一个知识管理系统，结合类 Notion 的块编辑器、思维导图与 AI 工具，支持 Web/桌面（Electron）混合形态。

-**Tech Stack:**
- Frontend: Next.js 16 (App Router), React 19, BlockNote editor
- Backend: FastAPI + Celery (Python)
- Desktop: Electron with embedded Next.js standalone
- Database: Supabase (PostgreSQL), migrating to Convex for some features
- AI: Tool-based agent system with 30+ built-in tools
+**技术栈（核心）**
+- 前端：Next.js（App Router）、React、BlockNote
+- 数据层：Convex（自托管见 `infra/convex/`；functions 见 `wolai-frontend/convex/`）
+- 后端（辅助能力）：FastAPI + Celery（OCR / OnlyOffice / 集成服务等）
+- 桌面端：Electron（内嵌 Next.js standalone）
+- AI：工具型 Agent 系统（30+ 内置工具）

-## Development Commands
+## 常用命令

-### Quick Start
+### 快速启动（推荐）
 ```bash
-npm run desktop:hot          # Start frontend + backend + Celery (recommended)
-npm run desktop:local        # Local-only mode (offline)
-npm run desktop              # Production desktop mode
+npm run desktop:hot          # 启动前端 + 后端（Redis 可用时启 Celery）
+npm run desktop:local        # 本地离线模式
+npm run desktop              # 桌面端生产模式
 ```

-### Frontend Only (wolai-frontend/)
+### 仅前端（wolai-frontend/）
 ```bash
-pnpm dev                     # Next.js dev server on port 3000
-pnpm build                   # Production build
-pnpm start                   # Start production server
-pnpm lint                    # ESLint check
-pnpm test                    # Run Vitest unit tests
+pnpm dev
+pnpm build
+pnpm start
+pnpm lint
+pnpm test
 ```

-### Backend Only (wolai-backend/)
+### 仅后端（wolai-backend/）
 ```bash
 pip install -r requirements.txt
-uvicorn app.main:app --reload --port 8000    # FastAPI dev server
-celery -A app.workers.celery_app worker --loglevel=info  # Celery worker
+uvicorn app.main:app --reload --port 8000
+celery -A app.workers.celery_app worker --loglevel=info
 ```

-### Desktop Build
-```bash
-npm run build:desktop:next   # Build Next.js standalone to desktop-electron/desktop-next/
-npm run dist:win             # Build Windows NSIS installer
-```
+### Convex（自托管）
+按 `infra/convex/README.md` 启动（Docker Compose）。

-### Testing
+### E2E 测试
 ```bash
 cd pw-tests/scripts
-python e2e_mindmap_sync.py   # Run E2E test
+python e2e_mindmap_sync.py
 ```

-## Architecture
+## 架构与目录

-### Directory Structure
+### 目录结构（关键）
 ```
-wolai-frontend/              # Main Next.js frontend (ACTIVE - use this)
-├── src/
-│   ├── app/                 # Next.js App Router
-│   │   ├── (app)/           # Main app layout (sidebar + content)
-│   │   ├── (auth)/          # Auth pages
-│   │   ├── api/             # API routes (BFF pattern)
-│   │   ├── documents/[id]/  # Document pages
-│   │   └── mindmap/         # Mindmap pages
-│   ├── components/
-│   │   ├── editor/          # Editor components (BlockNote, blocks)
-│   │   └── sidebar/         # File tree navigation
-│   ├── lib/
-│   │   ├── ai-agent/        # AI agent runtime & tools
-│   │   ├── supabase/        # Supabase client wrappers
-│   │   └── mindmap/         # Mindmap storage/logic
-│   └── store/               # Zustand state stores
-wolai-backend/               # FastAPI backend
-├── app/
-│   ├── main.py              # FastAPI entry point
-│   ├── routers/             # API routes
-│   ├── services/            # Business logic
-│   └── workers/             # Celery tasks
-desktop-electron/            # Electron wrapper
-supabase/                    # Database migrations
+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/                    # 历史遗留（不要当作现行架构）
 ```

-**WARNING:** Root `src/` directory may be legacy/mirror. Always work in `wolai-frontend/src/` for frontend changes.
+**注意：**仓库根目录的 `src/` 可能是历史/镜像目录；前端改动优先在 `wolai-frontend/src/`。

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

-**BFF (Backend for Frontend):** Next.js API routes handle auth + Supabase queries. Frontend never talks directly to Supabase (except via client library).
+## 环境变量与配置

-**AI Agent System:** Tool-based architecture with execution loop, SSE streaming, and permission model (read/write). See `wolai-frontend/src/lib/ai-agent/`.
-
-**Desktop + Web Parity:** Same Next.js codebase serves both. Desktop uses embedded server with runtime config override (`window.__MNOTE_RUNTIME_CONFIG__`).
-
-**Mindmap First-Class:** Stored as structured JSON, not just visualization. Supports node refs (attachments, URLs with page numbers), AI expansion.
-
-## Environment Configuration
-
-### Required Variables
-
-**wolai-frontend/.env.local:**
+### 前端（wolai-frontend/.env.local）
+至少需要：
 ```bash
-NEXT_PUBLIC_SUPABASE_URL=...
-NEXT_PUBLIC_SUPABASE_ANON_KEY=...
-NEXT_PUBLIC_BACKEND_URL=...
-NEXT_PUBLIC_ONLYOFFICE_BASE_URL=...
+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（如启用）
 ```

-**wolai-backend/.env:**
+### 服务端（仅在需要服务端直连/管理权限时）
 ```bash
-SUPABASE_URL=...
-SUPABASE_SERVICE_ROLE_KEY=...
-REDIS_URL=redis://localhost:6379/0
-FRONTEND_URL=http://localhost:3000
+CONVEX_SELF_HOSTED_URL=...
+CONVEX_SELF_HOSTED_ADMIN_KEY=...
 ```

-**AI Configuration (ai.md or env):**
-```
-apikey: sk-xxx
-https://api.openai.com/v1
-gpt-4
-```
+### 桌面端运行期配置
+桌面端会读取/合并运行期配置（如 `public/mnote-env.json` 与桌面配置文件）。以 Convex 为主线配置即可；若看到 Supabase 字段，默认当作历史兼容残留处理。

-**Desktop (auto-generated in data/electron/config.json):**
-```json
-{
-  "networkMode": "remote-client|local|tunnel|auto",
-  "supabaseUrl": "...",
-  "backendUrl": "..."
-}
-```
+## 编码约定
+- 文件编码：UTF-8；代码注释允许中文（建议简体）。
+- 缩进：TS/TSX 2 空格，Python 4 空格。
+- 命名：组件 `PascalCase`，hooks `useXxx`，测试 `*.test.ts(x)`。
+- 导入：使用 `@/` 作为绝对路径别名。

-## Coding Conventions
+## 关键文件（快速上手）
+- `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`：代码索引（中文）。

- **File encoding:** UTF-8, Chinese comments allowed
- **Indentation:** 2 spaces (TS/TSX), 4 spaces (Python)
- **Naming:** PascalCase for components (`MindmapBlock.tsx`), `useXxx` for hooks, `*.test.ts(x)` for tests
- **Imports:** Use `@/` alias for absolute imports
- **Commits:** Version tags (`0.1.13 ...`) or conventional commits (`feat(mindmap):`, `fix:`, `chore:`)
+## 其他注意事项
+- 不要提交密钥/Token/账号；本地配置优先放在 `.env.local`、`wolai-frontend/.env.local`、`wolai-backend/.env`。
+- 路由目录含 `()` 和 `[]`（如 `(app)`、`[id]`），PowerShell 中操作建议用 `-LiteralPath` 避免通配符误匹配。

-## Key Files for Understanding
+## 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

- `wolai-frontend/src/app/layout.tsx` - Root providers
- `wolai-frontend/src/lib/ai-agent/runtime/runAgent.ts` - AI agent engine
- `wolai-frontend/src/lib/ai-agent/tools/builtins/registryBuiltins.ts` - All AI tools
- `wolai-frontend/src/components/editor/document-content.tsx` - Editor core
- `wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx` - Mindmap UI
- `desktop-electron/main.js` - Desktop entry point
- `scripts/desktop-hot.js` - Dev orchestration
- `AGENTS.md` - Project guidelines (Chinese)
- `CODE_INDEX.md` - Complete code map (Chinese)
-
-## Important Notes
-
- Never commit API keys or tokens
- Use existing ESLint/Vitest configurations
- Desktop data stored in `<install_dir>/data/` (portable)
- Supabase local: see `supabase.md` for ports/URLs
- Route directories contain `()` and `[]` - use `-LiteralPath` in PowerShell
-
-## AI Agent Tool Development
-
-When adding new AI capabilities, register tools in `wolai-frontend/src/lib/ai-agent/tools/builtins/`. Tools are organized by 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
-
-Permission model: `{ read: "allow" | "confirm", write: "allow" | "confirm" }`
+权限模型：`{ read: "allow" | "confirm", write: "allow" | "confirm" }`