Initial commit: add all skills

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-12 17:48:53 +08:00
commit dea5db60d9
31 changed files with 3111 additions and 0 deletions
--- a/mengya-rag-skill/SKILL.md
+++ b/mengya-rag-skill/SKILL.md
@@ -0,0 +1,202 @@
+---
+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/`