Imported from phuhao00/bony-agent (electron/resources/agent-skills/rag-expert/SKILL.md). Install upstream with npx skills add phuhao00/bony-agent --skill rag-expert. Copyright stays with the author (MIT).

知识库管理专家 (RAG Expert)

你是私有知识库的全链路管理专家，基于 LlamaIndex + ZhiPu AI 实现 RAG（检索增强生成）。

技术架构

用户 → Next.js 前端 → FastAPI 后端 → RAGManager → ZhiPu AI
                                         ↓
                               LlamaIndex VectorStoreIndex
                                         ↓
                              storage/rag/ (持久化索引)
                              storage/knowledge/ (源文件)

核心文件

API 端点

支持的文档格式

.txt .md .pdf .docx .doc .json .csv（最大 20MB）

使用方法

1. Agent 内检索知识库

当用户提问涉及已上传文档内容时：

from tools.rag_tools import search_knowledge_base

result = search_knowledge_base("用户的问题")
# 返回: 答案文本 + 参考来源（前3条）

2. 直接使用 RAGManager

from utils.rag_manager import get_rag_manager, save_knowledge_file

rag = get_rag_manager()

# 上传文档
filepath = save_knowledge_file(content_bytes, "report.pdf")
result = rag.ingest_documents([filepath])
# result: {"success": True, "documents": [{"id": "uuid", "filename": "report.pdf", "size": 10240}]}

# 查询
result = rag.query("如何配置系统？", top_k=3)
# result: {"success": True, "answer": "...", "sources": [{"text": "...", "score": 0.92, "metadata": {...}}]}

# 获取文档列表
docs = rag.get_documents_info()

# 删除文档（会重建索引）
rag.delete_document("doc-uuid")

# 获取状态
status = rag.get_status()
# status: {"initialized": True, "document_count": 5, "total_file_size_human": "2.3 MB", ...}

# 清空
rag.clear_all()

3. 通过 HTTP API 操作

# 上传
curl -X POST http://localhost:8000/knowledge/upload -F "file=@report.pdf"

# 查询
curl -X POST http://localhost:8000/knowledge/query \
  -H "Content-Type: application/json" \
  -d '{"query": "你的问题", "top_k": 3}'

# 列出文档
curl http://localhost:8000/knowledge/documents

# 删除文档
curl -X DELETE http://localhost:8000/knowledge/documents/{doc_id}

# 查看状态
curl http://localhost:8000/knowledge/status

# 清空
curl -X DELETE http://localhost:8000/knowledge/clear

数据流详解

上传流程

1. 前端上传文件 → Next.js 代理转发 → FastAPI 接收
2. 验证文件类型和大小（≤20MB）
3. save_knowledge_file() 保存到 storage/knowledge/（文件名加时间戳防重名）
4. SimpleDirectoryReader 解析文档内容
5. Settings.chunk_size=512 分块 → embedding-2 向量化
6. VectorStoreIndex.insert() 插入索引
7. 持久化索引至 storage/rag/ + 保存元数据至 documents_meta.json

查询流程

1. 用户问题 → embedding-2 转向量
2. VectorStoreIndex 余弦相似度检索 Top-K 文本块
3. 检索结果 + 问题 → GLM-4-Plus 生成答案
4. 返回 {answer, sources[{text, score, metadata}]}

删除流程

1. 从 documents_meta 移除记录
2. 删除 storage/knowledge/ 中的源文件
3. 全量重建索引（重新读取+向量化所有剩余文档）

存储结构

storage/
├── knowledge/           # 源文件目录
│   ├── report_20260209_123456.pdf
│   └── guide_20260210_091011.md
├── rag/                 # LlamaIndex 持久化
│   ├── documents_meta.json  # 自定义文档元数据
│   ├── docstore.json        # LlamaIndex 文档存储
│   ├── index_store.json     # 索引元信息
│   └── default__vector_store.json  # 向量数据
└── uploads/             # 通用上传临时目录

Agent 集成位置

search_knowledge_base 工具已注册到以下 Agent 的工具列表中：

• backend/agents/bot.py — 基础 Agent
• backend/agents/planning_bot.py — 规划 Agent
• backend/core/prompts/agent_prompts.py — System Prompt 中描述工具用途

注意事项

1. 必须设置 ZHIPUAI_API_KEY：否则 RAGManager 初始化失败
2. GLM 模型注册：rag_manager.py 在导入时将 glm-4-plus 注册到 LlamaIndex 的模型列表中，绕过 OpenAI 模型名校验
3. 删除=重建：删除文档会触发全量索引重建，文档较多时较慢
4. 单例模式：全局共享一个 RAGManager 实例，首次调用时惰性初始化
5. Zero /tmp 策略：所有文件存储在 storage/ 目录下，不使用系统 /tmp