Add multi-platform learning guide and update README
This commit is contained in:
zy187
+282
@@ -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 开始，循序渐进。每个模块都有练习题，推荐先自己思考，再看答案。
|
||||||
@@ -1,124 +1,161 @@
|
|||||||
# Jaspersoft Learn - AI Agent 开发教学项目
|
# JasperSoft Agent Learn
|
||||||
|
|
||||||
> **目标**：手把手教你从零构建一个完整的 AI Agent 系统
|
> AI Agent 开发学习项目 | 从零到一掌握 Agent 核心概念
|
||||||
> **教学方式**：代码即文档，每一行代码都有详细解释
|
|
||||||
> **前置知识**：Python 基础（2年经验足够）
|
[](https://opensource.org/licenses/MIT)
|
||||||
|
[](https://www.python.org/)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 学习路径
|
## 🎯 这是什么？
|
||||||
|
|
||||||
本项目采用"渐进式构建"方式，从最简单的概念开始，逐步添加复杂度。
|
一个渐进式的 AI Agent 开发学习项目，通过 **7 个 Step** 带你从零掌握 AI Agent 的核心概念：
|
||||||
|
|
||||||
```
|
| Step | 主题 | 你将学会 |
|
||||||
学习顺序：
|
|------|------|---------|
|
||||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
| 01 | Tool 工具系统 | 如何定义和注册工具 |
|
||||||
|
| 02 | State 状态管理 | 如何管理 Agent 的状态 |
|
||||||
Step 01 ──▶ Step 02 ──▶ Step 03 ──▶ Step 04 ──▶ Step 05 ──▶ Step 06 ──▶ Step 07
|
| 03 | Simple Agent | 如何构建 Agent 循环 |
|
||||||
│ │ │ │ │ │ │
|
| 04 | Memory 记忆 | 如何让 Agent 记住对话 |
|
||||||
▼ ▼ ▼ ▼ ▼ ▼ ▼
|
| 05 | RAG 知识检索 | 如何让 Agent 查阅知识库 |
|
||||||
Tool基础 State状态 简单Agent Memory RAG检索 自我修正 Multi-Agent
|
| 06 | Self-Correction | 如何让 Agent 自我修正 |
|
||||||
管理 记忆系统
|
| 07 | Multi-Agent | 如何构建多 Agent 协作 |
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📚 每个 Step 的内容
|
## 📚 学习大纲
|
||||||
|
|
||||||
| Step | 主题 | 核心概念 | 完成后你将理解 |
|
### 第 1 周：基础（Step 01-03）
|
||||||
|------|------|---------|--------------|
|
- Day 1-2: 理解 Tool 系统
|
||||||
| **01** | Tool 工具系统 | 什么是 Tool，为什么需要 Tool | 如何设计可扩展的工具系统 |
|
- Day 3-4: 掌握 State 管理
|
||||||
| **02** | State 状态管理 | 什么是 Agent State | 如何在 Agent 中传递信息 |
|
- Day 5-7: 构建简单 Agent
|
||||||
| **03** | 简单 Agent | LLM + Tool + Loop = Agent | Agent 的核心工作原理 |
|
|
||||||
| **04** | Memory 记忆 | 短期/长期/工作记忆 | 如何让 Agent "记住"上下文 |
|
### 第 2 周：进阶（Step 04-07）
|
||||||
| **05** | RAG 知识检索 | 检索增强生成 | 如何让 Agent 知道"私有知识" |
|
- Day 8-9: 多级记忆系统
|
||||||
| **06** | Self-Correction | 自我修正循环 | 如何让 Agent 自动修复错误 |
|
- Day 10-11: RAG 与知识增强
|
||||||
| **07** | Multi-Agent | 多 Agent 协作 | 如何构建 Agent 团队 |
|
- Day 12-13: 自我修正模式
|
||||||
|
- Day 14: 多 Agent 协作
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 快速开始
|
## 🚀 快速开始
|
||||||
|
|
||||||
### 环境准备
|
### 1. 克隆项目
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 创建虚拟环境
|
git clone https://www.1415243231.top/gitea/panda/jaspersoft-agent-learn.git
|
||||||
python -m venv venv
|
cd jaspersoft-agent-learn
|
||||||
.\venv\Scripts\activate
|
|
||||||
|
|
||||||
# 2. 安装依赖
|
|
||||||
pip install langchain langchain-openai langchain-anthropic python-dotenv
|
|
||||||
|
|
||||||
# 3. 配置环境变量
|
|
||||||
cp .env.example .env
|
|
||||||
# 编辑 .env，填入你的 API Key
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 开始学习
|
### 2. 安装依赖
|
||||||
|
```bash
|
||||||
|
python -m venv venv
|
||||||
|
source venv/bin/activate # Linux/Mac
|
||||||
|
.\venv\Scripts\activate # Windows
|
||||||
|
pip install python-dotenv
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 开始学习
|
||||||
```bash
|
```bash
|
||||||
# Step 01: 理解 Tool
|
|
||||||
cd step_01_tools
|
cd step_01_tools
|
||||||
python main.py
|
python main.py
|
||||||
|
|
||||||
# Step 02: 理解 State
|
|
||||||
cd ../step_02_state
|
|
||||||
python main.py
|
|
||||||
|
|
||||||
# ...以此类推
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📖 学习方法
|
## 📖 学习方法
|
||||||
|
|
||||||
### 每一步的结构
|
每个 Step 都包含：
|
||||||
|
|
||||||
```
|
```
|
||||||
step_XX_xxx/
|
step_XX_name/
|
||||||
├── README.md # 本步骤的概念讲解
|
├── README.md # 理论 + 架构图（先读）
|
||||||
├── concept.py # 核心概念代码（有详细注释）
|
├── concept.py # 详细注释代码（再看）
|
||||||
├── exercise.py # 练习题
|
├── exercise.py # 练习题（自己做）
|
||||||
├── exercise_answer.py # 练习答案（先自己思考再看）
|
├── exercise_answer.py # 参考答案（对照）
|
||||||
└── main.py # 可运行的示例
|
└── main.py # 运行演示
|
||||||
```
|
```
|
||||||
|
|
||||||
### 如何使用本项目
|
---
|
||||||
|
|
||||||
1. **先读 README**：理解这个 Step 要学什么
|
## 💡 核心概念预览
|
||||||
2. **再看 concept.py**：跟着代码理解概念
|
|
||||||
3. **做 exercise.py**：巩固理解
|
### Tool（工具）
|
||||||
4. **对照答案**：检查自己的理解
|
```python
|
||||||
5. **运行 main.py**：看完整示例
|
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 的核心工作原理
|
- ✅ 理解 Tool 的定义和注册机制
|
||||||
- [ ] 设计可扩展的工具系统
|
- ✅ 掌握 State 的设计模式
|
||||||
- [ ] 实现状态管理和记忆系统
|
- ✅ 能够构建简单的 Agent 循环
|
||||||
- [ ] 构建完整的 RAG 知识检索
|
- ✅ 实现多级记忆系统
|
||||||
- [ ] 实现 Agent 自我修正能力
|
- ✅ 理解 RAG 架构
|
||||||
- [ ] 设计多 Agent 协作系统
|
- ✅ 掌握 Self-Correction 模式
|
||||||
- [ ] 阅读并理解 jaspersoft 项目的源码
|
- ✅ 设计 Multi-Agent 协作系统
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔗 参考资料
|
## 📝 项目结构
|
||||||
|
|
||||||
- [LangGraph 官方文档](https://langchain-ai.github.io/langgraph/)
|
```
|
||||||
- [LangChain Tool Calling](https://python.langchain.com/docs/how_to/tool_calling/)
|
jaspersoft-agent-learn/
|
||||||
- [Prompt Engineering Guide](https://www.promptingguide.ai/zh)
|
├── 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 学习之旅吧！** 🚀
|
||||||
|
|||||||
Reference in New Issue
Block a user