# 会话存储体系 — 设计文档

## 架构概览

```
用户请求
   │
   ▼
ChatService.executeChat() / AiOpsService.executeAiOpsAnalysis()
   │   ┌── 创建 diagnosis_session (status=RUNNING)
   │
   ▼
Agent Loop（带 AgentLoggingHook）
   │
   ├── beforeModel() → 创建 agent_step（记录 model_input 摘要）
   ├── afterModel()  → 更新 agent_step（记录 model_output、token_count、工具调用决策）
   │
   ├── 工具执行（如 lookup_knowledge）
   │     └── 写入 tool_invocation（L0/L1 明细、耗时、是否截断）
   │
   └── 循环直到模型不再调用工具
   │
   ▼
更新 diagnosis_session (status=SUCCESS/FAILED，汇总指标)
```

## 表结构

### diagnosis_session

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO_INC | 自增主键 |
| session_id | VARCHAR(64) UNIQUE | 会话唯一 ID |
| query | TEXT | 用户原始问题 |
| status | VARCHAR(16) DEFAULT 'PENDING' | PENDING/RUNNING/SUCCESS/FAILED |
| agent_flow | VARCHAR(32) | CHAT / AI_OPS |
| total_duration_ms | INT | 总耗时 |
| total_token_count | INT | 总 Token 消耗 |
| step_count | INT | Agent 步数 |
| tool_call_count | INT | 工具调用次数 |
| self_evaluation | JSON | 自评估信号 |
| feedback | VARCHAR(16) | 用户反馈 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

### agent_step

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO_INC | 自增主键 |
| session_id | VARCHAR(64) | 关联 diagnosis_session |
| step_index | INT | 当前 Agent 的第几步 |
| agent_name | VARCHAR(32) | intelligent_assistant / planner / executor |
| model_input | JSON | 模型输入摘要 [{role, content_truncated}] |
| model_output | JSON | 模型输出摘要 {text, tool_calls} |
| thought | TEXT | Agent 思考过程文本 |
| has_tool_call | BOOLEAN | 本轮是否调用了工具 |
| duration_ms | INT | 本轮耗时 |
| token_count | INT | 本轮 Token 消耗 |
| created_at | DATETIME | 创建时间 |

### tool_invocation

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK AUTO_INC | 自增主键 |
| session_id | VARCHAR(64) | 关联 diagnosis_session |
| step_id | BIGINT | 关联 agent_step.id（可为空） |
| tool_name | VARCHAR(64) | lookup_knowledge / 等 |
| input_params | JSON | 工具入参 |
| output_preview | TEXT | 输出前 500 字符 |
| output_length | INT | 输出总字符数 |
| retrieval_layer | VARCHAR(8) | L0 / L1 / L0+L1 |
| l0_match_count | INT | L0 匹配数 |
| l1_match_count | INT | L1 匹配数 |
| is_truncated | BOOLEAN | 内容是否被截断 |
| retrieval_details | JSON | L0 标题列表、L1 分数等 |
| duration_ms | INT | 工具执行耗时 |
| success | BOOLEAN | 是否成功 |
| error_message | TEXT | 失败原因 |
| created_at | DATETIME | 创建时间 |

## 关键设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| Hook 创建方式 | Spring Bean (@Component) | 需要注入 Repository |
| DB 写入时机 | 同步（Hook 内部直接写入） | MVP 阶段简化，后续可异步化 |
| session_id 向 Hook 传递 | 通过 RunnableConfig 的 metadata 携带 | Spring AI Alibaba Agent Framework 原生支持 |
| session_id 向 Tool 传递 | ThreadLocal（SessionContextHolder 工具类） | Tool 不在 Hook 调用链中，无法获取 RunnableConfig |
| tool_invocation 关联 agent_step | 通过 step_id 外键（不加约束） | 允许 tool_invocation 独立于 agent_step 写入 |
| AiOps 多 Agent 记录 | 每个子 Agent 独立 Hook 实例 | 各自维护 step_index 计数器 |