多工具Agent、RAG基础与环境搭建

本周的学习重点围绕两个方向展开：一是完成了第七周的多工具协同与规划任务，并进入了第八周的流式思考链优化；二是正式启动了RAG（检索增强生成）的系统学习，搭建了知识库和环境，为后续将RAG集成到Agent中打下基础。

---

一、多工具Agent与规划（第七周收尾）

1.1 复杂任务测试

设计了三组需要多个工具协同才能完成的复杂任务，验证Agent的规划能力：

测试用例	Agent行为链路	验证结论
“搜索上海天气 → 写穿衣建议脚本”	先搜索 → 再生成代码 → 整合结果	工具选择正确，调用顺序合理
“搜索Python 3.12新特性 → 演示 → 执行”	搜索 → 识别PEP 701 → 生成对比代码 → 执行验证	搜索质量高，错误处理合理
“审查 public int health; → 验证优化方案性能”	审查 → 生成优化方案 → 尝试执行性能对比	审查专业，任务分解合理

测试发现Agent能正确按照"先搜索信息，再生成代码，最后执行验证"的顺序操作，具备基本的多步规划能力。

1.2 工具描述优化

基于LangChain官方文档和社区最佳实践，系统学习了5个工具设计模式：

模式	核心思想	应用
类型约束参数	用Literal + args_schema硬约束参数，避免LLM传错值	search_web、execute_python_code
Pydantic模型定义输入	用BaseModel精确描述每个参数的含义和示例	所有工具
结构化错误返回	返回status + error_type + suggestion，让Agent知道如何恢复	execute_python_code区分超时/语法/网络错误
幂等性	相同输入多次调用不产生副作用，用哈希缓存实现	execute_python_code 10秒幂等保护
返回下一步操作提示	在响应中包含available_actions，引导Agent选择后续工具	后续可扩展

同时掌握了@tool装饰器的进阶参数：

参数	作用
parse_docstring=True	自动解析Google风格docstring，生成精确的参数Schema
args_schema=PydanticModel	硬约束参数类型和取值范围
return_direct=True	工具返回后直接结束推理（适用于查询型工具）

1.3 封装 /agent/multi 接口

新增了POST /agent/multi接口，作为多工具协同的统一入口。创建了MULTI_AGENT_SYSTEM_PROMPT专用提示词，明确列出4个工具（时间、计算器、代码执行、搜索）的使用场景和处理规则。Agent能根据用户输入自主决定调用哪些工具、以什么顺序调用。

踩坑：接口调用时报Empty input messages错误，排查发现是agent_graph.ainvoke()传入的键名写成了"message"（单数），而LangGraph要求"messages"（复数）。修正后恢复正常。

---

二、流式思考链优化（第八周开端）

为了让用户更直观地感知Agent的思考状态，对流式输出进行了体验优化：

• 后端：在/agent/memory/stream的stream_events生成器中增加了thinking_start事件，在Agent开始推理时向前端推送"正在分析你的问题…"的状态提示。
• 前端：在sendStreamChatMessage函数中新增对thinking_start事件的处理，让消息气泡在收到第一个token之前先显示思考状态，收到文本后再逐字替换为实际内容。

这一优化解决了之前用户发送消息后只能干等"思考中"占位符、无法区分网络延迟和Agent正在推理的问题。

---

三、RAG系统学习（第一阶段起步）

本周正式启动了RAG（检索增强生成）的系统学习，目标是让Agent具备从知识库中检索相关信息的能力，让代码审查建议更有依据。

3.1 理解RAG全链路

RAG的核心是"离线准备 + 在线查询"两大环节：

环节	核心任务
离线准备	加载文档 → 分割成块 → 向量化 → 存入数据库
在线查询	用户提问 → 检索相关块 → 拼接上下文 → LLM生成答案

为什么不能直接把整篇文档喂给LLM？

• LLM有上下文长度限制
• 无关信息会干扰LLM的注意力
• 每次传整本书Token消耗巨大

3.2 环境搭建与知识库准备

安装了RAG所需的核心依赖：langchain、chromadb、sentence-transformers。在AI-Agent-Dev项目总目录下创建了knowledge_base文件夹，准备了一份unity_csharp_guidelines.md知识库文档，包含公共字段vs属性、命名规范、性能优化、空值检查等核心编码规范。

3.3 项目结构整理

将unity-code-review-agent、ai-agent-notes和knowledge_base三个子目录统一收纳到AI-Agent-Dev总目录下，并迁移到ai_study根目录，形成了清晰的项目结构。同时为AI-Agent-Dev创建了独立的虚拟环境，三个子目录共享。

---

四、GitHub运营与学习笔记仓库

完善了ai-agent-notes学习笔记仓库，填充了第4周至第7周的完整笔记内容，包括Memory、Prompt工程、代码执行、多工具协同等核心主题。每个周文件夹下包含notes.md（学习笔记）和专题文档（如Few-shot设计指南、安全沙箱设计思路、工具设计模式总结等）。同时美化了两大仓库的README，加入了技术栈徽章和项目结构展示。

---

五、下周计划

1. 继续RAG学习：完成文档分割与向量化存储（第2天），跑通第一个完整的检索问答流程（第3-4天）。
2. 深入学习混合检索与Rerank：理解BM25+向量检索的混合策略，以及Rerank的"粗筛→精排"两阶段检索。
3. RAG与Agent集成：将RAG检索能力封装为Agent的第5个工具，实现审查代码时自动检索规范文档。

---

六、本周核心收获