# 多模态支持

多模态消息（文本 + 图片）支持，遵循 OpenAI API 规范。

---

## 架构层次

```
Prompt 层 (SimplePrompt) → OpenAI 格式消息 → Provider 层适配 → 模型 API
```

**关键原则**：
- 遵循 OpenAI API 消息格式规范
- 模型适配封装在 Provider 层
- 应用层通过 Prompt 层统一处理

---

## 核心实现

### 1. Prompt 层多模态支持

**实现位置**：`agent/prompts/wrapper.py:SimplePrompt`

**功能**：构建 OpenAI 格式的多模态消息

```python
# 使用示例
prompt = SimplePrompt("task.prompt")
messages = prompt.build_messages(
    text="内容",
    images="path/to/image.png"  # 或 images=["img1.png", "img2.png"]
)
```

**关键方法**：
- `build_messages(**context)` - 构建消息列表，支持 `images` 参数
- `_build_image_content(image)` - 将图片路径转为 OpenAI 格式（data URL）

**消息格式**（OpenAI 规范）：
```python
[
  {"role": "system", "content": "系统提示"},
  {
    "role": "user",
    "content": [
      {"type": "text", "text": "..."},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
    ]
  }
]
```

### 2. Gemini Provider 适配

**实现位置**：`agent/llm/providers/gemini.py:_convert_messages_to_gemini`

**功能**：将 OpenAI 多模态格式转换为 Gemini 格式

**转换规则**：
- 检测 `content` 是否为数组（多模态标志）
- `{"type": "text"}` → Gemini `{"text": "..."}`
- `{"type": "image_url"}` → Gemini `{"inline_data": {"mime_type": "...", "data": "..."}}`

**关键逻辑**：
```python
# 处理多模态消息
if isinstance(content, list):
    parts = []
    for item in content:
        if item.get("type") == "text":
            parts.append({"text": item.get("text")})
        elif item.get("type") == "image_url":
            # 解析 data URL 并转换
            mime_type, base64_data = parse_data_url(url)
            parts.append({"inline_data": {"mime_type": mime_type, "data": base64_data}})
```

---

## 使用方式

### .prompt 文件

标准 `.prompt` 文件格式：
```yaml
---
model: gemini-2.5-flash
temperature: 0.3
---

$system$
系统提示...

$user$
用户提示：%text%
```

### 应用层调用

**参考示例**：`examples/feature_extract/run.py`

```python
# 1. 加载 prompt
prompt = SimplePrompt("task.prompt")

# 2. 构建消息（自动处理图片）
messages = prompt.build_messages(text="...", images="img.png")

# 3. 调用 Agent
runner = AgentRunner(llm_call=create_gemini_llm_call())
result = await runner.call(messages=messages, model="gemini-2.5-flash")
```

---

## 扩展支持

**当前支持**：
- 图片格式：PNG, JPEG, GIF, WebP
- 输入方式：文件路径或 base64 data URL

**未来扩展**：
- 音频、视频等其他模态
- 资源缓存和异步加载