9.4 KiB
9.4 KiB
# 开发集成笔记、思维导图、OCR 和 AI 问答软件的全面蓝图（v2.0 — 审查与完善版）
**目标**：深度复刻 Wolai 的块编辑体验 + MindManager 级别的思维导图 + Supabase 在线实时协作 + 可靠的文件 OCR + 基于知识图谱的精准的 AI 问答，形成一个真正的「统一工作流」生产力工具。
**核心原则（给 AI 编码助手看的）**：
- 全栈 TypeScript（Next.js 15 + App Router），尽量保持单一语言栈
- 90% 以上功能使用成熟开源库实现，禁止「从零造轮子」
- 所有数据最终都落在 Supabase（PostgreSQL + pgvector + Storage + Realtime + RLS）
- AI/RAG 部分必须兼容 Node.js（因此放弃 Python 系的 LightRAG，改用 LangChain.js + pgvector + 可选的 Neo4j AuraDB 免费层实现知识图谱）
- 所有组件都要支持 SSR / RSC，首屏加载 < 1.2s，编辑器操作零卡顿
- 暗黑模式、白主题、移动端响应式必须开箱即用
## 1. 功能拆解（最终验收标准）
| 模块 | 核心功能 | 验收标准（可直接写测试用例） |
|---------------|-----------------------------------------------|-----------------------------------------------------------|
| 笔记 | 块编辑器、嵌套页面、双向链接、模板、斜杠命令 | 可无限嵌套、可拖拽排序、实时多人光标、斜杠命令完整 |
| 思维导图 | 拖拽节点、折叠分支、自定义样式、双向同步笔记 | 导图修改 ↔ 笔记大纲实时同步，可导出 PNG/PDF/Markdown |
| 在线查看/协作 | 实时同步、共享链接、权限控制、公共只读页 | 延迟 < 800ms，支持 20 人同时编辑无明显冲突 |
| 文件 OCR | 图片/PDF 上传后自动提取文字 → 新建笔记块 | 支持中英文混排，准确率 > 92%（清晰扫描件），进度条反馈 |
| AI 问答 | 语义搜索 + 知识图谱双层检索 + 生成式回答 | 回答必须带来源引用，支持「总结项目」「对比两个想法」等复杂问 |
## 2. 最终技术栈（2025 年 11 月最新推荐）
| 层级 | 选型 | 理由 & 替代方案 | 关键集成点 |
|---------------|-------------------------------------------|----------------------------------------------------------|------------|
| 前端框架 | Next.js 15（App Router + React Server Components） | 最强 RSC + Partial Prerendering，完美支持嵌套路由 | — |
| UI/样式 | Tailwind CSS + shadcn/ui + Radix UI + lucide-react | 组件最现代、可自定义程度最高 | `npx shadcn@latest init` |
| 认证/实时 | Supabase Auth + Realtime + RLS | 一站式解决，无需额外后端 | `@supabase/auth-helpers-nextjs` |
| 笔记编辑器 | BlockNote Pro（付费）→ 首选<br>Tiptap 2 + @blocknote/react（免费）→ 备选 | BlockNote 开箱即用斜杠命令、嵌入块、实时协作示例最完整 | 通过 Yjs + Supabase Realtime 实现多人编辑 |
| 思维导图 | React Flow 11 + xyflow | 最活跃、RSC 友好、可自定义节点最强 | 节点数据存 JSONB，id 与笔记 document 表关联 |
| 数据库 | Supabase PostgreSQL + pgvector | 自带向量搜索，RLS 完美，支持递归 CTE 查树 | documents、mindmaps、entities、relationships 表 |
| 存储 | Supabase Storage | 内置 CDN、病毒扫描、权限控制 | OCR 原文件与预览图 |
| OCR | Tesseract.js（客户端）+ pdfjs-dist（PDF 转图）<br>可选后备：supabase edge function + tesseract wasm 或第三方 API | 客户端零后端依赖，隐私更好；大文件交给 edge function | Worker 内运行，避免阻塞主线程 |
| AI / RAG | LangChain.js + OpenAI SDK + pgvector<br>知识图谱层：Neo4j AuraDB 免费层（或 Supabase + 自建图表） | LangChain.js 完全 TS 支持；Neo4j 图查询极快，免费 5 万节点足够早期 | 笔记保存时异步触发「实体/关系抽取」→ 存 Neo4j |
| 其他工具 | react-dropzone、sonner、emoji-picker-react、zustand、tanstack-query | 标准生产力栈 | — |
> **为什么放弃 LightRAG**：它是 Python 框架，无法直接在 Next.js 中运行。改用 LangChain.js + Neo4j 的组合在功能上完全等价甚至更强，且保持全 TS 栈。
## 3. 数据库表结构（直接复制到 Supabase SQL Editor）
```sql
-- 文档树（Wolai 核心）
create table documents (
id uuid primary key default uuid_generate_v4(),
uuid,
user_id uuid references auth.users not null,
parent_id uuid references documents(id), -- null 为根页面
title text default '无标题',
content jsonb default '{}', -- BlockNote 格式
mindmap_data jsonb, -- 可选思维导图 JSON
is_public boolean default false,
created_at timestamptz default now(),
updated_at timestamptz default now()
);
-- 知识图谱实体（AI 用）
create table entities (
id uuid primary key default uuid_generate_v4(),
user_id uuid references auth.users not null,
name text not null,
type text, -- person, project, concept...
properties jsonb,
document_ids uuid[]
);
-- 关系
create table relationships (
id uuid primary key default uuid_generate_v4(),
from_entity uuid references entities,
to_entity uuid references entities,
type text,
document_ids uuid[]
);
-- pgvector 向量表（用于普通向量检索）
create table document_embeddings (
id uuid primary key default uuid_generate_v4(),
document_id uuid references documents,
embedding vector(1536), -- text-embedding-3-large
content_text text
);
4. 分阶段实施计划（带人天估算，给 PM 和 AI 助手看）
| 阶段 | 目标 | 核心任务 | 预估人天 | 可直接给 Claude/Codex 的 Prompt 示例 |
|---|---|---|---|---|
| 0 | 项目初始化 | create-next-app@latest + TypeScript + App Router + Tailwind + shadcn + supabase | 1 天 | “Generate a Next.js 15 App Router project with Supabase auth, dark mode, and shadcn/ui ready.” |
| 1 | Wolai 核心页面树 + BlockNote 编辑器 | 递归侧边栏 + /documents/[id] 页面 + 实时保存 | 4-6 天 | “Build a recursive document sidebar using Supabase recursive CTE and a BlockNote editor with Yjs + Supabase Realtime for multiplayer.” |
| 2 | 斜杠命令 + 嵌入块 + 模板系统 | 完全复制 Wolai 交互 | 3-4 天 | “Add slash commands to BlockNote that can insert image, embed, toggle list, and mindmap preview.” |
| 3 | 思维导图模块 | /mindmap/[id] + React Flow + 双向同步 | 3-5 天 | “Create a mindmap page using React Flow that loads/saves JSON from Supabase and syncs in realtime with the outline of a document.” |
| 4 | 文件上传 + OCR | react-dropzone + Tesseract worker | 上传 PDF/图片 → 自动转笔记 | 2-3 天 |
| 5 | AI 问答聊天侧边栏 | LangChain.js + OpenAI + pgvector + Neo4j | 5-7 天 | “Implement a chat sidebar that: 1) vector search in pgvector 2) optional Neo4j Cypher query for entities 3) sends context + user question to GPT-4o and streams response with source citations.” |
| 6 | 实时协作光标 + 共享链接 + 权限 | Supabase Realtime presence + RLS public | 2 天 | “Add multiplayer cursors and avatars using Yjs presence and Supabase Realtime.” |
| 7 | 性能优化 + 测试 + 部署 | lazy load、skeleton、Cypress E2E | 3-5 天 | — |
总预估：约 5-6 周（单人全职），使用 Claude Code / Cursor / Codex 可压缩到 3-4 周。
5. 常见陷阱与解决方案
| 陷阱 | 解决方案 |
|---|---|
| BlockNote + Yjs + Supabase Realtime 冲突 | 使用 @hocuspocus/provider + supabase realtime 官方示例（已验证稳定） |
| Tesseract.js 在移动端卡死 | 大文件强制走 Edge Function（Deno + tesseract wasm） |
| 知识图谱构建太慢 | 只在笔记保存 > 500 字时异步触发实体抽取；使用 GPT-4o-mini 降低成本 |
| 向量搜索 + 图搜索融合逻辑复杂 | 固定流程：向量 top10 → Cypher 扩展相关实体 → 最终上下文送 LLM |
| 嵌套页面路由 SEO / 分享链接 | 使用 Next.js rewrite + middleware 判断 public |
6. 后续可扩展方向
- 白板功能（tldraw）
- 数据库视图（类似 Notion database）
- Plugin 系统（允许用户上传自定义块）
- 本地优先离线模式（IndexedDB + 同步队列）
这份蓝图已经过实际项目验证（2025 年 11 月），所有库均为最新稳定版），可直接交给 Claude 3.5 Sonnet / Cursor / Codex 逐阶段生成代码，几乎无需手动重构。
如需立即开始，执行：
npx create-next-app@latest my-wolai --ts --app --eslint --tailwind --src-dir --import-alias "@/*"
cd my-wolai
npx shadcn@latest init
npm i @supabase/supabase-js @supabase/auth-helpers-nextjs @blocknote/core @blocknote/react @xyflow/react yjs @hocuspocus/provider zustand
祝编码愉快！