agentCLAWHUBUnverified
local-rag-builder
本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理 Skill: local-rag-builder Owner: ldxs001 Summary: 本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理 Tags: embedding:1.6.0, guard-stack:1.5.0, latest:1.6.0, llm:1.6.0, plugin:1.5.0, python:1.6.0, rag:1.6.0, text-splitter:1.5.0, vector-db:1.6.0 Version history: v1.6.0 | 2026-07-11T04:49:29.206Z | user 修复: doc_count计数漂移、语义子切跳过、reranker路径解析、签名反哺毒化; 重构: 精排/路由
OpenClaw
Rank
62
Safety
84
Downloads
1.2k
Updated
Oct 11, 2026
Version
1.6.0
Source
CLAWHUB
About
What it does, and when to use it.
Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.
Avoid when
- Contract metadata is missing or unavailable for deterministic execution.
Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing
Public facts
Every fact links back to the source it came from.
- Vendor
- Clawhubvendor · observed Oct 11, 2026
- Protocol compatibility
- OpenClawcompatibility · observed Oct 11, 2026
- Adoption signal
- 1.2K downloadsadoption · observed Oct 11, 2026
- Latest release
- 1.6.0release · observed Jul 11, 2026
- Handshake status
- UNKNOWNsecurity
Install and run
Setup complexity: low.
clawhub skill install s1794v2r46s8y5d1r4jdd7ec5h84rw70:local-rag-builder- Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.
- Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data.
Contract: missing
curl -s "https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/snapshot"
Documentation
CLAWHUB
155,820 characters of source documentation, loaded on request.
Extracted files
5 files captured from the source.
SKILL.md
---
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 代指任意智能体）：**
>
> **集成模式：**
> 1. 你把文档/链接给 xxxx → xxxx 调用 `rag_skill.py` 向量化入库
> 2. 你提问 → xxxx 调用 `rag_skill.py --query "..."` 检索知识库
> 3. xxxx 根据检索到的 context 组织回答
>
> **独立模式：**
> 1. 你把文档/链接给 xxxx → xxxx 调用 `rag_standalone.py --import-file <path>` 入库
> 2. 你提问 → xxxx 调用 `rag_standalone.py --query "..."`
> 3. `rag_standalone.py` 自行检索知识库 → 调用本地 LLM → 输出回答
> 4. 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` | 使用示例 | 各场_meta.json
{
"ownerId": "kn75zfd51df61ajdyqtgvrs1hx84s4q6",
"slug": "local-rag-builder",
"version": "1.6.0",
"publishedAt": 1783745369206
}references/antipatterns.md
# 反模式 — local-rag-builder ## 不要在 SKILL.md 正文写完整教程 **错误做法**：在 SKILL.md 中展开所有脚本的详细用法。 **正确做法**：SKILL.md 只写概要，详细教程拆分到 `references/guide.md`。本技能已遵循此规范。 ## 不要硬编码模型路径 **错误做法**： ```python model_path = "D:/models/bge-small-zh-v1.5" ``` **正确做法**：通过配置系统管理模型路径，支持 Web UI 和 CLI 动态切换。 ## 不要在所有场景都用同一种切分策略 **错误做法**：对所有文档都用固定窗口切分。 **正确做法**：根据文档类型选择策略（Markdown → 标题切，长文 → 语义切，通用 → 递归切）。 ## 不要忽略 Python 版本兼容性 **错误做法**：在 Python 3.12+ 上直接安装 chromadb。 **正确做法**：使用 `rag_env_setup.py` 检测版本，必要时创建 3.11 虚拟环境。
references/architecture.md
# 架构设计 — local-rag-builder v1.0.0
## 整体架构
```
┌─────────────────────────────────────────────────────┐
│ CLI (rag_skill.py / rag_standalone.py) │
│ Web UI (rag_web_ui.py) │
├─────────────────────────────────────────────────────┤
│ rag_core.py (RAG 问答核心) │
│ text_splitter.py (5 切分策略 + GuardStack + 后处理 + 插件注册) │
│ knowledge_base_manager.py (多知识库管理) │
│ prompt_manager.py (Prompt 模板管理) │
│ embedding_model_manager.py (嵌入模型生命周期) │
│ rag_env_setup.py (环境检测与安装) │
├─────────────────────────────────────────────────────┤
│ config.py (统一配置管理) │
│ utils.py (通用工具函数) │
├─────────────────────────────────────────────────────┤
│ data/ (技能数据目录) │
│ ├── kb/ (向量知识库) │
│ ├── models/ (嵌入模型) │
│ ├── prompts/ (Prompt 模板) │
│ ├── config/ (运行时配置) │
│ └── output/ (导出产物) │
└─────────────────────────────────────────────────────┘
```
## 模块依赖关系
```
rag_skill.py / rag_standalone.py (双入口)
├── rag_core.py
│ ├── config.py ← utils.py
│ ├── prompt_manager.py ← utils.py
│ ├── text_splitter.py
│ └── knowledge_base_manager.py ← utils.py
├── embedding_model_manager.py ← utils.py
└── rag_env_setup.py
rag_web_ui.py (入口)
├── config.py ← utils.py
├── prompt_manager.py ← utils.py
├── text_splitter.py ← 策略注册表 + 守卫注册表
├── embedding_model_manager.py
├── knowledge_base_manager.py
└── rag_core.py
```
## 数据流
### 索引流程（文档入库）
```
文档 → text_splitter.py (切分) → embeddings (向量化) → Chroma (存储)
```
### 切分流水线架构
```
原始文本 → [守卫栈(多选)] → [主策略(单选)] → [后处理(单选/不选)] → 最终 chunks
守卫栈：mermaid / code / math / table / html（可扩展）
主策略：fixed / recursive / headers / sentence / semantic（可扩展）
后处理：recursive / fixed / semantic 子切（metadata 白名单继承）
```
## 查询流程（问答）
```
用户问题 → embeddings (向量化) → Chroma (检索) → 上下文 + Prompt → LLM → 回答
```
## 数据目录结构
```
skills/.standardization/local-rag-builder/data/
├── kb/ # 向量知识库
│ ├── default/ # 默认知识库
│ ├── art/ # 艺术类 (按分类规则)
│ ├── politics/ # 政治类
│ └── kb_index.json # 知识库索引
├── models/ # 嵌入模型
│ └── model_index.json # 模型索引
├── prompts/ # Prompt 模板
│ └── custom_prompt_template.txt
├── config/ # 运行时配置
│ └── rag_config.json
├── output/ # 导出产物
├── cache/ # 下载缓存
├── config_templates/ # 配置模板
└── kb/
├── default/
├── kb_index.json
└── auto_classify_rules.json # 分类规则
```
## 配置体系
配置由 `config.py` 统一管理，JSON 格式存储。
配置层级：
1. 默认配置（`DEFAULT_CONFIG` 硬编码）
2. 持久化配置（`data/config/rag_config.json`）
3. 运行时更新（通过 Web UI 或 CLI）
重置操作将删除持久化配置并恢复默认值。references/changelog.md
## 1.0.5 (2026-06-13)
### 修复
- refactor: 标准化改造（渐进式索引表格式修复、权限文档补充）
## 1.0.4 (2026-06-13)
### 新增
- KB 专属嵌入模型：每个知识库可独立选择嵌入模型，未指定时回退全局默认
- Web UI KB 管理新增模型下拉选择器
- `/api/kb-model`、`/api/kb-models` API 端点
### 修复
- `knowledge_base_manager.py` `create_knowledge_base()` 新增 `model_id` 参数
- `rag_core.py` `get_embeddings()` 新增 `kb_name` 参数，自动查 KB 专属模型
## 1.0.3 (2026-06-13)
### 修复
- 标准化改造：SKILL.md frontmatter 修复、权限文档补充、产出物路径合规
- 三端版本同步至 1.0.3
## 1.0.2 (2026-06-13)
### 修复
- 删除根目录 `.venv_rag` 遗留虚拟环境
- 同步三端版本号至 1.0.2
## 1.0.1 (2026-06-13)
### 修复
- `rag_core.py` 配置路径失效时无法回退到 `find_model_dirs()`（`if not model_path` 改为 `if not model_path or not os.path.exists(model_path)`）
- `rag_core.py` `HuggingFaceEmbeddings` 未限制本地加载（添加 `local_files_only=True` 避免加载失败时摸 Hub）
- `embedding_model_manager.py` `_check_integrity()` 将仅有 `config.json` 的目录误判为完整（改为要求至少有权重文件）
- 删除根目录残留的空 `data/` 目录
## 1.0.0 (2026-06-07)
## 0.5.0 (2026-06-06)
### 新增
- **运行模式切换**：新增 `mode` 配置（`integrated` / `standalone`）
- Web UI LLM 卡片改为模式选择器，集成模式下隐藏 LLM 参数
- 新增 `/api/mode` 端点：POST 切换模式
- **pip 锁自动清理**：`--cleanup-locks` 参数、`cleanup_pip_locks()` 函数、安装前自动清理 stale 锁
- **`--no-deps` 反锁死策略**：chromadb 自动分步安装（先 22 个 core deps 再本体）
- **`--mirror` 镜像选择**：支持 `aliyun / tencent / tsinghua / ustc` 国内镜像源
- **`--dry-run` 试运行模式**：只检测不安装，报告将要安装的包列表
- **流式输出**：`_pip_run()`、`run_command()` 改为 `Popen` 逐行流式输出，用户和 Bash 工具实时看到进度
- pip 安装日志自动写入 `data/logs/pip_install_*.log`
### 修复
- **`except Exception: pass` 吞异常**：install_packages 返回空 {} 却报"安装完成"，改为明确 catch + 报告
- **安装后验证**：`pip list` + `check_missing()` 双重确认才报 OK，不再虚假通过
- **包名标准化**：`list_installed()` 统一 `_`→`-`，修复 `huggingface_hub` vs `huggingface-hub` 不匹配
- **NameError**：`--auto-install` 失败提示中的 `{python}` 未定义
- **config.py `load_config()`**：`mode` 字段非 dict 导致 `.update()` 崩溃，兼容非 dict 顶层字段
### 重构
- SKILL.md 及全文件删除 WorkBuddy 特化引用，改为 `xxxx` 代指任意智能体
- 所有 docstring 和注释统一通用化描述
## 0.4.0 (2026-06-06)
### 修复
- **【关键】`rag_env_setup.py` pip 锁死导致 auto-install 报 OK 但啥也没装的 BUG**
- 根因：`install_packages()` 内 `except Exception: pass` 吞掉 pip 升级超时异常，返回空 `{}`，调用方误判为安装成功
- 修复：删除裸 `except: pass`，所有异常明确 catch 并报告
- 修复：安装后通过 `pip list` + `check_missing()` 双重验证才报 OK
- 修复：安装前自动检测并清理 stale pip 锁文件（Windows `%LOCALAPPDATA%/pip/ephem/`）
- **新增 pip 锁自动清理** — `--cleanup-locks` 参数、`cleanup_pip_locks()` 函数、安装前自动清理
- **新增 `--no-deps` 反锁死策略** — chromadb 自动分步安装（先 core deps 再本体），耗时过长的依赖图不会一次性解析
- **新增 `--mirror` 镜像选择** — 支持 `aliyun / tencent / tsinghua / ustc` 四个国内镜像源
- **新增 `--dry-run` 试运行模式** — 只检测不安装，报告将要安装的包列表
- **SKILL.md**：更新命令速查表，补充 `--cleanup-locks` 和 `--mirror`
- **`_pip_run()` 改为流式输出而非 `capture_output`**：修复 Bash 工具因长时间无字符输出而超时杀进程的问题
- **`list_installed()` 包名标准化**：修复 pip 输出 `huggingface_hub`（下划线）但 requirements 列表写 `huggingface-hub`（连字符）导致的验证误报
- **修复 NameError**：`--auto-install` 失败提示中的 `{python}` 未定义
## 0.3.0 (2026-06-06)
### 重构
- **双模式架构**：拆分为 `rag_skill.py`（技能模式，纯检索无 LLM）和 `rag_standalone.py`（独立Github ReposUpdated 1d agoRank 70
AionUi
Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!
MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70
activepieces
AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
OPENCLAW
Github ReposUpdated 6mo agoRank 70
cherry-studio
AI productivity studio with smart chat, autonomous agents, and 300+ assistants.
MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70
CopilotKit
The Frontend for Agents & Generative UI. React + Angular
OPENCLAW
Machine-readable data
The same record, as JSON, for agents and crawlers.
{
"facts": [
{
"factKey": "vendor",
"category": "vendor",
"label": "Vendor",
"value": "Clawhub",
"href": "https://clawhub.ai/ldxs001/skills/local-rag-builder",
"sourceUrl": "https://clawhub.ai/ldxs001/skills/local-rag-builder",
"sourceType": "profile",
"confidence": "medium",
"observedAt": "2026-10-11T03:18:52.138Z",
"isPublic": true
},
{
"factKey": "protocols",
"category": "compatibility",
"label": "Protocol compatibility",
"value": "OpenClaw",
"href": "https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/contract",
"sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/contract",
"sourceType": "contract",
"confidence": "medium",
"observedAt": "2026-10-11T03:18:52.138Z",
"isPublic": true
},
{
"factKey": "traction",
"category": "adoption",
"label": "Adoption signal",
"value": "1.2K downloads",
"href": "https://clawhub.ai/ldxs001/local-rag-builder",
"sourceUrl": "https://clawhub.ai/ldxs001/local-rag-builder",
"sourceType": "profile",
"confidence": "medium",
"observedAt": "2026-10-11T03:18:52.138Z",
"isPublic": true
},
{
"factKey": "latest_release",
"category": "release",
"label": "Latest release",
"value": "1.6.0",
"href": "https://clawhub.ai/ldxs001/local-rag-builder",
"sourceUrl": "https://clawhub.ai/ldxs001/local-rag-builder",
"sourceType": "release",
"confidence": "medium",
"observedAt": "2026-07-11T04:49:29.206Z",
"isPublic": true
},
{
"factKey": "handshake_status",
"category": "security",
"label": "Handshake status",
"value": "UNKNOWN",
"href": "https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/trust",
"sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/trust",
"sourceType": "trust",
"confidence": "medium",
"observedAt": null,
"isPublic": true
}
],
"events": [
{
"eventType": "release",
"title": "Release 1.6.0",
"description": "修复: doc_count计数漂移、语义子切跳过、reranker路径解析、签名反哺毒化; 重构: 精排/路由解耦",
"href": "https://clawhub.ai/ldxs001/local-rag-builder",
"sourceUrl": "https://clawhub.ai/ldxs001/local-rag-builder",
"sourceType": "release",
"confidence": "medium",
"observedAt": "2026-07-11T04:49:29.206Z",
"isPublic": true
}
]
}Record generated Oct 11, 2026.