molewikigraph 0.1.0

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

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. 安装

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

# 安装依赖
pip install -e .

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

2. 初始化知识库

mwkg init

3. 导入文档

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

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

4. 查询知识库

mwkg query "你的问题"

5. 安装 Trae SOLO Skill（可选）

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

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

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

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

📖 CLI 命令参考

mwkg init — 初始化知识库

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

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

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

---

mwkg import — 导入文档

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

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 — 查询知识库

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 — 知识库管理

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 — 配置管理

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 — 同步操作

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）调用。

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）进行实体关系提取。

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 提取的实体、关系、摘要导入知识库。

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 文件。

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）

---

全局选项

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

📄 许可证

MIT