# 当前 MVP 架构

**更新日期**：2026-07-17
**状态**：当前可运行架构
**适用范围**：Demo、面试讲解、后续迭代规划

## 1. 系统定位

SuperBizAgent MVP 不是通用 Chatbot，而是面向故障诊断的 Agent 工程项目。

核心目标：

- 支持用户主动发起的 Chat 诊断。
- 支持 AIOps 告警触发的自动诊断。
- 保留 Agent 的规划、执行、验证过程。
- 工具调用必须显式、可追踪、可回放。
- RAG 检索必须通过 `lookup_knowledge` 暴露证据链。
- 每次诊断都沉淀 session、step、tool invocation 和 self evaluation。

## 2. 总体分层

```mermaid
flowchart TB
    subgraph API["API Layer"]
        ChatController["ChatController"]
        TraceController["DiagnosisTraceController"]
        SearchController["SearchController"]
        DocumentController["DocumentController"]
    end

    subgraph App["Application Service"]
        ChatService["ChatService"]
        AiOpsService["AiOpsService"]
        TraceService["DiagnosisTraceService"]
    end

    subgraph Agent["Agent Orchestration"]
        Supervisor["Supervisor"]
        StateGraph["Chat Diagnosis StateGraph"]
        Planner["Planner"]
        Executor["Executor"]
        Gatekeeper["Gatekeeper"]
        VerifiedInput["Verified Input"]
        Verifier["Verifier"]
        Composer["Composer"]
        Fallback["Fallback"]
    end

    subgraph Tools["Evidence Tools"]
        KnowledgeTool["lookup_knowledge"]
        LogsTool["query_logs"]
        MetricsTool["query_metrics"]
        AlertsTool["queryPrometheusAlerts"]
    end

    subgraph Skills["Skill / Playbook"]
        SkillRegistry["SkillRegistry"]
        PlannerSkillHook["PlannerSkillMetadataHook"]
        SkillsHook["SkillsAgentHook"]
        ReadSkill["read_skill"]
    end

    subgraph RAG["RAG Retrieval"]
        L0["KnowledgeIndexService"]
        VectorSearch["VectorSearchService"]
        VectorStore["Spring AI VectorStore"]
        SdkFallback["Milvus SDK fallback"]
    end

    subgraph Store["Persistence and Trace"]
        ChatSession["chat_session"]
        Run["diagnosis_run"]
        Step["agent_step"]
        Invocation["tool_invocation"]
        ApiDoc["api_document"]
        Milvus["Milvus/Zilliz"]
    end

    API --> App
    ChatService --> StateGraph
    StateGraph --> Planner
    StateGraph --> Executor
    StateGraph --> Gatekeeper
    StateGraph --> VerifiedInput
    StateGraph --> Verifier
    StateGraph --> Composer
    StateGraph --> Fallback
    AiOpsService --> Agent
    SkillRegistry --> PlannerSkillHook
    PlannerSkillHook --> Planner
    SkillRegistry --> SkillsHook
    SkillsHook --> Executor
    Executor --> ReadSkill
    Agent --> Tools
    KnowledgeTool --> RAG
    RAG --> Store
    Tools --> Invocation
    Agent --> Step
    App --> Session
    TraceService --> Session
    TraceService --> Step
    TraceService --> Invocation
```

```text
API Layer
  -> ChatController
  -> DiagnosisTraceController
  -> SearchController
  -> DocumentController

Application Service
  -> ChatService
  -> AiOpsService
  -> DiagnosisTraceService

Agent Orchestration
  -> Supervisor
  -> Planner
  -> Executor
  -> Gatekeeper
  -> Verifier
  -> Composer

Evidence Tools
  -> lookup_knowledge
  -> query_logs
  -> query_metrics
  -> queryPrometheusAlerts

Skill / Playbook
  -> SkillRegistry
  -> PlannerSkillMetadataHook gives Planner name/description only
  -> SkillsAgentHook gives Executor read_skill
  -> Verifier is isolated from skills

RAG Retrieval
  -> KnowledgeIndexService
  -> VectorSearchService
  -> Spring AI VectorStore
  -> Milvus SDK fallback

Persistence
  -> chat_session
  -> diagnosis_run
  -> agent_step.run_id
  -> tool_invocation.run_id
  -> api_document
  -> Milvus/Zilliz collection

Quality Gates
  -> executor gatekeeper
  -> chat verifier
  -> AIOps rule evaluation
  -> diagnosis eval baseline
  -> RAG retrieval baseline
```

## 3. Chat 诊断链路

```mermaid
sequenceDiagram
    autonumber
    actor User as 用户
    participant API as POST /api/chat
    participant Chat as ChatService
    participant Planner as Planner Agent
    participant Executor as Executor Agent
    participant Tool as Evidence Tools
    participant Gatekeeper as Gatekeeper Hook
    participant Verifier as Verifier Agent
    participant Composer as Composer Agent
    participant DB as Trace Tables
    participant Trace as Trace API

    User->>API: 提交诊断问题
    API->>Chat: execute chat strategy
    Chat->>DB: 创建 chat_session metadata + diagnosis_run(runId)
    Chat->>Planner: 复杂问题进入规划
    Planner->>DB: 写入 agent_step.run_id
    Planner->>Executor: 下发排查方向
    Executor->>Tool: lookup_knowledge / logs / metrics
    Tool->>DB: 写入 tool_invocation.run_id
    Tool-->>Executor: 返回证据
    Executor->>Gatekeeper: 输出 executor_evidence_v2
    Gatekeeper->>DB: 读取 tool_invocation.evidence_refs 并校验引用
    Gatekeeper->>Verifier: 传入已验真的 claims / excerpts
    Verifier->>DB: 合并 diagnosis_run.self_evaluation.verifier_evaluation
    Verifier->>Composer: 传入 allowed_claims / missing_info / actions
    Composer->>Chat: 生成最终用户答复
    Chat->>DB: 保存 diagnosis_run.answer
    User->>Trace: GET /api/diagnosis/{sessionId}/trace?runId=...
    Trace->>DB: 聚合 run / step / tool
    Trace-->>User: 返回可回放诊断链路
```

```text
POST /api/chat
  -> ChatService
      -> 简单问题：轻量回答
      -> 复杂诊断：Agent 编排
          -> Planner 制定排查方向
          -> Executor 调用证据工具
              -> lookup_knowledge
              -> query_logs
              -> query_metrics
          -> Gatekeeper 校验 Executor 证据引用真实性
          -> Verifier 判断 claim 是否能由已核验证据推出
          -> Composer 生成最终用户答复
      -> 保存 chat_session metadata
      -> 保存 diagnosis_run
      -> 保存 agent_step.run_id
      -> 保存 tool_invocation.run_id
      -> 合并 diagnosis_run.self_evaluation.verifier_evaluation
```

Chat 链路的质量门禁由三段组成：Gatekeeper 先做代码级引用验真，Verifier 再做 LLM 可推导性判断，Composer 最后控制对用户的表达边界。Gatekeeper、Verifier、Composer 的输出合并到当前 `diagnosis_run.self_evaluation.verifier_evaluation`，Trace API 会展示该验证结果。

Agent 编排细节见 [agent-orchestration.md](agent-orchestration.md)。

关键代码：

- `src/main/java/com/superbiz/agent/controller/ChatController.java`
- `src/main/java/com/superbiz/agent/service/ChatService.java`
- `src/main/java/com/superbiz/agent/service/SelfEvaluationMergeService.java`
- `src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java`

## 4. AIOps 诊断链路

```mermaid
flowchart TD
    Request["POST /api/ai_ops"] --> Payload{"包含告警 payload?"}
    Payload -->|是| Targeted["PAYLOAD_TARGETED"]
    Payload -->|否| Discovery["AUTO_DISCOVERY"]

    Targeted --> BuildPrompt["构造聚焦 payload 的诊断 prompt"]
    Targeted --> QueryAug["生成 recommended lookup_knowledge query"]
    Discovery --> DiscoverAlert["通过 queryPrometheusAlerts 发现活跃告警"]

    BuildPrompt --> Plan["Planner 规划排查"]
    QueryAug --> Plan
    DiscoverAlert --> Plan

    Plan --> Execute["Executor 收集证据"]
    Execute --> Knowledge["lookup_knowledge"]
    Execute --> Metrics["query_metrics / Prometheus"]
    Execute --> Logs["query_logs"]

    Knowledge --> Report["告警分析报告"]
    Metrics --> Report
    Logs --> Report

    Report --> RuleEval["AiOpsRuleEvaluationService"]
    RuleEval --> SelfEval["self_evaluation.aiops_rule_evaluation"]
    Report --> Trace["DiagnosisTraceService"]
    SelfEval --> Trace
```

```text
POST /api/ai_ops
  -> AiOpsService
      -> 判断是否有告警 payload
          -> PAYLOAD_TARGETED
          -> AUTO_DISCOVERY
      -> 构造 AIOps 诊断 prompt
      -> payload 模式补充 recommended lookup_knowledge query
      -> Agent 编排
          -> Planner / Executor
          -> Prometheus / logs / knowledge tools
      -> 生成告警分析报告
      -> AiOpsRuleEvaluationService
      -> 合并 diagnosis_run.self_evaluation.aiops_rule_evaluation
      -> Trace API 可查看全链路
```

AIOps 保留两种模式：

| 模式 | 触发条件 | 行为 |
|---|---|---|
| `PAYLOAD_TARGETED` | 请求包含 alertName、service、severity、description、timeRange 等字段 | 以 payload 为唯一主诊断对象，并生成推荐知识库 query |
| `AUTO_DISCOVERY` | 请求没有明确告警 payload | 先查询当前活跃告警，再选择目标排查 |

AIOps 当前使用轻量规则验证器，重点检查：

- 最终报告是否存在。
- payload 模式是否聚焦输入告警。
- 是否使用关键证据工具，例如 `lookup_knowledge`、日志、指标。

关键代码：

- `src/main/java/com/superbiz/agent/service/AiOpsService.java`
- `src/main/java/com/superbiz/agent/service/AiOpsRuleEvaluationService.java`

## 5. RAG 位置

RAG 不是隐藏在 Chat Advisor 里的隐式能力，而是 Executor 可以显式调用的工具：

```mermaid
flowchart LR
    Executor["Executor Agent"] --> Tool["lookup_knowledge Tool"]
    Tool --> L0["L0 domain/entity hint"]
    Tool --> Search["VectorSearchService"]
    L0 --> Search
    Search --> VectorStore["Spring AI VectorStore"]
    Search --> Fallback["Milvus SDK fallback"]
    VectorStore --> Normalize["score/rawScore/scoreLabel"]
    Fallback --> Normalize
    Normalize --> Evidence["evidence output"]
    Evidence --> Invocation["tool_invocation"]
    Evidence --> Executor
```

```text
Executor
  -> lookup_knowledge(query)
      -> L0 domain/entity hint
      -> VectorSearchService
          -> Spring AI VectorStore
          -> Milvus SDK fallback
      -> evidence shaping
      -> tool_invocation
```

保留显式工具的原因：

- Agent 何时检索、检索什么、证据是什么，必须能在 trace 中解释。
- AIOps payload 到 query 的业务映射需要项目内控制。
- `tool_invocation` 是后续评测、回放和面试讲解的核心材料。

RAG 总体设计见 [rag-architecture.md](rag-architecture.md)，检索运行细节见 [retrieval-observability.md](retrieval-observability.md)。

## 6. 持久化模型

当前诊断持久化以 session/run/trace 明细为核心：

```text
chat_session
  -> 多轮会话目录和元数据
  -> session_id / status / message_pair_count

diagnosis_run
  -> 一次诊断运行的主记录
  -> run_id / session_id
  -> query / status / agent_flow / answer
  -> self_evaluation
  -> step_count / tool_call_count / duration

agent_step
  -> Agent 模型调用步骤
  -> session_id / run_id
  -> step_index / agent_name
  -> model_input / model_output / thought
  -> duration / token_count

tool_invocation
  -> 工具调用事实
  -> session_id / run_id
  -> tool_name / input_params / output_preview
  -> retrieval_layer / retrieval_details
  -> retrieval_details.evidence_refs
  -> relevance_level / dedup_reason
  -> duration / success
```

说明：

- 旧的 `diagnosis_record` 已不是当前主模型。
- `diagnosis_session` 已降级为历史兼容和回滚表，新执行写入 `chat_session + diagnosis_run`。
- `api_document` 仍用于文档元数据管理。
- 文档向量内容存放在 Milvus/Zilliz collection 中。

会话和 Trace 生命周期见 [session-trace-lifecycle.md](session-trace-lifecycle.md)，完整数据关系见 [data-model.md](data-model.md)。

## 7. Trace API

```text
GET /api/diagnosis/{sessionId}/trace
GET /api/diagnosis/{sessionId}/trace?runId=run-...
```

Trace API 聚合：

- 会话元数据、运行状态和最终报告。
- Agent step 序列。
- 工具调用和检索细节。
- Chat Gatekeeper / Verifier / Composer 结果。
- Chat `run.orchestrationTrace` 路由摘要，独立于 self-evaluation 和步骤/工具明细。
- AIOps rule evaluation 结果。

Trace 是本项目区别于普通问答系统的关键：答案不是孤立文本，而是可以追溯到 Agent 决策、工具调用和证据来源。

Prompt、StateGraph、Gatekeeper、Verifier、Composer 和评测门禁的完整说明见 [harness-quality-gates.md](harness-quality-gates.md)，用户反馈与 `self_evaluation` 闭环见 [feedback-architecture.md](feedback-architecture.md)。

## 8. 质量门禁

当前质量门禁分层如下：

| 门禁 | 位置 | 作用 |
|---|---|---|
| Executor Gatekeeper | `GatekeeperNode` / `ExecutorGatekeeperService` | 校验当前 Run 的 invocation、`raw_path`、`evidence_excerpt` 是否真实 |
| Verified Input | `VerifiedInputNode` | 仅投影 Gatekeeper 通过的 claims/evidence，阻断完整工具 Trace 进入 Verifier |
| Chat Verifier | `VerifierNodeAdapter` | 判断已验真证据是否能推出 Executor claims |
| Chat Composer / Fallback | `ComposerNodeAdapter` / `FallbackNode` | 输出受控答复；异常分支也必须安全终止 |
| Graph routing | `DiagnosisGraphWorkflowTest` / `run.orchestrationTrace` | 验证条件边、有限重试、最终节点和终止原因 |
| AIOps Rule Evaluation | `AiOpsRuleEvaluationService` | 校验告警诊断是否聚焦 payload 并使用证据 |
| Diagnosis Eval Baseline | `mvp/eval/` | 固化诊断 trace 和报告行为 |
| RAG Retrieval Baseline | `eval/rag-retrieval/` | 固化检索召回行为，避免 RAG 重构回退 |
| Live RAG Acceptance | `scripts/eval_rag_live_acceptance.py` | 在运行环境中验证重建索引后的真实检索 |

## 9. 当前完成状态

已经完成：

- Chat 和 AIOps 两条入口链路。
- Chat 复杂诊断已单轨切换到 bounded StateGraph，并持久化 Run-owned `orchestration_trace`。
- 显式 `lookup_knowledge` Agent Tool。
- L0 从最终决策降级为 domain/entity hint。
- `VectorSearchService` 作为稳定检索门面。
- Spring AI VectorStore 读取路径。
- Milvus SDK fallback。
- `score` / `rawScore` / `scoreLabel` 分数语义拆分。
- `title`、`breadcrumb`、`content` 参与 embedding 文本。
- `tool_invocation` 记录检索层、relevance level、dedup reason。
- Chat verifier 和 AIOps rule evaluation 合并进 `self_evaluation`。
- Chat Executor 结构化输出 `executor_evidence_v2`，不再直接承担最终用户答复。
- `tool_invocation.retrieval_details.evidence_refs` 支持 `raw_path` 精确引用和 `$.no_evidence` 负向证据。
- Gatekeeper 对 Executor 引用做代码级验真，并在审计中记录 `rule_set_version` 和规则元数据摘要。
- Verifier 只判断可推导性。
- Composer 在 Verifier 之后生成最终用户表达，并限制 negative observation 过度表述。
- RAG offline baseline 和 live acceptance 脚本。

暂不作为当前已完成能力声明：

- 完整 QueryTransformer / MultiQuery。
- BM25、RRF、cross-encoder rerank。
- 完整邻居 chunk / section context expansion。
- VectorStore 写入路径全面迁移。
- 完整 LLM-based AIOps verifier。

后续 Agent 拆分、Skill/Playbook、MCP 工具协议化和进程隔离等方向见 [evolution-roadmap.md](evolution-roadmap.md)。

## 10. 关键代码索引

| 能力 | 代码 |
|---|---|
| Chat 入口与编排 | `ChatController`, `ChatService` |
| Chat StateGraph | `ChatDiagnosisGraphRuntime`, `DiagnosisGraphFactory`, `DiagnosisRealGraphActionsFactory` |
| AIOps 入口与编排 | `ChatController.aiOps`, `AiOpsService` |
| AIOps 规则验证 | `AiOpsRuleEvaluationService` |
| 知识库工具 | `LookupKnowledgeTool` |
| L0 hint | `KnowledgeIndexService` |
| 向量检索门面 | `VectorSearchService` |
| 文档切片 | `DocumentChunkService` |
| 向量写入 | `VectorIndexService` |
| Spring AI VectorStore 配置辅助 | `SpringAiVectorStoreSidecarService` |
| Trace 聚合 | `DiagnosisTraceService` |
| 工具调用记录 | `ToolInvocationRecorder` |
| Executor 引用验真与投影 | `GatekeeperNode`, `ExecutorGatekeeperService`, `VerifiedInputNode` |
| self_evaluation 合并 | `SelfEvaluationMergeService` |