# LocalWise

**Repository Path**: shi2015/local-wise

## Basic Information

- **Project Name**: LocalWise
- **Description**: LocalWise 是一款完全本地运行的桌面 AI 知识库助手。它像一个专属的智能秘书，帮你管理项目文件、回答问题、撰写文档、整理资料——而你的所有数据都留在你自己的电脑上，永远不会上传到任何服务器。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-29
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LocalWise 本地智囊

> **为每个项目打造专属智能体，数据不出户，形态由你定。**

<p align="center">
  <strong>把 AI 请进你的电脑，把数据留在你的硬盘。</strong>
</p>

---

## 是什么？

LocalWise 是一款**完全本地运行**的桌面 AI 知识库助手。它像一个专属的智能秘书，帮你管理项目文件、回答问题、撰写文档、整理资料——而你的所有数据都留在你自己的电脑上，永远不会上传到任何服务器。

## 六大核心能力

| # | 能力 | 说明 |
|:---:|:---|:---|
| 1 | **自由创建多形态智能体** | 为不同项目创建专属助手——问答助手、报告撰写员、代码审查员、顾问、导师……形态由你定义 |
| 2 | **每个智能体独一无二** | 自定义 System Prompt + 关联知识库 + 绑定不同模型，让每个智能体拥有独立的"人格"和"专业领域" |
| 3 | **数据永不外泄** | 所有知识库、对话记录、智能体配置全部存储在本地，彻底杜绝隐私泄露 |
| 4 | **智能体能干"体力活"** | AI 不仅能回答问题，还能调用 10 个文件管理工具（查找、读取、创建、修改、删除、移动、复制等） |
| 5 | **专业级编辑体验** | 内置 Monaco 编辑器（VS Code 同款），支持 20+ 种语法高亮 |
| 6 | **模型自由切换** | 云端模型（OpenAI/DeepSeek/智谱等）、本地模型（Ollama/GGUF），你的 AI 你做主 |

## 功能概览

### 项目管理
- 项目级隔离：每个项目独立的文件目录、知识库索引和对话历史
- 自动恢复上次项目，最近项目快速切换

### 知识库
- 内置 bge-small-zh-v1.5 向量模型，开箱即用
- 混合检索：向量语义 + BM25 关键词 + RRF 融合，兼顾语义理解和精确匹配
- 精准引用：提及文件名时直接读取全文，不丢失上下文
- 增量同步：基于 MD5 比对，只处理变化的文件
- 支持 .txt/.md/.pdf/.docx/.html/.xlsx 多格式解析

### 智能体与工具调用
- 10 个文件操作工具：read / write / create / delete / list / find / mkdir / move / copy / plan_tasks
- 危险操作（写入/删除/移动等）强制弹窗确认
- 任务规划：AI 自动分解复杂任务，逐步执行
- 思考过程展示：支持 Qwen3 等思考模型的 thinking 内容

### 多模型支持
| 模式 | 实现 | 特点 |
|:---|:---|:---|
| Needle 内置引导 | NeedleService 关键词匹配 | 零配置，引导用户配置模型 |
| 本地 GGUF | node-llama-cpp | 真正流式、支持思考标签、完全离线 |
| 云端 API | OpenAI SDK | 流式、工具调用、兼容 OpenAI 格式 |

### 编辑器
- Monaco Editor（VS Code 同款内核）
- 多文件 Tab、自动保存、Markdown 预览

### 外观
- 深色/浅色主题切换
- 自研 Lw UI 组件库（18 个组件）
- 50+ SVG 图标，跟随主题变色

---

## 技术栈

| 层级 | 技术 | 说明 |
|:---|:---|:---|
| 桌面框架 | Electron + Vite | 跨平台，Vite 极速 HMR |
| 前端 | Vue 3 + TypeScript | Composition API + `<script setup>` |
| UI 组件 | 自研 Lw 组件库 | 18 个组件，CSS 变量主题系统 |
| 状态管理 | Pinia + persistedstate | 组合式 Store，关键状态持久化 |
| 编辑器 | Monaco Editor | VS Code 同款内核 |
| 本地 LLM | node-llama-cpp | GGUF 模型原生推理，流式输出 |
| ONNX 推理 | @huggingface/transformers | bge-small-zh-v1.5 嵌入模型（512维） |
| 文本分块 | @langchain/textsplitters | RecursiveCharacterTextSplitter |
| 向量索引 | vectra | 纯 JS，零原生依赖 |
| 关键词检索 | BM25Service | Okapi BM25 + RRF 混合融合 |
| 数据库 | better-sqlite3 | SQLite WAL 模式 |
| 云端 LLM | OpenAI SDK | 统一适配 OpenAI/Ollama/DeepSeek/智谱等 |
| 文档解析 | pdf-parse + mammoth + xlsx | PDF/Word/Excel |
| 文档生成 | docx + xlsx | Markdown→Word，CSV→Excel |
| 样式 | Less | CSS 自定义属性主题系统 |

---

## 架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        Electron 主进程                          │
│  AgentService ← LLMService ← EmbeddingService ← VectorIndex   │
│       ↓              ↓              ↓              ↓           │
│  FileToolService  BM25Service  DocumentLoader  DatabaseService │
├──────────────────── contextBridge ──────────────────────────────┤
│                        渲染进程 (Vue 3)                         │
│  Views (3)  ←  Components (业务+UI)  ←  Pinia Stores (5)      │
│  API Modules (6)  ←  Utils (5)  ←  Styles (主题系统)          │
└─────────────────────────────────────────────────────────────────┘
```

核心数据流：用户消息 → Agent Loop → 混合 RAG 检索 → LLM 推理 → 工具调用循环 → 流式推送

---

## 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm

### 安装与运行

```bash
# 克隆项目
git clone https://github.com/your-username/LocalWise.git
cd LocalWise

# 安装依赖（含 electron-rebuild）
npm install

# 下载内置模型（首次运行）
npm run download-models

# 开发模式
npm run dev

# 类型检查
npm run typecheck

# 构建
npm run build:win   # Windows
npm run build:mac   # macOS
```

---

## 项目结构

```
src/
├── main/                          # 主进程（Node.js）
│   ├── index.ts                   # 入口，窗口创建，CSP 策略
│   ├── preload.ts                 # contextBridge 安全桥接
│   ├── ipc/index.ts               # IPC 处理器注册
│   ├── services/                  # 核心服务层
│   │   ├── AgentService.ts        # Agent Loop 编排
│   │   ├── BM25Service.ts         # BM25 关键词检索 + RRF
│   │   ├── DatabaseService.ts     # SQLite CRUD
│   │   ├── DocumentLoader.ts      # 多格式解析 + 智能分块
│   │   ├── EmbeddingService.ts    # 向量化服务
│   │   ├── FileToolService.ts     # 10 个文件操作工具
│   │   ├── LLMService.ts         # 本地 GGUF + 云端 OpenAI
│   │   ├── NeedleService.ts       # 内置引导服务
│   │   ├── ONNXService.ts        # ONNX 推理（备用）
│   │   └── VectorIndexService.ts  # vectra 向量索引
│   └── utils/logger.ts
│
├── renderer/                      # 渲染进程（Vue 3）
│   ├── views/                     # 页面组件
│   ├── components/                # 业务组件 + 自研 Lw UI 组件库
│   ├── stores/                    # Pinia 状态管理
│   ├── api/modules/               # IPC API 封装
│   ├── utils/                     # 工具函数
│   ├── assets/icons/              # SVG 图标（50+）
│   └── styles/                    # 全局样式 + 主题变量
│
└── shared/types/                  # 主进程/渲染进程共享类型
```

---

## 安全设计

| 安全措施 | 实现方式 |
|:---|:---|
| 上下文隔离 | `contextIsolation: true`，`nodeIntegration: false` |
| CSP 策略 | 生产环境禁止 `unsafe-inline`/`unsafe-eval` |
| 外部链接拦截 | 交给系统浏览器打开 |
| 危险操作确认 | 写入/删除/移动/复制等操作需用户确认 |
| 文件大小限制 | 读取限制 10MB，工具输出截断 8000 字符 |
| 工具轮数限制 | 默认 5 轮，绝对上限 50 轮 |
| API Key 隔离 | 主进程 SQLite 管理，前端无法直接读取 |

---

## 性能优化

- SQLite WAL 模式，读写并发性能更好
- 模型实例缓存，避免重复加载
- 本地 LLM Context 每次创建释放，避免序列耗尽
- 批量向量写入（beginUpdate/endUpdate）
- 批量 Embedding（云端 API 按 10 条分批）
- 增量索引同步（MD5 比对）
- 流式内容与消息列表分离，避免 Vue 深层响应式追踪
- Monaco Editor 懒加载
- 并发保护（loadingPromise 防重复加载）

---

## 目标用户与场景

| 用户群体 | 典型场景 |
|:---|:---|
| 律师 | 案件文档导入项目，AI 辅助查找法律依据、起草法律意见书 |
| 咨询顾问 | 项目资料集中管理，AI 快速生成分析报告 |
| 研究人员 | 论文、实验数据本地归档，AI 辅助文献综述 |
| 企业管理者 | 内部制度、会议纪要集中管理，AI 快速解答疑问 |
| 开发者 | 技术文档本地索引，AI 辅助生成代码、撰写技术方案 |
| 知识工作者 | 个人知识库构建，告别"找不到文件"的烦恼 |

---

## 文档

| 文档 | 说明 |
|:---|:---|
| [需求文档](doc/LocalWise-需求文档.md) | 完整功能需求与技术架构 |
| [功能完成情况](doc/功能完成情况.md) | 各模块功能完成进度 |
| [技术文档](doc/LocalWise-技术文档.md) | 面向开发者的技术细节 |
| [用户手册](doc/LocalWise-用户手册.md) | 面向终端用户的使用指南 |