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. 环境准备

# 克隆项目
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. 配置环境变量

cp .env.example .env
# 编辑 .env，填入你的 API Key

3. 开始学习

# 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（工具）

# 工具的定义
class Tool:
    name: str          # 工具名称
    description: str   # 工具描述
    parameters: dict  # 参数定义
    execute: Callable # 执行函数

State（状态）

# 状态管理
state = {
    "messages": [...],    # 对话历史
    "context": {...},     # 上下文信息
    "memory": [...],     # 记忆
}

Agent（Agent）

# 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 练习

# 练习：创建一个计算器工具
# 1. 定义工具名称和描述
# 2. 实现加减乘除函数
# 3. 注册到工具注册表
# 4. 测试调用

def calculator_tool(operation: str, a: float, b: float) -> float:
    """计算器工具"""
    # 你的代码
    pass

Step 02 练习

# 练习：实现状态快照
# 1. 创建状态管理类
# 2. 实现状态保存/恢复
# 3. 添加状态版本追踪

class StateManager:
    def save_snapshot(self, state):
        # 你的代码
        pass

---

🎓 学习目标

完成本项目后，你将掌握：

• 理解 Tool 的定义和注册机制
• 掌握 State 的设计模式
• 能够构建简单的 Agent 循环
• 实现多级记忆系统
• 理解 RAG 架构
• 掌握 Self-Correction 模式
• 设计 Multi-Agent 协作系统

---

🔗 相关资源

内部项目

• JasperSoft 主项目: 同组织下的 jaspersoft 仓库 - LangGraph 实现参考
• 日报系统: 同组织下的 daily_on_work 仓库 - 自动化工作流

外部资源

• LangGraph 文档
• RAG 最佳实践
• OpenAI Function Calling

---

🤝 贡献指南

欢迎提交 PR！贡献方式：

1. 发现 bug？ → 提 Issue 或直接修
2. 添加练习？ → 在对应 Step 添加
3. 完善注释？ → 提 PR
4. 分享笔记？ → 在 Issue 区分享

---

📄 许可证

MIT License - 欢迎自由使用、修改和分发

---

开始学习吧！ 🚀

提示：建议从 Step 01 开始，循序渐进。每个模块都有练习题，推荐先自己思考，再看答案。