# Agent 任务图片上传技术方案
> 状态：方案设计阶段，暂不进入开发
## 1. 背景与目标
当前 Agent 任务的用户消息仅支持纯文本，前端虽然有文件选择入口（ChatInput 的 "+" 按钮），但上传的文件仅作为附件元数据展示，不会传递给 LLM。本次需求：**支持用户在发送任务时附带图片，图片通过 LLM 视觉能力被 Agent 理解和处理**。
图片存储采用阿里云 OSS，前端通过 STS 临时凭证直传 OSS（不经过后端代理，节省服务器带宽）。
## 2. 现状分析
### 2.1 消息链路（当前）
```
用户输入 → ChatInput.emit('send', text, files[])
→ useChat.sendMessage(text, files)
→ uploadFiles(files) // POST /v1/files/upload 存到本地磁盘
→ wsSendMessage(sid, text) // WS 只发纯文本，图片不参与
→ StreamingWsHandler.handleSendMessage()
→ sessionService.saveMessage() // content = 纯文本
→ HarnessService.execute()
→ buildContext() 加载历史消息
→ PromptEngine.buildRequest() // ChatRequest.Message.content = String
→ OpenAiLlmAdapter.stream() // 序列化为 {"role":"user","content":"纯文本"}
```
### 2.2 关键断点
| 层级 | 当前状态 | 需要改动 |
|------|---------|---------|
| DB `message.content` | MEDIUMTEXT 纯文本 | 支持 JSON content parts 或新增列 |
| `ChatRequest.Message.content` | `String` | 改为 `Object`（兼容 String 和 List） |
| `PromptEngine` | 透传纯文本 content | 透传多模态 content |
| `OpenAiLlmAdapter` | 序列化 content 为 string | 序列化为 string 或 content_parts 数组 |
| `HarnessService.buildContext()` | 从 DB 读取纯文本 | 读取多模态结构并还原 |
| 前端 `useChat.uploadFiles()` | 上传到后端本地磁盘 | 改为 OSS 直传 |
| 前端 `MessageBubble` | 展示文件名 tag | 渲染图片预览 |
| 前端 WS `send_message` | 只发 text | 携带图片 OSS URL 列表 |
## 3. 整体方案设计
### 3.1 上传方案：STS 直传 OSS
```
┌──────────┐ ①请求STS凭证 ┌──────────┐
│ 前端 │ ──────────────→ │ 后端 │
│ Vue3 │ ←────────────── │ Spring │
│ │ ②返回临时凭证 │ Boot │
│ │ │ │
│ │ ③直传图片 ┌──────────┐
│ │ ──────────────→ │ 阿里云OSS │
│ │ ←────────────── │ │
│ │ ④返回OSS URL │ │
└──────────┘ └──────────┘
```
- **步骤 ①②**：前端调用后端 `POST /api/v1/oss/sts-token`，后端通过 RAM AssumeRole 生成 STS 临时凭证（AccessKeyId / AccessKeySecret / SecurityToken / Expiration）
- **步骤 ③④**：前端使用阿里云 OSS JS SDK（`ali-oss`）+ STS 凭证直传图片到 OSS Bucket
- **步骤 ⑤**：前端拿到 OSS URL 后，随 WS `send_message` 一起发送
### 3.2 消息内容格式：OpenAI 兼容的 Content Parts
采用 OpenAI Vision API 的 content parts 格式，与现有纯文本向后兼容：
```json
// 纯文本消息（现有）
{ "role": "user", "content": "请分析这张图片" }
// 带图片消息（新增）
{
"role": "user",
"content": [
{ "type": "text", "text": "请分析这张图片" },
{ "type": "image_url", "image_url": { "url": "https://etfs.oss-cn-hangzhou.aliyuncs.com/session/123/abc.jpg" } }
]
}
```
这种格式被 OpenAI / Claude / 通义千问 / DeepSeek 等主流模型兼容。
### 3.3 数据流全景
```
前端选图 → 获取STS凭证 → 直传OSS → 拿到URL
↓
WS send_message 携带:
{ content: "文本", images: ["oss_url_1", ...] }
↓
后端 StreamingWsHandler
↓
saveMessage() 存入DB:
content = JSON([{type:"text",...},{type:"image_url",...}])
↓
HarnessService.buildContext()
读取DB → 还原 ChatRequest.Message
↓
PromptEngine.buildRequest()
透传 content parts
↓
OpenAiLlmAdapter.stream()
序列化为 OpenAI 格式发给 LLM
```
## 4. 详细设计
### 4.1 后端：OSS STS 模块
#### 4.1.1 新增 `OssProperties` 配置类
```java
@Data
@Component
@ConfigurationProperties(prefix = "oss")
public class OssProperties {
private String region = "oss-cn-hangzhou";
private String accessKeyId = "xxxxxxx";
private String accessKeySecret = "xxxxxxx";
private String bucket = "etfs";
private int maxKeys = 100;
private Sts sts = new Sts();
private Cdn cdn = new Cdn();
@Data
public static class Sts {
private String regionId = "cn-hangzhou";
private String endpoint = "sts.cn-hangzhou.aliyuncs.com";
private String accessKeyId = "xxxxxxx";
private String accessKeySecret = "xxxxxxx";
private String roleArn = "acs:ram::xxxxxxx:role/ramosstest";
private String roleSessionName = "OssSession"; // 运行时覆盖为 "User_{userId}"
private long expire = 3600;
private DataSize maxSize = DataSize.ofMegabytes(20); // STS policy 单文件上限 20MB
}
@Data
public static class Cdn {
private String domain; // CDN 域名，为空时使用 OSS 默认域名
}
}
```
#### 4.1.2 新增 STS 服务
```java
@Service
public class OssStsService {
// AssumeRole 生成临时凭证
// roleSessionName = "User_{userId}"（便于审计追踪）
// 限制 policy: 只允许 putObject，限定 bucket 和路径前缀
// 路径前缀: /session/{sessionId}/
// 单文件大小限制: 20MB
public StsTokenVO generateStsToken(Long userId, Long sessionId);
}
```
#### 4.1.3 新增 STS 接口
```
POST /api/v1/oss/sts-token
Body: { "sessionId": 123 }
Response: {
"accessKeyId": "...",
"accessKeySecret": "...",
"securityToken": "...",
"expiration": "2026-06-01T12:00:00Z",
"bucket": "etfs",
"region": "oss-cn-hangzhou",
"uploadDir": "session/123/"
}
```
#### 4.1.4 Maven 依赖
```xml
com.aliyun
aliyun-java-sdk-sts
3.1.1
com.aliyun
aliyun-java-sdk-core
4.6.4
```
### 4.2 后端：消息多模态改造
#### 4.2.1 `ChatRequest.Message.content` 类型改造
```java
@Data
@Builder
@JsonIgnoreProperties(ignoreUnknown = true)
public static class Message {
private String role;
private Object content; // String 或 List
private String name;
@JsonProperty("tool_call_id")
private String toolCallId;
@JsonProperty("tool_calls")
private List toolCalls;
}
// 新增 ContentPart 抽象
@Data
@Builder
public static class ContentPart {
private String type; // "text" 或 "image_url"
private String text; // type=text 时
@JsonProperty("image_url")
private ImageUrl imageUrl; // type=image_url 时
}
@Data
@Builder
public static class ImageUrl {
private String url;
}
```
**序列化兼容性**：当 `content` 是 `String` 时 Jackson 序列化为 JSON string，当是 `List` 时序列化为 JSON array。无需额外适配。
#### 4.2.2 DB 存储方案：直接存 JSON 到 `message.content`
```sql
-- 现有纯文本
content = "请分析这张图片"
-- 多模态
content = '[{"type":"text","text":"请分析这张图片"},{"type":"image_url","image_url":{"url":"https://..."}}]'
```
无需改表结构，MEDIUMTEXT 天然支持 JSON。`HarnessService.buildContext()` 读取时，先尝试 JSON 解析为 `List`，失败则视为纯文本字符串。
不采用新增列方案，避免不必要的表结构变更。
#### 4.2.3 `HarnessService.buildContext()` 改造
```java
// 原来
var msgBuilder = ChatRequest.Message.builder()
.role(msg.getRole().toLowerCase())
.content(msg.getContent());
// 改造后
Object parsedContent = parseContent(msg.getContent());
var msgBuilder = ChatRequest.Message.builder()
.role(msg.getRole().toLowerCase())
.content(parsedContent);
// 解析逻辑
private Object parseContent(String raw) {
if (raw == null) return null;
raw = raw.trim();
if (raw.startsWith("[")) {
try {
return objectMapper.readValue(raw, new TypeReference>() {});
} catch (Exception e) {
return raw; // fallback to plain text
}
}
return raw;
}
```
#### 4.2.4 `SessionService.saveMessage()` 改造
新增重载方法，支持保存多模态 content：
```java
public Message saveMessage(Long sessionId, String role, Object content,
String toolCallId, String toolCalls,
Integer tokenCount, Long modelId) {
Message message = new Message();
// ...
if (content instanceof String str) {
message.setContent(str);
} else {
message.setContent(objectMapper.writeValueAsString(content));
}
// ...
}
```
#### 4.2.5 `AgentExecutionContext` 改造
```java
// 新增多模态消息添加方法
public void addUserMessage(List parts) {
messages.add(ChatRequest.Message.builder()
.role("user")
.content(parts)
.build());
}
```
#### 4.2.6 `OpenAiLlmAdapter.buildRequest()` 改造
```java
// 原来
body.put("messages", request.getMessages());
// 不需要改动！Jackson 会自动将 Message.content (Object)
// 序列化为 string 或 array。
// 但需要确保 messages 的 content 字段在序列化时正确输出。
// 已有的 @JsonIgnoreProperties(ignoreUnknown = true) 足够。
```
实际上 `buildRequest()` 把 `request.getMessages()` 直接放入 HashMap 然后 Jackson 序列化，`content` 是 `Object` 类型，Jackson 会根据实际类型（String / List）输出正确的 JSON。**此层无需改动**。
### 4.3 后端：WebSocket 消息扩展
#### 4.3.1 `send_message` 协议扩展
```json
// 现有
{ "type": "send_message", "sessionId": 123,
"data": { "content": "请分析", "eventId": "uuid" } }
// 扩展
{ "type": "send_message", "sessionId": 123,
"data": { "content": "请分析", "eventId": "uuid",
"images": ["https://etfs.oss-cn-hangzhou.aliyuncs.com/session/123/abc.jpg"] } }
```
#### 4.3.2 `StreamingWsHandler.handleSendMessage()` 改造
```java
String content = data.get("content").asText();
List images = new ArrayList<>();
if (data.has("images") && data.get("images").isArray()) {
for (JsonNode img : data.get("images")) {
images.add(img.asText());
}
}
// 非 vision 模型 + 有图片 → 报错中断
if (!images.isEmpty()) {
Agent agent = agentMapper.selectById(session.getAgentId());
LlmModel model = llmModelMapper.selectById(agent.getModelId());
if (!model.isSupportsVision()) { // 需在 LlmModel 实体新增 supportsVision 字段
registry.send(userId, WsEvent.of("error", sessionId,
Map.of("message", "当前模型不支持图片输入，请切换支持视觉的模型")));
return;
}
}
// 前端限制最多 10 张图片
if (images.size() > 10) {
registry.send(userId, WsEvent.of("error", sessionId,
Map.of("message", "单条消息最多支持 10 张图片")));
return;
}
// 构建多模态 content
Object messageContent;
if (images.isEmpty()) {
messageContent = content;
} else {
List parts = new ArrayList<>();
if (content != null && !content.isBlank()) {
parts.add(ChatRequest.ContentPart.builder().type("text").text(content).build());
}
for (String imageUrl : images) {
parts.add(ChatRequest.ContentPart.builder()
.type("image_url")
.imageUrl(ChatRequest.ImageUrl.builder().url(imageUrl).build())
.build());
}
messageContent = parts;
}
// 保存到 DB
sessionService.saveMessage(sessionId, "USER", messageContent, null, null, 0, null);
// 传递给 HarnessService（需要同步改造 prepareMessage）
harnessService.prepareMessage(sessionId, messageContent);
```
#### 4.3.3 `HarnessService.prepareMessage()` 改造
```java
// 原来
public String prepareMessage(Long sessionId, String userContent) {
String eventId = UUID.randomUUID().toString();
eventContentStore.put(eventId, userContent);
return eventId;
}
// 改造：cache value 改为 Object
private final Cache eventContentStore = ...;
public String prepareMessage(Long sessionId, Object userContent) {
String eventId = UUID.randomUUID().toString();
eventContentStore.put(eventId, userContent);
return eventId;
}
```
### 4.4 前端改造
#### 4.4.1 新增 OSS 上传工具
```typescript
// desktop/src/utils/ossUpload.ts
import OSS from 'ali-oss'
interface StsToken {
accessKeyId: string
accessKeySecret: string
securityToken: string
bucket: string
region: string
uploadDir: string
expiration: string
}
export async function uploadToOss(
file: File,
stsToken: StsToken
): Promise {
const client = new OSS({
region: stsToken.region,
accessKeyId: stsToken.accessKeyId,
accessKeySecret: stsToken.accessKeySecret,
stsToken: stsToken.securityToken,
bucket: stsToken.bucket,
})
const key = `${stsToken.uploadDir}${Date.now()}_${file.name}`
const result = await client.put(key, file)
return result.url
}
```
新增 npm 依赖：`ali-oss`
#### 4.4.2 `useChat.ts` 改造
```typescript
// uploadFiles 改为 uploadImages，返回 OSS URL 列表
async function uploadImages(files: File[]): Promise {
// 1. 获取 STS 凭证
const { data: stsToken } = await api.post('/oss/sts-token', {
sessionId: sessionId.value
})
// 2. 逐个上传到 OSS
const urls: string[] = []
for (const file of files) {
try {
const url = await uploadToOss(file, stsToken)
urls.push(url)
} catch {
ElMessage.error(`图片 ${file.name} 上传失败`)
}
}
return urls
}
// sendMessage 改造
async function sendMessage(text: string, files?: File[]) {
// ...
const imageUrls = await uploadImages(files || [])
// 构建 displayContent（用于本地展示）
let displayContent = text
if (imageUrls.length > 0) {
displayContent += imageUrls.map(url => `\n[图片: ${url}]`).join('')
}
// WS 发送时携带 images
wsSendMessage(sid, text || '', eventId, imageUrls)
// 本地消息存储携带 images
sessionStore.addUserMessage(sid, {
id: `msg_${Date.now()}_user`,
role: 'user',
content: text,
createdAt: new Date().toLocaleString(),
images: imageUrls // 新增
})
}
```
#### 4.4.3 `useStreamWS.ts` 改造
```typescript
// sendMessage 扩展 images 参数
function sendMessage(sessionId: string, content: string, eventId: string, images?: string[]) {
ws.value?.send(JSON.stringify({
type: 'send_message',
sessionId,
data: { content, eventId, images: images || [] }
}))
}
```
#### 4.4.4 `ChatInput.vue` 改造
```typescript
// 文件选择增加图片类型过滤 + 数量限制
function handleFileSelect(event: Event) {
const input = event.target as HTMLInputElement
if (input.files) {
for (const file of Array.from(input.files)) {
// 限制最多 10 张图片
if (pendingFiles.value.length >= 10) {
ElMessage.warning('最多上传 10 张图片')
break
}
// 限制单图 10MB
if (file.size > 10 * 1024 * 1024) {
ElMessage.warning(`图片 ${file.name} 超过 10MB 限制`)
continue
}
// 图片预览
if (file.type.startsWith('image/')) {
file.previewUrl = URL.createObjectURL(file)
}
pendingFiles.value.push(file)
}
}
input.value = ''
}
// 文件 chips 增加图片缩略图
// ![]()
```
#### 4.4.5 `MessageBubble.vue` 改造
```typescript
// ChatMessage 类型扩展
interface ChatMessage {
// ...existing
images?: string[] // OSS 图片 URL 列表
}
// 用户消息渲染：图片以缩略图展示
//
//
![]()
//