# brain

**Repository Path**: lee26/brain

## Basic Information

- **Project Name**: brain
- **Description**: ai本地知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# brain

Local-first personal knowledge base for Markdown notes, search, AI retrieval, and static publishing.

---

## Quick start

```bash
cd /Users/lichao/IdeaProjects/brain
mvn spring-boot:run
```

Open:

- `http://localhost:8080/`
- `http://localhost:8080/api/health`
- `http://localhost:8080/api/documents`
- `http://localhost:8080/api/search?q=brain`

---

## 项目概述

一个基于 **Spring Boot 3.2.8 + Java 17** 的本地知识库系统，核心功能包括：

- **Markdown 笔记管理** — 基于 vault 体系的文件管理
- **Lucene 全文搜索** — 词法层面的快速检索
- **AI 增强检索 (RAG)** — 词法 + 语义混合排序，支持 LLM 问答
- **REST API + 静态页面 UI** — 前后端分离，前端为原生 HTML/CSS/JS
- **文件变更监控** — 实时检测 vault 文件变化并自动重新索引

---

## 技术栈

| 层 | 技术 |
|------|------|
| 框架 | **Spring Boot 3.2.8** |
| 语言 | **Java 17** |
| 搜索引擎 | **Apache Lucene 9.11.1** (core + queryparser + highlighter + analysis) |
| AI / LLM | DashScope API (阿里通义千问 / DeepSeek) |
| 向量嵌入 | 通过 AiEmbeddingService 调用第三方模型 |
| 前端 | 原生 HTML / CSS / JS（无前端框架） |
| 构建 | Maven |
| 监控 | Spring Actuator |

---

## 架构分层

```
┌─────────────────────────────────────────────────┐
│                  UI 层 (Static HTML)              │
│   index.html  view.html  ai.html                 │
├─────────────────────────────────────────────────┤
│               Controller 层 (REST API)            │
│   BrainController  PageController                │
├─────────────────────────────────────────────────┤
│               Service 层 (业务逻辑)                │
│   ┌─────────────┐  ┌──────────────────────┐      │
│   │  SearchService│  │  AiSearchService     │      │
│   │  (混合排序)   │  │  (RAG 问答)          │      │
│   └──────┬──────┘  └──────────┬───────────┘      │
│          │                     │                  │
│   ┌──────┴──────┐  ┌──────────┴───────────┐      │
│   │ LuceneSearch│  │ AiCompletionService   │      │
│   │ Index(词法) │  │ (LLM 生成回答)        │      │
│   └─────────────┘  └──────────────────────┘      │
│   ┌─────────────┐  ┌──────────────────────┐      │
│   │ ChunkIndex  │  │ AiEmbeddingService    │      │
│   │ Service     │  │ (向量嵌入)            │      │
│   └─────────────┘  └──────────────────────┘      │
├─────────────────────────────────────────────────┤
│          Domain 层 (数据模型)                      │
│   NoteDocument  SearchResult  AiAnswer           │
│   AiAskRequest  VaultTreeNode  ...               │
├─────────────────────────────────────────────────┤
│          基础设施层                                │
│   VaultScanner  VaultChangeWatcher  NoteWriter    │
│   MarkdownParser  MarkdownChunker  NoteCatalog     │
│   AttachmentResolver  BrainProperties             │
└─────────────────────────────────────────────────┘
```

### 各层职责

| 层 | 职责 | 关键类 |
|----------|----------|----------|
| **UI 层** | 提供前端交互界面，所有页面为静态 HTML | `index.html`, `view.html`, `ai.html` |
| **Controller 层** | 暴露 REST API 接口，处理 HTTP 请求/响应 | `BrainController`, `PageController` |
| **Service 层** | 核心业务逻辑，包括搜索排序、AI 检索、分块索引 | `SearchService`, `AiSearchService`, `LuceneSearchIndex` |
| **Domain 层** | 数据模型定义，请求/响应的 DTO | `NoteDocument`, `SearchResult`, `AiAnswer` |
| **基础设施层** | 文件系统操作、Markdown 解析、变更监控、配置绑定 | `VaultScanner`, `NoteCatalog`, `BrainProperties` |

---

## 源码模块结构

```
src/main/java/com/lee/brain/
│
├── BrainApplication.java               # 入口类，启动时自动加载 NoteCatalog
│
├── config/
│   └── BrainProperties.java            # @ConfigurationProperties 配置绑定
│                                       # (vault-root, index-root, ai-base-url 等)
│
├── controller/
│   ├── BrainController.java            # REST API 控制器 (/api/*)
│   │   ├── GET  /api/health            #   健康检查
│   │   ├── GET  /api/documents         #   所有文档列表
│   │   ├── GET  /api/tree              #   目录树
│   │   ├── GET  /api/document?path=    #   单个文档
│   │   ├── GET  /api/asset             #   附件获取
│   │   ├── GET  /api/search?q=         #   搜索
│   │   ├── GET  /api/ai/ask?q=         #   AI 问答 (GET)
│   │   ├── POST /api/ai/ask            #   AI 问答 (POST，支持 session)
│   │   ├── POST /api/refresh           #   刷新索引
│   │   └── POST /api/save              #   保存笔记
│   └── PageController.java             # 页面路由转发
│       ├── GET /view → view.html
│       └── GET /ai   → ai.html
│
├── domain/
│   ├── NoteDocument.java               # 笔记文档模型 (path, title, tags, content 等)
│   ├── SearchResult.java               # 搜索结果 (score, excerpt, relativePath 等)
│   ├── AiAnswer.java                   # AI 回答结果
│   ├── AiAskRequest.java               # AI 问答请求 (question, limit, session)
│   ├── AiChatTurn.java                 # 对话历史单轮
│   ├── AiSource.java                   # 回答引用的来源
│   ├── NoteWriteRequest.java           # 笔记写入请求
│   └── VaultTreeNode.java              # 目录树节点
│
└── service/
    ├── NoteCatalog.java                # 笔记目录 & 全文检索入口
    │                                    # 管理文档集合、路由搜索请求
    │
    ├── SearchService.java              # 混合排序搜索服务
    │                                    # 1. Lucene 词法搜索 (top N×3)
    │                                    # 2. 向量语义重排序 (cosine similarity)
    │                                    # 3. 混合: semantic×0.72 + lexical×0.28
    │
    ├── AiSearchService.java            # RAG 问答服务
    │                                    # 1. 检索相关文档 → 分块打分
    │                                    # 2. 语义重排序 → 构建上下文
    │                                    # 3. 调用 LLM 生成回答
    │                                    # 4. 回退策略(LLM 不可用时直接展示来源)
    │
    ├── AiCompletionService.java        # LLM 补全调用 (DashScope API)
    │                                    # 使用 HttpClient，支持对话历史
    │
    ├── AiEmbeddingService.java         # 向量嵌入服务
    │                                    # 调用外部 API 生成文本向量
    │
    ├── LuceneSearchIndex.java          # Lucene 索引封装
    │                                    # 索引写入、搜索、高亮
    │
    ├── ChunkIndexService.java          # 文档分块 + 嵌入缓存
    │                                    # 按标题层级分块，缓存向量结果
    │
    ├── MarkdownParser.java             # Markdown 解析: 提取 frontmatter + 内容
    │
    ├── MarkdownChunker.java            # Markdown 分块策略
    │                                    # 按 ## 标题切分，前 3 行摘要
    │
    ├── VaultScanner.java               # 文件系统扫描: 递归遍历 .md 文件
    │
    ├── VaultChangeWatcher.java         # WatchService 文件变更监控
    │
    ├── VaultChangeProcessor.java       # 变更事件处理 (创建/修改/删除)
    │
    ├── NoteWriter.java                 # 笔记写入/创建
    │
    └── AttachmentResolver.java         # 附件路径解析
```

---

## 核心业务流程

### 1. 启动流程

```
BrainApplication.main()
  └─ @Bean CommandLineRunner
       └─ NoteCatalog.reload()
            ├─ VaultScanner 扫描 vault 目录
            ├─ MarkdownParser 解析每篇笔记
            ├─ LuceneSearchIndex 建立全文索引
            └─ ChunkIndexService 分块 + 生成嵌入
```

### 2. 搜索流程 (`GET /api/search?q=...`)

```
用户查询
  └─ NoteCatalog.search()
       └─ SearchService.search()
            ├─ LuceneSearchIndex 词法搜索 (取 top N×3)
            ├─ AiEmbeddingService 生成 query 向量
            ├─ ChunkIndexService 按文档获取分块
            └─ 混合排序: semantic×0.72 + lexical×0.28
```

### 3. AI 问答流程 (`POST /api/ai/ask`)

```
用户问题
  └─ AiSearchService.ask()
       ├─ SearchService.search() 检索相关文档
       ├─ ChunkScore 排序分块
       ├─ AiEmbeddingService 语义重排序
       ├─ AiCompletionService.generateAnswer() LLM 生成回答
       └─ 返回 AiAnswer(question, answer, sources, candidates)
```

---

## 数据存储

| 存储 | 位置 | 用途 |
|------|------|------|
| **Vault** | `/Users/lichao/SynologyDrive/知识库/` | Markdown 原始笔记 |
| **Lucene 索引** | `{vault}/.brain/data/index/` | 全文搜索索引 |
| **配置** | `application.yml` | 应用配置 |

Vault 目录结构：

```
vault/
├── inbox/        # 待处理笔记
├── notes/        # 正式笔记
├── summaries/    # 摘要
├── projects/     # 项目笔记
├── published/    # 已发布
└── attachments/  # 附件
```

---

## 架构特点

1. **本地优先 (Local-First)** — 所有数据存储在本地文件系统，不依赖外部数据库
2. **混合搜索** — Lucene 词法搜索 + AI 向量语义搜索，权重比 **语义 72% : 词法 28%**
3. **RAG 架构** — 检索增强生成：先从知识库检索相关内容，再交给 LLM 生成答案
4. **文件变更监控** — 使用 Java WatchService 实时检测 vault 文件变化
5. **分块索引** — Markdown 文档按标题层级分块，每块独立索引 + 向量化
6. **可插拔 AI** — 通过配置切换模型（当前为 DeepSeek V4 Flash），API Key 通过环境变量注入

---

## Next steps

1. Add Lucene indexing
2. Add vector search
3. Add RAG
4. Add Hugo publishing