docs: 重构文档结构，分离学习笔记和 MVP 架构设计
**变更概述：** - 将 MVP 架构设计文档独立到项目根目录 `mvp/` - 整理 `docs/` 为纯学习和分析文档目录 - 按类型分类：learning（学习）、analysis（分析）、reports（报告）、guides（指南） **目录结构：** ``` mvp/ # MVP 架构设计（独立） ├── README.md # 数据库设计总览 ├── architecture/ # 架构文档 │ ├── agent-architecture-mvp.md │ ├── implementation-plan.md │ └── ... └── tables/ # 数据表设计 docs/ # 学习和分析文档 ├── learning/ # 学习笔记（00-08 编号） ├── analysis/ # 分析笔记 + 重构计划 ├── reports/ # 临时报告 └── guides/ # 指南文档 ``` **详细变更：** - docs/README.md → mvp/README.md（数据库设计入口） - docs/architecture/ → mvp/architecture/（架构设计） - docs/tables/ → mvp/tables/（数据表设计） - docs/学习笔记-*.md → docs/learning/07-*.md, 08-*.md - docs/项目学习路径.md → docs/learning/00-*.md - docs/功能分析报告.md → docs/analysis/ - docs/修复报告-*.md → docs/reports/ - docs/日志配置*.md → docs/guides/ 或 docs/reports/ - docs/design/ → docs/analysis/（问题分析和重构计划）
This commit is contained in:
zhuyongxin
@@ -0,0 +1,529 @@
|
||||
# Agent 架构设计（MVP 版）
|
||||
|
||||
## 一、MVP 全景
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 意图识别（Intent Recognition） 🆕 │
|
||||
│ "用户想干什么？" │
|
||||
│ │
|
||||
│ 诊断意图 → 路由到诊断 Skill │
|
||||
│ 文档意图 → 路由到文档问答 │
|
||||
│ 案例意图 → 路由到案例查询 │
|
||||
│ 闲聊 → 快速响应（不启动 Agent） │
|
||||
│ 模糊/无关 → 提示用户，直接中断 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
│ 诊断意图
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Supervisor Agent（调度者） │
|
||||
│ "谁来干？什么时候停？" │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Planner Agent（规划者） │
|
||||
│ 分析问题 → 制定策略 → 生成报告 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Executor Agent（执行者） │
|
||||
│ 调用工具收集证据 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Verifier Agent（验证者） │
|
||||
│ 事实核查 → 判定通过/修正/驳回 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
诊断报告输出
|
||||
↓
|
||||
用户反馈（有用/无用）
|
||||
↓
|
||||
案例沉淀 + BadCase 优化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、意图识别（入口层）🆕
|
||||
|
||||
### 2.1 设计理念
|
||||
|
||||
```
|
||||
定位：独立模块，不嵌入任何单一 Agent
|
||||
|
||||
分层策略（不是二选一，而是组合）：
|
||||
|
||||
L0: 正则规则 —— 0 成本，毫秒级 ✅ MVP
|
||||
├─ 处理 80%+ 的结构化查询
|
||||
├─ 正则匹配订单号/traceId/错误码格式
|
||||
└─ 关键词匹配（"报错"/"异常"/"失败"）
|
||||
|
||||
L1: 小模型 Agent —— 低成本，百毫秒级 ✅ MVP
|
||||
├─ L0 未命中时触发
|
||||
├─ 处理灵活的模糊表达（"系统有点慢"、"怎么查不到了"）
|
||||
├─ 不启动全链路 Agent，只做意图分类
|
||||
└─ 判断为诊断意图 → 路由到诊断 Skill
|
||||
|
||||
L2: 兜底策略 —— 极少使用
|
||||
├─ L0+L1 都无法判断 → 意图不明 → 中断
|
||||
└─ Phase 2 增强
|
||||
```
|
||||
|
||||
### 2.2 意图分类与路由
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────┐
|
||||
│ 意图 │ 说明 │ 路由 │
|
||||
├────────────────────────────────────────────────────┤
|
||||
│ 诊断意图 │ 包含结构化标识或错误描述 │ → 诊断Skill│
|
||||
│ 文档问答 │ "XX接口的参数有哪些" │ → 直接RAG │
|
||||
│ 案例查询 │ "之前有类似的问题吗" │ → 案例检索 │
|
||||
│ 闲聊 │ "你好"/"谢谢" │ → 快速响应 │
|
||||
│ 意图不明 │ 无法识别 │ → 中断+提示 │
|
||||
└────────────────────────────────────────────────────┘
|
||||
|
||||
关键原则：
|
||||
- 只有诊断意图才启动 Agent 全链路
|
||||
- 非诊断意图走轻量路径或直接中断
|
||||
```
|
||||
|
||||
### 2.3 L0：正则规则（MVP，处理 80%）
|
||||
|
||||
```
|
||||
为什么先做 L0？
|
||||
→ 0 成本（不调 LLM），毫秒级响应
|
||||
→ 结构化查询占比最大（订单号、traceId、错误码、关键词）
|
||||
→ L0 命中直接路由，不需要走后续逻辑
|
||||
|
||||
规则配置（可扩展）：
|
||||
┌────────────────────────────────────────────────┐
|
||||
│ 规则 │ 意图 │ 方式 │
|
||||
├────────────────────────────────────────────────┤
|
||||
│ 匹配 \d{12,} │ 诊断 │ 正则 │
|
||||
│ 匹配 trace[-_]?\w{8,} │ 诊断 │ 正则 │
|
||||
│ 包含"报错‖失败‖异常‖挂了‖超时" │ 诊断 │ 关键词│
|
||||
│ 包含"文档‖接口‖参数‖字段‖API" │ 文档 │ 关键词│
|
||||
│ 包含"案例‖之前‖类似‖历史" │ 案例 │ 关键词│
|
||||
│ 长度 <= 5 字符 │ 闲聊 │ 规则 │
|
||||
└────────────────────────────────────────────────┘
|
||||
|
||||
命中 → 直接路由，不调 L1
|
||||
未命中 → 进入 L1
|
||||
```
|
||||
|
||||
### 2.4 L1：小模型 Agent（MVP，处理剩余 20%）
|
||||
|
||||
```
|
||||
为什么用小模型 Agent 而非嵌入到 Supervisor？
|
||||
→ 意图识别是独立职责，不应耦合到任何业务 Agent
|
||||
→ 轻量 Agent：单一职责，只分类不执行
|
||||
→ 成本低（~50 token），延迟低（~200ms）
|
||||
|
||||
何时触发：L0 规则未命中
|
||||
|
||||
System Prompt:
|
||||
"你是意图分类器，判断用户想做什么。
|
||||
只返回一个词：[诊断 / 文档查询 / 案例查询 / 闲聊 / 意图不明]
|
||||
|
||||
诊断：用户描述了故障、报错、异常
|
||||
文档查询：用户询问接口文档、字段含义
|
||||
案例查询：用户询问历史案例、类似问题
|
||||
闲聊：简单的问候、感谢
|
||||
意图不明：无法判断用户意图"
|
||||
|
||||
输入：用户原始输入
|
||||
输出：意图类型 + 置信度
|
||||
```
|
||||
|
||||
### 2.5 L2：兜底策略
|
||||
|
||||
```
|
||||
L0+L1 都无法判断 → L2 兜底
|
||||
|
||||
中断规则：
|
||||
├─ 意图不明 → 提示用户 + 中断
|
||||
│ "无法判断您的意图，请提供订单号或错误码"
|
||||
├─ 闲聊 → 快速响应 + 中断
|
||||
│ "我是故障诊断助手，请描述您遇到的问题"
|
||||
└─ 不启动 Agent，直接返回
|
||||
|
||||
路由规则：
|
||||
├─ 诊断意图 → 启动 Supervisor + 4 Agent 全链路
|
||||
├─ 文档意图 → 不启动 Agent，直接 RAG 检索
|
||||
└─ 案例意图 → 不启动 Agent，直接查询 case_library
|
||||
```
|
||||
|
||||
### 2.5 架构位置
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 意图识别模块（独立） │
|
||||
│ │
|
||||
│ L1: 小模型 Agent ─→ 诊断意图？ │
|
||||
│ │ 文档意图？ │
|
||||
│ │ 案例意图？ │
|
||||
│ │ 闲聊？ │
|
||||
│ ↓ │
|
||||
│ L2: 兜底 ─────────→ 意图不明 → 中断 │
|
||||
│ 闲聊 → 快速响应 │
|
||||
└───────────────┬──────────────────────────┘
|
||||
│ 诊断意图
|
||||
↓
|
||||
Supervisor → Planner → Executor → Verifier
|
||||
```
|
||||
|
||||
### 2.6 MVP vs Phase 2
|
||||
|
||||
```
|
||||
MVP L0（正则）+ L1（小模型Agent） 覆盖 95%+ 场景
|
||||
Phase 2 L2（兜底增强） 细化中断提示，支持多轮澄清
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、4 个 Agent 设计
|
||||
|
||||
### 2.1 Supervisor Agent（调度者）
|
||||
|
||||
**职责**：总指挥，协调工作流
|
||||
|
||||
```
|
||||
调度规则：
|
||||
├─ 接收任务 → 发给 Planner 分析
|
||||
├─ Planner 完成 → 发给 Executor 执行
|
||||
├─ Executor 完成 → 发给 Verifier 校验
|
||||
└─ Verifier PASS → 输出报告 / REJECT → 返回 Planner 重新规划
|
||||
|
||||
不做：
|
||||
- 不直接调用工具
|
||||
- 不直接生成报告
|
||||
```
|
||||
|
||||
### 2.2 Planner Agent（规划者 + 分诊）
|
||||
|
||||
**职责**：分析问题、制定策略、生成报告草稿
|
||||
|
||||
```
|
||||
分析规则：
|
||||
├─ 有 errorCode + 接口 URL → EXTERNAL_API（外部接口故障）
|
||||
├─ 有堆栈信息 → INTERNAL_ERROR（系统内部错误）
|
||||
├─ 有数据库错误码（如 1213）→ DATABASE（数据库问题）
|
||||
└─ 其他 → 通用排查
|
||||
|
||||
规划流程：
|
||||
1. 确定 fault_category
|
||||
2. 制定排查步骤（每步：工具名 + 参数 + 预期）
|
||||
3. 生成决策：EXECUTE（继续执行）| FINISH（生成报告）
|
||||
|
||||
Replanner 职责：
|
||||
├─ Executor 每次返回结果后 → 评估证据是否充分
|
||||
├─ 需要补充？→ 调整步骤，继续执行
|
||||
├─ 证据齐全？→ FINISH，生成报告草稿
|
||||
└─ 连续 3 次失败？→ 降级
|
||||
|
||||
禁止：
|
||||
- 编造数据
|
||||
- 引用未经工具返回的内容
|
||||
```
|
||||
|
||||
### 2.3 Executor Agent（执行者）
|
||||
|
||||
**职责**：调用工具收集证据
|
||||
|
||||
```
|
||||
工具清单：
|
||||
├─ queryOrder：查询订单/业务数据（MySQL 只读）
|
||||
├─ searchDoc：检索接口文档（混合检索 Milvus + MySQL）
|
||||
├─ recommendCase：推荐相似案例（精确匹配 + 语义检索）
|
||||
└─ getCurrentTime：获取当前时间
|
||||
|
||||
执行规则：
|
||||
├─ 每次只执行 Planner 指定的一个步骤
|
||||
├─ 返回结构化的执行结果
|
||||
├─ 失败时返回错误详情（便于 Planner 调整）
|
||||
└─ 禁止编造结果
|
||||
|
||||
扩展预留：
|
||||
// 代码中 Executor 是接口，后续可扩展为 SubAgent
|
||||
public interface Executor {
|
||||
ExecutionResult execute(Step step);
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Verifier Agent（验证者）
|
||||
|
||||
**职责**：验证诊断报告，防止编造
|
||||
|
||||
```
|
||||
验证流程：
|
||||
|
||||
1️⃣ 事实核查（最重要）
|
||||
├─ 报告中的错误码 → 在 tool_calls 中存在？
|
||||
├─ 根因结论 → 有日志/文档证据支撑？
|
||||
├─ 修复方案 → 引用了文档或案例？
|
||||
└─ 发现编造数据 → 直接 REJECT
|
||||
|
||||
2️⃣ 完整性检查
|
||||
├─ 根因分析章节不能为空
|
||||
├─ 证据链章节不能为空
|
||||
└─ 修复方案章节不能为空
|
||||
|
||||
判决结果：
|
||||
├─ PASS：报告成立，直接输出
|
||||
├─ REVISE：小问题可修正，返回 Planner 微调
|
||||
└─ REJECT：编造数据或严重错误，返回 Planner 重新分析
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、RAG 两层加载策略
|
||||
|
||||
### 4.1 设计理念
|
||||
|
||||
```
|
||||
问题：
|
||||
❌ 全前置：启动时把所有文档塞给 Agent → 信息过载，推理变慢
|
||||
❌ 纯被动：等到需要才查 → Planner 没有全局视野，可能跑偏
|
||||
❌ 固定步骤：每次都调 → 内部错误查接口文档浪费
|
||||
|
||||
正确做法：两层互补
|
||||
|
||||
L1 预加载（Planner 启动时）
|
||||
→ 通用领域知识：系统架构、通用错误码、业务流程
|
||||
→ 给 Planner 全局视野，避免方向性错误
|
||||
|
||||
L2 按需加载（Executor 执行中）
|
||||
→ 具体接口文档：字段定义、错误码含义、调用规范
|
||||
→ 给 Executor 精准证据，定位具体问题
|
||||
```
|
||||
|
||||
### 4.2 两层对比
|
||||
|
||||
| | L1 预加载 | L2 按需加载 |
|
||||
|------|---------|-----------|
|
||||
| 触发时机 | 意图识别后，Planner 启动前 | Executor 拿到具体信息后 |
|
||||
| 内容 | 通用知识（架构、流程、高频错误码） | 具体接口文档（字段、错误码含义） |
|
||||
| 目的 | 让 Planner 有全局视野 | 让 Executor 有精准证据 |
|
||||
| 成本 | 固定，每次诊断 1 次 | 按需，最多 2-3 次 |
|
||||
| 谁负责 | Supervisor 注入 | Executor 自主调用 |
|
||||
|
||||
### 4.3 实现方式
|
||||
|
||||
```
|
||||
L1 预加载：
|
||||
Supervisor 在启动 Planner 前：
|
||||
searchDoc(keyword="系统架构 通用错误码 业务流程")
|
||||
→ 注入到 Planner 的 System Prompt 中
|
||||
→ Planner 拥有"领域背景知识"
|
||||
|
||||
L2 按需加载：
|
||||
Executor 执行 Step 2 时：
|
||||
拿到 errorCode=40003, faultSource="广东"
|
||||
→ 自主调用 searchDoc(errorCode="40003", faultSource="广东")
|
||||
→ 获取该接口的具体字段定义和错误码说明
|
||||
→ 作为证据写入诊断报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、Skill 设计（1 个）
|
||||
|
||||
### /diagnose-by-orderid（按订单号诊断）
|
||||
|
||||
```
|
||||
输入：orderId
|
||||
|
||||
工作流（6 步）：
|
||||
|
||||
Step 1: 查询订单信息
|
||||
工具：queryOrder
|
||||
失败：ABORT（订单不存在则终止）
|
||||
|
||||
Step 2: 检索接口文档
|
||||
工具：searchDoc
|
||||
参数：errorCode + faultSource
|
||||
失败：SKIP（标注"文档缺失"）
|
||||
|
||||
Step 3: 查询日志
|
||||
工具：queryLogs（Mock）
|
||||
参数：traceId
|
||||
失败：SKIP（标注"日志缺失"）
|
||||
|
||||
Step 4: 检索相似案例
|
||||
工具：recommendCase
|
||||
参数：errorCode + faultCategory
|
||||
失败：SKIP（标注"无相似案例"）
|
||||
|
||||
Step 5: 生成诊断报告
|
||||
汇总所有证据，按模板生成报告
|
||||
|
||||
Step 6: Verifier 验证
|
||||
事实核查 → 判决
|
||||
|
||||
门禁规则：
|
||||
├─ Step 1 失败 → 终止，返回"订单不存在"
|
||||
├─ Step 2-4 失败 → 跳过，标注缺失信息
|
||||
├─ 任意步骤超时 30s → 终止
|
||||
└─ Verifier REJECT → 返回 Planner 重新规划
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、Harness 控制层（精简版）
|
||||
|
||||
### 4.1 5 个 Quality Gates
|
||||
|
||||
```
|
||||
输入门禁（2 个）：
|
||||
├─ Gate 1: 输入参数非空校验
|
||||
└─ Gate 2: 5 分钟内同一订单 → 返回缓存
|
||||
|
||||
执行门禁（1 个）：
|
||||
└─ Gate 3: 工具调用超时（10 秒）
|
||||
|
||||
输出门禁（2 个）：
|
||||
├─ Gate 4: 报告章节完整性（3 章节不全 → 不通过）
|
||||
└─ Gate 5: 置信度阈值（< 60 → 标记"低置信度"）
|
||||
```
|
||||
|
||||
### 4.2 中断规则
|
||||
|
||||
```
|
||||
自动中断：
|
||||
├─ 工具连续失败 3 次 → 终止，降级输出
|
||||
└─ 全局超时 30 秒 → 终止
|
||||
|
||||
条件降级：
|
||||
├─ 文档检索为空 → 跳过继续
|
||||
├─ 案例推荐为空 → 跳过继续
|
||||
└─ 日志查询失败 → 跳过继续
|
||||
|
||||
降级输出：
|
||||
"无法自动诊断，请人工介入"
|
||||
+ 已收集的证据（订单信息 + 部分日志 + 已知错误码）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、技术实现
|
||||
|
||||
### 5.1 基于 Spring AI Alibaba
|
||||
|
||||
```java
|
||||
// Supervisor - 框架提供
|
||||
SupervisorAgent supervisor = SupervisorAgent.builder()
|
||||
.name("diagnosis_supervisor")
|
||||
.model(chatModel)
|
||||
.subAgents(List.of(planner, executor, verifier))
|
||||
.build();
|
||||
|
||||
// Planner
|
||||
ReactAgent planner = ReactAgent.builder()
|
||||
.name("planner_agent")
|
||||
.model(chatModel)
|
||||
.systemPrompt(plannerPrompt)
|
||||
.outputKey("planner_plan")
|
||||
.build();
|
||||
|
||||
// Executor（代码中预留 SubAgent 扩展接口）
|
||||
ReactAgent executor = ReactAgent.builder()
|
||||
.name("executor_agent")
|
||||
.model(chatModel)
|
||||
.systemPrompt(executorPrompt)
|
||||
.methodTools(diagnosisTools)
|
||||
.tools(new ToolCallback[]{queryOrder, searchDoc, recommendCase, getCurrentTime})
|
||||
.build();
|
||||
|
||||
// Verifier
|
||||
ReactAgent verifier = ReactAgent.builder()
|
||||
.name("verifier_agent")
|
||||
.model(chatModel)
|
||||
.systemPrompt(verifierPrompt)
|
||||
.outputKey("verifier_result")
|
||||
.build();
|
||||
```
|
||||
|
||||
### 5.2 工具注册
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class DiagnosisTools {
|
||||
|
||||
@Tool(description = "查询订单/业务数据（只读）")
|
||||
public OrderInfo queryOrder(@ToolParam(description = "订单号") String orderId) {
|
||||
// MySQL 只读 + SQL 注入防护
|
||||
}
|
||||
|
||||
@Tool(description = "检索接口文档")
|
||||
public List<DocChunk> searchDoc(
|
||||
@ToolParam(description = "错误码") String errorCode,
|
||||
@ToolParam(description = "省份/服务名") String faultSource
|
||||
) {
|
||||
// 混合检索：精确匹配 + 向量检索
|
||||
}
|
||||
|
||||
@Tool(description = "推荐相似历史案例")
|
||||
public List<CaseResult> recommendCase(
|
||||
@ToolParam(description = "错误码") String errorCode,
|
||||
@ToolParam(description = "故障类别") String faultCategory
|
||||
) {
|
||||
// 精确匹配 MySQL + 语义检索 Milvus
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、闭环机制
|
||||
|
||||
```
|
||||
诊断报告输出
|
||||
↓
|
||||
用户反馈（useful / not_useful）
|
||||
↓
|
||||
├─ useful → 自动生成 case_library
|
||||
└─ not_useful → 记录 BadCase
|
||||
↓
|
||||
每周 BadCase 分析
|
||||
↓
|
||||
Prompt / Skill 优化
|
||||
↓
|
||||
准确率验证（测试集重跑）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、MVP vs 扩展方向
|
||||
|
||||
| 维度 | MVP | 扩展方向 |
|
||||
|------|-----|---------|
|
||||
| Agent | 4 个 Agent | SubAgent 模式（专科医生） |
|
||||
| Skill | 1 个 | 渐进式披露（3 层知识） |
|
||||
| 工具 | @Tool 注解 | MCP 独立 Server |
|
||||
| 回退 | 2 级（失败→降级） | 4 级路由 |
|
||||
| Gates | 5 个 | 15 个全流程门禁 |
|
||||
| 隔离 | 单 JVM | K8s Pod 进程隔离 |
|
||||
| 进化 | 案例自动生成 | 模式识别 + Prompt 自优化 |
|
||||
|
||||
---
|
||||
|
||||
## 十、面试话术（精简版）
|
||||
|
||||
> "我用 Spring AI Alibaba 实现了一个故障诊断 Agent 系统。
|
||||
>
|
||||
> 入口层是**意图识别**：先判断用户想干什么——诊断故障、查文档、查案例还是闲聊。
|
||||
> 非诊断意图直接走轻量路径，只有诊断意图才启动 Agent 全链路，节省资源。
|
||||
>
|
||||
> 4 Agent 协作：Supervisor 调度、Planner 制定策略、
|
||||
> Executor 调用工具收集证据、Verifier 验证报告防止编造。
|
||||
>
|
||||
> 诊断流程封装成了 Skill，标准化 6 个步骤和异常处理。
|
||||
> Harness 层 5 个门禁保证质量——最关键的是输出门禁，
|
||||
> Verifier 会对比报告数据和工具返回数据，发现编造就驳回。
|
||||
>
|
||||
> 闭环机制：用户反馈 → BadCase 分析 → Prompt 优化。
|
||||
> 案例自动沉淀，系统越用越智能。"
|
||||
Reference in New Issue
Block a user