> ## Documentation Index
> Fetch the complete documentation index at: https://ai-gateway.juniortree.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 开发指南

> 在本地环境进行AI Gateway开发和调试

<Info>
  **前置要求**:

  * Python 3.12+
  * uv包管理器
  * 至少一个AI平台的API密钥
</Info>

## 环境准备

### 安装uv

uv是一个快速的Python包管理器，推荐用于AI Gateway开发：

```bash theme={null}
# 安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version
```

### 克隆项目

```bash theme={null}
git clone https://github.com/your-repo/ai-gateway.git
cd ai-gateway
```

## 本地开发

### 1. 安装依赖

使用uv安装项目依赖：

```bash theme={null}
# 创建虚拟环境并安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate     # Windows
```

### 2. 配置环境变量

参考[快速开始](/quickstart)页面中的环境变量配置部分，创建 `.env` 文件并配置必要的API密钥。

### 3. 启动开发服务器

```bash theme={null}
# 启动开发服务器（与 Makefile 保持一致）
make run
```

<Check>
  开发服务器启动后，访问 [http://localhost:8000](http://localhost:8000) 查看API文档
</Check>

### 使用 Makefile 进行本地调试

如果你更偏好通过 Makefile 管理开发与调试流程，项目内置了常用的一站式命令：

```bash theme={null}
# 查看所有可用命令
make help
```

<Steps>
  <Step title="安装与环境同步">
    ```bash theme={null}
    # 安装生产/开发/测试/文档依赖（按需选择其一）
    make install
    make install-dev
    make install-test
    make install-docs

    # 同步锁定依赖到虚拟环境
    make sync-deps
    ```

    <Info>
      需要已安装 uv，且已在项目根目录执行命令。
    </Info>
  </Step>

  <Step title="认证系统初始化（可选）">
    ```bash theme={null}
    # 初始化 .env 与依赖，并检查本机 MongoDB 环境
    make setup-auth

    # 创建管理员用户（需先完成 setup-auth）
    make create-admin
    ```

    <Tip>
      未设置 JWT\_SECRET\_KEY 时，系统会自动生成安全密钥。若需固定密钥，可在 `.env` 中设置。
    </Tip>
  </Step>

  <Step title="启动与构建">
    ```bash theme={null}
    # 启动开发服务器（支持热重载）
    make run

    # 启动生产服务器
    make run-prod

    # 构建项目发行物
    make build
    ```
  </Step>

  <Step title="测试与质量">
    ```bash theme={null}
    # 运行测试 / 生成覆盖率报告
    make test
    make test-cov

    # 代码检查与格式化
    make lint
    make format
    ```
  </Step>

  <Step title="API 与文档">
    ```bash theme={null}
    # 生成 OpenAPI 规范文件 openapi.json（基于运行时 app.openapi()）
    make openapi

    # 构建文档（Mintlify 站点）
    make docs
    ```

    <Check>
      完成后可在 `openapi.json` 中查看接口规范；文档构建产物位于站点输出目录。
    </Check>
  </Step>

  <Step title="调试认证与 API Key（可选）">
    ```bash theme={null}
    # 在另一个终端先执行 make run 启动服务后，再运行以下命令
    make test-auth
    make test-api-keys
    ```

    <Warning>
      上述两个命令会提示“等待服务启动后按任意键继续…”。若在 CI 或无人值守环境，请避免使用，或改为直接运行对应的 Python 测试脚本。
    </Warning>
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="更多常用命令">
    ```bash theme={null}
    # 清理构建与缓存
    make clean

    # 依赖升级与同步
    make update-deps

    # 预提交检查与安装钩子
    make pre-commit
    make install-hooks

    # 打印项目信息
    make info
    ```
  </Accordion>
</AccordionGroup>

## 开发工具

### 代码格式化

AI Gateway 使用 black 和 isort 进行格式化。可直接使用 Makefile：

```bash theme={null}
# 一键格式化
make format

# 代码检查（flake8 + mypy）
make lint
```

### 类型检查

使用 mypy 进行类型检查，可通过 `make lint` 统一执行，或单独运行：

```bash theme={null}
uv run mypy agent/ api/ auth/ services/ database/ models/
```

### 测试

运行项目测试：

```bash theme={null}
# 运行所有测试
make test

# 生成覆盖率报告
make test-cov

# 智能体管理 API 测试
make test-agents
```

## 调试技巧

### 日志配置

在开发环境中，可以设置更详细的日志级别：

```bash theme={null}
# 设置日志级别
export LOG_LEVEL=DEBUG

# 启动服务
make run
```

### 调试模式

使用Python调试器进行调试：

```python theme={null}
import pdb; pdb.set_trace()  # 在代码中添加断点
```

或者使用VSCode的调试功能：

```json theme={null}
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "AI Gateway Debug",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/main.py",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}
```

## 开发新Agent

要开发新的AI平台支持，请参考[Agent开发指南](/essentials/agent-development)页面。

## 文档开发

### 本地预览文档

AI Gateway 使用Mintlify进行文档管理。要预览文档：

```bash theme={null}
# 安装Mintlify CLI
npm i -g mint

# 启动文档预览
mint dev
```

文档将在 [http://localhost:3000](http://localhost:3000) 上可用。

### 自定义端口

如果3000端口被占用，可以使用其他端口：

```bash theme={null}
mint dev --port 3333
```

## 常见问题

<AccordionGroup>
  <Accordion title="依赖安装失败">
    检查Python版本是否为3.12+，确保网络连接正常。
  </Accordion>

  <Accordion title="API调用失败">
    确认环境变量配置正确，API密钥有效。
  </Accordion>

  <Accordion title="端口被占用">
    开发命令由 Makefile 管理。若需改端口，可直接运行：`uv run uvicorn main:app --port 8001 --reload`
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="Agent开发" icon="code" href="/essentials/agent-development">
    学习如何为AI Gateway添加新的AI平台支持
  </Card>

  <Card title="API文档" icon="terminal" href="/api-reference/introduction">
    查看完整的API接口文档
  </Card>

  <Card title="部署指南" icon="rocket" href="/deploy">
    了解如何部署AI Gateway到生产环境
  </Card>

  <Card title="架构设计" icon="diagram-project" href="/essentials/architecture">
    深入了解AI Gateway的技术架构
  </Card>
</CardGroup>