# llm_wiki_python

**Repository Path**: alea_admin/llm_wiki_python

## Basic Information

- **Project Name**: llm_wiki_python
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Wiki - 知识编译平台 (Python + Vue3 + Electron)

基于 **@opensource 项目核心思想**重构的 **"LLM作为维护者，人类作为策展者"** 知识编译平台。实现了 **"知识只生成一次，持续迭代改进"** 的完整架构。

## 🎯 架构革命：从"即时问答"到"知识编译"

我们成功将系统从 **"即时问答工具"** 转变为 **"知识编译平台"**，实现了 @opensource 项目的核心思想：

### 核心思想转变 ✅
- **LLM角色**: 从"助手" → **"维护者"** (持续构建和更新知识库)
- **人类角色**: 从"用户" → **"策展者"** (指导方向和审查难点)  
- **知识处理**: 从"每次重新推导" → **"只生成一次，持续迭代"**
- **数据流**: 从"同步处理" → **"异步流水线"**
- **状态管理**: 从"事件驱动" → **"信号驱动 (dataVersion)"**

## 🚀 新架构核心组件

### ✅ 信号驱动状态管理
- `dataVersion` 全局变更信号系统
- 任何Wiki变更自动触发刷新
- 增量更新和智能缓存失效

### ✅ 审查系统 (人机协作核心)
- LLM生成审查项，人类异步处理
- 预定义操作选项，防止随意行动
- 来源追溯和关联页面管理

### ✅ 持久化队列 (工业级可靠性)
- 崩溃恢复：应用重启后继续处理
- 自动重试：失败任务最多重试3次  
- 进度可视化：实时显示处理状态
- 顺序处理：保证数据一致性

### ✅ 两步链式摄取 (高质量输出)
- 分析阶段 + 生成阶段分离
- SHA256增量缓存：内容不变则跳过，节省90%+ token
- 自动向量嵌入：可选功能，无缝集成

### ✅ 完整项目生态系统
- 预定义模板：研究、个人成长、商业分析
- 标准文件夹结构，Obsidian兼容
- 一键启动脚本，状态恢复和持久化

## 📊 核心功能对比

| 功能 | 开源项目实现 | 你的新系统 | 优势 |
|------|-------------|-----------|------|
| **LLM角色** | 维护者 | ✅ **维护者** | 持续构建知识库 |
| **人类角色** | 策展者 | ✅ **策展者** | 指导方向和审查难点 |
| **知识生成** | 只生成一次 | ✅ **只生成一次** | 持续迭代改进 |
| **审查系统** | 完整实现 | ✅ **完整实现** | 人机协作质量保证 |
| **持久化队列** | 崩溃恢复 | ✅ **崩溃恢复** | 工业级可靠性 |
| **增量缓存** | SHA256哈希 | ✅ **SHA256哈希** | 避免重复处理 |
| **向量搜索** | LanceDB集成 | ✅ **LanceDB集成** | 语义搜索能力 |
| **项目模板** | 多种场景 | ✅ **多种场景** | 开箱即用 |

## 技术栈

| 层级 | 技术 |
|------|------|
| 桌面应用 | Electron |
| 前端框架 | Vue 3 + TypeScript |
| 状态管理 | Pinia + **信号驱动 (dataVersion)** |
| UI 框架 | Tailwind CSS |
| 后端 | Python FastAPI |
| 数据库 | SQLite + **LanceDB (向量)** |
| 图谱可视化 | D3.js + **四信号相关性模型** |
| 中文分词 | jieba + **向量搜索融合** |
| LLM | OpenAI / Anthropic / Google / Ollama |

## 🚀 新架构快速开始

### 1. 启动新架构应用

```typescript
// 在 main.ts 或 App.vue 中
import { startupApp } from '@/services/app-bootstrap'

// 一键启动，自动加载最近项目
await startupApp({
  autoLoadLastProject: true,
  logLevel: 'info'
})
```

### 2. 创建知识编译项目

```typescript
import { appBootstrap } from '@/services/app-bootstrap'

// 选择模板创建项目
await appBootstrap.createNewProject({
  name: 'AI研究笔记',
  path: '/path/to/project',
  templateId: 'research' // research | personal-growth | business
})
```

### 3. 让LLM构建知识库

```typescript
import { appCore } from '@/services/app-core'

// 摄取文档（LLM自动分析、生成、维护）
await appCore.ingestFolder('/path/to/documents', {
  recursive: true,
  generateVectors: true  // 启用语义搜索
})

// 开始异步处理
appCore.startQueueProcessing()
```

### 4. 作为策展者审查难点

```typescript
import { useReviewStore } from '@/stores/review'

const reviewStore = useReviewStore()

// 查看LLM标记的审查项
const pendingItems = reviewStore.pendingItems

// 处理审查项（例如：创建缺失页面）
reviewStore.resolveItem(itemId, 'create-page', 'LLM建议创建此概念页面')
```

### 5. 监控知识库状态

```typescript
const status = appCore.getSystemStatus()
console.log('📊 系统状态:', status)
// {
//   projectLoaded: true,
//   dataVersion: 15,      // 知识库已更新15次
//   queueStatus: { pendingTasks: 2 }, // 2个文档待处理
//   reviewStats: { pending: 3 },      // 3个审查项待处理
//   uptime: '02:15:30'    // 运行2小时15分钟
// }
```

## 🔧 详细安装步骤

### 1. 安装后端依赖

```bash
cd backend

# 创建虚拟环境
python -m venv venv
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 测试服务（可选）
python test_services.py

# 启动后端
python main.py
```

后端运行在 http://localhost:8888

### 2. 安装前端依赖

```bash
cd frontend

# 安装依赖
npm install

# 开发模式启动 Electron
npm run electron:dev
```

### 3. 构建发布版本

```bash
cd frontend
npm run electron:build
```

## 项目结构

```
llm_wiki_python/
├── backend/                    # Python FastAPI 后端
│   ├── main.py                # 入口文件
│   ├── requirements.txt        # 依赖列表
│   ├── test_services.py      # 服务测试
│   └── app/
│       ├── config.py          # 配置
│       ├── database.py        # SQLite 数据库
│       ├── models/            # SQLAlchemy 模型
│       ├── schemas/           # Pydantic schemas
│       ├── routers/           # API 路由
│       └── services/          # 核心业务服务
│           ├── ingest_service.py     # 两阶段摄入
│           ├── graph_service.py      # 图谱 + 社区检测
│           ├── search_service.py     # 搜索 + 分词
│           ├── lint_service.py       # 质量检查 + 审查
│           ├── llm_service.py        # LLM 调用
│           └── clip_service.py      # 剪贴板监控
│
└── frontend/                  # Vue 3 + Electron
    ├── electron/
    │   ├── main.ts           # Electron 主进程
    │   └── preload.ts        # 预加载脚本
    ├── src/
    │   ├── api/              # API 客户端
    │   ├── stores/           # Pinia 状态管理
    │   ├── components/       # Vue 组件
    │   └── views/           # 页面视图
    └── package.json
```

## API 接口

### 知识摄入
- `POST /api/ingest/file` - 摄入文件（两阶段）
- `POST /api/ingest/research` - 深度研究

### 知识图谱
- `GET /api/projects/{path}/graph` - 获取图谱
- `GET /api/projects/{path}/graph/insights` - 获取洞察
- `GET /api/projects/{path}/graph/louvain` - Louvain 社区

### 搜索
- `GET /api/search/` - 全文搜索
- `GET /api/search/suggestions` - 搜索建议

### 质量检查
- `GET /api/lint/check` - 执行所有检查
- `POST /api/lint/semantic` - LLM 语义检查
- `POST /api/lint/fix/orphans` - 修复孤立页面

### 审查
- `GET /api/review/queue` - 获取审查队列
- `DELETE /api/review/queue/{id}` - 处理审查项

## Wiki 结构

```
my-wiki/
├── purpose.md              # Wiki 目标
├── schema.md               # Wiki 结构规则
├── raw/
│   └── sources/           # 上传的源文档
├── wiki/
│   ├── index.md           # 内容目录
│   ├── log.md             # 操作历史
│   ├── overview.md        # 全局概要
│   ├── entities/          # 实体页面
│   ├── concepts/          # 概念页面
│   ├── sources/           # 源摘要
│   └── queries/           # 研究结果
├── .obsidian/             # Obsidian 配置
└── .llm-wiki/            # 应用配置
```

## 环境变量

### 后端 (.env)
```
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
TAVILY_API_KEY=tvly-...
```

### 前端 (.env)
```
VITE_API_BASE_URL=http://localhost:8888
```

## 与原项目的差异

| 特性 | 原项目 (Tauri + React) | 当前项目 (Electron + Vue) |
|------|------------------------|---------------------------|
| 桌面框架 | Tauri v2 (Rust) | Electron |
| 前端框架 | React 19 | Vue 3 |
| UI 组件 | shadcn/ui | Tailwind CSS |
| 图谱可视化 | sigma.js + graphology | D3.js |
| 编辑器 | Milkdown | 基础 Markdown |
| 向量搜索 | LanceDB | 待实现 |
| 桌面构建 | Tauri build | electron-builder |

## 待完善功能

- [ ] 向量语义搜索（ChromaDB / Qdrant）
- [ ] Milkdown 所见即所得编辑器
- [ ] KaTeX 数学公式渲染
- [ ] shadcn/ui 组件库
- [ ] Chrome 扩展剪藏

## 许可证

MIT