原始内容
name: local-rag-builder version: 1.0.5 description: 本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理 author: wUwproject license: MIT sensitive_access: false critical_write: false trigger: ['搭建 RAG 系统', '本地知识库', '嵌入模型下载', '文本切分', '向量检索', 'RAG 环境配置', '下载模型', '入库文档', '切分文档', '知识库管理'] trigger_negative: ['纯聊天', '简单问答'] tags: ['rag', 'embedding', 'llm', 'python', 'vector-db', 'text-splitter', 'guard-stack', 'plugin'] data_dir: skills/.standardization/local-rag-builder/data/ h1_position: true external_data_dir: true permission_weight: LOW faq_quality: improve_qa meta_field_sync: true data_dir_compliance: true create_permissions_md: true
local-rag-builder（本地 RAG 搭建工具）
一站式本地 RAG 系统搭建工具。支持环境自动检测修复、嵌入模型多源下载、5 种切分策略 + GuardStack 守卫栈 + 后处理子切 + 插件注册、多知识库管理与自动分类规则、可调 Prompt、Web 可视化配置。
两种运行模式：
- 🔌 集成模式（默认） — 纯检索，不调用 LLM。智能体（xxxx 等）根据检索到的 context 自行回答。无需配置 LLM，无额外推理成本。
- 🤖 独立模式 — 检索 + LLM 全链路。
rag_standalone.py直接调用外部 LLM（LM Studio / Ollama / vLLM）完成回答，不经过智能体。用户自行选择平台和模型。
工作流说明（以下 xxxx 代指任意智能体）：
集成模式：
- 你把文档/链接给 xxxx → xxxx 调用
rag_skill.py向量化入库- 你提问 → xxxx 调用
rag_skill.py --query "..."检索知识库- xxxx 根据检索到的 context 组织回答
独立模式：
- 你把文档/链接给 xxxx → xxxx 调用
rag_standalone.py --import-file <path>入库- 你提问 → xxxx 调用
rag_standalone.py --query "..."rag_standalone.py自行检索知识库 → 调用本地 LLM → 输出回答- xxxx 仅透传结果，不参与推理
触发场景
- 搭建 RAG — "帮我搭一个本地 RAG 系统"
- 环境检测 — "检查我的 Python 环境能否跑 RAG"
- 下载模型 — "下载一个嵌入模型" / "换个模型源重试"
- 切分文档 — "对这个 Markdown 文件做层级切分"
- 向量检索 — "把这份资料入库，搜索相似内容"
- 知识库管理 — "创建一个知识库" / "把这类资料存入指定库"
- 调整参数 — "更新切分参数" / "改 Prompt 模板"
- 智能体集成 — "根据这份资料回答：xxx"（智能体调用 skill 的集成模式）
- 不触发：纯 LLM 聊天不需要检索、简单问答不需要外部资料
核心能力
📚 渐进式加载：本技能采用渐进式 MD 体系，
SKILL.md为入口（≤230行），详细内容拆分到references/*.md按需加载。
| # | 能力 | 说明 |
|---|---|---|
| 1 | 环境自动检测修复 | 检测 Python 版本（需 3.8-3.11）、缺失包，自动创建虚拟环境安装 |
| 2 | 嵌入模型管理 | 多源下载（ModelScope / HuggingFace 镜像 / 官方 / LLM 找源），自动重试，完整性校验，路径修正 |
| 3 | 5 种切分策略 + GuardStack + 后处理 | 固定窗口、递归切、层级/标题切、按句切、语义切；守卫栈（mermaid/代码块/公式/表格/HTML 保护）；后处理子切（递归/固定/语义，metadata 白名单继承） |
| 4 | 多知识库管理 | 支持多个向量知识库并行，LLM 自动分类入库或用户指定 |
| 5 | 可调 Prompt | 模板持久化，支持自定义占位符（{context} {question}），运行时编辑 |
| 6 | Web 可视化界面 | 内嵌 HTML 配置面板：输入源开关、GuardStack 守卫配置、5 策略动态表单 + 后处理配置、极客模式 JSON 编辑器 + 配置模板管理、知识库自动分类规则编辑器 |
| 7 | 双模式接口 | 集成模式（--retrieve-only / --mode integrated）纯检索，智能体自行回答；独立模式（--mode standalone）检索 + LLM 全链路 |
渐进式文件索引
| 文件名 | 分类 | 包含内容 | 审计关联 |
|---|---|---|---|
references/antipatterns.md |
规范指南 | skill 编写中的常见反模式。包含：错误做法示例、正确做法示例、避坑指引。 | R-18 |
references/architecture.md |
架构设计 | skill-standardization 整体架构。包含：模块关系、数据流、核心设计决策。 | 无 |
references/changelog.md |
版本管理 | 版本更新日志。包含：版本号、变更类型、修复项、升级说明。 | R-24 |
references/examples.md |
使用示例 | 各场景完整执行示例。包含：CLI 命令、执行过程、输出结果。 | R-25 C-17 |
references/faq.md |
常见问题 | 常见疑问与解答。包含：问题分类、原因分析、解决方案。 | R-19, R-25 C-19 |
references/guide.md |
使用指南 | 三种执行模式操作教程。包含：audit/create/refactor 流程、参数说明、注意事项。 | 无 |
references/llm-setup.md |
参考文档 | > 本文件适用于 独立模式（rag_standalone.py）。技能模式（rag_skill.py）不需要 LLM。 |
无 |
references/permissions.md |
权限与测试 | 权限扫描说明与测试结论。包含：风险等级、高权限操作说明、测试概览、计时统计。 | R-15, R-16 |
快速开始
# 1. 进入技能目录
cd ~/.workbuddy/skills/local-rag-builder
# 2. 运行环境检测（自动修复，建议首次用国内镜像）
python scripts/rag_env_setup.py --auto-install --mirror aliyun # 国内用户推荐
# python scripts/rag_env_setup.py --auto-install # 海外用户/默认
# python scripts/rag_env_setup.py --check-only # 仅检测不安装
# python scripts/rag_env_setup.py --cleanup-locks # 清理 pip 锁文件
# 3. 下载嵌入模型（交互式选择）
python scripts/embedding_model_manager.py --interactive
# 4. 启动 Web 配置界面
python scripts/rag_web_ui.py
# 5a. [技能模式] 纯检索，供智能体调用（无需 LLM）
python scripts/rag_skill.py --query "问题"
python scripts/rag_skill.py --query "问题" --json # JSON 输出
# 5b. [独立模式] 检索 + LLM 全链路，需外部 LLM 服务
python scripts/rag_standalone.py # 交互式 CLI
python scripts/rag_standalone.py --query "问题" # 单次问答
python scripts/rag_standalone.py --query "问题" --json # JSON 输出
python scripts/rag_standalone.py --llm-help # 查看 LLM 接入指南
工作流程
- 环境准备 —
rag_env_setup.py检测并安装依赖 - 模型下载 —
embedding_model_manager.py下载/校验嵌入模型 - 文档入库 —
text_splitter.py切分文档 →knowledge_base_manager.py向量化 - 模式选择 — 根据用途选择入口
- 技能模式 →
rag_skill.py（纯检索，供智能体调用，无需 LLM） - 独立模式 →
rag_standalone.py（检索 + LLM 全链路，需外部 LLM）
- 技能模式 →
- 配置调整 —
rag_web_ui.py提供可视化面板
命令速查
| 脚本 | 作用 | 核心参数 |
|---|---|---|
rag_env_setup.py |
环境检测与修复 | --auto-install, --check-only, --cleanup-locks, --mirror, --dry-run |
embedding_model_manager.py |
嵌入模型管理 | --download, --list, --check, --remove |
text_splitter.py |
文本切分（三层流水线） | --strategy, --guard, --secondary, --chunk-size, --input, --list-strategies |
rag_core.py |
共享核心（被其他模块导入，不直接运行） | — |
rag_skill.py |
[技能模式] 纯检索接口 | --query, --kb, --json |
rag_standalone.py |
[独立模式] 检索+LLM | --query, --kb, --llm-help, --json |
rag_web_ui.py |
Web 配置界面 | --port, --gen-html |
prompt_manager.py |
Prompt 管理 | --set, --show, --reset |
knowledge_base_manager.py |
知识库管理 | --create, --import, --list, --delete, --set-rule, --classify |
数据目录（skills/.standardization/local-rag-builder/data/）
data/
├── kb/ # 向量数据库目录（每个知识库一个子目录）
│ ├── default/ # 默认知识库
│ ├── art/ # 艺术类资料
│ └── politics/ # 政治类资料
├── models/ # 下载的嵌入模型
├── prompts/ # Prompt 模板文件
├── config/ # 运行时配置
├── output/ # 导出产物
├── logs/ # 执行日志
├── cache/ # 缓存
└── config_templates/ # 用户保存的配置模板
自定义扩展（插件注册）
本技能 v1.0 支持通过代码注册自定义切分策略和守卫。
from text_splitter import register_strategy, register_guard, StrategyPlugin, GuardPlugin, Guard
# 自定义切分策略
def my_splitter(text, my_param=100, **kwargs):
from langchain_core.documents import Document
# 自定义切分逻辑
return [Document(page_content=text)]
register_strategy(StrategyPlugin(
"my_split", "我的自定义切分", my_splitter,
config_schema={
"my_param": {"type": "int", "label": "参数名", "default": 100, "min": 1, "max": 1000},
"flag": {"type": "bool", "label": "开关", "default": False},
},
default_config={"my_param": 100, "flag": False},
))
# 自定义守卫
my_guard = Guard("my_guard", re.compile(r'```special\n[\s\S]*?\n```'))
register_guard(GuardPlugin("my_guard", "保护特殊代码块", my_guard))
注册后自动出现在 Web UI 的下拉列表中，配置表单自动生成。
重要约定
- Python 版本：建议 3.8-3.11（3.12+ 需测试 chromadb 兼容性）
- 嵌入模型路径：下载后自动修正真实路径（如
bge-small-zh-v1___5） - 知识库隔离：不同资料自动/手动归入不同库
- 重置：删除
data/下对应子目录即可重置相关数据