{"id":"150e329d-05fd-4307-8b2e-2f34ae5a3adf","entityType":"agent","slug":"clawhub-ldxs001-local-rag-builder","name":"local-rag-builder","canonicalUrl":"https://www.xpersona.co/agent/clawhub-ldxs001-local-rag-builder","canonicalPath":"/agent/clawhub-ldxs001-local-rag-builder","generatedAt":"2026-10-11T05:31:54.072Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T03:18:52.138Z","emptyReason":null},"description":"本地 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路径解析、签名反哺毒化; 重构: 精排/路由","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1794v2r46s8y5d1r4jdd7ec5h84rw70:local-rag-builder","sourceUrl":"https://clawhub.ai/ldxs001/local-rag-builder","homepage":"https://clawhub.ai/ldxs001/skills/local-rag-builder","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/ldxs001/local-rag-builder","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/ldxs001/skills/local-rag-builder","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理 Skill: local-rag-builder Owner: ldxs001 Summa"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T03:18:52.138Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T03:18:52.138Z","emptyReason":null},"stars":null,"forks":null,"downloads":1175,"packageName":null,"latestVersion":"1.6.0","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T03:18:52.066Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T03:18:52.138Z","lastCrawledAt":"2026-10-11T03:18:52.066Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T03:18:52.066Z","lastVerifiedAt":null,"highlights":[{"version":"1.6.0","createdAt":"2026-07-11T04:49:29.206Z","changelog":"修复: doc_count计数漂移、语义子切跳过、reranker路径解析、签名反哺毒化; 重构: 精排/路由解耦","fileCount":22,"zipByteSize":79262},{"version":"1.4.3","createdAt":"2026-07-07T19:28:37.641Z","changelog":"- Removed the default configuration file `data/rag_config.json`. - Internal data/configuration setup may require manual or alternate initialization after upgrade. - No user-facing feature or workflow changes.","fileCount":32,"zipByteSize":160028},{"version":"1.5.0","createdAt":"2026-07-07T19:15:16.479Z","changelog":"重构：JS OO化（f-string→模块级变量根治转义问题）、签名语义化（reranker替代词频统计）、极客模式重构（分块编辑/开关/模板管理）。修复：路由脱钩、签名残留、单线程阻塞、缓存问题。优化：变量输入框提示、保存节流","fileCount":33,"zipByteSize":160760},{"version":"1.4.2","createdAt":"2026-07-06T15:11:46.342Z","changelog":"重构：Prompt模板系统/用户层分离——A系统指令+B资料占位+C问题占位+E回答前缀固化，D输出格式指令暴露给用户编辑。Web UI只显示用户层，系统层只读预览。向后兼容自动迁移旧模板","fileCount":33,"zipByteSize":157028},{"version":"1.4.1","createdAt":"2026-07-06T12:55:09.022Z","changelog":"修复：检索冒TextInputSequence must be str崩溃（_load_signatures返回的dict传给tokenizer，TypeError未被except捕获）","fileCount":33,"zipByteSize":156080},{"version":"1.4.0","createdAt":"2026-07-06T12:44:19.759Z","changelog":"修复：多页PDF只切第一页、语义子切批次内重复ID(HNSW损坏)、PDF分类读二进制为UTF-8乱码、h2 capture group只取仪器代码不取整行。改进：PDF乱码检测+OCR回退（CJK占比<10%触发），路由层hybrid加权投票（关键词40%+语义60%），upsert替代add_documents杜绝HNSW损坏。文档与代码脱钩修复7处","fileCount":33,"zipByteSize":155852},{"version":"1.3.8","createdAt":"2026-07-06T05:15:09.520Z","changelog":"修复: Chroma doc_count WAL漏计, HTML文档数不刷新, 改为max(chroma_count, 累加值)兜底; 新增: SM3国密哈希去重, 相同内容重复导入时覆盖而非追加","fileCount":32,"zipByteSize":148018},{"version":"1.3.7","createdAt":"2026-07-06T04:16:00.701Z","changelog":"修复: _load_index() 磁盘扫描补全KB，--kb-list 可正确显示全部10个知识库，不再遗漏磁盘已有但索引缺失的KB","fileCount":32,"zipByteSize":147206}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1794v2r46s8y5d1r4jdd7ec5h84rw70:local-rag-builder","setupComplexity":"low","setupSteps":["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":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T05:31:54.068Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-local-rag-builder/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T03:18:52.138Z","emptyReason":null},"readme":"Skill: local-rag-builder\n\nOwner: ldxs001\n\nSummary: 本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理\n\nTags: 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\n\nVersion history:\n\nv1.6.0 | 2026-07-11T04:49:29.206Z | user\n\n修复: doc_count计数漂移、语义子切跳过、reranker路径解析、签名反哺毒化; 重构: 精排/路由解耦\n\nv1.4.3 | 2026-07-07T19:28:37.641Z | user\n\n- Removed the default configuration file `data/rag_config.json`.\n- Internal data/configuration setup may require manual or alternate initialization after upgrade.\n- No user-facing feature or workflow changes.\n\nv1.5.0 | 2026-07-07T19:15:16.479Z | user\n\n重构：JS OO化（f-string→模块级变量根治转义问题）、签名语义化（reranker替代词频统计）、极客模式重构（分块编辑/开关/模板管理）。修复：路由脱钩、签名残留、单线程阻塞、缓存问题。优化：变量输入框提示、保存节流\n\nv1.4.2 | 2026-07-06T15:11:46.342Z | user\n\n重构：Prompt模板系统/用户层分离——A系统指令+B资料占位+C问题占位+E回答前缀固化，D输出格式指令暴露给用户编辑。Web UI只显示用户层，系统层只读预览。向后兼容自动迁移旧模板\n\nv1.4.1 | 2026-07-06T12:55:09.022Z | user\n\n修复：检索冒TextInputSequence must be str崩溃（_load_signatures返回的dict传给tokenizer，TypeError未被except捕获）\n\nv1.4.0 | 2026-07-06T12:44:19.759Z | user\n\n修复：多页PDF只切第一页、语义子切批次内重复ID(HNSW损坏)、PDF分类读二进制为UTF-8乱码、h2 capture group只取仪器代码不取整行。改进：PDF乱码检测+OCR回退（CJK占比<10%触发），路由层hybrid加权投票（关键词40%+语义60%），upsert替代add_documents杜绝HNSW损坏。文档与代码脱钩修复7处\n\nv1.3.8 | 2026-07-06T05:15:09.520Z | user\n\n修复: Chroma doc_count WAL漏计, HTML文档数不刷新, 改为max(chroma_count, 累加值)兜底; 新增: SM3国密哈希去重, 相同内容重复导入时覆盖而非追加\n\nv1.3.7 | 2026-07-06T04:16:00.701Z | user\n\n修复: _load_index() 磁盘扫描补全KB，--kb-list 可正确显示全部10个知识库，不再遗漏磁盘已有但索引缺失的KB\n\nv1.3.6 | 2026-07-06T03:44:49.984Z | user\n\n修复: _load_index() 索引重置丢失KB（索引为空时直接重置为仅default），改为无条件扫描磁盘目录恢复；run_import() 路由逻辑修复，--kb 默认值从 'default' 改为 None，区分用户未指定与指定default\n\nv1.3.5 | 2026-07-06T01:58:53.425Z | user\n\n新增: run_import() 流程钩子(router.enabled=true 时自动语义分类). 变更: FallbackRouter 提至循环外(省6次模型重载). 撤回: 1.3.4 best_score=-inf 改动(跨语言噪声路由问题)\n\nv1.3.4 | 2026-07-06T01:17:16.614Z | user\n\n修复: auto_classify() 语义模式 best_score 初始值导致负分被丢弃(英文文献无法路由); FallbackRouter() 每次 KB 迭代均 new 实例导致 7 次重载 1.3GB reranker 模型. 修复为: 语义模式 best_score=-inf, FallbackRouter 提至循环外单例复用\n\nv1.3.3 | 2026-07-05T07:21:40.995Z | user\n\n修复_load_index()空字典导致索引丢失的bug（if not data改为if data is None），增加索引自动恢复\n\nv1.3.2 | 2026-07-05T07:09:55.564Z | user\n\nChromaDB容灾备份（入库前自动备份sqlite3，写入失败自动回滚）、HNSW损坏自动修复（查询时重建索引）、Python 3.11 f-string兼容修复、ChromaDB检测更新为sqlite3\n\nv1.3.1 | 2026-07-05T06:37:32.814Z | user\n\n扫描PDF自动OCR（import_documents_to_kb回退EasyOCR）、KB签名自动更新、签名质量提升（中文词加权+过滤数字）、文档一致性修复\n\nv1.3.0 | 2026-07-05T05:50:30.134Z | user\n\n路由层关键词语义分类：入库/出库共享reranker语义匹配，扩展名始终精确\n\nv1.2.18 | 2026-07-05T05:26:57.673Z | user\n\n修复 Web UI UnboundLocalError（RECOMMENDED_RERANK_MODELS import 顺序错误）\n\nv1.2.17 | 2026-07-05T05:15:41.647Z | user\n\n知识库列表移除重复的KB嵌入模型下拉框，统一由规则编辑器管理\n\nv1.2.16 | 2026-07-05T04:58:54.434Z | user\n\n修复KB模型选择器存路径而非model_id；get_embeddings新增model_id→路径解析\n\nv1.2.15 | 2026-07-05T04:55:02.989Z | user\n\n修复KB模型选择器混入重排序模型；模型列表增加[嵌入]/[重排序]标签\n\nv1.2.14 | 2026-07-05T04:27:47.657Z | user\n\n修复 LICENSE.md 版权持有者署名\n\nv1.2.13 | 2026-07-05T04:24:35.714Z | user\n\nLICENSE.md 新增第三方模型许可声明表\n\nv1.2.12 | 2026-07-05T04:21:33.780Z | user\n\nEasyOCR回退机制；OCR描述修正（CPU/GPU区分+easyocr）；SKILL.md限制描述修正\n\nv1.2.11 | 2026-07-05T03:01:05.069Z | user\n\n修复：检索k值UI联动（开Rerank时k自动设为20）、输入源状态指示器初始黑色问题、清理冗余代码\n\nv1.2.10 | 2026-07-05T02:49:18.957Z | user\n\n检索k自动扩容：rerank开启时自动将k从3扩容到max(k, top_k×4)（默认20），保证精排候选池；文档对齐4份\n\nv1.2.9 | 2026-07-05T02:19:30.053Z | user\n\n修复：语义切分硬编码嵌入模型（不随用户配置变化）+ sentence切分fallback delimiter乱附着\n\nv1.1.3 | 2026-06-25T10:23:21.060Z | auto\n\nlocal-rag-builder 1.1.3\n\n- 增加了 SKILL.md，详细说明本地 RAG 系统搭建功能、支持的环境、切分策略、知识库管理与 Web 可视化配置。\n- 明确集成模式（纯检索，供智能体调用）与独立模式（检索+LLM全链路）的区别和工作流程。\n- 列举了正向/否定触发条件，并补充核心能力、文件索引、使用指引与约束、限制说明。\n- 支持环境检测修复、嵌入模型多源下载、插件注册、参数调节和多知识库自动分类等功能。\n- 提供命令行快速开始示例和完整运行流程说明。\n\nArchive index:\n\nArchive v1.6.0: 22 files, 79262 bytes\n\nFiles: _meta.json (136b), references/antipatterns.md (927b), references/architecture.md (4578b), references/changelog.md (6656b), references/examples.md (2940b), references/faq.md (1892b), references/guide.md (13536b), references/llm-setup.md (4328b), references/permissions.md (3646b), scripts/config.py (3200b), scripts/embedding_model_manager.py (16868b), scripts/knowledge_base_manager.py (12948b), scripts/prompt_manager.py (3987b), scripts/rag_core.py (8189b), scripts/rag_env_setup.py (20719b), scripts/rag_skill.py (4728b), scripts/rag_standalone.py (14620b), scripts/rag_web_ui.py (61418b), scripts/text_splitter.py (27519b), scripts/utils.py (6993b), skill-card.md (2505b), SKILL.md (10688b)\n\nFile v1.6.0:SKILL.md\n\n---\r\nname: local-rag-builder\r\nversion: 1.0.5\r\ndescription: 本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理\r\nauthor: wUwproject\r\nlicense: MIT\r\nsensitive_access: false\r\ncritical_write: false\r\ntrigger: ['搭建 RAG 系统', '本地知识库', '嵌入模型下载', '文本切分', '向量检索', 'RAG 环境配置', '下载模型', '入库文档', '切分文档', '知识库管理']\r\ntrigger_negative: ['纯聊天', '简单问答']\r\ntags: ['rag', 'embedding', 'llm', 'python', 'vector-db', 'text-splitter', 'guard-stack', 'plugin']\r\ndata_dir: skills/.standardization/local-rag-builder/data/\r\nh1_position: true\r\nexternal_data_dir: true\r\npermission_weight: LOW\r\nfaq_quality: improve_qa\r\nmeta_field_sync: true\r\ndata_dir_compliance: true\r\ncreate_permissions_md: true\r\n---\r\n# local-rag-builder（本地 RAG 搭建工具）\r\n\r\n一站式本地 RAG 系统搭建工具。支持环境自动检测修复、嵌入模型多源下载、5 种切分策略 + GuardStack 守卫栈 + 后处理子切 + 插件注册、多知识库管理与自动分类规则、可调 Prompt、Web 可视化配置。\r\n\r\n**两种运行模式：**\r\n- **🔌 集成模式（默认）** — 纯检索，不调用 LLM。智能体（xxxx 等）根据检索到的 context 自行回答。无需配置 LLM，无额外推理成本。\r\n- **🤖 独立模式** — 检索 + LLM 全链路。`rag_standalone.py` 直接调用外部 LLM（LM Studio / Ollama / vLLM）完成回答，不经过智能体。用户自行选择平台和模型。\r\n\r\n> **工作流说明（以下 xxxx 代指任意智能体）：**\r\n>\r\n> **集成模式：**\r\n> 1. 你把文档/链接给 xxxx → xxxx 调用 `rag_skill.py` 向量化入库\r\n> 2. 你提问 → xxxx 调用 `rag_skill.py --query \"...\"` 检索知识库\r\n> 3. xxxx 根据检索到的 context 组织回答\r\n>\r\n> **独立模式：**\r\n> 1. 你把文档/链接给 xxxx → xxxx 调用 `rag_standalone.py --import-file ` 入库\r\n> 2. 你提问 → xxxx 调用 `rag_standalone.py --query \"...\"` \r\n> 3. `rag_standalone.py` 自行检索知识库 → 调用本地 LLM → 输出回答\r\n> 4. xxxx 仅透传结果，不参与推理\r\n\r\n## 触发场景\r\n\r\n- **搭建 RAG** — \"帮我搭一个本地 RAG 系统\"\r\n- **环境检测** — \"检查我的 Python 环境能否跑 RAG\"\r\n- **下载模型** — \"下载一个嵌入模型\" / \"换个模型源重试\"\r\n- **切分文档** — \"对这个 Markdown 文件做层级切分\"\r\n- **向量检索** — \"把这份资料入库，搜索相似内容\"\r\n- **知识库管理** — \"创建一个知识库\" / \"把这类资料存入指定库\"\r\n- **调整参数** — \"更新切分参数\" / \"改 Prompt 模板\"\r\n- **智能体集成** — \"根据这份资料回答：xxx\"（智能体调用 skill 的集成模式）\r\n- **不触发**：纯 LLM 聊天不需要检索、简单问答不需要外部资料\r\n\r\n## 核心能力\r\n\r\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\r\n\r\n| # | 能力 | 说明 |\r\n|---|------|------|\r\n| 1 | **环境自动检测修复** | 检测 Python 版本（需 3.8-3.11）、缺失包，自动创建虚拟环境安装 |\r\n| 2 | **嵌入模型管理** | 多源下载（ModelScope / HuggingFace 镜像 / 官方 / LLM 找源），自动重试，完整性校验，路径修正 |\r\n| 3 | **5 种切分策略 + GuardStack + 后处理** | 固定窗口、递归切、层级/标题切、按句切、语义切；守卫栈（mermaid/代码块/公式/表格/HTML 保护）；后处理子切（递归/固定/语义，metadata 白名单继承） |\r\n| 4 | **多知识库管理** | 支持多个向量知识库并行，LLM 自动分类入库或用户指定 |\r\n| 5 | **可调 Prompt** | 模板持久化，支持自定义占位符（`{context}` `{question}`），运行时编辑 |\r\n| 6 | **Web 可视化界面** | 内嵌 HTML 配置面板：输入源开关、GuardStack 守卫配置、5 策略动态表单 + 后处理配置、极客模式 JSON 编辑器 + 配置模板管理、知识库自动分类规则编辑器 |\r\n| 7 | **双模式接口** | 集成模式（`--retrieve-only` / `--mode integrated`）纯检索，智能体自行回答；独立模式（`--mode standalone`）检索 + LLM 全链路 |\r\n\r\n### 渐进式文件索引\r\n\r\n| 文件名 | 分类 | 包含内容 | 审计关联 |\r\n|--------|------|----------|----------|\r\n| `references/antipatterns.md` | 规范指南 | skill 编写中的常见反模式。包含：错误做法示例、正确做法示例、避坑指引。 | R-18 |\r\n| `references/architecture.md` | 架构设计 | skill-standardization 整体架构。包含：模块关系、数据流、核心设计决策。 | 无 |\r\n| `references/changelog.md` | 版本管理 | 版本更新日志。包含：版本号、变更类型、修复项、升级说明。 | R-24 |\r\n| `references/examples.md` | 使用示例 | 各场景完整执行示例。包含：CLI 命令、执行过程、输出结果。 | R-25 C-17 |\r\n| `references/faq.md` | 常见问题 | 常见疑问与解答。包含：问题分类、原因分析、解决方案。 | R-19, R-25 C-19 |\r\n| `references/guide.md` | 使用指南 | 三种执行模式操作教程。包含：audit/create/refactor 流程、参数说明、注意事项。 | 无 |\r\n| `references/llm-setup.md` | 参考文档 | > 本文件适用于 **独立模式**（`rag_standalone.py`）。技能模式（`rag_skill.py`）不需要 LLM。 | 无 |\r\n| `references/permissions.md` | 权限与测试 | 权限扫描说明与测试结论。包含：风险等级、高权限操作说明、测试概览、计时统计。 | R-15, R-16 |\r\n## 快速开始\r\n\r\n```bash\r\n# 1. 进入技能目录\r\ncd ~/.workbuddy/skills/local-rag-builder\r\n\r\n# 2. 运行环境检测（自动修复，建议首次用国内镜像）\r\npython scripts/rag_env_setup.py --auto-install --mirror aliyun # 国内用户推荐\r\n# python scripts/rag_env_setup.py --auto-install # 海外用户/默认\r\n# python scripts/rag_env_setup.py --check-only # 仅检测不安装\r\n# python scripts/rag_env_setup.py --cleanup-locks # 清理 pip 锁文件\r\n\r\n# 3. 下载嵌入模型（交互式选择）\r\npython scripts/embedding_model_manager.py --interactive\r\n\r\n# 4. 启动 Web 配置界面\r\npython scripts/rag_web_ui.py\r\n\r\n# 5a. [技能模式] 纯检索，供智能体调用（无需 LLM）\r\npython scripts/rag_skill.py --query \"问题\"\r\npython scripts/rag_skill.py --query \"问题\" --json # JSON 输出\r\n\r\n# 5b. [独立模式] 检索 + LLM 全链路，需外部 LLM 服务\r\npython scripts/rag_standalone.py # 交互式 CLI\r\npython scripts/rag_standalone.py --query \"问题\" # 单次问答\r\npython scripts/rag_standalone.py --query \"问题\" --json # JSON 输出\r\npython scripts/rag_standalone.py --llm-help # 查看 LLM 接入指南\r\n```\r\n\r\n## 工作流程\r\n\r\n1. **环境准备** — `rag_env_setup.py` 检测并安装依赖\r\n2. **模型下载** — `embedding_model_manager.py` 下载/校验嵌入模型\r\n3. **文档入库** — `text_splitter.py` 切分文档 → `knowledge_base_manager.py` 向量化\r\n4. **模式选择** — 根据用途选择入口\r\n - **技能模式** → `rag_skill.py`（纯检索，供智能体调用，无需 LLM）\r\n - **独立模式** → `rag_standalone.py`（检索 + LLM 全链路，需外部 LLM）\r\n5. **配置调整** — `rag_web_ui.py` 提供可视化面板\r\n\r\n## 命令速查\r\n\r\n| 脚本 | 作用 | 核心参数 |\r\n|------|------|----------|\r\n| `rag_env_setup.py` | 环境检测与修复 | `--auto-install`, `--check-only`, `--cleanup-locks`, `--mirror`, `--dry-run` |\r\n| `embedding_model_manager.py` | 嵌入模型管理 | `--download`, `--list`, `--check`, `--remove` |\r\n| `text_splitter.py` | 文本切分（三层流水线） | `--strategy`, `--guard`, `--secondary`, `--chunk-size`, `--input`, `--list-strategies` |\r\n| `rag_core.py` | 共享核心（被其他模块导入，不直接运行） | — |\r\n| **`rag_skill.py`** | **[技能模式] 纯检索接口** | **`--query`, `--kb`, `--json`** |\r\n| **`rag_standalone.py`** | **[独立模式] 检索+LLM** | **`--query`, `--kb`, `--llm-help`, `--json`** |\r\n| `rag_web_ui.py` | Web 配置界面 | `--port`, `--gen-html` |\r\n| `prompt_manager.py` | Prompt 管理 | `--set`, `--show`, `--reset` |\r\n| `knowledge_base_manager.py` | 知识库管理 | `--create`, `--import`, `--list`, `--delete`, `--set-rule`, `--classify` |\r\n\r\n## 数据目录（skills/.standardization/local-rag-builder/data/）\r\n\r\n```\r\ndata/\r\n├── kb/ # 向量数据库目录（每个知识库一个子目录）\r\n│ ├── default/ # 默认知识库\r\n│ ├── art/ # 艺术类资料\r\n│ └── politics/ # 政治类资料\r\n├── models/ # 下载的嵌入模型\r\n├── prompts/ # Prompt 模板文件\r\n├── config/ # 运行时配置\r\n├── output/ # 导出产物\r\n├── logs/ # 执行日志\r\n├── cache/ # 缓存\r\n└── config_templates/ # 用户保存的配置模板\r\n```\r\n\r\n## 自定义扩展（插件注册）\r\n\r\n本技能 v1.0 支持通过代码注册自定义切分策略和守卫。\r\n\r\n```python\r\nfrom text_splitter import register_strategy, register_guard, StrategyPlugin, GuardPlugin, Guard\r\n\r\n# 自定义切分策略\r\ndef my_splitter(text, my_param=100, **kwargs):\r\n from langchain_core.documents import Document\r\n # 自定义切分逻辑\r\n return [Document(page_content=text)]\r\n\r\nregister_strategy(StrategyPlugin(\r\n \"my_split\", \"我的自定义切分\", my_splitter,\r\n config_schema={\r\n \"my_param\": {\"type\": \"int\", \"label\": \"参数名\", \"default\": 100, \"min\": 1, \"max\": 1000},\r\n \"flag\": {\"type\": \"bool\", \"label\": \"开关\", \"default\": False},\r\n },\r\n default_config={\"my_param\": 100, \"flag\": False},\r\n))\r\n\r\n# 自定义守卫\r\nmy_guard = Guard(\"my_guard\", re.compile(r'```special\\n[\\s\\S]*?\\n```'))\r\nregister_guard(GuardPlugin(\"my_guard\", \"保护特殊代码块\", my_guard))\r\n```\r\n\r\n注册后自动出现在 Web UI 的下拉列表中，配置表单自动生成。\r\n\r\n## 重要约定\r\n\r\n1. **Python 版本**：建议 3.8-3.11（3.12+ 需测试 chromadb 兼容性）\r\n2. **嵌入模型路径**：下载后自动修正真实路径（如 `bge-small-zh-v1___5`）\r\n3. **知识库隔离**：不同资料自动/手动归入不同库\r\n4. **重置**：删除 `data/` 下对应子目录即可重置相关数据\n\nFile v1.6.0:_meta.json\n\n{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"local-rag-builder\",\n \"version\": \"1.6.0\",\n \"publishedAt\": 1783745369206\n}\n\nFile v1.6.0:references/antipatterns.md\n\n# 反模式 — local-rag-builder\n\n## 不要在 SKILL.md 正文写完整教程\n\n**错误做法**：在 SKILL.md 中展开所有脚本的详细用法。\n\n**正确做法**：SKILL.md 只写概要，详细教程拆分到 `references/guide.md`。本技能已遵循此规范。\n\n## 不要硬编码模型路径\n\n**错误做法**：\n```python\nmodel_path = \"D:/models/bge-small-zh-v1.5\"\n```\n\n**正确做法**：通过配置系统管理模型路径，支持 Web UI 和 CLI 动态切换。\n\n## 不要在所有场景都用同一种切分策略\n\n**错误做法**：对所有文档都用固定窗口切分。\n\n**正确做法**：根据文档类型选择策略（Markdown → 标题切，长文 → 语义切，通用 → 递归切）。\n\n## 不要忽略 Python 版本兼容性\n\n**错误做法**：在 Python 3.12+ 上直接安装 chromadb。\n\n**正确做法**：使用 `rag_env_setup.py` 检测版本，必要时创建 3.11 虚拟环境。\n\nFile v1.6.0:references/architecture.md\n\n# 架构设计 — local-rag-builder v1.0.0\r\n\r\n## 整体架构\r\n\r\n```\r\n┌─────────────────────────────────────────────────────┐\r\n│ CLI (rag_skill.py / rag_standalone.py) │\r\n│ Web UI (rag_web_ui.py) │\r\n├─────────────────────────────────────────────────────┤\r\n│ rag_core.py (RAG 问答核心) │\r\n│ text_splitter.py (5 切分策略 + GuardStack + 后处理 + 插件注册) │\r\n│ knowledge_base_manager.py (多知识库管理) │\r\n│ prompt_manager.py (Prompt 模板管理) │\r\n│ embedding_model_manager.py (嵌入模型生命周期) │\r\n│ rag_env_setup.py (环境检测与安装) │\r\n├─────────────────────────────────────────────────────┤\r\n│ config.py (统一配置管理) │\r\n│ utils.py (通用工具函数) │\r\n├─────────────────────────────────────────────────────┤\r\n│ data/ (技能数据目录) │\r\n│ ├── kb/ (向量知识库) │\r\n│ ├── models/ (嵌入模型) │\r\n│ ├── prompts/ (Prompt 模板) │\r\n│ ├── config/ (运行时配置) │\r\n│ └── output/ (导出产物) │\r\n└─────────────────────────────────────────────────────┘\r\n```\r\n\r\n## 模块依赖关系\r\n\r\n```\r\nrag_skill.py / rag_standalone.py (双入口)\r\n ├── rag_core.py\r\n │ ├── config.py ← utils.py\r\n │ ├── prompt_manager.py ← utils.py\r\n │ ├── text_splitter.py\r\n │ └── knowledge_base_manager.py ← utils.py\r\n ├── embedding_model_manager.py ← utils.py\r\n └── rag_env_setup.py\r\n\r\nrag_web_ui.py (入口)\r\n ├── config.py ← utils.py\r\n ├── prompt_manager.py ← utils.py\r\n ├── text_splitter.py ← 策略注册表 + 守卫注册表\r\n ├── embedding_model_manager.py\r\n ├── knowledge_base_manager.py\r\n └── rag_core.py\r\n```\r\n\r\n## 数据流\r\n\r\n### 索引流程（文档入库）\r\n```\r\n文档 → text_splitter.py (切分) → embeddings (向量化) → Chroma (存储)\r\n```\r\n\r\n### 切分流水线架构\r\n\r\n```\r\n原始文本 → [守卫栈(多选)] → [主策略(单选)] → [后处理(单选/不选)] → 最终 chunks\r\n\r\n守卫栈：mermaid / code / math / table / html（可扩展）\r\n主策略：fixed / recursive / headers / sentence / semantic（可扩展）\r\n后处理：recursive / fixed / semantic 子切（metadata 白名单继承）\r\n```\r\n\r\n## 查询流程（问答）\r\n```\r\n用户问题 → embeddings (向量化) → Chroma (检索) → 上下文 + Prompt → LLM → 回答\r\n```\r\n\r\n## 数据目录结构\r\n\r\n```\r\nskills/.standardization/local-rag-builder/data/\r\n├── kb/ # 向量知识库\r\n│ ├── default/ # 默认知识库\r\n│ ├── art/ # 艺术类 (按分类规则)\r\n│ ├── politics/ # 政治类\r\n│ └── kb_index.json # 知识库索引\r\n├── models/ # 嵌入模型\r\n│ └── model_index.json # 模型索引\r\n├── prompts/ # Prompt 模板\r\n│ └── custom_prompt_template.txt\r\n├── config/ # 运行时配置\r\n│ └── rag_config.json\r\n├── output/ # 导出产物\r\n├── cache/ # 下载缓存\r\n├── config_templates/ # 配置模板\r\n└── kb/\r\n ├── default/\r\n ├── kb_index.json\r\n └── auto_classify_rules.json # 分类规则\r\n```\r\n\r\n## 配置体系\r\n\r\n配置由 `config.py` 统一管理，JSON 格式存储。\r\n\r\n配置层级：\r\n1. 默认配置（`DEFAULT_CONFIG` 硬编码）\r\n2. 持久化配置（`data/config/rag_config.json`）\r\n3. 运行时更新（通过 Web UI 或 CLI）\r\n\r\n重置操作将删除持久化配置并恢复默认值。\n\nFile v1.6.0:references/changelog.md\n\n## 1.0.5 (2026-06-13)\r\n\r\n### 修复\r\n- refactor: 标准化改造（渐进式索引表格式修复、权限文档补充）\r\n\r\n## 1.0.4 (2026-06-13)\r\n\r\n### 新增\r\n- KB 专属嵌入模型：每个知识库可独立选择嵌入模型，未指定时回退全局默认\r\n- Web UI KB 管理新增模型下拉选择器\r\n- `/api/kb-model`、`/api/kb-models` API 端点\r\n\r\n### 修复\r\n- `knowledge_base_manager.py` `create_knowledge_base()` 新增 `model_id` 参数\r\n- `rag_core.py` `get_embeddings()` 新增 `kb_name` 参数，自动查 KB 专属模型\r\n\r\n## 1.0.3 (2026-06-13)\r\n\r\n### 修复\r\n- 标准化改造：SKILL.md frontmatter 修复、权限文档补充、产出物路径合规\r\n- 三端版本同步至 1.0.3\r\n\r\n## 1.0.2 (2026-06-13)\r\n\r\n### 修复\r\n- 删除根目录 `.venv_rag` 遗留虚拟环境\r\n- 同步三端版本号至 1.0.2\r\n\r\n## 1.0.1 (2026-06-13)\r\n\r\n### 修复\r\n- `rag_core.py` 配置路径失效时无法回退到 `find_model_dirs()`（`if not model_path` 改为 `if not model_path or not os.path.exists(model_path)`）\r\n- `rag_core.py` `HuggingFaceEmbeddings` 未限制本地加载（添加 `local_files_only=True` 避免加载失败时摸 Hub）\r\n- `embedding_model_manager.py` `_check_integrity()` 将仅有 `config.json` 的目录误判为完整（改为要求至少有权重文件）\r\n- 删除根目录残留的空 `data/` 目录\r\n\r\n## 1.0.0 (2026-06-07)\r\n\r\n## 0.5.0 (2026-06-06)\r\n\r\n### 新增\r\n- **运行模式切换**：新增 `mode` 配置（`integrated` / `standalone`）\r\n - Web UI LLM 卡片改为模式选择器，集成模式下隐藏 LLM 参数\r\n - 新增 `/api/mode` 端点：POST 切换模式\r\n- **pip 锁自动清理**：`--cleanup-locks` 参数、`cleanup_pip_locks()` 函数、安装前自动清理 stale 锁\r\n- **`--no-deps` 反锁死策略**：chromadb 自动分步安装（先 22 个 core deps 再本体）\r\n- **`--mirror` 镜像选择**：支持 `aliyun / tencent / tsinghua / ustc` 国内镜像源\r\n- **`--dry-run` 试运行模式**：只检测不安装，报告将要安装的包列表\r\n- **流式输出**：`_pip_run()`、`run_command()` 改为 `Popen` 逐行流式输出，用户和 Bash 工具实时看到进度\r\n- pip 安装日志自动写入 `data/logs/pip_install_*.log`\r\n\r\n### 修复\r\n- **`except Exception: pass` 吞异常**：install_packages 返回空 {} 却报\"安装完成\"，改为明确 catch + 报告\r\n- **安装后验证**：`pip list` + `check_missing()` 双重确认才报 OK，不再虚假通过\r\n- **包名标准化**：`list_installed()` 统一 `_`→`-`，修复 `huggingface_hub` vs `huggingface-hub` 不匹配\r\n- **NameError**：`--auto-install` 失败提示中的 `{python}` 未定义\r\n- **config.py `load_config()`**：`mode` 字段非 dict 导致 `.update()` 崩溃，兼容非 dict 顶层字段\r\n\r\n### 重构\r\n- SKILL.md 及全文件删除 WorkBuddy 特化引用，改为 `xxxx` 代指任意智能体\r\n- 所有 docstring 和注释统一通用化描述\r\n\r\n## 0.4.0 (2026-06-06)\r\n\r\n### 修复\r\n- **【关键】`rag_env_setup.py` pip 锁死导致 auto-install 报 OK 但啥也没装的 BUG**\r\n - 根因：`install_packages()` 内 `except Exception: pass` 吞掉 pip 升级超时异常，返回空 `{}`，调用方误判为安装成功\r\n - 修复：删除裸 `except: pass`，所有异常明确 catch 并报告\r\n - 修复：安装后通过 `pip list` + `check_missing()` 双重验证才报 OK\r\n - 修复：安装前自动检测并清理 stale pip 锁文件（Windows `%LOCALAPPDATA%/pip/ephem/`）\r\n- **新增 pip 锁自动清理** — `--cleanup-locks` 参数、`cleanup_pip_locks()` 函数、安装前自动清理\r\n- **新增 `--no-deps` 反锁死策略** — chromadb 自动分步安装（先 core deps 再本体），耗时过长的依赖图不会一次性解析\r\n- **新增 `--mirror` 镜像选择** — 支持 `aliyun / tencent / tsinghua / ustc` 四个国内镜像源\r\n- **新增 `--dry-run` 试运行模式** — 只检测不安装，报告将要安装的包列表\r\n- **SKILL.md**：更新命令速查表，补充 `--cleanup-locks` 和 `--mirror`\r\n- **`_pip_run()` 改为流式输出而非 `capture_output`**：修复 Bash 工具因长时间无字符输出而超时杀进程的问题\r\n- **`list_installed()` 包名标准化**：修复 pip 输出 `huggingface_hub`（下划线）但 requirements 列表写 `huggingface-hub`（连字符）导致的验证误报\r\n- **修复 NameError**：`--auto-install` 失败提示中的 `{python}` 未定义\r\n\r\n## 0.3.0 (2026-06-06)\r\n\r\n### 重构\r\n- **双模式架构**：拆分为 `rag_skill.py`（技能模式，纯检索无 LLM）和 `rag_standalone.py`（独立模式，检索+LLM 全链路）\r\n- `rag_core.py` 删除所有 LLM 依赖，改为纯核心层。新增 `format_skill_output()` 返回结构化 JSON（含已填充 prompt）\r\n- `embedding_model_manager.py`：路径查找改为通用内容感知方案（`_normalize` + `_name_similarity` + `_is_model_dir`），不再依赖任何特定变形模式\r\n\r\n### 新增\r\n- `rag_skill.py`：零 LLM 依赖的技能接口，仅返回结构化 JSON，供任何智能体使用\r\n- `rag_standalone.py`：独立系统，含交互式 CLI + `/llm-help` 命令 + 内置三个 LLM 方案接入指南\r\n- `references/llm-setup.md`：结构化 LLM 接入文档（LM Studio / Ollama / vLLM 三方案含配置方式）\r\n\r\n### 修复\r\n- `rag_web_ui.py`：修复 `verify_llm_connection` 导入路径（已迁移到 rag_standalone）\r\n- `config.py`/`prompt_manager.py`/`rag_env_setup.py`：exception 覆盖加固\r\n- R-10/R-11/R-23 合规修复（产出物路径迁移、文档引用更新）\r\n- 文档引用 `rag_interface.py` 全部更新为 `rag_skill.py`/`rag_standalone.py`\r\n\r\n## 0.2.0 (2026-06-06)\r\n\r\n- 重构: 嵌入模型路径查找改为通用内容感知方案（`_normalize` + `_name_similarity` + `_is_model_dir`），不再依赖特定变形模式\r\n- 重构: `verify_model` 改用 `_is_model_dir` 通用检测\r\n- 重构: `get_model_path` 改用相似度评分匹配\r\n- 修复: exception 覆盖率加固（config.py/prompt_manager.py/rag_env_setup.py）\r\n- 测试: 功能测试通过（D1-D6: 0 BLOCK, 57 WARN）\r\n\r\n## 0.1.1 (2026-06-06)\r\n\r\n- 修复: 数据目录路径合规（R-12）\r\n- 修复: frontmatter 补充 trigger/trigger_negative/license 字段\r\n- 修复: 版本号格式合规\r\n\r\n## 0.1.0 (2026-06-06)\r\n\r\n- 初始版本\r\n- 环境自动检测与修复（Python 版本、缺失包）\r\n- 嵌入模型多源下载（ModelScope/HuggingFace/LLM 搜索）\r\n- 完整性校验与路径修正\r\n- 6 种文本切分策略 + 组合切分\r\n- 多知识库管理与自动分类\r\n- Prompt 模板持久化\r\n- Web 可视化配置界面\r\n- 结构化 JSON 接口（智能体调用）\r\n- 交互式 CLI 界面\n\nFile v1.6.0:references/examples.md\n\n# 使用示例 — local-rag-builder\r\n\r\n## 示例 1：完整搭建流程\r\n\r\n```bash\r\n# 1. 环境检测\r\ncd ~/.workbuddy/skills/local-rag-builder\r\npython scripts/rag_env_setup.py --auto-install\r\n\r\n# 2. 下载嵌入模型\r\npython scripts/embedding_model_manager.py --interactive\r\n# 选择 1: BAAI/bge-small-zh-v1.5\r\n\r\n# 3. 导入测试文档\r\necho \"# 测试文档\r\nRAG 即检索增强生成，是一种结合检索和生成的技术。\r\n它先根据问题从知识库检索相关文档，再输入 LLM 生成答案。\" > test_doc.md\r\n\r\n# 4. 智能体调用（技能模式）\r\npython scripts/rag_skill.py --query \"什么是 RAG？\" --json\r\n\r\n# 5. 独立问答（需外部 LLM）\r\npython scripts/rag_standalone.py --query \"什么是 RAG？\"\r\n```\r\n\r\n## 示例 2：Web 界面操作\r\n\r\n```bash\r\n# 启动 Web 面板\r\npython scripts/rag_web_ui.py --port 8888\r\n# 浏览器打开 http://localhost:8888\r\n```\r\n\r\n## 示例 3：智能体集成调用\r\n\r\n```python\r\nimport subprocess\r\nimport json\r\n\r\nSKILL_DIR = \"~/.workbuddy/skills/local-rag-builder\"\r\nPYTHON = \"python\"\r\n\r\n# 检测环境\r\nresult = subprocess.run(\r\n [PYTHON, f\"{SKILL_DIR}/scripts/rag_env_setup.py\", \"--json\"],\r\n capture_output=True, text=True\r\n)\r\nenv_report = json.loads(result.stdout)\r\n\r\n# 嵌入模型列表\r\nresult = subprocess.run(\r\n [PYTHON, f\"{SKILL_DIR}/scripts/embedding_model_manager.py\", \"--list\", \"--json\"],\r\n capture_output=True, text=True\r\n)\r\nmodels = json.loads(result.stdout)\r\n\r\n# [技能模式] 纯检索（不依赖 LLM）\r\nresult = subprocess.run(\r\n [PYTHON, f\"{SKILL_DIR}/scripts/rag_skill.py\",\r\n \"--query\", \"什么是 RAG？\", \"--json\"],\r\n capture_output=True, text=True\r\n)\r\ndata = json.loads(result.stdout)\r\ncontext = data[\"context\"] # 智能体根据 context 自行回答\r\n\r\n# [独立模式] 全链路问答\r\nresult = subprocess.run(\r\n [PYTHON, f\"{SKILL_DIR}/scripts/rag_standalone.py\",\r\n \"--query\", \"什么是 RAG？\", \"--json\"],\r\n capture_output=True, text=True\r\n)\r\n\r\nprint(answer[\"answer\"])\r\n```\r\n\r\n## 示例 4：多知识库管理\r\n\r\n```bash\r\n# 创建多个知识库\r\npython scripts/knowledge_base_manager.py --create art --desc \"艺术类资料\"\r\npython scripts/knowledge_base_manager.py --create tech --desc \"技术文档\"\r\n\r\n# 配置自动分类规则\r\npython scripts/knowledge_base_manager.py --set-rule art \"艺术,美术,绘画\"\r\npython scripts/knowledge_base_manager.py --set-rule tech \"编程,代码,算法,API\"\r\n\r\n# 测试分类\r\npython scripts/knowledge_base_manager.py --classify \"Python 编程语言\"\r\n# 输出: tech\r\n\r\npython scripts/knowledge_base_manager.py --classify \"梵高向日葵\"\r\n# 输出: art\r\n```\r\n\r\n## 示例 5：自定义 Prompt\r\n\r\n```bash\r\n# 配置带引用的 Prompt\r\npython scripts/prompt_manager.py --set \"你是严谨的研究助手。\\n\\n资料：\\n{context}\\n\\n问题：{question}\\n\\n回答（请在末尾标注引用编号）：\"\r\n\r\n# 验证模板\r\npython scripts/prompt_manager.py --show\r\n```\n\nFile v1.6.0:references/faq.md\n\n# 常见问题 (FAQ) — local-rag-builder\r\n\r\nQ: 为什么 Python 3.12 无法安装 chromadb？\r\nA: chromadb 的 Windows 预编译轮子最高支持到 Python 3.11。建议使用 conda 创建 3.11 虚拟环境。\r\n\r\nQ: 模型下载失败怎么办？\r\nA: 本工具内置 4 个下载源（ModelScope、HuggingFace 镜像、官方源、LLM 搜索），每个源会自动重试 3 次。如果全部失败，可以尝试：\r\n1. 配置环境变量 `HF_ENDPOINT` 为 `https://hf-mirror.com` 后重试\r\n2. 使用 `--interactive` 模式选择其他源\r\n3. 手动下载后使用 `--check` 验证\r\n\r\nQ: 多个知识库如何切换？\r\nA: 在 CLI 中使用 `/kb use ` 命令，或在配置文件的 `kb.active_kb` 字段指定。\r\n\r\nQ: Prompt 模板如何持久化？\r\nA: Prompt 模板保存在 `data/prompts/custom_prompt_template.txt`，程序重启后自动加载。使用 `/prompt set` 或 `--set` 命令配置后即持久化。\r\n\r\nQ: 如何重置所有配置恢复到初始状态？\r\nA: 运行 `python -c \"from config import reset_config; reset_config()\"` 或从 Web 界面点击\"重置配置\"按钮。这会清除 `data/config/rag_config.json` 并恢复默认值，同时重置 Prompt 模板。注意：重置不会删除知识库数据和已下载的嵌入模型。\r\n\r\nQ: 本技能和本地 LLM（如 LM Studio）是什么关系？\r\nA: 本技能本身可以扮演 LLM 角色，但如果你有本地运行的 LM Studio / Ollama 等服务，也可以通过配置 LLM 地址接入。技能自动适配两种模式。\r\n\r\nQ: 向量的相似度阈值如何配置？\r\nA: 在检索配置中配置 `score_threshold`（0-1 之间的浮点数），设为 `null` 则不启用阈值过滤。\r\n\r\nQ: Windows 上模型路径名变形如何处理？\r\nA: ModelScope 下载的模型名中 `.` 可能变为 `___`（如 `bge-small-zh-v1___5`）。本工具会自动检测并修正路径，无需手动处理。\n\nFile v1.6.0:references/guide.md\n\n# 使用指南 — local-rag-builder\r\n\r\n本指南提供 local-rag-builder 的完整使用教程，从环境搭建到高级配置。\r\n\r\n---\r\n\r\n## 目录\r\n\r\n1. [快速入门](#快速入门)\r\n2. [环境检测与安装](#环境检测与安装)\r\n3. [嵌入模型下载与管理](#嵌入模型下载与管理)\r\n4. [文本切分配置](#文本切分配置)\r\n5. [知识库管理](#知识库管理)\r\n6. [Prompt 自定义](#prompt-自定义)\r\n7. [Web 界面配置](#web-界面配置)\r\n8. [两种运行模式](#两种运行模式)\r\n9. [技能模式：智能体接口](#技能模式智能体接口)\r\n10. [独立模式：外部 LLM 接入](#独立模式外部-llm-接入)\r\n11. [故障排除](#故障排除)\r\n\r\n---\r\n\r\n## 快速入门\r\n\r\n```bash\r\n# 1. 进入技能目录\r\ncd ~/.workbuddy/skills/local-rag-builder\r\n\r\n# 2. 检查环境\r\npython scripts/rag_env_setup.py\r\n\r\n# 3. 下载嵌入模型（建议选 1: BGE-small-zh）\r\npython scripts/embedding_model_manager.py --interactive\r\n\r\n# 4. 启动 Web 配置界面\r\npython scripts/rag_web_ui.py\r\n\r\n# 5a. [技能模式] 纯检索（供智能体调用）\r\npython scripts/rag_skill.py --query \"问题\" --json\r\n\r\n# 5b. [独立模式] 检索 + LLM 全链路（需外部 LLM 服务）\r\npython scripts/rag_standalone.py\r\n```\r\n\r\n---\r\n\r\n## 环境检测与安装\r\n\r\n### 检测内容\r\n\r\n`rag_env_setup.py` 自动检测以下内容：\r\n\r\n- Python 版本（建议 3.8-3.11）\r\n- pip 可用性\r\n- 必需包安装状态（langchain, chromadb, sentence-transformers 等 9 个）\r\n- 可选包安装状态（unstructured, pdfplumber 等）\r\n- CUDA/GPU 可用性\r\n\r\n### 命令行用法\r\n\r\n```bash\r\n# 仅检测（不自动修复）\r\npython scripts/rag_env_setup.py --check-only\r\n\r\n# 检测并自动安装缺失的必需包\r\npython scripts/rag_env_setup.py --auto-install\r\n\r\n# 安装指定可选包\r\npython scripts/rag_env_setup.py --install-optional unstructured pdfplumber\r\n\r\n# 在指定路径创建虚拟环境\r\npython scripts/rag_env_setup.py --create-venv ./rag_env\r\n\r\n# JSON 格式输出（供智能体调用）\r\npython scripts/rag_env_setup.py --json\r\n```\r\n\r\n### 兼容性说明\r\n\r\n| Python 版本 | 状态 | 说明 |\r\n|------------|------|------|\r\n| 3.8 - 3.11 | ✅ 推荐 | chromadb 官方支持 |\r\n| 3.12+ | ⚠️ 实验性 | chromadb 可能有兼容问题 |\r\n| < 3.8 | ❌ 不支持 | 请升级 Python |\r\n\r\n---\r\n\r\n## 嵌入模型下载与管理\r\n\r\n### 交互式下载\r\n\r\n```bash\r\npython scripts/embedding_model_manager.py --interactive\r\n```\r\n\r\n会显示推荐模型列表，选择即可自动下载。\r\n\r\n### 直接指定模型\r\n\r\n```bash\r\npython scripts/embedding_model_manager.py --download BAAI/bge-small-zh-v1.5\r\n```\r\n\r\n### 多源重试机制\r\n\r\n下载优先级：ModelScope → HuggingFace 镜像 → HuggingFace 官方 → LLM 搜索\r\n\r\n每个源最多重试 3 次，全部失败后会报错并提示换源。\r\n\r\n### 完整性校验\r\n\r\n下载完成后自动执行：\r\n1. 检查目录是否存在模型文件（.bin, .safetensors 等）\r\n2. 检查 config.json 是否存在\r\n3. 计算总文件大小\r\n4. 修正路径名（如 `bge-small-zh-v1___5`）\r\n\r\n### 路径修正说明\r\n\r\nModelScope 在 Windows 上下载的模型路径名可能变形：\r\n- 原始名: `bge-small-zh-v1.5`\r\n- 实际名: `bge-small-zh-v1___5`\r\n\r\n本工具会自动查找并修正路径，无需手动处理。\r\n\r\n---\r\n\r\n## 文本切分配置\r\n\r\n### 6 种策略速查\r\n\r\n| 策略 | CLI 参数 | 适用场景 |\r\n|------|---------|---------|\r\n| 递归切分 | `recursive` | 通用兜底，适应性最强 |\r\n| 固定窗口 | `fixed` | 长度均匀的清洗文本 |\r\n| 层级/标题切 | `headers` | Markdown 结构化文档 |\r\n| 按句切分 | `sentence` | 证据抽取、短句文档 |\r\n| 语义切分 | `semantic` | 长叙述性文本 |\r\n| 代码块保护切 | `mermaid` | 含 mermaid 图表的文档 |\r\n\r\n### 组合切分\r\n\r\n支持主策略 + 二次策略组合：\r\n\r\n```bash\r\npython scripts/text_splitter.py --input doc.md --strategy headers --secondary recursive\r\n```\r\n\r\n### 参数调整\r\n\r\n```bash\r\n# 调整块大小和重叠\r\npython scripts/text_splitter.py --input doc.md --strategy recursive --chunk-size 300 --overlap 30\r\n\r\n# 列出所有可用策略\r\npython scripts/text_splitter.py --list-strategies\r\n\r\n# JSON 格式输出\r\npython scripts/text_splitter.py --input doc.md --strategy recursive --json\r\n```\r\n\r\n### 策略选择指南\r\n\r\n| 场景 | 推荐策略 | 原因 |\r\n|------|---------|------|\r\n| 文档有明确标题结构 | 层级切 | 保留结构元数据 |\r\n| 长度均匀、清洗干净 | 固定窗口 | 最快最简单 |\r\n| 不确定文档格式 | 递归切 | 安全兜底 |\r\n| 短句/证据抽取 | 按句切 | 精准定位 |\r\n| 长叙述性文本 | 语义切 | 主题完整 |\r\n| 含 mermaid 块 | 代码块保护切 | 防止代码块被切断 |\r\n\r\n---\r\n\r\n## 知识库管理\r\n\r\n### 基础操作\r\n\r\n```bash\r\n# 列出所有知识库\r\npython scripts/knowledge_base_manager.py --list\r\n\r\n# 创建知识库\r\npython scripts/knowledge_base_manager.py --create art --desc \"艺术类资料\"\r\n\r\n# 删除知识库\r\npython scripts/knowledge_base_manager.py --delete art\r\n\r\n# 查看统计\r\npython scripts/knowledge_base_manager.py --stats\r\n```\r\n\r\n### 自动分类规则\r\n\r\n配置关键词规则，LLM 可自动将内容归类到指定知识库：\r\n\r\n```bash\r\n# 配置规则：包含\"艺术\"\"美术\"\"绘画\"的内容归入 art 库\r\npython scripts/knowledge_base_manager.py --set-rule art \"艺术,美术,绘画,雕塑\"\r\n\r\n# 对一段文本自动分类\r\npython scripts/knowledge_base_manager.py --classify \"这幅画是梵高的代表作\"\r\n# 输出: 分类结果: art\r\n```\r\n\r\n### 知识库配置文件 (`data/kb/auto_classify_rules.json`)\r\n\r\n```json\r\n{\r\n \"art\": {\r\n \"keywords\": [\"艺术\", \"美术\", \"绘画\", \"雕塑\"],\r\n \"description\": \"艺术类资料\"\r\n },\r\n \"politics\": {\r\n \"keywords\": [\"政治\", \"政策\", \"政府\", \"选举\"],\r\n \"description\": \"政治类资料\"\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## Prompt 自定义\r\n\r\n### CLI 操作\r\n\r\n```bash\r\n# 显示当前模板\r\npython scripts/prompt_manager.py --show\r\n\r\n# 配置模板\r\npython scripts/prompt_manager.py --set \"请根据以下资料回答：\\n{context}\\n\\n问题：{question}\"\r\n\r\n# 从文件加载\r\npython scripts/prompt_manager.py --set-file my_prompt.txt\r\n\r\n# 重置为默认\r\npython scripts/prompt_manager.py --reset\r\n\r\n# 验证模板占位符\r\npython scripts/prompt_manager.py --validate custom_prompt_template.txt\r\n```\r\n\r\n### 模板变量\r\n\r\n| 占位符 | 说明 | 必需 |\r\n|--------|------|------|\r\n| `{context}` | 检索到的相关文本块 | ✅ |\r\n| `{question}` | 用户提问 | ✅ |\r\n\r\n---\r\n\r\n## Web 界面配置\r\n\r\n```bash\r\n# 启动 Web 配置面板\r\npython scripts/rag_web_ui.py\r\n\r\n# 指定端口\r\npython scripts/rag_web_ui.py --port 8888\r\n\r\n# 仅生成 HTML 文件（不启动服务器）\r\npython scripts/rag_web_ui.py --gen-html --output ~/Desktop/rag_settings.html\r\n```\r\n\r\nWeb 面板支持：\r\n- 嵌入模型选择与设备切换\r\n- 切分策略与参数调整\r\n- 检索参数（K 值、阈值）\r\n- LLM 地址与参数\r\n- Prompt 模板实时编辑\r\n- 知识库概览\r\n\r\n---\r\n\r\n## 两种运行模式\r\n\r\nlocal-rag-builder 分为**两个完全独立的入口**：\r\n\r\n| 模式 | 入口脚本 | 是否需要 LLM | 适用场景 |\r\n|:----:|:--------:|:------------:|:---------|\r\n| **技能模式** | `rag_skill.py` | **不需要** | 智能体（xxxx 等）调用，纯检索返回 context |\r\n| **独立模式** | `rag_standalone.py` | 需要（LM Studio / Ollama / vLLM） | 用户直接跑 Python，全链路问答 |\r\n\r\n> ⚠️ 两者不共享同一个运行进程。选择哪个入口，就决定了是否涉及 LLM 调用。\r\n\r\n---\r\n\r\n## 技能模式：智能体接口\r\n\r\n**文件**：`scripts/rag_skill.py`\r\n**设计原则**：零 LLM 依赖。不 import `langchain_community.llms`，不做任何 HTTP 请求到外部服务。\r\n\r\n### 核心输出格式\r\n\r\n```bash\r\npython scripts/rag_skill.py --query \"问题\" --kb default --json\r\n```\r\n\r\n输出 JSON 包含完整的 prompt（已填充占位符），智能体直接使用：\r\n\r\n```json\r\n{\r\n \"question\": \"问题\",\r\n \"kb\": \"default\",\r\n \"context\": \"[片段 1] (来源: doc.md)\\n...\",\r\n \"source_count\": 3,\r\n \"source_docs\": [\r\n {\"content\": \"...\", \"metadata\": {\"source\": \"doc.md\"}, \"length\": 500}\r\n ],\r\n \"prompt\": \"基于以下资料回答问题。\\n\\n资料：\\n...\\n\\n问题：...\\n\\n回答：\",\r\n \"prompt_template\": \"基于以下资料回答问题。\\n\\n资料：\\n{context}\\n\\n问题：{question}\\n\\n回答：\",\r\n \"has_context\": true\r\n}\r\n```\r\n\r\n关键字段：\r\n- `context` — 检索到的文本块，已按片段编号\r\n- `prompt` — **已填充** `{context}` 和 `{question}` 的完整 prompt，智能体直接拿去用\r\n- `prompt_template` — 原始的 prompt 模板，智能体可了解格式\r\n- `has_context` — 是否找到相关内容\r\n\r\n### 支持的操作\r\n\r\n```bash\r\n# 检索\r\npython scripts/rag_skill.py --query \"问题\"\r\npython scripts/rag_skill.py --query \"问题\" --json\r\n\r\n# 导入文档\r\npython scripts/rag_skill.py --import-file doc.md\r\n\r\n# 列表知识库\r\npython scripts/rag_skill.py --kb-list\r\npython scripts/rag_skill.py --kb-list --json\r\n\r\n# 自定义 prompt 模板\r\npython scripts/rag_skill.py --query \"问题\" --template \"自定义模板 {context} {question}\"\r\n```\r\n\r\n### 智能体集成示例\r\n\r\n```python\r\nimport subprocess, json\r\n\r\nresult = subprocess.run(\r\n [\"python\", \"scripts/rag_skill.py\", \"--query\", \"问题\", \"--json\"],\r\n capture_output=True, text=True, cwd=\"/path/to/skill\"\r\n)\r\ndata = json.loads(result.stdout)\r\n\r\n# data[\"context\"] → 检索到的文本\r\n# data[\"prompt\"] → 已填充的完整 prompt\r\n# 智能体根据 data[\"prompt\"] 或 data[\"context\"] 自行组织回答\r\n```\r\n\r\n---\r\n\r\n## 独立模式：外部 LLM 接入\r\n\r\n**文件**：`scripts/rag_standalone.py`\r\n**设计原则**：检索 + LLM 全链路。需要用户自行部署外部 LLM 服务。\r\n\r\n### 交互式 CLI\r\n\r\n```bash\r\npython scripts/rag_standalone.py\r\n```\r\n\r\n支持的交互命令：`/help`, `/prompt`, `/kb`, `/config`, `/verify-llm`, `/llm-help`, `/exit`\r\n\r\n### 外部 LLM 服务配置\r\n\r\n启动前，用户需自行选择一个平台和模型。配置在 `data/config/rag_config.json` 的 `llm` section：\r\n\r\n```json\r\n{\r\n \"llm\": {\r\n \"base_url\": \"http://localhost:1234/v1\",\r\n \"api_key\": \"not-needed\",\r\n \"temperature\": 0.1,\r\n \"max_tokens\": 512\r\n }\r\n}\r\n```\r\n\r\n三种方案对比（详见 `references/llm-setup.md`）：\r\n\r\n| 方案 | 地址 | 适合 |\r\n|:----|:----|:----|\r\n| LM Studio | http://localhost:1234/v1 | 新手，图形界面 |\r\n| Ollama | http://localhost:11434/v1 | 开发者，命令行 |\r\n| vLLM | http://localhost:8000/v1 | 生产环境，高并发 |\r\n\r\n```bash\r\n# 查看完整接入指南\r\npython scripts/rag_standalone.py --llm-help\r\n\r\n# 验证 LLM 连接\r\npython scripts/rag_standalone.py --verify-llm\r\n\r\n# 单次问答\r\npython scripts/rag_standalone.py --query \"什么是 RAG？\"\r\npython scripts/rag_standalone.py --query \"什么是 RAG？\" --json\r\n```\r\n> - **集成模式**（默认）：纯检索，不调用 LLM。智能体根据检索到的 context 自行回答。\r\n> - **独立模式**：检索 + LLM 全链路。需要外部 LLM 服务，用户自行选择平台和模型。\r\n\r\n以下推荐三种外部 LLM 服务方案，**用户根据自身情况选择**（本 skill 不做决定，只提供接入方法）。\r\n\r\n### LM Studio（图形界面，适合新手）\r\n\r\n1. 下载安装 [LM Studio](https://lmstudio.ai)\r\n2. 左侧 Search 搜索模型（如 Qwen2.5-7B-Instruct-GGUF、DeepSeek-R1-GGUF 等）\r\n3. 选择一个量化版本（如 Q4_K_M），点击 Download\r\n4. 左侧 Local Inference Server，选择已下载的模型\r\n5. 点击 Start Server，默认地址 http://localhost:1234/v1\r\n\r\n### Ollama（命令行，适合开发者）\r\n\r\n```bash\r\n# 下载安装 https://ollama.com\r\nollama pull qwen2.5:7b # 通义千问\r\nollama pull deepseek-r1:7b # DeepSeek\r\nollama pull gemma3:7b # Google Gemma\r\nollama run qwen2.5:7b # 运行（自动启动 API）\r\n\r\n# 默认 API 地址: http://localhost:11434/v1\r\n# 在 Web 面板的 LLM 配置中对应更新 base_url\r\n```\r\n\r\n### vLLM（生产环境高性能）\r\n\r\n```bash\r\npip install vllm\r\npython -m vllm.entrypoints.openai.api_server \\\r\n --model Qwen/Qwen2.5-7B-Instruct \\\r\n --port 8000\r\n\r\n# 地址: http://localhost:8000/v1\r\n```\r\n\r\n```bash\r\npython scripts/config.py # 直接更新 config 文件\r\n```\r\n\r\n默认地址: `http://localhost:1234/v1`\r\n\r\n### LM Studio 配置\r\n\r\n1. 下载安装 [LM Studio](https://lmstudio.ai)\r\n2. 搜索并下载模型（如 Qwen2.5-7B-Instruct-GGUF）\r\n3. 在 Local Inference Server 界面加载模型\r\n4. 点击 Start Server\r\n5. 验证: 访问 `http://localhost:1234/v1/models`\r\n\r\n### 验证 LLM 连接\r\n\r\n```bash\r\n# CLI 验证\r\npython scripts/rag_standalone.py --verify-llm\r\n\r\n# 或进入交互式 CLI 后输入 /verify-llm\r\n\r\n# Web 面板验证\r\n# 打开配置页，点击 \"验证连接\" 按钮\r\n```\r\n\r\n---\r\n\r\n## 故障排除\r\n\r\n| 问题 | 原因 | 解决 |\r\n|------|------|------|\r\n| chromadb 安装失败 | Python 版本过高 | 使用 Python 3.8-3.11 |\r\n| 模型下载超时 | 网络问题 | 使用 --interactive 选择其他源 |\r\n| 模型路径找不到 | 路径名变形 | 运行 verify 自动修正 |\r\n| LLM 连接失败 | LM Studio 未启动 | 启动 LM Studio Server |\r\n| 回答含 `` 标签 | 模型强制输出推理过程 | 已自动清理，无需处理 |\r\n| 向量库导入失败 | 缺失 langchain-chroma | 运行 --auto-install |\r\n| Web 界面端口被占用 | 端口冲突 | 指定其他端口 |\n\nFile v1.6.0:references/llm-setup.md\n\n# 外部 LLM 服务接入参考\r\n\r\n> 本文件适用于 **独立模式**（`rag_standalone.py`）。技能模式（`rag_skill.py`）不需要 LLM。\r\n\r\n## 配置方式\r\n\r\n所有 LLM 连接参数通过 `data/config/rag_config.json` 的 `llm` section 控制：\r\n\r\n```json\r\n{\r\n \"llm\": {\r\n \"base_url\": \"http://localhost:1234/v1\",\r\n \"api_key\": \"not-needed\",\r\n \"temperature\": 0.1,\r\n \"max_tokens\": 512,\r\n \"model_name\": \"\"\r\n }\r\n}\r\n```\r\n\r\n更新方式：\r\n- **Web 面板**：`python scripts/rag_web_ui.py` → LLM 配置卡片\r\n- **CLI**：`/config set llm.base_url http://localhost:11434/v1`\r\n\r\n---\r\n\r\n## 方案一：LM Studio（图形界面，适合新手）\r\n\r\n| 项目 | 说明 |\r\n|:----|:-----|\r\n| 下载 | https://lmstudio.ai |\r\n| 模型搜索 | 左侧 Search → 搜索 Qwen2.5 / DeepSeek-R1 / Gemma 等 GGUF 格式 |\r\n| 模型下载 | 选择一个量化版本（如 Q4_K_M），点击 Download |\r\n| 启动服务 | Local Inference Server → 选择模型 → Start Server |\r\n| API 地址 | `http://localhost:1234/v1` |\r\n| 验证 | 浏览器访问 `http://localhost:1234/v1/models` 应返回模型列表 |\r\n| Python 配置 | `base_url = \"http://localhost:1234/v1\"` |\r\n\r\n**典型流程：**\r\n```\r\n1. 下载 LM Studio 并安装\r\n2. 搜索 qwen2.5-7b-instruct-gguf，选择 Q4_K_M 量化版下载\r\n3. 切换到 Local Inference Server 标签页\r\n4. 下拉框选择刚下载的模型\r\n5. 点击 Start Server\r\n6. 保持 LM Studio 运行，回到终端\r\n7. python scripts/rag_standalone.py ← 启动问答\r\n```\r\n\r\n---\r\n\r\n## 方案二：Ollama（命令行，适合开发者）\r\n\r\n| 项目 | 说明 |\r\n|:----|:-----|\r\n| 下载 | https://ollama.com |\r\n| 模型市场 | https://ollama.com/library |\r\n| 常用模型 | `qwen2.5:7b`（通义千问）、`deepseek-r1:7b`、`gemma3:7b`、`llama3.1:8b` |\r\n| 启动服务 | `ollama serve`（自动后台运行） |\r\n| API 地址 | `http://localhost:11434/v1` |\r\n| 验证 | `curl http://localhost:11434/v1/models` |\r\n| Python 配置 | `base_url = \"http://localhost:11434/v1\"` |\r\n\r\n**典型流程：**\r\n```bash\r\n# 安装 Ollama 后\r\nollama pull qwen2.5:7b # 拉取模型（首次需下载）\r\nollama serve # 启动 API 服务（后台常驻）\r\n\r\n# 另一个终端\r\npython scripts/rag_standalone.py\r\n```\r\n\r\n**多模型管理：**\r\n```bash\r\nollama list # 列出已下载的模型\r\nollama pull deepseek-r1:7b # 拉取另一个模型\r\nollama run qwen2.5:7b # 直接交互运行\r\n```\r\n\r\n---\r\n\r\n## 方案三：vLLM（生产环境高性能推理）\r\n\r\n| 项目 | 说明 |\r\n|:----|:-----|\r\n| 安装 | `pip install vllm` |\r\n| GPU 要求 | NVIDIA GPU，建议 ≥8GB 显存 |\r\n| 常用模型 | `Qwen/Qwen2.5-7B-Instruct`、`deepseek-ai/DeepSeek-R1-Distill-Qwen-7B` |\r\n| API 地址 | `http://localhost:8000/v1`（可自定义端口） |\r\n| Python 配置 | `base_url = \"http://localhost:8000/v1\"` |\r\n\r\n**典型流程：**\r\n```bash\r\npip install vllm\r\n\r\n# 单卡启动\r\npython -m vllm.entrypoints.openai.api_server \\\r\n --model Qwen/Qwen2.5-7B-Instruct \\\r\n --port 8000\r\n\r\n# 另一个终端\r\npython scripts/rag_standalone.py\r\n```\r\n\r\n**vLLM 参数调优：**\r\n```bash\r\n# 指定 GPU 显存使用比例\r\n--gpu-memory-utilization 0.85\r\n\r\n# 使用 AWQ 量化模型（降低显存需求）\r\n--quantization awq\r\n\r\n# 最大并发数\r\n--max-num-seqs 32\r\n```\r\n\r\n---\r\n\r\n## 参数参考\r\n\r\n| 参数 | LM Studio 默认 | Ollama 默认 | vLLM 默认 |\r\n|:----|:--------------:|:-----------:|:---------:|\r\n| `base_url` | http://localhost:1234/v1 | http://localhost:11434/v1 | http://localhost:8000/v1 |\r\n| `api_key` | not-needed | not-needed | not-needed |\r\n| `temperature` | 0.1 | 0.1 | 0.1 |\r\n| `max_tokens` | 512 | 512 | 512 |\r\n| 推荐模型 | Qwen2.5-7B-GGUF | qwen2.5:7b | Qwen2.5-7B-Instruct |\r\n\r\n---\r\n\r\n## 故障排查\r\n\r\n| 现象 | 原因 | 解决 |\r\n|:----|:-----|:-----|\r\n| LLM 连接失败 | 服务未启动 | 启动 LM Studio / Ollama / vLLM 服务 |\r\n| 连接失败 | 端口不对 | 确认实际端口，更新 base_url |\r\n| 连接失败 | 地址不对 | 本地服务用 localhost，远程用 IP |\r\n| 回答乱码 | 模型不支持中文 | 换成 Qwen / DeepSeek 等中文模型 |\r\n| 回答太短 | max_tokens 太小 | 调大 max_tokens（如 2048） |\r\n| 显存不足 | 模型太大 | 换更小的量化版或换 3B 模型 |\n\nFile v1.6.0:references/permissions.md\n\n# 基于skill-standardization渐进式披露规范的权限说明\r\n\r\n## 风险等级\r\n\r\n（请填写：LOW / MEDIUM / HIGH / CRITICAL）\r\n\r\n## 高权限操作说明\r\n\r\n（如含敏感信息访问、关键位置写入，请在此说明：）\r\n- 操作：\r\n- 必要性：\r\n- 如何降低风险：\r\n\r\n---\r\n\r\n# 权限说明 — local-rag-builder\r\n\r\n## 权限概述\r\n\r\n本技能需要以下系统权限以完成 RAG 系统搭建和管理。\r\n\r\n| 权限类别 | 权重 | 涉及脚本 | 说明 |\r\n|---------|------|---------|------|\r\n| 文件系统写入 | 30% | 全部 | 创建虚拟环境、写入配置、保存模型、创建向量库 |\r\n| 网络访问 | 20% | rag_env_setup.py, embedding_model_manager.py | 下载 pip 包、下载嵌入模型 |\r\n| 文件删除 | 10% | embedding_model_manager.py, knowledge_base_manager.py | 删除模型、删除知识库 |\r\n| 子进程调用 | 20% | rag_env_setup.py, embedding_model_manager.py | 执行 pip install、运行模型下载脚本 |\r\n| 敏感路径访问 | 20% | 全部 | 读取/写入 skills/ 下的技能数据目录 |\r\n\r\n## 详细权限说明\r\n\r\n### 文件系统写入（权重 30%）\r\n\r\n**涉及操作**：\r\n- 创建 `.standardization/local-rag-builder/data/` 下的子目录\r\n- 写入配置文件 `rag_config.json`\r\n- 保存嵌入模型文件\r\n- 持久化向量数据库文件（chroma）\r\n- 保存 Prompt 模板文件\r\n\r\n**风险等级**：低 — 所有写入均在 skill 的数据目录内\r\n\r\n### 网络访问（权重 20%）\r\n\r\n**涉及操作**：\r\n- pip install 从 PyPI 下载包\r\n- 从 ModelScope / HuggingFace 下载嵌入模型\r\n- 连接本地/远程 LLM API\r\n\r\n**风险等级**：低 — 仅连接预定义源或用户指定的地址\r\n\r\n### 文件删除（权重 10%）\r\n\r\n**涉及操作**：\r\n- 删除下载失败的模型目录\r\n- 删除用户指定的知识库\r\n- 重置配置时清空配置\r\n\r\n**风险等级**：低 — 所有删除操作需用户显式确认\r\n\r\n### 子进程调用（权重 20%）\r\n\r\n**涉及操作**：\r\n- 调用 pip install 安装包\r\n- 创建 Python 虚拟环境\r\n- 执行模型下载脚本\r\n\r\n**风险等级**：低 — 仅执行标准的 Python 包管理操作\r\n\r\n### 敏感路径访问（权重 20%）\r\n\r\n**涉及操作**：\r\n- 读取 skills/.standardization/ 下的数据目录\r\n- 配置文件读写\r\n\r\n**风险等级**：低 — 仅访问技能自身的数据目录\r\n\r\n## 权限权重计算\r\n\r\n| 维度 | 权重 | 实际值 | 加权 |\r\n|------|------|--------|------|\r\n| 敏感信息访问 | 40% | 0% (不访问 credentials/token) | 0 |\r\n| 关键位置写入 | 30% | 30% | 0.09 |\r\n| 网络访问 | 20% | 20% | 0.04 |\r\n| 文件删除 | 10% | 10% | 0.01 |\r\n| **总计** | **100%** | | **0.14 (低风险)** |\r\n\r\n## 安全建议\r\n\r\n1. 首次运行建议在网络可信环境下执行 `--auto-install`\r\n2. 模型下载如遇网络问题，可手动下载后通过 `--check` 验证\r\n3. 知识库数据安全由本地文件系统保障，注意定期备份 `data/kb/` 目录\r\n\r\n---\r\n\r\n## 基于skill-function-test的测试报告\r\n\r\n> 生成时间: 2026-06-13\r\n\r\n### 测试概览\r\n\r\n| 测试项 | 结果 |\r\n|--------|------|\r\n| 场景测试 (S1-S3) | 10/11 PASS, 0 BLOCK |\r\n| 功能测试 (D1-D6) | 197/288 PASS, **0 BLOCK**, 91 WARN |\r\n| S4 执行忠实度 | 12/12 坚守 (100%) |\r\n\r\n**评估**: F-0 BLOCK = 0，无致命问题。91 条 WARN 主要为裸 print（CLI 工具设计选择）和外部依赖未安装。\r\n\r\n### 计时统计\r\n\r\n| 指标 | 耗时 |\r\n|------|------|\r\n| 总耗时 | 2750.582s |\r\n| 脚本执行 | 0.133s |\r\n| LLM 处理 | 2750.450s |\r\n| 目标技能调用 | 0.000s |\r\n\r\n**轮次统计**: 3 轮 | 均值 12.439s/轮 | 绝对差值 0.278s\n\nFile v1.6.0:skill-card.md\n\n## Description:\n\nBuilds and manages a local RAG workflow with environment setup, embedding model downloads, document splitting, vector knowledge bases, prompt templates, and optional Web UI configuration.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[ldxs001](https://clawhub.ai/user/ldxs001)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use this skill to set up local retrieval-augmented generation, import documents into local vector knowledge bases, retrieve context for an agent, or run a standalone local-LLM RAG loop.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The Web UI is unauthenticated and should not be exposed on a shared network.\n\nMitigation: Bind the Web UI to loopback, add authentication before broader exposure, and avoid running it where untrusted clients can reach it.\n\nRisk: Model download paths and custom model identifiers can pull code or model artifacts from external sources.\n\nMitigation: Use trusted model identifiers only, pin dependencies and model sources, and review downloaded artifacts before deployment.\n\nRisk: Standalone RAG mode can send retrieved context to a configured LLM endpoint.\n\nMitigation: Use only trusted local or remote LLM endpoints and treat indexed documents and retrieved context as sensitive data.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/ldxs001/skills/local-rag-builder)\n- [Architecture](references/architecture.md)\n- [Usage guide](references/guide.md)\n- [External LLM setup](references/llm-setup.md)\n- [Permissions and test report](references/permissions.md)\n- [Examples](references/examples.md)\n- [FAQ](references/faq.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance and command examples, with JSON available from CLI retrieval and management commands.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Can return retrieved context, source document metadata, filled prompts, knowledge-base status, environment reports, and configuration updates.]\n\n## Skill Version(s):\n\n1.6.0 (source: server release metadata; artifact frontmatter reports 1.0.5)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.4.3: 32 files, 160028 bytes\n\nFiles: _meta.json (136b), references/antipatterns.md (955b), references/architecture.md (5439b), references/changelog.md (31191b), references/commands.md (1434b), references/custom-extensions.md (1040b), references/data-directory.md (791b), references/examples.md (3524b), references/faq.md (2998b), references/guide.md (13508b), references/LICENSE.md (1612b), references/llm-setup.md (4328b), references/permissions.md (2969b), references/setup-spec.md (8266b), references/test-report.md (46142b), scripts/config.py (3742b), scripts/embedding_model_manager.py (26824b), scripts/knowledge_base_manager.py (21377b), scripts/prompt_manager.py (3286b), scripts/rag_core.py (17608b), scripts/rag_env_setup.py (21285b), scripts/rag_settings.html (84472b), scripts/rag_setup_orchestrator.py (22139b), scripts/rag_skill.py (10915b), scripts/rag_standalone.py (15040b), scripts/rag_web_ui.py (120372b), scripts/reranker.py (12282b), scripts/router.py (16603b), scripts/text_splitter.py (28874b), scripts/utils.py (7856b), skill-card.md (2737b), SKILL.md (11680b)\n\nFile v1.4.3:SKILL.md\n\n---\nname: local-rag-builder\nslug: local-rag-builder\ndisplayName: local-rag-builder\nversion: 1.5.0\ndescription: 本地 RAG 系统搭建技能，支持环境检测修复、嵌入模型多源下载、5种切分策略 + GuardStack + 后处理 + 插件注册、多知识库管理 + 自动分类规则、可调 Prompt、Web 可视化配置 + 极客模式 + 模板管理\nauthor: wUwproject\nlicense: MIT\nsensitive_access: true\ncritical_write: false\ntrigger: ['搭建 RAG 系统', '本地知识库', '嵌入模型下载', '文本切分', '向量检索', 'RAG 环境配置', '下载模型', '入库文档', '切分文档', '知识库管理']\ntrigger_negative: ['纯聊天', '简单问答']\ntags: ['rag', 'embedding', 'llm', 'python', 'vector-db', 'text-splitter', 'guard-stack', 'plugin']\ndata_dir: skills/.standardization/local-rag-builder/data/\nh1_position: true\nexternal_data_dir: true\npermission_weight: CRITICAL\nfaq_quality: improve_qa\nmeta_field_sync: true\ndata_dir_compliance: true\ncreate_permissions_md: true\n---\n# local-rag-builder（本地 RAG 搭建工具）\n\n一站式本地 RAG 系统搭建工具。支持环境自动检测修复、嵌入模型多源下载、5 种切分策略 + GuardStack 守卫栈 + 后处理子切 + 插件注册、多知识库管理与自动分类规则、可调 Prompt、Web 可视化配置。\n\n**两种运行模式：**\n- **🔌 集成模式（默认）** — 纯检索，不调用 LLM。智能体（xxxx 等）根据检索到的 context 自行回答。无需配置 LLM，无额外推理成本。\n- **🤖 独立模式** — 检索 + LLM 全链路。`rag_standalone.py` 直接调用外部 LLM（LM Studio / Ollama / vLLM）完成回答，不经过智能体。用户自行选择平台和模型。\n\n> **工作流说明（以下 xxxx 代指任意智能体）：**\n>\n> **集成模式：**\n> 1. 你把文档/链接给 xxxx → xxxx 调用 `rag_skill.py` 向量化入库\n> 2. 你提问 → xxxx 调用 `rag_skill.py --query \"...\"` 检索知识库\n> 3. xxxx 根据检索到的 context 组织回答\n>\n> **独立模式：**\n> 1. 你把文档/链接给 xxxx → xxxx 调用 `rag_standalone.py --import-file ` 入库\n> 2. 你提问 → xxxx 调用 `rag_standalone.py --query \"...\"` \n> 3. `rag_standalone.py` 自行检索知识库 → 调用本地 LLM → 输出回答\n> 4. xxxx 仅透传结果，不参与推理\n\n## 触发条件\n\n**正向触发：**\n- **搭建 RAG** — \"帮我搭一个本地 RAG 系统\"\n- **环境检测** — \"检查我的 Python 环境能否跑 RAG\"\n- **下载模型** — \"下载一个嵌入模型\" / \"换个模型源重试\"\n- **切分文档** — \"对这个 Markdown 文件做层级切分\"\n- **向量检索** — \"把这份资料入库，搜索相似内容\"\n- **知识库管理** — \"创建一个知识库\" / \"把这类资料存入指定库\"\n- **调整参数** — \"更新切分参数\" / \"改 Prompt 模板\"\n- **智能体集成** — \"根据这份资料回答：xxx\"（智能体调用 skill 的集成模式）\n\n**否定条件：**\n- **不触发**：纯 LLM 聊天不需要检索、简单问答不需要外部资料\n\n## 核心能力\n\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\n\n| # | 能力 | 说明 |\n| --- |------| ------ |\n| 1 | **环境自动检测修复** | 检测 Python 版本（需 3.11+）、缺失包，自动创建虚拟环境安装 |\n| 2 | **嵌入模型管理** | 多源下载（ModelScope / HuggingFace 镜像 / 官方 / 直连），自动重试，完整性校验，路径修正 |\n| 3 | **5 种切分策略 + GuardStack + 后处理** | 固定窗口、递归切、层级/标题切、按句切、语义切；守卫栈（mermaid/代码块/公式/表格/HTML 保护）；后处理子切（递归/固定/语义，metadata 白名单继承） |\n| 4 | **多知识库管理 + 路由层** | 支持多个向量知识库并行，LLM 自动分类入库或用户指定；路由层（关键词语义 rerank → 硬编码关键词 → 语义签名回退 → 全库广播兜底）。入库时路由开=关键词+语义hybrid加权投票，关=纯关键词 |\n| 5 | **Rerank 重排序层** | 可选精排（cross-encoder 模型 / 规则 / 混合），默认关闭。开启后对检索结果重排序，提升 top-K 精度 |\n| 6 | **可调 Prompt** | 模板持久化，支持自定义占位符（`{context}` `{question}`），运行时编辑 |\n| 7 | **Web 可视化界面** | 内嵌 HTML 配置面板：输入源开关、GuardStack 守卫配置、5 策略动态表单 + 后处理配置、Router/Rerank 参数、极客模式 JSON 编辑器 + 配置模板管理、知识库自动分类规则编辑器 |\n| 8 | **扫描 PDF 自动 OCR** | `import_documents_to_kb()` 自动检测扫描版 PDF（无文本时回退 EasyOCR）；新增中文乱码检测（中文文件名 + CJK 字符占比 < 10% → 自动 OCR），无需手动区分 |\n| 9 | **KB 签名自动归纳** | 入库时自动生成知识库内容摘要（词频+代表性片段），Web UI 可查看 |\n| 10 | **Markdown 标题预处理** | 入库前对 PDF/文档进行正则标题匹配，自动注入 `#`/`##` Markdown 标题标记并强制切换为 headers 策略。支持 h1~h4 自定义正则，Web UI 面板可开关+配置预设，极客模式支持精确编辑 |\n\n### 渐进式文件索引\n\n| 文件名 | 分类 | 包含内容 | 审计关联 |\n| -------- |------| ---------- |----------|\n| `references/antipatterns.md` | 规范指南 | skill 编写中的常见反模式。包含：错误做法示例、正确做法示例、避坑指引。 | R-18 |\n| `references/architecture.md` | 架构设计 | local-rag-builder 整体架构。包含：模块关系、数据流、核心设计决策。 | 无 |\n| `references/changelog.md` | 版本管理 | 版本更新日志。包含：版本号、更新类型、修复项、升级说明。 | R-24 |\n| `references/examples.md` | 使用示例 | 各场景完整执行示例。包含：CLI 命令、执行过程、输出结果。 | R-25 C-17 |\n| `references/faq.md` | 常见问题 | 常见疑问与解答。包含：问题分类、原因分析、解决方案。 | R-19, R-25 C-19 |\n| `references/guide.md` | 使用指南 | 三种执行模式操作教程。包含：audit/create/refactor 流程、参数说明、注意事项。 | 无 |\n| `references/llm-setup.md` | 参考文档 | > 本文件适用于 **独立模式**（`rag_standalone.py`）。技能模式（`rag_skill.py`）不需要 LLM。 | 无 |\n| `references/permissions.md` | 权限与测试 | 权限扫描说明与测试结论。包含：风险等级、高权限操作说明、测试概览、计时统计。 | R-15, R-16 |\n| `references/LICENSE.md` | 许可协议 | MIT 开源许可证声明。 | R-26 |\n| `references/setup-spec.md` | 规范文档 | RAG 搭建完整参数规范（32 参数 + 6 阶段流水线）。 | 无 |\n| `references/commands.md` | 命令参考 | 脚本命令速查表。包含：脚本名称、作用、核心参数。 | 无 |\n| `references/data-directory.md` | 数据目录 | 运行时数据目录结构说明。包含：各子目录用途。 | 无 |\n| `references/custom-extensions.md` | 扩展指南 | 插件注册指南与代码示例。包含：自定义切分策略、自定义守卫。 | 无 |\n## 快速开始\n\n```bash\n# 1. 进入技能目录\ncd ~/.workbuddy/skills/local-rag-builder\n\n# 2. 运行环境检测（自动修复，建议首次用国内镜像）\npython scripts/rag_env_setup.py --auto-install --mirror aliyun # 国内用户推荐\n# python scripts/rag_env_setup.py --auto-install # 海外用户/默认\n# python scripts/rag_env_setup.py --check-only # 仅检测不安装\n# python scripts/rag_env_setup.py --cleanup-locks # 清理 pip 锁文件\n\n# 3. 下载嵌入模型（交互式选择）\npython scripts/embedding_model_manager.py --interactive\n\n# 4. 启动 Web 配置界面\npython scripts/rag_web_ui.py\n\n# 5a. [技能模式] 纯检索，供智能体调用（无需 LLM）\npython scripts/rag_skill.py --query \"问题\"\npython scripts/rag_skill.py --query \"问题\" --json # JSON 输出\n\n# 5b. [独立模式] 检索 + LLM 全链路，需外部 LLM 服务\npython scripts/rag_standalone.py # 交互式 CLI\npython scripts/rag_standalone.py --query \"问题\" # 单次问答\npython scripts/rag_standalone.py --query \"问题\" --json # JSON 输出\npython scripts/rag_standalone.py --llm-help # 查看 LLM 接入指南\n```\n\n## 工作流程\n\n1. **环境准备** — `rag_env_setup.py` 检测并安装依赖\n - 输入：当前 Python 环境 + 系统包管理器\n - 输出：完整的依赖环境（chromadb / sentence-transformers / langchain 等）\n2. **模型下载** — `embedding_model_manager.py` 下载/校验嵌入模型\n - 输入：模型名称（如 BAAI/bge-small-zh-v1.5）\n - 输出：本地缓存的嵌入模型（支持 ModelScope / HuggingFace 镜像多源重试）\n3. **标题预处理配置（可选）** — Web UI 或极客模式配置 `preprocess.h1_patterns` / `h2_patterns` 正则规则，匹配文档中的章节标题行。启用后自动注入 Markdown 标题标记并强制使用 headers 切分策略，适用于结构化文档\n - 输入：h1~h4 正则模式\n - 输出：预处理后的 Markdown 标题文本\n4. **文档入库** — `text_splitter.py` 切分文档 → `knowledge_base_manager.py` 向量化入库（所有文件类型均适用 SM3 哈希去重 + upsert 覆盖写入）\n - 输入：原始文档（txt / md / py / json / yaml / pdf 等）\n - 输出：向量化存储到指定知识库（Chroma DB，相同内容 SM3 哈希自动去重）\n5. **模式选择** — 根据用途选择入口\n - **技能模式** → `rag_skill.py`（纯检索，供智能体调用，无需 LLM）\n - **独立模式** → `rag_standalone.py`（检索 + LLM 全链路，需外部 LLM）\n6. **配置调整** — `rag_web_ui.py` 提供可视化面板\n\n→ 详见 references/commands.md（命令速查表）\n\n→ 详见 references/data-directory.md（数据目录结构说明）\n\n→ 详见 references/custom-extensions.md（插件注册指南）\n\n## 约束\n\n1. **Python 版本**：建议 3.11+（已测试 3.11/3.14）\n2. **嵌入模型路径**：下载后自动修正真实路径（如 `bge-small-zh-v1___5`）\n3. **知识库隔离**：不同资料自动/手动归入不同库\n4. **重置**：删除 `data/` 下对应子目录即可重置相关数据\n\n## 限制\n\n- **文件类型支持**：原生支持 txt / md / py / json / yaml 纯文本格式；可选扩展支持 PDF（langchain PyPDFLoader → 自动回退 EasyOCR）、图片 OCR（paddleocr→自动回退 easyocr）、HTML→MD 转换（html2text）— 影响：纯文本以外的格式需手动开启输入源开关 🔄 可扩展（输入源开关）\n- **知识库容量**：单个知识库建议 5 万条以内，超过需考虑分段策略优化 — 影响：大规模部署需规划 🟡 有替代方案（分段入库）\n- **模型范围**：仅支持 sentence-transformers/HuggingFace 格式的嵌入模型，不直接支持 OpenAI/Cohere API 格式 — 影响：API 方式无法直接对接 ✅ 已接受\n- **LLM 依赖**：独立模式需要外部 LLM 服务（LM Studio / Ollama / vLLM），技能模式不需要 — 影响：独立模式有额外部署成本 ✅ 已说明\n- **并发限制**：单进程运行，不支持多用户并发写入知识库 — 影响：不适合高并发生产环境 🟡 规划中\n- **切分参数范围**：`chunk_size` 50–5000（默认 500），`chunk_overlap` 0–1000（默认 50）；超出范围自动钳位 — 影响：极端参数影响检索精度 ✅ 已处理\n\nFile v1.4.3:_meta.json\n\n{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"local-rag-builder\",\n \"version\": \"1.4.3\",\n \"publishedAt\": 1783452517641\n}\n\nFile v1.4.3:references/antipatterns.md\n\n# 反模式 — local-rag-builder\r\n\r\n## 不要在 SKILL.md 正文写完整教程\r\n\r\n**错误做法**：在 SKILL.md 中展开所有脚本的详细用法。\r\n\r\n**正确做法**：SKILL.md 只写概要，详细教程拆分到 `references/guide.md`。本技能已遵循此规范。\r\n\r\n## 不要硬编码模型路径\r\n\r\n**错误做法**：\r\n```python\r\nmodel_path = \"D:/models/bge-small-zh-v1.5\"\r\n```\r\n\r\n**正确做法**：通过配置系统管理模型路径，支持 Web UI 和 CLI 动态切换。\r\n\r\n## 不要在所有场景都用同一种切分策略\r\n\r\n**错误做法**：对所有文档都用固定窗口切分。\r\n\r\n**正确做法**：根据文档类型选择策略（Markdown → 标题切，长文 → 语义切，通用 → 递归切）。\r\n\r\n## 不要忽略 Python 版本兼容性\r\n\r\n**错误做法**：在 Python 3.12+ 上直接安装 chromadb。\r\n\r\n**正确做法**：使用 `rag_env_setup.py` 检测版本，必要时创建 3.11 虚拟环境。\n\nFile v1.4.3:references/architecture.md\n\n# 架构设计 — local-rag-builder v1.3.0\n\n## 整体架构\n\n```\n┌─────────────────────────────────────────────────────┐\n│ CLI (rag_skill.py / rag_standalone.py) │\n│ Web UI (rag_web_ui.py) │\n├─────────────────────────────────────────────────────┤\n│ rag_core.py (RAG 问答核心) │\n│ ├── router.py (路由层：硬编码 → 语义 → 广播) │\n│ └── reranker.py (重排序层：model/rule/hybrid) │\n│ text_splitter.py (5 切分策略 + GuardStack + 后处理 + 插件注册) │\n│ knowledge_base_manager.py (多知识库管理) │\n│ prompt_manager.py (Prompt 模板管理) │\n│ embedding_model_manager.py (嵌入模型生命周期) │\n│ rag_env_setup.py (环境检测与安装) │\n├─────────────────────────────────────────────────────┤\n│ config.py (统一配置管理) │\n│ utils.py (通用工具函数) │\n├─────────────────────────────────────────────────────┤\n│ data/ (技能数据目录) │\n│ ├── kb/ (向量知识库) │\n│ ├── models/ (嵌入模型) │\n│ ├── prompts/ (Prompt 模板) │\n│ ├── config/ (运行时配置) │\n│ └── output/ (导出产物) │\n└─────────────────────────────────────────────────────┘\n```\n\n## 模块依赖关系\n\n```\nrag_skill.py / rag_standalone.py (双入口)\n ├── rag_core.py\n │ ├── config.py ← utils.py\n │ ├── prompt_manager.py ← utils.py\n │ ├── text_splitter.py\n │ ├── router.py\n │ ├── reranker.py\n │ └── knowledge_base_manager.py ← utils.py\n ├── embedding_model_manager.py ← utils.py\n └── rag_env_setup.py\n\nrag_web_ui.py (入口)\n ├── config.py ← utils.py\n ├── prompt_manager.py ← utils.py\n ├── text_splitter.py ← 策略注册表 + 守卫注册表\n ├── embedding_model_manager.py\n ├── knowledge_base_manager.py\n └── rag_core.py\n```\n\n## 数据流\n\n### 索引流程（文档入库）\n```\n文档 → text_splitter.py (切分) → embeddings (向量化) → Chroma (存储)\n```\n\n### 切分流水线架构\n\n```\n原始文本 → [守卫栈(多选)] → [主策略(单选)] → [后处理(单选/不选)] → 最终 chunks\n\n守卫栈：mermaid / code / math / table / html（可扩展）\n主策略：fixed / recursive / headers / sentence / semantic（可扩展）\n后处理：recursive / fixed / semantic 子切（metadata 白名单继承）\n```\n\n## 查询流程（问答）\n```\n用户问题 → 路由(硬编码→语义→广播) → 每 KB 检索(k) → Rerank(可选, top_k) → 上下文 + Prompt → LLM/智能体\n```\n- **路由层**：硬编码关键词匹配 → 语义签名匹配 → 全库广播兜底\n- **检索层**：每 KB 召回 k 个文档\n- **Rerank 层**（默认关闭）：cross-encoder 精排，取 top_k 条；关闭时直接用检索结果\n\n## 参数耦合说明\n\n| 参数 | 角色 | rerank 关 | rerank 开 |\n|------|------|:---------:|:---------:|\n| `retrieval.k` | 每 KB 召回数 | **最终输出数**（默认 3） | 候选池（默认 3，应与 reranker.top_k 协调） |\n| `reranker.top_k` | 精排输出数 | — | **最终输出数**（默认 5） |\n\n> ⚠️ `k` 和 `reranker.top_k` 的默认值（3 vs 5）在单 KB + rerank 开启时低效：k=3 只召回 3 个候选，reranker 无筛选余地。\n\n## 数据目录结构\n\n```\nskills/.standardization/local-rag-builder/data/\n├── kb/ # 向量知识库\n│ ├── default/ # 默认知识库\n│ ├── art/ # 艺术类 (按分类规则)\n│ ├── politics/ # 政治类\n│ └── kb_index.json # 知识库索引\n├── models/ # 嵌入模型\n│ └── model_index.json # 模型索引\n├── prompts/ # Prompt 模板\n│ └── custom_prompt_template.txt\n├── config/ # 运行时配置\n│ └── rag_config.json\n├── output/ # 导出产物\n├── cache/ # 下载缓存\n├── config_templates/ # 配置模板\n└── kb/\n ├── default/\n ├── kb_index.json\n └── auto_classify_rules.json # 分类规则\n```\n\n## 配置体系\n\n配置由 `config.py` 统一管理，JSON 格式存储。\n\n配置层级：\n1. 默认配置（`DEFAULT_CONFIG` 硬编码）\n2. 持久化配置（`data/config/rag_config.json`）\n3. 运行时更新（通过 Web UI 或 CLI）\n\n重置操作将删除持久化配置并恢复默认值。\n\nFile v1.4.3:references/changelog.md\n\n## [1.5.0] - 2026-07-07\r\n\r\n### 重构\r\n- **JS OO化**：JS 从 Python f-string 拆出为模块级 `_JS_SCRIPTS` 普通字符串变量，彻底根除转义导致 SyntaxError 问题\r\n- **签名语义化**：KB 签名从硬编码词频统计+位置硬取改为用 reranker 语义模型打分，以 KB 名为查询对 chunks 排序，取高语义相关片段生成签名。文本清洗+Unicode 乱码过滤\r\n- **极客模式重构**：分块 JSON 编辑器（5 个可折叠区域）、编辑开关（默认关闭、持久化到 config.json）、模板管理（新建/保存/覆盖/刷新/编辑）\r\n\r\n### 修复\r\n- **路由脱钩**：三步变两步（reranker×规则关键词 → 关键词精确匹配），去掉 KB 签名语义回退\r\n- **签名残留**：删除 KB 时同步清理 `kb_signatures.json`，`rebuild_all_signatures()` 先清残留再重建\r\n- **单线程服务器**：`TCPServer` → `ThreadingTCPServer`，页面加载不阻塞 API 请求\r\n- **缓存问题**：`do_GET` 添加 Cache-Control/Pragma/Expires 头，HTML head 添加对应 meta 标签\r\n- **对比分析模板**：模板内容改为表格结构输出，明确 `{dim}` 用法\r\n\r\n### 优化\r\n- **变量输入框提示**：`{dim}` 显示\"如：价格/性能/质量\"，`{role}` 显示\"如：化学分析师/技术专家\"，`{alt}` 显示\"如：其他品牌/替代方法\"\r\n- **Prompt 保存节流**：400ms 防抖 + 状态分离（保存中/已保存）\r\n\r\n---\r\n\r\n## [1.4.2] - 2026-07-06\r\n\r\n### 重构\r\n- **Prompt 模板系统/用户层分离**：`prompt_manager.py` 重构为 `SYSTEM_PROMPT_PREFIX`（固化，A系统指令+B资料占位+C问题占位+E回答前缀）和 `DEFAULT_USER_TEMPLATE`（可配置，D输出格式指令）。`build_prompt()` 自动拼接。Web UI 只暴露用户层编辑，系统层只读预览。向后兼容自动迁移旧模板\r\n\r\n---\r\n\r\n## [1.4.1] - 2026-07-06\r\n\r\n### 修复\r\n- **检索 `TextInputSequence must be str` 崩溃**：`FallbackRouter.score()` 将 `_load_signatures()` 返回的 `{\"signature\": \"...\"}` 字典直接传给 tokenizer，TypeError 未被 `except ValueError/RuntimeError` 捕获导致 `rag_skill.py --query` 全线崩溃。改为提取 `sig[\"signature\"]` 后传入\r\n\r\n---\r\n\r\n## [1.4.0] - 2026-07-06\r\n\r\n### 修复\r\n- **多页 PDF 只切第一页**：`import_documents_to_kb()` 预处理时只取 `docs[0].page_content`（PDF 仅第一页），56 页文件只产出 4 块。改为 `\"\\n\\n\".join(d.page_content for d in docs)` 拼接全部页\r\n- **语义子切批次内重复 ID**：SM3 哈希碰撞导致 ChromaDB 抛出 `Expected IDs to be unique`，备份回滚机制反复触发后 HNSW 索引损坏。改为入库前 `seen` 集合去重，保留首个副本\r\n- **PDF 分类文本乱码**：`run_import()` 用 `open(file, \"r\", \"utf-8\")` 读取 PDF 二进制为 UTF-8 文本，中文关键词全变乱码，'LLM' 恰好出现在 ASCII 区域导致路由到 `LLM奠基理论`。改为 PyPDFLoader 提取真实文本\r\n- **h2 capture group 标题不完整**：`^(\\d+|\\w+).*仪器设定$` 的 `m.group(1)` 只捕获仪器代码（如 `996`），注入 `## 996` 而非完整的 `## 996 PDA 仪器设定`。改为外层 capture group 包裹整行\r\n- **Chroma HNSW 索引损坏**：`add_documents()` 在已有 ID 冲突时触发 `except Exception` 备份回滚，多次后 HNSW segment 丢失索引文件（仅剩 `index_metadata.pickle`），全部写入/查询中断。改为 `upsert()` 覆盖而非 `add_documents()`，从源头杜绝 ID 冲突触发备份链\r\n\r\n### 改进\r\n- **PDF 编码乱码检测 + OCR 自动回退**：中文文件名 PDF 在 pypdf 提取后检测 CJK 字符占比，低于 10% 且字符数 > 100 时视为编码异常，自动触发 EasyOCR 重提取。解决部分 PDF（CID 字体/自定义编码）文本关键词不匹配问题。**分类阶段也走 OCR**：保证路由在清晰文本上做决策，而不是先路由到错误 KB 再用 OCR 补救\r\n- **路由层 hybrid 加权投票**：路由开启时，`auto_classify(use_semantic=\"hybrid\")` 先关键词跑出 top-3 候选池 → 语义 rerank（min-max 归一化处理 logits 负数问题）→ 关键词 40% + 语义 60% 加权投票。路由不再是关键词落空后的回退，而是真正参与分类决策\r\n- **路由关键词扩充**：`政经文哲` 补充 29 个关键词（马克思/资本论/习近平/新时代/三个代表等）；`诸子百家` 补充国富论/货殖列传/儒家等 13 个关键词\r\n\r\n### 技术债\r\n- **HNSW 损坏重建验证**：4 个损坏 KB（LLM奠基理论/理化检测/白酒/设备条件）通过删除 segment 目录+触发 Chroma 重建全部恢复，数据零丢失\r\n\r\n---\r\n\r\n## [1.3.8] - 2026-07-06\r\n\r\n### 修复\r\n- **Chroma doc_count WAL 漏计**：`vectorstore._collection.count()` 因 Chroma SQLite 元数据段不查 WAL 导致最近写入被漏计，HTML 面板文档数不刷新。改为 `max(chroma_count, 累加值)` 兜底\r\n\r\n### 变更\r\n- **SM3 国密哈希去重**：`add_documents_to_kb()` 使用 SM3(content) 作为文档 ID，相同内容重复导入时 Chroma 覆盖而非追加，杜绝重复块\r\n- SM3 实现使用 Python 内置 `hashlib.new('sm3')`，零第三方依赖，国密合规\r\n\r\n---\r\n\r\n## [1.3.7] - 2026-07-06\r\n\r\n### 修复\r\n- **`_load_index()` 磁盘扫描补全 KB**：修复后 `--kb-list` 可正确显示全部 10 个知识库（含 `量子物理和弦`），不再遗漏磁盘上已有但索引缺失的 KB\r\n\r\n### 变更\r\n- 版本号从 _meta.json 强制读取，禁止 LLM 手动传参\r\n\r\n---\r\n\r\n## [1.3.6] - 2026-07-06\r\n\r\n### 修复\r\n\r\n- **`_load_index()` 索引重置丢失 KB**：索引文件为空时直接重置为仅 `default`，导致\"生物医疗\"等 KB 从索引中丢失。改为扫描磁盘目录恢复，无条件补录索引缺失的 KB。同时移除 `len(data)==1` 的恢复条件门禁（# 索引断裂恢复）\r\n- **`run_import()` 路由逻辑**：`--kb` 默认值从 `\"default\"` 改为 `None`，区分\"用户未指定\"与\"用户指定 default\"。`kb is None` 时走自动分类链路：关键词硬匹配 → 路由语义匹配（仅开启时）→ `default` 兜底。`kb is not None` 时为明确指令，直接入库不走路由\r\n\r\n### 变更\r\n- `_load_index()` 从有条件恢复改为无条件定期扫描（每次加载索引时对比磁盘目录，自动补录）\r\n\r\n---\r\n\r\n## [1.3.5] - 2026-07-06\r\n\r\n### 新增\r\n- **run_import() 流程钩子**：当 `auto_classify=False` 且路由层开启（`router.enabled=True`）时，自动触发语义分类，无需调用者显式传 `--auto-classify`\r\n\r\n### 变更\r\n- **FallbackRouter() 提至循环外单例复用**（从 1.3.4 保留）：避免每次 KB 重载 1.3GB reranker 模型\r\n- **撤回 1.3.4 的 `best_score = -float('inf')` 改动**：该改动拆除了语义模式的安全闸门，导致跨语言场景下 reranker 的噪声负分随机选 KB。恢复 `best_score = 0`，保持零阈值安全回落逻辑\r\n\r\n---\r\n\r\n## [1.3.4] - 2026-07-06\r\n\r\n### 修复\r\n- **`auto_classify()` 语义模式 `best_score` 初始值导致负分被丢弃**：`best_score = 0` 与 reranker 输出的原始 logits（可负）不兼容，英文内容×中文关键词锚点时所有得分均为负 → 永远回退到 `default`。修复为语义模式 `best_score = -float('inf')`，确保负数间正确比较选最高\r\n- **`FallbackRouter()` 每次 KB 迭代均 new 实例**：循环内 `fallback = FallbackRouter()` 导致每个 KB 重载 1.3GB reranker 模型（7 KB = 7 次加载）。提至循环外单例复用\r\n\r\n### 撤回（见 1.3.5）\r\n- `best_score = -float('inf')` 在跨语言场景下导致噪声路由，已于 1.3.5 撤回\r\n\r\n---\r\n\r\n## [1.3.3] - 2026-07-05\r\n\r\n### 修复\r\n- **`_load_index()` 空字典导致索引丢失**：`if not data:` 把空字典 `{}` 视为未初始化，替换为只剩 `default`，导致所有知识库从索引消失。修复为 `if data is None`，并增加自动恢复逻辑——索引只有 default 时扫描磁盘自动补回其他 KB\r\n\r\n---\r\n\r\n## [1.3.2] - 2026-07-05\r\n\r\n### 新增\r\n- **ChromaDB 容灾备份**：`add_documents_to_kb()` 入库前自动备份 `chroma.sqlite3.bak`，写入失败自动回滚恢复\r\n- **HNSW 损坏自动修复**：`retrieve_documents()` 检测到 HNSW 索引损坏时自动清理段数据并重建索引，查询不再中断\r\n\r\n### 修复\r\n- **Python 3.11 f-string 兼容**：修复 GPU OCR 脚本中反斜杠转义导致的 SyntaxError\r\n- **ChromaDB 文件检测**：`add_documents_to_kb()` 中 `.parquet` 改为 `.sqlite3`，适配新版 ChromaDB\r\n\r\n---\r\n\r\n## [1.3.1] - 2026-07-05\r\n\r\n### 改进\r\n- **扫描 PDF 自动 OCR**：`import_documents_to_kb()` 自动检测扫描版 PDF，无文本时回退 EasyOCR（不再需要手动写 OCR 脚本）\r\n- **KB 签名自动更新**：`add_documents_to_kb()` 入库时自动调用 `update_kb_signature()`，签名不再滞后\r\n- **签名质量提升**：过滤纯数字 token、中文词加权 3x、取中后段代表性片段（跳过封面/目录）\r\n- **文档一致性修复**：SKILL.md / guide.md / setup-spec.md / faq.md 中 Python 版本从\"3.8-3.11\"更新为\"3.11+\"，补充 OCR 回退和签名功能说明\r\n\r\n---\r\n\r\n## [1.3.0] - 2026-07-05\r\n\r\n### 新增\r\n- **路由层关键词语义分类**：路由开启后，入库和出库共享同一套 reranker 语义匹配逻辑\r\n - 入库：`auto_classify()` 新增 `use_semantic` 参数，路由开时用 reranker 对 `rule.keywords × doc_content` 打分，而非硬匹配\r\n - 出库：`route_query()` 新增 `① 关键词语义路由` 步骤，先于硬编码和签名回退执行\r\n - 扩展名匹配始终精确，不受路由开关影响\r\n - CLI：`rag_skill.py --import-file --auto-classify` 自动分类入库\r\n - Web UI：路由层新增「语义分类阈值」配置项\r\n\r\n---\r\n\r\n## [1.2.18] - 2026-07-05\r\n\r\n### 修复\r\n- **Web UI 启动报错 UnboundLocalError**：`generate_html()` 中 `RECOMMENDED_RERANK_MODELS` 在第 119 行使用但在第 128 行才 import，导致 Python 将其视为未绑定的局部变量\r\n - 根因：过滤器代码插入位置在 import 语句之前\r\n - 修复：将过滤逻辑移到 `from embedding_model_manager import ...` 之后\r\n\r\n---\r\n\r\n## [1.2.17] - 2026-07-05\r\n\r\n### 重构\r\n- **知识库列表移除嵌入模型下拉框**：图1（KB 列表）的逐 KB 模型选择器与图2（规则编辑器）完全重叠，移除后只显示 KB 名 + 文档数。KB 嵌入模型选择统一在「自动分类规则」编辑弹窗中操作。\r\n\r\n---\r\n\r\n## [1.2.16] - 2026-07-05\r\n\r\n### 修复\r\n- **知识库嵌入模型选择器存的是文件路径而非模型 ID**：下拉菜单的 `value` 用了 `m.get(\"path\")`，导致 `set_kb_model()` 将完整文件路径写入 KB 配置\r\n - 根因：`rag_web_ui.py` 规则编辑器 `