jaspersoft-agent-learn/LEARN_GUIDE.md

# 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://gitea.1415243231.top/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 -r requirements.txt
```

### 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 04: 记忆系统
cd ../step_04_memory
python main.py

# Step 05-07: 进阶（RAG / Self-Correction / Multi-Agent）
cd ../step_05_07_advanced
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+：仅标准库（如需 LLM 调用，见 `config.py` 加载 `.env`）
- 无需 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 主项目**: 同组织下的 `jaspersoft` 仓库 - LangGraph 实现参考
- **日报系统**: 同组织下的 `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 开始，循序渐进。每个模块都有练习题，推荐先自己思考，再看答案。