167 lines
6.6 KiB
Markdown
167 lines
6.6 KiB
Markdown
# 会话与 Trace 生命周期
|
||
|
||
**更新日期**：2026-07-17
|
||
**状态**：当前可运行架构
|
||
**参考历史文档**：`archive/2026-07-05-legacy/session-management.md`
|
||
|
||
## 1. 定位
|
||
|
||
当前 MVP 把“会话态”和“运行态”拆开：
|
||
|
||
```text
|
||
chat_session(sessionId)
|
||
-> diagnosis_run(runId)
|
||
-> agent_step(runId)
|
||
-> tool_invocation(runId)
|
||
```
|
||
|
||
- `sessionId` 表示多轮会话目录和 Redis 上下文。
|
||
- `runId` 表示一次可回放诊断执行。
|
||
- `DiagnosisTraceService` 聚合一个 run 的主记录、步骤和工具调用，形成可回放 Trace。
|
||
- 运行时不再映射、读取或写入 `diagnosis_session`；数据库中的旧表不属于当前版本契约。
|
||
|
||
## 2. 生命周期总图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start["request: chat / ai_ops"] --> Resolve["resolve sessionId"]
|
||
Resolve --> Session["ensure chat_session metadata"]
|
||
Session --> Run["create diagnosis_run(runId)"]
|
||
Run --> Running["run.status = RUNNING"]
|
||
|
||
Running --> Agent["Chat StateGraph / AIOps workflow"]
|
||
Agent --> Context["execution context(sessionId, runId)"]
|
||
Context --> StepHook["AgentLoggingHook"]
|
||
StepHook --> Step["agent_step(session_id, run_id)"]
|
||
Context --> Tool["Evidence tools"]
|
||
Tool --> Invocation["tool_invocation(session_id, run_id)"]
|
||
Invocation --> Gatekeeper["Gatekeeper evidence validation"]
|
||
|
||
Agent --> GraphTrace["Chat: save orchestration_trace"]
|
||
GraphTrace --> Final{"workflow result"}
|
||
Final -->|success| Success["run.status = SUCCESS, answer saved"]
|
||
Final -->|failed| Failed["run.status = FAILED"]
|
||
|
||
Success --> Evaluation["diagnosis_run.self_evaluation merge"]
|
||
Failed --> Evaluation
|
||
Evaluation --> Trace["GET /api/diagnosis/{sessionId}/trace?runId=..."]
|
||
Success --> Feedback["POST /api/feedback(sessionId, runId)"]
|
||
Feedback --> Case["useful -> case_library(run_id)"]
|
||
```
|
||
|
||
## 3. ID 规则
|
||
|
||
| ID | 来源 | 含义 |
|
||
|---|---|---|
|
||
| `sessionId` | Chat request `Id`、AIOps payload `sessionId`，缺失时由服务生成 | 多轮会话目录和 Redis 上下文 |
|
||
| `runId` | 每次有效 Chat/AIOps 执行创建 | 一次诊断运行和 Trace 回放边界 |
|
||
|
||
设计含义：
|
||
|
||
- 同一个 `sessionId` 可以贯穿多轮 Chat。
|
||
- 每次有效 Chat/AIOps 执行都会创建新的 `runId`。
|
||
- Trace 和 Feedback 必须同时传 `sessionId + runId`；后端不解析 latest run，也不回退旧表。
|
||
|
||
## 4. 运行状态流转
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> PENDING
|
||
PENDING --> RUNNING: start diagnosis
|
||
RUNNING --> SUCCESS: workflow completed
|
||
RUNNING --> FAILED: exception / empty state
|
||
SUCCESS --> SUCCESS: feedback submitted
|
||
FAILED --> FAILED: feedback submitted
|
||
```
|
||
|
||
字段边界：
|
||
|
||
| 字段 | 所属表 | 含义 |
|
||
|---|---|---|
|
||
| `status` | `diagnosis_run` | 单次运行执行状态 |
|
||
| `answer` | `diagnosis_run` | 本次运行最终报告或答复 |
|
||
| `self_evaluation` | `diagnosis_run` | 本次运行系统自评估 JSON |
|
||
| `orchestration_trace` | `diagnosis_run` | Chat StateGraph 路由摘要；包含 version、transitions、final node、termination reason、degraded 和 evidence retry count |
|
||
| `feedback` | `diagnosis_run` | 本次运行用户反馈 |
|
||
|
||
`feedback` 不修改 `status`。一个执行成功但用户标记 `not_useful` 的 run，仍然应该是 `SUCCESS + feedback=not_useful`。
|
||
|
||
## 5. agent_step 写入
|
||
|
||
`AgentLoggingHook` 在模型调用前后写入和回填 `agent_step`。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant Agent as Agent
|
||
participant Hook as AgentLoggingHook
|
||
participant DB as agent_step
|
||
|
||
Agent->>Hook: before_model(messages, sessionId, runId)
|
||
Hook->>DB: insert step(session_id, run_id, model_input, step_index)
|
||
Agent->>Hook: after_model(output, sessionId, runId)
|
||
Hook->>DB: update model_output, duration, token_count, has_tool_call
|
||
```
|
||
|
||
新写入必须带 `run_id`，同时保留 `session_id` 便于粗粒度排查。
|
||
|
||
## 6. tool_invocation 写入
|
||
|
||
工具调用记录同样通过执行上下文拿到 `sessionId + runId`：
|
||
|
||
```text
|
||
ToolInvocationRecorder
|
||
-> tool_invocation.session_id
|
||
-> tool_invocation.run_id
|
||
-> retrieval_details / evidence_refs
|
||
```
|
||
|
||
Gatekeeper 和 EvaluationService 按 `run_id` 读取工具调用，避免同一 session 的其他 run 参与评分或证据校验。Verifier 只读取 `VerifiedInputNode` 生成的 verified projection，不直接读取完整工具调用列表。
|
||
|
||
## 7. Trace API 聚合
|
||
|
||
```text
|
||
GET /api/diagnosis/{sessionId}/trace
|
||
GET /api/diagnosis/{sessionId}/trace?runId=run-...
|
||
```
|
||
|
||
聚合逻辑：
|
||
|
||
```text
|
||
diagnosis_run by sessionId + runId
|
||
+ run.orchestrationTrace parsed from diagnosis_run.orchestration_trace
|
||
+ chat_session metadata when available
|
||
+ agent_step where run_id = runId, ordered by the Trace API
|
||
+ tool_invocation where run_id = runId order by id
|
||
-> DiagnosisTraceResponse
|
||
```
|
||
|
||
当 `runId` 缺失时，Trace API 直接拒绝请求。当 `runId` 属于其他 `sessionId` 时，API 同样拒绝，不能泄漏其他会话的 Trace。
|
||
|
||
`run.orchestrationTrace` 只属于精确 Run 投影，响应不再提供兼容 `session` 对象。它解释 Graph 路由；`selfEvaluation` 解释证据/答案质量；`steps` 和 `toolInvocations` 保存详细执行证据，三者职责互不替代。非 StateGraph Run 的该字段可以为空。
|
||
|
||
## 8. Chat 与 AIOps 差异
|
||
|
||
| 维度 | Chat | AIOps |
|
||
|---|---|---|
|
||
| `agent_flow` | `CHAT` | `AI_OPS` |
|
||
| 编排方式 | bounded `StateGraph`: Planner / Executor / Gatekeeper / Verified Input / Verifier / Composer / Fallback | `SupervisorAgent`: Planner + Executor |
|
||
| 自评估 | `rule_evaluation` + `verifier_evaluation` | `aiops_rule_evaluation` |
|
||
| 答案字段 | Chat 最终答复 | 告警分析报告 |
|
||
| runId 暴露 | `/api/chat` JSON response | `/api/ai_ops` SSE metadata message |
|
||
|
||
Chat StateGraph 的权威自动化验收分三层：`DiagnosisGraphWorkflowTest` 验证路由，`DiagnosisGraphNodeContractTest` 验证真实 Node 输入输出，`ChatServiceGraphIntegrationTest` 验证 Run 生命周期、Trace 持久化和对外集成。
|
||
|
||
## 9. 清理与边界
|
||
|
||
- Redis 会话历史用于多轮上下文，不是长期审计记录。
|
||
- MySQL `diagnosis_run + agent_step + tool_invocation` 是主要可回放来源。
|
||
- `chat_session.expires_at` 只是目录元数据；Redis 消息历史可独立过期。
|
||
- `RetrievedDocTracker` 仍是 session 级运行时去重状态，诊断结束后清理。
|
||
|
||
## 10. 后续增强
|
||
|
||
1. Trace API 增加更结构化的 `self_evaluation` 展示。
|
||
2. `agent_step` 与 `tool_invocation.step_id` 建立更严格关联。
|
||
3. 数据库中的旧 `diagnosis_session` 表按独立数据治理任务决定是否物理删除；当前应用不再依赖它。
|