知识库原子化切片引擎

核心挑战：RAG 构建中的“文档消化”难题

构建有效的 RAG 知识库，第一步是将冗长的源文档拆解成可被精确检索的片段。直接上传整篇文档会导致：

• 语义碎片化：简单的字数或行数切割会粗暴地斩断代码块、表格或逻辑论证，破坏知识的完整性。
• 检索噪音：单一片段过大，包含过多无关上下文，降低检索精度；片段过小则失去语境，无法回答问题。
• 元数据缺失：传统切片缺乏结构化元数据，如分类、关键词、问答对，严重削弱了向量检索与语义匹配的效果。
• 维护困难：大量零散的切片文件缺乏统一管理，版本追踪、去重和错误修复成为噩梦。

该技能如何运作：从长文档到原子切片

knowledge-engineering 技能定位为 RAG 管线的 ETL 引擎，其核心是 原子化切片 理念：每个输出文件都是一个自包含、检索就绪的知识单元。它通过以下关键步骤和能力解决上述问题：

1. 结构化预分析与强制规划：执行任何切割前，必须完成一个预处理思维链（CoT），扫描文档结构（H1-H3 标题、代码块、表格），并执行 Token 预算模拟。这确保了切割方案在逻辑边界进行，而非机械截断。
2. 智能路由与目录隔离：自动为每个源文件创建独立文件夹（如 source_name/api/），并根据内容属性（如配置说明、操作指南）将切片路由到二级目录，从物理层面杜绝混乱。
3. 元数据驱动的切片生成：每个 .md 切片都强制包含一个 YAML 头部，其中 embedding_hint（语义摘要）、hybrid_keywords（混合关键词）、qa_pairs（示例问答）等14个字段由 Agent 推理生成。这些元数据直接服务于检索时的向量匹配和意图识别。
4. 多层次自检与审计协议：生成后立即进行单片校验（validate_slice.py），检查 YAML 完整性、语义指代（禁止使用“上述”等模糊词）和事实保真。随后进行批量审计（batch_audit.py），确保索引连续、无死链和跨切片语义重叠。
5. 渐进式防卡死流程：对于超长文档，采用 Init → Step → Poll 协议，每次只生成和校验少量切片（每批最多5个），防止 Token 溢出，并支持断点续传，确保过程可靠。

适用边界与关键约束

本技能并非万能的文档转换器，其设计边界明确：

• 输入格式：支持 Markdown, Text, YAML, JSON, PDF 等文本为主的格式。不支持直接处理图片、扫描件、数据库或动态网页。
• 输出核心：产出物是为向量数据库（如 Milvus, Pinecone）和检索器优化的原子切片文件。其验证（evaluate_retrieval.py）依赖于 sentence-transformers 模型来模拟真实检索效果（R@1, MRR 等）。
• 执行铁律：严格遵守“目录隔离”、“语义完整优先于长度”和“零指代”等核心红线。任何对事实数据（数值、参数、错误码）的改动都是被禁止的。最终交付前必须通过 batch_audit.py 和检索评估，输出证据链。

简言之，这是一个为构建高质量、可维护的 RAG 知识库而设计的专业切片控制器，强调过程的规范性、输出的结构化和结果的检索有效性。