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 开始，循序渐进。每个模块都有练习题，推荐先自己思考，再看答案。
|
||||
Reference in New Issue
Block a user