从零开始做一个 AI Agent以 Java Web RAG 学习助手为例本文是一套面向技术博客专栏的完整教程。它不是只讲概念而是以当前项目为真实案例从一个最小后端 API 出发逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。示例项目定位面向 Java Web 课程资料的 RAG Agent 学习助手用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引用户提交学习任务后Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用并把执行过程展示给前端。专栏总目录项目总览从普通问答到课程学习 Agent技术栈和工程结构FastAPI、Vue、SQLite、RAG、Agent Harness后端基础设施配置、数据库、模型和 Schema资料上传文件存储、文档记录和重建索引文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统文本切块chunk、metadata、语义类型和 embedding 状态检索系统关键词检索、向量检索、query rewrite 和 rerankLLM 与 Embedding Providerstub、OpenAI-compatible API 和本地模型接入Chat 问答入口兼容普通问答同时接入 Agent 主链路Agent Harness一次 Agent run 的生命周期Planner、Executor 与 Tool RegistryAgent 如何规划和调用工具Agent 校验、安全边界与资料不足处理Agent 记忆短期上下文、长期学习画像和推荐下一步前端工作台资料管理、Agent 任务、Trace、历史和健康状态测试、局限和演进从教学项目走向生产级 Agent SaaS第 5 篇文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统5.1 解析入口文件backend/app/services/parsers.py核心函数defparse_file(path:Path)-ParsedDocument:根据扩展名选择解析器.java / .xml / .properties / .yml / .sql / .html / .jsp / .js / .css - plain code .md / .txt - plain text .pdf - pypdf .docx - python-docx .pptx - python-pptx5.2 ParsedDocument 和 ParsedSection解析结果不是直接写字符串而是结构化对象dataclass(frozenTrue)classParsedSection:text:strcontent_type:strsource_path:strsource_page:int|NoneNonelanguage:str|NoneNonedataclass(frozenTrue)classParsedDocument:title:strsections:list[ParsedSection]这样做的好处是1. PDF / PPT 可以保留页码。 2. 代码文件可以保留 language。 3. chunk 阶段可以继承 source_path 和 source_page。 4. citation 可以回到具体来源。5.3 PDF 解析PDF 使用pypdf.PdfReader逐页读取 - page.extract_text() - 每页一个 ParsedSection - source_page 页码适合教材、讲义、实验指导书。5.4 DOCX 解析Word 使用python-docx读取 paragraphs - 过滤空段落 - 合并成文本 - 作为一个 ParsedSection5.5 PPTX 解析PPT 使用python-pptx遍历 slides - 遍历 shapes - 提取 shape.text - 每页幻灯片一个 ParsedSection5.6 代码和纯文本解析代码和文本统一走_parse_plain_file读取 UTF-8 文本 - content_type code 或 text - language java / xml / jsp / sql / ...这对于 Java Web 项目非常重要因为很多知识在代码和配置文件里而不是只在课件里。