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

会话与 Trace 生命周期

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

1. 定位

旧版会话设计以 Redis 会话为主，MySQL 作为可选长期沉淀。当前 MVP 的可追踪诊断已经转为 MySQL Trace 三表为主：

diagnosis_session
  -> agent_step
  -> tool_invocation

因此本文描述的是当前可运行链路：

• sessionId 是一次诊断和后续 trace/feedback 的关联键。
• diagnosis_session 保存会话级状态、问题、答案、自评估和反馈。
• agent_step 保存每个 Agent 模型调用。
• tool_invocation 保存工具调用事实。
• DiagnosisTraceService 聚合三类记录，形成可回放 trace。

2. 生命周期总图

flowchart TD
    Start["request: chat / ai_ops"] --> Resolve["resolve sessionId"]
    Resolve --> Create["create or reset diagnosis_session"]
    Create --> Running["status = RUNNING"]

    Running --> Agent["Agent workflow"]
    Agent --> StepHook["AgentLoggingHook"]
    StepHook --> Step["agent_step"]
    Agent --> Tool["Evidence tools"]
    Tool --> Invocation["tool_invocation"]
    Invocation --> Gatekeeper["Gatekeeper evidence validation"]

    Agent --> Final{"workflow result"}
    Final -->|success| Success["status = SUCCESS, answer saved"]
    Final -->|failed| Failed["status = FAILED"]

    Success --> Evaluation["self_evaluation merge"]
    Failed --> Evaluation
    Evaluation --> Trace["GET /api/diagnosis/{sessionId}/trace"]
    Success --> Feedback["POST /api/feedback"]
    Feedback --> Case["useful -> case_library"]

3. sessionId 规则

链路	sessionId 来源
Chat	如果请求带 sessionId，则复用；否则生成短 UUID
AIOps	如果 payload 带 sessionId，则复用；否则生成 UUID
Trace	URL path 中的 {sessionId}
Feedback	request body 中的 sessionId

设计含义：

• 同一个 sessionId 可以贯穿诊断、trace 查询和用户反馈。
• 当前诊断开始时会重置当前 session 的运行态字段，例如 answer、duration、step/tool count。
• sessionId 是业务关联键，不依赖数据库自增 ID 暴露给外部。

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	执行状态：PENDING / RUNNING / SUCCESS / FAILED
answer	Agent 最终返回给用户的报告或答复
self_evaluation	系统自评估 JSON
feedback	用户反馈：useful / not_useful / null

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

5. agent_step 写入

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

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

    Agent->>Hook: before_model(messages, sessionId)
    Hook->>DB: insert step_index / agent_name / model_input
    Agent-->>Agent: model call
    Agent->>Hook: after_model(messages, sessionId)
    Hook->>DB: update model_output / thought / has_tool_call / duration / token_count

当前记录：

• session_id
• step_index
• agent_name
• model_input
• model_output
• thought
• has_tool_call
• duration_ms
• token_count

6. tool_invocation 写入

工具调用记录真实工具事实，不记录模型猜测。

关键字段：

session_id
step_id
tool_name
input_params
output_preview
output_length
retrieval_layer
l0_match_count
l1_match_count
retrieval_details
  -> evidence_refs
relevance_level
dedup_reason
duration_ms
success
error_message

对 lookup_knowledge，retrieval_details 会承载 L0/L1、领域、证据状态、去重等检索细节。对日志、指标和知识库工具，retrieval_details.evidence_refs 会记录 Gatekeeper 可核验的最小证据引用：

{
  "evidence_refs": [
    {
      "raw_path": "$.logs[0]",
      "text": "最小证据文本"
    }
  ]
}

当工具明确没有返回匹配证据时，可以记录 raw_path=$.no_evidence。该路径只表示“本次工具查询未检索到匹配证据”，不表示问题被排除。

7. Trace API 聚合

GET /api/diagnosis/{sessionId}/trace

聚合逻辑：

diagnosis_session by sessionId
  + agent_step ordered by step_index
  + tool_invocation ordered by id
  -> DiagnosisTraceResponse

Trace 视图回答的问题：

• 这次诊断是否成功？
• 哪些 Agent 参与了？
• 每一步模型输入输出是什么摘要？
• 调用了哪些工具？
• 工具返回了什么证据？
• Gatekeeper / Verifier / Composer / AIOps rule 是否通过？
• 用户是否反馈有用？

8. Chat 与 AIOps 差异

维度	Chat	AIOps
agent_flow	CHAT	AI_OPS
编排方式	SequentialAgent: Planner -> Executor -> Gatekeeper -> Verifier -> Composer	SupervisorAgent: Planner + Executor
自评估	rule_evaluation + verifier_evaluation	aiops_rule_evaluation
答案字段	Chat 最终答复	告警分析报告
payload	用户自然语言 + history	alert payload 或 auto-discovery

9. 清理与边界

当前会话持久化边界：

• MySQL Trace 记录是主要可回放来源。
• Chat 历史仍可作为请求上下文传入 Agent，但不是本文档的主持久化模型。
• Redis 主会话存储是历史设计，不作为当前架构事实。
• RetrievedDocTracker 是 session 级运行时去重状态，诊断结束后清理。

10. 后续增强

可考虑：

1. Trace API 增加更结构化的 self_evaluation 展示。
2. agent_step 与 tool_invocation.step_id 建立更严格关联。
3. 对多轮同 session 诊断增加 run id，避免复用 session 时历史记录混杂。
4. 为 Trace 增加导出能力，服务面试演示和回归分析。