全本地 RAG 桌面应用 · 答案可追溯 · 隐私优先 · 轻量
English | 简体中文
piFlow 是一款检索增强生成（RAG）桌面应用：导入本地文档构建知识库，然后用自然语言提问。解析、嵌入、检索、推理全部在你的机器上（或你指定的服务器上）运行——文档与对话始终不离开你的掌控。生成的答案附带来源引用，可追溯到具体的文档与段落。
主对话由 piFlow Agent（Pi harness）驱动：知识库以 Skill / Tools（kb_*
）挂载，并可选用 Postgres 只读与本地文件 Skill。
UI 设计预览：docs/index.png
答案可追溯：每条答案都附带引用与原文摘录，可点击定位到源文档和具体片段——让幻觉无所遁形隐私优先：文档、向量索引、聊天记录都存储在本地 SQLite 数据库中，无任何云端依赖目录级导入：选择目录即可递归导入，后台任务静默执行，活动日志实时显示进度智能检索流水线（reRAG）：意图模板路由 → LLM 生成结构化检索计划 → 多路密集检索按意图动态 top-K 合并，并支持多轮共指消解多格式解析：PDF（pdf-oxide / mupdf）、Markdown、TXT、HTML；扫描版 PDF 自动路由到 PaddleOCR可插拔生成后端：本地 GGUF 推理（node-llama-cpp）、远程 Ollama（如局域网 GPU 服务器）、或 DeepSeek / Pleias-RAG-1B自动模型管理：基于清单的模型注册表；缺失模型自动从 hf-mirror.com 镜像下载，并支持强制重新下载** piFlow Agent**：主对话入口；可开关的 Knowledge RAG / Postgres 只读 / 本地文件 Skill（Pi harness + SSE）
采用 Tauri 2 + Node Sidecar 双进程设计：Tauri 仅作为薄 UI 外壳，所有 RAG 推理与原生模块运行在独立的 Node 进程中。前后端通过 localhost HTTP / SSE 通信。
┌────────────────────────────────────────────────────┐
│ Tauri WebView (React + TypeScript) │
│ 知识库 · piFlow（主对话）· 引用 · 设置 │
└──────────────────────┬─────────────────────────────┘
│ HTTP / SSE (localhost)
┌──────────────────────▼─────────────────────────────┐
│ Node Sidecar (apps/rag-server) │
│ │
│ RAG：导入 → 解析 → 分块 → BGE-M3 → 检索 → 生成 │
│ piFlow：Pi Agent + Skills（KB / Postgres / FS） │
│ │
│ SQLite · pg-actions · 模型缓存 · 文件 │
└─────────────────────────────────────────────────────┘
便携版用户数据目录：%APPDATA%\piFlow\
（开发态默认为仓库内 .data\
）。
完整设计文档见 docs/architecture.md（English）、docs/piflow.md 与 docs/reRAG.md。
| 层级 | 技术 |
|---|---|
| 桌面外壳 | Tauri 2（Rust 仅负责窗口与 sidecar 生命周期） |
| 前端 | React 19 + TypeScript + Vite |
| RAG 后端 | Node.js + Hono（HTTP / SSE） |
| 嵌入 | BGE-M3（Xenova ONNX，@huggingface/transformers ，worker 线程） |
| 生成 | Qwen2.5-3B-Instruct GGUF（node-llama-cpp）/ Ollama / DeepSeek / Pleias-RAG-1B |
| 存储 | better-sqlite3（元数据 + 向量，余弦相似度检索） |
| 解析 | pdf-oxide · mupdf · PaddleOCR（扫描文档） |
| 包管理 | pnpm workspaces（monorepo） |
前置条件：Node.js ≥ 20、pnpm 10。请将仓库放在 Linux 文件系统（~/
）下，而非 /mnt/c/
。
pnpm install
cp .env.example .env # 按需调整
export HF_ENDPOINT=https://hf-mirror.com
pnpm models:ensure
pnpm dev:server
pnpm dev:ui
pnpm dev
模型注册表：models/manifest.json；详情：models/README.md。
| 用途 | 模型 | 大小 |
|---|---|---|
| 嵌入 | Xenova/bge-m3（ONNX fp16） | ~1.1 GB |
| 本地生成 | Qwen2.5-3B-Instruct GGUF（q4_k_m） | ~2 GB |
| 生成（可选） | Pleias-RAG-1B GGUF | ~2.4 GB |
| OCR | PaddleOCR | 随包附带 |
推荐配置：16 GB 内存、10 GB 可用磁盘空间。
关键环境变量（完整列表见 .env.example）：
| 变量 | 说明 |
|---|---|
HF_ENDPOINT |
|
Hugging Face 镜像，默认 https://hf-mirror.com |
|
BLUELAMP_RAG_PORT |
|
RAG 服务端口，默认 3847 |
|
BLUELAMP_MODELS_DIR |
|
模型目录，默认仓库内 models/ |
|
BLUELAMP_DATA_DIR |
|
数据目录；未设置时开发态用仓库 .data/ ，打包版由壳注入 %APPDATA%\piFlow\ |
|
BLUELAMP_USE_LOCAL_LLM |
|
设为 true 启用本地 GGUF 生成（无需 Ollama） |
|
BLUELAMP_OLLAMA_URL / BLUELAMP_OLLAMA_MODEL |
|
| 远程 Ollama 端点与模型 |
请在 Windows 本机打包（不要只在 WSL 里打 Windows 包）。因内嵌 BGE-M3 体积很大，产物是便携目录 + zip，不是 NSIS/MSI。
- Node.js ≥ 20、pnpm 10、Git
- Rust（
x86_64-pc-windows-msvc
）+ Visual Studio Build Tools（C++ 桌面开发） - WebView2 Runtime（Win10/11 通常已有）
- 已下载嵌入模型：
pnpm models:ensure
（需本机 BGE-M3）
完整清单见 docs/development-windows.md。
在仓库根目录（PowerShell）：
pnpm install
$env:HF_ENDPOINT="https://hf-mirror.com"
pnpm models:ensure
pnpm build:windows
pnpm build:windows
依次会：
bundle:windows-sidecar
— 打包 Node runtime、rag-server
、模型等到 Tauri resourcestauri build --no-bundle
— 编译piFlow.exe
package:windows-portable
— 组装便携目录并打 zip
| 路径 | 说明 |
|---|---|
dist-windows/piFlow/ |
|
| 可直接运行的文件夹 | |
dist-windows/piFlow-<version>-portable.zip |
|
| 同上内容的压缩包 |
解压后运行 ** piFlow.exe**。首次启动会把后端解压到
%APPDATA%\piFlow\sidecar\
；用户数据 / 数据库 / 日志也在 %APPDATA%\piFlow\
。LLM 在 Settings 中配置 Ollama 或 DeepSeek；未配置时仍可导入与检索。
apps/desktop/ Tauri + React 桌面 UI
apps/rag-server/ Node HTTP 服务（RAG + piFlow，Hono）
packages/core/ 共享类型、分块器与 RAG 核心逻辑
packages/pg-actions/ piFlow Postgres 只读 tools
models/ 模型清单与本地缓存
scripts/ 模型下载与服务管理脚本
docs/ 架构文档、用户手册与 ADR
架构设计（English）— 系统设计、模块划分、平台策略piFlow 设计— Agent / Skill / SSE / 信息源策略用户手册（中文）— 安装、RAG、piFlow、设置与 FAQreRAG：结构化预检索规划— 模板路由 + 检索规划流水线检索质量升级— 混合检索与 RRF 融合（提案）知识库目录导入WSL 开发指南Windows 编译与运行清单- ADR： 001 Tauri + Sidecar·002 文档解析·003 模型管理·004 WSL 开发 / Windows 发布
阶段 1 — MVP（进行中）：monorepo 脚手架、RAG sidecar、文档导入、带引用的聊天、模型管理；Windows 便携包（pnpm build:windows
）阶段 2 — 体验：Docling 处理复杂文档、混合检索（BM25 + dense RRF）、模型下载 UI、推理轨迹可视化阶段 3 — Windows 增强：安装包体积优化、可选 OCR、CUDA 检测阶段 4 — 进阶：多个隔离的知识库、多轮上下文管理、可插拔文档源