# tiny-ai-app

**Repository Path**: tjccc/tiny-ai-app

## Basic Information

- **Project Name**: tiny-ai-app
- **Description**: 从零实现agent教程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## AgentCli 简单 AI 客户端

本项目包含一个基于 Python 的极简 AI 客户端 `AgentCli`，封装了与大语言模型的交互。

- **init**: 建立连接 / 完成客户端初始化
- **think**: 调用大模型进行“思考”，并返回回答文本

目前默认对接智谱 AI 的 `zai-sdk`（`ZhipuAiClient`），也可以通过依赖注入传入自定义 client。

---

### 1. 项目结构与规范

项目采用标准的 `src / tests` 布局，便于安装和测试：

```text
tiny-ai-app/
├── pyproject.toml         # 项目元数据与依赖（PEP 621）
├── requirements.txt       # 便捷安装依赖的清单
├── src/
│   └── agentcli/
│       ├── __init__.py    # 对外导出 AgentCli, ChatMessage
│       └── core.py        # AgentCli 具体实现
├── tests/
│   └── test_agent_cli.py  # 单元测试
└── run_agent.py           # 调用示例脚本
```

核心代码都在 `src/agentcli` 下，测试统一放在 `tests/` 中，方便后续打包发布或集成到 CI。

---

### 2. 环境准备

推荐在虚拟环境中安装依赖（避免污染系统 Python）：

```bash
cd tiny-ai-app
python3 -m venv .venv
source .venv/bin/activate

# 方式一：使用 requirements.txt
pip install -r requirements.txt

# 或方式二：通过 pyproject.toml 安装（开发模式）
pip install -e .[dev]
```

请在运行前配置环境变量中的 API Key（以 Linux/macOS 为例）：

```bash
export ZHIPU_API_KEY="你的真实智谱 API Key"
```

---

### 3. 核心类说明

核心类定义在 `src/agentcli/core.py` 中，并通过包入口 `agentcli/__init__.py` 暴露：

- `AgentCli`: AI 客户端主类
- `ChatMessage`: 用于多轮对话的简单消息数据结构

使用方式：

```python
from agentcli import AgentCli, ChatMessage

agent = AgentCli(api_key="your-api-key")
agent.init()
result = agent.think(prompt="你的问题")
```

---

### 4. 运行调用示例

项目中已经提供了示例脚本 `run_agent.py`，可直接运行：

```bash
export ZHIPU_API_KEY="你的真实智谱 API Key"
python run_agent.py
```

你也可以参考其中代码，将 `AgentCli` 集成到自己的应用中。

---

### 5. 运行测试用例

本项目使用 `pytest` 编写了单元测试，覆盖了：

- `init` 的错误参数场景与正常初始化
- `think` 的错误调用（未初始化）与正常请求发送

在已安装 `pytest` 的前提下，在项目根目录执行：

```bash
pytest -q
```

测试中使用了一个 `FakeClient`，不依赖真实网络请求，也不需要实际安装 `zai-sdk`，便于在本地或 CI 环境快速验证逻辑。