# localvault-workspace

**Repository Path**: codernight_m/localvault-workspace

## Basic Information

- **Project Name**: localvault-workspace
- **Description**: LocalVault — Windows 本地离线知识库桌面应用，支持 PDF、Office、Markdown 文档导入，AI semantic search 与 keyword hybrid search。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# LocalVault

<p align="center">
  <img src="assets/branding/localvault-logo.png" alt="LocalVault logo" width="96">
</p>

<p align="center"><strong>完全在本机运行的 Windows 知识库与混合检索桌面应用</strong></p>

LocalVault 将分散在电脑中的资料整理为可检索的本地知识空间。导入文档后，应用会在本机完成结构化解析、语义分片、向量索引与关键词检索；每条结果都能回到原始文档及其页码、行号、工作表或幻灯片位置。

适用于希望将产品文档、项目资料、岗位说明、研究笔记等内容留在本机，同时获得自然语言检索能力的 Windows 用户。

## 适用场景

- **项目资料库**：将需求、方案、会议纪要和技术文档放入同一知识空间，按问题、术语或编号检索。
- **团队知识沉淀**：保留文档原有的标题与来源位置，检索后可快速回到原文核对上下文。
- **个人离线资料库**：在不把原始资料发往云端的前提下，检索本机的笔记、手册和归档文件。
- **本机工具集成**：通过受 Scope 限制的回环 API，让本机脚本或工具按最小权限查询知识库。

![LocalVault 首页：选择知识库并搜索本地资料](output/playwright/dashboard-search-dropdown/space-menu-polished.png)

## 核心能力

| 能力 | 说明 |
| --- | --- |
| 本地优先 | 桌面端、Local Core、索引与检索均在本机运行；渲染层不直接接触文件系统、模型路径或服务凭据。 |
| 多格式导入 | 支持 TXT、Markdown、PDF、DOCX、XLSX 与 PPTX，可从文件或文件夹导入。 |
| 结构化分片 | 保留标题层级与来源定位；代码、表格、公式和主章节保持清晰边界。 |
| 混合检索 | 使用 BGE-M3 语义召回与 SQLite 词法召回，并通过 RRF 融合结果，兼顾自然语言、专有名词和编号。 |
| 结果可追溯 | 展示文档、标题路径、匹配片段及页码、行号、工作表或幻灯片等来源信息。 |
| 安全的本机 API | 可创建最小权限的 API Key，供本机工具按 Scope 读取检索或文档结果。 |

## 从文档到答案

1. **创建知识库并导入资料**：在桌面端建立独立的知识空间，按文件或文件夹选择资料。重复文件会被识别，导入状态会在界面中显示。
2. **解析并保留结构**：不同格式通过统一的解析接口进入分片流程；标题、段落、表格及原文定位会随分片保存。
3. **构建可发布的索引**：新版本索引会先完成校验，再切换为 active 视图。索引处理中，旧的可用视图会继续提供查询结果。
4. **混合检索并回到原文**：输入自然语言、关键词或编号后，系统融合语义和词法结果，并展示关联文档、标题路径、匹配片段与来源位置。

### 支持的文档格式

| 格式 | 主要保留的信息 | 常见来源定位 |
| --- | --- | --- |
| TXT / Markdown | 段落、标题层级、列表、代码围栏、表格 | 行号、标题路径 |
| PDF | 已有文本层 | 页码 |
| DOCX | 标题层级、段落、表格 | 段落号、表格号 |
| XLSX | 工作表、单元格内容、公式 | 工作表、单元格范围 |
| PPTX | 幻灯片标题、文本、表格 | 幻灯片序号 |

扫描版 PDF 目前只读取已有文本层，不执行 OCR；受密码保护、损坏或伪装扩展名的文件会在导入前被拒绝。

## 检索结果示例

搜索结果会同时展示语义召回、词法召回与 RRF 融合信息，并保留来源位置，便于快速核对答案上下文。

![LocalVault 搜索结果详情：相关度、检索排名与原文来源](output/playwright/dashboard-search-dropdown/search-result-detail-modal.png)

## 工作方式

```mermaid
flowchart LR
  A["本地文档<br/>TXT · PDF · Office · Markdown"] --> B[结构化解析与语义分片]
  B --> C[SQLite 元数据与来源定位]
  B --> D["BGE-M3 向量索引<br/>Qdrant"]
  C --> E[SQLite 词法召回]
  D --> F[语义召回]
  E --> G[RRF 融合]
  F --> G
  G --> H[桌面端结果与本机 API]
```

LocalVault 的 Electron 主进程负责受控地启动本地服务；Qdrant 仅在回环网络中作为 sidecar 运行，Renderer 通过白名单 IPC 获取必要的数据传输对象。这使界面、文件访问和运行时凭据保持隔离。

### 为什么同时使用语义与关键词检索？

- **语义召回**使用 BGE-M3 ONNX 在本机生成查询向量，适合"这份资料讲了什么"一类自然语言问题。
- **词法召回**使用 SQLite 的中文 n-gram、字母数字和编号 token 排名，适合精确的产品名、术语、型号与流程编号。
- **RRF 融合**按排名整合两路候选，而非直接混合不同量纲的原始分数；结果因此兼顾语义相关性和精确匹配。
- **来源回填**只从当前 active 文档与分片视图读取正文和定位信息，避免陈旧索引点、已删除文档或跨知识库结果进入页面。

## 快速开始

### 环境要求

- Windows 10/11 x64
- Node.js 24（`>=24 <25`）
- pnpm 11（`>=11 <12`）
- Python 3.12

### 安装依赖

```powershell
pnpm install
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".\apps\local_core[dev,packaging]"
```

如 Python 不在 `PATH`，启动前指定解释器：

```powershell
$env:LOCALVAULT_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe)
```

### 准备本地模型与运行时资产

首次在源码环境中使用 BGE-M3 与 Qdrant 前，需要下载并校验项目锁定的离线资产：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\fetch-phase3-assets.ps1
```

该命令只准备构建和验证所需的本地资产。模型清单会校验版本、文件大小和 SHA-256，避免在运行时静默下载或替换模型。

### 启动桌面端

```powershell
pnpm dev
```

首次使用时，在"知识库"中新建知识库并导入资料；待索引完成后，即可在"智能检索"中进行本地搜索。

### 验证构建

```powershell
pnpm test
pnpm build
```

常用开发命令：

| 命令 | 用途 |
| --- | --- |
| `pnpm dev` | 启动带热更新的桌面开发环境。 |
| `pnpm test` | 运行 Local Core 测试与桌面端契约测试。 |
| `pnpm typecheck` | 检查 Electron、Preload 与 Renderer 的 TypeScript 类型。 |
| `pnpm build` | 构建桌面端主进程和 Renderer。 |
| `pnpm dist:win` | 构建 Windows x64 NSIS 安装包；需先具备已校验的打包资产。 |

## 本机 API

LocalVault 运行时会在回环地址提供 HTTP API：`http://127.0.0.1:52598/api/v1`。它不是云端或局域网服务，只有桌面应用正常运行时才可用。

在"开放接口"页创建 API Key 后，可按最小权限为本机工具授予以下 Scope：

| Scope | 用途 |
| --- | --- |
| `search:read` | 列出知识库并执行混合检索。 |
| `document:read` | 读取文档列表和分片来源。 |
| `document:write` | 创建知识库及执行受控的文档管理操作。 |
| `status:read` | 读取本机服务健康状态。 |

所有请求使用 `Authorization: Bearer <API_KEY>` 鉴权。完整 Key 只在创建时显示一次；调用日志仅保留脱敏的请求元数据，不保存查询正文、响应正文或完整密钥。端点、参数与错误处理约定请参阅 [Phase 4 混合检索契约](docs/Phase4混合检索契约.md)。

## 项目结构

```
apps/
├─ desktop/                 Electron + React 桌面端
│  ├─ src/main/             生命周期、受控子进程与安全边界
│  ├─ src/preload/          白名单 IPC 桥接
│  └─ src/renderer/         知识库、检索与 API 设置界面
└─ local_core/              Python 本地服务
   ├─ src/localvault_core/  解析、分片、索引、检索与 HTTP API
   └─ tests/                Local Core 测试
assets/                     品牌、模型清单与许可证
docs/                       设计、索引与检索契约、评测集
scripts/                    构建、资产校验与评测脚本
```

### 核心模块说明

**桌面端 (`apps/desktop/`)**
- `src/main/`：主进程负责生命周期管理、受控子进程启动（Local Core、Qdrant sidecar）与安全边界维护
- `src/preload/`：白名单 IPC 桥接，定义安全的跨进程通信协议
- `src/renderer/`：React 知识库管理、混合检索界面与 API 设置页面

**本地核心服务 (`apps/local_core/src/localvault_core/`)**
- `parser_adapters.py`：统一解析接口，支持 TXT/Markdown/PDF/DOCX/XLSX/PPTX
- `semantic_chunker.py`：结构化分片，保留标题层级与来源定位
- `embedding_provider.py`：BGE-M3 ONNX 向量生成
- `retrieval.py`：混合检索（语义+词性）与 RRF 融合
- `index_publication.py`：索引发布与 active 视图切换
- `database.py`：SQLite 元数据存储与词法召回
- `qdrant_rest.py`：Qdrant 向量存储客户端
- `app.py`：FastAPI HTTP 服务与 API Key 鉴权

## 文档与开发入口

- [系统设计文档](docs/向量知识库系统设计文档.md)：产品范围、架构与安全边界。
- [Phase 3 模型与索引契约](docs/Phase3模型与索引契约.md)：模型、索引代际、发布与回滚约束。
- [Phase 4 混合检索契约](docs/Phase4混合检索契约.md)：检索、来源回填、评测和本机 API 约定。
- [检索评测集](docs/retrieval_eval/jd_hybrid_v1.json)：版本化的混合检索评测查询。
- [安全最佳实践报告](security_best_practices_report.md)：安全审计与修复状态。

## 安全说明

LocalVault 采用本地优先架构，所有敏感操作均在本地完成：

- **数据隔离**：桌面渲染层不直接接触文件系统、模型路径或服务凭据
- **API 鉴权**：本机 API 采用 Bearer Token 认证，支持细粒度 Scope 权限控制
- **进程隔离**：Local Core 与 Qdrant 通过受控子进程管理，Renderer 通过白名单 IPC 通信
- **索引原子切换**：采用 active 视图切换机制，确保索引更新异常时可恢复

详见 [安全最佳实践报告](security_best_practices_report.md)。

## 协议

- 本项目源代码遵循 [LICENSE](LICENSE) 中声明的开源协议
- 内置模型（BGE-M3）遵循其各自的开源协议，详见 [assets/licenses/](assets/licenses/)

## 说明

- LocalVault 是 Windows 桌面应用，不提供云端或局域网部署入口。
- 本机 API 默认只监听 `127.0.0.1:52598`；请按最小权限创建并妥善保存 API Key。
- 受管原文件和历史索引不会因普通文档删除而立刻物理清除；索引发布采用可校验的 active 视图切换，方便在异常时保留恢复空间。