# Architecture

## 系统分层

```text
API Layer
-> ChatController / DiagnosisTraceController

Agent Orchestration
-> ChatService / AiOpsService

Tools
-> lookupKnowledgeTool / queryLogs / queryMetrics / queryPrometheusAlerts

Persistence
-> diagnosis_session / agent_step / tool_invocation

Trace
-> GET /api/diagnosis/{sessionId}/trace
```

## Chat 链路

```mermaid
flowchart TD
    User[User Question] --> ChatAPI[POST /api/chat]
    ChatAPI --> Strategy[ChatService.executeChatWithStrategy]
    Strategy --> Complexity{QuestionComplexity}
    Complexity -->|simple| Single[ReactAgent]
    Complexity -->|complex| Planner[Planner Agent]
    Planner --> Executor[Executor Agent]
    Executor --> Tools[Evidence Tools]
    Tools --> Executor
    Executor --> Verifier[Verifier Agent]
    Verifier --> Answer[Final Answer]
    Answer --> Session[diagnosis_session]
    Planner --> Steps[agent_step]
    Executor --> Steps
    Verifier --> Steps
    Tools --> Invocations[tool_invocation]
    Session --> Trace[GET /api/diagnosis/{sessionId}/trace]
    Steps --> Trace
    Invocations --> Trace
```

关键代码：

- `ChatController.chat(...)`
- `ChatService.executeChatWithStrategy(...)`
- `ChatService.executeChatComplex(...)`
- `AgentLoggingHook`
- `ToolInvocationRecorder`
- `DiagnosisTraceService.getTrace(...)`

## AIOps 链路

```mermaid
flowchart TD
    Alert[Alert Payload or Empty Request] --> AiOpsAPI[POST /api/ai_ops]
    AiOpsAPI --> SessionEvent[SSE session event]
    AiOpsAPI --> AiOpsService[AiOpsService.executeAiOpsAnalysis]
    AiOpsService --> PromptMode{Payload?}
    PromptMode -->|yes| Targeted[PAYLOAD_TARGETED]
    PromptMode -->|no| Discovery[AUTO_DISCOVERY]
    Targeted --> Supervisor[ai_ops_supervisor]
    Discovery --> Supervisor
    Supervisor --> Planner[planner_agent]
    Supervisor --> Executor[executor_agent]
    Planner --> Tools[Prometheus / Logs / Knowledge]
    Executor --> Tools
    Tools --> Report[Alert Report]
    Report --> Persist[diagnosis_session.answer]
    Planner --> Steps[agent_step]
    Executor --> Steps
    Tools --> Invocations[tool_invocation]
    Persist --> Trace[GET /api/diagnosis/{sessionId}/trace]
    Steps --> Trace
    Invocations --> Trace
```

关键代码：

- `ChatController.aiOps(...)`
- `AIOpsRequest`
- `AiOpsService.resolveSessionId(...)`
- `AiOpsService.buildTaskPrompt(...)`
- `AiOpsService.hasAlertPayload(...)`
- `AiOpsService.persistFinalReport(...)`

## Trace 数据模型

### `diagnosis_session`

记录一次诊断会话的主信息：

- `session_id`
- `query`
- `status`
- `agent_flow`
- `total_duration_ms`
- `total_token_count`
- `step_count`
- `tool_call_count`
- `answer`
- `self_evaluation`
- `feedback`

### `agent_step`

记录 Agent 模型调用过程：

- `session_id`
- `step_index`
- `agent_name`
- `model_input`
- `model_output`
- `thought`
- `has_tool_call`
- `duration_ms`
- `token_count`

### `tool_invocation`

记录真实工具调用：

- `session_id`
- `tool_name`
- `input_params`
- `output_preview`
- `output_length`
- `retrieval_layer`
- `relevance_level`
- `duration_ms`
- `success`
- `error_message`

## 为什么 trace 是核心

Agent 系统的风险不只是“答案错”，还包括“答案看起来对但无法解释”。这个项目把执行链路拆成 session、step、tool 三层，让面试官可以看到：

- 模型为什么这么答
- 调了哪些工具
- 工具返回了什么证据
- Verifier 如何判断答案可信度
- 用户反馈如何回写到同一个 session

这就是项目区别于普通 Chatbot 的地方。