# mini-agent

**Repository Path**: liu_zy_developer/mini-agent

## Basic Information

- **Project Name**: mini-agent
- **Description**: 智能体学习项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 Mini Agent

一个从零开始构建 AI Agent 的学习项目，帮助你深入理解 Agent 的核心工作原理。

## 📖 项目简介

Mini Agent 是一个极简但完整的 AI Agent 实现，通过清晰的模块划分，逐步展示一个具备工具调用、对话记忆、持久化存储能力的 Agent 是如何运转的。

## 🏗️ 项目结构

```
mini-agent/
├── main.py       # CLI 入口，使用 typer 解析命令行参数
├── agent.py      # Agent 主循环（核心 loop 逻辑）
├── llm.py        # LLM 调用封装（OpenAI API）
├── tools.py      # 工具定义：schema 描述 + 工具注册表
├── prompt.py     # 系统提示词与消息组装
├── store.py      # SQLite 持久化（对话历史存储）
├── edit.py       # 文本编辑工具
├── exec.py       # 命令行执行工具
└── pyproject.toml
```

## 🧠 核心概念

| 模块 | 职责 |
|------|------|
| `agent.py` | Agent 主循环：接收任务 → 调用 LLM → 解析工具调用 → 执行工具 → 循环直到完成 |
| `llm.py` | 封装对 OpenAI Chat Completion API 的调用，统一处理请求与响应 |
| `tools.py` | 维护工具的 JSON Schema 描述（供 LLM 识别）及工具函数注册表 |
| `prompt.py` | 构建系统提示词，组装发送给 LLM 的消息列表 |
| `store.py` | 使用 SQLite 持久化对话历史，支持多轮记忆 |
| `edit.py` | 文本文件读写/编辑工具 |
| `exec.py` | Shell 命令执行工具 |

## ⚙️ 环境要求

- Python >= 3.11
- [uv](https://github.com/astral-sh/uv)（推荐包管理器）

## 🚀 快速开始

**1. 克隆项目**

```bash
git clone https://github.com/your-username/mini-agent.git
cd mini-agent
```

**2. 安装依赖**

```bash
uv sync
```

**3. 配置环境变量**

在项目根目录创建 `.env` 文件：

```env
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1   # 可选，使用代理时修改
```

**4. 运行 Agent**

```bash
# 方式一：通过 uv 运行
uv run python main.py "帮我查看当前目录下有哪些文件"

# 方式二：激活虚拟环境后运行
source .venv/bin/activate
python main.py "帮我查看当前目录下有哪些文件"
```

## 📦 依赖说明

| 依赖 | 用途 |
|------|------|
| `openai` | 调用 OpenAI / 兼容 API |
| `python-dotenv` | 从 `.env` 文件加载环境变量 |
| `rich` | 美化终端输出 |
| `typer` | 构建命令行界面 |

## 🔄 Agent 工作流程

```
用户输入任务
     │
     ▼
组装消息（system prompt + user message）
     │
     ▼
调用 LLM（携带 tools schema）
     │
     ▼
LLM 返回：普通回复 or 工具调用？
     │
  ┌──┴──┐
工具调用  普通回复
  │        │
执行工具  输出结果
  │        │
将结果追加  结束
到消息列表
  │
  └──► 回到调用 LLM（循环）
```

## 📚 学习路线

推荐按以下顺序阅读源码：

1. `main.py` — 了解项目入口与 CLI 结构
2. `agent.py` — 理解 Agent 主循环逻辑
3. `prompt.py` — 学习如何设计系统提示词
4. `llm.py` — 了解如何与 LLM 交互
5. `tools.py` — 理解工具注册机制
6. `exec.py` / `edit.py` — 具体工具的实现
7. `store.py` — 持久化与多轮对话记忆

## 📝 License

MIT