本地知识库检索 Skill（kb-retriever）：RAG 实战演示的典范

想象一下这样的场景：你是公司里的数据分析师，某天领导突然问你：「帮我查一下去年Q3华东区销售额最高的5个客户，顺便对比一下库存情况。」你打开文件夹一看——20多个子目录、30多份文件，PDF年报、Excel报表、Markdown文档混杂在一起。传统方式下，光是找到正确文件就要花上十几分钟。

ConardLi/rag-skill 正是为解决这类痛点而生的项目。它不是一个可以直接部署运行的完整应用，而是一套经过精心设计的AI Agent Skill 模板，展示了如何让大模型智能地「翻阅」本地知识库并回答复杂问题。

背景故事：从「大海捞针」到「精准导航」

本项目的作者 ConardLi 是国内知名的前端/架构技术作者，长期活跃于 GitHub 开源社区。随着大模型（LLM）应用逐步落地，他敏锐地注意到了 RAG（检索增强生成）技术的价值——与其让模型「背下」所有知识，不如让它学会「查资料」。

然而，现有的 RAG 教程大多聚焦于向量数据库和 Embedding 技术，忽略了结构化知识库的自然检索场景：当知识库以文件系统形式存在、包含 PDF/Excel/Markdown 等多格式文档时，如何让 AI 精准定位答案而非盲目全量搜索？

带着这个问题，ConardLi 设计了这套基于分层索引 + 渐进式检索的 Skill 规范，并在 garden-skills 仓库中持续维护更新。本仓库（rag-skill）则是这一理念的完整演示，包含了真实的多领域知识库样本数据。

核心设计理念

1. 分层索引导航

传统文件检索的痛点在于：AI 拿到一个巨大的目录后，要么盲目遍历所有文件（浪费 token、速度慢），要么「拍脑袋」乱找（准确率低）。本项目创造性地引入了分层索引树机制：

每个目录放置一个 data_structure.md 文件，向 AI 说明该目录下有哪些子目录/文件，以及各自的用途。例如根目录的 data_structure.md 指向 AI Knowledge/、Financial Report Data/、E-commerce Data/ 等业务领域；进入 AI Knowledge/ 后，又有下一层的 data_structure.md 指向具体的 PDF 文件。

AI 通过阅读索引文件，可以像人类一样「先看目录再翻内容」，智能选择最相关的路径，避免盲目搜索整棵目录树。

2. 先学习，再处理

当 AI 遇到不熟悉的文件格式时（如 PDF、Excel），传统做法是直接尝试读取，结果往往调用错误的工具、产生大量无效 token。本项目强制要求 AI 先阅读参考资料再处理文件：

• 处理 PDF 前：必须先读取 references/pdf_reading.md，学习 pdftotext / pdfplumber 等工具的正确用法
• 处理 Excel 前：必须先读取 references/excel_reading.md 和 references/excel_analysis.md，掌握 pandas 读取和数据分析方法

这一设计类似于人类在处理陌生任务前的「预习」环节，确保工具使用正确、检索高效。

3. 渐进式检索

与一次性加载整个文件的粗暴做法不同，本项目要求 AI 使用局部读取 + 多轮迭代策略：

• 第一轮：用 grep 定位关键词，初步筛选候选文件
• 第二轮：在候选文件中，用行号偏移精确读取匹配上下文（limit=200~500行）
• 第三至五轮：逐步缩小范围，直到找到足够信息

对于 PDF，使用 pdftotext input.pdf output.txt 提取文本到临时文件后再检索；对于 Excel，使用 nrows 参数限制读取行数。这些优化使得 token 消耗从「整文件加载的几十K」降低到「2K~8K的精准检索」。

示例知识库：真实场景全覆盖

项目自带一个内容丰富的示例知识库（knowledge/ 目录），包含四大领域：

领域	格式	内容
AI 行业报告	14个PDF (~135MB)	AI Agent技术发展、大模型应用趋势
金融财报	6个PDF	上市公司季度/年度报告
电商数据	4个Excel	客户、员工、库存、销售订单
安全知识	Markdown	XSS/SQL注入/CSRF防护

这使得开发者可以直接用这套 Skill 模板对接自己的知识库，无需从零设计检索流程。

技术架构

从代码结构看，本项目遵循 Skill 编写规范（类似于 MCP 工具集的 JSON Schema 规范）：

.agent/skills/rag-skill/
├── SKILL.md                  # Skill 主定义（7KB Markdown）
├── references/
│   ├── pdf_reading.md        # PDF处理指南
│   ├── excel_reading.md      # Excel读取指南
│   └── excel_analysis.md     # Excel分析指南
└── scripts/                  # 辅助脚本

SKILL.md 采用 YAML frontmatter + Markdown 主体结构，定义了 Skill 的触发条件（用户问题涉及知识库检索/查资料）、工具集（grep、Read、pdfplumber、pandas）和执行流程。

技术栈：纯 Python + Shell 命令行工具。项目本身零依赖，通过 grep、pdftotext、pandas 等标准工具实现文件处理。

AI 组件：项目本质上是 LLM 的工具使用规范，依赖 GPT-4 / Claude 等大模型的 function calling 能力来执行检索策略。没有使用特定的 ML 框架或训练流程。

上手体验

这是一个面向 AI 开发者的 Skill 模板项目，普通用户需要一定的技术背景才能使用：

• 使用门槛：需要理解 AI Agent / RAG 的基本概念，熟悉命令行工具
• 使用方式：阅读 SKILL.md，理解其设计理念，然后移植到自己的 AI 助手系统
• 注意事项：项目已归档，后续更新在 ConardLi/garden-skills 仓库

争议与局限

1. 无 Web UI：这是一个纯 Skill 定义，无任何图形界面，不适合非技术用户

• 2. 依赖外部 Agent 框架：Skill 本身不能独立运行，需要嵌入到支持 Skill 规范的 AI Agent 平台（如 Co-Agent、自定义的 Agent 系统）
• 3. 向量检索缺失：项目未使用 Embedding + 向量数据库，纯依赖文件系统索引和关键词匹配，对于语义模糊的查询（如「帮我概括一下这个报告的核心观点」）表现可能不如向量 RAG
• 4. 已归档：项目停止维护，仅作参考学习用途

行业意义

尽管功能简单，rag-skill 在 Skill 编写规范化和 RAG 最佳实践方面有重要参考价值。它提出的**「分层索引 + 先学习后处理 + 渐进式检索」**三层设计，为构建可靠的本地知识库 RAG 系统提供了清晰的可执行路径。

这类模板化、可复制的 Skill 规范，是 AI Agent 生态从「玩具 demo」走向「生产可用」的关键基础设施。随着更多垂直领域 Skill 的积累，开发者可以像搭积木一样快速组装具备领域知识的专业 AI 助手。