# 会话存储体系

## 问题

当前 `diagnosis_record` 单表无法支撑通用会话存储需求：

1. 字段语义耦合在"告警分析"领域（fault_category、error_code 等），ChatService 通用问答场景无法使用
2. 缺少 Agent 决策链维度（两个 Agent 的多轮思考过程无法区分和追溯）
3. 检索质量不可评估（L0/L1 命中层、截断信息、召回内容长度无记录）
4. 指标不完整（缺 token 用量、自评信号、采纳率）

## 建议方案

将单表拆分为三表体系，用 `session_id` 关联：

```
diagnosis_session (1)
      └── agent_step (0:N) —— 每次 Agent 决策
              └── tool_invocation (0:N) —— 每步中的工具调用
```

### 三表职责

| 表 | 职责 | 示例查询 |
|---|---|---|
| diagnosis_session | 诊断级元数据 + 汇总指标 | "某次诊断的总耗时和 Token 消耗" |
| agent_step | 决策链：每步 Agent 的输入输出摘要 | "Planner 的思考过程和工具调用决策" |
| tool_invocation | 工具调用明细 + 检索质量 | "lookup_knowledge 的 L0/L1 命中分布" |

### 集成点

1. `AgentLoggingHook` → 写入 `agent_step`
2. `LookupKnowledgeTool` → 写入 `tool_invocation`
3. `ChatService` / `AiOpsService` → 创建/更新 `diagnosis_session`

## 范围

- 新建 3 张表（Flyway 迁移）
- 新建 3 个 JPA Entity + 3 个 Repository
- 改造 AgentLoggingHook、LookupKnowledgeTool、ChatService、AiOpsService
- 现有 `diagnosis_record` 表保持不动

## 非目标

- 不涉及 UI 层面的会话展示
- 不涉及历史数据迁移
- 不涉及 diagnosis_record 的合并或废弃

## 上下文约束

- Flyway 迁移脚本命名：V005__create_diagnosis_session.sql 起
- JPA ddl-auto 使用 validate 模式
- JSON 列使用 `@JdbcTypeCode(SqlTypes.JSON)`（同现有 diagnosis_record 的 tool_calls 字段）
- 已有 SessionManager/Redis 会话机制不变，新表作为持久化补充

## 已确认的设计决策

| 决策 | 结论 | 来源 |
|------|------|------|
| AgentLoggingHook 创建方式 | 改造为 Spring Bean（@Component + 构造注入） | grill user-interview |
| AiOpsService 钩子范围 | Planner 和 Executor 各加 AgentLoggingHook | grill user-interview |
| Supervisor 步骤记录 | 不单独记录，由子 Agent 步骤覆盖 | grill user-interview |
| tool_invocation 截断长度 | 500 字符 | proposal 默认 |
| sessionId 传递机制 | ThreadLocal（SessionContextHolder） | grill user-interview |
| AiOps 步骤记录 | 只记 Planner/Executor，不记 Supervisor | grill user-interview |

## 风险

- AgentLoggingHook 目前是同步写日志，新增 DB 写可能影响 Agent 响应时间 → 考虑异步写入或先同步后优化
- tool_invocation 的 output_preview 截断长度需合理（建议 500 字符）