feat: 导出 SproutClaw .sproutclaw 配置
包含 extensions、skills、prompts、settings、auth、models、mcp 等配置。 排除 node_modules、npm 缓存、sessions 等运行时数据。
This commit is contained in:
202
agent/skills-disabled/mengya-rag/SKILL.md
Normal file
202
agent/skills-disabled/mengya-rag/SKILL.md
Normal file
@@ -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/`
|
||||
105
agent/skills-disabled/mengya-rag/references/output-schema.md
Normal file
105
agent/skills-disabled/mengya-rag/references/output-schema.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# mengya-rag JSON 输出格式参考
|
||||
|
||||
所有命令加 `--json` 后输出 JSON，供 Agent 程序化解析。
|
||||
|
||||
## status
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "status",
|
||||
"project_root": "...",
|
||||
"notes_dir": "...",
|
||||
"index_dir": "...",
|
||||
"db_exists": true,
|
||||
"nodes_file_exists": true,
|
||||
"deepseek_api_key_configured": true,
|
||||
"deepseek_model": "deepseek-v4-flash",
|
||||
"markdown_note_count": 495,
|
||||
"index_node_count": 1802
|
||||
}
|
||||
```
|
||||
|
||||
## search
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "search",
|
||||
"question": "用户问题",
|
||||
"mode": "hybrid",
|
||||
"top_k": 2,
|
||||
"results": [
|
||||
{
|
||||
"source": "Docker/Docker常用命令总结.md",
|
||||
"title": "Docker常用命令总结",
|
||||
"heading_path": "容器生命周期管理",
|
||||
"chunk_index": 0,
|
||||
"score": 0.85,
|
||||
"raw_score": 0.75,
|
||||
"metadata": { "h1": "Docker常用命令总结", "h2": "容器生命周期管理" },
|
||||
"content": "## 容器操作\n```bash\ndocker run ...\n```"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## context
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "context",
|
||||
"question": "用户问题",
|
||||
"mode": "hybrid",
|
||||
"top_k": 2,
|
||||
"context": "[1] 来源: ...\n文件: Docker/xxx.md\n标题: XXX\n标题路径: ...\n\n---\n笔记内容...\n\n[2] 来源: ...\n...",
|
||||
"sources": ["Docker/xxx.md", "Docker/yyy.md"]
|
||||
}
|
||||
```
|
||||
|
||||
## read
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "read",
|
||||
"source": "Docker/Docker常用命令总结.md",
|
||||
"content": "## 完整 Markdown 原文内容..."
|
||||
}
|
||||
```
|
||||
|
||||
## ask
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "ask",
|
||||
"question": "用户问题",
|
||||
"mode": "hybrid",
|
||||
"top_k": 4,
|
||||
"answer": "DeepSeek 生成的回答文本...",
|
||||
"sources": ["文件1.md", "文件2.md"]
|
||||
}
|
||||
```
|
||||
|
||||
## reindex
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"command": "reindex",
|
||||
"synced_notes": 495,
|
||||
"indexed_nodes": 1802,
|
||||
"duration_seconds": 12.5
|
||||
}
|
||||
```
|
||||
|
||||
## 错误返回
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": "错误描述信息"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user