SuperBizAgent-java/openspec/changes/archive/2026-06-26-session-storage/proposal.md

会话存储体系

问题

当前 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 字符）