SuperBizAgent-java/mvp/engineering/harness/Harness contract 状态流学习笔记-11个状态枚举的正交全景.md

Harness contract 状态流学习笔记：11 个状态枚举的正交全景

更新日期：2026-08-06 主题：contract 域状态枚举全景——五层状态 / 正交维度 / 纵向映射链 / 真实数据案例 / 面试讲法 配套：证据安全链笔记、application+audit 笔记

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. 正交维度（四个独立轴）

轴 1：RunState（技术终态）⊥ ReleaseOutcome（用户结局）
      一个 Run 技术停了，用户看到的可能是降级（有安全进展）或失败（没进展）
轴 2：InvocationStatus（调用生命周期）⊥ EvidenceStatus（证据语义）
      注释原话：一个是「投影中/就绪/错误」，一个是「有没有拿到可引用证据」
      NO_EVIDENCE 仍可能是 success 的工具执行（查了但空）
轴 3：ChatApplicationStatus（进度，进行中）⊥ 结局（终态）
      进度回答「走到哪」，结局回答「最终给什么」
轴 4：IntentType（路由）——每次请求一个，决定走哪条分支

4. 纵向映射链（代码事实）

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