用 LangGraph 打造个人 AI 智能助手：文件搜索工程实践

注：这篇文章讲的是该项目的 V1 版本。这是一个真实、可用的助手，我每天都在用——不是一个完成品。V2 正在开发中，我很希望听到你对它的想法（文末会更多涉及）。

我开始学习 agentic AI 的方式可能跟大多数人一样——看课程，逐个学习 LangChain 和 LangGraph 的基础概念：state、nodes、edges、tools、memory、human-in-the-loop、guardrails。在能真正构建东西之前，有很多基础工作要做，到某个时刻，教程项目的驱动力就消退了。我不想再做另一个"spec-to-API agent"演示项目，然后再也不打开它。我想做一个我真正会用的东西。

所以我选了一个自己真正面临的问题：太多文件散布在 Downloads、Desktop 和 Documents 里，完全记不得什么东西放在哪儿。结果就是 my-assistant——一个永远置顶的桌面小部件，我可以用纯英文问"我写过什么关于 TaskFlow 审批流的东西？"或"打开我上周的时间表"，它就能找到。

实际功能

在底层，它是一个 AI agent（不是多个 agent 的群组，下面会详细说）——用 LangChain 和 LangGraph 构建，由本地向量数据库（Qdrant）支持语义搜索，由 Groq 托管的模型进行实际推理。它有六个工具：按内容搜索、按文件名搜索、打开文件或文件夹、统计已索引文件数、列出已索引文件夹、索引新文件。一个基于 Flet 的 UI 把所有功能包装成一个小的、永远置顶的聊天小部件，放在我的桌面上。

我最骄傲的部分不是搜索功能——而是索引可以自动保持活跃。后台文件系统监察器会注意到我何时下载了新东西、编辑了现有文档或删除了文件，然后自动更新索引，我无需运行任何手动命令。告诉它"索引我的新 PDF"，它就会这么做，或者就在后台默默地工作。

一个 agent，而不是多个——以及我为什么花了这么久才真正理解这一点

早期，我假设"一个包含很多步骤的长流程"——扫描文件夹、提取文本、分块、嵌入、存储——意味着我需要多个 agent 协同工作。其实不是，弄明白为什么不是的过程是这个项目中更有用的一课。

真正决定你是否需要一个 agent 的，不是流程有多少步——而是是否有某个步骤需要对模糊输入进行判断。从 PDF 提取文本每次都只有一种正确的方式。分块、嵌入和写入向量存储也是如此。这些都不需要 LLM 的推理能力——它们需要确定性的管道。真正的模糊性只出现在最前面：解释我在聊天框里输入的内容真正是什么意思。这就是整个 agentic 的表面积。之后的一切都是管道工作。

这个重新框架化改变了我对何时真正需要多 agent 设计的理解——不是"这有很多步骤"，而是"某个子任务是否需要与其他部分截然不同的判断类型或角色"。更多关于这个在 V2 中可能真正适用的地方会在下面提到。

教会我最多的调试故事

在这个过程中，一些事情出错了，最终教会了我比那些一次就成功的部分更多的东西。

悄悄吞掉我自己虚拟环境的索引。 我的排除逻辑检查的是字面上名为 venv 或 .venv 的文件夹——直到我找到一个名为 venv_rag 的，突然出现了数百个来自不相关项目的 site-packages 文件在我的搜索结果里。修复方法不是添加更多精确的名称检查；而是通过检查 pyvenv.cfg 的存在来结构性地检测虚拟环境，这样无论有人给它起什么名字都没关系。

"存储文件夹已被另一个实例访问"。 一旦我添加了独立于聊天 agent 运行的后台监察器，两者就开始偶尔在同一时刻尝试打开各自与同一个本地 Qdrant 数据库的连接——这对于单个顺序 agent 来说没问题，但一旦有两个独立的线程接触同一个嵌入式数据库就会崩溃。修复方法是使用共享的单例连接，而不是每次调用都创建一个新的。

不肯停止折腾的 agent。 我问了一个埋在 Word 文档里的表格，agent 对第一次搜索的结果不满意，开始调用不相关的工具——试图重新索引文件、试图在 Word 中物理地打开文档——在它们之间循环，而不是直接告诉我找不到。实际的根本原因一旦我用原始数据库查询深入挖掘，几乎有点滑稽：内容一直都在那里。它只是没有在该特定措辞的前 3 个搜索结果中排名。真正的修复是收紧系统 prompt，让 agent 停止并告诉我，而不是折腾；还有扩大它每次搜索拉取的结果数量。

一个答案在技术上看似不陈旧，但背后的推理被编造了。 问一个文件夹的内容，agent 给了我正确的文件计数，但用编造的解释说为什么它无法显示子文件夹——一个其实根本不存在的限制。这是个很好的提醒：技术上正确的答案仍然可能带有自信但错误的推理，值得两者都检查。

Windows Explorer 创建了一个"删除的"文件，它从未被索引过。 创建一个新的空白文本文件似乎触发了一条"已从索引移除"的消息，甚至在文件有内容之前。原来 Explorer 的文件创建流程在底层触发为一个重命名事件，我的删除处理器无条件地打印成功消息，无论是否有任何东西真正被删除。一个小 bug，但那种会损害一个工具日志可信度的 bug，如果你不捕捉它的话。

这些都不是奇异的问题。它们是真正构建某样东西而不是跟随教程的常见摩擦——这正是为什么拥有它们是值得的。

接下来（以及我想听你的想法的地方）

这是 V1。它能工作，我每天都用，但不是最终状态。我在考虑 V2 的几个方向，特别是我认为多个专业化 agent 真正能发挥价值、而不仅仅是增加复杂性的地方：

一个写作 agent，可以从文件 agent 检索的文档中草拟摘要或邮件——一个与"查找和打开文件"完全不同的技能和声音。

一个用于截图和扫描文档的 vision agent，如果对图像的推理需要真实的判断而不仅仅是单个 API 调用的话。

一个主动模式，可以注意到杂乱或重复文件并建议清理，而不是仅仅对我的询问做出反应。

将其打包为真正的独立 Windows 应用，这样就不需要后台开着终端窗口。

如果你构建过类似的东西，或有你真正想从个人文件助手那里得到的功能，我很想听听——留下评论或联系我。仍然很大程度上是在进行中，这也是重点所在。

GitHub:- https://github.com/IsaacNatarajan/My-Assistant/tree/main

关于后续行动，你可以考虑屏蔽此人和/或举报滥用