# 会话与 Trace 生命周期

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

## 1. 定位

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

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

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

## 2. 生命周期总图

```mermaid
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. 运行状态流转

```mermaid
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`。

```mermaid
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`：

```text
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 聚合

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

聚合逻辑：

```text
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` 表按独立数据治理任务决定是否物理删除；当前应用不再依赖它。