106 lines
7.8 KiB
Markdown
106 lines
7.8 KiB
Markdown
# Harness contract 状态流学习笔记：11 个状态枚举的正交全景
|
||
|
||
**更新日期**：2026-08-06
|
||
**主题**：contract 域状态枚举全景——五层状态 / 正交维度 / 纵向映射链 / 真实数据案例 / 面试讲法
|
||
**配套**：[证据安全链笔记](Harness%20证据安全链学习笔记-从收敛控制到唯一发布点.md)、[application+audit 笔记](Harness%20application+audit%20学习笔记-从%20Run%20编排到可回放审计.md)
|
||
|
||
## 1. 一句话定位
|
||
|
||
**contract 状态流 = 11 个状态枚举按五层正交组织，每层回答一个独立问题；层间通过显式映射链串联——从技术终态到用户结局，从工具调用到发布裁决，全部类型化，杜绝字符串漂移。**
|
||
|
||
## 2. 五层状态全景
|
||
|
||
| 层 | 枚举 | 值 | 回答的问题 |
|
||
|---|---|---|---|
|
||
| ① 技术层（core） | `RunState` | RUNNING / SUCCESS / FAILED / CANCELLED / TIMED_OUT / BUDGET_EXHAUSTED | Run 技术上是否还允许执行 |
|
||
| ② 证据层（tool/guard） | `InvocationStatus` | PROJECTING / READY / ERROR | 调用生命周期走到哪 |
|
||
| | `EvidenceStatus` | EVIDENCE_FOUND / NO_EVIDENCE / ERROR | 这次调用有没有拿到可引用证据 |
|
||
| | `AnalysisKind` | NORMAL / NEGATIVE_OBSERVATION | 分析条目是正向还是负向观察 |
|
||
| ③ 收集层（progress） | `DiagnosisStopReason` | INFORMATION_SATURATED / BUDGET_LIMIT_REACHED / PROTOCOL_VIOLATED | 证据收集为何受控停止 |
|
||
| | `SemanticVerdict` | SUPPORTED / UNSUPPORTED | 结论是否被证据支持 |
|
||
| ④ 发布层（release） | `ReleaseOutcome` | SUCCESS / FALLBACK / FAILED / CANCELLED | 用户侧内容结局 |
|
||
| | `FallbackType` | EVIDENCE_VALIDATION_FAILED / SEMANTIC_UNSUPPORTED / SEMANTIC_UNAVAILABLE / BUDGET_EXHAUSTED / INSUFFICIENT_EVIDENCE / MISSING_REQUIRED_CONTEXT | 为什么降级 |
|
||
| ⑤ 协议层 + 失败层 | `ChatApplicationStatus` | ROUTING / SYSTEM_RESPONDING / KNOWLEDGE_SEARCHING / KNOWLEDGE_ANSWERING / DIAGNOSIS_RUNNING / SAFETY_VALIDATING | 当前走到哪一阶段（进行中） |
|
||
| | `SseOutcome` | SUCCESS / FALLBACK / FAILED | done 事件粗粒度结局（**未接线**） |
|
||
| | `ChatFailureCode` | ROUTING_UNAVAILABLE / SYSTEM_CHAT_UNAVAILABLE / KNOWLEDGE_UNAVAILABLE / DIAGNOSIS_UNAVAILABLE / RUN_PERSISTENCE_FAILED / RUN_CANCELLED / INTERNAL_FAILURE | 失败时给客户端的粗粒度原因 |
|
||
|
||
## 3. 正交维度（四个独立轴）
|
||
|
||
```text
|
||
轴 1：RunState（技术终态）⊥ ReleaseOutcome（用户结局）
|
||
一个 Run 技术停了，用户看到的可能是降级（有安全进展）或失败（没进展）
|
||
轴 2：InvocationStatus（调用生命周期）⊥ EvidenceStatus（证据语义）
|
||
注释原话：一个是「投影中/就绪/错误」，一个是「有没有拿到可引用证据」
|
||
NO_EVIDENCE 仍可能是 success 的工具执行（查了但空）
|
||
轴 3：ChatApplicationStatus（进度，进行中）⊥ 结局（终态）
|
||
进度回答「走到哪」，结局回答「最终给什么」
|
||
轴 4：IntentType（路由）——每次请求一个，决定走哪条分支
|
||
```
|
||
|
||
## 4. 纵向映射链（代码事实）
|
||
|
||
```text
|
||
RunState.BUDGET_EXHAUSTED ──hasObservedFacts()==true──▶ FALLBACK（INSUFFICIENT_EVIDENCE）
|
||
└──无 facts──▶ FAILED（fail closed）
|
||
RunState.CANCELLED ──▶ ReleaseOutcome.CANCELLED + ChatFailureCode.RUN_CANCELLED
|
||
内部失败 ──▶ RunState.FAILED + ReleaseOutcome.FAILED + INTERNAL_FAILURE
|
||
SemanticVerdict.SUPPORTED（guard 全过）──▶ ReleaseOutcome.SUCCESS（唯一出口）
|
||
FallbackType 任意值 ──▶ ReleaseOutcome.FALLBACK
|
||
|
||
证据层内部约束：
|
||
AnalysisKind.NORMAL.accepts(EVIDENCE_FOUND)
|
||
AnalysisKind.NEGATIVE_OBSERVATION.accepts(NO_EVIDENCE)
|
||
InvocationStatus.READY 是 EvidenceGuard 可引用前提（isReferencableBy）
|
||
EvidenceStatus.ERROR 不是证据，不能支持分析/结论（prompt 原话）
|
||
```
|
||
|
||
## 5. 真实数据案例（run 1b584a01 的状态流转）
|
||
|
||
| 阶段 | 状态值（真实 trace 佐证） |
|
||
|---|---|
|
||
| 路由 | IntentType=DIAGNOSIS（ROUTING_DECISION 事件 details） |
|
||
| Agent 执行 | RunState=RUNNING，ChatApplicationStatus: ROUTING → DIAGNOSIS_RUNNING → SAFETY_VALIDATING |
|
||
| 工具调用 | InvocationStatus: PROJECTING → READY；EvidenceStatus=EVIDENCE_FOUND |
|
||
| 分析 | AnalysisKind=NORMAL × 3（accepts EVIDENCE_FOUND） |
|
||
| 验真 | EVIDENCE_GUARD_INITIAL=PASSED（violations=0） |
|
||
| 语义裁决 | SEMANTIC_GUARD_DECISION=SUPPORTED |
|
||
| 发布 | RELEASE_DECISION=SUCCESS（= ReleaseOutcome.SUCCESS） |
|
||
| 终态 | RunState=SUCCESS |
|
||
|
||
## 6. 面试怎么讲这个状态流设计
|
||
|
||
### 6.1 叙事模板（① 动机 → ② 决策 → ③ 实现 → ④ 边界 → ⑤ 话术）
|
||
|
||
**① 动机**：Agent 系统里最容易被搞混的就是「状态」。技术停了（预算耗尽）不等于用户看到失败；查了没查到不等于系统出错；进行中不等于终态。如果所有状态塞进一个枚举，语义就糊了。
|
||
|
||
**② 决策**：**分层 + 正交 + 显式映射**——每个枚举只回答一个问题（技术/证据/收集/发布/协议各管各的），层间不隐式耦合，用明确的映射链串联。
|
||
|
||
**③ 实现**：11 个枚举五层，两个最典型的正交轴 + 一条纵向映射链（如上）；全部类型化（enum/record），杜绝字符串漂移。
|
||
|
||
**④ 边界**：SSE 取消场景连接可能已断、发不出 done，所以协议层只有三态；`SseOutcome` 目前未接线（实现直接复用 ReleaseOutcome）；`FallbackType.BUDGET_EXHAUSTED` 是命名债务（实际发布 INSUFFICIENT_EVIDENCE）。
|
||
|
||
**⑤ 话术（30 秒）**：
|
||
|
||
> "Harness 的状态设计核心是**分层正交**：技术终态（RunState）和用户结局（ReleaseOutcome）是两个正交轴——预算耗尽且有安全进展时用户看到 FALLBACK 降级，没进展才是 FAILED，这样同一个技术终态可以诚实映射到不同用户结局；工具调用也是两个正交轴（InvocationStatus 生命周期 vs EvidenceStatus 证据语义），查了但空结果（NO_EVIDENCE）仍是成功执行。层间是显式映射链：BUDGET_EXHAUSTED+有事实→FALLBACK，CANCELLED→CANCELLED+RUN_CANCELLED，guard 全过→SUCCESS 唯一出口。协议层（SSE）复用 ReleaseOutcome 三态并拒绝 CANCELLED（取消时连接已断），SseOutcome 是预留未启用的抽象。"
|
||
|
||
### 6.2 高频追问应对
|
||
|
||
| 追问 | 答 |
|
||
|---|---|
|
||
| RunState 和 ReleaseOutcome 有什么区别？ | 技术 vs 用户：RunState 回答 Run 是否还允许执行；ReleaseOutcome 回答用户侧内容形态。BUDGET_EXHAUSTED 可以有 FALLBACK 或 FAILED 两种用户结局 |
|
||
| 为什么预算耗尽既可能 FALLBACK 又可能 FAILED？ | `progress.hasObservedFacts()` 安全阀——有已验真事实才能发布降级，没有就 fail closed |
|
||
| NO_EVIDENCE 算失败吗？ | 不算。NO_EVIDENCE 是成功执行但范围内无证据（查了但空），常记为信息无增益；ERROR 才是工具侧失败 |
|
||
| CANCELLED 为什么不在 SSE done 里？ | 取消时客户端连接可能已断，发不出 done；所以协议层只有 SUCCESS/FALLBACK/FAILED 三态 |
|
||
| 这些状态为什么不直接用一个枚举？ | 塞一个枚举语义就糊了——技术、证据、发布、协议回答的是不同问题，正交分层后各层可独立演进，映射显式可审计 |
|
||
| InvocationStatus 和 EvidenceStatus 会不会重复？ | 分工明确：生命周期（投影中/就绪/错误）vs 证据语义（有没有证据）；READY+NO_EVIDENCE 是完全合法的组合 |
|
||
|
||
## 7. 代码位置索引
|
||
|
||
| 组件 | 文件 |
|
||
|---|---|
|
||
| 全部状态枚举与数据契约 | `src/main/java/com/superbiz/agent/harness/contract/` |
|
||
| RunState | `.../harness/core/RunState.java` |
|
||
| DiagnosisStopReason | `.../harness/progress/DiagnosisStopReason.java` |
|
||
| ChatApplicationStatus / ChatFailureCode | `.../harness/application/` |
|
||
| SSE 会话（done 事件拒绝 CANCELLED） | `.../controller/sse/ChatSseEvent.java` |
|