SuperBizAgent-java/mvp/architecture/session-trace-lifecycle.md

会话与 Trace 生命周期

更新日期：2026-07-17 状态：当前可运行架构 参考历史文档：archive/2026-07-05-legacy/session-management.md

1. 定位

当前 MVP 把“会话态”和“运行态”拆开：

chat_session(sessionId)
  -> diagnosis_run(runId)
      -> agent_step(runId)
      -> tool_invocation(runId)

• sessionId 表示多轮会话目录和 Redis 上下文。
• runId 表示一次可回放诊断执行。
• DiagnosisTraceService 聚合一个 run 的主记录、步骤和工具调用，形成可回放 Trace。
• 运行时不再映射、读取或写入 diagnosis_session；数据库中的旧表不属于当前版本契约。

2. 生命周期总图

flowchart TD
    Start["request: chat / ai_ops"] --> Resolve["resolve sessionId"]
    Resolve --> Session["ensure chat_session metadata"]
    Session --> Run["create diagnosis_run(runId)"]
    Run --> Running["run.status = RUNNING"]

    Running --> Agent["Chat StateGraph / AIOps workflow"]
    Agent --> Context["execution context(sessionId, runId)"]
    Context --> StepHook["AgentLoggingHook"]
    StepHook --> Step["agent_step(session_id, run_id)"]
    Context --> Tool["Evidence tools"]
    Tool --> Invocation["tool_invocation(session_id, run_id)"]
    Invocation --> Gatekeeper["Gatekeeper evidence validation"]

    Agent --> GraphTrace["Chat: save orchestration_trace"]
    GraphTrace --> Final{"workflow result"}
    Final -->|success| Success["run.status = SUCCESS, answer saved"]
    Final -->|failed| Failed["run.status = FAILED"]

    Success --> Evaluation["diagnosis_run.self_evaluation merge"]
    Failed --> Evaluation
    Evaluation --> Trace["GET /api/diagnosis/{sessionId}/trace?runId=..."]
    Success --> Feedback["POST /api/feedback(sessionId, runId)"]
    Feedback --> Case["useful -> case_library(run_id)"]

3. ID 规则

ID	来源	含义
sessionId	Chat request Id、AIOps payload sessionId，缺失时由服务生成	多轮会话目录和 Redis 上下文
runId	每次有效 Chat/AIOps 执行创建	一次诊断运行和 Trace 回放边界

设计含义：

• 同一个 sessionId 可以贯穿多轮 Chat。
• 每次有效 Chat/AIOps 执行都会创建新的 runId。
• Trace 和 Feedback 必须同时传 sessionId + runId；后端不解析 latest run，也不回退旧表。

4. 运行状态流转

stateDiagram-v2
    [*] --> PENDING
    PENDING --> RUNNING: start diagnosis
    RUNNING --> SUCCESS: workflow completed
    RUNNING --> FAILED: exception / empty state
    SUCCESS --> SUCCESS: feedback submitted
    FAILED --> FAILED: feedback submitted

字段边界：

字段	所属表	含义
status	diagnosis_run	单次运行执行状态
answer	diagnosis_run	本次运行最终报告或答复
self_evaluation	diagnosis_run	本次运行系统自评估 JSON
orchestration_trace	diagnosis_run	Chat StateGraph 路由摘要；包含 version、transitions、final node、termination reason、degraded 和 evidence retry count
feedback	diagnosis_run	本次运行用户反馈

feedback 不修改 status。一个执行成功但用户标记 not_useful 的 run，仍然应该是 SUCCESS + feedback=not_useful。

5. agent_step 写入

AgentLoggingHook 在模型调用前后写入和回填 agent_step。

sequenceDiagram
    autonumber
    participant Agent as Agent
    participant Hook as AgentLoggingHook
    participant DB as agent_step

    Agent->>Hook: before_model(messages, sessionId, runId)
    Hook->>DB: insert step(session_id, run_id, model_input, step_index)
    Agent->>Hook: after_model(output, sessionId, runId)
    Hook->>DB: update model_output, duration, token_count, has_tool_call

新写入必须带 run_id，同时保留 session_id 便于粗粒度排查。

6. tool_invocation 写入

工具调用记录同样通过执行上下文拿到 sessionId + runId：

ToolInvocationRecorder
  -> tool_invocation.session_id
  -> tool_invocation.run_id
  -> retrieval_details / evidence_refs

Gatekeeper 和 EvaluationService 按 run_id 读取工具调用，避免同一 session 的其他 run 参与评分或证据校验。Verifier 只读取 VerifiedInputNode 生成的 verified projection，不直接读取完整工具调用列表。

7. Trace API 聚合

GET /api/diagnosis/{sessionId}/trace
GET /api/diagnosis/{sessionId}/trace?runId=run-...

聚合逻辑：

diagnosis_run by sessionId + runId
  + run.orchestrationTrace parsed from diagnosis_run.orchestration_trace
  + chat_session metadata when available
  + agent_step where run_id = runId, ordered by the Trace API
  + tool_invocation where run_id = runId order by id
  -> DiagnosisTraceResponse

当 runId 缺失时，Trace API 直接拒绝请求。当 runId 属于其他 sessionId 时，API 同样拒绝，不能泄漏其他会话的 Trace。

run.orchestrationTrace 只属于精确 Run 投影，响应不再提供兼容 session 对象。它解释 Graph 路由；selfEvaluation 解释证据/答案质量；steps 和 toolInvocations 保存详细执行证据，三者职责互不替代。非 StateGraph Run 的该字段可以为空。

8. Chat 与 AIOps 差异

维度	Chat	AIOps
agent_flow	CHAT	AI_OPS
编排方式	bounded StateGraph: Planner / Executor / Gatekeeper / Verified Input / Verifier / Composer / Fallback	SupervisorAgent: Planner + Executor
自评估	rule_evaluation + verifier_evaluation	aiops_rule_evaluation
答案字段	Chat 最终答复	告警分析报告
runId 暴露	/api/chat JSON response	/api/ai_ops SSE metadata message

Chat StateGraph 的权威自动化验收分三层：DiagnosisGraphWorkflowTest 验证路由，DiagnosisGraphNodeContractTest 验证真实 Node 输入输出，ChatServiceGraphIntegrationTest 验证 Run 生命周期、Trace 持久化和对外集成。

9. 清理与边界

• Redis 会话历史用于多轮上下文，不是长期审计记录。
• MySQL diagnosis_run + agent_step + tool_invocation 是主要可回放来源。
• chat_session.expires_at 只是目录元数据；Redis 消息历史可独立过期。
• RetrievedDocTracker 仍是 session 级运行时去重状态，诊断结束后清理。

10. 后续增强

1. Trace API 增加更结构化的 self_evaluation 展示。
2. agent_step 与 tool_invocation.step_id 建立更严格关联。
3. 数据库中的旧 diagnosis_session 表按独立数据治理任务决定是否物理删除；当前应用不再依赖它。