15-AI与智能体

用户请求 → [感知] 理解意图
         → [思考] 规划步骤、选择工具
         → [行动] 调用工具 API
         → [观察] 获取工具执行结果
         → [思考] 判断是否完成/需要继续
         → 循环直至任务完成

// 伪代码：使用 Agent 框架的典型方式
Agent agent = Agent.builder()
    .model(new ChatModel("gpt-4o"))
    .addTool(new SearchTool())
    .addTool(new DatabaseQueryTool())
    .addTool(new FileReadTool())
    .memory(new InMemorySession())
    .build();

String result = agent.run("帮我查询订单12345的状态，如果已发货就通知用户");
System.out.println(result);

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  1. 用户请求  │────→│  2. Agent    │────→│  3. 大模型   │
└─────────────┘     │   组装 Prompt │     │   推理决策   │
                    └──────────────┘     └──────┬──────┘
                                                │
                                       ┌────────▼────────┐
                                       │ 4. 解析响应      │
                                       │    文本/工具调用  │
                                       └────────┬────────┘
                                                │
                              ┌─────────────────┼─────────────────┐
                              ▼                                   ▼
                    ┌─────────────┐                     ┌─────────────┐
                    │ 5a. 直接回复 │                     │ 5b. 执行工具 │
                    └─────────────┘                     └──────┬──────┘
                                                               │
                                                     ┌─────────▼─────────┐
                                                     │ 6. 结果反馈给模型   │
                                                     │     进入下一轮循环   │
                                                     └───────────────────┘

{
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "search_order",
      "arguments": "{\"order_id\": \"12345\"}"
    }
  }]
}

// 伪代码：模拟 Agent-LLM 交互流程
while (!agent.isTaskComplete()) {
    // Step 1: 组装消息
    List<Message> messages = agent.buildMessages(userInput, history, tools);

    // Step 2: 调用大模型
    LLMResponse response = llm.chat(messages);

    // Step 3: 解析响应
    if (response.hasToolCalls()) {
        // Step 4: 执行工具
        ToolResult result = agent.executeTool(response.getToolCalls());
        // Step 5: 反馈结果
        agent.addMessage(new ToolMessage(result));
    } else {
        // Step 6: 直接回复用户
        agent.finalize(response.getText());
    }
}

用户："帮我查一下订单12345现在到哪了"
单纯大模型：（训练数据中没有该订单）→ 可能编造答案
引入工具：调用订单查询API → 返回真实物流信息 → 可信回答

1. 开发者注册工具 → 定义工具名称、参数、描述
2. Agent 将工具定义以 JSON Schema 格式注入 System Prompt
3. 大模型根据用户请求判断是否需要调用工具
4. 若需要，输出 Function Call 格式的响应
5. Agent 解析响应、执行对应工具
6. 将工具结果（Tool Message）反馈给大模型
7. 大模型基于真实结果继续推理或直接回答

// 伪代码：注册并使用工具
// 1. 定义工具
Tool orderQueryTool = Tool.builder()
    .name("query_order")
    .description("根据订单号查询订单状态和物流信息")
    .parameter("order_id", "string", "订单编号")
    .handler(params -> orderService.queryOrder(params.get("order_id")))
    .build();

// 2. 注册到 Agent
agent.registerTool(orderQueryTool);

// 3. 大模型自动根据需要调用
// 用户："查一下订单ORD-2024-001的状态"
// 大模型输出：function_call -> query_order({order_id: "ORD-2024-001"})
// Agent 执行工具，将结果返回给大模型

大模型推理 → 判断需要什么能力 → 输出 Function Call
    → Agent 解析 → 执行对应工具 → 返回 Tool Result
    → 大模型基于结果继续推理

// Function Call 响应示例
{
  "role": "assistant",
  "content": null,
  "function_call": {
    "name": "get_weather",
    "arguments": "{\"city\": \"北京\", \"date\": \"2024-06-01\"}"
  }
}

Step 1: 开发者定义工具的 JSON Schema
        ↓
Step 2: Agent 将 Schema 注入 System Prompt
        ↓
Step 3: 大模型推理时，根据 Schema 生成函数调用
        ↓
Step 4: Agent 检测到 function_call 字段
        ↓
Step 5: Agent 执行对应函数，获取结果
        ↓
Step 6: Agent 将结果封装为 Tool Message 返回
        ↓
Step 7: 大模型基于结果继续推理

// 伪代码：Function Call 的使用方式

// 1. 定义工具 Schema
String toolSchema = """
{
  "name": "get_weather",
  "description": "获取指定城市的天气",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "城市名称"},
      "date": {"type": "string", "description": "日期 YYYY-MM-DD"}
    },
    "required": ["city"]
  }
}
""";

// 2. 调用大模型时传入工具列表
ChatCompletionResponse response = client.chat(
    messages,
    List.of(toolSchema)  // 注册可用工具
);

// 3. 处理响应
if (response.hasFunctionCall()) {
    FunctionCall call = response.getFunctionCall();
    String result = executeFunction(call);
    // 4. 将结果反馈给模型
    messages.add(new ToolMessage(call.getId(), result));
    // 再次调用模型...
}

┌──────────────┐     MCP Protocol     ┌──────────────┐
│  MCP Client  │◄────────────────────►│  MCP Server  │
│  (AI 应用)   │                      │  (工具提供方) │
└──────────────┘                      └──────────────┘

通信流程：
1. Client → Server: initialize（握手，协商版本）
2. Client → Server: tools/list（获取可用工具列表）
3. Server → Client: 返回工具定义（名称、描述、参数 Schema）
4. Client → Server: tools/call（调用指定工具）
5. Server → Client: 返回执行结果
6. Client → Server: resources/list（获取可用资源）
7. Server → Client: 返回资源列表
8. Client → Server: resources/read（读取资源）

// 伪代码：实现一个 MCP Server

// 1. 创建 MCP Server
MCPServer server = MCPServer.builder()
    .name("weather-server")
    .version("1.0.0")
    .build();

// 2. 注册工具
server.registerTool("get_weather", ToolDef.builder()
    .description("获取城市天气")
    .parameter("city", "string", "城市")
    .handler(params -> weatherService.getWeather(params.get("city")))
    .build());

// 3. 注册资源
server.registerResource("weather_codes",
    ResourceDef.builder()
        .description("天气代码表")
        .mimeType("application/json")
        .content(weatherCodesJson)
        .build());

// 4. 启动 Server
server.start();  // 通过 stdio/SSE 与 Client 通信

Skill 示例："数据分析技能"
├── Prompt：你是一个数据分析专家，擅长处理 CSV 文件...
├── 工具：[文件读取、Python 执行、图表生成]
└── 逻辑：读取数据 → 清洗 → 分析 → 生成报告

Skill 内部可以包含多个 Function Call 和 MCP 工具：

Skill "订单处理"
├── Function Call: query_order(order_id)     ← 原子调用
├── MCP Tool: send_email(to, content)        ← 通过 MCP 调用
├── Function Call: create_ticket(description) ← 原子调用
└── 执行逻辑：查询 → 通知 → 建单（步骤编排）

// 伪代码：定义和使用 Skill

// 定义 Skill
Skill dataAnalysisSkill = Skill.builder()
    .name("data_analysis")
    .systemPrompt("你是数据分析专家...")
    .tools(List.of(fileReadTool, pythonExecTool, chartTool))
    .build();

// 使用 Skill
agent.registerSkill(dataAnalysisSkill);
// 用户："帮我分析这个销售数据文件"
// Agent 加载 data_analysis Skill，使用其中的工具完成分析

一个 Skill 的上下文组成：
├── System Prompt: ~500-2000 Tokens
├── 工具定义（JSON Schema）: ~200-500 Tokens/工具
├── Few-shot 示例: ~500-2000 Tokens
└── 执行逻辑描述: ~200-500 Tokens
总计：一个 Skill 通常占用 1500-5000 Tokens

MCP 工具的上下文组成：
├── 工具名称: ~10 Tokens
├── 工具描述: ~50-200 Tokens
├── 参数 Schema: ~50-200 Tokens
└── （仅此而已）
总计：一个 MCP 工具通常占用 100-500 Tokens

Tool Call 返回结果
    ↓
┌─────────────────────┐
│  1. LLM 分析结果     │ ──→ 输出"继续"或"结束"
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  2. 检查显式条件     │ ──→ 结果是否满足预设规则
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  3. 检查最大轮次     │ ──→ 是否已达上限
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  4. 是否需要人工确认 │ ──→ 关键节点暂停
└─────────┬───────────┘
          │
     ┌────┴────┐
     ▼         ▼
  继续执行   结束任务

// 伪代码：实现多机制结束判断
int maxRounds = 10;
int currentRound = 0;

while (currentRound < maxRounds) {
    currentRound++;

    // 执行 Tool Call
    ToolResult result = agent.executeNextTool();

    // 机制 1: LLM 自主判断
    if (result.containsCompletionMark()) {
        break;
    }

    // 机制 2: 显式条件
    if (result.matches(completionRule)) {
        break;
    }

    // 机制 3: 最大轮次
    if (currentRound >= maxRounds) {
        agent.finalize("已达到最大执行轮次");
        break;
    }

    // 机制 4: 人工确认
    if (result.needsUserConfirmation()) {
        String userInput = agent.waitForUserInput();
        if (userInput.equals("确认完成")) break;
    }
}

Agent 生成代码
    ↓
发送到沙箱服务
    ↓
┌──────────────────────────────┐
│ 沙箱启动（容器/进程隔离）      │
│   ↓                          │
│ 资源限制应用（CPU/内存/超时）  │
│   ↓                          │
│ 权限控制（文件/网络/系统调用）  │
│   ↓                          │
│ 代码执行                      │
│   ↓                          │
│ 捕获输出/异常                 │
│   ↓                          │
│ 销毁沙箱环境                  │
└──────────────────────────────┘
    ↓
返回执行结果给 Agent

// 伪代码：使用沙箱执行代码
Sandbox sandbox = Sandbox.builder()
    .type(SandboxType.E2B)
    .timeout(30, TimeUnit.SECONDS)
    .memoryLimit(512, MemoryUnit.MB)
    .cpuLimit(1.0)
    .allowNetwork(false)
    .allowFileAccess("/tmp/workspace")
    .build();

ExecutionResult result = sandbox.execute(code, language);
if (result.isSuccess()) {
    System.out.println("Output: " + result.getOutput());
} else {
    System.out.println("Error: " + result.getError());
}

┌─────────────────────────────────────────────────┐
│              Code Execution Tool                 │
├─────────────────────────────────────────────────┤
│  1. 安全层（沙箱）                               │
│     ├── Docker / FireJail / E2B                 │
│     ├── 资源限制（CPU/内存/超时）                 │
│     └── 权限控制（文件/网络/系统调用）            │
├─────────────────────────────────────────────────┤
│  2. 执行层（多语言）                              │
│     ├── Python 解释器                            │
│     ├── Node.js 运行时                           │
│     ├── Java (JDK)                               │
│     └── Shell/Bash                               │
├─────────────────────────────────────────────────┤
│  3. 采集层（结果捕获）                           │
│     ├── 标准输出（stdout）                        │
│     ├── 错误输出（stderr）                       │
│     ├── 执行状态（exit code）                    │
│     └── 执行耗时（timing）                       │
├─────────────────────────────────────────────────┤
│  4. 处理层（错误处理）                           │
│     ├── 错误分类（语法/运行时/资源）              │
│     ├── 结构化错误信息生成                       │
│     └── 重试/降级决策                            │
├─────────────────────────────────────────────────┤
│  5. 观测层（日志与监控）                         │
│     ├── 执行日志记录                             │
│     ├── 错误统计分析                             │
│     └── 性能监控告警                             │
└─────────────────────────────────────────────────┘

代码执行报错
    ↓
┌─────────────────────┐
│ 1. 错误分类          │
│    ├── 语法错误      │ → 反馈给 LLM 修正
│    ├── 运行时错误    │ → 反馈给 LLM 修正
│    ├── 资源超限      │ → 调整资源限制或简化代码
│    └── 沙箱异常      │ → 基础设施问题，告警
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 2. 结构化错误反馈    │
│    {                │
│      "error_type":  │
│      "message":     │
│      "line":        │
│      "suggestion":  │
│    }                │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 3. LLM 自愈（重试）  │ → 最多 N 次（默认 3）
└─────────┬───────────┘
          │
          ▼
    重试成功？──否──→ 降级处理
          │是
          ▼
       返回结果    ├── 简化执行
                    ├── 建议用户手动
                    └── 记录学习（用于 Prompt 优化）

// 伪代码：代码执行工具使用
CodeExecutionTool codeTool = CodeExecutionTool.builder()
    .sandbox(new DockerSandbox("python:3.11-slim"))
    .language(ProgrammingLanguage.PYTHON)
    .maxRetries(3)
    .timeout(30, TimeUnit.SECONDS)
    .onError(ErrorStrategy.AUTO_FIX)
    .build();

ExecutionResult result = codeTool.execute(code);
// result 包含: success, stdout, stderr, exitCode, executionTime

if (!result.isSuccess() && result.getRetryCount() >= 3) {
    // 降级处理
    agent.handoffToUser("代码多次执行失败，建议手动检查");
}

失败场景分析：
├── 基础设施层（Tool 内部重试）
│   ├── 网络超时/抖动
│   ├── 服务暂时不可用
│   └── 资源临时不可用
│
│   处理：固定次数（2-3次）+ 递增等待（1s, 2s, 4s）
│
└── 智能层（Agent 多次调用）
    ├── 参数格式错误
    ├── 业务规则不满足
    ├── 需要补充信息
    └── 服务返回需要进一步处理
│
    处理：LLM 分析错误 → 调整参数/方案 → 重新调用

// 伪代码：分层重试设计

// Tool 层：处理瞬时故障
@Retryable(
    value = {TimeoutException.class, ServiceUnavailableException.class},
    maxAttempts = 3,
    backoff = @Backoff(delay = 1000, multiplier = 2)
)
public ToolResult callTool(ToolRequest request) {
    return toolClient.execute(request);
}

// Agent 层：处理逻辑错误
while (retryCount < MAX_AGENT_RETRIES) {
    ToolResult result = tool.execute(request);

    if (result.isLogicError()) {
        // 需要 LLM 分析并调整
        String correctedParams = llm.analyzeAndFix(
            result.getError(),
            request.getParams()
        );
        request.setParams(correctedParams);
        retryCount++;
    } else if (result.isSuccess()) {
        break;
    } else {
        // 未知错误，直接失败
        throw new AgentExecutionException(result.getError());
    }
}

// Tool 支持分页参数
ToolResult result = tool.queryOrders(
    QueryRequest.builder()
        .pageSize(20)      // 每页大小
        .pageNum(1)        // 当前页
        .filter("status=paid")
        .build()
);

// Agent 根据结果决定是否翻页
if (result.hasMore()) {
    // 获取下一页
    ToolResult nextPage = tool.queryOrders(result.nextPageRequest());
}

// Tool 返回摘要和详情引用
ToolResult result = tool.search("订单数据");
// result.getSummary() → "共找到 1,234 条订单，前 20 条已返回"
// result.getTotalCount() → 1234
// result.getDetailRef() → "ref:order_detail_abc" (引用 ID)
// Agent 需要详情时再通过 ref 获取
ToolResult detail = tool.getDetail("ref:order_detail_abc");

// Tool 提供精细化查询接口
ToolResult result = tool.queryOrders(
    QueryRequest.builder()
        .filter("status=paid AND amount>1000")
        .sortBy("create_time", SortOrder.DESC)
        .fields("order_id", "status", "amount")  // 只返回需要的字段
        .build()
);

// 大结果存储在外部，仅返回引用
ToolResult result = tool.exportData("orders_2024");
// result.getCacheId() → "cache_abc123"
// result.getExpireTime() → "2024-06-02T10:00:00"
// Agent 需要时通过引用 ID 异步获取

Tool 返回大结果
    ↓
┌─────────────────────┐
│ 1. 判断结果量级      │
│    ├── 小（<1000 Token）→ 直接返回
│    ├── 中（1000-10K）→ 摘要截断
│    └── 大（>10K）→ 分页/缓存
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 2. 返回分层结果      │
│    ├── 摘要/前 N 条  │
│    ├── 总数/分页信息 │
│    └── 引用 ID       │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ 3. Agent 按需获取    │
│    ├── 需要更多 → 翻页│
│    ├── 需要详情 → 引用│
│    └── 不需要 → 结束  │
└─────────────────────┘

┌─────────────────────────────────────────────────┐
│              Coding Agent 架构                    │
├─────────────────────────────────────────────────┤
│                                                  │
│  ┌─────────────┐   ┌─────────────┐              │
│  │ 需求理解模块  │──→│ 代码规划模块  │              │
│  └─────────────┘   └──────┬──────┘              │
│                           │                      │
│                           ▼                      │
│  ┌─────────────┐   ┌─────────────┐              │
│  │ 项目管理模块  │──→│ 代码生成模块  │              │
│  └─────────────┘   └──────┬──────┘              │
│                           │                      │
│                           ▼                      │
│  ┌─────────────┐   ┌─────────────┐              │
│  │ 错误修复模块  │←──│ 代码执行模块  │              │
│  └─────────────┘   └─────────────┘              │
│                           │                      │
│                           ▼                      │
│                    ┌─────────────┐              │
│                    │ 交互协作模块  │              │
│                    └─────────────┘              │
│                                                  │
└─────────────────────────────────────────────────┘

用户："帮我写一个 Spring Boot 的用户 CRUD 接口"
    ↓
需求理解：识别为 Web API 开发任务
    ↓
代码规划：
  1. 创建 User 实体类
  2. 创建 UserRepository
  3. 创建 UserService
  4. 创建 UserController
  5. 配置数据库连接
  6. 编写单元测试
    ↓
代码生成：按规划逐步生成各文件
    ↓
项目管理：创建文件结构、添加依赖
    ↓
代码执行：编译 + 运行 + 测试
    ↓
错误修复：编译错误 → 修正 → 重新执行
    ↓
交互协作：向用户展示结果、确认是否需要调整

┌─────────────────────────────────┐
│        Orchestrator Agent        │
│  （主控：任务分配、结果汇总）      │
└────────┬──────────┬──────────────┘
         │          │
    ┌────▼───┐  ┌───▼────┐  ┌────────┐
    │Agent A │  │Agent B │  │Agent C │
    │(前端)  │  │(后端)  │  │(测试)  │
    └────────┘  └────────┘  └────────┘
         │          │          │
         └──────────┴──────────┘
                    │
              结果汇总

┌──────────┐ 提议  ┌──────────┐
│ Agent A  │──────→│ Agent B  │
│(产品经理)│       │(架构师)  │
└────┬─────┘       └────┬─────┘
     │                  │
     │  ←──── 反对 ────│
     │                  │
     ▼                  ▼
┌──────────┐ 协商  ┌──────────┐
│ Agent C  │──────→│ Agent D  │
│(开发者)  │       │(测试)    │
└──────────┘       └──────────┘
     │                  │
     └──────── 达成共识 ────────┘

agentA.sendMessage(agentB,
    Message.builder()
        .type(MessageType.TASK_REQUEST)
        .content("请实现用户认证接口")
        .build()
);

// 所有 Agent 共享一个知识黑板
blackboard.post("task_board",
    TaskBoard.builder()
        .addTask("auth_api", Status.IN_PROGRESS)
        .addResult("auth_api", "完成 JWT 认证实现")
        .build()
);
// Agent 从黑板读取其他 Agent 的进度

// Agent 间直接消息传递
MessageBus messageBus = new MessageBus();

// 发送消息
agent.send(Message.builder()
    .id(UUID.randomUUID().toString())
    .from("agent-001")
    .to("agent-002")
    .type(MessageType.TASK_RESULT)
    .content("用户模块开发完成")
    .payload(Map.of("files", List.of("User.java", "UserController.java")))
    .timestamp(LocalDateTime.now())
    .build());

// 接收消息
messageBus.subscribe("agent-002", message -> {
    if (message.getType() == MessageType.TASK_RESULT) {
        // 处理任务结果
    }
});

// 所有 Agent 共享的状态空间
Blackboard blackboard = new Blackboard();

// Agent A 写入状态
blackboard.write("task:user-module",
    TaskState.builder()
        .status(Status.IN_PROGRESS)
        .progress(0.6)
        .artifacts(List.of("User.java"))
        .updatedAt(LocalDateTime.now())
        .build()
);

// Agent B 读取状态
TaskState state = blackboard.read("task:user-module");
if (state.getProgress() > 0.5) {
    // 开始测试准备
}

// 使用 Redis 持久化 Agent 状态
StateStore stateStore = RedisStateStore.builder()
    .host("localhost")
    .port(6379)
    .keyPrefix("agent:state:")
    .ttl(24, TimeUnit.HOURS)
    .build();

// 保存状态
stateStore.save("session-001", AgentState.builder()
    .sessionId("session-001")
    .currentTask("用户认证模块")
    .completedTasks(List.of("实体创建", "Repository"))
    .context(Map.of("tech_stack", "Spring Boot"))
    .build()
);

// 恢复状态
AgentState state = stateStore.load("session-001");

// 状态变更通知机制
public class StateSyncManager {
    private final List<StateListener> listeners = new CopyOnWriteArrayList<>();

    public void registerListener(String agentId, StateListener listener) {
        listeners.add(listener);
    }

    public void broadcast(StateChangeEvent event) {
        // 通知所有相关 Agent
        listeners.stream()
            .filter(l -> l.isInterestedIn(event.getChannel()))
            .forEach(l -> l.onStateChange(event));
    }
}

// 按 session_id 隔离状态
public class IsolatedStateManager {
    private final Map<String, AgentState> sessionStates = new ConcurrentHashMap<>();

    public AgentState getState(String sessionId) {
        return sessionStates.computeIfAbsent(sessionId,
            id -> AgentState.init(id)
        );
    }

    public void updateState(String sessionId, AgentState state) {
        sessionStates.put(sessionId, state);
    }

    public void cleanExpired() {
        // 清理过期会话
    }
}

┌─────────────────────────────────────────────────────┐
│                 通信与状态管理架构                    │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌──────────────┐     ┌──────────────┐             │
│  │  Agent A     │     │  Agent B     │             │
│  └──────┬───────┘     └──────┬───────┘             │
│         │                    │                     │
│         ▼                    ▼                     │
│  ┌──────────────────────────────────────┐          │
│  │           消息传递层（Message Bus）    │          │
│  │  点对点通信 / 广播 / 订阅              │          │
│  └──────────────────────────────────────┘          │
│         │                    │                     │
│         ▼                    ▼                     │
│  ┌──────────────────────────────────────┐          │
│  │           共享黑板层（Blackboard）     │          │
│  │  状态共享 / 进度同步 / 结果汇总        │          │
│  └──────────────────────────────────────┘          │
│         │                    │                     │
│         ▼                    ▼                     │
│  ┌──────────────────────────────────────┐          │
│  │           状态持久层（State Store）    │          │
│  │  Redis / DB / 文件存储                │          │
│  └──────────────────────────────────────┘          │
│                                                     │
└─────────────────────────────────────────────────────┘

// 评估 Agent 是否完成任务
public class TaskCompletionEvaluator {

    public EvaluationResult evaluate(AgentTask task, AgentResult result) {
        boolean completed = checkTaskCompletion(task, result);
        List<String> missingSteps = findMissingSteps(task, result);
        List<String> errors = findErrors(result);

        return EvaluationResult.builder()
            .taskId(task.getId())
            .completed(completed)
            .completionRate(calculateCompletionRate(task, result))
            .missingSteps(missingSteps)
            .errors(errors)
            .score(calculateScore(completed, missingSteps, errors))
            .build();
    }

    private double calculateScore(boolean completed,
            List<String> missing, List<String> errors) {
        double score = completed ? 1.0 : 0.5;
        score -= missing.size() * 0.1;
        score -= errors.size() * 0.15;
        return Math.max(0, score);
    }
}

public class ProcessQualityEvaluator {

    public ProcessEvaluation evaluate(List<AgentStep> steps) {
        int correctToolCalls = countCorrectToolCalls(steps);
        int totalToolCalls = steps.size();
        double toolAccuracy = totalToolCalls > 0
            ? (double) correctToolCalls / totalToolCalls
            : 0.0;

        int optimalSteps = calculateOptimalSteps(steps);
        int actualSteps = steps.size();
        double stepEfficiency = optimalSteps > 0
            ? (double) optimalSteps / actualSteps
            : 1.0;

        return ProcessEvaluation.builder()
            .toolCallAccuracy(toolAccuracy)
            .stepEfficiency(stepEfficiency)
            .decisionQuality(evaluateDecisions(steps))
            .build();
    }
}

public class EfficiencyEvaluator {

    public EfficiencyMetrics evaluate(AgentExecution execution) {
        return EfficiencyMetrics.builder()
            .totalTokens(execution.getTotalTokens())
            .inputTokens(execution.getInputTokens())
            .outputTokens(execution.getOutputTokens())
            .toolResultTokens(execution.getToolResultTokens())
            .executionTimeMs(execution.getDuration().toMillis())
            .toolCallCount(execution.getToolCalls().size())
            .estimatedCost(calculateCost(execution))
            .build();
    }
}

自动评估（量化指标）
    ↓
人工评估（质量判断）
    ↓
加权汇总 → 综合评分

1. 定义评估用例集
    ├── 覆盖典型场景（60%）
    ├── 覆盖边界场景（30%）
    └── 覆盖异常场景（10%）
    ↓
2. 批量执行 Agent
    ↓
3. 自动评估
    ├── 检查任务完成度
    ├── 统计效率指标
    ├── 检测安全问题
    ↓
4. 人工评估
    ├── 抽样评估质量
    ├── 开放性问题打分
    ↓
5. 汇总报告
    ├── 整体评分
    ├── 各维度得分
    ├── 改进建议

用户输入 → 关键词提取 → 倒排索引匹配 → 返回文档列表 → 用户阅读

用户问题 → 向量化 → 语义检索 → 返回相关文档
    → 将文档+问题提交给 LLM → LLM 生成答案 + 引用来源

用户问："如何配置 Spring Boot 的数据库连接池？"

传统搜索：
  → 返回 10 篇文档（"Spring Boot HikariCP 配置"、"数据库连接池详解"...）
  → 用户需逐一阅读找到答案

RAG：
  → 检索到最相关的 3 段内容
  → 大模型生成：
    "Spring Boot 默认使用 HikariCP 作为连接池，配置方式如下：
     在 application.yml 中设置 spring.datasource.hikari.maximum-pool-size=10...
     （引用：Spring Boot 官方文档第 8.3 节）"

用户问："如何优化 Java 程序的启动速度？"

关键词检索匹配的文档：
  ✅ "Java 启动性能调优"（精确匹配）
  ❌ "Spring Boot 容器初始化优化"（相关但关键词不同）
  ❌ "JVM 类加载机制详解"（相关但关键词不同）
  ❌ "减少 Bean 初始化时间"（相关但表达方式不同）

用户问："分布式锁的实现方式？"

关键词检索可能遗漏：
  ❌ "分布式互斥锁"（同义词"互斥锁"≠"锁"）
  ❌ "Redis SETNX 实现并发控制"（用"并发控制"代替"锁"）
  ❌ "Zookeeper 临时节点原理"（技术方案名称不含"锁"）

查询："Redis 缓存穿透解决方案"

排序靠前的文档：
  1. "Redis 缓存穿透、击穿、雪崩详解"（词频高，但内容不聚焦）
  2. "布隆过滤器实战"（词频低，但恰好是解决方案）
  → 用户可能错过最相关的文档

语义检索通过 Embedding 将文本映射到高维向量：

"如何优化 Java 程序的启动速度？" → 向量 A
"Spring Boot 容器初始化优化" → 向量 B（与 A 余弦相似度高）
"JVM 类加载机制详解" → 向量 C（与 A 余弦相似度中等）
"减少 Bean 初始化时间" → 向量 D（与 A 余弦相似度高）

通过向量相似度计算，即使关键词不同，语义相近的文档也能被召回

// 混合检索：关键词 + 语义
public List<Document> hybridSearch(String query) {
    // 关键词检索（保留精确匹配能力）
    List<ScoredDoc> keywordResults = keywordSearch(query, topK);

    // 语义检索（补充语义召回）
    List<ScoredDoc> semanticResults = semanticSearch(query, topK);

    // 融合排序（RRF 或加权融合）
    return reciprocalRankFusion(keywordResults, semanticResults);
}

用户查询
    ↓
关键词检索（精确匹配）
    ↓ 未命中
语义检索（补充召回）
    ↓
返回结果

用户查询
    ↓
┌──────────┬──────────┐
│          │          │
▼          ▼          ▼
关键词    语义     元数据过滤
检索      检索      （时间/权限）
│          │          │
└──────────┴──────────┘
    ↓
  融合排序
    ↓
  返回结果

// RRF 融合算法
public double rrfScore(int rank, double k) {
    return 1.0 / (k + rank);
}

public List<Document> hybridSearch(String query, double keywordWeight, double semanticWeight) {
    List<ScoredDoc> keywordResults = keywordSearch(query);
    List<ScoredDoc> semanticResults = semanticSearch(query);

    // RRF 融合
    Map<String, Double> scores = new HashMap<>();
    for (int i = 0; i < keywordResults.size(); i++) {
        String docId = keywordResults.get(i).getId();
        scores.merge(docId, rrfScore(i + 1, 60) * keywordWeight, Double::sum);
    }
    for (int i = 0; i < semanticResults.size(); i++) {
        String docId = semanticResults.get(i).getId();
        scores.merge(docId, rrfScore(i + 1, 60) * semanticWeight, Double::sum);
    }

    return scores.entrySet().stream()
        .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
        .map(e -> getDocument(e.getKey()))
        .collect(Collectors.toList());
}

public class RetrievalEvaluator {

    public EvaluationResult evaluate(List<Query> queries,
            RetrievalSystem system) {

        double totalRecall = 0;
        double totalPrecision = 0;
        double totalMRR = 0;

        for (Query query : queries) {
            List<Document> results = system.search(query.getText(), 10);
            Set<String> relevantIds = query.getRelevantDocIds();

            int relevantFound = 0;
            for (int i = 0; i < results.size(); i++) {
                if (relevantIds.contains(results.get(i).getId())) {
                    relevantFound++;
                    totalMRR += 1.0 / (i + 1);
                }
            }

            totalRecall += (double) relevantFound / relevantIds.size();
            totalPrecision += (double) relevantFound / results.size();
        }

        int n = queries.size();
        return EvaluationResult.builder()
            .recallAtK(totalRecall / n)
            .precisionAtK(totalPrecision / n)
            .mrr(totalMRR / n)
            .build();
    }
}

Step 1: 准备标注数据集
  ├── 查询集合（覆盖典型/边界/异常场景）
  ├── 每个查询的相关文档标注
  └── 每个查询的标准答案（可选）
    ↓
Step 2: 运行检索系统
  ├── 执行所有查询
  ├── 记录 TopK 结果
  └── 保存检索日志
    ↓
Step 3: 计算检索指标
  ├── Recall@K、Precision@K
  ├── MRR、NDCG
  └── 与基线方法对比
    ↓
Step 4: 评估生成质量
  ├── 答案准确性打分
  ├── 引用正确性检查
  └── 幻觉检测
    ↓
Step 5: 生成评估报告

// 简单但可能切断语义
public List<Chunk> fixedChunk(String text, int chunkSize, int overlap) {
    List<Chunk> chunks = new ArrayList<>();
    for (int i = 0; i < text.length(); i += chunkSize - overlap) {
        int end = Math.min(i + chunkSize, text.length());
        chunks.add(new Chunk(text.substring(i, end)));
    }
    return chunks;
}

public List<Chunk> semanticChunk(String text) {
    List<Chunk> chunks = new ArrayList<>();
    List<String> paragraphs = splitByParagraphs(text);

    StringBuilder currentChunk = new StringBuilder();
    for (String para : paragraphs) {
        if (currentChunk.length() + para.length() > MAX_CHUNK_SIZE) {
            chunks.add(new Chunk(currentChunk.toString()));
            currentChunk = new StringBuilder(para);
        } else {
            currentChunk.append(para);
        }
    }
    if (currentChunk.length() > 0) {
        chunks.add(new Chunk(currentChunk.toString()));
    }
    return chunks;
}

文档 → 章节 → 段落 → 句子
（按文档组织结构分层切片，检索时可选择粒度）

文档变更 → 版本号/哈希变更检测
    ↓
┌─────────────────────────────┐
│ 变更检测层                   │
│ 对比文档版本号/哈希值        │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ 更新调度层                   │
│ 同步/异步/增量策略选择       │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ 索引更新层                   │
│ 重新嵌入 + 向量索引更新      │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ 校验层（定期全量校验）       │
│ 比对原文与索引的版本一致性   │
└─────────────────────────────┘

public class IndexSyncService {

    private final DocumentStore documentStore;
    private final VectorStore vectorStore;
    private final EmbeddingService embeddingService;
    private final MessageQueue messageQueue;

    // 增量更新
    public void onDocumentChanged(String docId) {
        Document doc = documentStore.get(docId);
        String newHash = doc.calculateHash();

        // 检测变更
        if (doc.getLastIndexedHash().equals(newHash)) {
            return; // 无变更
        }

        // 找出变更的 Chunk
        List<Chunk> changedChunks = findChangedChunks(doc);

        // 更新变更的 Chunk
        for (Chunk chunk : changedChunks) {
            float[] embedding = embeddingService.embed(chunk.getText());
            vectorStore.upsert(
                docId + ":" + chunk.getId(),
                embedding,
                chunk.getMetadata()
            );
        }

        // 更新版本号
        doc.setLastIndexedHash(newHash);
        documentStore.update(doc);
    }

    // 异步更新（通过消息队列）
    public void asyncSync(String docId) {
        messageQueue.publish("doc-changed", docId);
    }

    // 消费者
    @SqsListener("doc-changed")
    public void onMessage(String docId) {
        onDocumentChanged(docId);
    }
}

public List<ScoredDoc> semanticFilter(String query,
        List<ScoredDoc> keywordResults, double threshold) {
    float[] queryEmbedding = embeddingService.embed(query);

    return keywordResults.stream()
        .filter(doc -> {
            float[] docEmbedding = embeddingService.embed(doc.getText());
            double similarity = cosineSimilarity(queryEmbedding, docEmbedding);
            return similarity > threshold;
        })
        .collect(Collectors.toList());
}

public List<ScoredDoc> rerank(String query, List<ScoredDoc> candidates) {
    // Cross-Encoder 同时考虑查询和文档的交互特征
    List<RerankedResult> reranked = crossEncoder.rerank(query, candidates);

    return reranked.stream()
        .sorted(Comparator.comparingDouble(RerankedResult::getScore).reversed())
        .map(r -> candidates.get(r.getOriginalIndex()))
        .collect(Collectors.toList());
}

public double fusedScore(double keywordScore, double semanticScore,
        double semanticWeight) {
    // 语义相关性低时，整体分数大幅降低
    double semanticFactor = semanticScore > 0.5 ? 1.0 : 0.3;
    return keywordScore * semanticFactor * semanticWeight;
}

并行检索
├── 关键词检索 → TopK 结果
├── 语义检索 → TopK 结果
│
└── 融合
    ↓
语义过滤（去除语义不相关的关键词结果）
    ↓
Rerank（Cross-Encoder 精排）
    ↓
返回最终结果

// 让 LLM 先生成一个"假设性答案"，再用假设答案做检索
public String hydeSearch(String query) {
    // Step 1: 生成假设性答案
    String hypothetical = llm.generate(
        "根据以下问题生成一个可能的答案：" + query
    );

    // Step 2: 用假设性答案做检索（通常比原问题效果好）
    return vectorSearch(hypothetical);
}

public String rewriteQuery(String query) {
    return llm.generate(
        "将以下查询改写为更适合检索的形式，" +
        "包含关键词扩展和语义澄清：" + query
    );
}

public List<Document> searchWithFilter(String query,
        String source, LocalDate fromDate) {
    return vectorStore.search(
        query,
        Filter.builder()
            .eq("source", source)
            .gte("publish_date", fromDate)
            .build()
    );
}

System Prompt:
你是一个基于检索内容回答问题的助手。
规则：
1. 只基于提供的上下文回答，不要编造
2. 在答案中标注引用来源 [1][2]
3. 如果上下文不足以回答，明确说明
4. 优先使用最新的信息

Context:
[1] {doc1_content}
[2] {doc2_content}

Question: {user_query}

public List<Document> selectDocuments(List<Document> docs, int maxDocs) {
    // 按相关性排序
    docs.sort(Comparator.comparingDouble(Document::getScore).reversed());

    // 去重 + 多样性保证
    List<Document> selected = new ArrayList<>();
    Set<String> seenSources = new HashSet<>();
    for (Document doc : docs) {
        if (selected.size() >= maxDocs) break;
        if (!seenSources.contains(doc.getSource())) {
            selected.add(doc);
            seenSources.add(doc.getSource());
        }
    }
    return selected;
}

没有 CoT：
用户：一个商店有 23 个苹果，卖了 17 个，又进货 8 个，还剩多少？
模型：34 个（可能算错）

有 CoT：
用户：一个商店有 23 个苹果，卖了 17 个，又进货 8 个，还剩多少？
模型：让我们一步步思考：
  1. 初始 23 个
  2. 卖了 17 个：23 - 17 = 6 个
  3. 进货 8 个：6 + 8 = 14 个
  4. 答案是 14 个
（准确率显著提升）

Prompt:
问题：{question}
让我们一步步思考，然后给出答案。

Prompt:
示例：
问题：小明有 5 个糖果，给了小红 3 个，又买了 2 个
思考过程：
1. 初始 5 个
2. 给了 3 个：5 - 3 = 2
3. 买了 2 个：2 + 2 = 4
答案：4

问题：{question}
思考过程：

// 多次采样，取多数答案
public String selfConsistencyCoT(String question, int samples) {
    Map<String, Integer> answerCounts = new HashMap<>();
    for (int i = 0; i < samples; i++) {
        String response = llm.coTGenerate(question);
        String answer = extractAnswer(response);
        answerCounts.merge(answer, 1, Integer::sum);
    }
    return answerCounts.entrySet().stream()
        .max(Map.Entry.comparingByValue())
        .getKey();
}

用户提问
    ↓
检索权威文档（知识注入）
    ↓
构建 Prompt：
  System: 只基于提供的上下文回答，不编造信息。
  Context: [检索到的文档内容]
  Question: 用户问题
  Instruction: 如果上下文不足，说明"根据现有信息无法回答"
    ↓
模型生成答案（基于检索内容）
    ↓
验证答案引用（确保引用来源真实）

public class FaithfulnessEvaluator {

    public FaithfulnessResult evaluate(String answer,
            List<Document> retrievedDocs) {
        // 将答案切分为原子陈述
        List<String> claims = extractClaims(answer);

        int supportedClaims = 0;
        List<String> unsupportedClaims = new ArrayList<>();

        for (String claim : claims) {
            // 检查每个陈述是否被检索文档支持
            boolean supported = checkSupport(claim, retrievedDocs);
            if (supported) {
                supportedClaims++;
            } else {
                unsupportedClaims.add(claim);
            }
        }

        double faithfulness = (double) supportedClaims / claims.size();

        return FaithfulnessResult.builder()
            .faithfulness(faithfulness)
            .totalClaims(claims.size())
            .supportedClaims(supportedClaims)
            .unsupportedClaims(unsupportedClaims)
            .build();
    }
}

public class CitationEvaluator {

    public CitationResult evaluate(String answer,
            List<Document> retrievedDocs) {
        // 提取答案中的引用
        List<Citation> citations = extractCitations(answer);

        int correctCitations = 0;
        List<Citation> incorrectCitations = new ArrayList<>();

        for (Citation citation : citations) {
            // 检查引用是否对应正确的文档
            if (citation.isValid(retrievedDocs)) {
                correctCitations++;
            } else {
                incorrectCitations.add(citation);
            }
        }

        double accuracy = citations.isEmpty() ? 1.0
            : (double) correctCitations / citations.size();

        return CitationResult.builder()
            .citationAccuracy(accuracy)
            .totalCitations(citations.size())
            .correctCitations(correctCitations)
            .build();
    }
}

需求分析
    ↓
┌─────────────────────┐
│ 1. 能力需求评估      │
│   - 推理/代码/多模态？│
│   - 中文/英文？       │
│   - 准确率要求？      │
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│ 2. 安全与合规        │
│   - 数据可外传？      │
│   - 需要私有化？      │
│   - 行业合规要求？    │
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│ 3. 成本与性能        │
│   - 预算范围？        │
│   - 延迟要求？        │
│   - 吞吐量？          │
└─────────┬───────────┘
          ↓
    模型选型决策

┌──────────┐    HTTP POST     ┌──────────────┐
│  客户端   │─────────────────→│  API 网关     │
│          │                 │  (鉴权/路由)  │
└────┬─────┘                 └──────┬───────┘
     │                              │
     │                   ┌──────────▼──────────┐
     │                   │    模型服务           │
     │                   │  (推理引擎 + GPU)    │
     │                   └──────────┬──────────┘
     │                              │
     │                   推理完成，返回结果
     │                              │
     │←────────── HTTP Response ────┘
     │
     ▼
  客户端处理结果

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "你是一个助手"},
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": false
}

服务端按 Token 粒度推送：

data: {"choices":[{"delta":{"content":"你"}}]}

data: {"choices":[{"delta":{"content":"好"}}]}

data: {"choices":[{"delta":{"content":"！"}}]}

data: [DONE]

// 使用 OkHttp 调用流式 API
OkHttpClient client = new OkHttpClient();

RequestBody body = RequestBody.create(
    jsonPayload,
    MediaType.parse("application/json")
);

Request request = new Request.Builder()
    .url("https://api.openai.com/v1/chat/completions")
    .header("Authorization", "Bearer " + apiKey)
    .post(body)
    .build();

// 流式处理
try (Response response = client.newCall(request).execute()) {
    BufferedSource source = response.body().source();
    while (!source.exhausted()) {
        String line = source.readUtf8Line();
        if (line.startsWith("data: ")) {
            String data = line.substring(6);
            if ("[DONE]".equals(data)) break;
            // 解析并处理每个 Token
            processToken(data);
        }
    }
}

// 使用 WebClient 处理流式响应
WebClient client = WebClient.create();

Flux<String> tokenStream = client.post()
    .uri("/v1/chat/completions")
    .contentType(MediaType.APPLICATION_JSON)
    .bodyValue(requestBody)
    .retrieve()
    .bodyToFlux(String.class);

tokenStream.subscribe(
    token -> {
        // 实时渲染 Token
        appendToUI(token);
    },
    error -> log.error("Stream error", error),
    () -> log.info("Stream completed")
);

# System Prompt（设定身份和行为规则）
你是一名{role}，擅长{skill}。
规则：
1. {rule1}
2. {rule2}

# Context（提供背景信息）
背景：{context}

# Instruction（明确任务指令）
请{task_description}

# Example（提供示例，可选）
示例：
输入：{example_input}
输出：{example_output}

# Output Format（指定输出格式）
输出格式：{format_spec}

# User Input（用户输入）
{user_input}

请将以下技术术语解释为通俗易懂的比喻：

示例：
术语：JVM
解释：JVM 就像一个"翻译官"，把 Java 代码翻译成电脑能听懂的指令

术语：HashMap
解释：

请以 JSON 格式输出，包含以下字段：
{
  "answer": "详细答案",
  "confidence": 0.0-1.0的置信度,
  "sources": ["引用来源列表"]
}

请一步步思考以下问题，然后给出最终答案：
问题：{question}
思考过程：

1. 写初始 Prompt
    ↓
2. 测试典型用例
    ↓
3. 分析输出问题
    ├── 指令不清晰 → 简化指令
    ├── 输出不符合格式 → 添加格式约束
    ├── 知识不足 → 添加背景信息
    └── 风格不对 → 调整角色/语气
    ↓
4. 优化 Prompt
    ↓
5. 重新测试
    ↓
6. 迭代至满意

┌─────────────────────────────────────────────────┐
│              上下文工程                          │
├─────────────────────────────────────────────────┤
│                                                  │
│  ┌──────────────┐                               │
│  │ 1. 提示词设计  │ ← 提示词工程                  │
│  └──────────────┘                               │
│                                                  │
│  ┌──────────────┐                               │
│  │ 2. 历史管理   │ 选择/压缩/隔离历史对话          │
│  └──────────────┘                               │
│                                                  │
│  ┌──────────────┐                               │
│  │ 3. 知识注入   │ RAG 检索结果、知识库            │
│  └──────────────┘                               │
│                                                  │
│  ┌──────────────┐                               │
│  │ 4. 工具上下文  │ 工具定义、执行结果             │
│  └──────────────┘                               │
│                                                  │
│  ┌──────────────┐                               │
│  │ 5. 多模态处理  │ 图片、文件、代码等             │
│  └──────────────┘                               │
│                                                  │
└─────────────────────────────────────────────────┘

public class ContextManager {

    // 策略一：滑动窗口（保留最近 N 轮）
    public List<Message> slidingWindow(List<Message> history, int windowSize) {
        int start = Math.max(0, history.size() - windowSize);
        return history.subList(start, history.size());
    }

    // 策略二：摘要压缩（旧对话压缩为摘要）
    public List<Message> summarizeAndCompress(List<Message> history) {
        // 旧对话 → LLM 生成摘要 → 摘要作为上下文
        String summary = llm.summarize(history.subList(0, history.size() - 5));
        List<Message> result = new ArrayList<>();
        result.add(new SystemMessage("对话摘要：" + summary));
        result.addAll(history.subList(history.size() - 5, history.size()));
        return result;
    }

    // 策略三：关键信息提取（只保留关键信息）
    public List<Message> extractKeyInfo(List<Message> history) {
        // 提取用户偏好、决策、关键数据
        return history.stream()
            .filter(msg -> msg.isKeyInformation())
            .collect(Collectors.toList());
    }
}

public class IsolatedContextStore {

    private final Map<String, List<Message>> sessionContexts = new ConcurrentHashMap<>();

    // 获取用户会话上下文
    public List<Message> getContext(String sessionId) {
        return sessionContexts.getOrDefault(sessionId, new ArrayList<>());
    }

    // 更新上下文
    public void addMessage(String sessionId, Message message) {
        sessionContexts.computeIfAbsent(sessionId, k -> new ArrayList<>())
            .add(message);
    }

    // 清理过期会话
    @Scheduled(fixedRate = 3600000) // 每小时
    public void cleanExpiredSessions() {
        // 清理超过 24 小时未活跃的会话
        sessionContexts.entrySet().removeIf(
            entry -> isExpired(entry.getKey())
        );
    }
}

// 请求中携带 Session ID
@RestController
public class AgentController {

    @PostMapping("/chat")
    public ChatResponse chat(
            @RequestBody ChatRequest request,
            @RequestHeader("X-Session-Id") String sessionId) {

        // 使用 Session ID 隔离上下文
        List<Message> context = contextStore.getContext(sessionId);
        context.add(new UserMessage(request.getMessage()));

        // 调用 Agent
        AgentResponse response = agent.run(context);

        // 保存上下文
        context.add(new AssistantMessage(response.getText()));
        contextStore.addMessage(sessionId, new AssistantMessage(response.getText()));

        return ChatResponse.from(response);
    }
}

// 使用 Redis 的 Key 前缀隔离
public class RedisContextStore {

    private static final String KEY_PREFIX = "agent:context:";

    public List<Message> getContext(String sessionId) {
        String key = KEY_PREFIX + sessionId;
        String json = redisTemplate.opsForValue().get(key);
        return json != null ? deserialize(json) : new ArrayList<>();
    }

    public void saveContext(String sessionId, List<Message> messages) {
        String key = KEY_PREFIX + sessionId;
        redisTemplate.opsForValue().set(key, serialize(messages), 24, TimeUnit.HOURS);
    }
}

public class ContextSelector {

    // 策略一：滑动窗口
    public List<Message> selectByWindow(List<Message> all, int lastN) {
        return all.subList(Math.max(0, all.size() - lastN), all.size());
    }

    // 策略二：关键词过滤
    public List<Message> selectByKeyword(List<Message> all, String keyword) {
        return all.stream()
            .filter(msg -> msg.getContent().contains(keyword))
            .collect(Collectors.toList());
    }

    // 策略三：语义检索
    public List<Message> selectBySemantic(List<Message> all, String query, int topK) {
        // 将历史消息向量化，按语义相似度选择
        return semanticSearch(all, query, topK);
    }

    // 策略四：时间窗口
    public List<Message> selectByTimeRange(List<Message> all,
            LocalDateTime from, LocalDateTime to) {
        return all.stream()
            .filter(msg -> msg.getTimestamp().isAfter(from)
                && msg.getTimestamp().isBefore(to))
            .collect(Collectors.toList());
    }
}

public class ContextCompressor {

    // 策略一：LLM 摘要压缩
    public CompressedContext summarize(List<Message> oldMessages) {
        String summary = llm.generate(
            "请总结以下对话的关键信息：\n" +
            formatMessages(oldMessages)
        );
        return new CompressedContext(summary, oldMessages.size());
    }

    // 策略二：结构化提取
    public StructuredContext extractStructure(List<Message> messages) {
        Map<String, Object> structure = new HashMap<>();
        structure.put("user_preferences", extractPreferences(messages));
        structure.put("key_decisions", extractDecisions(messages));
        structure.put("entities", extractEntities(messages));
        return new StructuredContext(structure);
    }

    // 策略三：Token 预算分配
    public List<Message> allocateBudget(List<Message> messages, int maxTokens) {
        // 系统提示 + 摘要 + 最近对话
        List<Message> result = new ArrayList<>();
        result.add(getSystemPrompt());
        result.add(getSummary(messages));
        result.addAll(getRecentMessagesWithinBudget(messages, maxTokens));
        return result;
    }
}

-- 会话表
CREATE TABLE conversation (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    session_id VARCHAR(64) NOT NULL UNIQUE,
    user_id VARCHAR(64) NOT NULL,
    title VARCHAR(255),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_user_id (user_id)
);

-- 消息表
CREATE TABLE message (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    conversation_id BIGINT NOT NULL,
    role ENUM('system', 'user', 'assistant', 'tool') NOT NULL,
    content TEXT NOT NULL,
    metadata JSON,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_conversation_id (conversation_id)
);

-- 上下文元数据表
CREATE TABLE context_metadata (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    session_id VARCHAR(64) NOT NULL,
    context_summary TEXT,
    key_facts JSON,
    entities JSON,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_session_id (session_id)
);

@Service
public class ContextPersistenceService {

    private final ConversationRepository conversationRepo;
    private final MessageRepository messageRepo;
    private final RedisTemplate<String, List<Message>> redisTemplate;

    // 异步持久化（写入消息后立即返回）
    @Async
    public void persistMessage(String sessionId, Message message) {
        // 1. 更新 Redis 缓存（热数据）
        String redisKey = "context:" + sessionId;
        List<Message> cached = redisTemplate.opsForList().range(redisKey, 0, -1);
        cached.add(message);
        redisTemplate.opsForList().rightPush(redisKey, message);

        // 2. 异步写入数据库（冷数据）
        Conversation conversation = conversationRepo
            .findBySessionId(sessionId)
            .orElseGet(() -> createConversation(sessionId));

        MessageEntity entity = MessageEntity.from(message, conversation.getId());
        messageRepo.save(entity);
    }

    // 启动时恢复上下文
    public List<Message> restoreContext(String sessionId) {
        // 优先从 Redis 读取
        List<Message> cached = redisTemplate.opsForList()
            .range("context:" + sessionId, 0, -1);
        if (cached != null && !cached.isEmpty()) {
            return cached;
        }

        // Redis 没有，从数据库恢复
        return messageRepo.findBySessionIdOrderByCreatedAtAsc(sessionId)
            .stream()
            .map(MessageEntity::toMessage)
            .collect(Collectors.toList());
    }
}

@Scheduled(fixedRate = 86400000) // 每天执行
public void cleanExpiredContexts() {
    // 清理超过 30 天的会话
    LocalDateTime threshold = LocalDateTime.now().minusDays(30);
    List<Conversation> expired = conversationRepo
        .findByUpdatedAtBefore(threshold);

    for (Conversation conv : expired) {
        // 删除消息和会话
        messageRepo.deleteByConversationId(conv.getId());
        conversationRepo.delete(conv);

        // 清理 Redis 缓存
        redisTemplate.delete("context:" + conv.getSessionId());
    }
}

// 直接将所有历史消息拼接
List<Message> messages = new ArrayList<>();
messages.add(new SystemMessage("你是一个助手"));
messages.addAll(conversationHistory); // 所有历史
messages.add(new UserMessage(currentInput));

ChatResponse response = llm.chat(messages);

// 旧对话压缩为摘要 + 最近 N 轮完整保留
List<Message> buildContext(List<Message> history,
        Message current, int keepLastN) {
    List<Message> context = new ArrayList<>();

    // 系统提示
    context.add(new SystemMessage("你是一个助手"));

    // 历史摘要
    if (history.size() > keepLastN) {
        String summary = summarizeHistory(
            history.subList(0, history.size() - keepLastN)
        );
        context.add(new SystemMessage("历史摘要：" + summary));
    }

    // 最近对话
    int start = Math.max(0, history.size() - keepLastN);
    context.addAll(history.subList(start, history.size()));

    // 当前消息
    context.add(current);
    return context;
}

// 从历史中提取关键信息，结构化注入
Map<String, Object> extractedContext = extractKeyInfo(history);

String enhancedPrompt = """
    基于以下上下文信息回答问题：
    用户偏好：%s
    之前的决策：%s
    关键数据：%s

    当前问题：%s
    """.formatted(
        extractedContext.get("preferences"),
        extractedContext.get("decisions"),
        extractedContext.get("key_data"),
        currentInput
    );

public class WindowManager {

    private static final int MAX_TOKENS = 4000;
    private static final int SUMMARY_THRESHOLD = 3000;

    public List<Message> manageWindow(List<Message> messages) {
        int currentTokens = countTokens(messages);

        if (currentTokens <= MAX_TOKENS) {
            return messages; // 直接返回
        }

        // 超过阈值，触发压缩
        List<Message> result = new ArrayList<>();
        result.add(messages.get(0)); // 保留 System Prompt

        // 计算需要压缩多少
        int keepTokens = MAX_TOKENS - countTokens(
            messages.get(0),
            messages.get(messages.size() - 1)
        );

        // 保留最近的消息，压缩中间的
        List<Message> toCompress = new ArrayList<>();
        List<Message> toKeep = new ArrayList<>();

        int midPoint = findSplitPoint(messages, keepTokens);
        toCompress.addAll(messages.subList(1, midPoint));
        toKeep.addAll(messages.subList(midPoint, messages.size()));

        // 压缩 + 拼接
        result.add(new SystemMessage("历史摘要：" + summarize(toCompress)));
        result.addAll(toKeep);
        return result;
    }
}

public class PromptTemplate {
    private String id;
    private String name;
    private String template;          // Prompt 模板
    private String scenario;         // 适用场景描述
    private List<String> tags;       // 分类标签
    private Map<String, Object> metadata; // 元数据
    private double avgScore;         // 平均效果分
    private int usageCount;          // 使用次数
    private String version;          // 版本号
    private List<String> versions;   // 历史版本 ID
    private float[] embedding;       // 向量嵌入（用于相似度计算）
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

@Service
public class PromptRegistry {

    private final Map<String, PromptTemplate> prompts = new ConcurrentHashMap<>();
    private final VectorStore vectorStore;
    private final EmbeddingService embeddingService;

    // 注册新 Prompt
    public String register(PromptTemplate template) {
        // 1. 检测相似度
        float[] embedding = embeddingService.embed(template.getTemplate());
        List<SimilarPrompt> similar = findSimilar(embedding, 0.85f);

        if (!similar.isEmpty()) {
            // 相似度超过阈值，提示复用
            template.setSimilarPrompts(
                similar.stream().map(SimilarPrompt::getId).toList()
            );
        }

        // 2. 生成 ID 并存储
        String id = generateId(template.getName());
        template.setId(id);
        template.setEmbedding(embedding);
        prompts.put(id, template);

        // 3. 存入向量索引
        vectorStore.upsert(id, embedding, template.getMetadata());

        return id;
    }

    // 相似度检测
    public List<SimilarPrompt> findSimilar(float[] embedding, double threshold) {
        return vectorStore.search(embedding, 10).stream()
            .filter(result -> result.getScore() > threshold)
            .map(result -> new SimilarPrompt(
                result.getId(),
                result.getScore()
            ))
            .collect(Collectors.toList());
    }

    // 按场景/标签检索
    public List<PromptTemplate> findByScenario(String scenario) {
        return prompts.values().stream()
            .filter(p -> p.getScenario().contains(scenario)
                || p.getTags().contains(scenario))
            .sorted(Comparator.comparingInt(PromptTemplate::getUsageCount).reversed())
            .collect(Collectors.toList());
    }
}

新 Prompt 提交
    ↓
计算 Embedding
    ↓
与已有 Prompt 比对相似度
    ↓
┌─────────────────────────────┐
│ 相似度 < 阈值 (0.7)         │
│ → 注册为新 Prompt            │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│ 0.7 ≤ 相似度 < 0.9          │
│ → 标记为相似，人工审核       │
│ → 可作为已有 Prompt 的新版本 │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│ 相似度 ≥ 0.9                │
│ → 拒绝注册，建议复用         │
│ → 自动关联到已有 Prompt      │
└─────────────────────────────┘

public class PromptVersionManager {

    // 创建新版本
    public String createVersion(String promptId, String newTemplate) {
        PromptTemplate original = registry.get(promptId);

        // 保存旧版本
        String oldVersionId = promptId + "-v" + original.getVersion();
        registry.registerVersion(oldVersionId, original);

        // 更新为新版本
        original.setTemplate(newTemplate);
        original.setVersion(incrementVersion(original.getVersion()));
        original.getVersions().add(oldVersionId);
        registry.update(original);

        return original.getId();
    }

    // 获取指定版本
    public PromptTemplate getVersion(String versionId) {
        return registry.get(versionId);
    }
}

Step 1: 确定数据规模
    ├── < 100万 → FAISS / pgvector（嵌入式）
    ├── 100万 ~ 1000万 → Qdrant / Weaviate
    └── > 1000万 → Milvus / Weaviate 集群
    ↓
Step 2: 确定部署需求
    ├── 不想运维 → Pinecone（全托管）
    ├── 需要私有化 → Milvus / Qdrant / Weaviate
    └── 嵌入式 → FAISS / pgvector
    ↓
Step 3: 确定检索特性
    ├── 纯语义检索 → 所有产品都支持
    ├── 混合检索（关键词+语义）→ Weaviate / Milvus
    ├── 元数据过滤 → Weaviate / Qdrant / Milvus
    └── 多模态 → Weaviate / Pinecone
    ↓
Step 4: 确定性能要求
    ├── 高 QPS + 低延迟 → Qdrant / Milvus
    ├── 平衡型 → Weaviate / Pinecone
    └── 研究/学习 → FAISS

// HNSW 核心参数
HNSWConfig config = HNSWConfig.builder()
    .setM(16)              // 每层最大连接数，越大召回越高
    .setEfConstruction(200) // 构建时搜索宽度
    .setEfSearch(50)        // 查询时搜索宽度，越大召回越高但越慢
    .build();

// 调优策略：
// 追求速度 → M=8, efSearch=16
// 平衡型 → M=16, efSearch=50
// 追求召回 → M=32, efSearch=100

// IVF 核心参数
IVFConfig config = IVFConfig.builder()
    .setNlist(256)   // 聚类中心数，越大分片越多、查询越快
    .setNprobe(16)   // 查询时搜索的聚类数，越大召回越高但越慢
    .build();

// 调优策略：
// 速度优先 → nlist=1024, nprobe=4
// 平衡型 → nlist=256, nprobe=16
// 召回优先 → nlist=256, nprobe=64

public class OptimizedSearchService {

    // 1. 向量预归一化
    public float[] normalizeVector(float[] vector) {
        float norm = 0;
        for (float v : vector) norm += v * v;
        norm = (float) Math.sqrt(norm);
        if (norm > 0) {
            for (int i = 0; i < vector.length; i++) {
                vector[i] /= norm;
            }
        }
        return vector;
    }

    // 2. 批量并行查询
    public List<SearchResult> batchSearch(List<float[]> queries) {
        return queries.parallelStream()
            .map(q -> vectorStore.search(normalizeVector(q), topK))
            .flatMap(List::stream)
            .collect(Collectors.toList());
    }

    // 3. 限制候选集 + 重排序
    public List<SearchResult> searchWithRerank(float[] query,
            int candidateSize, int finalTopK) {
        // 第一阶段：粗召回（大候选集）
        List<SearchResult> candidates = vectorStore.search(query, candidateSize);

        // 第二阶段：精排（重排序）
        return reranker.rerank(query, candidates, finalTopK);
    }
}

public class LayeredCache {

    private final Cache l1Cache;  // 内存缓存（Caffeine）
    private final RedisTemplate<String, List<SearchResult>> l2Cache;

    public List<SearchResult> search(float[] query, String cacheKey) {
        // L1: 内存缓存
        List<SearchResult> cached = l1Cache.get(cacheKey);
        if (cached != null) return cached;

        // L2: Redis 缓存
        cached = l2Cache.opsForValue().get(cacheKey);
        if (cached != null) {
            l1Cache.put(cacheKey, cached);
            return cached;
        }

        // L3: 向量数据库查询
        List<SearchResult> result = vectorStore.search(query, 100);

        // 写入缓存
        l1Cache.put(cacheKey, result);
        l2Cache.opsForValue().set(cacheKey, result, 30, TimeUnit.MINUTES);

        return result;
    }
}

客户端                协调节点               分片1          分片2          分片3
  │                    │                    │              │              │
  │── 1.Query ────────→│                    │              │              │
  │                    │                    │              │              │
  │                    │── 2.DFS(查询广播) ──→│              │              │
  │                    │                    │              │              │
  │                    │    ┌───────────────┴──────────────┘              │
  │                    │    │                                              │
  │                    │    ↓                                              │
  │                    │── 2.DFS(查询广播) ───────────────────────────────→│
  │                    │                    │              │              │
  │                    │                    │              │←── 3.局部TopN ──│
  │                    │                    │←── 3.局部TopN ──│              │
  │                    │←── 3.局部TopN ────│              │              │
  │                    │                    │              │              │
  │                    │    ┌───────────────┴──────────────┐              │
  │                    │    │                                              │
  │                    │    ↓                                              │
  │                    │── 4.Merge(全局排序取Top100)                       │
  │                    │                    │              │              │
  │                    │── 5.Fetch(按需拉取详情) ──────────────────────→│
  │                    │                    │              │              │
  │                    │←── 5.Fetch(按需拉取详情) ───────────────────────│
  │                    │                    │              │              │
  │←── 6.Return ───────│                    │              │              │
  │                    │                    │              │              │

每个分片执行：
1. 本地计算 BM25 评分
2. 取本地 Top N（默认 10 条）
3. 返回：文档 ID + 评分 + 全局统计（词频、文档数）

协调节点汇总：
1. 合并所有分片的 Top N 候选
2. 计算全局 BM25 评分（使用全局统计值）
3. 按全局评分排序，取 Top 100 的文档 ID 列表

协调节点：
1. 根据 Top 100 文档 ID 列表，确定每个文档所在分片
2. 并行发送 Fetch 请求到对应分片
3. 分片返回完整文档数据
4. 协调节点汇总返回给客户端

// 优化前：固定 500 字符切分
public List<Chunk> fixedChunk(String text) {
    return splitByFixedSize(text, 500);
}

// 优化后：语义切分 + 50% 重叠
public List<Chunk> semanticChunk(String text) {
    List<Chunk> chunks = new ArrayList<>();
    List<String> sentences = splitIntoSentences(text);

    StringBuilder currentChunk = new StringBuilder();
    int overlapSize = 0;

    for (int i = 0; i < sentences.size(); i++) {
        String sentence = sentences.get(i);
        currentChunk.append(sentence);

        // 达到目标大小或遇到语义边界
        if (currentChunk.length() >= TARGET_SIZE
                || isSemanticBoundary(sentence)) {
            chunks.add(new Chunk(currentChunk.toString(), i));

            // 50% 重叠：保留最后几句
            overlapSize = Math.max(3, sentences.size() / 10);
            currentChunk = new StringBuilder();
            for (int j = i - overlapSize + 1; j <= i; j++) {
                currentChunk.append(sentences.get(j));
            }
        }
    }
    return chunks;
}

public class HybridRetriever {

    private final BM25Retriever bm25Retriever;
    private final VectorRetriever vectorRetriever;
    private final Reranker reranker;

    public List<Document> retrieve(String query, int topK) {
        // 1. BM25 关键词检索（取 topK*2）
        List<Document> keywordResults = bm25Retriever.search(query, topK * 2);

        // 2. 向量语义检索（取 topK*2）
        List<Document> semanticResults = vectorRetriever.search(query, topK * 2);

        // 3. 融合去重（RRF 算法）
        List<Document> fused = rrfFusion(
            keywordResults, semanticResults, 60
        );

        // 4. 重排序（Cross-Encoder 精排）
        return reranker.rerank(query, fused, topK);
    }

    // Reciprocal Rank Fusion
    private List<Document> rrfFusion(List<Document> list1,
            List<Document> list2, int k) {
        Map<String, Double> scores = new HashMap<>();

        for (int i = 0; i < list1.size(); i++) {
            scores.merge(list1.get(i).getId(),
                1.0 / (k + i + 1), Double::sum);
        }
        for (int i = 0; i < list2.size(); i++) {
            scores.merge(list2.get(i).getId(),
                1.0 / (k + i + 1), Double::sum);
        }

        return scores.entrySet().stream()
            .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
            .map(e -> getDocumentById(e.getKey()))
            .collect(Collectors.toList());
    }
}

public class QueryExpander {

    private final LlmService llmService;
    private final ThesaurusService thesaurusService;

    public String expand(String originalQuery) {
        // 1. 同义词扩展
        List<String> synonyms = thesaurusService.getSynonyms(originalQuery);

        // 2. LLM 生成子问题
        String subQuestions = llmService.generate(
            "将以下问题分解为 3-5 个子问题：\n" + originalQuery
        );

        // 3. 组合扩展
        return String.join(" OR ",
            Stream.concat(
                Stream.of(originalQuery),
                synonyms.stream(),
                Stream.of(subQuestions.split("\n"))
            ).collect(Collectors.toList())
        );
    }
}

public class EvaluationPipeline {

    // 构建标注数据集
    private static final List<QueryLabel> GROUND_TRUTH = loadLabels(
        "evaluation_dataset.json"  // 2000 条标注数据
    );

    public EvaluationResult evaluate() {
        int correctTop1 = 0, correctTop5 = 0, correctTop10 = 0;

        for (QueryLabel item : GROUND_TRUTH) {
            List<Document> results = retriever.retrieve(item.getQuery(), 10);
            Set<String> retrievedIds = results.stream()
                .map(Document::getId).collect(Collectors.toSet());

            if (results.get(0).getId().equals(item.getRelevantId())) {
                correctTop1++;
            }
            if (retrievedIds.contains(item.getRelevantId())) {
                correctTop5++;
            }
        }

        return EvaluationResult.builder()
            .top1Recall((double) correctTop1 / GROUND_TRUTH.size())
            .top5Recall((double) correctTop5 / GROUND_TRUTH.size())
            .top10Recall((double) correctTop10 / GROUND_TRUTH.size())
            .build();
    }
}

public enum ToolErrorType {
    // 可重试错误
    NETWORK_TIMEOUT("网络超时", true),
    CONNECTION_RESET("连接重置", true),
    RATE_LIMIT("限流", true),
    TEMPORARY_UNAVAILABLE("服务暂时不可用", true),

    // 不可重试错误
    INVALID_PARAMS("参数错误", false),
    PERMISSION_DENIED("权限不足", false),
    BUSINESS_RULE("业务规则不满足", false),
    RESOURCE_NOT_FOUND("资源不存在", false),
    UNKNOWN("未知错误", false);

    private final String message;
    private final boolean retryable;
}

@Service
public class ToolCallExecutor {

    private static final int MAX_RETRIES = 3;
    private static final long INITIAL_BACKOFF_MS = 100;

    private final Map<String, Tool> toolRegistry;
    private final ErrorReporter errorReporter;

    public ToolResult executeWithFallback(ToolCall call) {
        Tool tool = toolRegistry.get(call.getToolName());

        // 1. 主工具尝试
        ExecutionResult result = executeWithRetry(tool, call);
        if (result.isSuccess()) {
            return result.toToolResult();
        }

        // 2. 降级工具尝试
        Tool fallbackTool = tool.getFallback();
        if (fallbackTool != null) {
            ExecutionResult fallbackResult = executeWithRetry(fallbackTool, call);
            if (fallbackResult.isSuccess()) {
                return fallbackResult.toToolResult();
            }
        }

        // 3. 保底方案：返回自然语言提示
        String friendlyMessage = buildFallbackMessage(result.getError());
        errorReporter.report(call, result);
        return ToolResult.failure(friendlyMessage);
    }

    private ExecutionResult executeWithRetry(Tool tool, ToolCall call) {
        int attempts = 0;
        long backoffMs = INITIAL_BACKOFF_MS;

        while (attempts < MAX_RETRIES) {
            try {
                return tool.execute(call.getParams());
            } catch (Exception e) {
                attempts++;
                ToolErrorType errorType = classifyError(e);

                if (!errorType.isRetryable() || attempts >= MAX_RETRIES) {
                    return ExecutionResult.failure(errorType, e);
                }

                // 指数退避
                sleep(backoffMs);
                backoffMs *= 2;
            }
        }
        return ExecutionResult.failure(ToolErrorType.UNKNOWN,
            new RuntimeException("Max retries exceeded"));
    }

    private String buildFallbackMessage(ExecutionError error) {
        return switch (error.getType()) {
            case NETWORK_TIMEOUT -> "抱歉，操作暂时超时，请稍后重试或尝试其他方式";
            case INVALID_PARAMS -> "参数可能有误，请确认后重试";
            case PERMISSION_DENIED -> "权限不足，无法执行此操作";
            case BUSINESS_RULE -> "操作不符合业务规则";
            default -> "操作失败，请稍后重试";
        };
    }
}

工具调用失败
    ↓
┌─────────────────────────────┐
│ Layer 1: Agent 决策层        │
│ - 正确选择了工具？            │
│ - 正确理解了用户意图？        │
│ → 查看 tool_selection 日志   │
└─────────────┬───────────────┘
              ↓
       意图识别正确？
        ↙          ↘
      Yes            No
      ↓               ↓
┌─────────────────────────────┐
│ Layer 2: 参数生成层          │
│ - 参数是否符合 Schema？      │
│ - 是否有缺失/类型错误？      │
│ → 查看 param_validation 日志 │
└─────────────┬───────────────┘
              ↓
       参数生成正确？
        ↙          ↘
      Yes            No
      ↓               ↓
┌─────────────────────────────┐
│ Layer 3: 工具执行层          │
│ - 业务逻辑是否正常？        │
│ - 外部依赖是否可用？        │
│ → 查看 tool_execution 日志   │
└─────────────┬───────────────┘
              ↓
       工具执行成功？
        ↙          ↘
      Yes            No
      ↓               ↓
┌─────────────────────────────┐
│ Layer 4: 基础设施层          │
│ - 网络是否正常？            │
│ - 服务发现是否正常？        │
│ - 配置是否正确？            │
└─────────────────────────────┘

@Service
public class ToolCallTracer {

    private final TraceRepository traceRepo;

    public void traceToolCall(ToolCallContext context) {
        Trace trace = Trace.builder()
            .traceId(UUID.randomUUID().toString())
            .sessionId(context.getSessionId())
            .userId(context.getUserId())
            .toolName(context.getToolName())
            .intent(context.getRecognizedIntent())
            .params(context.getParams())
            .selectionConfidence(context.getSelectionConfidence())
            .status(context.getStatus())
            .errorMessage(context.getErrorMessage())
            .errorType(classifyError(context))
            .timestamp(LocalDateTime.now())
            .build();

        traceRepo.save(trace);
    }

    // 错误分类器
    private String classifyError(ToolCallContext context) {
        if (!context.isToolSelected()) {
            return "INTENT_MISRECOGNITION";  // 意图识别错误
        }
        if (!context.isParamValid()) {
            return "PARAMETER_ERROR";        // 入参错误
        }
        if (!context.isToolHealthy()) {
            return "TOOL_UNAVAILABLE";       // 工具掉线
        }
        if (!context.isBusinessLogicOk()) {
            return "BUSINESS_LOGIC_ERROR";   // 业务逻辑错误
        }
        return "UNKNOWN";
    }
}

@RestController
@RequestMapping("/api/trace")
public class TraceController {

    private final ToolCallTracer tracer;

    // 按 Trace ID 查询完整链路
    @GetMapping("/{traceId}")
    public TraceDetail getTrace(@PathVariable String traceId) {
        return tracer.getFullTrace(traceId);
    }

    // 按 Session 查询所有调用
    @GetMapping("/session/{sessionId}")
    public List<Trace> getSessionTraces(
            @PathVariable String sessionId,
            @RequestParam(required = false) String errorType) {
        return tracer.getBySession(sessionId, errorType);
    }

    // 统计分析
    @GetMapping("/stats")
    public TraceStats getStats(
            @RequestParam LocalDateTime from,
            @RequestParam LocalDateTime to) {
        return tracer.getErrorStats(from, to);
    }
}

// LangSmith 集成（LangChain 项目）
@Configuration
public class LangSmithConfig {

    @Bean
    public Runnable langSmithTracer() {
        return LangSmithTracer.builder()
            .projectName("my-agent-project")
            .apiKey(apiKey)
            .build();
    }

    // 自动追踪 Agent 执行
    @Bean
    public Agent tracedAgent(ChatModel model, List<Tool> tools) {
        return Agent.builder()
            .model(model)
            .tools(tools)
            .tracer(langSmithTracer())
            .build();
    }
}

// Langfuse 集成（框架无关）
@Configuration
public class LangfuseConfig {

    @Bean
    public LangfuseClient langfuseClient() {
        return Langfuse.builder()
            .publicKey(publicKey)
            .secretKey(secretKey)
            .host("https://cloud.langfuse.com")  // 自托管地址
            .build();
    }

    // 手动追踪任意 LLM 调用
    public String traceAgentExecution(TraceContext context) {
        return langfuseClient.trace(
            Trace.builder()
                .name("agent-execution")
                .sessionId(context.getSessionId())
                .userId(context.getUserId())
                .input(context.getInput())
                .build()
        ).getId();
    }

    // 记录 LLM 调用详情
    public void recordLlmCall(String traceId, LlmCall call) {
        langfuseClient.generation(
            Generation.builder()
                .traceId(traceId)
                .model(call.getModel())
                .prompt(call.getPrompt())
                .completion(call.getResponse())
                .cost(call.getCost())
                .latency(call.getLatency())
                .build()
        );
    }
}

技术栈判断
    ↓
┌─────────────────────────┐
│ 使用 LangChain/LlamaIndex│
│ → LangSmith（深度集成）  │
└───────────┬─────────────┘
            ↓
┌─────────────────────────┐
│ 非 LangChain 技术栈      │
├─────────────────────────┤
│ 数据需要自托管？         │
│ → Yes: Langfuse（开源）  │
│ → No: LangSmith / Langfuse│
└───────────┬─────────────┘
            ↓
┌─────────────────────────┐
│ 需要 Playground 调试？   │
│ → Yes: LangSmith        │
│ → No: Langfuse / 其他   │
└─────────────────────────┘

用户请求
    ↓
┌─────────────────────────────┐
│ 主工具调用                    │
│ （自动重试 2-3 次）           │
└─────────────┬───────────────┘
              ↓ 失败
┌─────────────────────────────┐
│ Level 1: 同类型替代工具       │
│ MySQL → PostgreSQL           │
│ Redis 主 → Redis 从          │
│ 搜索 API A → 搜索 API B      │
└─────────────┬───────────────┘
              ↓ 失败
┌─────────────────────────────┐
│ Level 2: 能力降级            │
│ 完整报告 → 摘要报告           │
│ 实时数据 → 缓存数据           │
│ 完整功能 → 基础功能           │
└─────────────┬───────────────┘
              ↓ 失败
┌─────────────────────────────┐
│ Level 3: 人工介入            │
│ → 返回友好错误信息            │
│ → 建议用户操作               │
│ → 创建工单通知运维           │
└─────────────────────────────┘

@Service
public class GuaranteedToolExecutor {

    private final CircuitBreaker circuitBreaker;
    private final AlertService alertService;

    public ToolResult execute(ToolCall call) {
        String toolName = call.getToolName();

        // 检查熔断状态
        if (circuitBreaker.isOpen(toolName)) {
            return executeFallback(call);
        }

        // Level 0: 主工具 + 重试
        ToolResult result = executeWithRetry(call);
        if (result.isSuccess()) return result;

        // Level 1: 替代工具
        ToolResult alternative = tryAlternativeTool(call);
        if (alternative.isSuccess()) {
            logFallback(call, "alternative_tool");
            return alternative;
        }

        // Level 2: 能力降级
        ToolResult degraded = tryDegradedCapability(call);
        if (degraded.isSuccess()) {
            logFallback(call, "degraded_capability");
            return degraded;
        }

        // Level 3: 人工介入
        circuitBreaker.recordFailure(toolName);
        alertService.createTicket(call, result.getError());
        return buildHumanInterventionResult(call);
    }

    // 替代工具映射
    private ToolResult tryAlternativeTool(ToolCall call) {
        Map<String, String> alternatives = Map.of(
            "mysql_query", "postgresql_query",
            "redis_get", "redis_get_replica",
            "search_web", "search_web_backup"
        );
        String altTool = alternatives.get(call.getToolName());
        if (altTool != null) {
            return executeWithRetry(call.toBuilder().toolName(altTool).build());
        }
        return ToolResult.failure("No alternative tool available");
    }

    // 降级能力映射
    private ToolResult tryDegradedCapability(ToolCall call) {
        Map<String, DegradedAction> degradedMap = Map.of(
            "generate_report", new DegradedAction("generate_summary",
                "生成简化版摘要报告"),
            "realtime_data", new DegradedAction("get_cached_data",
                "使用最近缓存的数据"),
            "full_search", new DegradedAction("basic_search",
                "使用基础搜索功能")
        );
        DegradedAction action = degradedMap.get(call.getToolName());
        if (action != null) {
            ToolResult result = executeWithRetry(
                call.toBuilder().toolName(action.getToolName()).build()
            );
            if (result.isSuccess()) {
                result.setMessage(
                    result.getMessage() + "\n（已降级：" + action.getDescription() + "）"
                );
            }
            return result;
        }
        return ToolResult.failure("No degraded capability available");
    }
}

@Component
public class CircuitBreaker {

    private final Map<String, CircuitState> states = new ConcurrentHashMap<>();
    private static final int FAILURE_THRESHOLD = 5;
    private static final long RECOVERY_TIMEOUT_MS = 60000;

    public boolean isOpen(String toolName) {
        CircuitState state = states.get(toolName);
        if (state == null) return false;

        if (state.getFailureCount() >= FAILURE_THRESHOLD) {
            long elapsed = System.currentTimeMillis() - state.getLastFailureTime();
            if (elapsed > RECOVERY_TIMEOUT_MS) {
                state.setState(CircuitState.HALF_OPEN);
                return false;
            }
            return true; // 熔断中
        }
        return false;
    }

    public void recordFailure(String toolName) {
        states.computeIfAbsent(toolName, k -> new CircuitState())
            .recordFailure();
    }

    public void recordSuccess(String toolName) {
        states.computeIfAbsent(toolName, k -> new CircuitState())
            .recordSuccess();
    }
}

模型生成参数
    ↓
┌─────────────────────────────┐
│ Layer 1: Prompt 引导         │
│ - System Prompt 说明参数格式 │
│ - Few-shot 提供正确示例     │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│ Layer 2: Schema 自动校验     │
│ - JSON Schema 定义参数规范   │
│ - Function Calling 自动校验  │
│ → 类型错误/必填缺失直接拦截  │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│ Layer 3: 业务规则校验        │
│ - 值域检查（min/max）       │
│ - 格式检查（正则）          │
│ - 业务约束（交叉校验）      │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│ Layer 4: 安全校验            │
│ - SQL 注入防护              │
│ - 权限检查                  │
│ - 数据合法性                │
└─────────────────────────────┘

// 在 System Prompt 中明确参数格式要求
String systemPrompt = """
    你是一个客服助手。调用工具时必须严格遵守参数格式：

    工具名：query_order
    参数：
    - order_id (string, 必填): 订单号，格式为ORD+10位数字
    - date_range (object, 可选):
        - start_date (string): YYYY-MM-DD
        - end_date (string): YYYY-MM-DD

    示例：
    正确：{"order_id": "ORD1234567890"}
    错误：{"order_id": "123"}  // 缺少ORD前缀
    """;

public class ToolSchemaValidator {

    private final JsonSchemaFactory schemaFactory;

    public ValidationResult validate(String toolName,
            Map<String, Object> params) {
        JsonNode schema = loadSchema(toolName);
        JsonNode paramsNode = objectMapper.valueToTree(params);

        Set<ValidationMessage> errors = schema.validate(paramsNode);

        if (errors.isEmpty()) {
            return ValidationResult.valid();
        }
        return ValidationResult.invalid(
            errors.stream()
                .map(ValidationMessage::getMessage)
                .collect(Collectors.toList())
        );
    }

    private JsonNode loadSchema(String toolName) {
        String schemaJson = toolSchemaRegistry.get(toolName);
        return objectMapper.readTree(schemaJson);
    }
}

public class BusinessRuleValidator {

    public List<String> validate(String toolName,
            Map<String, Object> params) {
        List<String> errors = new ArrayList<>();

        switch (toolName) {
            case "query_order":
                validateOrderId(params.get("order_id"), errors);
                validateDateRange(params.get("date_range"), errors);
                break;
            case "transfer_money":
                validateAmount(params.get("amount"), errors);
                validateAccount(params.get("account"), errors);
                break;
            // ... 其他工具
        }
        return errors;
    }

    private void validateOrderId(Object orderId, List<String> errors) {
        if (orderId == null) {
            errors.add("order_id 是必填项");
            return;
        }
        if (!orderId.toString().matches("ORD\\d{10}")) {
            errors.add("order_id 格式错误，应为ORD+10位数字");
        }
    }

    private void validateAmount(Object amount, List<String> errors) {
        if (amount == null || new BigDecimal(amount.toString()).compareTo(BigDecimal.ZERO) <= 0) {
            errors.add("amount 必须大于 0");
        }
        if (new BigDecimal(amount.toString()).compareTo(new BigDecimal("1000000")) > 0) {
            errors.add("单次转账金额不能超过100万");
        }
    }
}

public class SecurityValidator {

    public void validate(Map<String, Object> params, String userId) {
        // SQL 注入防护
        for (Map.Entry<String, Object> entry : params.entrySet()) {
            if (entry.getValue() instanceof String value) {
                if (containsSqlInjection(value)) {
                    throw new SecurityException("检测到潜在的 SQL 注入风险");
                }
            }
        }

        // 权限检查
        if (!hasPermission(userId, params)) {
            throw new SecurityException("无权限执行此操作");
        }
    }

    private boolean containsSqlInjection(String input) {
        String[] patterns = {
            "(?i)(\\b(SELECT|INSERT|UPDATE|DELETE|DROP)\\b)",
            "(?i)(--|;|\\/\\*)",
            "(?i)(\\b(OR|AND)\\b.*\\b(TRUE|FALSE)\\b)"
        };
        for (String pattern : patterns) {
            if (input.matches(pattern)) return true;
        }
        return false;
    }
}

日常编码
    ↓
GitHub Copilot → 实时补全（Tab 接受）
    ↓
遇到新 API/框架
    ↓
Claude/ChatGPT → 询问用法、看示例
    ↓
需要重构/跨文件修改
    ↓
Cursor → 选中代码，描述需求，自动修改
    ↓
需要批量修改
    ↓
Aider → 命令行批量替换
    ↓
代码完成
    ↓
TestGPT → 自动生成测试
CodeRabbit → 自动 Review

场景：从 0 到 1 开发一个 Spring Boot 接口

Step 1: 创建 Controller 类
    → Copilot: 输入 @RestController 后自动生成模板
    → 输入方法签名 + 注释，Tab 生成方法体

Step 2: 实现 Service 层
    → Copilot: 接口定义后自动生成实现类骨架
    → 复杂逻辑：描述意图，Copilot 生成初版

Step 3: 需要重构（如将同步改异步）
    → Cursor: 选中整个 Service 类
    → 描述："将所有方法改为 CompletableFuture 异步返回"
    → Cursor 自动修改相关代码

Step 4: 不确定某个 API 用法
    → Claude: "Spring 的 @Async 注解怎么用？线程池怎么配置？"
    → 获取方案后回到 IDE 实现

Step 5: 生成单元测试
    → TestGPT: 选中 Service 类 → 生成测试
    → 手动补充 Mock 数据和边界用例

Step 6: Code Review
    → CodeRabbit: 提交 PR → 自动 Review
    → 根据建议修改代码

Step 1: 需求理解
    ├── 明确功能边界
    ├── 定义输入输出
    └── 识别约束条件
    ↓
Step 2: 方案设计
    ├── 选择技术栈
    ├── 设计模块架构
    ├── 定义接口契约
    └── 数据模型设计
    ↓
Step 3: 代码生成（按模块）
    ├── 3.1 基础设施层（配置、工具类）
    ├── 3.2 数据层（Entity、Repository）
    ├── 3.3 业务层（Service、DTO）
    ├── 3.4 接口层（Controller、API）
    └── 3.5 横切关注点（日志、异常、安全）
    ↓
Step 4: 代码审查
    ├── AI 自动审查（CodeRabbit）
    ├── 人工审查（代码规范、业务逻辑）
    └── 安全审查（注入、越权等）
    ↓
Step 5: 测试验证
    ├── 单元测试（TestGPT 生成 + 补充）
    ├── 集成测试
    └── 运行验证
    ↓
Step 6: 迭代优化
    ├── Bug 修复
    ├── 性能优化
    └── 代码重构

// 需求拆解示例：开发一个电商订单系统
//
// Epic: 订单管理系统
//   ├── Story 1: 创建订单
//   │   ├── Task 1.1: 定义 Order 数据模型
//   │   ├── Task 1.2: 实现 OrderRepository
//   │   ├── Task 1.3: 实现 OrderService.createOrder()
//   │   └── Task 1.4: 实现 OrderController.POST /orders
//   ├── Story 2: 查询订单
//   │   ├── Task 2.1: 实现 OrderService.queryOrder()
//   │   └── Task 2.2: 实现 OrderController.GET /orders/{id}
//   ├── Story 3: 支付订单
//   │   ├── Task 3.1: 集成支付网关
//   │   └── Task 3.2: 实现支付回调处理
//   └── Story 4: 取消订单
//       └── Task 4.1: 实现取消逻辑和状态流转

public class ProjectContextManager {

    // 项目级上下文：确保各模块一致性
    private String projectContext;

    public String buildProjectContext() {
        return """
            项目：电商订单系统
            技术栈：Spring Boot 3 + JPA + Redis
            规范：
            - Controller → Service → Repository 分层
            - DTO/Entity 分离
            - 统一异常处理
            - RESTful API 设计
            - 统一响应封装
            """;
    }

    // 每个模块生成时注入项目上下文
    public String generateWithContext(String module, String requirement) {
        return projectContext + """

            现在实现模块：%s
            需求：%s
            请严格遵循项目规范生成代码。
            """.formatted(module, requirement);
    }
}

// 高质量 Prompt 约束示例
String codingPrompt = """
    请生成一个用户认证的 Service 类，要求：

    1. 代码规范：
       - 使用 Lombok 简化代码
       - 方法名驼峰，类名大驼峰
       - 异常使用自定义 BusinessException
       - 添加 Javadoc 注释

    2. 功能要求：
       - register(UserDTO): 注册用户，校验邮箱唯一
       - login(LoginDTO): 登录验证，返回 JWT
       - refreshToken(String): 刷新 Token

    3. 边界条件：
       - 邮箱格式校验
       - 密码强度校验（>=8位，含数字和字母）
       - 登录失败次数限制（5次锁定30分钟）

    4. 性能要求：
       - 密码加密使用 BCrypt
       - 敏感操作添加日志
    """;

<!-- Maven 集成 SonarQube -->
<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <configuration>
        <sonar.host.url>http://sonarqube:9000</sonar.host.url>
        <sonar.login>${SONAR_TOKEN}</sonar.login>
    </configuration>
</plugin>

// 为 AI 生成的 Service 编写测试
@Test
public void testRegisterSuccess() {
    UserDTO dto = new UserDTO();
    dto.setEmail("test@example.com");
    dto.setPassword("Pass123456");

    assertDoesNotThrow(() -> userService.register(dto));
    User savedUser = userRepository.findByEmail("test@example.com");
    assertNotNull(savedUser);
    assertNotEquals("Pass123456", savedUser.getPassword());
}

@Test
public void testRegisterDuplicateEmail() {
    // 边界条件：重复邮箱
    UserDTO dto = new UserDTO();
    dto.setEmail("existing@example.com");

    assertThrows(BusinessException.class,
        () -> userService.register(dto));
}

@Test
public void testPasswordStrength() {
    // 边界条件：弱密码
    UserDTO dto = new UserDTO();
    dto.setEmail("test@example.com");
    dto.setPassword("123"); // 不符合强度要求

    assertThrows(BusinessException.class,
        () -> userService.register(dto));
}

// 集成测试
@SpringBootTest
class UserIntegrationTest {

    @Autowired
    private WebTestClient webClient;

    @Test
    void testFullAuthFlow() {
        // 注册 → 登录 → 刷新 → 登出
        UserDTO user = new UserDTO("test@example.com", "Pass123456");

        webClient.post().uri("/api/users/register")
            .bodyValue(user)
            .exchange()
            .expectStatus().isOk();

        LoginDTO login = new LoginDTO("test@example.com", "Pass123456");
        String token = webClient.post().uri("/api/users/login")
            .bodyValue(login)
            .exchange()
            .expectStatus().isOk()
            .expectBody(LoginResponse.class)
            .returnResult().getResponseBody().getToken();

        // 验证 Token 有效性
        webClient.get().uri("/api/users/profile")
            .header("Authorization", "Bearer " + token)
            .exchange()
            .expectStatus().isOk();
    }
}

设计稿（Figma）表达的是：
- 视觉布局（相对位置、视觉层级）
- 颜色/字体/间距（设计 Tokens）
- 组件形状（圆形按钮、方形卡片）

但缺乏代码层面的精确信息：
- 响应式断点（手机/平板/桌面）
- Flex/Grid 布局方式
- 具体像素值或百分比
- 组件层级和嵌套关系

设计稿 → ??? 技术栈
    ├── React + Tailwind + shadcn/ui
    ├── Vue 3 + Element Plus
    ├── 小程序 + 原生组件
    └── Flutter + Material

需要用户指定或 AI 推断，但容易出错

设计稿元素          →  目标组件库
─────────────────────────────────
矩形按钮            →  Button（variant: primary）
输入框              →  Input（type: text）
卡片容器            →  Card + CardHeader + CardBody
列表项              →  List + ListItem
下拉菜单            →  Select / Dropdown
弹窗                →  Modal / Dialog
表单验证            →  Form + FormItem + rules

设计稿通常展示的状态：
- 默认状态（Default）
- 悬停状态（Hover）
- 选中状态（Selected）
- 禁用状态（Disabled）

但缺失的交互逻辑：
- 点击后触发什么？
- 数据从哪里加载？
- 提交后跳转到哪里？
- 表单验证规则是什么？
- 权限控制在哪里？

生成的代码需要适配：
- 项目目录结构（src/components、src/pages）
- 路由配置（React Router、Vue Router）
- 状态管理（Redux、Pinia、Zustand）
- API 调用约定（axios 封装、React Query）
- 代码规范（ESLint、Prettier、Husky）
- 国际化支持（i18n）

设计稿（Figma）
    ↓
Step 1: 导出设计 Tokens
    → 颜色、字体、间距、圆角
    → 生成 CSS Variables / Tailwind Config
    ↓
Step 2: 指定技术栈
    → 用户选择 React/Vue/小程序
    → 指定 UI 组件库（shadcn/ui、Element Plus）
    ↓
Step 3: AI 生成骨架代码
    → 识别组件结构
    → 生成组件骨架和样式
    → 映射到指定组件库
    ↓
Step 4: 人工补充交互
    → 添加事件处理
    → 实现数据绑定
    → 配置路由
    → 添加状态管理
    ↓
Step 5: 工程化调整
    → 移动到正确目录
    → 统一代码规范
    → 集成到项目结构