106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
## Context
|
||
|
||
当前仓库中已经存在统一的 `GeminiMessage` 消息结构，并且底层协议层已经能处理图片消息：
|
||
|
||
- `openai.chat.completions` 可以直接承载 `image_url`
|
||
- `google.generateContent` 已经能把 `image_url` 转成 `inline_data`
|
||
|
||
但上层文本链路并没有把图片喂给协议层：
|
||
|
||
- `chat-service` 会显式丢弃 `attachments`
|
||
- `AgentExecutor` 默认只发送结构化文本和图片占位符
|
||
- `ai_analyze` 工作流主要传递纯文本 `messages`
|
||
|
||
因此，当前需要解决的不是“协议是否支持图片”，而是“什么时候允许文本消息带图，以及如何在不同入口统一组装消息”。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
- Goals:
|
||
- 让文本聊天与 Agent 在支持的绑定上能真正发送图片内容
|
||
- 用绑定能力位控制是否允许图片输入，避免纯文本模型误收图片
|
||
- 在不改动现有 provider routing 主干的前提下复用现有 `GeminiMessage` 结构
|
||
- Non-Goals:
|
||
- 不在本阶段接入新的文件上传协议
|
||
- 不在本阶段统一支持所有第三方自定义文本协议
|
||
- 不在本阶段做服务端中转上传
|
||
|
||
## Decisions
|
||
|
||
### Decision: 以绑定能力位控制文本图片输入
|
||
|
||
文本模型是否支持图片输入，不再由 UI 或模型名猜测，而是由文本绑定显式声明。
|
||
|
||
建议新增字段：
|
||
|
||
```ts
|
||
interface TextInputCapability {
|
||
supportsImageInput?: boolean;
|
||
maxImageCount?: number;
|
||
}
|
||
```
|
||
|
||
第一阶段默认规则：
|
||
|
||
- `google.generateContent` 绑定默认 `supportsImageInput = true`
|
||
- `openai.chat.completions` 绑定默认 `supportsImageInput = true`
|
||
- 其他文本绑定默认 `false`
|
||
|
||
这样可以在不引入复杂供应商探测的前提下，先覆盖当前已经落地的两条文本协议。
|
||
|
||
### Decision: 统一使用 `GeminiMessage.content[]` 承载文本图片消息
|
||
|
||
不新增新的消息结构，继续复用：
|
||
|
||
```ts
|
||
type GeminiMessagePart =
|
||
| { type: 'text'; text: string }
|
||
| { type: 'image_url'; image_url: { url: string } };
|
||
```
|
||
|
||
原因：
|
||
|
||
- 现有 OpenAI 兼容消息已经能直接使用 `image_url`
|
||
- 现有 Google 协议转换器已经能把 `image_url` 转成 `inline_data`
|
||
- 这条路径对聊天与 Agent 都可复用
|
||
|
||
### Decision: 先优先支持可直接引用的图片来源
|
||
|
||
第一阶段支持以下来源：
|
||
|
||
- 聊天抽屉上传得到的图片附件
|
||
- 画布分析/Agent 选择上下文中的图片 URL
|
||
- 已存在的 `data:`、缓存 URL、远程 URL
|
||
|
||
对于 Google 协议，继续依赖现有 `toGoogleInlineData()` 在发送前转码。
|
||
|
||
### Decision: 保留参考图片占位说明，但不再仅靠占位符
|
||
|
||
Agent 原有的“参考图片说明文字”仍可保留，帮助模型理解上下文，但它不应代替真实图片输入。
|
||
|
||
最终消息结构应同时包含：
|
||
|
||
- 文本说明
|
||
- 图片内容 part
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 第三方 OpenAI 兼容供应商未必真的支持 vision，即使接口名是 `chat/completions`
|
||
- Mitigation: 第一阶段仍以绑定能力位控制，必要时允许后续做供应商级覆盖
|
||
- 将本地图片转为 `data:` 或 Google `inline_data` 可能增大请求体
|
||
- Mitigation: 第一阶段不处理超大图上传，后续通过 Gemini Files API / OpenAI file 引用扩展
|
||
- Agent 消息结构从纯文本变成多 part 后，旧的日志和调试输出可能不再完整反映实际请求
|
||
- Mitigation: 为消息组装层增加最小调试信息与测试覆盖
|
||
|
||
## Migration Plan
|
||
|
||
1. 为文本 binding 增加图片输入能力声明与推断
|
||
2. 改造聊天服务，允许在支持的文本 binding 下发送附件图片
|
||
3. 改造 Agent 默认执行链，将参考图片拼进用户消息
|
||
4. 改造 `ai_analyze` 相关入口，透传图片内容而不是只透传占位符
|
||
5. 补充最小测试，覆盖 OpenAI 与 Google 两条路径
|
||
|
||
## Open Questions
|
||
|
||
- 是否需要在 UI 上对“当前文本模型支持看图”做显式提示
|
||
- 第三方自定义文本协议是否需要在设置页允许手动关闭 vision 能力
|