zhuyongxin
e3f20b1f06
- 创建 devflow 项目档案（brief/evidence/decisions/acceptance） - 更新 devflow/index.md 索引 - 移动 OpenSpec 到 archive
94 lines
3.6 KiB
Markdown
94 lines
3.6 KiB
Markdown
# 会话存储体系 — 设计文档
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
用户请求
|
||
│
|
||
▼
|
||
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 计数器 |
|