smy-skills/mengya-rag-skill/SKILL.md

name, description

name	description
mengya-rag	萌芽本地 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、博客文章、工具教程等主题。

前置检查

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

cd /shumengya/project/agent/mengya-rag && uv run mengya-rag status --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 重建索引后再继续。

项目路径

项目根目录: /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	同步笔记 + 重建索引	笔记更新后

常用参数

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

Agent 工作流

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

第一步：检查状态

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 完成检索 + 回答

uv run mengya-rag ask "用户的问题" -k 4 --json

解析返回的 answer 和 sources，直接呈现给用户。

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

uv run mengya-rag search "博客文章" -k 10 --json

返回结果中的 results[].title 和 results[].heading_path 可以直接展示给用户。

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

# 先检索
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

uv run mengya-rag context "WireGuard 配置方法" -k 4 --json

返回的 context 字段可直接拼入其他模型的提示词中。

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

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 > 展示文件列表，询问用户想读哪篇

维护操作

# 同步笔记 + 重建索引（一步完成）
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
markdown_note_count: 0	笔记目录为空	执行 uv run mengya-rag reindex --json 从 bigmengya 同步
DeepSeek API 报错	API Key 无效或网络问题	检查 .env 中的 DEEPSEEK_API_KEY 和网络连通性

配置参考

.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
• JSON 输出格式参考：references/output-schema.md
• 源码目录：/shumengya/project/agent/mengya-rag/src/mengya_rag/