版本: v0.5.0 最后更新: 2026-08-08
包含通用代码库、避坑指南、工具手册等的个人知识库，内置向量数据库与四层检索架构，支持 AI 语义检索、PDF 解析管线和 MCP 协议接入，助力跨项目知识共享（BUSL-1.1 非商用许可证）。
个人的技术知识分散在多个项目、多个文档中，无法被 AI 统一检索利用。ECatVecLib 解决的核心问题是：把零散知识集中管理，让 AI 能语义化检索并复用。
1. 目录结构即约定
知识按「领域/细分领域/文档」两级文件夹组织，向量索引自动识别层级关系，无需额外配置。这是整个系统一致性的基础：
knowledge/
├── 软件开发/ # 一级目录（领域）
│ ├── 信息处理/ # 二级目录（细分领域）
│ │ └── Markdown语法参考手册.md
│ └── 版本控制/ # 二级目录
├── 数学/ # 一级目录
└── ...
2. 四层检索架构
领域级 → 细分领域级 → 文档级 → 段落级，支持从粗到精、由快到准的分层检索，兼顾定位速度与内容精度。
3. 二次检索
第一次检索定位文档，第二次检索定位段落，兼顾召回与精度。
4. 索引本地构建
向量索引 index/ 依赖本地嵌入模型，体积大，不通过 git 同步，每台电脑独立构建，保护知识资产。
5. 零成本
本地嵌入模型（bge-base-zh-v1.5）+ faiss-cpu 向量库，不依赖付费 API。
6. 许可证 BUSL-1.1
非商业免费，商业使用受限，保护知识资产。
- 四层检索架构：领域级 → 细分领域级 → 文档级 → 段落级，兼顾定位速度与内容精度
- 多领域知识分类：软件开发、数学、物理、哲学、历史、动漫游戏、工程技术等多领域，两层文件夹结构
- 统一 PDF 解析管线：电子 PDF 用 PyMuPDF，扫描件用 MinerU OCR，自动分流
- 嵌入后端抽象层：支持 SentenceTransformer（CPU 优先）和 Ollama 两种后端，工厂模式自动选择
- 文档切分系统：Markdown 标题分块 + 语义分块 + overlap，无嵌入时自动回退
- 多接口支持：CLI 命令行、MCP 协议服务器、Agent 集成三种接口共用底层逻辑
- local-only 本地专属：通过
.git/info/exclude排除 Git 追踪，但仍参与向量索引 - 自动更新检测：基于文件 SHA-256 哈希检测知识库文档变化
- 附件管理与转换：支持 PDF、图片等非 Markdown 格式，自动忽略原始附件目录
# 克隆仓库并进入项目根目录
git clone https://github.com/ElectriCatKennen/ECatVecLib.git
cd ECatVecLib
# 创建独立环境（推荐）
conda create -n ecatveclib-cpu python=3.11 -y
conda activate ecatveclib-cpu
# 安装核心依赖 + CPU 嵌入 + OCR + MCP（一条命令搞定，含扫描件 OCR）
pip install -e ".[cpu,mcp,ocr]"若已通过 git submodule 挂载到主项目，则在主项目根目录进入子模块路径即可。
# 安装后即可直接使用 ecat/ecatveclib 命令（无需 python -m）
# 设置 ECATVECLIB_HOME 后可在任意目录调用
$env:ECATVECLIB_HOME = "D:\OpenClaw\shared\ECatVecLib"
ecat build --force# 位置参数直接传查询文本（无需 --query）
ecat query "git submodule 使用方法" --top-k 3完整上手步骤见 快速开始。
| 文档 | 说明 |
|---|---|
| 文档首页 | 按角色分层的文档导航 |
| 快速开始 | 安装、构建、搜索、挂载、转换 |
| 配置说明 | 配置文件、文档切分策略 |
| 目录结构 | 项目目录树、local-only 机制 |
| CLI 命令参考 | 全部命令行命令 |
| MCP 接入 | MCP 协议接入 + 代码直接调用 |
| 知识分类体系 | 知识分类列表与目录结构 |
| 常见问题 FAQ | 排障与使用问题 |
| 版本历史 | 版本变更记录 |
本项目采用 BUSL-1.1 许可证，详见 LICENSE。
- 非商业使用：免费使用、复制、修改、分发
- 商业使用：需单独获得商业授权（包括作为 MCP 服务对外提供）
- 变更日期：2030年7月16日
- 变更许可证：Apache License, Version 2.0