# CLAUDE.md

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

## 项目概述

`aib`（AI Bridge）是一个统一的 Python AI 模型桥接库，发布到 PyPI 的包名为 `ai2-Abridge`。核心理念是"透明桥接"：不拦截错误、不修改响应，直接透传厂商原始 SDK 返回。

## 开发命令

```bash
# 安装到本地（可编辑模式，推荐开发时使用）
uv pip install -e .

# 构建分发包
uv build

# 发布到 TestPyPI（先测试）
uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-xxx

# 发布到正式 PyPI
uv publish --token pypi-xxx
```

**运行测试脚本：**
```bash
python test_sdk.py
```

**版本更新时需同步修改两处：**
- `pyproject.toml` → `version`
- `src/aib/__init__.py` → `__version__`

## 架构

```
src/aib/
├── __init__.py       # 导出 AIBridge / Response / VendorType
├── bridge.py         # AIBridge 门面类 - 唯一对外入口
├── config.py         # 配置加载（YAML + 环境变量）
├── models.py         # Response / Usage / VendorType 数据模型
├── cli.py            # CLI 工具（入口：ab 命令）
├── vendors/          # 厂商适配器层
│   ├── base.py       # VendorAdapter 抽象基类（chat + upload_file）
│   ├── gemini.py     # google-genai SDK
│   ├── kimi.py       # openai SDK（兼容模式）
│   ├── openai.py     # openai SDK
│   └── qwen.py       # dashscope SDK
└── batch/            # Batch API 批量处理
    ├── base.py        # BaseBatchManager 抽象基类
    ├── gemini.py      # GeminiBatchManager
    └── qwen.py        # QwenBatchManager
```

### 核心流程

1. 用户调用 `AIBridge(vendor, api_key, ...)` → `bridge.py` 读配置、选适配器
2. 调用 `bridge.chat(prompt, files)` → 委托给 `VendorAdapter.chat()`
3. 适配器负责：文件上传（File API 或 Base64）+ SDK 调用 + 返回 `Response(content, usage, raw)`
4. `Usage` 通过三个 `from_*` 类方法统一不同厂商的字段命名

### 配置优先级（高到低）

代码显式传入 > 环境变量（`AIB_<VENDOR>_API_KEY` 等）> 指定配置文件 > `~/.aib/config.yaml` > `./config.yaml` > 内置默认值

### 添加新厂商适配器

1. 在 `vendors/` 新建 `<vendor>.py`，继承 `VendorAdapter`，实现 `chat()` 和 `upload_file()`
2. 在 `vendors/__init__.py` 的 `get_adapter()` 注册新厂商
3. 在 `bridge.py` 的 `valid_vendors` 列表添加厂商名
4. 在 `config.py` 的环境变量扫描列表添加厂商名

### 各厂商文件处理方式

| 厂商 | 文件处理 |
|------|---------|
| Gemini | 原生 Files API，上传后轮询等待 `ACTIVE` 状态（60s 超时） |
| Kimi | 原生 Files API，通过 `fileid://` 协议引用 |
| Qwen | VL 模型用 Base64 图片；文本模型用原生 Files API |
| OpenAI | Base64 编码图片 |
