---
name: mengya-rag
description: 萌芽本地 RAG 知识库，基于 LlamaIndex + DeepSeek + BM25/向量混合检索的 Obsidian 笔记问答工具。当用户提到查笔记、查知识库、根据笔记回答问题、搜索自己的文档、翻看笔记内容、查自己的博客文章、查教程、查项目文档、整理笔记素材、问"我写过什么""我之前记录过什么""我的笔记里有没有关于X的内容"时，一定要使用本技能。也适用于用户需要查询知识库状态、同步笔记、重建索引的场景。该技能通过 CLI 工具 mengya-rag 实现，项目路径 /shumengya/project/agent/mengya-rag。
---

# 萌芽 RAG 知识库

基于 LlamaIndex + DeepSeek + BM25/本地向量混合检索的个人 Obsidian 笔记问答系统。

**当前状态：** 已索引 495 篇 Markdown 笔记，共计 1802 个语义分块，覆盖 Docker、Linux、Android、AI Agent、博客文章、工具教程等主题。

## 前置检查

执行任何操作前，先确认工具可用：

```bash
cd /shumengya/project/agent/mengya-rag && uv run mengya-rag status --json
```

返回示例：
```json
{"ok": true, "markdown_note_count": 495, "index_node_count": 1802, "db_exists": true, "deepseek_model": "deepseek-v4-flash"}
```

如果 `ok: false` 或 `db_exists: false`，需要先执行 `reindex` 重建索引后再继续。

## 项目路径

```text
项目根目录: /shumengya/project/agent/mengya-rag
笔记目录:   data/notes/          (495 篇 Markdown 笔记)
索引目录:   data/index/bm25/     (SQLite + sqlite-vec 向量库)
配置:       .env                 (DeepSeek API Key)
```

## 技术栈

| 组件 | 技术 |
|------|------|
| RAG 框架 | LlamaIndex |
| 本地 embedding | BAAI/bge-small-zh-v1.5 (FastEmbed + ONNX，无 PyTorch/GPU 依赖) |
| 大模型回答 | DeepSeek API (默认 deepseek-v4-flash) |
| 检索方式 | BM25 关键词 + 向量语义 混合检索 + RRF 融合 + 同文件去重 |
| 向量库 | SQLite + sqlite-vec（单文件，无外部服务依赖）|
| 运行环境 | Python 3.11+, uv 包管理 |

## CLI 命令参考

所有命令从项目根目录执行，`uv run` 前缀：

### 核心命令（推荐 Agent 统一使用 `--json`）

| 命令 | 用途 | 推荐场景 |
|------|------|---------|
| `mengya-rag status --json` | 检查索引和配置状态 | 对话开始时先跑一次确认环境 |
| `mengya-rag search "Q" -k N --json` | 纯检索，不调大模型 | 需要自己分析检索结果时 |
| `mengya-rag context "Q" -k N --json` | 返回拼接好的 context 字符串 | 需要把检索结果注入其他大模型提示词时 |
| `mengya-rag read "path" --json` | 读取完整 Markdown 原文 | 检索命中后需要补充上下文时 |
| `mengya-rag ask "Q" -k N --json` | RAG + DeepSeek 完整问答 | 用户直接想问笔记里的内容时 |
| `mengya-rag reindex --json` | 同步笔记 + 重建索引 | 笔记更新后 |

### 常用参数

```bash
-k, --top-k <num>         # 返回条数（默认 6）
--mode auto               # 自动判断：普通问答或盘点列表（默认）
--mode hybrid             # 强制语义检索模式
--mode inventory          # 强制盘点/目录检索模式
--env-file /path/.env     # 指定配置文件
--notes-dir /path         # 覆盖笔记目录
--index-dir /path         # 覆盖索引目录
```

## Agent 工作流

当用户提到查笔记、查知识库、找文档时，按以下顺序操作：

### 第一步：检查状态

```bash
cd /shumengya/project/agent/mengya-rag && uv run mengya-rag status --json
```

确认 `ok: true`、`db_exists: true`、`markdown_note_count > 0`。

### 第二步：根据用户问题类型选择命令

**场景 A：用户问"关于X的内容是什么""XX怎么做"**
→ 使用 `ask`，让 RAG 完成检索 + 回答

```bash
uv run mengya-rag ask "用户的问题" -k 4 --json
```
解析返回的 `answer` 和 `sources`，直接呈现给用户。

**场景 B：用户想查"有哪些笔记""我写过什么"**
→ 检索模式会自动切换到盘点模式，用 `search` 即可

```bash
uv run mengya-rag search "博客文章" -k 10 --json
```
返回结果中的 `results[].title` 和 `results[].heading_path` 可以直接展示给用户。

**场景 C：检索结果不够详细，需要看完整原文**
→ 先用 `search` 拿到 `source` 文件名，再用 `read` 读完整内容

```bash
# 先检索
uv run mengya-rag search "Docker 网络配置" -k 3 --json
# 取出结果中的 source 字段（如 "Docker/Docker网络配置.md"）后执行：
uv run mengya-rag read "Docker/Docker网络配置.md" --json
```

**场景 D：需要把笔记内容作为上下文给另一个大模型**
→ 使用 `context` 模式，返回纯文本 context

```bash
uv run mengya-rag context "WireGuard 配置方法" -k 4 --json
```
返回的 `context` 字段可直接拼入其他模型的提示词中。

**场景 E：用户说笔记更新了/查不到新内容**
→ 执行同步 + 重建索引

```bash
uv run mengya-rag reindex --json
```

### 第三步：呈现结果

- **ask 结果**：直接展示 `answer` 内容，并附上 `sources` 来源说明
- **search 结果**：列表展示文件名和标题路径，询问用户是否需要进一步阅读某篇
- **read 结果**：展示 `content`，如果内容较长则先总结再给用户
- **context 结果**：说明已获取上下文，询问用户想用它做什么

## 检索模式说明

系统自动识别两类问题，无需手动指定（也可通过 `--mode` 强制）：

| 问题类型 | 示例 | 检索策略 |
|---------|------|---------|
| 普通问答 | "Docker 常用命令有哪些""WireGuard 怎么配置" | Markdown 结构感知分块 → BM25 + 向量混合检索 → RRF 融合 → DeepSeek 生成回答 |
| 盘点列表 | "我有哪些博客文章""安卓 Gradle 相关笔记" | 文件级摘要节点 → BM25 检索 → 关键词覆盖过滤 → 输出文件列表和预览 |

## 查询模式示例

**普通问答：**
```
用户 > docker-compose 怎么设置资源限制
Agent > uv run mengya-rag ask "docker-compose 资源限制配置" -k 4 --json
返回  > answer: "在 docker-compose.yml 中通过 deploy.resources.limits 设置..."
       > sources: ["Docker/Docker Compose配置.md", "Docker/资源限制.md"]
Agent > 展示回答内容和来源
```

**盘点列表：**
```
用户 > 我有哪些博客文章
Agent > uv run mengya-rag search "博客文章" -k 10 --json
返回  > results[].title 列表
Agent > 展示文件列表，询问用户想读哪篇
```

## 维护操作

```bash
# 同步笔记 + 重建索引（一步完成）
uv run mengya-rag reindex --json

# 或分步执行：
uv run mengya-sync-notes         # 从 bigmengya 同步最新笔记
uv run mengya-build-index        # 重建索引
```

## 错误处理

| 现象 | 可能原因 | 处理方式 |
|------|---------|---------|
| `db_exists: false` | 索引未构建 | 执行 `uv run mengya-rag reindex --json` |
| `ok: false` | 项目或配置问题 | 检查 `.env` 中 `DEEPSEEK_API_KEY` 是否配置 |
| `command not found: uv` | uv 未安装 | `pip install uv` 或 `curl -LsSf https://astral.sh/uv/install.sh | sh` |
| `markdown_note_count: 0` | 笔记目录为空 | 执行 `uv run mengya-rag reindex --json` 从 bigmengya 同步 |
| DeepSeek API 报错 | API Key 无效或网络问题 | 检查 `.env` 中的 `DEEPSEEK_API_KEY` 和网络连通性 |

## 配置参考

`.env` 文件中的可调参数：

```env
DEEPSEEK_API_KEY=你的API密钥          # 必填
TOP_K=6                               # 默认检索返回条数
EMBED_MODEL=BAAI/bge-small-zh-v1.5    # 本地 embedding 模型
EMBED_BATCH_SIZE=32                   # embedding 批处理大小
VECTOR_WEIGHT=0.65                    # 向量检索权重（混合模式）
BM25_WEIGHT=0.35                      # BM25 关键词权重
```

## 参考

- 完整文档：[README.md](/shumengya/project/agent/mengya-rag/README.md)
- JSON 输出格式参考：[references/output-schema.md](references/output-schema.md)
- 源码目录：`/shumengya/project/agent/mengya-rag/src/mengya_rag/`