# open-knowledge-wiki

**Repository Path**: su_zhou_123/open-knowledge-wiki

## Basic Information

- **Project Name**: open-knowledge-wiki
- **Description**: 基于 RAG 与大语言模型的 RAG + 双链 Wiki 个人知识管理系统。支持wikilinks、知识图谱可视化、混合检索(全文 + 语义 RRF 融合)。前端 Next.js 16 + TipTap WYSIWYG,后端FastAPI + pgvector + LiteLLM。本地优先、数据完全自主。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenKnowledge

<p align="center">
  <img src="https://img.shields.io/badge/Next.js-16-black?style=flat-square&logo=next.js" alt="Next.js">
  <img src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react" alt="React">
  <img src="https://img.shields.io/badge/FastAPI-0.109-009688?style=flat-square&logo=fastapi" alt="FastAPI">
  <img src="https://img.shields.io/badge/PostgreSQL-16-336791?style=flat-square&logo=postgresql" alt="PostgreSQL">
  <img src="https://img.shields.io/badge/pgvector-0.2-336791?style=flat-square" alt="pgvector">
  <img src="https://img.shields.io/badge/Python-3.12-3776AB?style=flat-square&logo=python" alt="Python">
  <img src="https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square&logo=typescript" alt="TypeScript">
  <img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="License">
</p>

<p align="center">
  <strong>本地优先的智能知识管理与学习助手</strong>
</p>

<p align="center">
  基于 RAG（检索增强生成）的私有文档问答，叠加一套 Obsidian 风格的双向链接 Wiki，<br/>
  帮助你在本地高效地积累、连接、检索和回顾知识。
</p>

---

## ✨ 功能特性

### AI 助手
- **🤖 知识库问答 (RAG)** — 上传文档后基于其内容做语义检索并回答，附带流式（SSE）逐字输出
- **🧠 长期记忆** — 自动从对话中提炼结构化记忆（类别 / 重要性），下次对话按语义召回
- **🛠️ 工具调用** — 内置日期时间、计算器、DuckDuckGo 网页搜索，最多 4 轮工具循环
- **💬 对话历史** — 多会话管理、历史搜索，超长对话用 token 感知策略自动摘要压缩
- **🌐 多 LLM 支持** — 经 LiteLLM 统一网关接入 OpenAI、Claude、Qwen / DashScope、DeepSeek、Moonshot、Zhipu、Gemini、Ollama 等

### Wiki 知识库
- **🔗 双向链接** — `[[wikilinks]]` 语法（别名、嵌入、锚点），自动反向链接与悬空链接解析
- **📝 所见即所得编辑器** — 基于 TipTap，支持表格、任务列表、代码块、WikiLink 自动补全
- **🕸️ 知识图谱** — Cytoscape 力导向布局，节点大小随连接度变化
- **🔍 三种搜索模式** — 全文（PostgreSQL FTS）、语义（pgvector）、混合（RRF 融合，默认）
- **🗂️ 数据自主权** — 每页双写为 `.md` 文件镜像；支持单页 / 批量导出、导入、从 vault 反向同步
- **🤝 AI 读层** — 相关页面推荐、知识缺口发现、AI 草稿生成

### 通用
- **🔒 本地优先** — 数据存储在本地 PostgreSQL 与 `.md` vault；配合 Ollama 可完全离线运行
- **📚 多格式文档** — PDF（6 引擎瀑布式回退）、Word、Excel、TXT、Markdown，异步处理 + 实时进度

---

## 🛠️ 技术栈

### 前端 (`frontend/`)

| 技术 | 版本 | 说明 |
|------|------|------|
| Next.js | 16.x (App Router) | React 框架 |
| React | 19.x | UI 库 |
| TypeScript | 5.x | 类型安全（strict） |
| TailwindCSS | 4.x | 样式 |
| shadcn/ui + Radix UI | — | 无障碍 UI 组件 |
| Zustand | 5.x | 客户端状态（`persist` 持久化） |
| TanStack Query | 5.x | 服务端状态 / 数据获取 |
| TipTap | 3.x | Wiki 所见即所得编辑器 |
| Cytoscape | 3.x | 知识图谱可视化 |

### 后端 (`backend/`)

| 技术 | 版本 | 说明 |
|------|------|------|
| FastAPI | 0.109 | Web 框架、流式响应 |
| Python | 3.12+ | 编程语言 |
| SQLAlchemy (async) | 2.0 | ORM，`asyncpg` 驱动 |
| PostgreSQL + pgvector | pg16 / 0.2 | 关系存储 + 向量检索（同一实例） |
| LiteLLM | 1.50+ | 多提供商 LLM 统一网关 |
| LangChain (openai) | — | 仅用于记忆提取 |
| PyMuPDF / pdfplumber / pypdf | — | 多引擎 PDF 解析 |
| bleach / markdown-it-py | — | Wiki HTML 渲染（XSS 安全） |
| pytest + pytest-asyncio | — | 测试（Wiki 模块 146 个测试） |

---

## 🚀 快速开始

### 环境要求

- Node.js >= 20
- Python >= 3.12
- Docker Desktop（用于运行 PostgreSQL + pgvector）
- 至少一个 LLM 提供商的 API Key（或本地安装 Ollama 完全离线运行）

### 安装步骤

**1. 克隆项目**

```bash
git clone https://gitee.com/su_zhou_123/open-knowledge-wiki.git
cd open-knowledge-wiki
```

**2. 启动数据库**

```bash
docker-compose up -d
```

启动带 pgvector 扩展的 PostgreSQL（端口 `5432`，库名 `knowledge_assistant`）。

**3. 安装并启动后端**

```bash
cd backend
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

uvicorn main:app --reload --port 8000
```

后端启动时会自动执行 `init_db()`，创建所有表并补建 Wiki 所需的 GIN / ivfflat 索引。默认数据库连接见下方[环境变量](#️-环境变量)，与 `docker-compose.yml` 一致，无需额外配置即可启动。

**4. 安装并启动前端**

```bash
cd frontend
npm install
npm run dev
```

**5. 访问应用并配置模型**

- 前端：http://localhost:3000
- 后端 API 文档：http://localhost:8000/docs

打开**设置**页面，选择提供商并填入 API Key（Key 保存在浏览器本地，随请求发送，不写入服务端）。若使用 Ollama 本地嵌入：

```bash
ollama pull nomic-embed-text
```

### 页面入口

| 页面 | URL | 功能 |
|------|-----|------|
| 首页 | `/` | 导航入口 |
| 聊天 | `/chat` | RAG 对话主界面 |
| 知识库 | `/knowledge` | 上传 / 管理文档 |
| 记忆 | `/memories` | 查看 / 管理 AI 记忆 |
| Wiki | `/wiki` | 双向链接知识库（编辑、图谱、搜索、标签、导入、缺口） |
| 设置 | `/settings` | API Key 与模型配置 |

---

## 📁 项目结构

```
OpenKnowledge/
├── frontend/                  # Next.js 前端
│   ├── app/
│   │   ├── chat/             # RAG 对话
│   │   ├── knowledge/        # 文档管理
│   │   ├── memories/         # 记忆管理
│   │   ├── settings/         # 模型 / API Key 配置
│   │   └── wiki/             # Wiki：编辑 / 图谱 / 搜索 / 标签 / 导入 / 缺口
│   ├── components/           # UI 组件（含 wiki/）
│   ├── lib/                  # api.ts / wiki-api.ts / utils.ts
│   ├── hooks/                # 自定义 Hooks（wiki/）
│   ├── stores/               # Zustand：settings / wiki / wiki-draft
│   └── types/                # 共享类型定义
├── backend/                   # FastAPI 后端
│   ├── api/                  # chat / documents / conversations / memories / wiki
│   ├── services/             # 业务逻辑（LLM / RAG / 嵌入 / 文档 / 记忆 / 工具 / Wiki*）
│   ├── models/               # SQLAlchemy 模型 + Pydantic Schema
│   ├── core/                 # config / database
│   ├── tests/wiki/           # Wiki 模块 pytest 测试套件
│   ├── wiki_vault/           # Wiki 的 .md 文件镜像（数据自主权）
│   └── uploads/              # 上传文件存储（UUID 命名）
├── docs/                      # 项目文档、开发日志、Wiki 开发者指南
├── sql/                       # SQL 脚本
├── docker-compose.yml         # PostgreSQL + pgvector
└── README.md
```

---

## 🏗️ 核心架构

### 系统架构图

```mermaid
graph TB
    subgraph Frontend["🎨 前端层 (Next.js 16 + React 19)"]
        UI[用户界面]
        State[Zustand / TanStack Query]
        Editor[TipTap 编辑器]
        Graph[Cytoscape 图谱]
    end

    subgraph Backend["⚙️ 后端层 (FastAPI)"]
        subgraph Routers["API 路由"]
            ChatAPI[chat]
            DocAPI[documents]
            ConvAPI[conversations]
            MemAPI[memories]
            WikiAPI[wiki]
        end

        subgraph Services["业务服务层"]
            LLMGateway[LLM 网关]
            RAGService[RAG 检索]
            EmbedService[嵌入服务]
            DocService[文档处理]
            MemoryService[记忆服务]
            ToolsService[工具服务]
            WikiService[Wiki 服务]
            EventBus[Wiki 事件总线]
        end
    end

    subgraph DataLayer["💾 数据层"]
        PG[(PostgreSQL)]
        VectorDB[(pgvector<br/>向量检索)]
        Vault[wiki_vault<br/>.md 镜像]
        FileStore[uploads<br/>原始文件]
    end

    subgraph External["🌐 外部 LLM 提供商"]
        Providers[OpenAI / Claude / Qwen<br/>DeepSeek / Moonshot / Zhipu<br/>Gemini / Ollama]
    end

    UI --> State
    Editor --> State
    Graph --> State
    State --> Routers
    Routers --> Services

    ChatAPI --> LLMGateway
    LLMGateway --> RAGService
    LLMGateway --> MemoryService
    LLMGateway --> ToolsService
    RAGService --> VectorDB
    DocService --> FileStore
    DocService --> EmbedService
    WikiAPI --> WikiService
    WikiService --> EventBus
    EventBus --> Vault
    EventBus --> VectorDB

    LLMGateway --> Providers
    EmbedService --> Providers
    Services --> PG
```

### RAG 数据流图

```mermaid
sequenceDiagram
    participant User as 用户
    participant UI as 前端界面
    participant API as FastAPI
    participant Conv as 会话服务
    participant RAG as RAG 引擎
    participant Mem as 记忆服务
    participant Vector as pgvector
    participant LLM as LLM 网关

    User->>UI: 输入问题
    UI->>API: POST /api/chat/rag
    API->>Conv: 构建 token 感知上下文
    par RAG 检索
        API->>RAG: 检索相关文档块
        RAG->>Vector: 余弦距离搜索
        Vector-->>RAG: top-K 文档块
    and 记忆召回
        API->>Mem: 语义召回记忆
        Mem->>Vector: 余弦距离搜索
        Vector-->>Mem: 相关记忆
    end
    API->>LLM: System Prompt = RAG + 记忆 + 历史
    LLM-->>API: 流式生成（含工具循环）
    API-->>UI: SSE 逐字响应
    UI-->>User: 显示答案
    API->>Mem: 后台任务：保存消息 + 提取记忆
```

### Wiki 保存流程（事件驱动）

```mermaid
flowchart LR
    A[POST/PUT /api/wiki/pages] --> B[同步 DB 写入]
    B --> C[返回响应]
    B -.BackgroundTask.-> D[发布 PageSaved 事件]
    D --> E[镜像 .md]
    E --> F[渲染 HTML]
    F --> G[解析链接]
    G --> H[解析悬空链接]
    H --> I[同步标签]
    I --> J[生成嵌入向量]

    style A fill:#e1f5fe
    style C fill:#c8e6c9
    style J fill:#fff3e0
```

> Wiki 采用 **Path B 事件驱动**：DB 同步写入后由 FastAPI BackgroundTask 发布 `PageSaved`，各订阅者按注册顺序串行处理副作用（每个处理器独立 try/except 隔离）。

### 文档处理流程图

```mermaid
flowchart LR
    A[用户上传文档] --> B{文件类型}

    B -->|PDF| C[6 引擎瀑布式提取]
    B -->|Word| D[python-docx 解析]
    B -->|Excel| E[pandas 读取]
    B -->|TXT/MD| F[直接读取]

    C --> H[文本分块<br/>1000 字/块, 200 重叠]
    D --> H
    E --> H
    F --> H

    H --> I[批量生成嵌入向量]
    I --> J[存储到 pgvector]
    J --> K[更新状态为 completed]

    style A fill:#e1f5fe
    style K fill:#c8e6c9
```

### 数据库 E-R 图

```mermaid
erDiagram
    CONVERSATION ||--o{ MESSAGE : contains
    DOCUMENT ||--o{ DOCUMENT_CHUNK : split_into
    WIKI_PAGE ||--o{ WIKI_LINK : has
    WIKI_PAGE ||--o{ WIKI_TAG : tagged

    CONVERSATION {
        uuid id PK
        string title
        text summary
        datetime created_at
        datetime updated_at
    }
    MESSAGE {
        uuid id PK
        uuid conversation_id FK
        string role
        text content
        datetime created_at
    }
    DOCUMENT {
        uuid id PK
        string filename
        string file_type
        string status
        datetime uploaded_at
    }
    DOCUMENT_CHUNK {
        uuid id PK
        uuid document_id FK
        text content
        int chunk_index
        vector embedding
    }
    MEMORY {
        uuid id PK
        text content
        string category
        float importance
        vector embedding
    }
    WIKI_PAGE {
        uuid id PK
        string slug
        string title
        text content
        text html
        boolean archived
        vector embedding
    }
    WIKI_LINK {
        uuid id PK
        uuid source_id FK
        uuid target_id FK
        string target_title
        boolean dangling
    }
    WIKI_TAG {
        uuid id PK
        uuid page_id FK
        string tag
    }
```

### 部署架构图

```mermaid
graph TB
    subgraph Client["客户端"]
        Browser[浏览器]
    end

    subgraph Local["本地主机"]
        Frontend[前端<br/>Next.js :3000]
        Backend[后端<br/>FastAPI :8000]
        Vault[wiki_vault/<br/>.md 镜像]
        subgraph Docker["Docker"]
            Postgres[PostgreSQL + pgvector<br/>:5432]
        end
    end

    subgraph ExternalAPIs["外部 / 本地 LLM"]
        Cloud[OpenAI / Claude / Qwen ...]
        LocalLLM[Ollama 本地模型]
    end

    Browser -->|HTTP / SSE| Frontend
    Frontend -->|API 请求| Backend
    Backend -->|SQL + 向量检索| Postgres
    Backend -->|.md 双写| Vault
    Backend -->|LLM / 嵌入调用| Cloud
    Backend -->|本地模型| LocalLLM

    style Client fill:#e3f2fd
    style Local fill:#f3e5f5
    style ExternalAPIs fill:#fff3e0
```

---

## 🧩 核心模块

### 1. LLM Gateway
经 LiteLLM 封装的统一调用层，屏蔽各提供商 API 差异，组装 RAG + 记忆 + 历史上下文，并驱动工具循环。任何 OpenAI 兼容代理只需填 `base_url` 即可接入。

### 2. RAG Engine
文档分块（1000 字/块、200 重叠）→ 多提供商嵌入 → pgvector 余弦距离检索，无需独立向量数据库。

### 3. Document Processor
异步处理 + 内存进度追踪。PDF 采用 6 引擎瀑布式回退（pymupdf4llm → pypdf → pymupdf → pdfplumber → OCR 兜底），并支持 Word / Excel / TXT / Markdown。

### 4. Memory System
后台任务用 LLM 把对话提炼为结构化记忆（类别 / 重要性），经白名单 / 黑名单与重要性阈值过滤后向量化存储，按语义召回。

### 5. Wiki Module
Obsidian 风格双向链接知识库。事件驱动后端 + PostgreSQL/`.md` 双写，含全文 / 语义 / 混合（RRF）三种搜索、Cytoscape 知识图谱、导入导出与 vault 同步、AI 读层（相关页面 / 知识缺口 / 草稿）。详见 [docs/wiki/README.md](docs/wiki/README.md)。

---

## 📡 API 概览

所有路由以 `/api` 为前缀，完整交互文档见 `http://localhost:8000/docs`。

| 模块 | 前缀 | 代表性端点 |
|------|------|-----------|
| Chat | `/api` | `POST /chat`、`POST /chat/rag`（流式）、`GET /tools` |
| Documents | `/api/documents` | `POST /upload`、`GET /{id}/status`、`POST /search` |
| Conversations | `/api/conversations` | CRUD、`GET /search`、`POST /{id}/messages` |
| Memories | `/api/memories` | CRUD、`GET /search`、`POST /extract`、`GET/POST /settings` |
| Wiki | `/api/wiki` | `pages` CRUD、`GET /search`、`GET /graph`、`GET /tags`、`import` / `export` / `sync-from-vault`、`ai/related`、`gaps`、`ai/draft` |

---

## 🔧 开发指南

### 前端开发

```bash
cd frontend
npm run dev          # 开发服务器
npm run build        # 生产构建
npm run lint         # ESLint 检查
```

### 后端开发

```bash
cd backend
source venv/bin/activate
uvicorn main:app --reload   # 开发服务器（或 python main.py）
pytest                      # 运行测试
pytest --cov=. tests/       # 带覆盖率
```

> 当前测试覆盖集中在 Wiki 模块（`backend/tests/wiki/`，146 个测试）。需要 Postgres 的集成测试标记为 `integration`，纯逻辑测试标记为 `unit`。前端暂未配置测试框架。

---

## ⚙️ 环境变量

后端唯一必需的配置是数据库连接，默认值与 `docker-compose.yml` 一致，开箱即可运行。如需覆盖，在 `backend/` 下创建 `.env`：

```env
# 数据库（默认值，与 docker-compose 一致）
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/knowledge_assistant
```

> **LLM / 嵌入 API Key 不通过环境变量配置**。它们在前端**设置**页面填写，保存于浏览器本地，随请求发送给后端，不会写入服务端文件或日志。

---

## 🔒 部署到 localhost 之外前须知

本项目为**单用户本地优先**设计。在任何共享 / 托管 / 网络暴露的环境部署前，需先处理以下两点（属应用级别，应在全部路由统一处理，而非仅 Wiki）：

- **无认证** — 全部路由（chat / documents / memories / wiki）目前均无鉴权。`POST /api/wiki/sync-from-vault` 与 `POST /api/wiki/import` 会覆盖内容，风险最高。暴露前应增加统一的认证层。
- **API Key 走请求体** — 用户的第三方 LLM / 嵌入 Key 通过 POST body / form 传输（是用户自己的 Key，非服务端密钥，且不写日志）。托管部署应改为 `Authorization` / `X-Api-Key` 请求头，并确保未启用任何记录请求体的中间件。

详见 [docs/wiki/README.md](docs/wiki/README.md) 的「Before deploying beyond localhost」。

---

## 🗺️ 路线图

- [x] 基础文档管理
- [x] RAG 问答系统（流式）
- [x] 多 LLM 支持
- [x] 长期记忆系统
- [x] 工具调用
- [x] Wiki 双向链接知识库
- [x] 知识图谱与混合搜索
- [x] Wiki 导入 / 导出 / vault 同步
- [x] AI 读层（相关页面 / 知识缺口 / 草稿）
- [ ] 应用级认证
- [ ] 移动端适配
- [ ] 协作功能
- [ ] Tauri 桌面端

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request。

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: add some amazing feature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

提交前请参考 [AGENTS.md](AGENTS.md) 的仓库约定与构建 / 测试命令。

---

## 📄 许可证

本项目基于 [MIT](LICENSE) 许可证开源。

---

<p align="center">
  Made with ❤️ by <a href="https://gitee.com/su_zhou_123">su_zhou_123</a>
</p>

<p align="center">
  <strong>OpenKnowledge</strong> — 你的本地智能知识助手
</p>