133 lines
7.2 KiB
Markdown
133 lines
7.2 KiB
Markdown
# 通用附件管线
|
||
|
||
## 使用位置
|
||
|
||
控制台 → **站点配置 → 输入处理 → 通用附件 / 超长输入**。
|
||
|
||
- 通用附件开关独立于超长文本处理开关。
|
||
- 配置附件数量、单文件和累计大小、允许类型、上传方式顺序、确认预算和错误节点选择器。
|
||
- 元素选择器增加可选的 `composer_root`,限制自动文件输入框查找及附件观察范围;指定 `file_input` 时优先使用指定入口。
|
||
- 超长输入的“处理策略”和“生成格式”在 UI 分开显示;仍写回旧 `temp_file_type`,兼容现有预设和编辑器。
|
||
- 类型留空只表示不加额外类型限制,**不代表网站/模型支持所有文件**。没有就绪预览的网站需要配置附件预览选择器。iframe/shadow-root 等特殊页面仍可能需要站点适配,未增加自动穿透能力。
|
||
|
||
## 配置与兼容
|
||
|
||
```json
|
||
{
|
||
"file_paste": {
|
||
"enabled": false,
|
||
"threshold": 50000,
|
||
"temp_file_type": "txt",
|
||
"attachments": {
|
||
"enabled": true,
|
||
"max_count": 8,
|
||
"max_file_mb": 20,
|
||
"max_total_mb": 50,
|
||
"allowed_types": ["image/*", ".pdf", ".docx", ".txt", "audio/*", "video/*"],
|
||
"transport_order": ["file_input", "cdp_drop", "js_drop", "file_clipboard"],
|
||
"ready_timeout": 30,
|
||
"error_selectors": [".upload-card[data-state='error']"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
未配置 `attachments` 的旧预设使用运行时默认值,读取旧配置不会批量写入新字段。`allowed_types` 默认为空列表。安全上限:32 个附件、单文件 100 MiB、总量 200 MiB、确认预算 180 秒;有效值会规范化到此范围内。UI 中 MB 按 1024² 字节计算。生成的长文本文件与用户附件共享数量/字节配额。
|
||
|
||
**行为变化(有意收紧):**
|
||
|
||
1. 工作流中的附件准备默认全部成功或明确报错,不再忽略失败图片或截断超限附件。
|
||
2. Windows 图片默认上传原文件,而非像素剪贴板。依赖旧图片粘贴行为的站点,可以显式启用并前移 `image_clipboard`;该方式可能丢失动画、透明度与元数据。
|
||
3. 投递后未确认,不再换一种方式自动重传;网站拒绝、观察器不可用均停止发送。普通网页没有幂等键,不能承诺 exactly-once。
|
||
4. 超长文本转文件失败不再悄悄降级成普通文本。PDF 只生成文本层版本;ReportLab/字体失败时不再回退到图片型 PDF。
|
||
5. 旧 `upload_signal_timeout` / `upload_signal_grace` 字段保留读取,但新的上传等待使用 `attachments.ready_timeout`,UI 不再展示两个旧入口。发送后的确认配置保留原逻辑。
|
||
6. 现有 `UPLOAD_HISTORY_IMAGES` 开关也用于选择附件来源:开启时上传所选历史中的附件;关闭时沿用“最近一条带附件的用户消息”的语义。不是仅最后一条消息。
|
||
7. 旧 `extract_images_from_messages()` 工具仍保留兼容行为,但实际工作流已经改用严格的 `AttachmentBatch`。
|
||
|
||
## 支持的输入形式
|
||
|
||
OpenAI Chat 图片保持不变:
|
||
|
||
```json
|
||
{"type":"image_url","image_url":{"url":"https://example.com/image.png"}}
|
||
```
|
||
|
||
OpenAI 文件(也接受 `file_url` HTTP(S) 来源作为本项目扩展):
|
||
|
||
```json
|
||
{"type":"file","file":{"filename":"notes.txt","file_data":"data:text/plain;base64,aGVsbG8="}}
|
||
```
|
||
|
||
Responses 文件:
|
||
|
||
```json
|
||
{"type":"input_file","filename":"notes.txt","file_data":"data:text/plain;base64,aGVsbG8="}
|
||
```
|
||
|
||
Anthropic 文档:
|
||
|
||
```json
|
||
{"type":"document","source":{"type":"base64","media_type":"application/pdf","data":"完整PDF的base64"}}
|
||
```
|
||
|
||
`document.source` 也支持 `url` 和 `text`;text 会生成 UTF-8 文件。`input_image`、Anthropic `image` 块会规范化为图片引用。
|
||
|
||
音频数据:
|
||
|
||
```json
|
||
{"type":"input_audio","input_audio":{"format":"wav","data":"完整音频的base64"}}
|
||
```
|
||
|
||
音视频 URL(本项目接受的扩展内容块):
|
||
|
||
```json
|
||
{"type":"audio_url","audio_url":{"url":"https://example.com/audio.mp3"}}
|
||
{"type":"video_url","video_url":{"url":"https://example.com/video.mp4"}}
|
||
```
|
||
|
||
音频/文档等传入网站的是原文件,不自动转录、抽文本或转码。支持 URL/字节规范化不等于目标网站支持该文件。
|
||
|
||
**暂不支持:** `file_id`(尚无有权限隔离的文件登记服务)、任意本地路径、`file://`、非 base64 的 data URI。声明了附件但缺少数据会在协议边界返回 400;下载、内容校验或站点能力错误在工作流错误响应中返回对应 code。不是所有错误都能在 SSE 开始前预检。
|
||
|
||
## 实现分层
|
||
|
||
- `app/utils/attachments.py`:协议归一化、有序索引、资源准备、逐文件/总配额、请求资源 lease。
|
||
- `app/core/workflow/attachment_upload.py`:共享上传事务、限额预检和各 transport。
|
||
- `image_input.py`:保留旧入口名称的薄包装;图片与普通附件共享执行器。
|
||
- `text_input.py`:只负责长文本文件生产、输入焦点和提示语,上传交给同一个协调器。
|
||
- `attachment_monitor.py`:继续复用 DOM baseline、稳定窗口和取消;新增新鲜预览确认、可见错误节点、观察器丢失保护,等待改用 monotonic clock。
|
||
|
||
状态流程:
|
||
|
||
```text
|
||
准备 → not_dispatched(可尝试下一方式)
|
||
→ dispatched / unknown(只观察,不重传)
|
||
→ 新鲜附件预览 + 无 pending/error + 稳定窗口 → 就绪
|
||
→ 未确认 / 拒绝 / 取消 → 中止发送
|
||
```
|
||
|
||
不能仅凭 `input.files.length`、拖拽事件返回或旧同名附件判定就绪。失败后已有副作用的标签页标记错误,交给既有恢复机制。
|
||
|
||
## 安全和生命周期
|
||
|
||
- 复用受限公共 URL 下载器,不为用户附件附加浏览器凭证;继续逐跳校验远程重定向。
|
||
- HTTP 流式落盘并按实际字节限额,base64 解码前限额,图片仍做格式/像素/帧数校验。
|
||
- 普通文件不执行、不自动解压。MIME 探测仅做有限的常见格式识别,并保留后缀匹配语义;允许类型是能力配置,不是恶意文件扫描器。
|
||
- 存储采用请求目录 + 唯一附件目录,同名/重复内容不会覆盖或删除语义引用。
|
||
- 浏览器主机必须能访问上传文件的本地路径;远程 Chromium 文件传输未实现。
|
||
- 请求作用域负责准备失败/生成器退出时释放 lease;可能已投递的文件保留 15 分钟供浏览器异步读取。下次准备或旧清理任务触发时清扫过期目录;进程崩溃的孤立目录 24 小时后回收,不是实时后台定时删除。
|
||
- 图片/文档输入的错误不暴露 URL 查询参数、base64 或绝对路径。
|
||
- 输出媒体本地化和协议输出暂未重构,避免扩大回归范围。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python -m pip install -r requirements-dev.txt
|
||
python -m playwright install --with-deps chromium
|
||
python -m pytest -q tests/test_attachments.py tests/test_attachment_ui.py tests/test_attachment_browser.py
|
||
```
|
||
|
||
浏览器测试仅使用本地模拟 composer,不访问 AI 站点。缺少 Playwright 或浏览器时该文件会跳过;CI 若要求浏览器验证,应先安装上述依赖。
|
||
|
||
本次还在真实配置控制台确认了面板渲染,未发现 Vue 页面错误。没有验证登录态第三方站点的端到端上传,应先在测试预设试用,尤其是依赖 Windows 图片剪贴板或无标准附件预览的站点。
|