知识库实时监测
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_ae4fb953/knowledge-monitor,将其接入 AI 助手以提供知识库检测器能力。
技能介绍
为什么需要它
RAG 知识库一旦混入多方写入者,就会出现一类棘手问题:索引的所有权不明确。AI skill 刚把一批新文档写进知识库、完成向量化,cron 定时任务可能把这些文档当成"用户手动修改",再次触发索引重建——轻则浪费算力,重则重建过程中的文件变动又引发二次重建。反过来,如果用户在编辑器里改了一篇 notes.md,系统却毫不知情,检索时拿到的仍是旧向量。
Knowledge Monitor 要解决的就是这件事:让定时扫描知道"这次变更是谁做的",从而决定是否重建索引。
核心机制
核心是静默窗口(Silence Window)机制,配合 md5 hash 快照对比与 mtime 时间戳判断,流程如下:
- 写入前登记:AI skill 在写文件之前调用
--silence记录一个静默窗口,默认 300 秒; - 写入后关闭:skill 写完文件、完成向量化之后调用
--unsilence关闭窗口; - 定时扫描:cron 每 10 分钟触发
--scan,对比上次快照与当前文件的 md5 hash,找出变更文件; - 归属判定:检查变更文件的修改时间(mtime)是否落在任一静默窗口内——在窗口内则判定为 AI 操作,跳过重建(索引已由 skill 自己处理);在窗口外则判定为用户手动操作,触发增量重建并将事件写入
changelog.json。
每个窗口带过期时间:即使 skill 异常退出,窗口也会在默认 300 秒后自动失效,不会永久吞掉后续的用户操作。
--scan 的完整流程是:清理过期窗口 → 对比新旧快照 → 过滤静默窗口内的变更 → 增量重建索引 → 写入 changelog。另有 --quick-check 供 knowledge-reader 在检索前调用,只返回"是否存在用户手动变更",不触发重建,适合高频检索路径。
边界与注意点
- 脚本只读不写:不修改任何
.md文件,只读文件系统并操作索引; - 依赖
faiss-cpu、numpy、ollama,需通过qclaw-envskill 安装; - 失败不阻塞:Ollama 未运行时只记录错误日志,变更事件不会丢失;
- 协作是硬前提:静默窗口依赖写入方主动调用
--silence/--unsilence,未集成该协议的写入者产生的变更会被误判为手动操作; - 所有用户手动变更和重建结果均可在
changelog.json中回溯。
使用场景
- 团队知识库由 AI 和人共同维护,需要区分哪些改动是用户手动做并触发重新索引
- 知识库搭配 knowledge-writer 等 skill 使用时,避免刚写完就被 cron 当成手动变更重建索引
- 想在用户编辑文档后保留 Faiss 索引准确性,让玩家只改文件也能得到正确的检索结果
- 频繁检索前用 quick-check 快速判断知识库是否有用户手动变更,决定是否重建索引
适合人员
- 维护 RAG 知识库的后端工程师,想让 cron 扫描跳过 AI 写入、只重建手动改动
- 开发或定制 knowledge-writer 类 skill 的工程师,需要理解 silence 与 unsilence 窗口协议
- 负责 RAG 检索质量的算法工程师,关心用户改动是否能及时反映进 Faiss 索引
- 多人协作维护知识库的团队,希望离线编辑后不打断 AI 工作流且检索结果保持准确