469 lines
17 KiB
Markdown
469 lines
17 KiB
Markdown
# Harness 异常处理：Loop 内 vs Loop 外
|
||
|
||
**日期**：2026-07-30
|
||
**范围**：诊断路径（`intent=DIAGNOSIS`）上 ReactAgent ReAct 循环内外的异常、受控停止、降级与终态
|
||
**读者**：已读 E2E 全流程 / 运行控制，需要把「失败时系统到底怎么走」串成一张图
|
||
|
||
**关联文档**：
|
||
|
||
- [Harness 失败图谱](./Harness失败图谱-异常-停止-降级与终态.md)（失败类型总览）
|
||
- [Harness 生命周期与状态](./Harness生命周期与状态.md)（RunState / CollectionState）
|
||
- [信息增益停止](./Harness信息增益停止-让无证据诊断正常收敛.md)（SATURATED / STOP_REQUIRED）
|
||
|
||
---
|
||
|
||
## 0. 先记住一张总图
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph app["Application 编排"]
|
||
UC[ChatApplicationUseCase]
|
||
EX[DiagnosisChatExecutor]
|
||
end
|
||
|
||
subgraph agent["Agent 用例"]
|
||
UC2[DiagnosisAgentUseCase]
|
||
CE[controlledExecution]
|
||
RF[recoverInvalidDraft]
|
||
end
|
||
|
||
subgraph loop["ReactAgent ReAct Loop"]
|
||
MI[HarnessModelInterceptor]
|
||
LLM[ChatModel]
|
||
TI[HarnessToolInterceptor]
|
||
TB[ToolBoundary]
|
||
end
|
||
|
||
subgraph release["Release"]
|
||
REL[DiagnosisReleaseUseCase]
|
||
FB[SafeFallback / FALLBACK]
|
||
OK[SUCCESS 报告]
|
||
end
|
||
|
||
UC --> EX
|
||
EX --> UC2
|
||
UC2 -->|agent.call| loop
|
||
MI --> LLM
|
||
LLM -->|tool_call| TI
|
||
TI --> TB
|
||
TB -->|observation| LLM
|
||
|
||
loop -->|受控异常穿出| CE
|
||
CE -->|stopped draft=null| REL
|
||
loop -->|正常返回坏 draft| UC2
|
||
UC2 -->|DiagnosisAgentOutputException| RF
|
||
RF -->|有 observedFacts| REL
|
||
REL --> FB
|
||
REL --> OK
|
||
CE -->|取消/超时再抛| UC
|
||
RF -->|无 facts 再抛| UC
|
||
```
|
||
|
||
**一句话**：
|
||
|
||
| 区域 | 异常怎么处理 |
|
||
|------|----------------|
|
||
| **Loop 内** | 多数变成 **tool/model 侧 observation 或拦截**；少数 **受控异常穿出 loop** |
|
||
| **Loop 边界** | `controlledExecution`：受控停止 → `stopped`；不可控 → 包装/再抛 |
|
||
| **Loop 外（Executor）** | `recoverInvalidDraft`：坏 draft + 有事实 → FALLBACK；否则失败 |
|
||
| **Release** | 有 draft 走 Guard；无 draft / 非法 draft 走专用降级 |
|
||
| **Application** | 未消化异常 → `ChatFailureCode` + Run 终态落库 |
|
||
|
||
---
|
||
|
||
## 1. 状态有三层，不要混
|
||
|
||
异常处理会同时碰到三套状态，职责不同：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph core["Core 执行面"]
|
||
RS[RunState<br/>RUNNING / SUCCESS / FAILED<br/>CANCELLED / TIMED_OUT / BUDGET_EXHAUSTED]
|
||
end
|
||
subgraph prog["Progress 收集面"]
|
||
CS[CollectionState<br/>COLLECTING / SATURATED]
|
||
SR[DiagnosisStopReason]
|
||
end
|
||
subgraph out["对外发布面"]
|
||
RO[ReleaseOutcome<br/>SUCCESS / FALLBACK / FAILED / CANCELLED]
|
||
FT[FallbackType]
|
||
CF[ChatFailureCode]
|
||
end
|
||
RS -.->|"预算耗尽可并存"| RO
|
||
SR -.->|"有 facts 常映射"| FT
|
||
RO -.->|"失败粗码"| CF
|
||
```
|
||
|
||
| 层 | 枚举 | 回答的问题 |
|
||
|----|------|------------|
|
||
| Core | `RunState` | 这次 Run 技术上还能不能继续？ |
|
||
| Progress | `DiagnosisStopReason` / `CollectionState` | 证据收集为何停、是否已饱和？ |
|
||
| 发布 | `ReleaseOutcome` / `FallbackType` | 用户看到报告、降级还是失败？ |
|
||
| 协议失败 | `ChatFailureCode` | SSE failure 的粗粒度原因？ |
|
||
|
||
**典型组合**：
|
||
|
||
| 场景 | RunState | StopReason | ReleaseOutcome |
|
||
|------|----------|------------|----------------|
|
||
| 正常成功 | SUCCESS | — | SUCCESS |
|
||
| 信息饱和且有事实 | 常仍可 SUCCESS 收尾* | INFORMATION_SATURATED | FALLBACK / INSUFFICIENT_EVIDENCE |
|
||
| 预算耗尽且有事实 | BUDGET_EXHAUSTED | BUDGET_LIMIT_REACHED | FALLBACK / INSUFFICIENT_EVIDENCE |
|
||
| 预算耗尽且无事实 | BUDGET_EXHAUSTED | BUDGET_LIMIT_REACHED | FAILED |
|
||
| 客户端断开 | CANCELLED | — | CANCELLED / 可能无 done |
|
||
|
||
\*饱和后若 Agent 合法写完 draft 并过 Guard，也可能 SUCCESS；若 stopped 无 draft 则走 FALLBACK。
|
||
|
||
---
|
||
|
||
## 2. 架构位置：异常在哪一层被「接住」
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph L0["L0 协议"]
|
||
CTRL[ChatController / SSE]
|
||
end
|
||
subgraph L1["L1 Application"]
|
||
APP[ChatApplicationUseCase<br/>统一 catch → ChatFailureCode]
|
||
DEX[DiagnosisChatExecutor<br/>recoverInvalidDraft]
|
||
end
|
||
subgraph L2["L2 Agent 用例"]
|
||
DAU[DiagnosisAgentUseCase<br/>controlledExecution]
|
||
end
|
||
subgraph L3["L3 框架 Loop"]
|
||
RA[ReactAgent.call]
|
||
end
|
||
subgraph L4["L4 Interceptor / Boundary"]
|
||
MI[ModelInterceptor]
|
||
TI[ToolInterceptor]
|
||
TB[ToolBoundary]
|
||
CORE[DiagnosisHarnessCore]
|
||
end
|
||
|
||
CTRL --> APP --> DEX --> DAU --> RA
|
||
RA --> MI --> CORE
|
||
RA --> TI --> TB --> CORE
|
||
|
||
MI -.->|BudgetExceeded / RunAborted 上抛| DAU
|
||
TI -.->|多数 error observation 留在 loop| RA
|
||
TI -.->|CollectionStopped 上抛| DAU
|
||
DAU -.->|stopped| DEX
|
||
DAU -.->|Draft 契约异常| DEX
|
||
DEX -.->|未恢复| APP
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Loop 内：一次 ReAct 轮次里发生什么
|
||
|
||
### 3.1 正常成功路径（对照）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant DAU as DiagnosisAgentUseCase
|
||
participant RA as ReactAgent
|
||
participant MI as ModelInterceptor
|
||
participant LLM as ChatModel
|
||
participant TI as ToolInterceptor
|
||
participant TB as ToolBoundary
|
||
|
||
DAU->>RA: agent.call(input, config)
|
||
RA->>MI: interceptModel
|
||
MI->>MI: beforeModelCall 预算闸
|
||
MI->>LLM: handler.call
|
||
LLM-->>MI: tool_call
|
||
MI-->>RA: ModelResponse
|
||
RA->>TI: interceptToolCall
|
||
TI->>TI: 协议/重复/饱和检查
|
||
TI->>TB: invoke
|
||
TB-->>TI: READY + agentResult
|
||
TI-->>RA: 投影 observation
|
||
RA->>MI: interceptModel 第 2 轮
|
||
MI->>LLM: 写 Draft
|
||
LLM-->>MI: 文本 JSON
|
||
MI-->>RA: ModelResponse
|
||
RA-->>DAU: AssistantMessage
|
||
DAU->>DAU: 解析 DiagnosisDraft
|
||
DAU-->>DAU: completed(draft, progress)
|
||
```
|
||
|
||
### 3.2 Loop 内：Model 路径异常（会穿出 loop）
|
||
|
||
**触发点**：`HarnessModelInterceptor.interceptModel`
|
||
|
||
```text
|
||
beforeModelCall / handler.call / checkActive
|
||
→ BudgetExceededException
|
||
→ RunAbortedException（已终态、超时、取消）
|
||
→ 其它 RuntimeException（供应商错误等）
|
||
```
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant RA as ReactAgent
|
||
participant MI as ModelInterceptor
|
||
participant Core as DiagnosisHarnessCore
|
||
participant DAU as DiagnosisAgentUseCase
|
||
|
||
RA->>MI: interceptModel（第 N 次模型）
|
||
MI->>Core: beforeModelCall
|
||
Core-->>MI: throw BudgetExceeded / RunAborted
|
||
Note over MI: 不吞异常，不转 observation
|
||
MI-->>RA: 异常上抛
|
||
RA-->>DAU: agent.call 失败
|
||
DAU->>DAU: controlledExecution(e)
|
||
```
|
||
|
||
| 异常 | Loop 内是否消化 | 穿出后 |
|
||
|------|-----------------|--------|
|
||
| `BudgetExceededException` | 否 | → `stopped(BUDGET_LIMIT_REACHED)` |
|
||
| `RunAbortedException(BUDGET_EXHAUSTED)` | 否 | → 同上 |
|
||
| `RunAbortedException(CANCELLED/TIMED_OUT/…)` | 否 | controlledExecution **再抛** → Application |
|
||
| 其它未识别 | 否 | → `DiagnosisAgentOutputException(EXECUTION_FAILED)` |
|
||
|
||
### 3.3 Loop 内：Tool 路径（多数不穿出）
|
||
|
||
**触发点**：`HarnessToolInterceptor.interceptToolCall` + `ToolBoundary`
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
TC[收到 tool_call] --> SUP{是否证据工具?}
|
||
SUP -->|否| H[handler.call 旁路]
|
||
SUP -->|是| SAT{已 SATURATED 且 stop 已交付?}
|
||
SAT -->|是| EX[throw DiagnosisCollectionStoppedException]
|
||
SAT -->|否| PARSE[解析 Envelope / previous_observation]
|
||
PARSE -->|协议违规| REP[可修复 error observation<br/>或连续违规后 stop]
|
||
PARSE --> DUP{重复 scope?}
|
||
DUP -->|是| DUPR[DUPLICATE_SCOPE observation]
|
||
DUP -->|否| INV[ToolBoundary.invoke]
|
||
INV -->|READY| OBS[投影 modelObservation 回注]
|
||
INV -->|BUDGET_EXHAUSTED 等 error| ERR[error observation<br/>markBudgetLimitReached]
|
||
EX --> OUT[穿出 ReactAgent loop]
|
||
OBS --> LOOP[留在 loop，模型继续]
|
||
ERR --> LOOP
|
||
REP --> LOOP
|
||
DUPR --> LOOP
|
||
```
|
||
|
||
**设计选择**：
|
||
|
||
| 情况 | 策略 | 原因 |
|
||
|------|------|------|
|
||
| 工具执行失败、投影失败、结果过大 | **error observation 留在 loop** | 给模型一次感知/改写机会，不立刻整 run 崩 |
|
||
| 预算在 ToolBoundary 触顶 | **先 error observation** + progress 标记预算 | 本轮不强制撕开 loop；下一轮 model 的 `beforeModelCall` 会硬闸 |
|
||
| 信息饱和后仍要工具 | **`DiagnosisCollectionStoppedException` 穿出** | 收集已无价值，禁止空转 |
|
||
| 协议违规（未达阈值） | **repairable error observation** | 要求模型补 previous_observation 等 |
|
||
|
||
`ToolBoundary` 对预算的处理（**吞异常 → 错误码**，不抛给框架）：
|
||
|
||
```text
|
||
catch (RunAbortedException | BudgetExceededException)
|
||
→ ToolBoundaryResult.error(BUDGET_EXHAUSTED | RUN_INACTIVE)
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Loop 边界：`controlledExecution`
|
||
|
||
**位置**：`DiagnosisAgentUseCase`，包住 `agent.call(...)`。
|
||
|
||
**职责**：把「Harness 约定的受控停止」从异常栈（含 cause 链）捞出来，转成 **`DiagnosisAgentExecution.stopped`**；其余失败交给外层。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
E[catch Exception from agent.call] --> F1{cause 含 CollectionStopped?}
|
||
F1 -->|是| S1[stopped progress + stopReason]
|
||
F1 -->|否| F2{cause 含 RunAborted?}
|
||
F2 -->|是且 BUDGET_EXHAUSTED| S2[markBudgetLimitReached<br/>stopped BUDGET_LIMIT_REACHED]
|
||
F2 -->|是且其它终态| R1[再抛 RunAborted]
|
||
F2 -->|否| F3{BudgetExceeded 或 lifecycle 已预算耗尽?}
|
||
F3 -->|是| S2
|
||
F3 -->|否| N[return null]
|
||
N --> W[包装 DiagnosisAgentOutputException EXECUTION_FAILED]
|
||
S1 --> RET[正常 return 给 Executor]
|
||
S2 --> RET
|
||
```
|
||
|
||
| 输入信号 | 输出 |
|
||
|----------|------|
|
||
| `DiagnosisCollectionStoppedException` | `stopped(stopReason)`，`draft=null` |
|
||
| 预算耗尽类 | `stopped(BUDGET_LIMIT_REACHED)` |
|
||
| 取消 / 超时类 `RunAborted` | **不转 stopped，再抛** |
|
||
| 未知 | `null` → 包装执行失败异常 |
|
||
|
||
**结果形态**：
|
||
|
||
```text
|
||
completed(draft, progress) // 有合法草稿
|
||
stopped(progress, stopReason) // 无草稿，仅有进度快照
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Loop 外：坏 Draft 与 `recoverInvalidDraft`
|
||
|
||
**时机**：`agent.call` **已经返回**（或解析阶段），最终文本 **不是**合法 `DiagnosisDraft`。
|
||
|
||
**位置**：`DiagnosisChatExecutor` catch `DiagnosisAgentOutputException`。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[DiagnosisAgentOutputException] --> K{isDraftContractFailure?}
|
||
K -->|否 EXECUTION_FAILED| P1[再抛 → Application FAILED]
|
||
K -->|是 EMPTY/INVALID_JSON/SCHEMA| H{hasObservedFacts?}
|
||
H --> AUD[审计 agentDraftInvalid]
|
||
AUD --> H2{hasObservedFacts?}
|
||
H2 -->|否| P1
|
||
H2 -->|是| SSE[status SAFETY_VALIDATING]
|
||
SSE --> RID[releaseInvalidDraft progress]
|
||
RID --> FB[FALLBACK INSUFFICIENT_EVIDENCE]
|
||
```
|
||
|
||
要点（与常见误解对照）：
|
||
|
||
| 误解 | 实际 |
|
||
|------|------|
|
||
| recover 里再验 draft 完不完整 | draft 合法性已在 Agent 用例判定；此处只看 **异常 Kind** |
|
||
| hasProgress = 有过 tool_call | = **`progress.observedFacts` 非空**（可发布观察事实） |
|
||
| 降级会带上坏 JSON | **丢弃非法正文**，只根据 progress 生成 SafeFallback |
|
||
|
||
**专用发布**：`DiagnosisReleaseUseCase.releaseInvalidDraft`
|
||
|
||
- 不再跑 Evidence/Semantic Guard（没有可校验 draft）
|
||
- 要求 `hasObservedFacts()`，否则 `IllegalStateException`
|
||
- 产出 `FallbackType.INSUFFICIENT_EVIDENCE`
|
||
|
||
---
|
||
|
||
## 6. Release：按 execution 形态分叉
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
EX[DiagnosisAgentExecution] --> D{draft == null?}
|
||
D -->|是 stopped| CS[releaseControlledStop<br/>需有 observedFacts]
|
||
D -->|否| C{conclusion == null?}
|
||
C -->|是| NC[releaseNoConclusion<br/>部分 Evidence + progress]
|
||
C -->|否| RC[releaseConclusion<br/>Evidence → 可选 Repair → Semantic]
|
||
CS --> FB[FALLBACK]
|
||
NC --> FB
|
||
RC -->|SUPPORTED| OK[SUCCESS]
|
||
RC -->|其它| FB
|
||
```
|
||
|
||
| 入口 | 典型来源 |
|
||
|------|----------|
|
||
| `releaseControlledStop` | `controlledExecution` → stopped |
|
||
| `releaseInvalidDraft` | `recoverInvalidDraft`（loop 结束坏 draft） |
|
||
| `releaseConclusion` | 正常 completed + 有结论 |
|
||
| `releaseNoConclusion` | draft 合法但无 conclusion |
|
||
|
||
---
|
||
|
||
## 7. Application 统一失败出口
|
||
|
||
未被转成 FALLBACK / SUCCESS 的异常，进入 `ChatApplicationUseCase`：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant EX as DiagnosisChatExecutor
|
||
participant APP as ChatApplicationUseCase
|
||
participant Core as DiagnosisHarnessCore
|
||
participant Store as ChatRunStore
|
||
participant SSE as ChatSseSession
|
||
|
||
EX-->>APP: 抛 ChatApplicationException 或 RuntimeException
|
||
APP->>Core: terminalOutcome / completeFailure
|
||
APP->>Store: finish(terminal, ...)
|
||
APP->>APP: safeFailure → ChatFailureCode
|
||
APP-->>SSE: fail(code, 安全文案)
|
||
```
|
||
|
||
常见映射直觉：
|
||
|
||
| 情况 | ChatFailureCode 倾向 |
|
||
|------|----------------------|
|
||
| 取消 | `RUN_CANCELLED` |
|
||
| 路由失败 | `ROUTING_UNAVAILABLE` |
|
||
| 落库失败 | `RUN_PERSISTENCE_FAILED` |
|
||
| 其它 | `INTERNAL_FAILURE` |
|
||
|
||
---
|
||
|
||
## 8. 端到端对照表（按场景）
|
||
|
||
| # | 场景 | 发生位置 | 关键信号 | 第一处理点 | 用户侧 |
|
||
|---|------|----------|----------|------------|--------|
|
||
| 1 | 第 N 次模型前预算没了 | Loop 内 Model | `BudgetExceeded` | controlledExecution → stopped | 有 facts→FALLBACK；无→FAILED |
|
||
| 2 | 工具执行失败 | Loop 内 Tool | `TOOL_EXECUTION_ERROR` observation | 留在 loop | 模型可能改写或再试 |
|
||
| 3 | 工具触顶预算 | Loop 内 ToolBoundary | error + markBudget | 常留在 loop，下轮 model 硬闸 | 同预算结局 |
|
||
| 4 | 饱和后仍要工具 | Loop 内 Tool | `DiagnosisCollectionStopped` | controlledExecution → stopped | 有 facts→FALLBACK |
|
||
| 5 | 取消/超时 | Core → 任意 checkActive | `RunAborted` | controlledExecution **再抛** | CANCELLED / FAILED |
|
||
| 6 | 模型返回烂 JSON | Loop 外解析 | `INVALID_JSON` 等 | recoverInvalidDraft | 有 facts→FALLBACK；无→FAILED |
|
||
| 7 | 执行崩溃未识别 | Loop 边界 | `EXECUTION_FAILED` | recover 不恢复，上抛 | FAILED |
|
||
| 8 | Guard 引用失败 | Loop 外 Release | Evidence 违规 | repair 或 FALLBACK | FALLBACK EVIDENCE_* |
|
||
| 9 | 语义不支持 | Loop 外 Release | UNSUPPORTED | FALLBACK | FALLBACK SEMANTIC_* |
|
||
|
||
---
|
||
|
||
## 9. 两条主恢复路径对比（必记）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph mid["Loop 中途打断"]
|
||
A1[Interceptor / Core 异常] --> B1[controlledExecution]
|
||
B1 --> C1[stopped draft=null]
|
||
C1 --> D1[releaseControlledStop]
|
||
end
|
||
|
||
subgraph end["Loop 正常结束但输出坏"]
|
||
A2[解析 Draft 失败] --> B2[DiagnosisAgentOutputException]
|
||
B2 --> C2[recoverInvalidDraft]
|
||
C2 --> D2[releaseInvalidDraft]
|
||
end
|
||
|
||
D1 --> E[INSUFFICIENT_EVIDENCE FALLBACK<br/>前提 hasObservedFacts]
|
||
D2 --> E
|
||
```
|
||
|
||
| | `controlledExecution` | `recoverInvalidDraft` |
|
||
|--|----------------------|------------------------|
|
||
| 时机 | loop **中途** | loop **结束后** |
|
||
| 输入 | `Throwable` cause 链 | `DiagnosisAgentOutputException` |
|
||
| 成功产物 | `Execution.stopped` | 直接 `DiagnosisExecutionResult(FALLBACK)` |
|
||
| 发布入口 | `releaseControlledStop` | `releaseInvalidDraft` |
|
||
| 共同点 | 都依赖 **可发布 observedFacts**；都 **fail closed** |
|
||
|
||
---
|
||
|
||
## 10. 代码索引
|
||
|
||
| 组件 | 路径 |
|
||
|------|------|
|
||
| Model 拦截 | `harness/agent/HarnessModelInterceptor.java` |
|
||
| Tool 拦截 | `harness/agent/HarnessToolInterceptor.java` |
|
||
| 工具边界 | `harness/tool/boundary/ToolBoundary.java` |
|
||
| 受控停止转换 | `harness/agent/DiagnosisAgentUseCase#controlledExecution` |
|
||
| 坏 Draft 恢复 | `harness/application/executor/DiagnosisChatExecutor#recoverInvalidDraft` |
|
||
| 非法 draft 发布 | `harness/release/DiagnosisReleaseUseCase#releaseInvalidDraft` |
|
||
| 受控停止发布 | `DiagnosisReleaseUseCase#releaseControlledStop` |
|
||
| 应用失败出口 | `harness/application/ChatApplicationUseCase` |
|
||
| 错误码注释 | `ChatFailureCode` / `ReleaseOutcome` / `FallbackType` / `RunState` / `DiagnosisStopReason` / `ToolBoundaryErrorCode` 等 |
|
||
|
||
---
|
||
|
||
## 11. 阅读检查清单
|
||
|
||
1. 这个失败是 **还在 loop 里**，还是 **已经穿出 agent.call**？
|
||
2. 是 **资源/取消**（Core），还是 **收集收敛**（Progress），还是 **输出契约**（Draft Kind）？
|
||
3. 最终有没有 **`observedFacts`**？有才能谈 FALLBACK。
|
||
4. `RunState` 与 `ReleaseOutcome` 是否一致理解（预算耗尽 ≠ 一定 FAILED）？
|
||
5. Tool 错误是 **observation** 还是 **异常穿出**？不要默认「有 error 就崩 run」。
|
||
|
||
---
|
||
|
||
## 12. 一句话总结
|
||
|
||
> **Loop 内：能安全回注的变成 observation，必须停收集或硬预算的穿出异常。**
|
||
> **Loop 边界：controlledExecution 把受控停止收成 stopped。**
|
||
> **Loop 外：坏 draft 用 recoverInvalidDraft，只认 observedFacts 做降级。**
|
||
> **全程 fail closed：没有可验证事实，就不发「看起来友好」的假成功。**
|