0. 阅读导引

本文面向以下读者：

• 了解 RAG 基本概念，希望进一步理解「知识图谱增强检索」架构的开发者；
• 有前端或 Python 基础，想了解一个完整 AI 桌面应用的跨语言技术选型；
• 正在学习 ChromiaDB / LanceDB 等向量数据库，需要横向对比参考；
• 对 Tauri v2（Rust 桌面壳）替代 Electron 的技术路线感兴趣。

本文假定读者具备基本的编程概念（变量、函数、HTTP 请求），但不要求 Rust、图论或编辑器框架的前置知识。每个概念均从零定义。

1. 项目概述

llm_wiki 是一个采用 GPL-3.0 许可的开源桌面端 AI 知识管理系统，支持 macOS、Windows 与 Linux 三平台。其核心工作流可概括为三步：

摄入：用户导入多格式文档（PDF、DOCX、网页等）→ 系统借助 LLM 自动提取实体与论点 → 生成结构化 Wiki 页面并构建持久化知识图谱。

检索：用户提出自然语言查询 → 系统执行四级混合检索（关键词 + 向量语义 + 图谱扩展 + 上下文预算分配）→ 拼接 prompt 交由 LLM 生成回答。

维护：SHA256 增量缓存确保文档局部修改不触发全量重处理；图谱分析模块自动发现「惊奇连接」与「知识空白」。

工程层面的关键指标：安装包体积 3–10 MB（对比 Electron 典型值 120+ MB），内存占用 20–50 MB（对比 Electron 典型值 150+ MB）。这一差距的核心来源是 Tauri v2 以 Rust 二进制替代了 Node.js 运行时。

2. 系统架构

llm_wiki 采用严格的分层架构，各层之间的职责边界清晰、技术栈独立。先看一张完整的四层逻辑视图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

┌─────────────────────────────────────────────┐
│                 前端 UI 层                    │
│  React 19 + TypeScript + Vite               │
│  shadcn/ui + Tailwind CSS v4                │
│  Zustand (状态管理)                           │
│  Milkdown/ProseMirror (富文本编辑器)           │
│  sigma.js + graphology (知识图谱可视化)        │
├─────────────────────────────────────────────┤
│              Tauri v2 桌面壳                   │
│  Rust 编写的系统级壳，负责：                     │
│  - 文件系统操作                                │
│  - 本地 SQL/向量数据库                          │
│  - 文档解析 (PDF/DOCX/XLSX/PPTX)              │
│  - 系统托盘、快捷键、原生对话框                   │
├─────────────────────────────────────────────┤
│              AI / LLM 层                      │
│  - 多模型 API 调用 (OpenAI/DeepSeek/Gemini 等) │
│  - 两步思维链 (CoT) 摄入管线                    │
│  - 多模态视觉模型 (图片→文本描述)                 │
│  - 嵌入向量生成 + 语义检索                       │
├─────────────────────────────────────────────┤
│             存储 & 索引层                       │
│  - 文件系统: Markdown + YAML frontmatter      │
│  - 向量数据库: LanceDB (Rust 嵌入式)            │
│  - 全文索引 + SHA256 增量缓存                   │
└─────────────────────────────────────────────┘

以下 Mermaid 图展示了各层之间的数据流与调用关系：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

graph TB
    subgraph 前端UI层
        A1["React 19 + TypeScript<br/>Vite 构建"]
        A2["shadcn/ui + Tailwind CSS v4<br/>组件与样式"]
        A3["Zustand<br/>状态管理"]
        A4["Milkdown / ProseMirror<br/>富文本编辑器"]
        A5["sigma.js + graphology<br/>知识图谱可视化"]
    end

    subgraph Tauri v2 桌面壳
        B1["Rust 原生二进制"]
        B2["文件系统操作"]
        B3["本地数据库宿主"]
        B4["文档解析引擎"]
        B5["系统托盘 / 快捷键 / IPC"]
    end

    subgraph LLM 管线层
        C1["多模型 API 调度<br/>OpenAI / DeepSeek / Gemini"]
        C2["两步思维链 CoT 摄入"]
        C3["多模态视觉模型"]
        C4["嵌入向量生成"]
    end

    subgraph 存储与索引层
        D1["Markdown + YAML<br/>文件系统存储"]
        D2["LanceDB<br/>嵌入式向量数据库"]
        D3["全文索引 + SHA256<br/>增量缓存"]
    end

    A1 & A2 & A3 & A4 & A5 -->|"invoke() IPC"| B1
    B1 --> B2 & B3 & B4 & B5
    B3 --> D2
    C1 & C2 & C3 & C4 --> D1 & D2 & D3
    D2 --> C4

3. 前端技术栈

前端层承载了最复杂的用户交互逻辑，涉及四组相互解耦的技术模块。

3.1 核心框架：React 19 + TypeScript + Vite

React 19 在桌面端场景下不涉及 SSR，因此与 Web 开发中的 React 19 使用方式有显著差异——无需考虑水合（hydration）与服务端组件串行化问题。

Zustand：不可变状态管理

Zustand 的设计哲学是「将状态视为可变对象的不可变快照」。与 Redux 的 action → reducer → selector 三层间接性不同，Zustand 的 API 更接近原生 JavaScript 对象操作：

1
2
3
4
5
6
7
8

import { create } from 'zustand'

const useWikiStore = create((set) => ({
  pages: [],
  currentPage: null,
  setCurrentPage: (page) => set({ currentPage: page }),
  addPage: (page) => set((state) => ({ pages: [...state.pages, page] })),
}))

一个 set() 调用即完成状态更新，无需 action type 常量、无需 switch-case reducer、无需 middleware 串联。llm_wiki 使用 Zustand 管理三类高频变化的状态：聊天会话、Wiki 页面集合、以及知识图谱数据的缓存。

3.2 组件体系：shadcn/ui + Tailwind CSS v4

shadcn/ui 的核心设计决策是将组件源码直接复制到项目 src/ 中，而非通过 node_modules 引入黑盒包。这与 Ant Design 或 MUI 存在根本性差异：

Tailwind CSS v4 负责原子化样式层。其核心思想是将 CSS 属性映射为单一职责的 class：

1
2
3
4

<!-- 每个 class 对应一个 CSS 属性，所见即所得 -->
<div class="bg-white rounded-lg shadow-md p-6 hover:shadow-lg transition-shadow">
  <!-- 白底 · 圆角 · 阴影 · 内边距 · 悬停增强阴影 · 过渡动画 -->
</div>

3.3 富文本编辑器：Milkdown / ProseMirror

这是整个前端层中架构复杂度最高的模块。理解它需要先理解 ProseMirror 的设计理念：

1
2
3
4
5
6
7
8
9

ProseMirror: Schema-driven Editor Framework
  ├── Schema  定义文档的合法节点类型与嵌套规则
  ├── Plugin  扩展编辑器行为（快捷键、自动补全、协同编辑）
  ├── View    基于 Schema 的不可变状态渲染
  └── Transform  所有编辑操作都是对文档状态的纯函数变换

Milkdown: 在 ProseMirror 之上封装 Markdown 编辑体验
  ├── 基于 remark/unified 生态做 Markdown ↔ Schema 双向转换
  └── 通过 ProseMirror Plugin 机制扩展自定义语法（如 [[wikilinks]]）

3.4 图谱可视化：sigma.js + graphology + ForceAtlas2

性能关键数字：sigma.js 在消费级 GPU 上可实时渲染 10⁴–10⁵ 量级的节点与边，比 D3-force（基于 SVG，受 DOM 节点数约束）高出一个数量级。这是技术选型的决定性因素——D3 的 SVG 渲染路径在 10³ 节点时即开始出现可感知的帧率下降。

4. 桌面壳层：Tauri v2

4.1 架构对比

1

Tauri v2 = Rust 后端 (tauri-core) + 平台原生 WebView + IPC 桥接层

4.2 四个核心抽象

Command 调用示例

1
2
3
4
5
6
7
8
9
10
11
12

// src-tauri/src/main.rs —— Rust 后端
#[tauri::command]
fn extract_pdf_text(path: String) -> Result<String, String> {
    pdf_extract::extract_text(&path).map_err(|e| e.to_string())
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![extract_pdf_text])
        .run(tauri::generate_context!())
        .expect("failed to start");
}

1
2
3
4
5
6

// src/App.tsx —— TypeScript 前端
import { invoke } from '@tauri-apps/api/core'

const text: string = await invoke('extract_pdf_text', {
  path: '/Users/xxx/document.pdf'
})

5. LLM 管线：两步思维链摄入

这是 llm_wiki 与传统 RAG 系统最本质的差异点，值得用完整的篇幅展开。

5.1 一步 RAG 的局限

标准 RAG 管道为线性流程：

1

文档 → 文本分块 → Embedding → 向量数据库 → 用户查询 → 相似度检索 → 拼接 Prompt → LLM 回答

此流程存在三个系统性缺陷：

1. 缺乏全局语义：每个 chunk 独立编码，LLM 生成时无法感知文档的全貌结构；
2. 无矛盾检测：新摄入内容若与已有知识冲突，RAG 不会主动标记；
3. 链接缺失：不同文档之间的隐含关联在检索阶段才被计算，摄入阶段完全丢失。

5.2 两步 CoT 设计

llm_wiki 在摄入阶段引入 LLM 参与，采用 Chain-of-Thought 分步推理：

1
2
3
4
5
6
7

graph LR
    A["源文档"] --> B["第一步：分析 Analyze"]
    B --> C["第二步：生成 Generate"]
    C --> D["Wiki 页面 + 知识图谱更新"]

    B -.- B1["提取：实体、论点、矛盾点<br/>建议：新页面标题"]
    C -.- C1["创建/更新 Wiki 页面<br/>建立 [[wikilinks]] 内链<br/>更新图谱索引"]

第一步：分析

LLM 通读完整文档（非分块），提取以下结构化信息：

第二步：生成

基于分析层的结构化输出，LLM 执行：

• 创建或更新 Markdown 格式的 Wiki 页面（含 YAML frontmatter）；
• 在页面内容中插入 [[wikilinks]] 内链；
• 更新知识图谱的节点与边（依据四信号模型，详见 §6.1）。

5.3 多模态扩展

对于包含内嵌图片的 PDF 或直接输入的图像文件，管线增加视觉处理分支：

1
2
3
4

输入文件 → 文本层提取 → 常规 CoT 管线
         → 图像层提取 → 视觉模型 (GPT-4V / Gemini Pro Vision)
                           → 图片事实描述文本
                           → 混入 Wiki 页面 + 建立图片分区索引

这使得语义检索能够匹配到图片中描述但未以文本形式存在的概念——例如 PDF 中的架构图、论文中的实验流程图。

5.4 SHA256 增量缓存

1
2
3

文件 → SHA256(input_bytes) → 查缓存
    ├── 命中且未变更 → 跳过，零 token 消耗
    └── 未命中或已变更 → 触发完整摄入管线

6. 知识图谱层

llm_wiki 与传统 RAG 之间最核心的架构差异在于此：它维护了一个持久化的、带权重的知识图谱，摄入时建图，检索时用图。

6.1 四信号关联度模型

知识图谱的核心抽象问题：给定两个 Wiki 页面（节点），它们之间的边应该分配多大的权重？

llm_wiki 采用加权多信号模型：

6.2 Louvain 社区检测

Louvain 算法是图论中应用最广泛的社区发现算法之一，属于贪心优化的层次聚类方法。在 llm_wiki 中，它的输入与输出如下：

1
2
3
4
5
6
7
8

输入: 带权有向图 G = (V, E, w)
      其中 V = Wiki 页面集合
           E = 页面间关联边集合
           w = 边权重（由四信号模型计算）

输出: 每个节点 v ∈ V 被分配至一个社区 Cᵢ
      模块度 (modularity) Q ∈ [0, 1] —— 聚类质量的全局度量
      社区内聚度 (cohesion) —— 社区内部连接密度的归一化度量

为什么选用 Louvain 而非 K-means？

K-means 要求预设聚类数 k，且其距离度量定义在欧氏空间中。图数据的节点之间不存在坐标嵌入，只有拓扑关系。Louvain 不需要预设社区数量，它通过贪心最大化模块度（modularity）自适应地确定最优划分。模块度本质上衡量的是「社区内部的实际边数」与「随机图中期望边数」的差值——差值越大，社区结构越显著。

当某社区的内聚度 < 0.15 时，系统将其标记为「松散社区」，提示用户该聚类可能是算法伪影而非真正的语义聚类。

6.3 自动图谱洞察

系统基于图结构自动发现两类模式：

7. 检索管线：四级混合检索

llm_wiki 的检索架构从传统 RAG 的两级（关键词 + 向量）扩展为四级：

1
2
3
4
5
6

graph TD
    Q["用户查询"] --> L1["第一级：分词搜索<br/>基于关键词的精确匹配"]
    L1 --> L2["第二级：语义搜索<br/>LanceDB 向量检索<br/>余弦相似度排序"]
    L2 --> L3["第三级：图谱扩展<br/>从匹配节点沿边走 N 步<br/>抓取直接与间接关联节点"]
    L3 --> L4["第四级：上下文预算分配<br/>60% 直接匹配 + 20% 延伸上下文<br/>+ 5% 图谱描述 + 15% 系统保留"]
    L4 --> P["拼接 Prompt → LLM"]

四级分解

第三级是本系统的核心差异。传统 RAG 在每次查询时从零检索整个向量空间；llm_wiki 利用了摄入阶段构建的持久化知识图谱——这相当于将跨文档的语义关系预先物化为图的拓扑结构，检索时直接沿边遍历，避免了实时计算全量向量相似度的开销。

LanceDB 与 ChromiaDB 对比

选型逻辑：Tauri v2 的 Rust 后端可以直接 cargo add lancedb 将向量数据库编译进二进制文件，用户完全感知不到数据库的存在。若选用 ChromiaDB 的 C/S 模式，则需要用户额外运行一个数据库服务进程——这在桌面应用场景下不可接受。

8. 文档解析层

全部文档解析工作均在 Rust 侧完成，利用原生线程避免阻塞 UI：

网页内容的处理路径不同：通过 Chrome 扩展（Manifest V3）在浏览器中调用 Readability.js 提取正文、Turndown.js 将 HTML 转换为 Markdown，再送入标准的 CoT 摄入管线。

9. 其他模块

除了上述四层核心架构外，llm_wiki 还包含多个辅助但关键的子系统。

9.1 国际化 (i18n)

使用 react-i18next 实现中/英文双语界面。所有面向用户的文案均通过 t('key') 函数调用，翻译文件以 JSON 格式按模块组织：

1
2
3
4
5
6
7
8
9

src/locales/
  ├── zh-CN/
  │     ├── common.json      # 通用 UI 文案
  │     ├── editor.json      # 编辑器相关
  │     └── settings.json    # 设置面板
  └── en-US/
        ├── common.json
        ├── editor.json
        └── settings.json

react-i18next 的选择逻辑：自动检测系统语言设置，用户可在应用内手动覆盖。切换语言无需重启应用——i18next 的响应式机制会自动触发所有使用了 useTranslation() Hook 的组件重新渲染。

9.2 数学公式渲染

集成 KaTeX（而非 MathJax）处理 LaTeX 数学公式。选型原因：

在桌面端场景下，KaTeX 的首屏渲染速度优势是决定性因素——用户打开包含大量公式的 Wiki 页面时不应出现可见的渲染延迟。

9.3 CoT 可视化

llm_wiki 内置了一个自定义的推理过程可视化组件，用于展示 LLM 思维链的中间步骤。当系统执行两步摄入时，用户可以在 UI 中观察到：

• 第一步分析产出的实体列表、论点摘要、矛盾标记
• 第二步生成产出的 Wiki 页面草稿与图谱更新计划

这不是通用的 LLM 对话界面——它是专为「文档→结构化 Wiki」这一特定工作流设计的可视化层。

9.4 Chrome 扩展（网页剪藏）

基于 Manifest V3 的 Chrome 扩展，技术栈独立于桌面端：

工作流：用户在 Chrome 中点击扩展图标 → Readability.js 提取正文 → Turndown.js 转换为 Markdown → 通过本地 HTTP 接口（localhost 端口）将 Markdown 推入桌面应用的 CoT 摄入管线。

9.5 异步审核队列

对于 LLM 生成结果中置信度低于阈值的内容（如矛盾标记、新页面建议），系统不会直接写入知识库，而是将其放入异步审核队列，等待用户人工确认。

1
2
3

LLM 生成 → 置信度评估
              ├── 高置信度 → 自动写入知识库
              └── 低置信度 → 入审核队列 → 用户确认/修改/驳回

此设计的关键原则是：自动管线不阻塞于人工判断。审核队列是一个独立的优先级队列，用户的待审核项以通知红点形式展示，不干扰正常的摄入与检索流程。这种「人机协作」模式比全自动或全人工都更实用——机器做它能确定的事，不确定的事交给人。

10. 关键设计决策

以下五项决策定义了 llm_wiki 的架构基因。每一项都涉及明确的权衡取舍。

10.1 Tauri v2 而非 Electron

核心判断：性能收益是用户直接感知的（启动速度、内存占用、响应流畅度），而开发成本是一次性的。

10.2 LanceDB 而非 ChromiaDB

零部署是硬约束。桌面应用不能让用户安装数据库服务。LanceDB 实现了「文件即数据库」——启动应用即启动数据库，退出应用即停止，用户无感知。

10.3 两步 CoT 而非单步

一步生成在 token 成本上更优，但质量不可靠：遗漏上下文矛盾、生成内容结构松散、无法自动规划页面拆分。两步设计额外消耗 30–50% token，但生成的 Wiki 页面具有一致的结构与内链密度，大幅降低了后续人工整理的工作量。

10.4 知识图谱本地存储而非云端

隐私（文档全文不出本地）、离线可用性、以及低延迟图谱遍历是本地存储的三个不可替代的优势。代价是本地算力受限——万级以上节点的大规模图谱分析会触发可感知的计算延迟。

10.5 GPL-3.0 许可

作者明确选择了强 Copyleft：自由使用、自由修改，但分发修改版本时必须同样以 GPL-3.0 开源。这保护了项目的公共属性，同时不限制个人或学术用途。

11. 学习路径建议

对于希望从源码层面理解该项目的开发者，建议按以下顺序推进：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

gantt
    title llm_wiki 源码学习路线
    dateFormat  YYYY-MM-DD
    section P0 基础层
    TypeScript 泛型 + React 19 Hooks     :a1, 2026-06-01, 7d
    Tauri v2 架构概念 (Command/Event)    :a2, after a1, 3d
    [[wikilinks]] 知识管理理念           :a3, after a2, 1d
    section P1 核心层
    ProseMirror Schema + Plugin 体系     :b1, after a3, 7d
    Zustand 不可变状态管理               :b2, after a3, 3d
    LanceDB 嵌入式向量数据库              :b3, after b1, 5d
    CoT Prompt Engineering               :b4, after b3, 7d
    Louvain 社区检测 + 图论基础           :b5, after b4, 5d
    section P2 深入层
    Rust 基础 + Tauri Plugin 开发         :c1, after b5, 21d
    sigma.js + ForceAtlas2 定制          :c2, after b5, 7d
    多模态模型 API 适配                   :c3, after c1, 5d

如果目标是日常使用该工具而非二次开发，则无需学习以上任何技术——直接下载安装即可。

参考项目：nashsu/llm_wiki — Stars 9k+ · GPL-3.0

致新手：不必试图同时理解所有层。从 React 前端 + TypeScript 入手，让项目跑起来，再逐步下钻到 Rust 后端与 LLM 管线。有层次感的架构值得反复研读——每轮深入都会发现上一轮忽略的设计细节。