好的，下面是去掉截图占位符的最终内容，可直接整段复制发帖。
【标签】学习工作
【标题】【学习工作赛道】Agentic RAG 智能知识库问答系统
【正文】
0. 先和大家打个招呼吧 
我是谁：一名对 AI 工程化感兴趣的独立开发者，最近在系统学习 LangGraph、DeepAgents、Agentic RAG 这套技术栈，想通过做一个真实可跑的项目把知识点真正吃透。
我是怎么用 TRAE 把 Demo 做出来的：
- 我不是单纯的"提需求、看结果"，而是把 TRAE 当成"结对编程的同事"——在每个阶段前先用 brainstorming 跟它一起澄清需求边界（比如"为什么要用父子块而不是直接用大块"），再把设计沉淀成 spec/plan 文档，让它按 TDD 节奏逐个功能推进
- 最让我惊喜的是 receiving-code-review 这个能力：完成一个阶段后，TRAE 会主动审查代码并给出"重要/建议"分级反馈，我用它的反馈修掉了一个流式中间事件丢失的 Bug 和一个 langfuse_handler 死代码问题——这种"自动 review"对独立开发者帮助巨大
- 踩过的坑：在阶段 5 真实跑系统时，遇到过 DashScope embedding API 实际 batch 限制是 10（文档写 20）导致索引失败的坑；本地 socket 端口冲突导致 rerank 并发调用失败。TRAE 不只是"答问题"，而是带着我一起调试、看日志、定位根因，最后改 indexer.py 的 batch_size 参数一次性解决
- 跨过的坎：LangGraph 的 Send API 并行派发 + interrupt_before 人在回路 + SqliteSaver 持久化这三件事单独看都不难，但组合起来形成"主图编排多 Agent 子图并行 + 用户澄清中断恢复"的完整链路——这个坎是 TRAE 一步步引导我走通的
1. Demo 简介
是什么：一个面向个人/团队的本地知识库智能问答 Web 应用（Gradio 网页）。用户把 PDF 文档扔进知识库后，系统会自动切分、向量化、混合检索、重排序，并通过多 Agent 子图并行回答复杂问题。
面向谁：
- 需要基于大量 PDF 资料（书籍、手册、论文）做快速问答的学习者与研究者
- 希望搭建"私有、可追溯、可解释"知识库的开发者
- 想学习 LangGraph / DeepAgents / RAG 工程化实现的工程师
主要功能：
-
PDF 知识库自动构建：PDF → Markdown → 父子块双层切分 → Qdrant 混合检索（dense 语义 + sparse 关键词）+ parent_store 父块回溯，索引一次即可反复检索。本项目索引了 3 个 PDF（125 parent blocks / 878 child blocks）。
-
多子问题并行 Agent 检索：用户提一个复合问题（如"Python 是什么？Java 是什么？“），主图用结构化输出拆成多个子问题，通过 Send API 并行派发到多个 Agent 子图，每个子图独立做"检索→重排→压缩→回答”，最后由 aggregate 节点合并答案。
-
查询澄清 + 中断恢复：模糊问题（如"那个东西怎么用？"）触发 interrupt_before 暂停执行，state 持久化到 SQLite（SqliteSaver），用户补充澄清后从断点恢复执行，不丢上下文。
2. Demo 创作思路
灵感来源：在学习 Claude Code、harness 工程等较新主题时，通用大模型经常给不出准确答案（训练截止后或理解偏差），而本地 PDF 资料又难以快速检索。我参考了 GiovanniPasq/agentic-rag-for-dummies 项目，想用一个真实可跑的系统把 Agentic RAG 的工程化细节彻底吃透。
想解决的问题：
- 传统 RAG 一问一答、不会自主决策：用户问复杂问题，普通 RAG 一次检索就回答，容易答非所问或信息不全
- 多轮对话上下文丢失：长会话里早期内容被截断，丢失指代和细节
- 检索结果鱼龙混杂：单纯向量召回精度有限，需要重排
- 模糊提问得不到引导：用户问题不清楚时，系统硬答反而误导，应当主动澄清
为什么做这个方向：
- Agentic RAG 是当前 LLM 应用落地的核心范式之一，"Agent 自主决定何时检索、检索什么、何时停止"比"固定检索-生成 pipeline"更接近真实助手
- 这个方向能完整覆盖 LangGraph 的关键能力：状态机、Send API 并行、Command 节点、interrupt 人在回路、checkpointer 持久化
- 选择本地部署（Qdrant 嵌入式 + SQLite）而非云端托管，兼顾隐私与可控，适合学习/研究场景
3. Demo 体验地址
作品形式：交互式可体验的 HTML 格式文件（Zip 压缩包）
附件：agentic_rag_demo.zip（14.6 KB，含 index.html / README.md / sample_qa.json）
体验步骤：
- 下载附件
agentic_rag_demo.zip - 解压到任意目录
- 双击解压后的
index.html，浏览器自动打开 - 点击"查看答案"按钮可展开真实系统运行产生的问答样例
- 完整本地部署（需 DashScope API key）步骤见 HTML 内"5. 本地部署与体验"章节
4. TRAE 实践过程
整个 Demo 完全在 TRAE IDE 中，通过"brainstorming → writing-plans → harness-creator → executing-plans → test-driven-development → git commit"的标准工作流完成，分 5 个阶段自底向上交付。
4.1 五个阶段的关键产出
| 阶段 | 主题 | 关键产出 | 测试数 |
|---|---|---|---|
| 1 | 数据层基础 | config + embedding 工厂 + PDF→MD + 父子块切分 + Qdrant 混合检索 + 端到端索引器 | 25 |
| 2 | 检索工具层 | search_child_chunks + retrieve_parent_chunks + gte-rerank-v2 重排序 | 11 |
| 3 | Agent 子图 | State/AgentState + 3 自定义 reducer + 7 节点子图（orchestrator→ToolNode→rerank→compress→fallback） | 23 |
| 4 | 主图编排 | rewrite_query 结构化输出 + Send API 并行派发 + interrupt_before 中断恢复 + DeepAgents 中间件 | 25 |
| 5 | UI + 可观测性 + 评估 | Gradio ChatInterface + Langfuse 回调 + RAGAS 4 指标离线评估 | 14 |
4.2 TRAE 开发关键步骤截图
4.3 关键任务对话 Session ID
以下为 TRAE 中真实开发会话的 Session ID，按开发时间顺序排列，可用于验证作品由 TRAE 完整开发：
-
Session ID:
6a486a413d4e921d532f8ded- 阶段：阶段 1（数据层基础）+ 阶段 2（检索工具层）
- 关键任务：搭建项目骨架、配置中心、embedding 工厂、父子块切分、Qdrant 混合检索封装、检索工具与 rerank 实现
-
Session ID:
6a4b04b323d42d122e28cb36- 阶段：阶段 3（Agent 子图）+ 阶段 4（主图编排）
- 关键任务：State/AgentState/QueryAnalysis 设计、3 自定义 reducer、7 节点 Agent 子图、Send API 并行派发、interrupt_before 中断恢复、DeepAgents 中间件装配
-
Session ID:
6a4caaed2f5cfbf7641b6c0c- 阶段：阶段 4 收尾 + 阶段 5（UI + 可观测性 + 评估）
- 关键任务：Langfuse 回调工厂、RAGAS 离线评估管道、Gradio ChatInterface 流式与中断恢复
-
Session ID:
6a4debc02447833aebed02ed- 阶段：真实文档索引 + 端到端联调 + 代码审查修复
- 关键任务：向 docs/pdfs/ 索引 3 个 PDF（125 parent / 878 child blocks）、修复 DashScope embedding batch_size=10 限制、调优 rerank top_k 与 prompt 以提升答案质量、处理代码审查反馈（流式中间事件映射、langfuse_handler 死代码清理）
5. 对应的报名审核通过的帖子链接
agentic_rag_demo.zip (14.6 KB)
