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

会话存储体系 — 设计文档

架构概览

用户请求
   │
   ▼
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 计数器