luckypeak-maomao 0.1.0

AI编码知识库系统 - 本地向量化 + MCP集成

Maomao - AI 编码知识库系统

一套 本地化、可控、可演进 的 AI 编码知识库系统，解决 AI 不理解旧代码、忽略私域规范、破坏向后兼容等问题。

特性

• 本地化: 所有数据存储在本地，无需联网，保护隐私
• 一键安装: 通过 pip/npm 快速安装，自动检测依赖
• 智能分块: Markdown 按标题层级分块，搜索更精准
• 增量更新: 基于内容 hash 的增量导入，避免重复处理
• MCP 集成: 通过 MCP 协议与 AI 编码工具无缝集成
• 知识分类: 区分通用编程知识和项目特定知识，精准检索

环境要求

组件	最低版本	说明
Python	3.11+	核心运行环境
Node.js	18.0+	MCP Server 运行环境（可选）
Ollama	任意版本	向量化服务
Qdrant	任意版本	向量数据库
Docker	任意版本	运行 Qdrant（推荐）

安装指南

方式一：快速安装（推荐）

使用快速启动脚本自动完成环境检测和配置：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/lucky-peak/maomao/main/scripts/quickstart.sh | bash

方式二：标准安装

1. 安装 Python 包

# 从 PyPI 安装（推荐）
pip install luckypeak-maomao

# 或从源码安装
pip install git+https://github.com/lucky-peak/maomao.git

2. 安装 MCP Server（可选）

MCP Server 用于与 AI 编码助手（如 Claude Desktop）集成：

# 全局安装
npm install -g @luckypeak/mcp-server

# 或使用 npx 直接运行（无需安装）
npx @luckypeak/mcp-server

3. 安装外部依赖

Ollama（向量化服务）：

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# 下载 BGE-M3 模型
ollama pull bge-m3

Qdrant（向量数据库）：

# 使用 Docker（推荐）
docker run -d --name maomao-qdrant -p 6333:6333 qdrant/qdrant

# 或使用 Docker Compose
# 创建 docker-compose.yml:
# services:
#   qdrant:
#     image: qdrant/qdrant
#     ports:
#       - "6333:6333"

方式三：开发环境安装

# 克隆仓库
git clone https://github.com/lucky-peak/maomao.git
cd maomao

# 安装 Python 依赖
pip install -e ".[dev]"

# 安装 MCP Server 依赖
cd mcp-server && npm install && npm run build

验证安装

# 检查版本
maomao --version

# 运行环境检测
maomao setup --check

# 完整验证
maomao verify

快速开始

1. 初始化配置

# 交互式配置（推荐）
maomao init

# 或使用默认模板
maomao init --no-interactive

这将创建 maomao.json 配置文件。

2. 编辑配置文件

编辑 maomao.json，配置你的知识源：

{
  "sources": [
    {
      "type": "local_doc",
      "enabled": true,
      "knowledge_scope": "project",
      "project_id": "my-project",
      "config": {
        "path": "/path/to/your/docs",
        "patterns": ["*.md", "*.txt"],
        "recursive": true
      }
    }
  ],
  "ollama": {
    "base_url": "http://127.0.0.1:11434",
    "embedding_model": "bge-m3",
    "embedding_dim": 1024
  },
  "qdrant": {
    "host": "127.0.0.1",
    "port": 6333,
    "collection_name": "maomao_knowledge"
  }
}

3. 验证配置

maomao validate

4. 导入知识

# 全量导入（首次使用）
maomao ingest --full

# 增量导入（后续更新）
maomao ingest

5. 搜索测试

maomao search "变量命名规范"
maomao search "错误处理最佳实践" -l 10

CLI 命令参考

基础命令

命令	说明
maomao --version	显示版本信息
maomao --help	显示帮助信息

安装与配置

命令	说明
maomao setup	环境检测和初始化设置
maomao setup --check	仅检查依赖，不执行安装
maomao doctor	诊断系统问题，提供修复建议
maomao verify	验证安装完整性
maomao init	交互式创建配置文件
maomao init --no-interactive	使用默认模板创建配置
maomao validate	验证配置文件
maomao validate -c <path>	验证指定配置文件

知识管理

命令	说明
maomao ingest	增量导入知识
maomao ingest --full	全量导入知识
maomao search <query>	搜索知识库
maomao search <query> -l 10	限制返回结果数量
maomao search <query> -t siyuan	按来源类型过滤
maomao status	查看知识库状态
maomao config	显示当前配置
maomao sources	列出可用知识源类型

命令参数详解

maomao search

maomao search <query> [OPTIONS]

参数:
  query                搜索查询文本

选项:
  -l, --limit INT      返回结果数量，默认 5
  -t, --type TEXT      来源类型过滤（如 siyuan, local_doc）

maomao ingest

maomao ingest [OPTIONS]

选项:
  -f, --full           执行全量导入，重新处理所有知识源

MCP Server 集成

配置 Claude Desktop

编辑配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "maomao": {
      "command": "maomao-mcp",
      "env": {
        "MAOMAO_PROJECT_ID": "my-project"
      }
    }
  }
}

或使用 Node.js 直接运行：

{
  "mcpServers": {
    "maomao": {
      "command": "node",
      "args": ["/path/to/maomao/mcp-server/dist/index.js"],
      "env": {
        "MAOMAO_PROJECT_ID": "my-project"
      }
    }
  }
}

可用工具

工具	说明	适用场景
search_global_knowledge	搜索通用编程知识	编码规范、框架用法、设计模式
search_project_knowledge	搜索项目特定知识	业务逻辑、架构决策、代码模式
search_all_knowledge	综合搜索	需要同时参考通用和项目知识
knowledge_status	获取知识库状态	查看向量数量、当前 project_id

MCP Server 环境变量

变量	说明	默认值
MAOMAO_QDRANT_HOST	Qdrant 主机地址	127.0.0.1
MAOMAO_QDRANT_PORT	Qdrant 端口	6333
MAOMAO_QDRANT_COLLECTION	集合名称	maomao_knowledge
MAOMAO_OLLAMA_BASE_URL	Ollama API 地址	http://127.0.0.1:11434
MAOMAO_OLLAMA_MODEL	嵌入模型	bge-m3
MAOMAO_PROJECT_ID	项目标识	自动从目录名推断

配置参考

knowledge_scope 说明

知识源可以配置 knowledge_scope 来区分知识类型：

值	说明	适用场景
global	通用编程知识，跨项目复用	编码规范、框架用法、设计模式、最佳实践
project	项目特定知识，仅当前项目相关	业务逻辑、架构决策、代码模式说明

完整配置示例

{
  "sources": [
    {
      "type": "siyuan",
      "enabled": true,
      "knowledge_scope": "global",
      "config": {
        "api_url": "http://127.0.0.1:6806",
        "token": "your-token",
        "box_id": "your-box-id",
        "root_block_id": ""
      }
    },
    {
      "type": "local_doc",
      "enabled": true,
      "knowledge_scope": "project",
      "project_id": "my-project",
      "config": {
        "path": "/path/to/project/docs",
        "patterns": ["*.md", "*.txt", "*.rst"],
        "recursive": true
      }
    }
  ],
  "ollama": {
    "base_url": "http://127.0.0.1:11434",
    "embedding_model": "bge-m3",
    "embedding_dim": 1024,
    "timeout": 120
  },
  "qdrant": {
    "host": "127.0.0.1",
    "port": 6333,
    "collection_name": "maomao_knowledge",
    "prefer_grpc": false
  },
  "chunk": {
    "chunk_size": 512,
    "chunk_overlap": 50,
    "min_chunk_size": 50
  },
  "incremental": {
    "enabled": true,
    "state_file": ".maomao/state.json"
  },
  "log_level": "INFO"
}

环境变量配置

所有配置都可以通过环境变量设置，前缀为 MAOMAO_：

export MAOMAO_OLLAMA__BASE_URL=http://127.0.0.1:11434
export MAOMAO_QDRANT__HOST=127.0.0.1
export MAOMAO_QDRANT__PORT=6333

内置知识源

SiyuanSource (思源笔记)

从思源笔记 API 获取文档内容。

配置项：

参数	说明	必填
api_url	思源笔记 API 地址	是
token	API Token	是
box_id	笔记本 ID	是
root_block_id	根文档 ID	否

LocalDocSource (本地文档)

从本地文件系统读取文档。

配置项：

参数	说明	必填
path	文档目录路径	是
patterns	文件匹配模式	否（默认 ["*.md", "*.txt"]）
recursive	是否递归扫描	否（默认 true）

支持的文件格式：

• .md, .markdown → Markdown 分块器
• .txt, .rst, .adoc → 文本分块器

注意事项

已知限制

1. Python 版本: 仅支持 Python 3.11 及以上版本
2. 嵌入模型: 默认使用 BGE-M3，需要约 2GB 显存或内存
3. 并发限制: Ollama 默认单线程处理，大批量导入可能较慢
4. 文件大小: 单个文件建议不超过 10MB，大文件可能导致内存问题

常见问题

Q: 连接 Ollama 失败

# 检查 Ollama 是否运行
ollama list

# 如果未运行，启动服务
ollama serve

Q: 连接 Qdrant 失败

# 检查 Qdrant 容器状态
docker ps | grep qdrant

# 重启容器
docker restart maomao-qdrant

# 或重新创建
docker run -d --name maomao-qdrant -p 6333:6333 qdrant/qdrant

Q: BGE-M3 模型未找到

# 下载模型
ollama pull bge-m3

# 验证模型已安装
ollama list | grep bge-m3

Q: 配置文件未找到

# 检查配置文件位置
ls -la maomao.json

# 或创建新配置
maomao init

Q: 搜索结果不准确

1. 检查知识源是否正确配置
2. 确认已执行 maomao ingest --full
3. 尝试调整搜索查询关键词
4. 检查嵌入模型是否正确加载

性能优化建议

1. 使用 SSD: Qdrant 数据存储在 SSD 上可提升搜索性能
2. 调整分块大小: 根据文档特点调整 chunk_size，默认 512 字符
3. 批量导入: 首次导入使用 --full，后续使用增量导入
4. Docker 资源: 为 Qdrant 容器分配足够的内存

# 为 Qdrant 分配更多资源
docker run -d --name maomao-qdrant \
  -p 6333:6333 \
  --memory=4g \
  --cpus=2 \
  qdrant/qdrant

5. Ollama 并发: 如需处理大量文档，可配置 Ollama 并发

# 设置 Ollama 并发数
export OLLAMA_NUM_PARALLEL=4
ollama serve

安全建议

1. Token 保护: 配置文件中的 token 等敏感信息不要提交到版本控制
2. 网络隔离: Ollama 和 Qdrant 默认仅监听本地，生产环境注意网络安全
3. 数据备份: 定期备份 Qdrant 数据目录

架构

┌─────────────────────────────────────────────────────────────────┐
│                        知识源 (可扩展)                            │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   SiyuanSource  │  LocalDocSource │  自定义 Source...            │
│   (思源笔记)     │  (本地文档)      │  (Notion/Obsidian/...)       │
└────────┬────────┴────────┬────────┴─────────────────────────────┘
         │                 │
         ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                      分块器 (可扩展)                              │
├─────────────────┬─────────────────┬─────────────────────────────┤
│ MarkdownChunker │   TextChunker   │  自定义 Chunker...           │
│  (按标题分块)     │  (按段落分块)    │  (代码/表格/...)              │
└────────┬────────┴────────┬────────┴─────────────────────────────┘
         │                 │
         ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│              Python Ingestion Pipeline                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │  解析     │→ │  分块     │→ │ 向量化   │→ │  存储     │        │
│  │  Source  │  │ Chunker  │  │ Ollama   │  │ Qdrant   │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
└─────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MCP Server (TypeScript)                       │
│  ┌─────────────────────┐  ┌─────────────────────┐               │
│  │search_global_knowledge│  │search_project_knowledge│            │
│  │  (通用编程知识)       │  │  (项目特定知识)       │              │
│  └─────────────────────┘  └─────────────────────┘               │
│  ┌─────────────────────┐  ┌─────────────────────┐               │
│  │search_all_knowledge │  │  knowledge_status   │               │
│  │  (综合搜索)          │  │  (知识库状态)        │               │
│  └─────────────────────┘  └─────────────────────┘               │
└─────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Coding Agent (支持 MCP)                        │
│              Claude / Cursor / Trae / ...                        │
└─────────────────────────────────────────────────────────────────┘

开发指南

运行测试

# 单元测试
python -m pytest tests/ -v -m "not e2e"

# E2E 测试（需要外部服务）
./scripts/run_e2e_tests.sh

# TypeScript 测试
cd mcp-server && npm test

代码检查

# Lint
python -m ruff check src/maomao/

# 类型检查
python -m mypy src/maomao/ --ignore-missing-imports

扩展知识源

from maomao.sources.base import KnowledgeSource, SourceItem, SourceRegistry

@SourceRegistry.register
class MySource(KnowledgeSource):
    @classmethod
    def source_type(cls) -> str:
        return "my_source"
    
    @classmethod
    def from_config(cls, config: dict) -> "MySource":
        return cls(...)
    
    async def scan(self) -> list[SourceItem]:
        return [...]
    
    async def get_changes(self, state: dict) -> SourceChange:
        ...
    
    async def close(self) -> None:
        pass

扩展分块器

from maomao.chunkers.base import Chunker, ChunkerRegistry

@ChunkerRegistry.register
class CodeChunker(Chunker):
    @classmethod
    def chunker_type(cls) -> str:
        return "code"
    
    @classmethod
    def from_config(cls, config: dict) -> "CodeChunker":
        return cls(...)
    
    def chunk(self, content: str, metadata: dict | None) -> list[Chunk]:
        ...

项目结构

maomao/
├── src/maomao/              # Python 包
│   ├── sources/             # 知识源
│   │   ├── base.py          # 抽象基类和注册表
│   │   ├── siyuan.py        # 思源笔记源
│   │   └── local_doc.py     # 本地文档源
│   ├── chunkers/            # 分块器
│   │   ├── base.py          # 抽象基类和注册表
│   │   ├── markdown.py      # Markdown 分块器
│   │   └── text.py          # 文本分块器
│   ├── embeddings.py        # 向量化服务
│   ├── vectorstore.py       # 向量存储
│   ├── pipeline.py          # 导入流程
│   ├── state.py             # 状态管理
│   ├── config.py            # 配置
│   ├── models.py            # 数据模型
│   ├── dependency_checker.py # 依赖检测
│   └── cli.py               # CLI 工具
├── mcp-server/              # MCP Server
│   ├── src/
│   │   ├── index.ts         # 入口
│   │   ├── services.ts      # 知识检索服务
│   │   ├── config.ts        # 配置
│   │   └── types.ts         # 类型定义
│   └── package.json
├── scripts/
│   ├── quickstart.sh        # 快速启动脚本
│   └── run_e2e_tests.sh     # E2E 测试脚本
├── tests/                   # 测试目录
├── docs/                    # 文档目录
├── pyproject.toml           # Python 项目配置
└── LICENSE                  # MIT License

License

MIT License - 详见 LICENSE 文件