Metadata-Version: 2.4
Name: molewikigraph
Version: 0.1.0
Summary: 开箱即用的知识库引擎——让你的 AI 助手拥有真正理解你文档的能力
Author: MoleWikiGraph Team
License: MIT
Keywords: knowledge-graph,wiki,rag,agent,mcp,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: jieba>=0.42
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.11.0; extra == "pdf"
Requires-Dist: PyMuPDF>=1.24.0; extra == "pdf"
Provides-Extra: office
Requires-Dist: python-docx>=1.1.0; extra == "office"
Requires-Dist: python-pptx>=0.6.23; extra == "office"
Requires-Dist: openpyxl>=3.1.0; extra == "office"
Provides-Extra: code
Requires-Dist: tree-sitter<0.22,>=0.21; extra == "code"
Requires-Dist: tree-sitter-languages>=1.10.0; extra == "code"
Provides-Extra: all-parsers
Requires-Dist: molewikigraph[code,office,pdf]; extra == "all-parsers"
Dynamic: license-file

# MoleWikiGraph

> 开箱即用的本地知识库引擎——让你的 AI 助手拥有真正理解你文档的能力

MoleWikiGraph 采用 **"LLM Wiki + 知识图谱 + 小型 LLM"** 三层架构，将文档自动消化为结构化知识，支持多路检索和原文回溯，提供 CLI 和 MCP Agent 两种交互方式。

## ✨ 特性

- **纯本地运行** — 所有数据存储在本地 SQLite，无需云服务，隐私安全
- **智能知识提取** — 规则提取 + LLM 消化双模式，自动从文档中提取实体、关系和摘要
- **多路并行检索** — 图谱检索 + FTS5 全文检索 + 查询改写，三路并行提升召回率
- **中文优化** — jieba 分词 + FTS5 预分词策略，原生支持中文全文搜索
- **人在回路** — Wiki 页面可人工编辑，修改通过反向同步即时生效
- **MCP Agent 集成** — 通过 MCP 协议暴露工具接口，供 AI Agent 直接调用

## 🏗 架构概览

```
┌─────────────────────────────────────────────────────────┐
│                    知识存储流程（Pipeline）                 │
│                                                         │
│  文档 ──→ 解析 ──→ 规则提取 ──→ LLM 消化 ──→ 入库       │
│            │          │            │          │          │
│         章节切分   标题/表格实体  摘要+实体    SQLite     │
│                                 关系抽取    + FTS5      │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                    问题检索流程（QueryEngine）              │
│                                                         │
│  提问 ──→ 意图分析 ──→ 三路并行检索 ──→ 评分融合 ──→ 返回  │
│            │            │              │          │      │
│         jieba/LLM   图谱+FTS5+改写   四维加权   原文回溯  │
└─────────────────────────────────────────────────────────┘
```

## 🚀 快速开始

### 1. 安装

```bash
# 克隆项目
git clone <repo-url>
cd MoleWikiGraph

# 安装依赖
pip install -e .

# 安装中文分词依赖
pip install jieba
```

### 2. 初始化知识库

```bash
mwkg init
```

### 3. 导入文档

```bash
# 规则模式（无需 LLM）
mwkg import ./docs/

# LLM 模式（需要本地 LLM 服务）
mwkg import ./docs/ --llm
```

### 4. 查询知识库

```bash
mwkg query "你的问题"
```

### 5. 安装 Trae SOLO Skill（可选）

将 MoleWikiGraph 集成到 Trae SOLO，让 AI 助手自动调用知识库：

```bash
# 在你的项目中安装 Skill
mwkg skill install --project /path/to/your/project
```

安装后，在 Trae SOLO 中重新打开项目，当提到"知识库"、"查询知识"等关键词时，AI 助手会自动调用 mwkg 命令。

> 也可以手动将 `.trae/skills/mwkg/` 目录复制到你的项目中。

## 📖 CLI 命令参考

### `mwkg init` — 初始化知识库

创建知识库目录结构和 SQLite 数据库。

```bash
mwkg init                          # 默认名称 "default"
mwkg init --name myproject         # 指定名称
mwkg init --path ./my-kb           # 指定路径
mwkg init --interactive             # 交互式向导
```

| 选项 | 说明 |
|------|------|
| `--name` | 知识库名称（默认 `default`） |
| `--path` | 知识库根目录（默认 `~/.mwkg/<name>`） |
| `--interactive` | 交互式向导模式 |

---

### `mwkg import` — 导入文档

导入文档到知识库，自动解析、提取实体和关系。

```bash
mwkg import ./docs/                    # 导入目录下所有文件
mwkg import ./report.md                # 导入单个文件
mwkg import ./docs/ -f markdown        # 只导入 Markdown 文件
mwkg import ./docs/ --no-recursive     # 不递归子目录
mwkg import ./docs/ --no-wiki          # 不生成 Wiki 页面
mwkg import ./docs/ --kb myproject     # 导入到指定知识库
mwkg import ./docs/ --llm              # 启用 LLM 消化模式
mwkg import ./docs/ --llm --llm-backend vllm --llm-url http://localhost:8000
```

| 选项 | 说明 |
|------|------|
| `PATH` | 文件或目录路径（必选） |
| `--recursive / --no-recursive` | 是否递归子目录（默认递归） |
| `-f, --format` | 限定文件格式（如 `markdown`） |
| `--no-wiki` | 不生成 Wiki 页面 |
| `--kb` | 指定知识库名称 |
| `--llm` | 启用 LLM 消化模式 |
| `--llm-backend` | LLM 后端：`ollama`（默认）/ `vllm` |
| `--llm-model` | 模型名称（默认 `qwen2.5:7b`） |
| `--llm-url` | LLM 服务地址（默认 `http://localhost:11434`） |

---

### `mwkg query` — 查询知识库

```bash
mwkg query "龙腾化工厂的污染情况"           # 文本输出
mwkg query "修复技术" --top-k 3            # 限制返回数量
mwkg query "土壤修复" --format json        # JSON 格式输出
mwkg query "API 设计" --show-scores        # 显示评分详情
```

| 选项 | 说明 |
|------|------|
| `QUESTION` | 查询问题（必选） |
| `--kb` | 指定知识库名称 |
| `--top-k` | 最大返回数量（默认 `5`） |
| `--format` | 输出格式：`text`（默认）/ `json` |
| `--show-scores` | 显示评分详情 |
| `--no-show-sources` | 不显示来源引用 |

---

### `mwkg kb` — 知识库管理

```bash
mwkg kb list                    # 列出所有知识库
mwkg kb info myproject          # 查看知识库详情
mwkg kb use myproject           # 切换活动知识库
mwkg kb delete myproject        # 删除知识库
```

| 子命令 | 说明 |
|--------|------|
| `list` | 列出所有知识库（名称、路径、文档数） |
| `info <NAME>` | 显示知识库详情（实体数、关系数、摘要数、数据库大小） |
| `use <NAME>` | 切换活动知识库 |
| `delete <NAME>` | 删除知识库（`--confirm` 跳过确认） |

---

### `mwkg config` — 配置管理

```bash
mwkg config list                # 列出所有配置项
mwkg config get llm.model       # 获取配置
mwkg config set llm.model qwen2.5:7b  # 设置配置
mwkg config validate            # 校验配置完整性
mwkg config reset               # 重置为默认值
```

| 子命令 | 说明 |
|--------|------|
| `list` | 列出所有配置项 |
| `get <KEY>` | 获取指定配置项 |
| `set <KEY> <VALUE>` | 设置配置项（支持嵌套键如 `llm.model`） |
| `validate` | 校验配置完整性 |
| `reset` | 重置为默认值 |

---

### `mwkg sync` — 同步操作

```bash
mwkg sync wiki                  # 将 Wiki 编辑同步回数据库
mwkg sync wiki --kb myproject   # 指定知识库
```

| 子命令 | 说明 |
|--------|------|
| `wiki` | 解析 `wiki/entities/` 中用户编辑的 Wiki 页面，将修改同步回 SQLite 和 FTS5 索引 |

---

### `mwkg agent` — MCP Agent 服务器

通过 MCP 协议暴露知识库工具接口，供 AI Agent（如 Claude、Trae SOLO）调用。

```bash
mwkg agent                              # 启动 stdio MCP 服务器
mwkg agent --transport list-tools        # 列出可用 MCP 工具
mwkg agent --kb myproject               # 指定知识库
```

| 选项 | 说明 |
|------|------|
| `--kb` | 指定知识库名称 |
| `--transport` | 传输协议：`stdio`（默认）/ `list-tools` |

**MCP 工具列表：**

| 工具 | 说明 |
|------|------|
| `search_knowledge` | 搜索知识库，返回最相关的知识片段 |
| `get_entity` | 获取实体详情（含 Wiki 内容和关联关系） |
| `import_documents` | 导入文档到知识库 |
| `export_chapters` | 导出章节结构，供外部 LLM 进行实体关系提取 |

---

### `mwkg export-chapters` — 导出章节结构

解析文档并导出章节 JSON，供外部 LLM（如 Trae SOLO 内置 LLM）进行实体关系提取。

```bash
mwkg export-chapters "报告.docx"                    # 导出到 stdout
mwkg export-chapters "报告.docx" -o chapters.json    # 导出到文件
mwkg export-chapters "报告.docx" --with-prompts      # 包含 LLM 提取 prompt 模板
mwkg export-chapters "报告.docx" --max-chars 4000    # 限制单章节字符数
```

| 选项 | 说明 |
|------|------|
| `PATH` | 文档路径（必选） |
| `-o, --output` | 输出 JSON 文件路径（默认 stdout） |
| `--with-prompts` | 同时输出 LLM 提取 prompt 模板 |
| `--max-chars` | 单章节最大字符数（默认 8000） |

---

### `mwkg import-extractions` — 导入 LLM 提取结果

将外部 LLM 提取的实体、关系、摘要导入知识库。

```bash
mwkg import-extractions extractions.json --kb myproject --source-doc "报告.docx"
```

| 选项 | 说明 |
|------|------|
| `INPUT_FILE` | 提取结果 JSON 文件（必选） |
| `--kb` | 指定知识库名称（必选） |
| `--doc-id` | 文档 ID（默认从 JSON 中读取） |
| `--source-doc` | 来源文档文件名 |

---

### `mwkg skill` — Skill 管理

生成和安装 Trae SOLO / Claude Code Skill 文件。

```bash
mwkg skill generate                     # 生成到当前目录 .trae/skills/mwkg/
mwkg skill generate --output /path/to   # 指定输出目录
mwkg skill generate --force             # 覆盖已存在的文件
mwkg skill install                      # 安装到当前项目
mwkg skill install --project /path/to   # 安装到指定项目
```

| 子命令 | 说明 |
|--------|------|
| `generate` | 生成 skill.json + skill.md + README.md |
| `install` | 安装 Skill 到指定项目的 `.trae/skills/mwkg/` 目录 |

| 选项 | 说明 |
|------|------|
| `--output, -o` | 输出目录（generate 命令） |
| `--project, -p` | 目标项目路径（install 命令） |
| `--force` | 覆盖已存在的文件 |
| `--json-only` | 仅生成 skill.json（不生成 skill.md 和 README.md） |

---

### 全局选项

```bash
mwkg -v query "测试"    # 启用详细日志（DEBUG 级别）
```

| 选项 | 说明 |
|------|------|
| `-v, --verbose` | 启用详细输出 |

## 📊 功能清单

### 已完成

| 功能 | 说明 |
|------|------|
| 多格式文档解析 | Markdown、Word（docx）、PDF、Excel（xlsx）、PPT（pptx）、代码文件解析，章节切分 |
| 编号标题识别 | 自动识别"第X章"、"X.X"、"X.X.X"等编号格式的标题（Word 文档） |
| 规则提取 | 标题实体 + 表格实体 + 内容实体（组织、项目、技术、政策法规）自动提取 |
| LLM 摘要生成 | 基于本地 LLM 生成章节摘要和关键句 |
| LLM 实体关系抽取 | 与规则提取结果合并去重 |
| JSON 截断恢复 | LLM 输出被 max_tokens 截断时自动修复，保留已完整解析的实体/关系 |
| FTS5 全文检索 | SQLite FTS5 + jieba 预分词，BM25 评分 |
| 图谱检索 | 实体匹配 + 2 跳关系遍历 |
| 查询改写 | LLM 改写模糊查询，补偿语义检索缺失 |
| 四维评分融合 | entity_match + relation_match + semantic_sim + position_weight |
| 原文回溯 | 段落级定位 + 上下文窗口 + key_sentences 兜底 |
| Wiki 页面生成 | 实体 Wiki（YAML Frontmatter）+ 文档 Wiki + 索引页 |
| Wiki 反向同步 | `mwkg sync wiki` 将编辑同步回数据库 |
| originals/ 原文存储 | Pipeline 导入时自动复制原始文件 |
| summary_entities 关联表 | 摘要-实体多对多映射 |
| entities_fts 实体索引 | 实体全文索引，图谱检索 BM25 快速匹配 |
| relation_match 评分 | 基于关联实体的关系覆盖率计算 |
| MCP Server | stdio 传输协议，4 个工具（search/get/import/export_chapters） |
| 多知识库管理 | 创建、切换、删除知识库 |
| Trae SOLO Skill | 自动生成并安装 Skill（`mwkg skill install`） |
| LLM 辅助导入 | Skill 编排模式，使用 AI 助手内置 LLM 进行实体关系提取 |
| export-chapters / import-extractions | 导出章节供外部 LLM 提取，导入提取结果 |

### 规划中

| 功能 | 说明 |
|------|------|
| 增量更新 | 文档变更检测和增量处理 |
| 向量检索 | sqlite-vec 语义向量搜索（当前 FTS5 已达 92% 召回率） |

## 📁 知识库目录结构

```
<kb_path>/
├── mwkg.db              # SQLite 数据库（含 FTS5 索引）
├── wiki/
│   ├── entities/        # 实体 Wiki 页面（YAML Frontmatter + Markdown）
│   ├── documents/       # 文档 Wiki 页面
│   └── index.md         # 知识库索引页
├── originals/           # 原始文档副本（用于原文回溯）
├── pipelines/           # 管道中间产物
└── logs/                # 日志文件
```

全局配置：`~/.mwkg/config.yaml`
知识库注册表：`~/.mwkg/registries.json`

## 🔀 三种运行模式

| 特性 | 规则模式（默认） | LLM 模式（`--llm`） | Skill 编排模式 |
|------|:---:|:---:|:---:|
| 文档解析 | ✅ | ✅ | ✅ |
| 规则实体提取 | ✅ | ✅ | ✅ |
| LLM 摘要生成 | ❌ | ✅ | ✅（AI 助手内置 LLM） |
| LLM 实体关系抽取 | ❌ | ✅ | ✅（AI 助手内置 LLM） |
| Wiki 页面生成 | ✅ | ✅ | ✅ |
| FTS5 全文检索 | ✅ | ✅ | ✅ |
| 图谱检索 | ✅ | ✅ | ✅ |
| LLM 意图分析 | ❌（jieba 分词） | ✅ | ❌ |
| 查询改写 | ❌ | ✅ | ❌ |
| 原文回溯 | 降级到摘要 | 段落级 + 上下文 | 段落级 + 上下文 |
| 需要 LLM 服务 | ❌ | ✅（Ollama/vLLM） | ❌（AI 助手内置） |

> - **规则模式**：无需 LLM 服务，适合快速体验
> - **LLM 模式**：需要本地运行 Ollama 或 vLLM，提供更高质量的摘要和检索
> - **Skill 编排模式**：通过 `mwkg export-chapters` + `mwkg import-extractions`，利用 Trae SOLO 等 AI 助手的内置 LLM 进行实体关系提取，无需额外配置 LLM 服务

## 🛠 技术栈

- **Python 3.10+**
- **SQLite FTS5** — 全文搜索引擎
- **jieba** — 中文分词
- **Click** — CLI 框架
- **Ollama / vLLM** — 本地 LLM 推理（可选）
- **MCP** — Agent 工具协议（可选）

## 🔄 与其他项目的对比

MoleWikiGraph 与 GBrain、LLM Wiki 等项目解决的是不同层面的问题，可以互补使用：

| 维度 | MoleWikiGraph | GBrain | LLM Wiki |
|------|:---:|:---:|:---:|
| **定位** | 文档知识库引擎 | AI Agent 记忆系统 | 知识组织方法论 |
| **核心问题** | AI 不理解你的文档 | AI 记不住你的交互 | AI 知识怎么组织 |
| **知识来源** | 文档（MD/PDF/Word/PPT/Excel） | 多源（邮件/日历/通话/会议） | 文本资料 |
| **中文支持** | ✅ 原生（jieba + FTS5） | ❌ 无针对性优化 | ❌ 无针对性优化 |
| **LLM 依赖** | 可选（规则模式零依赖） | 强依赖（OpenAI + Anthropic） | 可选 |
| **隐私性** | 纯本地，零云端调用 | 需要 OpenAI/Anthropic API | 本地 Markdown |
| **知识图谱** | 实体-关系图 + N 跳遍历 | 页面链接图谱 | 无 |
| **原文回溯** | 段落级精准定位 | 无 | 无 |
| **安装复杂度** | `pip install` 即用 | 需 AI Agent + API Key | 零配置 |

> 详细对比分析见 [docs/molewikigraph-vs-gbrain.md](docs/molewikigraph-vs-gbrain.md)

## 📄 许可证

[MIT](LICENSE)
