# LLMWiki

自动化的 LLM 驱动知识库生成工具。将原始文档（Markdown 文件）通过大语言模型分析，自动整理为结构化的双链知识库（Wiki）。

## 核心功能

- **两阶段智能处理**：先分析源文档生成结构化报告，再根据分析结果生成 Wiki 页面
- **增量导入与缓存**：基于内容哈希的缓存机制，源文件未变化时自动跳过 LLM 调用
- **OpenAI 兼容接口**：支持任何 OpenAI 兼容的 LLM 服务端（LM Studio、Ollama、vLLM 等）
- **流式传输**：使用 SSE 流式接收响应，避免长时间等待导致的连接超时
- **自动语言检测**：根据源文档内容自动匹配输出语言
- **结构化输出**：生成带 YAML frontmatter 的标准 Markdown 页面，支持 `[[wikilink]]` 双链引用

## 技术栈

- Python >= 3.12
- [uv](https://github.com/astral-sh/uv) — 包管理与运行环境
- [llama-index](https://github.com/run-llama/llama_index) — LLM 客户端
- [ruff](https://github.com/astral-sh/ruff) — 代码检查与格式化
- [mypy](https://github.com/python/mypy) — 静态类型检查

## 快速开始

### 1. 环境准备

全局安装 uv（如果尚未安装）：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 克隆并安装依赖

```bash
git clone <repo-url>
cd LLMWiki
python tasks.py install
```

### 3. 配置 LLM

编辑 `config.json`，设置你的 LLM 服务端信息：

```json
{
    "language": "Chinese",
    "raw_dir": "raw/sources",
    "wiki_dir": "wiki",
    "llm": {
        "model": "qwen/qwen3.6-27b",
        "api_base": "http://100.123.83.113:1234/v1",
        "api_key": "123456"
    }
}
```

| 配置项 | 说明 |
|--------|------|
| `language` | 输出语言，支持 `Chinese`、`English` 或 `auto`（自动检测） |
| `raw_dir` | 源文档目录，默认 `raw/sources` |
| `wiki_dir` | Wiki 输出目录，默认 `wiki` |
| `llm.model` | LLM 模型名称 |
| `llm.api_base` | OpenAI 兼容 API 地址（需包含 `/v1` 后缀） |
| `llm.api_key` | API 密钥 |

### 4. 准备源文档

将需要分析的 Markdown 文件放入 `raw/sources/` 目录下。支持按文件夹分类组织。

```
raw/sources/
├── DTU/
│   ├── DTU－Distribution Terminal Unit.md
│   └── RTU－Remote Terminal Unit.md
└── ...
```

### 5. 运行

```bash
python tasks.py run
```

日志会同时输出到终端和 `llmwiki.log` 文件。

## 处理流程

```
raw/sources/*.md
    │
    ▼
┌─────────────┐
│  缓存检查    │  ← 内容未变化则跳过
└──────┬──────┘
       ▼
┌─────────────┐
│ Step 1      │  ← 分析源文档，生成结构化报告
│  分析       │     （关键实体、概念、论点、关联、建议）
└──────┬──────┘
       ▼
┌─────────────┐
│ Step 2      │  ← 根据分析生成 Wiki 页面
│  生成       │     （FILE 块 + REVIEW 块）
└──────┬──────┘
       ▼
┌─────────────┐
│ Step 3      │  ← 解析 FILE 块，写入 wiki/ 目录
│  写入       │
└──────┬──────┘
       ▼
┌─────────────┐
│ Step 4      │  ← 保存缓存，下次相同内容直接命中
│  缓存       │
└─────────────┘
```

## 项目结构

```
├── src/
│   ├── main.py          # 执行入口
│   ├── config.py        # 配置加载
│   ├── llm.py           # LLM 客户端（分析 + 生成）
│   ├── prompt.py        # 提示词构建
│   ├── source.py        # 源文件路径处理
│   ├── ingest_cache.py  # 导入缓存
│   └── wiki_writer.py   # Wiki 文件解析与写入
├── tests/               # 测试用例
├── raw/sources/         # 源文档目录
├── wiki/                # 生成的 Wiki 知识库
├── config.json          # 配置文件
├── tasks.py             # 任务运行器
└── pyproject.toml       # 项目依赖与工具配置
```

## 可用命令

| 命令 | 说明 |
|------|------|
| `python tasks.py install` | 安装依赖并配置 pre-commit |
| `python tasks.py run` | 执行主流程 |
| `python tasks.py check` | 运行代码检查（ruff + mypy + deptry） |
| `python tasks.py test` | 运行测试套件 |
| `python tasks.py clean` | 清理缓存目录 |

## Wiki 页面类型

生成的 Wiki 页面支持以下类型：

- **source** — 源文档摘要页面
- **entity** — 关键实体（产品、芯片、算法等）
- **concept** — 关键概念（理论、方法、技术等）
- **query** — 查询页面
- **synthesis** — 综合页面
- **comparison** — 对比页面

## 许可证

MIT License