ZipAgent: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

LiteAgent 是一个轻量级的 AI Agent 框架，设计简洁且易于扩展。项目采用模块化架构，每个模块职责单一明确。

核心架构

模块结构

• agent.py: Agent 核心类，管理代理配置、指令和工具集
• context.py: 对话上下文管理，维护消息历史和 token 统计
• model.py: LLM 接口抽象层，基于 OpenAI 客户端
• runner.py: 执行引擎，处理工具调用循环和对话流程
• tool.py: 工具系统，支持函数装饰器自动转换

设计模式

• 策略模式：Model 抽象基类支持不同 LLM 实现
• 装饰器模式：@function_tool 简化工具创建
• 数据类：广泛使用 @dataclass 减少样板代码

开发环境设置

使用 uv 原生管理（推荐）

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone https://github.com/JiayuXu0/LiteAgent.git
cd LiteAgent

# uv 会自动创建虚拟环境并管理依赖
# 添加核心依赖
uv add openai pydantic

# 添加开发依赖
uv add --dev pyright ruff pytest pytest-cov pytest-asyncio

# 添加可选依赖
uv add python-dotenv

验证安装

# 检查依赖状态
uv tree

# 检查虚拟环境
uv run python --version
uv run python -c "import liteagent; print('✅ 安装成功')"

环境变量配置

# 创建 .env 文件
MODEL=gpt-3.5-turbo  # 或其他支持的模型
API_KEY=your_api_key
BASE_URL=https://api.openai.com/v1  # 可选

常用开发命令

构建和打包

# 使用 uv 构建
uv build

# 构建后的文件在 dist/ 目录
# - liteagent-0.1.0-py3-none-any.whl  # wheel 包
# - liteagent-0.1.0.tar.gz             # 源码包

# 安装构建的 wheel 包
pip install dist/liteagent-0.1.0-py3-none-any.whl

类型检查

# 使用 uv run 运行 pyright
uv run pyright

# 检查特定目录
uv run pyright src/

# 检查特定文件
uv run pyright src/liteagent/agent.py

代码风格检查

# 运行 ruff 代码检查
uv run ruff check .

# 自动修复可修复的问题
uv run ruff check --fix .

# 格式化代码
uv run ruff format .

# 检查特定文件
uv run ruff check src/liteagent/

运行测试

# 运行所有测试
uv run pytest

# 运行特定测试文件
uv run pytest tests/test_agent.py

# 运行并显示覆盖率
uv run pytest --cov=src/liteagent --cov-report=html

# 运行特定标记的测试
uv run pytest -m unit        # 只运行单元测试
uv run pytest -m integration # 只运行集成测试

# 详细输出
uv run pytest -v --cov-report=term-missing

当前项目状态

• ✅ 测试: 37 个测试全部通过
• 📊 覆盖率: 60% (核心模块 90%+)
• 🔧 依赖: 2 个核心，5 个开发依赖
• 📦 包大小: wheel 12.4KB