# Harness 生命周期与状态

**更新日期**：2026-07-29
**状态**：当前实现口径
**术语前置**：[CONTEXT.md](CONTEXT.md)

## 1. 先澄清：系统不存在一条包含所有状态的总状态机

当前 Harness 有多组正交状态：

- RunState 控制内存执行终态；
- ChatApplicationStatus 表示用户可见处理阶段；
- InvocationStatus 表示单次 Tool invocation 生命周期；
- EvidenceStatus 表示 Tool 客观结果；
- CollectionState 表示能否继续收集证据；
- StopReason 表示停止收集的内部原因；
- SemanticVerdict 表示结论支持度；
- ReleaseOutcome 表示最终发布结果；
- SSE Session State 表示连接能否继续发送。

它们在一次请求中并行演进，只在少数边界发生映射。生命周期文档的目标不是把它们合并，而是说明谁先发生、由谁拥有、在哪里汇合。

## 2. 一次 Run 的主时间线

```mermaid
sequenceDiagram
    participant C as Client / SSE
    participant A as ChatApplicationUseCase
    participant H as Harness Core
    participant R as Intent Router
    participant D as Diagnosis Runtime
    participant L as Release Pipeline
    participant P as Persistence / Trace

    C->>A: query + optional sessionId
    A->>A: 读取 routing history / PreviousTurn
    A->>H: startRun(sessionId)
    H-->>A: RUNNING RunContext
    A->>P: diagnosis_run=RUNNING + RUN_STARTED
    A-->>C: metadata(sessionId, runId)

    A->>R: route(query, bounded history)
    R-->>A: IntentType

    alt SYSTEM_CHAT
        A->>A: 单轮受控模型回答
    else KNOWLEDGE_QUERY
        A->>A: 一次 RAG + 单轮答案
    else DIAGNOSIS
        A->>D: Agent ReAct / Tool / Progress
        D-->>A: Draft 或 Controlled Stop
        A->>L: release(Draft/Progress/StopReason)
        L-->>A: SUCCESS Draft 或 SafeFallback
    end

    alt 正常完成
        A->>H: completeSuccess（预算 Fallback 特例除外）
        A->>P: 持久化 release outcome / safe content / usage
        A->>P: RUN_FINISHED
        A-->>C: content + done
    else 失败
        A->>H: completeFailure 或读取既有终态
        A->>P: 持久化 FAILED/CANCELLED
        A->>P: RUN_FINISHED
        A-->>C: failure + done(FAILED)
    end
```

创建顺序很重要：Application 先读取会话上下文，再创建 RunContext、持久化 RUNNING、记录 RUN_STARTED，之后才进入路由和执行。SSE 的 metadata 在 `onStarted` 中发布 exact sessionId/runId，后续结果必须匹配这组身份。

## 3. Run 生命周期

### 3.1 状态

```mermaid
stateDiagram-v2
    [*] --> RUNNING
    RUNNING --> SUCCESS: 正常路径完成
    RUNNING --> FAILED: 不可恢复内部失败
    RUNNING --> CANCELLED: 客户端断开或用户取消
    RUNNING --> TIMED_OUT: deadline 到达
    RUNNING --> BUDGET_EXHAUSTED: 任一硬预算超限

    SUCCESS --> [*]
    FAILED --> [*]
    CANCELLED --> [*]
    TIMED_OUT --> [*]
    BUDGET_EXHAUSTED --> [*]
```

`RunLifecycle.finish` 使用原子 compare-and-set：只有从“尚无 termination”到某个终态的第一次转换成功。所有终态都不可再次转换。

### 3.2 状态含义

| RunState | 含义 | 常见来源 |
|---|---|---|
| `RUNNING` | 尚未产生 RunTermination | `startRun` 后默认状态 |
| `SUCCESS` | Application 已形成正常可持久化结果 | 正常内容，或非预算类 SafeFallback |
| `FAILED` | 不可恢复执行失败 | 路由不可用、模型失败、无安全进展的非法 Draft 等 |
| `CANCELLED` | 协作取消已成为第一个终态 | 客户端断开、用户请求 |
| `TIMED_OUT` | `checkActive` 发现 deadline 已到 | 模型/Tool/Guard 边界前后检查 |
| `BUDGET_EXHAUSTED` | 模型、Tool、Token 或 bytes 预算超限 | `DiagnosisHarnessCore.exhaustBudget` |

### 3.3 RunState 与 ReleaseOutcome 不一一对应

最重要的反例是 Fallback：

- 证据不足、缺少上下文、语义不支持等正常降级，RunState 最终为 `SUCCESS`，ReleaseOutcome 为 `FALLBACK`；
- 预算耗尽后已经有安全 ProgressSnapshot，RunState 保持 `BUDGET_EXHAUSTED`，但 ReleaseOutcome 可以为 `FALLBACK`；
- 超时或预算耗尽且无法形成安全内容时，RunState 分别保持 `TIMED_OUT / BUDGET_EXHAUSTED`，ReleaseOutcome 映射为 `FAILED`。

所以不能从 ReleaseOutcome 反推出精确 RunState，也不能把 `FALLBACK` 当作 RunState。

## 4. 取消生命周期

`RunCancellation` 使用 first-reason-wins。取消原因包括：

| Reason | RunState 映射 |
|---|---|
| `CLIENT_DISCONNECTED` | `CANCELLED` |
| `USER_REQUESTED` | `CANCELLED` |
| `DEADLINE_EXCEEDED` | `TIMED_OUT` |
| `BUDGET_EXHAUSTED` | `BUDGET_EXHAUSTED` |
| `INTERNAL_FAILURE` | `FAILED` |

生命周期和取消句柄互相配合：取消回调尝试完成 RunLifecycle；deadline 和预算路径也会先确定终态，再触发取消阻止后续工作。

取消语义是协作式的：

1. 后续模型、Tool、Guard 边界调用 `checkActive` 时立即失败；
2. SSE 断开后不再发送 content；
3. first-terminal-wins 阻止迟到成功覆盖 CANCELLED/TIMED_OUT；
4. 已经进入 Provider 的同步调用是否物理停止，取决于底层客户端，Harness 不作虚假保证。

## 5. Application 阶段不是生命周期状态

`ChatApplicationStatus` 用于 SSE status 事件：

```text
ROUTING
SYSTEM_RESPONDING
KNOWLEDGE_SEARCHING
KNOWLEDGE_ANSWERING
DIAGNOSIS_RUNNING
SAFETY_VALIDATING
```

这些值只是用户可见的处理阶段：

- 不是严格完备的状态机；
- 不表示终态；
- 不持有取消或预算；
- 不保证每个 Run 都经过全部阶段。

例如 Diagnosis Run 通常经过 `ROUTING -> DIAGNOSIS_RUNNING -> SAFETY_VALIDATING`，System Chat 则经过 `ROUTING -> SYSTEM_RESPONDING`。

## 6. Diagnosis Agent 执行生命周期

`DiagnosisAgentExecution` 只有两种合法形态，不额外定义一套枚举：

| 形态 | 字段 | 含义 |
|---|---|---|
| Completed | `draft != null, stopReason=null` | Agent 输出严格合法 DiagnosisDraft |
| Controlled Stop | `draft=null, stopReason != null` | Tool loop 因信息饱和、预算或协议错误受控停止 |

其他情况通过异常表达：

- 空 Draft；
- 非法 JSON；
- Schema 不合法；
- 模型调用失败；
- RunAborted。

Draft 合同失败不是 DiagnosisStopReason。非法 Draft 会被丢弃；只有异常携带的 ProgressSnapshot 已包含可验真 facts，Application 才允许 Release 生成过程型 Fallback。

## 7. 单次 Tool Invocation 生命周期

### 7.1 状态转换

```mermaid
stateDiagram-v2
    [*] --> PREFLIGHT
    PREFLIGHT --> REJECTED: invalid run/id/auth/readonly/request/budget/store
    PREFLIGHT --> PROJECTING: canonical begin 成功
    PROJECTING --> READY: backend + projection + store 成功
    PROJECTING --> ERROR: execution/projection/size/budget/store error
    READY --> [*]
    ERROR --> [*]
    REJECTED --> [*]
```

`PREFLIGHT` 和 `REJECTED` 是本文用于解释流程的阶段，不是 `InvocationStatus` 枚举值。canonical record 只有：

- `PROJECTING`：已创建，尚未形成可引用结果；
- `READY`：执行和投影完成，可以被当前 Run 引用；
- `ERROR`：调用失败，不可引用。

部分 preflight 失败发生在 canonical begin 之前，因此可能只有 `ToolBoundaryResult.ERROR` 和审计事件，没有 canonical ERROR record。

### 7.2 EvidenceStatus 是另一条轴

| InvocationStatus | EvidenceStatus | 语义 |
|---|---|---|
| `PROJECTING` | `null` | 未完成 |
| `READY` | `EVIDENCE_FOUND` | 技术完成，存在候选内容 |
| `READY` | `NO_EVIDENCE` | 技术完成，当前 scope 为空 |
| `ERROR` | `ERROR` | 技术失败 |

`READY + EVIDENCE_FOUND` 仍不表示证据足以支持结论；后续还要经过 InformationGain、EvidenceGuard 和 SemanticGuard。

## 8. 信息收集生命周期

### 8.1 Collection State

```mermaid
stateDiagram-v2
    [*] --> COLLECTING
    COLLECTING --> COLLECTING: GAINED / 清零 no-gain
    COLLECTING --> COLLECTING: NO_GAIN / 未达阈值
    COLLECTING --> SATURATED: 连续 NO_GAIN 达阈值
    COLLECTING --> SATURATED: 连续 progress protocol violation 达阈值
    SATURATED --> SATURATED: 终态，不再允许新 evidence Tool
```

`SATURATED` 只表示证据收集不再允许继续。它不是整个 Run 的终态，Agent 仍有一次机会输出 Draft，之后进入 Release。

预算超限不会把 CollectionState 改成 SATURATED。它将 RunState 置为 `BUDGET_EXHAUSTED`，并把内部 DiagnosisStopReason 标记为 `BUDGET_LIMIT_REACHED`。

### 8.2 InformationGain

- `NO_EVIDENCE` 和完全重复的 `tool_name + normalized_scope` 由 Harness 产生 `NO_GAIN`；
- 其他成功非空结果由 Diagnosis Agent 评价 `GAINED / NO_GAIN`；
- `GAINED` 清零连续 NO_GAIN；
- 技术失败和 progress 协议错误不产生 InformationGain。

### 8.3 StopReason

| DiagnosisStopReason | 触发条件 | 对 CollectionState 的影响 |
|---|---|---|
| `INFORMATION_SATURATED` | 连续 NO_GAIN 达阈值 | 进入 SATURATED |
| `PROGRESS_PROTOCOL_VIOLATED` | 连续协议错误达阈值 | 进入 SATURATED |
| `BUDGET_LIMIT_REACHED` | RunBudget 超限 | 不要求进入 SATURATED；Run 已终止 |

STOP_REQUIRED 是否已经交付由独立 boolean 记录，它不是第四种 CollectionState。一次指令交付后仍请求 Tool，会抛出受控停止异常。

## 9. Guard 与 Release 生命周期

```mermaid
flowchart TD
    I["DiagnosisAgentExecution"] --> D{"有合法 Draft?"}
    D -->|"否，受控停止"| PS["验证 ProgressSnapshot"]
    D -->|"是，无 conclusion"| NC["验证已有 Tool references"]
    D -->|"是，有 conclusion"| EG["EvidenceGuard initial"]

    EG --> EV{"evidence valid?"}
    EV -->|"否"| ER["EvidenceRepair once"]
    ER --> RE["EvidenceGuard recheck"]
    EV -->|"是"| SG["SemanticGuard"]
    RE -->|"valid"| SG
    RE -->|"invalid"| EF["EVIDENCE_VALIDATION_FAILED"]

    SG -->|"SUPPORTED"| SU["ReleaseOutcome.SUCCESS"]
    SG -->|"UNSUPPORTED"| SF["SEMANTIC_UNSUPPORTED"]
    SG -->|"unavailable"| UF["SEMANTIC_UNAVAILABLE"]

    NC -->|"有 progress"| IF["INSUFFICIENT_EVIDENCE"]
    NC -->|"无 progress，有 missing_info"| MF["MISSING_REQUIRED_CONTEXT"]
    NC -->|"两者都无"| FAIL["FAILED"]
    PS -->|"有 verified facts"| IF
    PS -->|"无 verified facts"| FAIL

    EF --> FB["ReleaseOutcome.FALLBACK"]
    SF --> FB
    UF --> FB
    IF --> FB
    MF --> FB
```

`DiagnosisReleaseResult` 只表达 `SUCCESS` 或 `FALLBACK`。真正不可恢复的 `FAILED / CANCELLED` 由 Chat Application 异常路径映射。

## 10. RunState、ReleaseOutcome 和 FallbackType 映射

| 场景 | RunState | ReleaseOutcome | FallbackType / 内容 |
|---|---|---|---|
| 有结论且 Guards 通过 | `SUCCESS` | `SUCCESS` | Diagnosis report |
| 缺少必要上下文，零 Tool 合法结束 | `SUCCESS` | `FALLBACK` | `MISSING_REQUIRED_CONTEXT` |
| 有限检查后证据不足 | `SUCCESS` | `FALLBACK` | `INSUFFICIENT_EVIDENCE` |
| 信息饱和后有安全进展 | `SUCCESS` | `FALLBACK` | `INSUFFICIENT_EVIDENCE` |
| 协议停止后有安全进展 | `SUCCESS` | `FALLBACK` | `INSUFFICIENT_EVIDENCE` |
| EvidenceGuard 最终失败 | `SUCCESS` | `FALLBACK` | `EVIDENCE_VALIDATION_FAILED` |
| SemanticGuard 判定不支持 | `SUCCESS` | `FALLBACK` | `SEMANTIC_UNSUPPORTED` |
| SemanticGuard 技术不可用 | `SUCCESS` | `FALLBACK` | `SEMANTIC_UNAVAILABLE` |
| 预算耗尽但有安全进展 | `BUDGET_EXHAUSTED` | `FALLBACK` | 当前发布 `INSUFFICIENT_EVIDENCE` |
| 超时，无法形成安全内容 | `TIMED_OUT` | `FAILED` | failure |
| 预算耗尽且无安全进展 | `BUDGET_EXHAUSTED` | `FAILED` | failure |
| 不可恢复内部失败 | `FAILED` | `FAILED` | failure |
| 客户端断开 | `CANCELLED` | `CANCELLED` | 不公开 CANCELLED done |

这张表解释了为什么不能只问“最后 status 是什么”。必须先确定是在问内存执行、发布结果还是 Fallback 原因。

## 11. SSE 连接生命周期

`ChatSseSession` 有自己的连接状态机：

```mermaid
stateDiagram-v2
    [*] --> NEW
    NEW --> OPEN: onStarted / metadata
    NEW --> DISCONNECTED: 客户端提前断开
    OPEN --> OPEN: status events
    OPEN --> TERMINAL: content + done
    OPEN --> TERMINAL: failure + done(FAILED)
    OPEN --> DISCONNECTED: send failure / disconnect
    TERMINAL --> [*]
    DISCONNECTED --> [*]
```

公开事件顺序是：

```text
metadata -> status* -> content | failure -> done
```

边界规则：

- content 最多发送一次；
- result 的 sessionId/runId 必须匹配 metadata；
- TERMINAL 或 DISCONNECTED 后拒绝迟到内容；
- `ReleaseOutcome.CANCELLED` 不作为公开 done outcome；客户端已经断开时没有可靠发送目标；
- 当前 `SseOutcome` 枚举未参与运行时协议，`ChatSseEvent.Done` 使用 `ReleaseOutcome`。

## 12. 持久化生命周期

### 12.1 创建

RunContext 创建后，Application 写入：

```text
diagnosis_run.status = RUNNING
session_id / run_id / query
```

之后记录 intent。

### 12.2 完成映射

`JpaChatRunStore` 根据 ReleaseOutcome 映射数据库通用 status：

| ReleaseOutcome | diagnosis_run.status |
|---|---|
| `SUCCESS` | `SUCCESS` |
| `FALLBACK` | `SUCCESS` |
| `FAILED` | `FAILED` |
| `CANCELLED` | `CANCELLED` |

这里的 `status=SUCCESS` 表示请求已被正常处理并形成安全内容，不表示一定有诊断 conclusion。

同时保存：

- `release_outcome`；
- safe answer JSON；
- 从 safe content 提取的 conclusion；
- duration、Token、Agent step 数和实际 Tool call 数；
- 仅在 `DIAGNOSIS + SUCCESS` 时保存 `published_result`。

Fallback 不进入下一轮 PreviousTurn。

### 12.3 当前可观测缺口

内存 `RunTermination.state/reason` 当前没有独立字段直接持久化。`RUN_FINISHED` 主要记录 ReleaseOutcome 和预算对账，精确的 TIMED_OUT/BUDGET_EXHAUSTED 原因需要结合异常路径和其他 Trace 事件判断。

因此数据库 `status`、ReleaseOutcome 和 Trace 都是必要观察面，任何一个都不是完整替代品。

## 13. Trace Timeline 如何对应生命周期

典型 Diagnosis SUCCESS：

```text
RUN_STARTED
ROUTING_ATTEMPT
ROUTING_DECISION
AGENT_MODEL_STEP
TOOL_INVOCATION / TOOL_PROGRESS ...
EVIDENCE_GUARD_INITIAL
SEMANTIC_GUARD_ATTEMPT
SEMANTIC_GUARD_DECISION
RELEASE_DECISION SUCCESS
RUN_FINISHED SUCCESS
```

典型信息不足 Fallback：

```text
RUN_STARTED
ROUTING_ATTEMPT
ROUTING_DECISION
AGENT_MODEL_STEP
TOOL_INVOCATION / TOOL_PROGRESS ...
COLLECTION_STOP（可选）
EVIDENCE_GUARD_INITIAL（无结论引用检查）
RELEASE_DECISION FALLBACK
RUN_FINISHED FALLBACK
```

`TracePhase` 和 `TraceEventStatus` 用来组织 Timeline。它们描述事件发生在哪一阶段、该事件结果如何，不构成新的 Run 生命周期。

## 14. 并发和迟到结果规则

一次 Run 的终止安全依赖三层协作：

1. `RunLifecycle`：first-terminal-wins，终态不可覆盖；
2. `DiagnosisHarnessCore.checkActive`：每个关键边界阻止终止后的新工作；
3. `ChatSseSession`：TERMINAL/DISCONNECTED 后拒绝迟到 content。

这能保证逻辑上的“取消后不再发布”。它不等于强制终止底层线程或 Provider 计算；底层调用返回后仍要经过 active 和 SSE state 检查，迟到结果才会被丢弃。

## 15. 排障时应该先看哪个状态

| 问题 | 首先看 | 然后看 |
|---|---|---|
| 用户为什么收到 Fallback | `release_outcome + FallbackType` | RELEASE/EVIDENCE/SEMANTIC Trace |
| Agent 为什么停止调用 Tool | `DiagnosisStopReason` | TOOL_PROGRESS、TOOL_REQUEST_REJECTED、COLLECTION_STOP |
| Tool 为什么没有证据 | `InvocationStatus + EvidenceStatus` | canonical record 和 Tool audit error code |
| Run 是超时还是预算耗尽 | 内存 termination（运行中）或相关 Trace/异常 | budget usage、collection stop、失败码 |
| 数据库为什么 status=SUCCESS 但没有结论 | `release_outcome` | answer 的 content type / FallbackType |
| 为什么没有 SSE done | `ChatSseSession.State` | client disconnect/send failure 和 Run cancellation |
| 为什么下一轮没有上一轮上下文 | 是否 `DIAGNOSIS + ReleaseOutcome.SUCCESS + published_result` | PublishedResultPolicy |

## 16. 生命周期不变量

1. 一个 Run 只能有一个 RunTermination。
2. 一个公开 SSE 最多有一次 content/failure 和一次 done。
3. Tool Invocation 只有 READY 才能被引用。
4. READY 必须同时拥有 `EVIDENCE_FOUND` 或 `NO_EVIDENCE`。
5. `NO_EVIDENCE` 不能被提升为全局否定。
6. SATURATED 后不再执行新的 evidence Tool。
7. StopReason 不直接决定公开内容，必须经过 Release。
8. 有 conclusion 才执行完整 EvidenceGuard/Repair/SemanticGuard 链。
9. FALLBACK 是正常发布结果，不等于 RunState.FAILED。
10. 数据库 status、ReleaseOutcome 和 RunState 不能互相替代。