1520 lines
70 KiB
Markdown
1520 lines
70 KiB
Markdown
# 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 框架的增强和工程化。"
|
||
```
|