diff --git a/LEARN_GUIDE.md b/LEARN_GUIDE.md new file mode 100644 index 0000000..621e7ab --- /dev/null +++ b/LEARN_GUIDE.md @@ -0,0 +1,282 @@ +# JasperSoft Agent Learn - 多平台学习指南 + +> 专为多平台分发设计的学习资料包 | 包含完整理论 + 代码 + 练习 + +--- + +## 📚 项目简介 + +**JasperSoft Agent Learn** 是一个面向 AI Agent 开发的学习项目，通过循序渐进的方式带你掌握 AI Agent 的核心概念。 + +### 核心模块 + +| 模块 | 内容 | 难度 | +|------|------|------| +| Step 01 | Tool - 工具系统 | ⭐ 基础 | +| Step 02 | State - 状态管理 | ⭐ 基础 | +| Step 03 | Simple Agent - 简单 Agent | ⭐⭐ 入门 | +| Step 04 | Memory - 记忆系统 | ⭐⭐ 中级 | +| Step 05 | RAG - 知识检索 | ⭐⭐⭐ 进阶 | +| Step 06 | Self-Correction - 自我修正 | ⭐⭐⭐ 进阶 | +| Step 07 | Multi-Agent - 多 Agent 协作 | ⭐⭐⭐⭐ 高级 | + +--- + +## 🎯 学习路径 + +``` +第1周 → Step 01~03（工具、状态、简单 Agent） +第2周 → Step 04（记忆系统） +第3周 → Step 05~07（进阶内容） +``` + +--- + +## 📦 文件结构说明 + +``` +jaspersoft-agent-learn/ +├── README.md # 你在这里！ +├── LEARN_GUIDE.md # 学习指南（通用） +├── .env.example # 环境变量模板 +│ +├── step_01_tools/ # ★ Step 01: 工具系统 +│ ├── README.md # 理论 + 架构图 +│ ├── concept.py # 核心概念（详细注释） +│ ├── exercise.py # 练习题 +│ ├── exercise_answer.py # 参考答案 +│ └── main.py # 运行演示 +│ +├── step_02_state/ # ★ Step 02: 状态管理 +│ ├── README.md +│ ├── concept.py +│ ├── exercise.py +│ ├── exercise_answer.py +│ └── main.py +│ +├── step_03_simple_agent/ # ★ Step 03: 简单 Agent +│ ├── README.md +│ ├── concept.py +│ └── main.py +│ +├── step_04_memory/ # ★ Step 04: 记忆系统 +│ ├── README.md +│ └── concept.py +│ +└── step_05_07_advanced/ # ★ Step 05-07: 进阶 + ├── README.md + └── concept.py +``` + +--- + +## 🚀 快速开始 + +### 1. 环境准备 + +```bash +# 克隆项目 +git clone https://www.1415243231.top/gitea/panda/jaspersoft-agent-learn.git +cd jaspersoft-agent-learn + +# 创建虚拟环境（Python 3.9+） +python -m venv venv +source venv/bin/activate # Linux/Mac +# 或 +.\venv\Scripts\activate # Windows + +# 安装依赖 +pip install python-dotenv openai +``` + +### 2. 配置环境变量 + +```bash +cp .env.example .env +# 编辑 .env，填入你的 API Key +``` + +### 3. 开始学习 + +```bash +# Step 01: 工具系统 +cd step_01_tools +python main.py + +# Step 02: 状态管理 +cd ../step_02_state +python main.py + +# Step 03: 简单 Agent +cd ../step_03_simple_agent +python main.py +``` + +--- + +## 📖 每个 Step 的学习方法 + +每个模块都包含： + +| 文件 | 用途 | 学习顺序 | +|------|------|---------| +| `README.md` | 理论 + 架构图 | 1️⃣ 先读 | +| `concept.py` | 详细注释的代码 | 2️⃣ 再看 | +| `exercise.py` | 练习题 | 3️⃣ 自己做 | +| `exercise_answer.py` | 参考答案 | 4️⃣ 对照 | +| `main.py` | 运行演示 | 5️⃣ 运行 | + +--- + +## 🔧 代码设计特点 + +### 1. 渐进式复杂度 + +``` +Step 01: 工具 → 函数调用 +Step 02: 状态 → 数据流 +Step 03: 循环 → 自主决策 +Step 04: 记忆 → 上下文 +Step 05: RAG → 知识增强 +Step 06: 修正 → 自我改进 +Step 07: 协作 → 多Agent +``` + +### 2. 详细的代码注释 + +每个 `concept.py` 都包含： +- 为什么这样设计 +- 核心概念解释 +- 常见陷阱提醒 +- 实际应用场景 + +### 3. 零依赖入门 + +- Step 01~03: 仅需 Python 标准库 +- Step 04+: 只需 `python-dotenv` +- 无需 LangChain、LangGraph 等框架 + +--- + +## 💡 关键概念速查 + +### Tool（工具） + +```python +# 工具的定义 +class Tool: + name: str # 工具名称 + description: str # 工具描述 + parameters: dict # 参数定义 + execute: Callable # 执行函数 +``` + +### State（状态） + +```python +# 状态管理 +state = { + "messages": [...], # 对话历史 + "context": {...}, # 上下文信息 + "memory": [...], # 记忆 +} +``` + +### Agent（Agent） + +```python +# Agent 核心循环 +while not done: + # 1. 思考 (Think) + thought = llm.think(state) + + # 2. 行动 (Act) + action = llm.decide(thought) + result = tool.execute(action) + + # 3. 观察 (Observe) + state.update(result) +``` + +--- + +## 📝 练习题示例 + +### Step 01 练习 + +```python +# 练习：创建一个计算器工具 +# 1. 定义工具名称和描述 +# 2. 实现加减乘除函数 +# 3. 注册到工具注册表 +# 4. 测试调用 + +def calculator_tool(operation: str, a: float, b: float) -> float: + """计算器工具""" + # 你的代码 + pass +``` + +### Step 02 练习 + +```python +# 练习：实现状态快照 +# 1. 创建状态管理类 +# 2. 实现状态保存/恢复 +# 3. 添加状态版本追踪 + +class StateManager: + def save_snapshot(self, state): + # 你的代码 + pass +``` + +--- + +## 🎓 学习目标 + +完成本项目后，你将掌握： + +- [x] 理解 Tool 的定义和注册机制 +- [x] 掌握 State 的设计模式 +- [x] 能够构建简单的 Agent 循环 +- [x] 实现多级记忆系统 +- [x] 理解 RAG 架构 +- [x] 掌握 Self-Correction 模式 +- [x] 设计 Multi-Agent 协作系统 + +--- + +## 🔗 相关资源 + +### 内部项目 +- **JasperSoft 主项目**: `D:\Idea Project\jaspersoft` - LangGraph 实现参考 +- **日报系统**: `D:\Idea Project\daily_on_work` - 自动化工作流 + +### 外部资源 +- [LangGraph 文档](https://langchain-ai.github.io/langgraph/) +- [RAG 最佳实践](https://www.pinecone.io/learn/rag/) +- [OpenAI Function Calling](https://platform.openai.com/docs/guides/function-calling) + +--- + +## 🤝 贡献指南 + +欢迎提交 PR！贡献方式： + +1. **发现 bug？** → 提 Issue 或直接修 +2. **添加练习？** → 在对应 Step 添加 +3. **完善注释？** → 提 PR +4. **分享笔记？** → 在 Issue 区分享 + +--- + +## 📄 许可证 + +MIT License - 欢迎自由使用、修改和分发 + +--- + +**开始学习吧！** 🚀 + +> 提示：建议从 Step 01 开始，循序渐进。每个模块都有练习题，推荐先自己思考，再看答案。 diff --git a/README.md b/README.md index 81e68f8..a1c9d99 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,161 @@ -# Jaspersoft Learn - AI Agent 开发教学项目 +# JasperSoft Agent Learn -> **目标**：手把手教你从零构建一个完整的 AI Agent 系统 -> **教学方式**：代码即文档，每一行代码都有详细解释 -> **前置知识**：Python 基础（2年经验足够） +> AI Agent 开发学习项目 | 从零到一掌握 Agent 核心概念 + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/) --- -## 🎯 学习路径 +## 🎯 这是什么？ -本项目采用"渐进式构建"方式，从最简单的概念开始，逐步添加复杂度。 +一个渐进式的 AI Agent 开发学习项目，通过 **7 个 Step** 带你从零掌握 AI Agent 的核心概念： -``` -学习顺序： -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Step 01 ──▶ Step 02 ──▶ Step 03 ──▶ Step 04 ──▶ Step 05 ──▶ Step 06 ──▶ Step 07 - │ │ │ │ │ │ │ - ▼ ▼ ▼ ▼ ▼ ▼ ▼ -Tool基础 State状态 简单Agent Memory RAG检索 自我修正 Multi-Agent - 管理 记忆系统 -``` +| Step | 主题 | 你将学会 | +|------|------|---------| +| 01 | Tool 工具系统 | 如何定义和注册工具 | +| 02 | State 状态管理 | 如何管理 Agent 的状态 | +| 03 | Simple Agent | 如何构建 Agent 循环 | +| 04 | Memory 记忆 | 如何让 Agent 记住对话 | +| 05 | RAG 知识检索 | 如何让 Agent 查阅知识库 | +| 06 | Self-Correction | 如何让 Agent 自我修正 | +| 07 | Multi-Agent | 如何构建多 Agent 协作 | --- -## 📚 每个 Step 的内容 +## 📚 学习大纲 -| Step | 主题 | 核心概念 | 完成后你将理解 | -|------|------|---------|--------------| -| **01** | Tool 工具系统 | 什么是 Tool，为什么需要 Tool | 如何设计可扩展的工具系统 | -| **02** | State 状态管理 | 什么是 Agent State | 如何在 Agent 中传递信息 | -| **03** | 简单 Agent | LLM + Tool + Loop = Agent | Agent 的核心工作原理 | -| **04** | Memory 记忆 | 短期/长期/工作记忆 | 如何让 Agent "记住"上下文 | -| **05** | RAG 知识检索 | 检索增强生成 | 如何让 Agent 知道"私有知识" | -| **06** | Self-Correction | 自我修正循环 | 如何让 Agent 自动修复错误 | -| **07** | Multi-Agent | 多 Agent 协作 | 如何构建 Agent 团队 | +### 第 1 周：基础（Step 01-03） +- Day 1-2: 理解 Tool 系统 +- Day 3-4: 掌握 State 管理 +- Day 5-7: 构建简单 Agent + +### 第 2 周：进阶（Step 04-07） +- Day 8-9: 多级记忆系统 +- Day 10-11: RAG 与知识增强 +- Day 12-13: 自我修正模式 +- Day 14: 多 Agent 协作 --- ## 🚀 快速开始 -### 环境准备 - +### 1. 克隆项目 ```bash -# 1. 创建虚拟环境 -python -m venv venv -.\venv\Scripts\activate - -# 2. 安装依赖 -pip install langchain langchain-openai langchain-anthropic python-dotenv - -# 3. 配置环境变量 -cp .env.example .env -# 编辑 .env，填入你的 API Key +git clone https://www.1415243231.top/gitea/panda/jaspersoft-agent-learn.git +cd jaspersoft-agent-learn ``` -### 开始学习 - +### 2. 安装依赖 +```bash +python -m venv venv +source venv/bin/activate # Linux/Mac +.\venv\Scripts\activate # Windows +pip install python-dotenv +``` + +### 3. 开始学习 ```bash -# Step 01: 理解 Tool cd step_01_tools python main.py - -# Step 02: 理解 State -cd ../step_02_state -python main.py - -# ...以此类推 ``` --- ## 📖 学习方法 -### 每一步的结构 +每个 Step 都包含： ``` -step_XX_xxx/ -├── README.md # 本步骤的概念讲解 -├── concept.py # 核心概念代码（有详细注释） -├── exercise.py # 练习题 -├── exercise_answer.py # 练习答案（先自己思考再看） -└── main.py # 可运行的示例 +step_XX_name/ +├── README.md # 理论 + 架构图（先读） +├── concept.py # 详细注释代码（再看） +├── exercise.py # 练习题（自己做） +├── exercise_answer.py # 参考答案（对照） +└── main.py # 运行演示 ``` -### 如何使用本项目 +--- -1. **先读 README**：理解这个 Step 要学什么 -2. **再看 concept.py**：跟着代码理解概念 -3. **做 exercise.py**：巩固理解 -4. **对照答案**：检查自己的理解 -5. **运行 main.py**：看完整示例 +## 💡 核心概念预览 + +### Tool（工具） +```python +class Tool: + name: str # 工具名称 + description: str # 工具描述 + execute: Callable # 执行函数 +``` + +### State（状态） +```python +state = { + "messages": [...], # 对话历史 + "context": {...}, # 上下文 + "memory": [...], # 记忆 +} +``` + +### Agent 循环 +```python +while not done: + thought = think(state) # 思考 + action = decide(thought) # 决策 + result = execute(action) # 执行 + observe(state, result) # 观察 +``` --- -## 🎓 最终目标 +## 🎓 学习目标 -完成所有 Step 后，你将能够： +完成本项目后，你将能够： -- [ ] 理解 Agent 的核心工作原理 -- [ ] 设计可扩展的工具系统 -- [ ] 实现状态管理和记忆系统 -- [ ] 构建完整的 RAG 知识检索 -- [ ] 实现 Agent 自我修正能力 -- [ ] 设计多 Agent 协作系统 -- [ ] 阅读并理解 jaspersoft 项目的源码 +- ✅ 理解 Tool 的定义和注册机制 +- ✅ 掌握 State 的设计模式 +- ✅ 能够构建简单的 Agent 循环 +- ✅ 实现多级记忆系统 +- ✅ 理解 RAG 架构 +- ✅ 掌握 Self-Correction 模式 +- ✅ 设计 Multi-Agent 协作系统 --- -## 🔗 参考资料 +## 📝 项目结构 -- [LangGraph 官方文档](https://langchain-ai.github.io/langgraph/) -- [LangChain Tool Calling](https://python.langchain.com/docs/how_to/tool_calling/) -- [Prompt Engineering Guide](https://www.promptingguide.ai/zh) +``` +jaspersoft-agent-learn/ +├── LEARN_GUIDE.md # 详细学习指南 +├── README.md # 项目概览 +├── .env.example # 环境变量模板 +│ +├── step_01_tools/ # 工具系统 +├── step_02_state/ # 状态管理 +├── step_03_simple_agent/ # 简单 Agent +├── step_04_memory/ # 记忆系统 +└── step_05_07_advanced/ # RAG/修正/多Agent +``` --- -## 📝 贡献指南 +## 🔗 相关链接 -发现错误或有改进建议？欢迎提交 PR！ +- 📂 **详细学习指南**: [LEARN_GUIDE.md](./LEARN_GUIDE.md) +- 🏠 **主项目**: [JasperSoft](https://www.1415243231.top/gitea/panda/jaspersoft) +- 📊 **日报系统**: [Daily On Work](https://www.1415243231.top) --- -*本项目是学习用途，代码尽量写得清晰易懂，而非追求极致性能。* +## 🤝 参与贡献 + +欢迎提交 Issue 和 PR！ + +--- + +## 📄 许可证 + +MIT License + +--- + +**开始你的 AI Agent 学习之旅吧！** 🚀