agent 模式补充文件功能已经实现

.agents/docs/error-experience/2026-06-15-补充材料SSE立即读到旧result.json导致前端无消息.md

@@ -0,0 +1,60 @@
+---
+last_reviewed: 2026-06-15
+---
+
+# 补充材料提交后 SSE 立即读到旧 result.json 导致前端无消息
+
+## 错误现象
+
+- 第二次补充材料提交后，前端没有任何消息显示
+- 状态栏不更新，聊天区无新增消息
+- 后台日志显示处理正常完成（LLM 提取、校验、Bot 提交均成功）
+- 前端像是"卡住"了一样，没有报错也没有反馈
+
+## 触发条件
+
+1. 第一轮处理或第一轮补充材料完成，`result.json` 已写入 session 目录
+2. 用户再次补充材料，触发新一轮处理
+3. 前端创建新的 SSE 连接到 `/api/logs/<session_id>`
+4. SSE 端点轮询时立即检测到旧的 `result.json`，直接发射 `done` 事件并关闭连接
+5. 前端断开 SSE，但后台线程仍在执行新任务
+
+## 根因
+
+`_run_agent_task` 在每次任务启动时只清理了 `llm_stream.log`，未清理 `result.json` 和 `agent_events.log`。
+
+```python
+# 修复前 - 只清理了 llm_stream.log
+try:
+    (session_dir / "llm_stream.log").unlink(missing_ok=True)
+except Exception:
+    pass
+```
+
+SSE 端点 (`/api/logs/<session_id>`) 在 `generate()` 中轮询检查 `result.json` 是否存在，一旦存在就发射 `done` 事件并 `break` 退出循环。旧的 `result.json` 未被清理，导致 SSE 连接在任务实际开始前就结束了。
+
+## 修复
+
+在 `_run_agent_task` 开头统一清理三个残留文件：
+
+```python
+# 修复后 - 同时清理三个残留文件
+for fname in ("llm_stream.log", "agent_events.log", pipeline_web.SESSION_RESULT_FILE):
+    try:
+        (session_dir / fname).unlink(missing_ok=True)
+    except Exception:
+        pass
+```
+
+- `llm_stream.log` — LLM 流式日志
+- `agent_events.log` — Agent 事件日志（避免旧事件被重放）
+- `result.json` — 处理结果文件（避免 SSE 立即读到旧结果）
+
+## 影响范围
+
+所有使用 `_run_agent_task` 的端点均受影响：
+- `/api/process/<session_id>` — 初始处理
+- `/api/agent/supplement/<session_id>` — 补充文件
+- `/api/agent/user-supplement/<session_id>` — 文字补充
+- `/api/agent/force-submit/<session_id>` — 强制提交
+- `/api/submit-financial/<session_id>` — 手动财务提交