[Feature Request]: Agentic Static Resource Handling Capability - 让 Agent 自主处理静态资源的能力

# 功能提议：Agent 自主处理静态资源的能力

## 📋 问题概述

**当前问题**：来自 Discord（以及其他可能的频道）的静态资源（图片、视频、文件）会被框架自动处理并直接传递给模型 API，这可能会因为网络问题、CDN 限制或其他问题导致失败。Agent 在这个过程中没有任何决策权。

**提议的解决方案**：让 Agent 自主决定如何处理静态资源，而不是由框架自动处理。

---

## 🔍 问题描述

### 当前行为

1. 用户在 Discord 中发送图片
2. Discord 频道层自动检测到图片并创建包含 CDN URL 的 `ImageContent`
3. 消息被自动传递给 Agent
4. Formatter 自动将图片 URL 包含在 prompt 中
5. 模型 API 尝试下载图片
6. **发生失败**（例如：在中国访问 Discord CDN 超时）
7. 整个请求崩溃

### 真实案例

来自我们的实际经历：
- 用户在 Discord 私聊中发送图片
- Discord CDN URL：`https://cdn.discordapp.com/attachments/...`
- 模型 API 尝试下载
- 错误：`dial tcp 31.13.96.193:443: i/o timeout`
- 结果：整个对话崩溃，Agent"死亡"

### 根本原因

框架做出了几个在所有环境中都不成立的假设：
1. 所有静态资源 URL 都是普遍可访问的
2. 模型 API 可以从任何位置下载任何 URL
3. 网络条件在任何地方都是相同的
4. Agent 不需要对资源做出决策

---

## 🤔 当前架构的局限性

```
用户 → 频道层（自动处理）→ Agent（没有选择权）→ 模型 API（可能失败）
```

### 局限性

1. **没有 Agent 自主权**：Agent 对如何处理资源没有发言权
2. **没有回退机制**：如果一种方法失败，没有替代方案
3. **没有上下文感知**：框架不知道网络条件、用户偏好或环境限制
4. **脆弱的失败**：单个资源失败会导致整个请求崩溃

---

## 💡 提议的解决方案：Agent 自主处理静态资源

### 核心理念

**让 Agent 自主决定如何处理静态资源。**

```
用户 → 频道层（检测，不自动处理）→ Agent（决定）→ 模型 API
```

### 关键原则

1. **Agent 自主权**：Agent 决定如何处理每个资源
2. **灵活性**：多种处理策略可用
3. **回退**：如果一种策略失败，尝试另一种
4. **上下文感知**：Agent 可以考虑网络条件、用户偏好等

---

## 🔧 实现选项

### 选项 1：资源元数据 + Agent 工具（推荐）

#### 架构

```
1. 频道层检测资源 → 创建元数据（不是 ImageContent）
2. 消息携带资源元数据传递给 Agent
3. Agent 使用工具做出决策并处理
4. Agent 为模型创建适当的内容
```

#### 频道层变更

频道层不是自动创建 `ImageContent`，而是：
- 检测资源（图片、视频、文件）
- 创建资源元数据，包含：
- `resource_type`：image/video/file
- `url`：原始 URL
- `metadata`：大小、格式、content_type、文件名等
- 将此元数据包含在消息中（不作为内容）

#### Agent 工具

为 Agent 提供这些工具：

```python
# 检查资源 URL 是否可访问
check_resource_accessibility(url: str) -> bool

# 将资源下载到本地（如果可用，使用频道的 proxy）
download_resource(url: str, path: str) -> LocalResource

# 将图片转换为 base64
image_to_base64(path: str) -> str

# 将资源上传到对象存储（可配置）
upload_to_storage(path: str) -> StorageUrl

# OCR：从图片中提取文本
extract_text_from_image(path: str) -> str

# 获取资源元数据而不下载
get_resource_metadata(url: str) -> ResourceMetadata
```

#### Agent 工作流程

1. Agent 收到带有资源元数据的消息
2. Agent 根据上下文决定策略：
- URL 是否可访问？
- 网络环境是什么？
- 用户偏好是什么？
- 资源大小/类型是什么？
3. Agent 执行选择的策略
4. Agent 为模型创建适当的内容
5. Agent 继续推理

### 选项 2：混合模式（向后兼容）

#### 架构

- **默认**：保持当前的自动处理行为（向后兼容）
- **选择加入**：Agent 可以选择接管资源处理

#### 实现

- 向 Agent 添加一个标志：`agent_handles_resources = False`（默认）
- 如果为 `False`：框架像以前一样自动处理
- 如果为 `True`：框架传递资源元数据，Agent 决定

### 选项 3：资源预处理器插件

#### 架构

允许插件在资源到达 Agent 之前拦截和处理资源。

```
用户 → 频道 → 资源预处理器 → Agent
```

#### 好处

- 用户可以创建自定义预处理器
- 可以处理特定环境的问题（如中国网络）
- 不需要更改核心框架

---

## 🎯 推荐的实现路径

### 第一阶段：快速胜利 - 更好的错误处理

即使没有完整的 Agent 处理，也可以改善当前情况：

1. **不要让整个请求崩溃**，如果一个资源失败
2. **记录错误**并继续处理其他内容
3. **提供用户友好的消息**："无法处理图片，继续处理其他内容"

### 第二阶段：资源元数据 + 基本工具

实现选项 1，包含：
- 来自频道层的资源元数据
- 基本工具：`check_accessibility`、`download_resource`
- Agent 可以决定使用或跳过资源

### 第三阶段：完整工具包

添加更多工具：
- Base64 转换
- 对象存储上传
- OCR
- 等等

---

## ✨ 这种方法的好处

### 1. 灵活性

- Agent 可以适应不同的网络环境
- 可以处理 CDN 限制、防火墙等
- 针对不同资源类型的不同策略

### 2. 健壮性

- 没有单点故障
- 回退策略可用
- 优雅降级

### 3. 可扩展性

- 可以添加新工具而不更改核心框架
- 社区可以贡献工具
- 可以处理新的资源类型

### 4. 智能化

- Agent 可以学习用户偏好
- 可以做出上下文感知的决策
- 可以根据资源特征进行优化

---

## 🚀 真实用例

### 用例 1：中国的 Discord

- 问题：Discord CDN 在中国无法访问
- 解决方案：Agent 通过 proxy 下载图片，转换为 base64，发送给模型

### 用例 2：大图片

- 问题：大图片超过 token 限制
- 解决方案：Agent 检测大小，在下采样或摘要后发送

### 用例 3：敏感内容

- 问题：用户不希望某些图片发送给模型
- 解决方案：Agent 检测敏感内容，询问用户许可

### 用例 4：OCR 优先

- 问题：图片主要包含文本
- 解决方案：Agent 使用 OCR 工具，提取文本，发送文本而不是图片

---

## 📝 结论

当前的自动静态资源处理是脆弱的，在真实场景中会失败。通过让 Agent 自主决定如何处理静态资源，我们创建了一个更灵活、更健壮、更智能的系统。

这个提议保持了向后兼容性，同时启用了强大的新功能。我们建议分阶段实现，从更好的错误处理开始，逐步走向完整的 Agent 资源处理。

---
**标签**：`feature`、`enhancement`、`agent`、`resources`、`images`、`discord`