local-vault

local-vault

将一个包含原始文件的文件夹转换为Markdown 知识库，让大模型可以通过 grep 搜索，并负责任地基于该知识库回答问题。

思维模型：SOURCE = 原始文件（事实来源）。VAULT = 每个源文件对应一个 .md 文件，其中包含用于检索的 frontmatter（摘要 / 标签 / 同义词）和一个 source 反向链接。大模型读取知识库；用户则通过原始文件进行核实。

这里有两个不同的任务——先判断用户需要哪一种：

• A. 转换 / 同步——用户放入了文件，希望将它们加入知识库 → 运行流水线（scripts/sync.py）。
• B. 检索 / 回答——用户想要基于现有知识库获得答案 → 按照下方的检索与反馈协议操作。此时不要运行流水线。

---

A. 转换 / 同步

一次性设置（如果尚未完成，请替用户完成）

1. Python 依赖（用户级，无虚拟环境）：

   python3 -m pip install --user requests python-dotenv pypdf pymupdf4llm openpyxl python-pptx
   

2. pandoc（用于处理 docx/rtf/odt/epub）：brew install pandoc（macOS）/发行版软件包。
3. ffmpeg（仅用于音频 / 视频转录）：brew install ffmpeg（macOS）/发行版软件包。whisper 引擎会根据平台自动选择——Apple Silicon 上使用 mlx-whisper（GPU），其他平台使用 faster-whisper（跨平台 CPU/CUDA）——并在用户同意后于首次运行时自动安装（无需手动执行 pip）。首次运行时如果检测到音频 / 视频，工具会显示模型大小选项（tiny 约 75 MB / small 约 480 MB / turbo 约 1.6 GB / large-v3 约 3 GB），并允许用户选择或跳过；选择会保存到 .env（KB_WHISPER_MODEL），之后不会再次询问。完全在本地运行——无需令牌 / 配额；模型只需下载一次，之后即可离线使用。
4. claude CLI 位于 PATH 中——流水线会调用 claude -p 来补充 frontmatter 并对 PPT 图片执行 OCR。如果未安装，会跳过这些步骤（不会导致失败）。
5. 配置路径——有两种方式：
   • **引导式（推荐用户使用）：**在终端中运行 python3 scripts/sync.py 即可。首次运行时（尚未配置路径）会启动交互式向导：提示用户选择原始文件文件夹和知识库文件夹（以及可选的 MinerU 令牌），创建这些文件夹，写入 scripts/.env，并说明如何使用此工具。之后再次运行即可转换文件。
   • **手动配置：**将 scripts/.env.example 复制为 scripts/.env，并设置 KB_SOURCE_DIR（原始文件）和 KB_TARGET_DIR（Markdown 知识库）的绝对路径。MINERU_TOKEN 为可选项（仅用于旧版 .doc/.ppt、.html、扫描版 PDF 和图片——可在 https://mineru.net 获取）。
   • 当**你（Claude）**替用户运行设置时，优先采用手动配置：询问用户的两个文件夹，然后直接写入 scripts/.env（向导只会在交互式 TTY 中启动，而 claude -p 子进程不满足此条件）。

运行

python3 scripts/sync.py

在 macOS 上，首次运行（向导或任何常规运行）还会在知识库根目录（SOURCE 文件夹的父目录）中放置一个可点击的 sync.command，其中预先写入了 sync.py 的绝对路径（工具和数据分开存放——在 /plugin install 下，脚本位于 ~/.claude/plugins/cache/…，离数据文件夹很远，因此相对路径启动器无法使用）。之后的日常流程是：将文件放入 SOURCE → 双击 sync.command → 阅读 VAULT 中的 .md 文件。启动器具有幂等性；较旧版本在 SOURCE 文件夹中留下的过时自动生成副本会自动删除（用户编写的副本不会被触碰）。如果根目录中已存在不同的 sync.command，交互式终端会提示更新 / 跳过；在非交互模式下，我们自己的过时启动器会自动静默修复，而用户自定义的启动器则会保持不变。

首次在没有配置的情况下运行终端 → 启动设置向导（见上文）。.env 存在后：

• 增量处理：仅处理 SOURCE 中没有对应 .md 文件的文件。若要强制重新转换，请先删除对应的 .md 文件，然后重新运行。
• 本地处理路径无需 MinerU 令牌（xlsx/csv/docx/pptx/md/txt/代码 + 数字 PDF）。仅当文件确实需要 MinerU 时才会延迟验证令牌。
• 孤立文件暂存：如果源文件被删除，其工具生成的 .md 文件及其 attachments/<stem>/ 图像会移至 orphaned/<date>/ 文件夹（绝不会永久删除——用户可能添加了备注），并清理现已为空的 attachments/。用户编写的 .md 文件（没有转换器标记）绝不会被触碰。

路由（每种文件类型使用哪种工具）

类型	工具	说明
.xlsx	openpyxl 双重读取	每个工作表：值网格（含 A/B/C 列和行坐标）+ 公式列表
.csv / .tsv	csv → Markdown 表格	超过 CSV_MAX_ROWS 后截断
.pdf（数字版）	pymupdf4llm	本地处理，速度快，无配额；如果 PYMUPDF4LLM_WRITE_IMAGES（默认开启），则将 ≥ PYMUPDF4LLM_IMAGE_SIZE_LIMIT（页面的 12%）的图像提取到 attachments/，然后按最小字节数过滤并去重。如果 pymupdf4llm 崩溃（例如缺少字体），会先尝试本地纯文本处理，然后再使用 MinerU
.pdf（扫描版）	MinerU vlm（备用）	每页字符数过少时触发
.docx/.rtf/.odt/.epub	pandoc	将图像提取到 attachments/
.html/.htm	pandoc（本地）	先移除 style/class/id 属性以及布局用的 div/section/span，仅保留内容；表格无损保留。无需 MinerU/令牌
.pptx	python-pptx	标题/正文/表格/图表/备注 + 图像；智能 OCR（见下文）
.md/.markdown/.txt	直接传递	原样复制；仅添加 frontmatter，正文保持不变
.json/.yaml/.py/…	代码直接传递	用围栏代码块包裹 + frontmatter
音频 .mp3/.m4a/.wav/… + 视频 .mp4/.mov/.m4v	whisper（本地；自动选择引擎：Apple Silicon 上使用 mlx-whisper，否则使用 faster-whisper）	语音转文字，无需令牌/配额；首次运行会询问要使用的模型（显示模型大小），并在用户同意后自动安装引擎（如果此机器上已缓存某个模型，则直接复用，不再询问）；每个片段带有 [mm:ss] 时间戳和检测到的语言；视频仅处理音轨（ffmpeg 从容器中提取音轨）。需要 ffmpeg；对清晰语音效果最佳——歌曲/音乐的转录效果较差
旧版 .doc/.ppt、图像	MinerU（云端）	本地库无法读取这些文件
其他所有类型（numbers/pages/zip/…）	跳过	结束时会报告并提供修复提示——绝不会静默丢弃

PPT 智能 OCR

通过 claude -p 对幻灯片中嵌入的图像进行 OCR（其 Read 工具会读取图像），但为了避免每个装饰性徽标都启动一个运行缓慢的 claude：会对相同图像去重（只进行一次 OCR），跳过小于 OCR_MIN_IMAGE_BYTES 的图像，并发处理内容不同的图像（OCR_MAX_WORKERS）。原生 PowerPoint 图表对象会直接读取（类别 + 系列值 → 表格）。将 OCR_PPTX_IMAGES = False 设为关闭所有 OCR（仍会提取图像并添加引用）。

写入每个 .md 的 Frontmatter

---
source: "[[…/<file>.<ext>]]"   # backlink to the raw file
source_type: pdf | xlsx | docx | pptx | md | …
converted_by: pymupdf4llm | pandoc | python-pptx | excel-openpyxl | csv | passthrough | whisper | "MinerU vlm" | …
# enrich (best-effort via claude -p, may be missing on failure):
abstract: |
  3-sentence summary.
auto_tags: [..]
synonyms: [English + 中文 同义词]   # so any phrasing greps the right doc
key_data: ["important numbers/facts"]
---

调优（scripts/config.py）

PYMUPDF4LLM_MIN_CHARS_PER_PAGE（扫描版 PDF 的阈值） · PYMUPDF4LLM_WRITE_IMAGES（开启/关闭数字版 PDF 的图像提取；.env： KB_PDF_NO_IMAGES=1 可禁用） · PYMUPDF4LLM_IMAGE_SIZE_LIMIT（图像提取面积下限，占页面面积的比例；默认值 0.12） · PYMUPDF4LLM_IMAGE_MIN_BYTES （丢弃小于此大小的图像；默认值 6000） · OCR_PPTX_IMAGES / OCR_MIN_IMAGE_BYTES / OCR_MAX_WORKERS（PPT 图像 OCR） · EXCEL_MAX_CELLS_PER_SHEET · CSV_MAX_ROWS · ENRICH_FRONTMATTER。

---

B. 检索与反馈协议（基于知识库作答）

当用户要求你基于其知识库作答或进行跨文档比较时，直接读取知识库（grep + 读取 .md）。在此过程中，主动检查并指出问题——不要只给出答案。

启动时的知识库健康检查（会话中的第一个知识库问题）

find "$KB_TARGET_DIR" -name "*.md" -not -path "*/.obsidian/*" | wc -l   # file count

粗略判断规模，只有存在问题时才提及： 小型（<100 个文件）用 Agent 式 grep 已足够 · 中型（100–500）留意关键词命中数量 · 大型（500–2000）建议添加语义搜索层（例如 Smart Connections） · 超大型（>2000）建议使用真正的 RAG 层。

复杂查询后的自检（仅在触发时提醒）

信号	告知用户
一次 grep 命中 >30 个文件	关键词太宽泛——换成更具体的关键词，或添加语义搜索
读取 5+ 个文件后仍未找到答案	可能是同义词缺失，也可能确实不在知识库中——列出已读取的文件
多次询问同一主题	提议为其建立索引/MOC
“哪一章讲了 X”需要通读全文	提议为该文档补充大纲
某文档缺少 abstract	可能是其丰富处理失败——提议重新处理
问题需要精确数字/公式	提醒用户点击 source 反向链接，并对照原文核实

主题查询 → MOC 条目顺序与演进

MOC（内容地图）是用户用于进入某个主题的笔记——Frontmatter 为 type: moc，存放在 <vault>/索引/（或 index/）中。

1. 对于跨文档主题问题，先检查是否有相关 MOC；如果有，先读取它，并以此作为答案框架。
2. 如果没有，且用户持续询问该主题，提议创建一个最简 MOC（Frontmatter + ## related files 列表——仅此而已）。
3. MOC 的结构应从实际使用中逐步扩展，绝不预先设计。发现某种模式时（频繁询问的子主题、反复出现的判断或未解决的问题），提议将其沉淀下来——由用户决定，你负责起草。

频率限制（避免反复提醒）： 每个会话最多提出 一项 MOC 演进提议；如果在过去 <7 天内提议过此 MOC，则跳过；需要确实存在多种信号形成的模式，而非一次随口提问；提议仅使用一个 > 💡 … 引用块。

不要

• 不要在每个答案后都附上一大段“提示”——只有触发信号时才提醒。
• 不要仅为回答问题而运行转换流程。
• 不要批量编辑知识库的 .md 文件（用户笔记和工具输出共存）。
• 不要因为 grep 没搜到就编造内容——“知识库中没有”胜过猜测。
• 不要将源文本复制到 MOC 中——只添加 wiki 链接和一行注释。

备注

• 该流水线不依赖正在运行的 Claude 会话——它是一个 CLI；只有在可选的丰富化/OCR 步骤中才会调用 claude -p。
• 它绝不会重写文档的正文——所有自动化操作仅针对 frontmatter，因此该工具本身不会造成任何内容丢失。
• 权威且经过测试覆盖的源代码位于作者的开发项目中；此处的 scripts/ 是打包后的快照。