Embedder KB 语义检索库

问题：技术文档散落各处，写代码时找不到对的片段

在嵌入式开发中，一个项目往往涉及多份数据手册、HAL/LL 例程源码、厂商应用笔记和 SDK 文档。这些资料格式各异、体积庞大，全量阅读不现实，而传统全文搜索又无法理解语义——你搜 "以太网描述符" 可能漏掉 "ETH descriptor" 的段落。当你需要写一段 STM32H7 以太网 DMA 代码时，真正卡住你的不是语法，而是 "描述符 Cache 一致性" 这种细节散落在哪份 PDF 的第几页。

工作方式：语料进库，语义出库

Embedder KB 用三个零三方依赖的 Python 脚本解决这个问题。把语料（.md、.c、.h、.py、PDF 等）放进 corpus/，mcu_init.py 或 mcu_embedder.py build 会完成切分并向量化——调用 SiliconFlow 的 bge-m3 embedding 模型，把每个片段编码成稠密向量存为 pickle 文件。之后用 mcu_embedder.py query "STM32H7 以太网描述符 Cache 一致性" --topk 5 就能拿到语义最相关的片段，而且不需要精确关键词匹配。

几个关键设计值得留意：

• 增量重建：--incremental 只重算新增或改动过的文件，mcu_watcher.py 监听目录变化自动触发，PDF 变更也会重新抽取。
• PDF 流水线：mcu_embedder.py extract 依次尝试 pdftotext、pypdf、PyPDF2，把 PDF 转成可索引的 .txt。
• WorkBuddy 集成：--prompt 参数输出的上下文块可以直接贴进对话，让大模型基于你的私有语料写代码。
• 离线自检：mcu_embedder.py selftest 不联网就能验证切分、检索和增量判定逻辑是否正确。

适用边界与注意点

这套方案不是万能的。它依赖 SiliconFlow 的在线 embedding 服务——账户必须有余额，否则 API 返回 402。建库前先跑 mcu_embedder.py check-key 确认密钥有效，能避免大量语料跑到一半才失败。

自动化任务尤其要注意：WorkBuddy 的运行环境不继承 shell 变量，API Key 必须写在 .env 文件里，脚本内置的 load_env_file() 会读取它。

语料质量也直接影响召回效果。建议在笔记顶部加 > 关键词：型号 外设 寄存器 常见坑 的元信息，按 "写代码会卡住的点" 来组织内容，而不是按教科书章节叙述。corpus/README.md 这类目录说明文件会被自动排除在向量库之外。

这个工具适合技术文档的语义级检索，但如果你的语料是高度结构化的表格数据，或者需要跨文档的复杂推理，它只能给你一个起点——最终还是得靠人（或大模型）来消化和整合。