SuperBizAgent-java/mvp/architecture/agent-architecture.md

# Agent 架构设计

## 一、总体架构

### 1.1 核心理念

```
不是一个人干所有活，而是团队协作

类比：医院会诊
- Supervisor  = 院长（调度资源）
- Planner     = 分诊台（判断病情，分配合适科室）
- SubAgent    = 专科医生（各有所长，精准诊断）
- Verifier    = 质检员（验证诊断，防止误诊）
```

### 1.2 Agent 全景图

```
用户输入
    ↓
┌──────────────────────────────────────────────────────────┐
│              Supervisor Agent（调度者）                    │
│              "谁来干？什么时候干？结果给谁看？"             │
└──────┬───────────────────────────────────────────────────┘
       │
       ↓
┌──────────────────────────────────────────────────────────┐
│              Planner Agent（规划者 + 分诊）                │
│                                                           │
│  职责1：分析问题类型，确定 fault_category                  │
│  职责2：制定排查策略，拆解执行步骤                         │
│  职责3：根据 fault_category 选择合适的 SubAgent           │
│  职责4：根据 Executor 反馈动态调整（Replanner）            │
│  职责5：最终生成诊断报告草稿                               │
└──────┬───────────────────────────────────────────────────┘
       │
       ↓ fault_category = EXTERNAL_API
┌──────────────────────────────────────────────────────────┐
│                    SubAgent 执行层                         │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌─────────────────────┐  ┌─────────────────────────────┐ │
│  │ ExternalApiSubAgent │  │ InternalErrorSubAgent       │ │
│  │ "接口专家"          │  │ "代码专家"                   │ │
│  │                     │  │                             │ │
│  │ 工具：              │  │ 工具：                      │ │
│  │ - searchDoc         │  │ - queryLogs                 │ │
│  │ - queryLogs         │  │ - queryTrace                │ │
│  │ - queryTrace        │  │ - queryOrder                │ │
│  │ - queryOrder        │  │                             │ │
│  │                     │  │ Prompt：堆栈分析、代码定位    │ │
│  │ Prompt：文档对比、   │  │                             │ │
│  │ 参数校验、签名检查   │  │                             │ │
│  └─────────────────────┘  └─────────────────────────────┘ │
│                                                           │
│  ┌─────────────────────┐                                 │
│  │ DatabaseSubAgent    │   Phase 2 扩展...               │
│  │ "数据库专家"        │   ┌─────────────────────────┐   │
│  │                     │   │ CacheSubAgent           │   │
│  │ 工具：              │   │ "缓存专家"              │   │
│  │ - queryLogs         │   └─────────────────────────┘   │
│  │ - queryTrace        │   ┌─────────────────────────┐   │
│  │ - queryOrder        │   │ NetworkSubAgent         │   │
│  │                     │   │ "网络专家"              │   │
│  │ Prompt：死锁分析、   │   └─────────────────────────┘   │
│  │ 慢查询优化、索引建议  │                                 │
│  └─────────────────────┘                                 │
│                                                           │
└───────────────────┬───────────────────────────────────────┘
                    │ 执行结果 + 证据
                    ↓
┌──────────────────────────────────────────────────────────┐
│              Verifier Agent（验证者）                      │
│              "诊断报告是否成立？证据是否充分？"             │
│                                                           │
│  第一轮：事实核查 ──→ 第二轮：逻辑验证 ──→ 第三轮：完整性检查│
│                                                           │
│  判决：PASS ──→ 直接输出报告                              │
│        REVISE ──→ 有问题需修正，返回 Planner              │
│        REJECT ──→ 诊断不成立，返回 Planner 重新分析        │
└──────────────────────┬───────────────────────────────────┘
                       │
                       ↓
                  诊断报告输出
```

---

## 二、Agent 详细设计

### 2.1 Supervisor Agent（调度者）

**职责**：总指挥，协调所有 Agent 的工作流程

**System Prompt 核心**：
```
你是 AI Ops Supervisor，负责调度 Agent 协作。

调度规则：
1. 接收用户任务 → 先调用 Planner 分析
2. Planner 完成规划后 → 调用合适的 SubAgent 执行
3. SubAgent 执行完成后 → 决定：
   - 继续执行下一步
   - 返回给 Planner 重新规划
   - 调用 Verifier 校验
4. Verifier 校验完成后 → 决定：
   - PASS → 输出报告给用户
   - REVISE → 返回 Planner 修正
   - REJECT → 返回 Planner 重新分析

你只做调度，不直接执行工具，不生成报告。
```

---

### 2.2 Planner Agent（规划者 + 分诊 + Replanner）

**职责**：分析问题、制定策略、选择 SubAgent、动态调整

**System Prompt 核心**：
```
你是 Planner Agent，同时承担 Replanner 角色。

职责 1：分析问题类型（分诊）
- 有错误码 + 接口URL → EXTERNAL_API
- 有堆栈信息 → INTERNAL_ERROR  
- 有数据库错误码（如1213）→ DATABASE
- 有缓存相关关键词 → CACHE

职责 2：制定排查策略
- 确定 fault_category 后，选择对应的 SubAgent
- 制定执行步骤（每步包含：工具名、参数、预期输出）

职责 3：动态调整（Replanner）
- 每次 Executor 返回结果后，评估：
  - 证据是否充分？
  - 需要补充什么信息？
  - 是否需要更换 SubAgent？
- Decision: EXECUTE（继续执行）| FINISH（生成报告）

职责 4：生成诊断报告草稿
- 当 decision=FINISH 时，汇总所有证据
- 按照报告模板生成草稿
- 交给 Verifier 验证

输出格式：
{
  "decision": "EXECUTE|FINISH",
  "fault_category": "EXTERNAL_API|INTERNAL_ERROR|DATABASE|...",
  "sub_agent": "ExternalApiSubAgent|InternalErrorSubAgent|...",
  "steps": [
    {
      "tool": "queryOrder",
      "params": {"orderId": "xxx"},
      "expect": "订单详情和错误信息"
    }
  ]
}

约束：
- 禁止编造数据，只能引用工具返回的真实内容
- 如果连续 3 次调用同一工具仍失败，停止该方向
- 如果所有方向都无进展，在报告结论部分诚实说明"无法完成"
```

---

### 2.3 SubAgent 执行层（专科医生）

#### 2.3.1 SubAgent 设计原则

```
每个 SubAgent 的差异化要素：
1. 专属 System Prompt（不同的分析思路）
2. 专属工具集（不是所有工具都给）
3. 专属 Skill（不同故障类型走不同诊断流程）
4. 专属 Few-shot 示例（减少推理错误）
```

#### 2.3.2 MVP 版本 SubAgent 清单

**ExternalApiSubAgent（外部接口专家）**

```
System Prompt 核心：
- 对比请求报文 vs 接口文档的必填字段
- 检查签名算法、加密方式是否正确
- 解读第三方返回的错误码（查接口文档）
- 检查省份差异（不同省份的字段要求可能不同）
- 检查 HTTP 状态码（4xx/5xx 的含义）

专属工具：
- searchDoc（检索接口文档，必须）
- queryLogs（查网关/第三方日志）
- queryTrace（看调用链耗时分布）
- queryOrder（查订单基本信息和请求参数）

专属 Skill：
- /diagnose-by-orderid（按订单号诊断）
- /diagnose-by-errorcode（按错误码诊断）
```

**InternalErrorSubAgent（内部错误专家）**

```
System Prompt 核心：
- 分析堆栈信息：定位异常类、方法、行号
- 分析空指针：哪个对象为 null？为什么？
- 分析类型转换、数组越界、参数格式
- 分析异常传播路径（哪个方法抛出的，谁调用的）
- 建议具体的代码修改位置和修改方式

专属工具：
- queryLogs（查错误堆栈，必须）
- queryTrace（查调用链，定位是哪个服务出错）
- queryOrder（查触发错误的请求上下文）

专属 Skill：
- /diagnose-by-stacktrace（堆栈分析诊断）
```

**DatabaseSubAgent（数据库专家）**

```
System Prompt 核心：
- 分析死锁日志：事务A等什么锁？事务B持什么锁？
- 分析慢查询：全表扫描？没走索引？JOIN 太多？
- 分析连接池：活跃/空闲/等待数，是否耗尽？
- 建议索引优化、SQL 改写、连接池参数调整

专属工具：
- queryLogs（查数据库错误日志，必须）
- queryTrace（查数据库调用耗时）
- queryOrder（查触发 SQL 的业务请求）

专属 Skill：
- /quick-check（快速检查，只做 SQL 分析和连接池检查）
```

---

### 2.4 Verifier Agent（验证者）

**职责**：验证诊断报告的准确性和完整性

**System Prompt 核心**：

```
你是 Verifier Agent（验证者），负责验证诊断报告的准确性和完整性。

## 验证流程

### 第一轮：事实核查（Fact Check）
- 报告中引用的错误码：是否在工具返回结果中存在？
- 根因结论：是否有日志/报文/文档证据支撑？
- 修复方案：是否引用了文档或案例中的标准方案？
- 数据准确性：引用的数值（耗时、错误率）是否与工具返回一致？

### 第二轮：逻辑验证（Logic Check）
- 根因 → 症状的因果关系是否成立？
- 是否存在其他可能的根因（根因是否唯一）？
- 修复方案是否能真正解决根因？
- 修复方案是否会引入新问题？

### 第三轮：完整性检查（Completeness Check）
- 根因分析章节不能为空
- 证据链章节必须有具体引用（标注来源）
- 修复方案章节必须可执行（不是空话）
- 不确定的结论必须标注"低置信度"

## 判决结果

{
  "verdict": "PASS|REVISE|REJECT",
  "score": 0-100,
  "issues": [
    {
      "type": "fact_check|logic_check|completeness",
      "severity": "error|warning",
      "detail": "具体问题描述",
      "evidence": "与哪个工具返回数据矛盾"
    }
  ],
  "suggestion": "如果 REVISE，给出具体的修正建议"
}

判决规则：
- PASS：无 error 级别问题，score >= 70
- REVISE：有 error 级别问题但可修正，score 40-69
- REJECT：证据严重不足或逻辑矛盾，score < 40
- 如果发现疑似编造数据 → 直接 REJECT
```

---

## 三、Skill 体系设计

### 3.1 设计理念

```
Skill = 标准化的诊断流程

为什么需要 Skill？
- 没有 Skill：Agent 自由发挥，流程不可控，质量不稳定
- 有 Skill：固定步骤、明确输入输出、异常处理标准化

类比：医生看病的 SOP
- 不同症状走不同 SOP
- 每个 SOP 有固定检查项目
- 异常情况有预案
```

### 3.2 MVP 版本 Skill 清单

```
/diagnose-by-orderid        按订单号一键诊断（最常用）
/diagnose-by-errorcode      按错误码分类诊断
/diagnose-by-stacktrace     堆栈分析诊断（内部错误）
/quick-check                快速检查（只做基础排查）
```

### 3.3 Skill 定义结构

```yaml
skill:
  name: diagnose-by-orderid
  description: 根据订单号一键诊断故障
  applicable_fault_types: [EXTERNAL_API, INTERNAL_ERROR, DATABASE]
  
  input:
    order_id:
      required: true
      description: 订单号
      validation: 格式校验
    
  workflow:
    - step: 1
      name: 查询订单信息
      tool: queryOrder
      input_from: user_input
      on_failure: abort
      on_failure_message: "订单不存在或查询失败"
      
    - step: 2
      name: 获取链路追踪
      tool: queryTrace
      input_from: step1.traceId
      on_failure: skip
      on_failure_message: "链路追踪数据缺失，继续排查"
      
    - step: 3
      name: 查询错误日志
      tool: queryLogs
      input_from: step1.traceId
      on_failure: skip
      on_failure_message: "日志查询失败，继续排查"
      
    - step: 4
      name: 检索接口文档
      tool: searchDoc
      input_from: step1.errorCode + step1.province
      on_failure: skip
      on_failure_message: "文档检索失败，使用已知信息"
      
    - step: 5
      name: 检索相似案例
      tool: recommendCase
      input_from: step1.errorCode + step1.faultCategory
      on_failure: skip
      on_failure_message: "无相似案例"
      
    - step: 6
      name: 生成诊断报告
      action: generate_report
  
  guardrails:
    - step1_failure: 终止执行，返回错误
    - step2_5_failure: 跳过继续，最终报告中标注缺失信息
    - any_step_timeout_30s: 超时终止
    - verifier_reject: 返回 planner 重新分析
    
  output:
    format: Markdown
    sections:
      - 基本信息
      - 根因分析
      - 证据链
      - 修复方案
      - 相似案例
```

### 3.4 Skill 与 SubAgent 的映射

```
/diagnose-by-orderid
├─ fault_category=EXTERNAL_API → ExternalApiSubAgent
├─ fault_category=INTERNAL_ERROR → InternalErrorSubAgent
└─ fault_category=DATABASE → DatabaseSubAgent

/diagnose-by-errorcode
└─ fault_category=EXTERNAL_API → ExternalApiSubAgent

/diagnose-by-stacktrace
└─ fault_category=INTERNAL_ERROR → InternalErrorSubAgent

/quick-check
└─ fault_category=DATABASE → DatabaseSubAgent
```

---

## 四、Harness 控制层设计

### 4.1 三层架构

```
┌──────────────────────────────────────────────────────────┐
│                    Harness 控制层                          │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  第一层：Prompt Engineering（提示词工程）                  │
│  ├─ 系统提示词模板化                                       │
│  ├─ 动态上下文注入（历史对话、诊断记录）                    │
│  ├─ Few-shot 示例管理（不同故障类型的标准案例）            │
│  └─ 输出格式约束（JSON Schema / Markdown 模板）           │
│                                                           │
│  第二层：Quality Gates（质量门禁）                         │
│  ├─ 输入门禁：校验请求合法性                              │
│  ├─ 执行门禁：监控工具调用质量                            │
│  ├─ 输出门禁：校验报告质量                                │
│  └─ 安全门禁：禁止编造、SQL注入防护                       │
│                                                           │
│  第三层：Interrupt（中断机制）                             │
│  ├─ 自动中断：连续失败、超时、置信度过低                  │
│  ├─ 人工确认：高危建议、敏感操作                          │
│  └─ 条件降级：部分失败时跳过继续                          │
│                                                           │
└──────────────────────────────────────────────────────────┘
```

---

### 4.2 Prompt Engineering（提示词工程）

#### 4.2.1 提示词文件结构

```
src/main/resources/prompts/
├── system/
│   ├── supervisor-system.md       # Supervisor Agent 提示词
│   ├── planner-system.md          # Planner Agent 提示词
│   ├── executor-external-api.md   # ExternalApiSubAgent 提示词
│   ├── executor-internal-error.md # InternalErrorSubAgent 提示词
│   ├── executor-database.md       # DatabaseSubAgent 提示词
│   └── verifier-system.md         # Verifier Agent 提示词
│
├── few-shot/
│   ├── external-api-case1.md      # 外部接口故障示例1
│   ├── internal-error-case1.md    # 内部错误示例1
│   └── database-case1.md          # 数据库问题示例1
│
├── templates/
│   └── diagnosis-report.md        # 报告模板
│
└── rules/
    ├── output-rules.md            # 输出格式规则
    └── safety-rules.md            # 安全规则
```

#### 4.2.2 动态上下文注入

```
每次 Prompt 构建时，动态注入：

1. 用户输入（orderId / traceId / errorDescription）
2. 历史对话上下文（Redis 中的最近 3 轮对话）
3. 当前诊断记录（diagnosis_record 的已有信息）
4. 相似案例（case_library 中的 Top 3 案例）
5. Few-shot 示例（根据 fault_category 选择）
```

---

### 4.3 Quality Gates（质量门禁）

#### 4.3.1 门禁清单

```
输入门禁（诊断前）：
├─ Gate 1: order_id / trace_id 格式校验
├─ Gate 2: 输入参数不能为空
├─ Gate 3: 5分钟内同一订单 → 返回缓存结果
├─ Gate 4: SQL 注入检测（queryOrder 工具）
└─ Gate 5: 敏感信息脱敏检查

执行门禁（诊断中）：
├─ Gate 6: 工具参数合法性校验
├─ Gate 7: 工具返回结果非空校验
├─ Gate 8: 工具调用超时检查（10 秒）
├─ Gate 9: 脱敏校验（返回内容中的手机号、身份证）
└─ Gate 10: 工具调用次数限制（同一工具最多 5 次）

输出门禁（诊断后）：
├─ Gate 11: 报告章节完整性（4 章节不全 → 不通过）
├─ Gate 12: 置信度阈值检查（< 60 → 标记"低置信度"）
├─ Gate 13: 数据真实性校验（引用的错误码是否真实存在于 Milvus）
├─ Gate 14: 禁止编造检测（报告中的数据 vs 工具返回数据对比）
└─ Gate 15: 报告长度检查（不能太短，"无法分析"之类的不通过）
```

#### 4.3.2 门禁实现结构

```
src/main/java/com/superbiz/agent/
├── harness/
│   ├── gate/
│   │   ├── GateResult.java           # 门禁结果
│   │   ├── InputGates.java           # 输入门禁
│   │   ├── ExecutionGates.java       # 执行门禁
│   │   ├── OutputGates.java          # 输出门禁
│   │   └── SecurityGates.java        # 安全门禁
│   │
│   ├── interrupt/
│   │   ├── InterruptDecision.java    # 中断决策
│   │   ├── InterruptService.java     # 中断服务
│   │   └── InterruptStrategy.java    # 中断策略
│   │
│   └── prompt/
│       ├── PromptTemplate.java       # Prompt 模板
│       ├── PromptBuilder.java        # Prompt 构建器
│       └── ContextInjector.java      # 上下文注入器
```

---

### 4.4 Interrupt（中断机制）

#### 4.4.1 中断分类

```
自动中断（无需人工）：
├─ 工具连续失败 3 次 → 终止，标记状态
├─ 工具调用超时 10 秒 → 终止，记录超时
├─ 全局执行超时 30 秒 → 终止，返回中间结果
├─ 置信度 < 60 → 终止，标记"需要人工审核"
└─ SQL 注入风险 → 紧急终止，记录安全事件

条件降级（继续执行）：
├─ 文档检索为空 → 跳过，标注"文档缺失"
├─ 案例推荐为空 → 跳过，标注"无相似案例"
├─ 链路追踪数据缺失 → 跳过，基于日志继续
└─ 日志查询返回空 → 跳过，提示用户补充信息

人工确认（弹窗等待）：
├─ 删除文档操作 → 二次确认
├─ 置信度 < 60 的报告 → 人工审核后发布
├─ 高危修复建议（如重启服务）→ 二次确认
└─ 重新索引操作 → 确认对话框
```

#### 4.4.2 中断处理流程

```
工具调用
    ↓
中断检查
    ↓
├─ 连续失败 3 次？ → 自动终止，返回部分结果 + 错误说明
├─ 超时？ → 自动终止，返回中间状态 + 耗时信息
├─ 置信度低？ → 发起人工确认（标记状态，等待审核）
├─ 高危操作？ → 弹窗确认
└─ 正常 → 继续执行
```

---

## 五、技术实现（基于 Spring AI Alibaba）

### 5.1 框架能力复用

```java
// 框架已提供，直接使用
✅ DashScopeChatModel        // 大模型调用
✅ DashScopeEmbeddingModel   // 向量化
✅ ReactAgent                // Agent 基类
✅ SupervisorAgent           // 多 Agent 调度
✅ @Tool 注解                // 工具注册
✅ ToolCallbackProvider      // 工具发现
```

### 5.2 Agent 实现方式

```java
// Supervisor Agent（框架提供）
SupervisorAgent supervisor = SupervisorAgent.builder()
    .name("diagnosis_supervisor")
    .description("负责调度 Planner / SubAgent / Verifier")
    .model(chatModel)
    .systemPrompt(supervisorPrompt)
    .subAgents(List.of(plannerAgent, verifierAgent, 
        externalApiSubAgent, internalErrorSubAgent, databaseSubAgent))
    .build();

// Planner Agent
ReactAgent planner = ReactAgent.builder()
    .name("planner_agent")
    .description("负责分析问题、制定策略、选择 SubAgent")
    .model(chatModel)
    .systemPrompt(plannerPrompt)
    .outputKey("planner_plan")
    .build();

// SubAgent 示例（ExternalApiSubAgent）
ReactAgent externalApiSubAgent = ReactAgent.builder()
    .name("external_api_sub_agent")
    .description("外部接口故障专家")
    .model(chatModel)
    .systemPrompt(externalApiPrompt)
    .methodTools(externalApiTools)  // 专属工具集
    .tools(new ToolCallback[]{searchDoc, queryLogs, queryTrace, queryOrder})
    .build();

// Verifier Agent
ReactAgent verifier = ReactAgent.builder()
    .name("verifier_agent")
    .description("负责验证诊断报告的准确性")
    .model(chatModel)
    .systemPrompt(verifierPrompt)
    .outputKey("verifier_result")
    .build();
```

### 5.3 Skill 实现方式

```java
// Skill 定义接口
public interface SkillDefinition {
    String getName();
    String getDescription();
    List<SkillStep> getWorkflow();
    List<GuardRule> getGuardrails();
    SkillOutput execute(SkillInput input);
}

// Skill 注册中心
@Component
public class SkillRegistry {
    private final Map<String, SkillDefinition> skills = new HashMap<>();
    
    public void register(SkillDefinition skill) {
        skills.put(skill.getName(), skill);
    }
    
    public SkillDefinition get(String name) {
        return skills.get(name);
    }
    
    public List<String> getByFaultType(String faultCategory) {
        // 根据故障类型推荐合适的 Skill
    }
}

// Skill 示例
@Component
public class DiagnoseByOrderIdSkill implements SkillDefinition {
    @Override
    public String getName() { return "diagnose-by-orderid"; }
    
    @Override
    public List<SkillStep> getWorkflow() {
        return Arrays.asList(
            new SkillStep(1, "查询订单", "queryOrder", FailStrategy.ABORT),
            new SkillStep(2, "查询链路", "queryTrace", FailStrategy.SKIP),
            new SkillStep(3, "查询日志", "queryLogs", FailStrategy.SKIP),
            new SkillStep(4, "检索文档", "searchDoc", FailStrategy.SKIP),
            new SkillStep(5, "推荐案例", "recommendCase", FailStrategy.SKIP),
            new SkillStep(6, "生成报告", null, FailStrategy.NONE)
        );
    }
    
    // ...
}
```

---

## 六、面试话术

### 6.1 Agent 架构

> "这个系统的核心是 5 个 Agent 协作：
> 
> - **Supervisor** 是总指挥，负责调度
> - **Planner** 是分诊台 + 军师，分析问题类型，制定策略，选择合适的 SubAgent
> - **3 个 SubAgent** 是专科医生，各有专长
> - **Verifier** 是质检员，验证诊断报告的准确性
> 
> 不是一个人干所有活，而是团队协作，
> 类比医院的会诊制度。"

### 6.2 Skill 体系

> "诊断流程太复杂，不能让 Agent 自由发挥。我设计了 Skill 体系：
> 
> 每个 Skill 固定了 6 个步骤，每步调用哪个工具、传什么参数、失败怎么处理，
> 都定义清楚了。
> 
> 不同故障类型走不同 Skill：
> - 外部接口故障走 /diagnose-by-orderid
> - 内部错误走 /diagnose-by-stacktrace
> 
> 就像医生看病的 SOP，流程标准化后，质量才能稳定。"

### 6.3 Harness 控制

> "Harness 是 Agent 的安全带，三层控制：
> 
> **Prompt Engineering**：不是写死一个 Prompt，而是模板化 + 动态注入。
> 不同 SubAgent 有专属 Prompt，不同阶段注入不同上下文。
> 
> **Quality Gates**：15 个门禁点覆盖输入→执行→输出全流程。
> 最关键的是输出门禁——报告必须通过事实核查才能发布。
> 
> **Interrupt**：分级中断策略。自动中断（连续失败、超时）、
> 条件降级（跳过非关键步骤）、人工确认（高危操作）。
> 
> 这三层保证 Agent 不会胡说八道，出了问题有据可查。"

---

## 七、MVP 版本总结

### 7.1 Agent 清单

| Agent | 角色 | 实现方式 |
|-------|------|---------|
| SupervisorAgent | 总指挥 | Spring AI Alibaba SupervisorAgent |
| PlannerAgent | 军师+分诊 | ReactAgent |
| ExternalApiSubAgent | 接口专家 | ReactAgent + 专属工具 |
| InternalErrorSubAgent | 代码专家 | ReactAgent + 专属工具 |
| DatabaseSubAgent | 数据库专家 | ReactAgent + 专属工具 |
| VerifierAgent | 质检员 | ReactAgent |

### 7.2 Skill 清单

| Skill | 适用场景 | 对应 SubAgent |
|-------|---------|---------------|
| /diagnose-by-orderid | 按订单号诊断 | 自动选择 |
| /diagnose-by-errorcode | 按错误码诊断 | ExternalApiSubAgent |
| /diagnose-by-stacktrace | 堆栈分析 | InternalErrorSubAgent |
| /quick-check | 快速检查 | DatabaseSubAgent |

### 7.3 Harness 清单

| 层 | 数量 | 说明 |
|----|------|------|
| Prompt 模板 | 6 个系统提示词 + 3 个 Few-shot | 每个 Agent 一个 |
| Quality Gates | 15 个门禁 | 输入5 + 执行5 + 输出5 |
| Interrupt | 4 自动 + 4 降级 + 3 人确 | 分级中断 |

---

## 八、与框架的关系

```
Spring AI Alibaba 提供：
✅ DashScope 大模型调用
✅ ReactAgent 基类
✅ SupervisorAgent 多 Agent 调度
✅ @Tool 注解工具注册
✅ 向量化（Embedding）

我们在此基础上增强：
🆕 SubAgent 模式（专科医生分工）
🆕 Verifier Agent（独立验证角色）
🆕 Skill 体系（标准化诊断流程）
🆕 Harness 三层控制（安全+质量）
🆕 混合 RAG 检索（提升准确率）

不是重复造轮子，是对框架的增强和工程化！
```

---

## 九、Skills 知识底座（渐进式披露）

### 9.1 设计理念

```
问题：
把全部 Skill 一次性加载给 Agent
→ Agent 信息过载，决策变慢，容易选错流程

解决方案：渐进式披露
→ 根据诊断进度，逐步释放需要的知识
→ 就像你不会给实习生看所有 SOP，
   而是根据他当前的任务，逐步放出需要的知识
```

### 9.2 三层知识结构

```
┌──────────────────────────────────────────────────────────┐
│          Skill 知识底座（三层渐进式）                      │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  L1：通用诊断 Skill（所有 Agent 始终可见）                 │
│  ┌────────────────────────────────────────────────────┐  │
│  │ /quick-check          快速检查（首个诊断步骤）       │  │
│  │ /safety-rules         安全规则（禁止编造、脱敏）     │  │
│  │ /output-format        输出格式要求（Markdown 模板）  │  │
│  └────────────────────────────────────────────────────┘  │
│                          ↓ Planner 分析 fault_category    │
│  L2：领域 Skill（按故障类别加载）                         │
│  ┌────────────────────────────────────────────────────┐  │
│  │ EXTERNAL_API → /diagnose-by-orderid                │  │
│  │              → /diagnose-by-errorcode               │  │
│  │ INTERNAL_ERROR→ /diagnose-by-stacktrace             │  │
│  │ DATABASE     → /diagnose-sql-analysis               │  │
│  │              → /diagnose-deadlock                    │  │
│  └────────────────────────────────────────────────────┘  │
│                  ↓ 执行中触发具体模式                     │
│  L3：专家 Skill（按识别到的模式触发）                     │
│  ┌────────────────────────────────────────────────────┐  │
│  │ NPE 模式触发    → /diagnose-npe-pattern             │  │
│  │ 死锁模式触发    → /diagnose-deadlock-pattern         │  │
│  │ 广东社保模式触发 → /diagnose-guangdong-social-sec    │  │
│  │ 签名失败模式触发 → /diagnose-signature-failure       │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
└──────────────────────────────────────────────────────────┘
```

### 9.3 加载逻辑

```
Planner 启动时：
  ✅ L1 始终加载（4 个通用 Skill）

Planner 分析 fault_category=EXTERNAL_API 时：
  ✅ 额外加载 L2 中 EXTERNAL_API 相关的 2 个 Skill

Executor 执行中发现 NPE 异常模式时：
  ✅ 触发加载 L3 中 /diagnose-npe-pattern
  ✅ 该 Skill 会指导如何分析堆栈、定位代码行

Executor 执行中发现广东社保 40003 错误时：
  ✅ 触发加载 L3 中 /diagnose-guangdong-social-sec
  ✅ 该 Skill 包含广东省社保接口的特有字段和常见错误
```

### 9.4 面试话术

> "Skill 不是一次性全给 Agent，而是渐进式披露。
> 
> L1 通用 Skill 始终可见，保证基础安全规则和输出规范。
> L2 领域 Skill 按故障类别按需加载，比如外部接口故障时
> 才加载接口文档对比相关的 Skill。
> L3 专家 Skill 是最精密的，只有 Agent 识别到特定模式时才触发，
> 比如检测到 NPE 模式，自动加载空指针分析专家 Skill。
> 
> 这样做的好处是：Agent 不会被信息淹没，
> 每个阶段只看到该阶段需要的知识，决策更精准。"

---

## 十、SubAgent 进程隔离（防止故障扩散）

### 10.1 设计理念

```
问题：
所有 SubAgent 在同一个 JVM 进程中
→ 一个 SubAgent OOM，所有诊断都挂了
→ 一个 SubAgent 死循环，整个系统卡死
→ CPU/内存竞争，互相影响

解决方案：每个 SubAgent 独立进程，K8s Pod 隔离
```

### 10.2 隔离架构

```
┌──────────────────────────────────────────────────────────┐
│              Kubernetes 集群                              │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Supervisor Pod（调度器）    replicas: 1          │   │
│  │  resources: 256Mi / 0.5 CPU                      │   │
│  └──────────────────────────────────────────────────┘   │
│                          ↓                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Planner Pod（规划器）       replicas: 1          │   │
│  │  resources: 256Mi / 0.5 CPU                      │   │
│  └──────────────────────────────────────────────────┘   │
│                          ↓                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  SubAgent 容器组（独立 Pod，独立扩缩）              │   │
│  │                                                   │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │   │
│  │  │External API │ │Internal Err │ │ Database   │ │   │
│  │  │SubAgent Pod │ │SubAgent Pod │ │SubAgent Pod│ │   │
│  │  ├─────────────┤ ├─────────────┤ ├────────────┤ │   │
│  │  │ replicas: 3 │ │ replicas: 2 │ │ replicas: 2│ │   │
│  │  │ 512Mi/1 CPU │ │ 512Mi/1 CPU │ │ 512Mi/1 CPU│ │   │
│  │  │ 故障不扩散  │ │ 故障不扩散  │ │ 故障不扩散 │ │   │
│  │  │ 独立扩缩    │ │ 独立扩缩    │ │ 独立扩缩   │ │   │
│  │  └─────────────┘ └─────────────┘ └────────────┘ │   │
│  │                                                   │   │
│  └──────────────────────────────────────────────────┘   │
│                          ↓                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Verifier Pod（验证器）       replicas: 1         │   │
│  │  resources: 256Mi / 1 CPU                        │   │
│  └──────────────────────────────────────────────────┘   │
│                                                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │  MCP Tool Server 容器组（独立服务）                │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
│  │  │ DB Svr  │ │Log Svr  │ │Doc Svr  │  ...       │   │
│  │  └─────────┘ └─────────┘ └─────────┘            │   │
│  └──────────────────────────────────────────────────┘   │
│                                                           │
└──────────────────────────────────────────────────────────┘
```

### 10.3 隔离级别

```
资源隔离：
├─ 每个 SubAgent 独立 CPU/Memory Request & Limit
├─ ExternalAPI SubAgent：流量高 → replicas=3, 1CPU
├─ InternalError SubAgent：流量低 → replicas=2, 0.5CPU
└─ 不会互相抢占资源

故障隔离：
├─ DatabaseSubAgent OOM → K8s 自动重启该 Pod
├─ 其他两个 SubAgent 不受影响
├─ Supervisor 检测到 Pod 重启 → 自动切换请求到新 Pod
└─ 故障半径：1 个 Pod（而非整个系统）

部署隔离：
├─ 更新 ExternalApiSubAgent → 滚动更新，不中断服务
├─ 不影响其他 SubAgent
└─ 金丝雀发布：10% 流量 → 验证 → 100%

安全隔离：
├─ DatabaseSubAgent 可以访问 DB 网络
├─ ExternalApiSubAgent 不能访问 DB 网络
└─ Network Policy 精细化控制
```

### 10.4 MVP 实现方式

```
Phase 1（当前）：
- 所有 SubAgent 在同一 JVM，但代码层面做了接口隔离
- 预留 K8s 部署配置模板

Phase 2（生产化）：
- 独立 Pod 部署
- Helm Chart 管理
- HPA 自动扩缩

面试时可以说：
"当前 MVP 版本在代码层面做了接口隔离，
生产环境可以通过 K8s Pod 实现进程级隔离。
部署配置已经预留好，切换只需修改 Helm values。"
```

### 10.5 面试话术

> "SubAgent 之间进程隔离，就像微服务架构。
> 
> 一个 DatabaseSubAgent 如果因为慢查询导致 OOM，
> K8s 会自动重启它，而 ExternalApiSubAgent 和
> InternalErrorSubAgent 完全不受影响。
> 
> 每个 SubAgent 可以独立扩缩：
> 外部接口故障高峰期，ExternalApiSubAgent 扩容到 5 个副本，
> 其他 SubAgent 保持 2 个副本。资源利用更精准。
> 
> 更新一个 SubAgent 也不需要重启整个系统，
> 滚动更新 + 金丝雀发布，0 停机。"

---

## 十一、回退路由（不让一次失败摧毁整个诊断）

### 11.1 设计理念

```
问题：
专项 SubAgent 失败 → 诊断终止 → 返回"系统错误"
用户得到的是一个无法使用的错误信息

解决方案：多级回退路由
→ 永远不会返回"系统错误"
→ 最差给用户"请人工介入" + 已有证据
→ 每级回退都有价值
```

### 11.2 四级回退路由

```
用户输入：orderId=202406150001

┌──────────────────────────────────────────────────────────┐
│              Planner 选择 SubAgent                        │
└──────┬───────────────────────────────────────────────────┘
       │ fault_category=EXTERNAL_API
       ↓
┌──────────────────────────────────────────────────────────┐
│  L0：首选路由                                             │
│  ExternalApiSubAgent（接口专家）                           │
│  预期：对比文档 → 检查参数 → 定位根因                      │
└──────┬───────────────────────────────────────────────────┘
       │ ❌ 执行失败（工具连续失败/超时）
       ↓
┌──────────────────────────────────────────────────────────┐
│  L1：第1级回退                                            │
│  InternalErrorSubAgent（换个角度）                         │
│  也许"外部接口故障"的表象下是内部空指针                     │
│  重新诊断：查日志 → 分析堆栈                               │
└──────┬───────────────────────────────────────────────────┘
       │ ❌ 仍然失败
       ↓
┌──────────────────────────────────────────────────────────┐
│  L2：第2级回退                                            │
│  GenericDiagnosisSubAgent（通用诊断）                      │
│  不做专项分析，基于已有证据给出推断性结论                    │
│  标注"低置信度"                                            │
└──────┬───────────────────────────────────────────────────┘
       │ ❌ 仍然失败
       ↓
┌──────────────────────────────────────────────────────────┐
│  L3：第3级回退                                            │
│  基于缓存的快速响应                                       │
│  查询相似订单的历史诊断结果                                 │
│  "订单 202406150001 的错误码 40003，类似订单 xxx 的根因是…" │
│  标注"缓存推断，置信度低"                                   │
└──────┬───────────────────────────────────────────────────┘
       │ ❌ 仍然失败
       ↓
┌──────────────────────────────────────────────────────────┐
│  L4：降级报告                                             │
│  返回：                                                    │
│  "无法自动诊断，请人工介入"                                 │
│  + 已收集的证据（订单信息、部分日志、已知错误码）            │
│  + 建议人工排查方向                                        │
│                                                           │
│  永不返回"系统错误"！                                     │
└──────────────────────────────────────────────────────────┘
```

### 11.3 回退决策规则

```
触发回退的条件：
├─ SubAgent 连续 3 次工具调用失败 → L1 回退
├─ SubAgent 执行超时 30 秒 → L1 回退
├─ Verifier 判定 REJECT → L1 回退
├─ L1 回退后仍然失败 → L2 回退
├─ L2 回退后仍然失败 → L3 回退
└─ L3 回退后仍然失败 → L4 降级

不触发回退的条件：
├─ 只是文档检索为空 → 跳过该步骤，继续执行
├─ 只是案例推荐为空 → 标注"无相似案例"，继续执行
└─ Verifier 判定 REVISE → Planner 修正，不换 SubAgent
```

### 11.4 面试话术

> "诊断系统最重要的不是'多准确'，而是'多可靠'。
> 
> 我设计了 4 级回退路由：
> 
> 第一级，换 SubAgent。外部接口专家不行，换内部错误专家试试，
> 也许故障表象是外部 API 错误，根因其实是内部空指针。
> 
> 第二级，换通用模式。不做专项分析，基于已有证据给推断结论。
> 
> 第三级，换历史经验。查相似订单的已有诊断结果。
> 
> 第四级，降级服务。返回'请人工介入'，但附带已收集的所有证据，
> 让运维人员不需要从零开始排查。
> 
> 核心原则：永不返回'系统错误'，每级回退都有价值输出。"

---

## 十二、进化引擎（从每次诊断中学习）

### 12.1 设计理念

```
问题：
系统只是"被使用"，不会"变聪明"
每次诊断都从零开始，历史经验只有案例推荐

解决方案：全自动进化引擎
→ 高频模式 → 自动创建 Skill
→ 低效 Prompt → 自动优化
→ 低质量案例 → 自动降权
→ 过时文档 → 自动提醒更新
```

### 12.2 四大进化模块

```
┌──────────────────────────────────────────────────────────┐
│                    进化引擎                                │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ 模块1：模式识别引擎                                  │  │
│  │                                                     │  │
│  │ 输入：过去 30 天的 diagnosis_record                  │  │
│  │ 规则：                                               │  │
│  │ ├─ 同一 error_code 出现 > 50 次 → 高优先级模式       │  │
│  │ ├─ 同一 fault_target 出现 > 30 次 → 热点接口         │  │
│  │ ├─ 新出现的 error_code 组合 → 新故障模式             │  │
│  │ └─ 聚类相似根因的案例 → 生成通用解决方案             │  │
│  │                                                     │  │
│  │ 输出：                                               │  │
│  │ ├─ 自动创建 L3 专家 Skill                            │  │
│  │ ├─ 自动归类新 fault_category                         │  │
│  │ └─ 自动生成 Few-shot 示例                            │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ 模块2：Prompt 自优化                                 │  │
│  │                                                     │  │
│  │ 输入：每个 Prompt 变体的诊断准确率                    │  │
│  │ 规则：                                               │  │
│  │ ├─ A/B 测试：10% 流量用 Prompt A，10% 用 Prompt B    │  │
│  │ ├─ 统计 7 天内的准确率差异                            │  │
│  │ ├─ 显著提升（>5%）→ 全量切换                         │  │
│  │ └─ 无显著差异 → 保留当前版本                          │  │
│  │                                                     │  │
│  │ 输出：                                               │  │
│  │ ├─ 自动切换到最优 Prompt                             │  │
│  │ ├─ 记录 Prompt 变更历史（可回退）                     │  │
│  │ └─ 生成优化报告                                      │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ 模块3：案例质量自动评估                               │  │
│  │                                                     │  │
│  │ 输入：case_library 的引用和反馈数据                   │  │
│  │ 规则：                                               │  │
│  │ ├─ reference_count 高 + 关联诊断 feedback=useful     │  │
│  │ │  → 提升权重（score +10）                           │  │
│  │ ├─ reference_count 高 + 关联诊断 feedback=not_useful │  │
│  │ │  → 降低权重（score -20），标记人工审核             │  │
│  │ ├─ 创建 > 90 天的案例无引用 → 降低权重（时间衰减）    │  │
│  │ └─ 创建 > 180 天的案例无引用 → 自动归档              │  │
│  │                                                     │  │
│  │ 输出：                                               │  │
│  │ ├─ 案例权重自动调整                                  │  │
│  │ ├─ 低质量案例自动归档                                │  │
│  │ └─ 高质量案例置顶                                    │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ 模块4：知识自动更新                                   │  │
│  │                                                     │  │
│  │ 规则：                                               │  │
│  │ ├─ 文档 30 天未更新 + 引用率下降 → 提醒更新           │  │
│  │ ├─ 新接口上线 + 文档缺失 → 提醒导入                   │  │
│  │ ├─ 错误码模式变更 → 提醒复查文档                      │  │
│  │ └─ 案例老化 → 自动归档，释放存储                      │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
└──────────────────────────────────────────────────────────┘
```

### 12.3 MVP 实现方式

```
Phase 1（当前）：
✅ 案例自动生成（diagnosis_record → case_library）
✅ reference_count 简单排序
✅ 用户 feedback 字段

Phase 2（进化）：
❌ 模式识别引擎（定时任务，每周执行）
❌ Prompt A/B 测试框架
❌ 案例自动升降权
❌ 文档过期检测

面试时可以说：
"当前 MVP 已实现案例自动生成和反馈收集，
为进化引擎储备了数据基础。
Phase 2 会增加模式识别和 Prompt 自优化，
这些是自动化运行的，不需要人工干预。"
```

### 12.4 面试话术

> "系统不只是'被使用'，而是'在进化'。每次诊断都是一次学习。
> 
> **模式识别**：如果同一个错误码出现了 50 次以上，
> 系统自动创建一个 L3 专家 Skill，包含处理这类问题的标准流程。
> 
> **Prompt 自优化**：A/B 测试不同 Prompt 变体，
> 自动统计哪个准确率更高，7 天后自动切换到最优版本。
> 不需要人工分析"哪个 Prompt 更好"。
> 
> **案例自评估**：引用率高 + 反馈好的案例自动提权排在前面，
> 长期无人引用的案例自动归档。质量越高越靠前，劣质案例自然淘汰。
> 
> **知识更新提醒**：文档 30 天没更新？引用率下降？
> 自动提醒运维复查。新接口上线没文档？自动提醒导入。
> 
> 最重要的是，这些都是自动化的，系统越运行越聪明。"

---

## 十三、MCP 协议化工具（标准化连接）

### 13.1 设计理念

```
问题：
工具写在 Java 代码里（@Tool 注解）
→ 工具和 Agent 紧耦合
→ 换工具需要改 Agent 代码
→ 新工具需要重新部署 Agent

解决方案：MCP 协议标准化
→ 工具作为独立 MCP Server 运行
→ Agent 通过 MCP Client 发现和调用工具
→ 类似 USB：换工具不需要改 Agent
```

### 13.2 MCP 架构

```
┌──────────────────────────────────────────────────────────┐
│              Agent 层（MCP Client）                        │
│  Supervisor / Planner / SubAgent / Verifier               │
│                                                           │
│  通过 MCP 协议发现和调用工具                                │
│  不关心工具的实现细节                                       │
└──────┬───────────────────────────────────────────────────┘
       │ MCP 协议（标准 JSON-RPC）
       ↓
┌──────────────────────────────────────────────────────────┐
│           MCP Tool Server 层（独立服务）                    │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Database MCP Server                                │  │
│  │ ├─ queryOrder：查询订单                             │  │
│  │ ├─ queryUser：查询用户                              │  │
│  │ ├─ queryConfig：查询配置                            │  │
│  │ └─ 安全：只读 + SQL注入防护 + 超时控制              │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Log MCP Server                                     │  │
│  │ ├─ queryLogsByTraceId：按链路查日志                 │  │
│  │ ├─ queryLogsByKeyword：按关键词查日志               │  │
│  │ └─ 后端可切换：ES / Loki / SLS                      │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Document MCP Server                                │  │
│  │ ├─ searchDoc：检索接口文档                          │  │
│  │ ├─ indexDoc：索引新文档                             │  │
│  │ └─ 后端：Milvus + api_document                      │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Trace MCP Server                                   │  │
│  │ ├─ queryTrace：查询调用链                           │  │
│  │ └─ 后端：Jaeger / SkyWalking（可切换）               │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Case MCP Server                                    │  │
│  │ ├─ recommendCase：推荐相似案例                      │  │
│  │ └─ 后端：MySQL + Milvus（混合检索）                  │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
└──────────────────────────────────────────────────────────┘
```

### 13.3 MCP 协议化的优势

```
优势1：工具可发现
├─ Agent 启动时自动扫描所有 MCP Server
├─ 通过 mcp.listTools() 获取所有可用工具
└─ 新工具上线 → Agent 自动发现，无需重启

优势2：工具可替换
├─ 换 ES 为 Loki → 只改 Log MCP Server 实现
├─ 换 Jaeger 为 SkyWalking → 只改 Trace MCP Server 实现
└─ Agent 代码完全不变

优势3：工具可组合
├─ 不同 SubAgent 使用不同的工具子集
├─ ExternalApiSubAgent：Document + Log + Trace Server
├─ DatabaseSubAgent：Database + Log + Trace Server
└─ 权限隔离：不同 SubAgent 只能调用授权的 Server

优势4：工具可独立部署
├─ Document MCP Server 流量大 → 独立扩容 5 个副本
├─ 不影响其他 Server
└─ 每个 Server 独立版本管理和灰度发布

优势5：跨语言支持
├─ Agent 用 Java（Spring AI Alibaba）
├─ Log MCP Server 可以用 Go（性能更好）
├─ Document MCP Server 可以用 Python（ML 生态好）
└─ MCP 协议统一 JSON-RPC，不限制语言
```

### 13.4 MVP 实现方式

```
Phase 1（当前）：
✅ @Tool 注解直接在 Java 代码中
✅ 工具接口抽象（预留 MCP 切换能力）
✅ Spring AI MCP Client 已集成（pom.xml 已有依赖）

Phase 2（生产化）：
✅ 每个 MCP Server 独立 Spring Boot 应用
✅ 独立 Docker 镜像
✅ K8s 独立部署和扩缩

面试时可以说：
"当前 MVP 用 @Tool 注解快速实现，
但工具接口层已经做了抽象。
生产化时每个 Server 独立部署，
Agent 通过 MCP 协议发现和调用。Agent 代码完全不变。"
```

### 13.5 面试话术

> "工具不是写死在 Agent 代码里的，而是通过 MCP 协议标准化暴露。
> 
> 就像 USB 接口：你换一个鼠标，不需要改装电脑。
> 我换 ES 为 Loki，只需要改 Log MCP Server 的实现，
> Agent 代码完全不动。
> 
> 每个 MCP Server 是独立的服务：
> - 可以独立扩缩（文档检索流量大，Document Server 扩到 5 个副本）
> - 可以独立部署（更新 Log Server 不需要重启 Agent）
> - 可以用不同语言写（Python 写文档解析，Go 写日志查询，Java 写 Agent）
> 
> 新工具上线也是即插即用：部署一个新的 MCP Server，
> Agent 通过协议自动发现，零代码变更。"

---

## 十四、生产级全景图

### 14.1 最终架构总览

```
                    ┌──────────────┐
                    │   用户输入    │
                    └──────┬───────┘
                           │
    ┌──────────────────────┴──────────────────────────────┐
    │                    K8s 集群                          │
    ├──────────────────────────────────────────────────────┤
    │                                                       │
    │  ┌─────────────────────────────────────────────────┐ │
    │  │         Supervisor Pod（调度者）                  │ │
    │  │         + 回退路由控制                            │ │
    │  └───────────────┬─────────────────────────────────┘ │
    │                  │                                    │
    │  ┌───────────────┴─────────────────────────────────┐ │
    │  │         Planner Pod（规划者 + 分诊）              │ │
    │  │         + Skill 渐进式加载                        │ │
    │  └───────────────┬─────────────────────────────────┘ │
    │                  │                                    │
    │  ┌───────────────┴─────────────────────────────────┐ │
    │  │     SubAgent 容器组（进程隔离，独立扩缩）          │ │
    │  │                                                  │ │
    │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐        │ │
    │  │  │External  │ │Internal  │ │Database  │        │ │
    │  │  │API Pod   │ │Error Pod │ │Pod       │        │ │
    │  │  │×3 reps   │ │×2 reps   │ │×2 reps   │        │ │
    │  │  └──────────┘ └──────────┘ └──────────┘        │ │
    │  │                                                  │ │
    │  │  ┌──────────────────────────────────┐          │ │
    │  │  │   GenericSubAgent（回退路由L2）    │          │ │
    │  │  └──────────────────────────────────┘          │ │
    │  └───────────────┬─────────────────────────────────┘ │
    │                  │                                    │
    │  ┌───────────────┴─────────────────────────────────┐ │
    │  │         Verifier Pod（验证者 + 质量门禁）         │ │
    │  └───────────────┬─────────────────────────────────┘ │
    │                  │                                    │
    │  ┌───────────────┴─────────────────────────────────┐ │
    │  │      MCP Tool Server 层（独立服务，独立扩缩）      │ │
    │  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐│ │
    │  │  │ DB   │ │ Log  │ │ Doc  │ │Trace │ │ Case ││ │
    │  │  │Server│ │Server│ │Server│ │Server│ │Server││ │
    │  │  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘│ │
    │  └──────────────────────────────────────────────────┘ │
    │                                                       │
    │  ┌──────────────────────────────────────────────────┐ │
    │  │              进化引擎（后台任务）                  │ │
    │  │  ├─ 模式识别（每周）                              │ │
    │  │  ├─ Prompt 自优化（AB 测试）                      │ │
    │  │  ├─ 案例质量评估（每天）                           │ │
    │  │  └─ 知识更新提醒（每周）                           │ │
    │  └──────────────────────────────────────────────────┘ │
    │                                                       │
    └──────────────────────────────────────────────────────┘
```

### 14.2 技术栈全景

```
应用框架：
├─ Spring Boot 3.2
├─ Spring AI Alibaba 1.1.0（Agent 框架）
└─ DashScope（大模型 + 向量化）

数据存储：
├─ MySQL 8.0+（元数据 + 业务数据）
├─ Redis 6.0+（会话 + 缓存）
└─ Milvus 2.6+（向量检索）

基础设施：
├─ Kubernetes（容器编排 + 进程隔离）
├─ Helm（部署管理）
└─ Prometheus + Grafana（监控）

协议标准：
├─ MCP（工具协议层）
└─ REST + SSE（API 层）
```

---

## 十五、更新面试话术

### 15.1 完整架构描述（2 分钟版）

> "这是一个**生产级的、可持续进化的线上诊断 Agent 系统**，包含 6 层设计：
> 
> **第一层，Agent 协作**：5 个 Agent——Supervisor 调度、Planner 分诊、
> 3 个 SubAgent 专科诊断、Verifier 验证。SubAgent 进程隔离，
> 一个挂掉不影响其他的，K8s 自动拉起。
> 
> **第二层，Skill 知识底座**：渐进式披露，三层知识结构。
> 通用 Skill 始终可见，领域 Skill 按故障类别加载，
> 专家 Skill 按识别到的模式触发。Agent 不会被信息淹没。
> 
> **第三层，回退路由**：4 级回退——专项 SubAgent → 通用 SubAgent →
> 缓存历史 → 降级报告。永不返回'系统错误'，最差给用户'请人工介入'加证据。
> 
> **第四层，Harness 安全带**：Prompt Engineering + 15 个 Quality Gates +
> 分级中断。保证 Agent 不会胡说八道。
> 
> **第五层，MCP 协议化工具**：工具作为独立服务运行，像 USB 一样即插即用。
> 换工具不改 Agent 代码，新工具上线自动发现。
> 
> **第六层，进化引擎**：模式识别 → 自动创建 Skill，Prompt A/B 测试自动选优，
> 案例自动升降权。系统越运行越聪明。"
```

### 15.2 面试追问应对

| 追问 | 回答要点 |
|------|---------|
| "Agent 怎么保证不编造数据？" | Verifier 事实核查 + Output Gate 数据真实性校验 |
| "一个 SubAgent 挂了怎么办？" | 进程隔离 + K8s 自动重启 + 回退路由切换到其他 SubAgent |
| "工具换了怎么改代码？" | MCP 协议化，换工具只改 Server 实现，Agent 代码不动 |
| "系统怎么越来越准？" | 进化引擎：模式识别创建 Skill + Prompt A/B 测试自动选优 |
| "准确率能提升多少？" | 混合 RAG 62%→85%，闭环优化每月 +1%，目标 90% |
| "和直接用 ChatGPT 有什么区别？" | 专业诊断 Skill + 领域文档 RAG + 案例库 + 质量门禁 + 进化引擎 |

---

## 十六、MVP vs 生产级对比

| 维度 | MVP（Phase 1） | 生产级（Phase 2-4） |
|------|---------------|-------------------|
| Agent | 5 Agent 同一 JVM | 独立 Pod，进程隔离 |
| Skill | 4 个固定 Skill | 3 层渐进式，50+ Skill |
| 回退 | 3 次失败终止 | 4 级回退路由 |
| 工具 | @Tool 注解 | MCP 独立 Server |
| 进化 | 案例自动生成 | 模式识别 + Prompt 自优化 + 案例自评估 |
| 部署 | 单实例 | K8s 集群 + HPA 扩缩 |
| 准确率 | 85%（目标） | 90%+（持续进化） |

---

## 十七、面试核心金句

```
"不是一个人干所有活，而是 5 个 Agent 团队协作。"

"Skill 不是一次性全给，而是渐进式披露，Agent 不被信息淹没。"

"SubAgent 进程隔离，一个挂了不影响其他的，就像微服务。"

"4 级回退路由，永不返回'系统错误'，最差给'人工介入'加证据。"

"Harness 是安全带，15 个门禁保证 Agent 不胡说八道。"

"MCP 协议化就像 USB，换工具不需要改 Agent。"

"进化引擎让系统越运行越聪明，不只是被使用，而是在进化。"

"不是重复造轮子，是对 Spring AI Alibaba 框架的增强和工程化。"
```