用途：把一文件夹原始文件转换成一个可供 LLM grep 的 Markdown vault，并在检索时负责任地回答问题。心智模型：SOURCE 是原始文件（唯一事实来源），VAULT 是每个源文件对应一个 .md，带检索用 frontmatter（abstract / tags / synonyms）和源文件回链；LLM 读 vault，用户回原始文件核对。
两个任务需区分：A 转换/同步——文件已放入、想进 vault，运行 pipeline（scripts/sync.py）；B 检索/回答——从已有 vault 取答案，按检索与反馈协议，不要跑 pipeline。
主要能力（转换）：增量处理，仅处理 SOURCE 中无对应 .md 的文件；按类型路由——xlsx 用 openpyxl 双读（值网格+公式）、csv/tsv 转 Markdown 表、数字 PDF 用 pymupdf4llm、扫描 PDF 回退 MinerU vlm、docx/rtf/odt/epub 与 html 用 pandoc、pptx 用 python-pptx 并做智能 OCR、md/txt 直通、代码包成围栏代码块、音视频用本地 whisper 转写（含逐段 [mm:ss] 时间戳与语言检测，视频只取音轨）、旧版 .doc/.ppt 与图片走 MinerU 云端、其余类型跳过并在结尾报告。PPT OCR 会去重图片、跳过过小图片、并发处理内容图，也可用 OCR_PPTX_IMAGES=False 关闭。每个 .md 写入 frontmatter（source 回链、source_type、converted_by，以及尽力而为的 abstract/auto_tags/synonyms/key_data）。源文件删除时其工具生成的 .md 与附件被移入 orphaned/<日期>/ 而非硬删除。
使用方式：首次安装依赖 python3 -m pip install --user requests python-dotenv pypdf pymupdf4llm openpyxl python-pptx；docx 等需 pandoc；音视频需 ffmpeg。配置路径可用交互向导（直接运行 python3 scripts/sync.py）或手动复制 scripts/.env.example → scripts/.env，设置 KB_SOURCE_DIR 与 KB_TARGET_DIR（均为绝对路径），MINERU_TOKEN 可选。之后运行 python3 scripts/sync.py。macOS 首次运行会在知识库根目录生成可点击的 sync.command。检索时直接 grep 并读 .md；会话首次 vault 提问做健康检查（文件数），复杂查询后按信号提示（如一次 grep 命中超过 30 个文件、读 5 个以上仍无答案、缺 abstract 等）。主题类查询优先看 MOC（frontmatter type: moc，位于 <vault>/索引/ 或 index/），没有且反复被问可建议创建。
限制：pipeline 不依赖 Claude 会话，是 CLI，仅可选地调用 claude -p 做 enrich/OCR；不重写正文，自动化仅限 frontmatter。本地路径无需 MinerU token，token 仅在确有文件需要时才惰性校验。不应对着问题跑转换 pipeline，不批量编辑 vault 的 .md，不在 grep 未命中时编造内容，不把源文本抄进 MOC。更多细节（各调优参数）见 scripts/config.py。