# labwiki

**Repository Path**: lonlier/labwiki

## Basic Information

- **Project Name**: labwiki
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LabWiki-Qoder: LLM 驱动的个人知识库

## Context

构建一个 Python 桌面端应用，核心理念：LLM 逐步构建并维护一个持久化 wiki（结构化 Markdown + 知识图谱），而非传统 RAG 每次查询从头检索。新文档添加时，LLM 读取、提取、整合到现有 wiki，知识编译一次并持续积累。

**技术选型（用户确认）**：Web UI (FastAPI + Vanilla JS) | 多模型 LangChain | 全格式文件 | 交互式图谱 (networkx + force-graph)

---

## 1. 项目结构

```
labwiki-qoder/
├── main.py                        # uvicorn 启动入口
├── pyproject.toml
├── .env.example
├── labwiki/                       # 后端包
│   ├── __init__.py
│   ├── app.py                     # FastAPI 工厂 + 静态文件
│   ├── config.py                  # Pydantic Settings
│   ├── api/                       # API 层
│   │   ├── __init__.py
│   │   ├── router.py              # 总路由
│   │   ├── workspace.py           # 知识库创建/打开
│   │   ├── resources.py           # 资源上传/导入(SSE)
│   │   ├── wiki.py                # Wiki CRUD + 搜索
│   │   ├── chat.py                # 对话(WebSocket)
│   │   ├── graph.py               # 图谱查询/导出
│   │   ├── health.py              # 健康检查
│   │   └── settings.py            # 配置管理
│   ├── core/                      # 业务引擎
│   │   ├── __init__.py
│   │   ├── workspace.py           # Workspace 管理器
│   │   ├── schema_manager.py      # Schema -> 提示词
│   │   ├── wiki_engine.py         # 页面CRUD + 索引 + 交叉引用
│   │   ├── graph_engine.py        # 图谱构建/查询/持久化
│   │   ├── import_pipeline.py     # 导入流水线(核心)
│   │   ├── query_pipeline.py      # 查询流水线
│   │   ├── health_checker.py      # 检查引擎
│   │   └── log_manager.py         # log.md 管理
│   ├── llm/                       # LLM 集成
│   │   ├── __init__.py
│   │   ├── provider.py            # LangChain 模型工厂
│   │   ├── chains.py              # 业务 Chain
│   │   └── prompts.py             # 提示词模板
│   ├── loaders/                   # 文档加载
│   │   ├── __init__.py
│   │   └── loader_factory.py      # 文件类型分发
│   └── models/                    # Pydantic 模型
│       ├── __init__.py
│       ├── resource.py
│       ├── wiki_page.py
│       ├── graph.py
│       └── chat.py
├── frontend/                      # 前端 SPA(无构建)
│   ├── index.html
│   ├── css/style.css              # Tailwind CDN + 自定义
│   └── js/
│       ├── app.js                 # 路由 + 状态
│       ├── api.js                 # API 封装
│       └── components/
│           ├── sidebar.js         # 页面树 + 资源列表
│           ├── wiki-viewer.js     # Markdown 渲染 + 内链
│           ├── chat-panel.js      # 对话面板
│           ├── graph-viewer.js    # 知识图谱可视化
│           ├── upload-dialog.js   # 资源上传
│           └── settings-page.js   # 设置页
└── tests/
```

### Workspace（知识库）目录结构

每个知识库是独立的自包含目录：

```
my-knowledge-base/
├── .labwiki/
│   ├── schema.yaml          # Schema 配置（指导 LLM 行为）
│   ├── graph.json           # 知识图谱持久化
│   └── config.json          # 知识库局部配置
├── resources/               # 原始资源（不可变）
│   └── _manifest.json       # 资源清单（哈希、导入时间、状态）
├── wiki/                    # LLM 生成的 Wiki
│   ├── index.md
│   ├── log.md
│   ├── summaries/           # 资源摘要页
│   ├── entities/            # 实体页
│   ├── concepts/            # 概念页
│   ├── topics/              # 主题综述页
│   └── comparisons/         # 对比页
└── chat_history/            # 对话历史
```

---

## 2. API 设计

### Workspace

| 方法 | 路径                       | 说明           |
| ---- | -------------------------- | -------------- |
| POST | `/api/workspace/create`  | 创建新知识库   |
| POST | `/api/workspace/open`    | 打开已有知识库 |
| GET  | `/api/workspace/current` | 当前知识库信息 |
| GET  | `/api/workspace/recent`  | 最近打开列表   |

### Resources

| 方法   | 路径                           | 说明              |
| ------ | ------------------------------ | ----------------- |
| POST   | `/api/resources/upload`      | 上传资源          |
| GET    | `/api/resources`             | 列出所有资源      |
| DELETE | `/api/resources/{id}`        | 删除资源          |
| POST   | `/api/resources/{id}/import` | 触发导入(SSE流式) |

### Wiki

| 方法   | 路径                       | 说明     |
| ------ | -------------------------- | -------- |
| GET    | `/api/wiki/pages`        | 页面树   |
| GET    | `/api/wiki/pages/{path}` | 读取页面 |
| PUT    | `/api/wiki/pages/{path}` | 编辑页面 |
| DELETE | `/api/wiki/pages/{path}` | 删除页面 |
| GET    | `/api/wiki/search?q=`    | 全文搜索 |

### Chat (WebSocket)

| 方法 | 路径                  | 说明             |
| ---- | --------------------- | ---------------- |
| WS   | `/ws/chat`          | 实时对话(流式)   |
| GET  | `/api/chat/history` | 对话历史         |
| POST | `/api/chat/archive` | 归档回答为wiki页 |

### Graph

| 方法 | 路径                                        | 说明          |
| ---- | ------------------------------------------- | ------------- |
| GET  | `/api/graph`                              | 完整图谱 JSON |
| GET  | `/api/graph/subgraph?center={id}&depth=2` | 局部子图      |

### Health & Settings

| 方法    | 路径                              | 说明              |
| ------- | --------------------------------- | ----------------- |
| POST    | `/api/health/check`             | 触发健康检查(SSE) |
| GET/PUT | `/api/settings`                 | 读写配置          |
| POST    | `/api/settings/test-connection` | 测试LLM连接       |

---

## 3. 核心引擎设计

### A) Workspace 管理器 (`core/workspace.py`)

- 持有当前 workspace 根路径，提供路径解析（resources_dir, wiki_dir 等）
- 初始化新 workspace：创建目录结构 + 默认 schema.yaml + 空 index.md/log.md/graph.json
- 验证已有目录合法性（检查 `.labwiki/`）
- FastAPI 依赖注入单例

### B) Schema 管理器 (`core/schema_manager.py`)

- 读写 `.labwiki/schema.yaml`，将其转化为 LLM 系统提示词
- schema 内容：wiki 目录约定、命名规范(kebab-case)、内链格式(`[[page-name]]`)、页面模板、图谱节点/边类型、导入流程步骤
- `build_system_prompt(task: str) -> str` 根据任务类型构建提示词

### C) Wiki 引擎 (`core/wiki_engine.py`)

- `list_pages()` 扫描 wiki 目录返回页面树
- `read_page() / write_page() / delete_page()` 页面 CRUD
- `update_index()` 重写 index.md（LLM 生成受影响条目）
- `search_pages(query)` 全文搜索
- `find_backlinks(page)` 查找反向链接
- `extract_wiki_links(content)` 解析 `[[内链]]`
- 内链约定：`[[page-name]]` 格式，渲染前转换为实际链接

### D) 图谱引擎 (`core/graph_engine.py`)

- 内存模型：networkx DiGraph；持久化：`.labwiki/graph.json`
- 节点：`{id, label, type, wiki_page, properties}`
- 边：`{source, target, relation, weight}`
- `merge_extracted(nodes, edges)` 合并 LLM 提取的新数据（去重 + 模糊匹配）
- `get_full_graph()` 导出 JSON 供前端可视化

### E) 导入流水线 (`core/import_pipeline.py`) — 最核心

```
Step 1: 加载文档 (loader_factory)
Step 2: LLM 初步分析 → 摘要、实体、概念、论点
Step 3: 用户讨论(可选) → 通过 WebSocket 交互
Step 4: 生成摘要页 → wiki/summaries/{name}.md
Step 5: 图谱提取 → LLM 提取三元组，merge 到图谱
Step 6: 关联分析 → 确定需更新/新建的页面
Step 7: 页面更新 → LLM 融合新信息更新 5-10 个页面
Step 8: 索引更新 → 重写 index.md 受影响条目
Step 9: 日志记录 → 追加 log.md
Step 10: 图谱持久化 → 写 graph.json
```

每步通过 SSE 向前端发送进度事件。

### F) 查询流水线 (`core/query_pipeline.py`)

1. 搜索 wiki 页面 + 图谱节点找相关上下文
2. 读取相关页面全文构建 LLM 上下文
3. LLM 流式生成回答（含 wiki 引用）
4. 可选归档为新 wiki 页面

### G) 健康检查器 (`core/health_checker.py`)

- 孤儿页面、断裂链接、缺失交叉引用（程序化检测）
- 矛盾、过时声明、数据缺口（LLM 辅助检测）

### H) 日志管理器 (`core/log_manager.py`)

- 追加格式：`## [2026-04-10 14:32] Import: filename`
- 记录创建/更新的页面、图谱变化、耗时

---

## 4. LLM 集成层

### Provider (`llm/provider.py`)

- `get_chat_model(provider, model, **kwargs) -> BaseChatModel`
- 支持：openai, anthropic, ollama, azure_openai
- 延迟导入，不强依赖所有 SDK

### Chains (`llm/chains.py`)

- SummarizeChain: 文档 → 结构化摘要页
- EntityExtractChain: 文档 → 实体列表
- GraphExtractChain: 文档 → 三元组 (subject, relation, object)
- PageUpdateChain: 现有页面 + 新信息 → 更新后页面
- IndexUpdateChain: 受影响页面 → index.md 条目
- QueryChain: wiki 上下文 + 问题 → 带引用的回答
- HealthCheckChain: 页面集合 → 问题列表

### 文档加载 (`loaders/loader_factory.py`)

| 类型     | 加载器         | 依赖           |
| -------- | -------------- | -------------- |
| .md/.txt | TextLoader     | -              |
| .pdf     | PyPDFLoader    | pypdf          |
| .docx    | Docx2txtLoader | docx2txt       |
| .html    | BSHTMLLoader   | beautifulsoup4 |
| .csv     | CSVLoader      | -              |
| 图片     | LLM 视觉 API   | -              |

---

## 5. 前端设计

### 布局

```
┌──────────────────────────────────────────────────┐
│  LabWiki  [知识库名]              [设置] [切换]    │
├─────────┬──────────────────────┬─────────────────┤
│ 侧边栏  │     主内容区          │   聊天面板       │
│         │                      │                 │
│ Wiki树  │ Wiki页面渲染          │  对话历史        │
│ 资源列表 │ 或 知识图谱可视化     │  输入框+发送     │
│ [上传]  │ 或 导入进度           │                 │
├─────────┴──────────────────────┴─────────────────┤
│ 状态栏: LLM连接 | 模型 | 节点数 | 最后操作        │
└──────────────────────────────────────────────────┘
```

### 技术栈（无构建工具）

- Tailwind CSS (CDN) — UI 样式
- markdown-it — Markdown 渲染 + 自定义 `[[内链]]` 插件
- force-graph (D3) — 知识图谱可视化
- 原生 WebSocket — 对话
- EventSource — SSE 导入进度

---

## 6. 依赖 (pyproject.toml)

```toml
dependencies = [
    # Web
    "fastapi",
    "uvicorn[standard]",
    "python-multipart",
    "websockets",
    "aiofiles",
    # LLM
    "langchain-core",
    "langchain-openai",
    "langchain-anthropic",
    "langchain-community",
    # 文档加载
    "pypdf",
    "docx2txt",
    "beautifulsoup4",
    # 图谱
    "networkx",
    # 配置
    "pydantic-settings",
    "pyyaml",
]
```

---

## 7. 实现阶段

### Phase 1: 骨架搭建

**目标**：启动 Web 服务，创建/打开知识库，看到基本 UI

- 创建项目目录结构 + 安装依赖
- `labwiki/app.py` FastAPI 工厂 + 静态文件
- `labwiki/config.py` 配置
- `labwiki/core/workspace.py` 知识库创建/打开
- `labwiki/api/workspace.py` API
- `frontend/index.html` 基本布局
- `main.py` uvicorn 启动

**关键文件**: `labwiki/app.py`, `labwiki/core/workspace.py`, `frontend/index.html`, `main.py`

### Phase 2: Wiki 引擎 + 浏览

**目标**：浏览和编辑 Wiki 页面

- `labwiki/core/wiki_engine.py` 页面 CRUD
- `labwiki/core/log_manager.py` 日志
- `labwiki/api/wiki.py` API
- `frontend/js/components/wiki-viewer.js` Markdown 渲染
- `frontend/js/components/sidebar.js` 页面树

**关键文件**: `labwiki/core/wiki_engine.py`, `labwiki/api/wiki.py`

### Phase 3: LLM 集成 + 对话

**目标**：配置 LLM 并对话

- `labwiki/llm/provider.py` 模型工厂
- `labwiki/llm/prompts.py` 提示词
- `labwiki/core/schema_manager.py` Schema
- `labwiki/api/chat.py` WebSocket
- `labwiki/api/settings.py` 配置 API
- `frontend/js/components/chat-panel.js`
- `frontend/js/components/settings-page.js`

**关键文件**: `labwiki/llm/provider.py`, `labwiki/llm/chains.py`, `labwiki/api/chat.py`

### Phase 4: 文档加载 + 导入流水线

**目标**：上传资源并触发完整导入

- `labwiki/loaders/loader_factory.py` 文档加载
- `labwiki/llm/chains.py` 业务 Chain（摘要/实体提取/页面更新）
- `labwiki/core/import_pipeline.py` 导入编排
- `labwiki/api/resources.py` 上传 + 导入 API(SSE)
- `frontend/js/components/upload-dialog.js` 上传 + 进度

**关键文件**: `labwiki/core/import_pipeline.py`, `labwiki/loaders/loader_factory.py`

### Phase 5: 知识图谱

**目标**：图谱构建和可视化

- `labwiki/core/graph_engine.py` 图谱引擎
- `labwiki/api/graph.py` 图谱 API
- 导入流水线集成图谱提取
- `frontend/js/components/graph-viewer.js` 力导向图

**关键文件**: `labwiki/core/graph_engine.py`, `frontend/js/components/graph-viewer.js`

### Phase 6: 查询流水线 + 健康检查

**目标**：Wiki 上下文查询和维护功能

- `labwiki/core/query_pipeline.py` 查询
- `labwiki/core/health_checker.py` 检查
- `labwiki/api/health.py` API
- 前端集成引用跳转 + 检查报告

**关键文件**: `labwiki/core/query_pipeline.py`, `labwiki/core/health_checker.py`

### Phase 7: 打磨增强

- 对话归档为 wiki 页面
- 导入中的用户讨论交互
- 图谱子图视图
- 搜索增强 + 错误处理

---

## 8. 验证方式

1. **Phase 1 验证**：`uv run main.py` 启动服务 → 浏览器打开 `http://localhost:8000` → 创建知识库 → 验证目录结构生成正确
2. **Phase 2 验证**：创建知识库后 → 侧边栏显示 index.md/log.md → 点击查看渲染 → 手动编辑保存
3. **Phase 3 验证**：设置页配置 API Key → 测试连接成功 → 聊天面板发消息 → LLM 流式回复
4. **Phase 4 验证**：上传 PDF/MD → 触发导入 → SSE 进度显示 → wiki 中出现摘要页/实体页 → index.md 更新
5. **Phase 5 验证**：导入后 → 图谱视图显示节点和边 → 点击节点跳转 wiki 页面
6. **Phase 6 验证**：聊天中提问 → 回答引用 wiki 页面 → 触发健康检查 → 显示问题报告