# 面试一页式架构讲解

**用途**：面试现场 2-5 分钟讲清项目  
**适合场景**：开场介绍、架构追问、Demo 前铺垫

## 1. 一句话

SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：它把用户问题或 AIOps 告警转换成 Planner、Executor、Gatekeeper、Verifier、Composer 的诊断链路，所有工具证据、模型步骤、最终答案、自评估和用户反馈都能通过同一个 `sessionId` 回放。

## 2. 一张图

```mermaid
flowchart TB
    User["用户问题 / AIOps 告警"] --> API["API Layer"]

    API --> Chat["ChatService"]
    API --> AiOps["AiOpsService"]

    Chat --> ChatFlow["Chat: Planner -> Executor -> Gatekeeper -> Verifier -> Composer"]
    AiOps --> AiOpsFlow["AIOps: Supervisor -> Planner / Executor"]

    ChatFlow --> Tools["Evidence Tools"]
    AiOpsFlow --> Tools

    Tools --> Knowledge["lookup_knowledge"]
    Tools --> Logs["query_logs"]
    Tools --> Metrics["query_metrics / Prometheus"]

    Knowledge --> RAG["RAG: L0 hint + VectorSearchService"]
    RAG --> VectorStore["Spring AI VectorStore"]
    RAG --> SDK["Milvus SDK fallback"]

    ChatFlow --> Trace["Trace Persistence"]
    AiOpsFlow --> Trace
    Tools --> Trace

    Trace --> Session["diagnosis_session"]
    Trace --> Step["agent_step"]
    Trace --> Invocation["tool_invocation"]

    Invocation --> Verifier["Verifier / Rule Evaluation"]
    Verifier --> SelfEval["self_evaluation"]

    Session --> TraceAPI["GET /api/diagnosis/{sessionId}/trace"]
    Step --> TraceAPI
    Invocation --> TraceAPI
    SelfEval --> TraceAPI

    TraceAPI --> Feedback["POST /api/feedback"]
    Feedback --> Case["useful -> case_library"]
```

## 3. 面试讲法

```text
这个项目不是把问题直接丢给大模型，而是把诊断拆成可审计的执行链路。

Chat 复杂问题走 Planner -> Executor -> Gatekeeper -> Verifier -> Composer：
Planner 负责拆解，Executor 只负责调用知识库、日志和指标工具并提炼带证据引用的微观事实；Gatekeeper 用代码核对 invocation、raw_path 和 excerpt 是否真实；Verifier 判断这些事实能否由已验真的证据推出；Composer 只把允许表达的结论写成最终答案。

AIOps 告警入口走 Supervisor 调度 Planner/Executor：
如果请求里有 alert payload，系统会进入 PAYLOAD_TARGETED 模式，报告必须聚焦这个告警，而不是被当前环境中的其他活跃告警带偏。

所有过程都会落到 diagnosis_session、agent_step、tool_invocation。
所以我可以用一个 sessionId 回放：模型怎么规划、调了哪些工具、工具返回什么、Gatekeeper 怎么验真、Verifier 怎么判定、Composer 最后怎么表达、用户最后是否反馈有用。
```

## 4. 五个亮点

| 亮点 | 怎么讲 |
|---|---|
| 可追踪 Agent | 每次诊断都有 `sessionId`，Trace API 可以回放 session、step、tool |
| 显式工具证据链 | `lookup_knowledge`、日志、指标都记录到 `tool_invocation` |
| RAG 工程化 | L0 降级为 hint，Spring AI VectorStore 做主检索，SDK fallback 保底 |
| 质量门禁 | Chat Gatekeeper 验引用、Verifier 判可推导、Composer 控表达，AIOps rule evaluation 控制告警聚焦 |
| 反馈闭环 | useful 反馈沉淀 `case_library`，not_useful 保留 bad case 信号 |

## 5. 三个关键取舍

### 取舍 1：为什么不用隐式 Advisor 做 RAG？

因为这个项目强调 Agent 决策可见性。`lookup_knowledge` 必须作为显式工具调用被记录，这样才能解释“什么时候检索、检索了什么、证据如何支撑结论”。

### 取舍 2：为什么保留 Milvus SDK fallback？

因为迁移到 Spring AI VectorStore 期间，schema、collection、score 语义都可能变化。`auto` 模式先走 VectorStore，失败时 fallback 到 SDK，保证 MVP 主链路可运行，也方便对比新旧检索质量。

### 取舍 3：为什么 self_evaluation 分三层？

因为三类评估回答的问题不同：

```text
rule_evaluation         -> 工具证据是否充分
verifier_evaluation     -> Chat 答案关键事实是否有证据支撑
aiops_rule_evaluation   -> AIOps 报告是否聚焦告警并使用证据
```

## 6. 面试官可能追问

| 追问 | 回答方向 |
|---|---|
| 怎么防止幻觉？ | Executor 输出 `executor_evidence_v2`，每个 claim 绑定 `source_invocation_id + raw_path + evidence_excerpt`；Gatekeeper 用 `tool_invocation.retrieval_details.evidence_refs` 核验引用真实性；Verifier 只判断可推导性；Composer 防止把 no-evidence 说成已排除 |
| RAG 质量怎么保证？ | offline golden cases + live acceptance + trace inspection 三层验证 |
| 为什么 L0 不直接返回？ | L0 子串命中不等于语义相关，当前只做 domain/entity hint 和 metadata filter |
| AIOps 如何避免跑偏？ | payload 模式生成 recommended query，并用 rule evaluation 检查报告聚焦输入告警 |
| 下一步怎么演进？ | 固化 E2E fixture、Prompt version、Gatekeeper 规则配置化、邻居 chunk、AIOps LLM Verifier、MCP 工具协议化 |

## 7. 现场演示入口

- Demo 脚本：`mvp/demo/ten-minute-interview-demo.md`
- 故事案例：`interview/story-cases.md`
- 架构细节：`mvp/architecture/README.md`