SuperBizAgent-java/interview/architecture.md

Architecture

系统分层

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 链路

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 链路

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 的地方。