总体架构
Molore是一个本地优先的个人 AI 知识库：数据默认留在用户自己的机器上，AI 能力按「本地免费 / 自带 key 自付 / 平台按量」三条通道硬分流供给。整套系统由 FastAPI 后端、React 19 前端、Electron 桌面端（内嵌 PyInstaller sidecar 后端）和浏览器剪藏扩展组成，同一份后端代码以桌面 sidecar、Docker、云服务器三种形态部署。本页给出全局分层视图，后续各页逐层展开。
分层视图
| 层 | 组件 | 技术 | 职责 |
|---|---|---|---|
| 交互层 | Web 前端 | React 19 SPA，Vite 构建 | 笔记、剪藏、问答、图谱、wiki、设置等全部界面 |
| 交互层 | 桌面端 | Electron + 内嵌 PyInstaller sidecar | 本地跑完整后端，数据落 %APPDATA%\psb-desktop\data\，托盘常驻、全局热键、自动更新 |
| 交互层 | 剪藏扩展 | 浏览器扩展 | 网页剪藏直传后端 clips 接口 |
| API 层 | REST API | FastAPI，app/api/v1/endpoints/ | 40+ 端点模块按域拆分；启动编排走 app/core/startup.py 钩子注册表 |
| 服务层 | 领域服务 | app/services/ | 检索、打标、图谱、wiki、同步、计费等业务逻辑 |
| 数据层 | 单库三索引 | SQLite + sqlite-vec + FTS5 | 关系数据、1024 维向量、BM25 全文倒排共库（backend/data/psb.db） |
| 模型层 | 三通道 LLM | 本地 Ollama / BYOK / 平台按量 | 对话、嵌入、自动打标、复盘等全部模型调用 |
各层要点
- 交互层：三种客户端打同一套
/api/v1接口。桌面端与网页版的差别只在进程模型（sidecar 本地起后端）和付费入口（桌面端无本地平台计费，平台模型走cloud-proxy云端转发，系统行 rewrite 为platform:前缀通道）。 - API 层：
app/main.py只有 261 行，负责中间件、路由挂载和 lifespan 骨架；启动顺序固定为「schema 迁移 → 数据播种 → 启动钩子注册表」，注册表见app/core/startup.py的STARTUP_HOOKS（23 个钩子，含图谱、打标、向量、FTS、各类调度器）。 - 服务层：
app/services/按域组织——retrieval检索问答、autotag_service自动打标、graphify_service图谱、wiki_service百科、llm_service模型执行与通道、sync_*云同步、billing_*计费。巨型文件一律按「包 + façade 再导出」拆分子包，对外接口零破坏（详见后端设计）。 - 数据层：一个 SQLite 文件承载全部数据。向量走 sqlite-vec 影子索引（bge-m3，统一 1024 维），全文走 FTS5 虚拟表 + 触发器，两路索引与内容表同事务维护。个人与团队内容同库，隔离在查询侧收口。
- 模型层：三条通道硬分流、互不兜底，通道判定、默认模型、回退策略、自动链路门禁的唯一事实源是
app/services/llm_service/channel_policy.py：
| 通道 | 形态 | 计费 | 典型用途 |
|---|---|---|---|
本地（local） | Ollama，默认 qwen3.5:0.8b + bge-m3 | 零成本 | 自动打标、复盘周报、查询改写等自动链路；免费用户对话 |
BYOK（byok） | 用户自带厂商 key，0 价非系统目录行 | 用户自付 | Pro 用户自选模型对话 |
平台按量（platform） | sys- 前缀系统行，默认 sys-glm-5.3-flash | 云端余额扣费，不足 402 | 无本地模型时的云端强模型 |
双空间：个人与团队
系统同时支持个人空间与团队租户，两类数据全链路隔离：租户上下文贯穿内容、标签、图谱、wiki、检索与计费，图谱构建状态用复合主键 (user_id, tenant_id)（个人空间以空串占位），会话始终为创建者私有。向量层个人与团队内容都进，隔离在检索侧内容行收口；语义加工层（图谱/wiki/打标/复盘）另受 index_only 仓库模式门禁过滤（见内容入库）。
部署形态
| 形态 | 进程模型 | 数据位置 | 适用 |
|---|---|---|---|
| 桌面 sidecar | Electron 拉起 PyInstaller 冻结后端（约 693MB，含 OCR 全家桶） | %APPDATA%\psb-desktop\data\ | 个人本地使用，默认形态 |
| Docker | 容器内 uvicorn | 挂载卷 | 自托管（见自托管指南） |
| 云服务器 | nginx 443 → uvicorn（pm2 守护，内存帽 1400M） | backend/data/psb.db | 官方云端 grzhishiku.com |
三种形态跑同一份 backend/app 代码，行为差异全部由环境变量驱动（ENV、PSB_DESKTOP、DATABASE_URL、SERVE_FRONTEND_DIR 等）。
下一步
- FastAPI 后端设计 —— 启动编排、目录结构、迁移与播种、通道策略
- 内容入库流程 —— 四类内容如何进入检索层与语义加工层
- 检索问答全流程 —— 召回、融合、装配、生成与证据边界
- 异步任务与定时调度 —— 防抖自进化、兜底扫描、复盘周报
- 快速开始 —— 用户视角的上手路径