Files
universal-web-api/docs/attachment-and-cancellation-fix.md
T
2026-11-02 22:54:14 +08:00

56 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 附件误判与立即取消后重发:修复说明
## 修复范围
### 启动器代理:禁止重放已转发的请求
确认此前的应用层取消修复遗漏了启动器层。旧 `start.py` 将客户端断连导致的响应写入失败也放进重试循环,因此会把同一份缓存 POST 再次发给后端。旧代理也没有在等待首字节输出期间及时监听客户端断开。
现在持续检查客户端断开并关闭后端连接;一旦开始转发请求,不因断连、部分写入、后端 EOF 或一般 503 重放。只有连接尚未建立,或后端明确确认请求尚未进入路由执行、正在重启交接,才允许等待重试。
原先的取消屏蔽、有界工作线程清理、所有权检查和二级防风暴机制保留。工具调用 worker 对标签页恢复服务可见;活跃线程不会因请求记录压缩而失去跟踪;迟到的开始事件不再覆盖请求终态。
### 附件监视:正文不是上传状态
- 不再克隆和扫描整个输入区 Prompt 来匹配忙碌词。
- 排除输入控件、镜像、隐藏内容、常见文件名、文件正文预览和历史区域。
- 从附件状态区域、真实进度指示及发送状态采集证据;保留真实“读取中/解析中”阻断,即使发送按钮可用。
- 英文状态词使用边界匹配,中文默认使用进行中短语。
- 卡片和内层图片去重;本批附件未齐或任一附件仍忙碌/失败时,不提前发送。
- 正文变化、持续不变的忙碌词和无关 DOM mutation 不再刷新进展计时。观察器丢失、输入区整体更换不会借旧快照推断成功。
- 状态判断、阻断说明和等待共用忙碌证据;保留稳定窗口、无进展超时和固定总截止时间。
- 默认诊断不再输出 root Prompt 片段、文件正文或节点 title / aria-label 内容。快照以 `evidenceVersion=2` 标识;旧 `rootText` / `rootTextSample` 字段保留为空,自定义探针不应再依赖这些字段判断附件上传。
高级附件规则增加两个可选入口:「附件状态提示区域」「不参与附件检测的内容区域」。前后端保存、规范化与运行时已接通。没有给旧预设强行添加新字段;普通用户不必配置它们,也无需关闭 Tools 或避开“读取”等词。
### 附件失败不能变成空工具回复
- 标签页因同一任务失败进入 ERROR 时仍停止执行,但不再误称为任务所有权丢失并覆盖错误。
- 结构化流程先识别不可恢复的附件错误,不让停止检查抢先把它变成取消。
- 线性流程与非流聚合明确透传失败,不把失败后的空结果包装为成功。
- Tools 适配器保留原始错误码,而不是丢掉错误后解析空文本。
- 保留真实所有权变化、客户端取消和合法 TRY 恢复的安全边界。
## 验证
最终相关回归:**28 个测试文件,454 passed,72.50 秒**。另有 2 条 WebSocket 依赖弃用警告,无测试失败。这是相关测试集,不是全仓所有测试通过声明。
旧代码上的代理回归先失败,修复后通过:客户端写失败触发重放;首字节前取消未及时关闭后端连接。
本地真实 TCP 链路测试覆盖:启动代理 → Uvicorn → ASGI 中间件 → API 普通/Tools 生命周期 → 真实标签页池。使用约 162 万字符、6 条消息;取消后立即重发,不等待旧请求清理。检查旧 worker 退出、新请求完成、两次请求只执行两次、标签页恢复 IDLE、等待队列清空。
Chromium 本地页面覆盖:可见/隐藏镜像、文件名、文档预览、历史消息、编辑器内部 loading、真实状态文本、进度/错误、多文件、旧附件、输入区更换以及高级配置控件编辑。
执行器、结构化流程、聚合与 Tools 适配器测试覆盖原始附件错误保留。另有计时、监视器失联、终态竞争、活跃 worker 可见性、配置兼容回归。
**证据边界:供应商网页动作在 TCP 链路测试中被模拟;未连接用户的 Chatbox / SillyTavern 或已登录 DeepSeek 进行现场发送。不能据此承诺任意站点 DOM 都无需适配。UI 就绪推断也不是服务端解析完成证明。**
## 如何生效
1. 完全退出旧的 `start.py` / `start.bat` 启动器及其后端,再重新启动。只重启 API 子进程不够,旧代理代码仍在父启动器中。
2. 刷新管理页面,加载更新后的附件规则界面。
3. 在 Chatbox 保持原 Tools 设置,依次测试「立即中断 → 立即重发」和「输出中途停止 → 重发」。
4. 如仍异常,保留第一次停止前后的日志,特别是旧请求的取消、工作线程收尾与标签页释放;不需要提供密钥或完整 Prompt。
DeepSeek 唯一默认「主预设」、Gemini 四预设及已有工作流 UI 不变。