知识库灌入

背景：向量数据库灌入的工程痛点

当你准备将本地文档、共享笔记或知识库目录接入 RAG（检索增强生成）流程时，第一步通常是把这些文本变成向量并写入数据库。如果直接写一个脚本去遍历目录，很快就会遇到问题：大文件会撑爆单条记录的长度限制，网络抖动导致的中断会让整个任务前功尽弃，而当目录里已有数千个文件时，很难分辨哪些是新内容，哪些是旧索引。

这个技能的目标是把“知识库灌入”做成一条标准化的流水线，处理从文件读取、切块到向量入库的完整过程，并加入工程上必要的容错和验证机制。

工作方式与核心能力

1. 灵活的后端适配
技能剥离了对特定向量库的硬依赖。默认使用本地部署的 ChromaDB，适合小规模起步。如果后续需要迁移到托管服务，只需设置 VECTOR_DB 环境变量即可切换后端，而无需修改灌入逻辑。源目录则通过 KB_DIR 指定。

2. 自动化的文档预处理
对于超过 4000 字符的大文件，技能会自动按段落将其切分为 chunks，并严格控制单个 chunk 的长度不超过 8000 字符。同时，它通过计算文件路径的 MD5 值前 16 位来生成唯一标识，用于后续的去重判断。

3. 分批执行与断点续跑
灌入脚本以批处理模式运行，每批处理文件数限制在 500 个以内，防止单次内存占用过高。更重要的是，它会将进度实时保存到状态文件中。如果灌入过程中出现异常中断，重新运行时脚本会自动读取状态文件，跳过已完成的部分，实现无缝续跑。

4. 索引质量验证
灌入完成后，流程会强制进入验证阶段。它会检查最终的 chunks 数量是否大于 0、每一个 chunk 是否都成功生成了对应的 embedding 向量，以及整个过程中的错误率是否在可控范围内。

适用边界与注意事项

• 外部脚本依赖：核心脚本 scripts/knowledge-ingest.py 并未包含在技能目录中。你需要根据接口描述从项目仓库获取，或自行编写 Python 代码实现该逻辑。
• 适用场景：该技能专为首次全量灌入或索引重建设计。如果你只需要查询已有知识，应直接调用对应的搜索工具；若只需添加三五个文件，手动调用针对单个文件的灌入命令会更轻量。
• 大规模数据建议：虽然支持断点续跑，但对于超过 5000 文件的超大目录，建议通过定时任务（Cron）分多天执行，以保持稳定的处理性能。
• 命名规范：客户目录名将直接映射为向量库的集合名（Collection Name），请确保目录名规范，避免使用特殊字符引发报错。