文章目录一、开篇：你的企业知识，还在靠"问人"吗？二、功能全景图三、系统架构总览四、项目结构与依赖五、核心模块一：RAG 检索引擎5.1 RAG 核心运行流程图5.2 文档加载：编码容错是个容易踩的坑5.3 递归切分：为什么用 RecursiveCharacterTextSplitter？5.4 Embedding 多 Provider 适配：零配置也能跑5.5 向量库单例：避免重复加载模型5.6 元数据设计：source + page + file_md55.7 按文档删除：Chroma API 的坑5.8 检索结果格式化：来源可追溯六、核心模块二：Agent 自主决策6.1 Agent 决策时序图6.2 System Prompt：7 条规则约束 Agent 行为6.3 多轮对话记忆：LangGraph checkpointer6.4 create_agent 的版本兼容6.5 流式事件捕获：astream_events v2七、核心模块三：安全计算器——为什么不能用 eval？7.1 AST 白名单方案7.2 测试验证八、核心模块四：SSE 流式输出与前端8.1 后端 SSE 实现8.2 前端 SSE 解析8.3 前端界面设计九、模块架构图十、配置中心：pydantic-settings 的优雅之处十一、API 接口设计11.1 文档上传的健壮性处理11.2 删除的事务性设计十二、关键参数调优指南十三、冒烟测试：无需 API Key 也能验证核心逻辑十四、安全设计总结十五、快速启动三步曲市面上 RAG 教程很多，但大多停留在"调个 LangChain 接口跑通 demo"的层面。这个项目的价值在于工程化细节：Agent + RAG 真正融合：不是简单的 RAG 问答，而是让 Agent 自主决策何时查知识库、何时联网、何时计算，这才是真实企业场景的需求；多轮对话记忆：LangGraph checkpointer + thread_id 隔离，生产可用的会话管理；流式输出完整方案：后端 SSE + 前端 fetch 流解析，包括 buffer 拼接这种容易踩坑的细节；安全计算器：AST 白名单方案，附带注入阻断测试，这是很多教程忽略的安全红线；工程化健壮性：编码容错、版本兼容、单例模式、删除事务性、上传多层校验——这些都是 demo 和生产系统的差距；零配置上手：Embedding 支持本地默认模型，只需一个 LLM Key 就能跑通全流程。读完这篇文章，你不仅理解了 RAG+Agent 的原理，更掌握了把它做成可部署、可维护、可扩展的企业级系统的全部关键细节。一、开篇：你的企业知识，还在靠"问人"吗？每个公司都有一堆文档：员工手册、报销制度、产品说明、项