mnote/design/local-first-desktop-client.md

本地优先（Local-first）Win 客户端改造方案（不依赖客户端 Docker）

1. 背景与目标

你已明确选择“方案 2”：以 丝滑体验 为第一优先级，把主要交互（新建/删除/打开/编辑/附件管理/文件树）尽可能做成 本地零延迟；在线能力只承担 多设备同步、鉴权、RAG/OCR 结果回传 等“不需要即时展示”的部分。

同时你希望：

• Windows 客户端可打包分发（家人/同事无需安装 Docker）
• 后续可扩展：安卓端可以继续使用网页版（或再做安卓壳/客户端）
• 现有服务端栈（Supabase/LightRAG/Redis/MinerU/OnlyOffice）在需要时仍可使用，但不强制落到每个客户端

2. 现状盘点（基于当前仓库）

• 当前仓库根目录的 pnpm run desktop / pnpm run desktop:hot 本质是“一键启动脚本”，会启动：
  • wolai-frontend（Next.js）
  • wolai-backend（FastAPI）
  • services/ingest_service（自动入库/清理/触发）
  • services/rag_gateway（RAG 查询网关）
• 这不是可分发的“桌面客户端”：仍依赖 Node/Python 环境、端口服务、配置文件，且前端资源与 API 仍走 HTTP。

结论：要实现你要的“丝滑 + 易安装”，需要把“桌面壳 + 本地数据层 + 后台任务/同步”做成独立产品形态，而不是继续依赖 Cloudflare 反代公网访问。

3. 推荐总体架构（分层 + 可演进）

3.1 角色划分

A. 桌面客户端（Windows，主力）

• UI：本地窗口（WebView/Electron）加载本地页面（不经公网）
• 本地数据层：本地数据库（建议 SQLite）+ 本地文件目录（附件/导入文件）
• 本地任务队列：后台线程/进程异步执行（避免 UI 卡顿）
• 网络：只做“同步/索引请求/鉴权”，且尽量后台化

B. 家庭/办公室“轻服务端”（可选，但强烈建议）

你目前已有 Docker 相关服务，更适合放到一台“常开机器”（NAS/迷你主机/家用服务器）上，而不是每个客户端：

• Supabase（鉴权/同步/共享数据/存储桶/pgvector）
• Redis（队列/后台任务）
• LightRAG（入库/检索）
• MinerU（OCR）
• OnlyOffice Document Server（如仍需要网页内编辑 Office）

C. 公网访问（可选）

• 安卓端/外网访问时，继续使用网页版（可走 Cloudflare、或 VPN/IPv6）
• 但桌面端的“主要交互体验”不再依赖公网链路

3.2 本地优先的数据归属

核心原则：“能本地完成的操作，绝不阻塞在网络请求上。”

• 文档/思维导图的“当前版本内容”：本地可用（SQLite + 文件）
• 附件文件本体：本地可用（本地目录），需要时再同步/上传
• 远端（Supabase）只承担：
  • 多设备同步与共享（最终一致）
  • RAG/OCR 的产物存储与检索
  • 登录鉴权（如你希望跨设备一致账号体系）

4. 技术路线：桌面壳怎么做（不跑 Docker）

你现在的前端是 Next.js（含 Server Components + API Routes），要做桌面客户端通常有两条路线：

路线 1（推荐落地优先）：桌面壳 + 本地 HTTP（保持现有 Next/FastAPI）

• 桌面壳：Tauri 2 或 Electron（两者都能）
• 客户端启动时：
  1. 启动本机 wolai-frontend（生产模式）到 127.0.0.1:3000
  2. 启动本机 wolai-backend（或逐步把关键 API 收敛到一个本地服务）
  3. 桌面壳打开 http://127.0.0.1:3000（同源、零公网）

优点：

• 改造小：最大复用当前 Next/FastAPI
• 体验立刻提升：不再经过 Cloudflare/Tunnel

缺点：

• “安装体积/依赖”需要进一步工程化（见第 8 节分阶段）

路线 2（长期更优雅）：本地壳 + 静态前端 + 本地 API（逐步去 Next Server 依赖）

• 把前端逐步改成更“纯前端”的形态（或迁 Vite/React SPA）
• 本地 API 用一个可打包的二进制提供（Rust/Go）+ SQLite

优点：

• 最终安装最轻、启动更快、可控性最好

缺点：

• 改造量大，不建议作为第一阶段目标

建议决策：先走“路线 1”把体验做顺，再按收益逐步往“路线 2”靠拢。

5. “丝滑”的关键：本地任务队列 + 最终一致同步

5.1 本地操作必须立刻返回

把下列操作改为“本地先完成，后台再同步”：

• 新建/重命名/移动/删除（进入回收站）
• 打开文档（本地读）
• 编辑器保存（本地落盘 + 去抖）
• 附件导入（本地复制到附件目录，立即可用）

5.2 同步模型（建议：Oplog/变更日志）

为避免“每次都全量上传大字段”导致卡顿，建议本地维护一个 oplog：

• 每个操作写入：op_id、entity_type、entity_id、op_type、payload、created_at、synced_at
• 后台同步器按顺序上传到 Supabase（或服务端）
• 冲突策略（第一阶段先简单）：
  • 同一文档若出现冲突：保留双方版本（生成“冲突副本”），避免覆盖丢数据

5.3 建议的本地 SQLite 最小表结构（用于落地与排期）

目标：先把“本地秒开 + 不依赖网络”的体验做出来；同步与协作逐步增强。

• local_documents
  • id（uuid）、parent_id、title、content_json（或文件路径）、updated_at、deleted_at
• local_media_assets
  • id、document_id、file_path、mime、sha256、size、created_at、deleted_at
• local_mindmaps
  • id、document_id（可选）、data_json、updated_at、deleted_at
• local_trash_jobs
  • entity_type、entity_id、purge_after（时间戳）、canceled_at
• local_oplog
  • op_id、entity_type、entity_id、op_type、payload_json、created_at、synced_at、retry_count
• local_sync_state
  • remote_cursor（用于增量拉取）、last_pull_at、last_push_at

5.4 与当前 Supabase 表的映射（基于 supabase_local 现有表）

你当前 Supabase（public schema）已经有这些关键表：documents、media_assets、mindmap_meta/mindmap_nodes、rag_index_sources、lightrag_*、document_embeddings 等。

建议映射策略（第一阶段）：

• 本地 local_documents <-> 远端 public.documents
  • 远端作为“同步与共享的汇聚层”，本地为“即时交互层”
• 本地 local_media_assets <-> 远端 public.media_assets + storage.objects
  • 远端文件本体尽量走 Storage（签名 URL/直传），避免经 API 中转
• 思维导图：本地 local_mindmaps <-> 远端 mindmap_meta/mindmap_nodes
  • 目前“思维导图删除后垃圾桶没有出现”，本质是缺少统一的 deleted_at 与回收站视图
  • 建议把 mindmap 也纳入统一软删体系（与 documents/media_assets 同标准）

6. 回收站 + 延迟删除（解决误删与垃圾堆积）

你提出的需求非常关键：误删后 Ctrl+Z 可恢复，所以“删文件”不应立即删 OCR/RAG 资源。

建议统一成两段式删除：

1. 软删（立刻）：进入回收站

   • 本地：移动到 .trash/（或打标 deleted_at），UI 可见
   • 服务端：对应记录打 deleted_at（不做物理删除）

2. 延迟清理（例如 10 分钟后）：后台任务执行硬删除

   • 若用户在延迟窗口内恢复：取消清理任务
   • 手动“清空垃圾桶”：触发立即清理（仍建议带二次确认）

注意：你现有的报错 rag_index_sources 外键约束，说明服务端“删除顺序/级联规则”需要统一：

• 设计层面建议：对 RAG 相关表引入 ON DELETE CASCADE 或“先删子表再删父表”的硬规则
• 实现层面建议：垃圾桶清理走同一个 purge 流程，确保顺序一致

基于你当前的约束信息：rag_index_sources_document_id_fkey 的 ON DELETE 是 NO ACTION（也就是不会级联删除），因此“清空垃圾桶”若直接删 documents 就必然触发外键错误。这里推荐两条修复路径（二选一）：

1. 保留外键 NO ACTION：清理时严格按顺序删除子表（例如先删 rag_index_sources、再删 documents）
2. 改为 ON DELETE CASCADE：允许删除 documents 时自动清理 rag_index_sources（更省心，但要确认不会误删共享/审计数据）

7. RAG/OCR（MinerU）在本地优先架构中的位置

你的期望是：客户端体验优先，OCR/RAG 可以后台慢慢做。因此推荐：

• 客户端只负责触发与展示结果（不在客户端跑 Docker）
• OCR/RAG 在“轻服务端”执行（可继续用你现有 Docker/服务）

7.1 触发策略（建议）

当本地文件发生变化（导入/更新）：

• 计算 content_hash（用于去重与增量）
• 将任务写入本地队列（或远端队列）
• 后台上传文件到服务端（或 Supabase Storage）
• 服务端按文件类型处理：
  • PDF/图片型 PDF：MinerU OCR -> 结构化文本
  • docx/pptx/xlsx：提取文本（必要时转 pdf 再 OCR）
  • 图片：OCR + 元数据
• 最终写入：标准化 chunk + embedding + 元数据（Supabase/pgvector）

7.2 Embedding 建议（中英混合 + 化学语料，尽量免费）

优先推荐“可自托管/本地跑”的 embedding（服务端跑即可）：

• bge-m3：多语种通用表现稳定，适合中英混合
• multilingual-e5-large（或同系）：检索向 embedding 生态成熟
• 你现有 Ollama 方案里预拉的 qwen3-embedding:8b：可作为可用基线（但模型较大，CPU 可能慢，建议服务端有 GPU 或更强 CPU）

第一阶段建议先选 1 个跑通“自动入库闭环”，再用你提供的化学书籍片段做小规模对比评测（Recall@k + 人工判读）。

7.3 任务编排建议（复用现有 Supabase 表）

你当前 Supabase 已有两张非常适合做“可观测后台任务”的表：

• public.rag_index_sources：有 status/attempts/last_error/source_updated_at/last_enqueued_at/last_processed_at
• public.background_tasks：有 task_type/status/progress/message/updated_at

建议用法：

1. 入库入口统一：任何“需要入库/重建索引”的源（documents/media_assets/mindmap/ocr_text）都落一条 rag_index_sources
2. 执行过程可视化：真正跑 OCR/切块/embedding/入库时，同步写 background_tasks（用于前端显示进度条/日志）
3. 幂等与去重：
   • 用 source_updated_at + content_hash（可在 payload 里存）判断是否需要重跑
   • 同一 source_id 新任务到来时，若已有 RUNNING 则只更新 last_enqueued_at，避免并发重复跑

7.4 OCR 决策（PDF 有文本 vs 图片型 PDF）

针对你提供的两类测试 PDF（“已 OCR 过含文本”与“图片型 PDF”），建议服务端在入库前做一个轻量判断：

• 先尝试“抽取文本”（例如每页抽样、统计可抽取字符数）
• 若字符数/覆盖率低于阈值，再走 MinerU OCR
• OCR 产物建议保留：
  • raw_text（纯文本，用于检索）
  • layout（段落/页码/坐标等，用于引用定位与高亮）

这样可以避免对“本来就有文本层的 PDF”重复 OCR，节省大量时间。

7.5 LightRAG 版本对齐（你提到的 v1.4.9.10）

当前仓库内的 LightRAG 代码与其自带虚拟环境显示版本为 1.4.9.9（LightRAG/lightrag/__init__.py 与 LightRAG/.venv 一致）。

建议策略：

• 先稳：在“本地优先客户端”主线落地前，LightRAG 不做大范围升级，避免把变量叠加到体验问题上
• 再对齐：单独开一个“LightRAG 升级分支计划”（仅改 LightRAG 目录/服务启动脚本/兼容性），升级到你说的 v1.4.9.10 后，用你提供的两份测试 PDF 跑一遍入库回归（含 OCR 分支）

8. 分阶段落地路线（建议按收益/难度）

P0（最小可用，立刻变丝滑）

• 明确“桌面端默认走本机”：127.0.0.1 / 局域网 IP
• 桌面端不经过 Cloudflare（Cloudflare 仅保留给“手机/外网”）
• 这一步不解决“安装依赖”，但先把“体验问题”排除在公网链路之外

P1（可分发 Win 客户端：无需 Docker）

目标：家人/同事拿到安装包即可用（最多只安装一次 VC 运行库/WebView2）。

• 引入桌面壳（Tauri 或 Electron）
• 把必要服务以“sidecar”方式随客户端分发并由壳统一拉起/关闭：
  • Next 前端（建议 next standalone 输出 + 内置 Node）
  • 后端 API（优先收敛成一个本地服务；Python 可先保留，后续再二进制化）
• 本地数据层落地：SQLite + 本地文件目录

P2（减少依赖与体积）

• Python 服务逐步二进制化（PyInstaller/Nuitka 或重写关键路径为 Rust/Go）
• 能迁到本地 API 的 Next app/api/* 逐步迁移，减少 Next server 负担

P3（多端）

• 安卓端继续用网页版（外网可用 VPN/IPv6/Cloudflare 其一）
• 桌面端与网页版共享同一套“同步协议/数据模型”，但桌面端以本地为主

9. 你需要做的关键取舍（我建议的默认值）

1. OnlyOffice 的定位

• 如果你追求“打开速度极致”：Windows 客户端对 docx/xlsx/pptx 优先“用本机 Office/OnlyOffice Desktop 打开”，应用内只做预览/管理/版本
• OnlyOffice Document Server 保留给：手机端/外网网页端

2. 服务端部署位置

• 若你有一台常开机器：把 Supabase/LightRAG/MinerU/Redis/OnlyOffice 放到 LAN 里，桌面端访问延迟会非常低
• 外网访问建议优先 VPN（你是小范围用户），避免 Cloudflare 造成的不可控绕路

10. 下一步我建议你先确认的 5 个问题（确认后我再给出更“可执行”的工程拆分）

1. Windows 客户端你更偏好：Tauri（小体积）还是 Electron（生态成熟）？
2. 你是否接受“第一阶段仍需要安装 Node/Python”，还是必须“一键安装无运行时依赖”？
3. 你希望本地数据目录放哪：%USERPROFILE%\\Documents\\MNOTE 还是跟仓库同级？
4. 多人同时编辑是否重要？（决定是否引入 Yjs 协作服务端/冲突策略）
5. 你的“轻服务端”准备放在哪台机器（家用主机/NAS/云服务器）？

11. 你已确认的项目决策（已记录，后续按此推进）

你已明确选择：

1. 桌面壳：Electron
2. 依赖：可以安装任何东西，但希望“安装后即可启动客户端”（减少手工配置）
3. 本地数据：放在安装目录（用户上传文件先落到该目录，再与远程 Supabase 同步）
4. 协作：暂不做多人同时编辑
5. 轻服务端：当前家用主机（先这样）

11.1 关键风险提醒：Windows 的“安装目录”通常不可写

如果你用的是常见的安装方式（MSI/NSIS 默认装到 C:\\Program Files\\...），Windows 会对普通用户进程启用 UAC/权限限制，安装目录默认不可写，会导致：

• 上传文件/本地数据库写入失败或变成“时好时坏”
• 需要管理员权限运行（体验差、也不安全）

你已进一步明确：标准安装，但安装位置必须可选且尽量不在 C 盘（数据会越来越大）。

这里的关键点不在“C 盘 vs 非 C 盘”，而在“是否安装在受保护目录（如 Program Files）”。即使装到 D:\\Program Files\\...，也可能同样不可写。

为满足“标准安装 + 数据放安装目录 + 不在 C 盘”，我建议按下面规则实现（作为默认方案）：

• 安装路径强约束：安装器允许用户自选安装目录，但禁止选择 C 盘，并且默认推荐路径形如 D:\\Apps\\MNOTE（而不是 D:\\Program Files\\...）。
• 数据目录固定在安装目录内：例如 D:\\Apps\\MNOTE\\data（满足“数据跟安装目录走”）。
• 安装时设置 data 目录 ACL：安装器在安装阶段为 data 目录授予当前用户（或 Users 组）可写权限，避免运行时写入失败。

如果你希望“强制必须装到非 C 盘”，这是可做的；但如果同事机器没有 D 盘，也需要允许选择 E/F 等其它盘符。

结论：你不需要做“绿色版”，也不需要把数据放到 userData；但必须在安装器层面把“安装目录可写”这件事做成默认成立。

12. Electron 客户端落地方案（不让客户端跑 Docker）

12.1 本地优先的最小形态（推荐作为第一阶段实现）

Electron 只做三件事：

• 提供 UI（窗口内渲染网页）
• 提供本地数据目录与 SQLite（零延迟读写）
• 后台做“同步/上传/触发服务端入库”（不阻塞 UI）

客户端不运行 Docker，也不强制在客户端跑 LightRAG / MinerU / Supabase。

12.2 与现有代码的衔接方式（尽量少改，先跑通）

第一阶段建议继续复用你现有的 HTTP 形态，但把链路从“公网 Cloudflare”改为“本机/局域网”：

• Electron 启动时拉起本机服务（作为 sidecar）：
  • wolai-frontend：Next production（本机 127.0.0.1:3000）
  • wolai-backend：FastAPI（本机 127.0.0.1:8000）
• Electron 窗口直接打开 http://127.0.0.1:3000

这样 UI 完全不走公网，页面切换/打开文档会立刻变“本地速度”。

说明：你仓库根目录的 pnpm run desktop 目前更像“开发者一键启动”；后续我们会新增专用的“Electron sidecar 启动器”，把端口探测、日志、崩溃重启、退出清理做成稳定产品级行为。

12.3 依赖与打包策略（让“安装后可启动”）

你允许安装任何东西，但希望安装后可启动。我建议用“两阶段”逐步降低门槛：

阶段 1（最快落地）

• 安装前置：Node、Python（以及必要的 VC 运行库、WebView2）
• Electron installer 在首次启动时做自检（缺什么就引导安装）

阶段 2（更像产品）

• 把后端打成单文件/少量文件的可执行程序（PyInstaller/Nuitka）
• 把前端打成 Next standalone（或更进一步变成静态 + 本地 API）
• Electron 安装包内置所有运行时（用户无需额外安装 Node/Python）

13. 轻服务端（家用主机）承担什么

鉴于你暂时不做多人实时协作，且优先“本地丝滑”，建议家用主机只承担：

• Supabase：鉴权 + 多端同步汇聚层 + Storage + pgvector
• ingest_service：监听/轮询需要入库的源（rag_index_sources），做切块/embedding/入库
• MinerU：OCR 工作负载（图片/图片型 PDF）
• LightRAG：统一入库/检索（或作为 ingest_service 内部依赖）
• Redis：任务队列/限流（可选）
• OnlyOffice Document Server：主要给“网页/手机端”使用；Windows 客户端可优先走本机 Office/OnlyOffice Desktop 提升打开速度

14. 下一步里程碑（可直接开工的任务清单）

M0：确定安装与数据目录规则（必须先定）

• 标准安装（NSIS/MSI），允许用户选择安装路径
• 默认路径推荐 D:\\Apps\\MNOTE
• 禁止安装到 C 盘（可配置为硬限制或安装器强提示）
• 数据目录固定为 $INSTDIR\\data 并在安装时设置写权限

M1：Electron 外壳 + 本机服务启动（体验立竿见影）

• 新增 electron-app/（主进程 + 渲染进程）
• 主进程实现：
  • 启动前端（Next production）到 127.0.0.1:3000
  • 启动后端（FastAPI）到 127.0.0.1:8000
  • 进程托管：崩溃重启、退出清理、日志落盘（UTF-8）
• 渲染进程直接加载 http://127.0.0.1:3000

M2：本地数据目录与 SQLite（真正 local-first）

• 选定数据根目录（绿色版：./data；标准版：userData）
• 引入 SQLite（文档/附件索引/oplog/回收站任务）
• 把“创建/删除/打开”的关键路径改为本地优先（网络失败也能操作）

M3：同步（最终一致）

• 本地 local_oplog 推送到 Supabase
• 从 Supabase 拉取增量变更，更新本地 SQLite
• 冲突先采用“生成冲突副本”的保守策略

M4：入库/OCR 后台化（不阻塞 UI）

• 客户端只负责：上传文件 + 写 rag_index_sources（或触发 API）
• 家用主机跑 ingest_service/MinerU/LightRAG 完成入库
• 客户端订阅/轮询 background_tasks 显示进度（可选）