agent 模式补充文件功能已经实现
This commit is contained in:
wandering
657
.agents/docs/guides/系统事件流全景图.md
Normal file
657
.agents/docs/guides/系统事件流全景图.md
Normal file
@@ -0,0 +1,657 @@
|
||||
# 系统事件流全景图
|
||||
|
||||
> 最后更新: 2026-06-15
|
||||
> 用途: 排查 SSE 事件问题、提交流程中断、状态不一致等 Bug
|
||||
|
||||
---
|
||||
|
||||
## 一、核心概念
|
||||
|
||||
### 1.1 前后端状态映射
|
||||
|
||||
| 前端 `App.processState` | 后端 `AgentState` | 含义 |
|
||||
|---|---|---|
|
||||
| `idle` | `IDLE` | 初始状态，等待用户操作 |
|
||||
| `processing` | `EXTRACTING` | LLM 正在分析文件 |
|
||||
| `awaiting_supplement` | `AWAITING_SUPPLEMENT` | 信息不完整，等待用户补充 |
|
||||
| `submitting` | `SUBMITTING` | 正在提交到财务系统 |
|
||||
| `ready` | `READY` | 信息完整，可以提交 |
|
||||
| `submitting` | `SUBMITTING` | 正在提交到财务系统 |
|
||||
| `done` | `DONE` / `ERROR` | 流程结束（成功或失败） |
|
||||
|
||||
### 1.2 通信机制
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as 前端
|
||||
participant S as SSE连接
|
||||
participant B as 后端线程
|
||||
|
||||
F->>B: POST /api/agent/process/:sid
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid (SSE长连接)
|
||||
S-->>F: message: file_progress (轮询 file_events.log)
|
||||
S-->>F: message: llm_stream (轮询 llm_stream.log)
|
||||
S-->>F: message: agent_* (轮询 agent_events.log)
|
||||
S-->>F: message: done (检测到 result.json)
|
||||
S->>S: 连接关闭
|
||||
```
|
||||
|
||||
**关键约束**：
|
||||
- 后端所有处理接口均返回 `{status: "started"}`，实际工作在 daemon 线程中执行
|
||||
- SSE 通过每 0.5 秒轮询 4 个日志文件实现（非原生 SSE，是长轮询模拟）
|
||||
- `result.json` 的原子写入：先写 `.tmp`，再 `replace()` 重命名
|
||||
- SSE 超时：600 秒后自动断开
|
||||
|
||||
### 1.3 操作信号点清单
|
||||
|
||||
每个 API 操作涉及的信号文件生命周期如下。**新增或修改信号文件时必须同步更新此清单**。
|
||||
|
||||
| 序号 | 操作 | API 端点 | 线程启动时清理 | 一次写入且不被清理 | 轮次结束时写入 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 初始处理 | `POST /api/agent/process/:sid` | `llm_stream.log`, `agent_events.log`, `result.json` | `file_events.log`, `session.log` | `result.json` |
|
||||
| 2 | 补充文件 | `POST /api/agent/supplement/:sid` | `llm_stream.log`, `agent_events.log`, `result.json` | `file_events.log`, `session.log` | `result.json` |
|
||||
| 3 | 文字补充 | `POST /api/agent/user-supplement/:sid` | `llm_stream.log`, `agent_events.log`, `result.json` | `file_events.log`, `session.log` | `result.json` |
|
||||
| 4 | 强制提交 | `POST /api/agent/force-submit/:sid` | `llm_stream.log`, `agent_events.log`, `result.json` | `file_events.log`, `session.log` | `result.json` |
|
||||
| 5 | 手动财务提交 | `POST /api/submit-financial/:sid` | `llm_stream.log`, `agent_events.log`, `result.json` | `file_events.log`, `session.log` | `result.json` |
|
||||
|
||||
**信号点说明**：
|
||||
|
||||
| 信号文件 | 读/写方 | 生命周期 | 作用 |
|
||||
|---|---|---|---|
|
||||
| `result.json` | 后端线程写入，SSE 端点读取 | 每轮开始时删除，`finally` 块中原子写入 | SSE 检测到该文件即发射 `done` 事件并断开连接 |
|
||||
| `agent_events.log` | Agent 调度器追加写入，SSE 端点读取 | 每轮开始时删除，Agent 运行时持续追加 | 传递 agent 状态变化事件给前端 |
|
||||
| `llm_stream.log` | LLM 回调追加写入，SSE 端点读取 | 每轮开始时删除，LLM 运行时持续追加 | 传递 LLM 流式输出给前端 |
|
||||
| `file_events.log` | `pipeline_web` 追加写入，SSE 端点读取 | 会话内持续追加，不删除 | 传递文件处理进度给前端 |
|
||||
| `session.log` | `sse_handler` 追加写入，SSE 端点读取 | 会话内持续追加，不删除 | 传递普通日志行给前端 |
|
||||
|
||||
### 1.4 关键约束（修改代码前必读）
|
||||
|
||||
**约束 1：`result.json` 必须在每轮线程启动时删除**
|
||||
|
||||
SSE 端点通过检测 `result.json` 是否存在来判断任务是否完成。如果上一轮的 `result.json` 残留，SSE 会立即读到旧数据并发射 `done` 事件，导致前端断开连接，新任务的消息无法送达。
|
||||
|
||||
- 实现位置：`_run_agent_task()` 的 `try` 块开头
|
||||
- 删除时机：在 `install_log_collector()` 之后、`task_fn()` 执行之前
|
||||
- 写入位置：`finally` 块中统一写入（唯一写入点）
|
||||
- 写入规则：`finally` 始终执行原子写入，不再有条件判断
|
||||
- `_emit_ready_and_submit` 只返回 result 字典，不写入文件
|
||||
|
||||
**约束 2：`result.json` 的写入必须使用 `finally` 块**
|
||||
|
||||
无论任务成功或失败，SSE 端点都需要 `result.json` 来发送 `done` 事件。如果仅在成功路径写入，异常时 SSE 会一直轮询直到 600 秒超时，前端无反馈。
|
||||
|
||||
**约束 3：SSE 新建连接时，当前文件偏移必须从 0 开始**
|
||||
|
||||
`_run_agent_task` 在启动时删除 `llm_stream.log` 和 `agent_events.log`，确保 SSE 重新建立连接后从 0 偏移开始读取。如果文件不被删除，旧的事件会被重复发送给前端。
|
||||
|
||||
**约束 4：前端 SSE 连接的生命周期**
|
||||
|
||||
- 前端在每次 POST 请求返回 `{status: "started"}` 后立即创建新的 SSE 连接
|
||||
- 收到 `done` 事件后关闭连接
|
||||
- 旧的连接引用必须清理（`agent.js` 中的 `agentEventSource`）
|
||||
- 如果前端在 POST 之前就创建了 SSE 连接，会读到旧数据
|
||||
|
||||
---
|
||||
|
||||
## 二、场景一：用户提交材料 → LLM 分析完整 → 直接提交
|
||||
|
||||
### 2.1 时序图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as 前端
|
||||
participant S as SSE连接
|
||||
participant B as 后端线程
|
||||
participant A as Agent调度器
|
||||
|
||||
F->>F: startProcess()
|
||||
F->>B: POST /api/agent/process/:sid
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid
|
||||
|
||||
Note over B,A: 后台线程启动
|
||||
B->>A: extract_invoices()
|
||||
S-->>F: file_progress (processing/done)
|
||||
Note over S: 轮询 file_events.log
|
||||
|
||||
S-->>F: llm_stream (start/chunk/end)
|
||||
Note over S: 轮询 llm_stream.log
|
||||
|
||||
S-->>F: agent_state_change (state=extracting)
|
||||
Note over S: 轮询 agent_events.log
|
||||
|
||||
Note over A: _do_extraction_with_validation()<br/>LLM提取 → validator校验<br/>最多3次重试
|
||||
|
||||
S-->>F: agent_state_change (校验通过/未通过)
|
||||
|
||||
Note over A: can_submit == true
|
||||
|
||||
A->>A: state → READY
|
||||
A->>A: _emit_agent_event (agent_ready)
|
||||
A->>A: _emit_ready_and_submit()
|
||||
A->>A: run_financial_submit()
|
||||
|
||||
S-->>F: agent_ready
|
||||
|
||||
Note over B: 写入 result.json
|
||||
|
||||
S-->>F: done (携带 result)
|
||||
Note over S: 检测到 result.json
|
||||
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'done'
|
||||
F->>F: addChatMessage(成功)
|
||||
Note over B: remove_log_collector
|
||||
```
|
||||
|
||||
### 2.2 事件流清单
|
||||
|
||||
| 序号 | 事件类型 | 来源文件 | 触发时机 | 前端处理 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | `file_progress` | `file_events.log` | 每个文件处理开始/完成 | 更新文件状态 UI |
|
||||
| 2 | `llm_stream` | `llm_stream.log` | LLM 流式输出 | 显示聊天气泡 |
|
||||
| 3 | `agent_state_change` | `agent_events.log` | 状态变为 `extracting` | 显示瞬态状态提示 |
|
||||
| 4 | `agent_state_change` | `agent_events.log` | 校验通过/未通过 | 更新瞬态状态 |
|
||||
| 5 | `agent_ready` | `agent_events.log` | 双重校验通过 | 由 `done` 事件统一处理 |
|
||||
| 6 | `done` | SSE 检测到 `result.json` | 流程结束 | 根据 `result` 判断终态 |
|
||||
|
||||
### 2.3 result.json 结构（成功路径）
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"agent_ready": true,
|
||||
"submit_ok": true,
|
||||
"round": 1,
|
||||
"message": "信息完整，已自动提交到财务系统"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、场景二：用户提交材料 → 需补充 → 用户上传文件
|
||||
|
||||
### 3.1 时序图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as 前端
|
||||
participant S as SSE连接
|
||||
participant B as 后端线程
|
||||
participant A as Agent调度器
|
||||
|
||||
Note over F,A: 阶段1: 初次分析
|
||||
F->>B: POST /api/agent/process/:sid
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid
|
||||
|
||||
S-->>F: agent_state_change (state=extracting)
|
||||
|
||||
Note over A: can_submit == false
|
||||
|
||||
A->>A: state → AWAITING_SUPPLEMENT
|
||||
|
||||
S-->>F: agent_request_supplement
|
||||
|
||||
Note over B: 写入 result.json<br/>(waiting_for_supplement=true)
|
||||
|
||||
S-->>F: done
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'awaiting_supplement'
|
||||
F->>F: showStatus('请补充')
|
||||
F->>F: showAgentRequest()
|
||||
Note over B: remove_log_collector
|
||||
|
||||
Note over F,A: 阶段2: 用户上传补充文件
|
||||
F->>F: 用户点击"上传补充材料"
|
||||
F->>F: 文件上传完成
|
||||
F->>F: handleSupplementUpload(newFilenames)
|
||||
F->>B: POST /api/agent/supplement/:sid<br/>{files: [...]}
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid
|
||||
|
||||
Note over B: 新后台线程启动
|
||||
|
||||
A->>A: add_supplement()<br/>(记录文件名, 发射收到事件)
|
||||
|
||||
S-->>F: agent_supplement_received
|
||||
|
||||
A->>A: extract_invoices()<br/>(重新提取所有文件)
|
||||
A->>A: run_agent_round(new_files=[...])
|
||||
Note over A: 加载上一轮结果作为<br/>previous_analysis
|
||||
|
||||
S-->>F: agent_state_change (state=extracting)
|
||||
|
||||
Note over A: LLM提取 → 校验循环
|
||||
|
||||
alt 分支A: 补充后仍不完整
|
||||
S-->>F: agent_request_supplement
|
||||
S-->>F: done (waiting=true)
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'awaiting_supplement'
|
||||
else 分支B: 补充后完整
|
||||
Note over A: can_submit == true
|
||||
A->>A: state → READY
|
||||
A->>A: _emit_ready_and_submit()
|
||||
S-->>F: agent_ready
|
||||
S-->>F: done (submit_ok=true)
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'done'
|
||||
F->>F: addChatMessage(成功)
|
||||
end
|
||||
```
|
||||
|
||||
### 3.2 事件流清单（补充文件路径）
|
||||
|
||||
| 序号 | 事件类型 | 来源文件 | 触发时机 | 前端处理 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | `agent_supplement_received` | `agent_events.log` | 收到补充文件列表 | 显示"已收到补充文件" |
|
||||
| 2 | `agent_state_change` | `agent_events.log` | 开始重新分析 | 显示瞬态状态 |
|
||||
| 3 | `agent_request_supplement` | `agent_events.log` | 仍不完整 | 更新补充请求面板 |
|
||||
| 4 | `agent_ready` | `agent_events.log` | 校验通过 | 由 `done` 统一处理 |
|
||||
| 5 | `done` | SSE 检测到 `result.json` | 流程结束 | 判断终态 |
|
||||
|
||||
### 3.3 result.json 结构（需补充）
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"agent_ready": false,
|
||||
"agent_state": "awaiting_supplement",
|
||||
"round": 1,
|
||||
"waiting_for_supplement": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、场景三：用户提交材料 → 需补充 → 用户通过对话提供信息
|
||||
|
||||
### 4.1 时序图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as 前端
|
||||
participant S as SSE连接
|
||||
participant B as 后端线程
|
||||
participant A as Agent调度器
|
||||
|
||||
Note over F,A: 阶段1: 初次分析
|
||||
F->>B: POST /api/agent/process/:sid
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid
|
||||
|
||||
S-->>F: agent_request_supplement
|
||||
S-->>F: done (waiting=true)
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'awaiting_supplement'
|
||||
Note over B: remove_log_collector
|
||||
|
||||
Note over F,A: 阶段2: 用户输入文字
|
||||
F->>F: 用户在输入框输入文字
|
||||
F->>F: handleUserSupplement()
|
||||
F->>B: POST /api/agent/user-supplement/:sid<br/>{text: "..."}
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid
|
||||
|
||||
Note over B: 新后台线程启动
|
||||
|
||||
S-->>F: agent_supplement_received
|
||||
|
||||
A->>A: process_user_text_supplement()
|
||||
A->>A: process_user_supplement()<br/>(LLM解析用户文字)
|
||||
|
||||
S-->>F: llm_stream (解析过程)
|
||||
|
||||
A->>A: merge_supplement_into_info()<br/>(合并到 extracted_info)
|
||||
Note over A: 保存到缓存文件
|
||||
|
||||
A->>A: run_agent_round()<br/>(重新校验)
|
||||
|
||||
S-->>F: agent_state_change<br/>(state=extracting, 正在重新校验)
|
||||
|
||||
alt 分支A: 补充后仍不完整
|
||||
S-->>F: agent_request_supplement
|
||||
S-->>F: done (waiting=true)
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'awaiting_supplement'
|
||||
else 分支B: 补充后完整
|
||||
Note over A: can_submit == true
|
||||
A->>A: state → READY
|
||||
A->>A: _emit_ready_and_submit()
|
||||
S-->>F: agent_ready
|
||||
S-->>F: done (submit_ok=true)
|
||||
F->>F: es.close()
|
||||
F->>F: App.processState = 'done'
|
||||
F->>F: addChatMessage(成功)
|
||||
end
|
||||
```
|
||||
|
||||
### 4.2 事件流清单（文字补充路径）
|
||||
|
||||
| 序号 | 事件类型 | 来源文件 | 触发时机 | 前端处理 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | `agent_supplement_received` | `agent_events.log` | 收到用户文字 | 显示"已收到补充" |
|
||||
| 2 | `llm_stream` | `llm_stream.log` | LLM 解析用户文字 | 显示解析过程 |
|
||||
| 3 | `agent_state_change` | `agent_events.log` | 开始重新校验 | 显示"正在重新校验" |
|
||||
| 4 | `agent_request_supplement` | `agent_events.log` | 仍不完整 | 更新补充请求 |
|
||||
| 5 | `agent_ready` | `agent_events.log` | 校验通过 | 由 `done` 统一处理 |
|
||||
| 6 | `done` | SSE 检测到 `result.json` | 流程结束 | 判断终态 |
|
||||
|
||||
---
|
||||
|
||||
## 五、强制提交流程
|
||||
|
||||
### 5.1 时序图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as 前端
|
||||
participant S as SSE连接
|
||||
participant B as 后端线程
|
||||
|
||||
F->>F: handleForceSubmit()
|
||||
F->>F: App.forceSubmitting = true
|
||||
F->>B: POST /api/agent/force-submit/:sid
|
||||
B-->>F: {status: "started"}
|
||||
F->>S: GET /api/logs/:sid
|
||||
|
||||
Note over B: 后台线程启动
|
||||
|
||||
B->>B: force_submit()<br/>(state → READY)
|
||||
|
||||
S-->>F: agent_force_submit
|
||||
|
||||
B->>B: run_financial_submit()
|
||||
|
||||
Note over B: 写入 result.json
|
||||
|
||||
S-->>F: done
|
||||
F->>F: es.close()
|
||||
F->>F: App.forceSubmitting = false
|
||||
F->>F: App.processState = 'done'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、错误处理路径
|
||||
|
||||
### 6.1 错误场景和事件
|
||||
|
||||
| 错误场景 | 后端行为 | 发射事件 | 前端表现 |
|
||||
|---|---|---|---|
|
||||
| LLM 提取异常 | `state → ERROR` | `agent_error` | 聊天显示错误，`processState → 'done'` |
|
||||
| 规则校验 3 次失败 | 返回最后一次结果，继续语义判断 | `agent_state_change` | 依赖 `can_submit` 字段决定 |
|
||||
| 轮次超限 (5 轮) | `state → ERROR` | `agent_max_rounds` | 聊天显示错误，可强制提交 |
|
||||
| 财务提交失败 | `result.submit_ok = false` | 无独立事件 | `done` 事件携带错误信息 |
|
||||
| SSE 连接中断 | 无 | `es.onerror` 触发 | 显示"连接中断" |
|
||||
| 超时 (600s) | SSE 轮询循环退出 | 连接自然断开 | 连接断开 |
|
||||
|
||||
### 6.2 agent_error 事件结构
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "agent_error",
|
||||
"message": "LLM 提取失败: ..."
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 agent_max_rounds 事件结构
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "agent_max_rounds",
|
||||
"message": "已达到最大轮次 (5)，请检查信息或强制提交"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、状态机完整图
|
||||
|
||||
### 7.1 后端 AgentState 状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> IDLE
|
||||
|
||||
IDLE --> EXTRACTING: POST /api/agent/process\nPOST /api/agent/supplement\nPOST /api/agent/user-supplement
|
||||
|
||||
EXTRACTING --> READY: can_submit == true
|
||||
EXTRACTING --> AWAITING_SUPPLEMENT: can_submit == false
|
||||
EXTRACTING --> ERROR: 异常 / 轮次超限
|
||||
|
||||
READY --> SUBMITTING: _emit_ready_and_submit()
|
||||
SUBMITTING --> DONE: 财务提交完成
|
||||
|
||||
AWAITING_SUPPLEMENT --> EXTRACTING: 用户补充文件/文字
|
||||
|
||||
READY: 准备提交\n(终态保护)
|
||||
SUBMITTING: 财务提交中\n(终态保护)
|
||||
DONE: 终态\n(终态保护)
|
||||
ERROR: 错误状态\n(可强制提交)
|
||||
|
||||
note right of EXTRACTING
|
||||
LLM 提取 + validator 校验\n最多 3 次重试
|
||||
end note
|
||||
```
|
||||
|
||||
### 7.2 前端 processState 状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> idle
|
||||
|
||||
idle --> processing: startProcess()
|
||||
|
||||
processing --> awaiting_supplement: done事件\nresult.waiting_for_supplement
|
||||
processing --> done: done事件\nresult.ok
|
||||
|
||||
awaiting_supplement --> processing: 补充文件或文字
|
||||
awaiting_supplement --> submitting: 强制提交
|
||||
|
||||
submitting --> done: done事件
|
||||
|
||||
done: 流程结束
|
||||
idle: 初始状态
|
||||
processing: 处理中
|
||||
awaiting_supplement: 等待补充
|
||||
submitting: 提交中
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、SSE 事件类型完整参考
|
||||
|
||||
### 8.1 Agent 事件 (agent_events.log)
|
||||
|
||||
| 事件类型 | 数据结构 | 触发条件 |
|
||||
|---|---|---|
|
||||
| `agent_state_change` | `{type, state, round, attempt, message}` | 状态切换 |
|
||||
| `agent_ready` | `{type, round, message}` | 双重校验通过 |
|
||||
| `agent_request_supplement` | `{type, round, missing_fields, missing_materials, semantic_issues, suggestion}` | 校验未通过 |
|
||||
| `agent_supplement_received` | `{type, files}` | 收到用户补充 |
|
||||
| `agent_force_submit` | `{type, message}` | 用户强制提交 |
|
||||
| `agent_error` | `{type, message}` | 提取失败 |
|
||||
| `agent_max_rounds` | `{type, message}` | 达到最大轮次 |
|
||||
|
||||
### 8.2 文件进度事件 (file_events.log)
|
||||
|
||||
| 事件类型 | 数据结构 | 触发条件 |
|
||||
|---|---|---|
|
||||
| `file_progress` | `{type, file, status, summary?, error?}` | 文件处理状态变更 |
|
||||
|
||||
`status` 取值: `processing` / `done` / `cached` / `error`
|
||||
|
||||
### 8.3 LLM 流式事件 (llm_stream.log)
|
||||
|
||||
| 事件类型 | 数据结构 | 触发条件 |
|
||||
|---|---|---|
|
||||
| `llm_stream` | `{type, phase, text?}` | LLM 输出流 |
|
||||
|
||||
`phase` 取值: `start` / `reasoning` / `chunk` / `end` / `error`
|
||||
|
||||
### 8.4 完成事件 (SSE 直接发送)
|
||||
|
||||
| 事件类型 | 数据结构 | 触发条件 |
|
||||
|---|---|---|
|
||||
| `done` | `{type, result: {...}}` | `result.json` 出现 |
|
||||
|
||||
---
|
||||
|
||||
## 九、常见问题排查清单
|
||||
|
||||
### 9.1 SSE 事件丢失
|
||||
|
||||
**症状**: 前端没有收到预期的 agent 事件
|
||||
|
||||
**排查步骤**:
|
||||
1. 检查 `agent_events.log` 是否存在、是否有内容
|
||||
2. 检查 SSE 连接是否建立成功（浏览器 Network 面板）
|
||||
3. 确认 `sse_handler.install_log_collector()` 是否被调用
|
||||
4. 确认 `remove_log_collector()` 是否过早调用
|
||||
|
||||
### 9.2 提交流程中断
|
||||
|
||||
**症状**: 流程在某个中间状态卡住，没有 `done` 事件
|
||||
|
||||
**排查步骤**:
|
||||
1. 检查 `result.json` 是否被写入
|
||||
2. 检查后台线程是否异常退出（查看 `session.log`）
|
||||
3. 确认 `finally` 块中的 `result.json` 写入逻辑是否执行
|
||||
4. 检查是否触发了 600 秒超时
|
||||
|
||||
### 9.3 状态不一致
|
||||
|
||||
**症状**: 前端 `processState` 和后端 `AgentState` 不匹配
|
||||
|
||||
**排查步骤**:
|
||||
1. 对比 `agent_events.log` 中的状态变更序列
|
||||
2. 检查前端是否正确处理了 `done` 事件
|
||||
3. 确认 SSE 连接是否在适当时机关闭和重建
|
||||
4. 检查 `App.agentEventSource` 引用是否正确清理
|
||||
|
||||
### 9.4 补充流程不触发
|
||||
|
||||
**症状**: 用户上传补充文件或输入文字后，没有重新分析
|
||||
|
||||
**排查步骤**:
|
||||
1. 确认 `processState` 是否为 `awaiting_supplement`
|
||||
2. 检查补充 API 是否返回 `{status: "started"}`
|
||||
3. 检查新 SSE 连接是否成功建立
|
||||
4. 确认 `add_supplement()` 或 `process_user_text_supplement()` 是否被调用
|
||||
|
||||
### 9.5 补充材料后前端无任何消息（`result.json` 残留问题）
|
||||
|
||||
**症状**: 第二轮及之后的补充材料提交后，前端完全没有任何消息显示，状态栏不更新，聊天区无新增消息。后台日志显示处理正常完成。
|
||||
|
||||
**根因**: `_run_agent_task` 在每轮启动时未清理上一轮的 `result.json`。SSE 端点轮询时立即检测到旧的 `result.json`，直接发射 `done` 事件并关闭连接，前端断开后无法接收新任务的消息。
|
||||
|
||||
**排查步骤**:
|
||||
1. 检查 session 目录中 `result.json` 的修改时间 — 如果早于当前轮次开始时间，说明是残留文件
|
||||
2. 检查浏览器 Network 面板中 SSE 连接 — 是否在建立后立即收到 `done` 事件
|
||||
3. 确认 `_run_agent_task` 是否在启动时清理了 `result.json`
|
||||
|
||||
**修复**: 在 `_run_agent_task` 的 `try` 块开头同时清理 `llm_stream.log`、`agent_events.log` 和 `result.json` 三个文件。
|
||||
|
||||
**详细记录**: 参见 `.agents/docs/error-experience/2026-06-15-补充材料SSE立即读到旧result.json导致前端无消息.md`
|
||||
|
||||
---
|
||||
|
||||
## 十、关键文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|---|---|
|
||||
| `src/web/static/js/process.js` | 主提交流程入口，SSE 事件分发 |
|
||||
| `src/web/static/js/agent.js` | Agent 事件处理，补充/强制提交逻辑 |
|
||||
| `src/web/static/js/state.js` | 全局状态管理 |
|
||||
| `src/web/routes.py` | 后端路由，后台线程启动 |
|
||||
| `src/agent/orchestrator.py` | Agent 调度器，状态机，校验循环 |
|
||||
| `src/web/sse_handler.py` | SSE 日志收集器 |
|
||||
| `src/web/pipeline_web.py` | 发票提取管道，财务提交 |
|
||||
|
||||
---
|
||||
|
||||
## 十一、文件生命周期与操作信号点
|
||||
|
||||
### 11.1 单轮处理的完整文件生命周期
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant API as 路由层
|
||||
participant RT as _run_agent_task
|
||||
participant TF as task_fn
|
||||
participant SS as _emit_ready_and_submit
|
||||
participant SSE as SSE 端点
|
||||
|
||||
Note over API: 1. 创建 handler
|
||||
API->>API: install_log_collector(session_dir)
|
||||
Note over API: 创建 SSE 日志收集器<br/>随即开始写入 session.log
|
||||
|
||||
API->>RT: threading.Thread(target=_run_agent_task)
|
||||
|
||||
Note over RT: 2. 清理残留文件
|
||||
RT->>RT: unlink(llm_stream.log)
|
||||
RT->>RT: unlink(agent_events.log)
|
||||
RT->>RT: unlink(result.json)
|
||||
|
||||
Note over RT: 3. 执行任务
|
||||
RT->>TF: task_fn(session_dir, config)
|
||||
|
||||
Note over TF: 执行期间各个文件由对应模块写入：
|
||||
TF-->>TF: file_events.log (pipeline_web)
|
||||
TF-->>TF: llm_stream.log (LLM 回调)
|
||||
TF-->>TF: agent_events.log (Agent 调度器)
|
||||
|
||||
TF-->>RT: 返回 (agent_session, 占位 result)
|
||||
|
||||
alt 成功路径 (READY)
|
||||
RT->>SS: _emit_ready_and_submit()
|
||||
Note over SS: 发射 agent_ready 事件<br/>执行财务提交<br/>返回 result 字典
|
||||
SS-->>RT: result 字典
|
||||
Note over RT: result = {...}
|
||||
else 需补充路径 (AWAITING_SUPPLEMENT)
|
||||
Note over RT: result = {waiting_for_supplement: true}
|
||||
else 异常路径
|
||||
Note over RT: result = {ok: false, error: ...}
|
||||
end
|
||||
|
||||
Note over RT: 4. finally 块 — 唯一写入点
|
||||
RT->>RT: 原子写入 result.json (.tmp → replace)
|
||||
|
||||
RT->>RT: remove_log_collector(handler)
|
||||
|
||||
Note over SSE: 5. SSE 端点检测
|
||||
SSE->>SSE: 轮询检测到 result.json
|
||||
SSE-->>SSE: 发射 done 事件
|
||||
SSE->>SSE: break 退出轮询
|
||||
```
|
||||
|
||||
### 11.2 各阶段信号文件状态
|
||||
|
||||
| 阶段 | `result.json` | `llm_stream.log` | `agent_events.log` | `file_events.log` | `session.log` |
|
||||
|---|---|---|---|---|---|
|
||||
| 会话创建 | 不存在 | 不存在 | 不存在 | 不存在 | 不存在 |
|
||||
| `install_log_collector` 后 | 不存在 | 不存在 | 不存在 | 不存在 | 开始写入 |
|
||||
| `_run_agent_task` 清理后 | 已删除 | 已删除 | 已删除 | 保持 | 保持 |
|
||||
| 文件提取中 | 不存在 | 不存在 | 不存在 | 持续追加 | 持续追加 |
|
||||
| LLM 提取中 | 不存在 | 持续追加 | 持续追加 | 保持 | 持续追加 |
|
||||
| 校验中 | 不存在 | 保持 | 持续追加 | 保持 | 持续追加 |
|
||||
| 任务完成 (READY) | 已写入 | 保持 | 保持 | 保持 | 保持 |
|
||||
| 任务完成 (需补充) | 已写入 | 保持 | 保持 | 保持 | 保持 |
|
||||
| 任务异常 | 已写入 | 保持 | 保持 | 保持 | 保持 |
|
||||
| SSE done 事件后 | 保持 | 保持 | 保持 | 保持 | 保持 |
|
||||
|
||||
### 11.3 新增信号文件检查清单
|
||||
|
||||
当需要在系统中新增一个信号文件（如 `submit_progress.log`）时，必须检查以下事项：
|
||||
|
||||
1. **写入方**：哪个模块负责写入？写入时机是什么？
|
||||
2. **读取方**：SSE 端点是否需要轮询？前端是否需要处理？
|
||||
3. **清理时机**：是否需要在 `_run_agent_task` 中清理？如果不需要，为什么？
|
||||
4. **原子性**：写入是否需要 `.tmp` + `replace` 模式？
|
||||
5. **轮询偏移**：SSE 端点是否需要跟踪该文件的读取偏移？
|
||||
6. **更新本文档**：在 1.3 操作信号点清单中新增一行，在 11.2 文件状态表中新增一列
|
||||
7. **更新 `_run_agent_task`**：如果需要清理，在清理循环中添加文件名
|
||||
8. **更新前端**：在 `sse.js` 或 `agent.js` 中添加对应的事件处理器
|
||||
Reference in New Issue
Block a user