AI Agent Learning

基于 FastAPI 的 AI Agent 学习项目，集成火山引擎豆包模型（doubao-lite-128k）。

项目结构

learning-agent/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── config.py            # 配置管理（环境变量、模型配置）
│   ├── models/
│   │   ├── __init__.py
│   │   └── llm_client.py    # LLM 客户端抽象层（支持模型切换）
│   └── api/
│       ├── __init__.py
│       └── chat.py          # 对话 API 端点
├── .cursor/
│   ├── rules/               # Cursor 规则文件
│   │   └── superpowers-workflow.mdc  # Superpowers 工作流激活规则
│   └── skills/              # Superpowers skills（标准化开发流程）
├── scripts/
│   └── install-superpowers.sh  # Superpowers skills 安装脚本
├── venv/                    # Python 虚拟环境（运行 setup.sh 后生成）
├── requirements.txt         # Python 依赖
├── env.example              # 环境变量示例
├── setup.sh                 # 项目初始化脚本（macOS/Linux）
├── run.sh                   # 应用启动脚本（macOS/Linux）
├── .gitignore
└── README.md                # 项目说明

快速开始

方式一：使用 Makefile（推荐）

macOS/Linux:

# 1. 查看所有可用命令
make help

# 2. 初始化项目（创建虚拟环境并安装依赖）
make setup

# 3. 配置环境变量（编辑 .env 文件，填入 API Key）
# 编辑 .env 文件

# 4. 启动应用
make dev

常用 Makefile 命令：

make help              # 显示所有可用任务和说明
make setup             # 初始化项目（会自动安装 Git hooks）
make install           # 安装依赖
make install-hooks     # 安装 Git hooks（pre-commit）
make dev               # 启动应用（开发模式）
make test              # 运行所有测试
make test-cov          # 运行测试并生成覆盖率报告
make format            # 格式化代码（black）
make lint              # 代码检查（ruff）
make lint-fix          # 代码检查并自动修复（ruff --fix）
make type-check        # 类型检查（mypy）
make clean             # 清理所有缓存文件
make install-superpowers  # 安装/更新 Superpowers skills
make check-env         # 检查环境配置

方式二：使用自动化脚本

macOS/Linux:

# 1. 初始化项目（创建虚拟环境并安装依赖）
./setup.sh

# 2. 配置环境变量（编辑 .env 文件，填入 API Key）
# 编辑 .env 文件

# 3. 启动应用
./run.sh

注意： 推荐使用 Makefile 方式，shell 脚本保留作为备选。

方式三：手动设置

1. 创建虚拟环境

# 创建 venv 虚拟环境
python -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

创建 .env 文件（参考 .env.example）：

# 火山引擎 API 配置
DOUBAO_API_KEY=your_api_key_here
DOUBAO_API_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3/chat/completions
DOUBAO_MODEL_NAME=doubao-seed-1-6-lite-251015

# FastAPI 配置
API_HOST=0.0.0.0
API_PORT=8000

注意： 模型名称 doubao-seed-1-6-lite-251015 是示例，请根据你在火山引擎控制台实际可用的模型名称进行配置。

4. 运行应用

重要：运行前必须先激活虚拟环境！

# 激活虚拟环境（如果还没激活）
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate     # Windows

# 方式1：使用 uvicorn 直接运行
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 方式2：使用 Python 运行
python -m app.main

或者使用启动脚本（自动激活虚拟环境）：

./run.sh  # macOS/Linux

5. 访问 API 文档

启动后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Makefile 命令说明

项目使用 Makefile 统一管理所有常用任务。运行 make help 查看所有可用命令。

基础任务

• make setup - 初始化项目（创建虚拟环境、安装依赖、创建 .env）
• make dev - 启动应用（开发模式）
• make install - 安装依赖（从 requirements.txt）
• make check-env - 检查环境配置（Python 版本、虚拟环境、.env 文件）

测试任务

• make test - 运行所有测试
• make test-cov - 运行测试并生成覆盖率报告（生成 htmlcov/index.html）
• make test-watch - 监控文件变化并自动运行测试
• make test-file FILE=tests/test_main.py - 运行指定测试文件

清理任务

• make clean - 清理所有缓存文件（Python 缓存、pytest 缓存、覆盖率报告等）

代码质量任务

• make format - 格式化代码（使用 black）
• make lint - 代码检查（使用 ruff）
• make lint-fix - 代码检查并自动修复（使用 ruff --fix）
• make type-check - 类型检查（使用 mypy）

Git Hooks（自动代码检查）

项目配置了 Git pre-commit hook，在每次 git commit 前自动运行代码质量检查：

1. 自动格式化：使用 black 格式化代码
2. 自动修复：使用 ruff --fix 自动修复可修复的问题
3. 代码检查：验证没有剩余的问题
4. 类型检查：使用 mypy 进行类型检查

安装方式：

• 自动安装：运行 make setup 时会自动安装 Git hooks
• 手动安装：运行 make install-hooks 单独安装

工作原理：

• Hook 脚本位于 scripts/pre-commit，会被提交到仓库
• 运行 make setup 或 make install-hooks 时，会将脚本复制到 .git/hooks/pre-commit
• 每次提交前，hook 会自动运行检查
• 如果检查失败，提交会被阻止，并提示运行相应的命令查看详细错误
• 格式化修复的文件会自动添加到暂存区

跳过检查（不推荐）：

如果确实需要跳过检查（例如紧急修复），可以使用：

git commit --no-verify -m "紧急修复"

注意： 跳过检查可能导致代码质量问题，请谨慎使用。

Superpowers 管理

• make install-superpowers - 安装/更新 Superpowers skills
• make update-superpowers - 更新 Superpowers skills（快捷方式）

文档任务

• make docs - 生成 API 文档（FastAPI 自动生成，访问 http://localhost:8000/docs）
• make serve-docs - 本地启动文档服务器

API 使用示例

标准对话接口

基础文本对话：

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "temperature": 0.7,
    "max_completion_tokens": 2000
  }'

多模态对话（图片+文本）：

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg"
            }
          },
          {
            "type": "text",
            "text": "图片主要讲了什么?"
          }
        ]
      }
    ],
    "max_completion_tokens": 65535,
    "reasoning_effort": "medium"
  }'

简化对话接口

curl -X POST "http://localhost:8000/chat/simple?message=你好"

API 参数说明

• messages: 消息列表，支持文本或多模态内容
• temperature: 温度参数，控制随机性（0.0-2.0）
• max_completion_tokens: 最大完成 token 数（火山引擎 API 参数）
• max_tokens: 兼容参数，会自动转换为 max_completion_tokens
• reasoning_effort: 推理努力程度，可选值：low, medium, high
• stream: 是否流式返回

核心设计

1. 配置管理

使用 pydantic-settings 管理环境变量，支持从 .env 文件加载配置。

2. LLM 客户端抽象层

• BaseLLMClient: 抽象基类，定义统一的接口
• DoubaoClient: 火山引擎豆包模型的具体实现
• 支持未来扩展其他模型（OpenAI、Claude 等）

3. 可扩展架构

• 模块化设计，便于添加新功能
• 抽象层设计，支持模型切换
• 清晰的代码结构，便于学习和扩展

未来扩展方向

• 添加对话历史管理
• 实现工具调用（Function Calling）
• 添加 Agent 规划能力
• 支持多模型切换
• 添加流式响应支持
• 实现记忆管理
• 添加向量数据库支持

技术栈

• FastAPI: 现代、快速的 Web 框架
• httpx: 异步 HTTP 客户端
• pydantic: 数据验证和设置管理
• uvicorn: ASGI 服务器

故障排除

ModuleNotFoundError: No module named 'pydantic_settings'

原因： 运行应用时没有激活虚拟环境，或者使用了系统 Python 而不是虚拟环境中的 Python。

解决方法：

# 确保激活虚拟环境
source venv/bin/activate  # macOS/Linux

# 然后运行应用
uvicorn app.main:app --reload
# 或使用启动脚本
./run.sh

安装依赖失败（pydantic-core 编译错误）

原因： Python 版本过新（如 Python 3.14），缺少预编译的 wheel 包。

解决方法：

1. 使用 Python 3.11 或 3.12（推荐）
2. 或者安装 Rust 工具链来编译 pydantic-core
3. 或者等待更新的 pydantic 版本支持你的 Python 版本

如何检查虚拟环境是否激活

激活虚拟环境后，命令行提示符前会显示 (venv)：

(venv) user@host:~/learning-agent$

如果没有看到 (venv)，说明虚拟环境未激活。

Superpowers 开发工作流

本项目集成了 Superpowers 开发工作流系统，提供标准化的软件开发流程。

什么是 Superpowers？

Superpowers 是一套完整的软件开发工作流，基于可组合的 "skills" 系统，确保 AI 代理遵循最佳实践：

• Test-Driven Development (TDD) - 测试驱动开发
• Brainstorming - 设计阶段的需求探索
• Writing Plans - 详细的实施计划
• Systematic Debugging - 系统化调试流程

安装 Superpowers Skills

Skills 已预装在项目中，位于 .cursor/skills/ 目录。

首次安装或更新：

# 方式一：使用安装脚本（自动检测安装/更新）
./scripts/install-superpowers.sh

# 方式二：使用更新脚本（快捷方式）
./scripts/update-superpowers.sh

脚本功能：

• ✅ 自动检测是否已安装（首次安装 vs 更新）
• ✅ 更新时自动备份现有 skills 到 .cursor/skills.backup.YYYYMMDD_HHMMSS/
• ✅ 从 GitHub 下载最新版本
• ✅ 显示版本信息（Commit hash 和日期）
• ✅ 列出所有已安装的 skills

更新说明：

• 🔄 可以随时重新运行脚本获取最新版本
• 💾 更新时会自动备份，备份目录格式：.cursor/skills.backup.YYYYMMDD_HHMMSS/
• ↩️ 如需恢复旧版本，可以手动复制备份目录的内容回 .cursor/skills/
• 🗑️ 备份目录可以安全删除（确认新版本正常后）

核心工作流

1. Brainstorming（设计） - 在编码前探索需求、设计方案
2. Writing Plans（计划） - 创建详细的实施计划，分解为小任务
3. Test-Driven Development（实施） - 先写测试，再写代码
4. Systematic Debugging（调试） - 系统化的调试流程

如何使用

在 Cursor 中与 AI 对话时，Superpowers skills 会自动激活。例如：

• 说 "我想添加一个新功能" → 自动触发 brainstorming skill
• 说 "帮我修复这个 bug" → 自动触发 systematic-debugging skill
• 开始编码时 → 自动遵循 test-driven-development 流程

更多信息请查看 .cursor/rules/superpowers-workflow.mdc 和 .cursor/skills/ 目录。

学习资源

这是一个学习 AI Agent 开发的基础框架，你可以在此基础上：

1. 学习 FastAPI 的使用
2. 理解 LLM API 的调用方式
3. 学习抽象层设计模式
4. 逐步添加 Agent 功能（记忆、工具调用、规划等）
5. 使用 Superpowers 工作流标准化开发流程

许可证

MIT