refactor(harness): remove legacy agent architecture

2026-07-22 18:02:01 +08:00
parent bc36248cd8
commit 8ee7cc0b70
148 changed files with 3091 additions and 13889 deletions
@@ -0,0 +1,160 @@
+# 会话与 Trace 生命周期
+
+**更新日期**：2026-07-10
+**状态**：当前可运行架构
+**参考历史文档**：`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["Agent 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 --> 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 新客户端应传 `runId`；只传 `sessionId` 时兼容解析 latest run。
+- latest run 排序使用 `diagnosis_run.created_at DESC, id DESC`，不使用 `updated_at`。
+
+## 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 |
+| `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
+```
+
+Verifier、Gatekeeper 和 EvaluationService 应按 `run_id` 读取工具调用，避免同一 session 的其他 run 参与评分或证据校验。
+
+## 7. Trace API 聚合
+
+```text
+GET /api/diagnosis/{sessionId}/trace
+GET /api/diagnosis/{sessionId}/trace?runId=run-...
+```
+
+聚合逻辑：
+
+```text
+diagnosis_run by sessionId + runId
+  + 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 为兼容旧客户端解析最新 run，并在响应中返回 resolved `runId`。当 `runId` 属于其他 `sessionId` 时，API 必须拒绝，不能泄漏其他会话的 Trace。
+
+## 8. Chat 与 AIOps 差异
+
+| 维度 | Chat | AIOps |
+|---|---|---|
+| `agent_flow` | `CHAT` | `AI_OPS` |
+| 编排方式 | `SequentialAgent`: Planner -> Executor -> Gatekeeper -> Verifier -> Composer | `SupervisorAgent`: Planner + Executor |
+| 自评估 | `rule_evaluation` + `verifier_evaluation` | `aiops_rule_evaluation` |
+| 答案字段 | Chat 最终答复 | 告警分析报告 |
+| runId 暴露 | `/api/chat` JSON response | `/api/ai_ops` SSE metadata message |
+
+## 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` 只读观察期结束后，再评估数据库层面的约束收紧或归档策略。