CH 07工具调用（Tool Calling）

7.1工具调用的本质：模型只会「举手」，不会「动手」

先用一个比喻理解：模型像一位坐在办公室里的顾问，他知道很多东西，但不能出门。当需要查实时数据时，他会写一张便条（工具名 + 参数）递给你，你跑出去把事情办完，把结果写回来给他，他再基于结果给你最终答复。

为什么这么写（设计意图）：这个比喻不是修辞，而是对 Spring AI 工具调用架构的精确描述。模型的输出里只含「我要调用某个工具、参数是这些」，真正的执行发生在你的 Java 代码里。理解这一点，后面所有的权限、异常处理、成本控制才站得住脚。很多初学者把模型当成「安全边界」，根源就是没建立这个心智模型。

7.2完整时序：为什么一次问答会有两次模型调用

下面这张图描述一次「订单发货时间」问答在 Spring AI 2.0 内部的完整流转。注意：对调用方（你的 Controller）而言只写了一次 .call()，但底层发生了多次模型请求。

▌动手补充：模型返回的 tool_calls 到底长什么样

上面图里第 ① 步说「模型返回：我要调工具」。它返回的其实是一段结构化 JSON（不是自然语言）。看清它，你才能真正理解「模型只举手、不动手」：

# 第 ① 步：模型不直接回答，而是返回 tool_calls（注意 content 是 null）
{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "queryOrderStatus",
        "arguments": "{\"orderNo\":\"2024001\"}"
      }
    }
  ]
}

# 第 ③ 步：你的代码把工具结果包成一条 role=tool 消息回灌
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"status\":\"未发货\",\"promisedDate\":\"2024-03-08\"}"
}

▌运行验证：开启 debug 日志，亲眼看「两次模型请求」

光看文字不直观，现在就让你在日志里看到循环的存在。本章自建工程（见 7.7）跑起来后，打开 DEBUG 日志：

# 临时在 application.yml 打开 Spring AI 的 DEBUG 日志（只看工具相关足够）
logging:
  level:
    org.springframework.ai.chat.client: DEBUG

# 触发一次带工具的问答（命令见 7.7，这里先认识输出长什么样）
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 什么时候发货？"}'

期望在控制台看到（节选，顺序即循环）：

... [ToolCallingAdvisor] 第 1 次迭代：模型返回 tool_calls=[queryOrderStatus]
... [ToolCallingManager] 执行工具 queryOrderStatus(orderNo=2024001)
... [ToolCallingAdvisor] 第 2 次迭代：模型返回最终文本（无 tool_calls）

看到什么算通过：日志里出现至少两轮「模型请求」痕迹（一次返回 tool_calls、一次返回最终文本），且最终 curl 正常返回了发货说明文字，而不是报错或空串。

7.3@Tool 注解：把 Java 方法暴露给模型

把一个普通 Java 方法变成模型可用的工具，核心就是 @Tool 注解（包 org.springframework.ai.tool.annotation.Tool）。下面这个例子包含本章最重要的三个安全要点：描述怎么写、参数怎么描述、身份怎么取。

▌动手：创建 OrderTools 类

1. 在 IDEA 左侧 Project 视图，展开 src/main/java/com/example/springai。若没有 ch07 包，右键 com.example.springai → New → Package，输入 ch07 回车。
2. 右键 ch07 包 → New → Java Class，名字精确填 OrderTools，回车。
3. 清空自动生成的内容，把下方整段代码粘贴进去（含 import），按 Ctrl/Cmd+S 保存。
4. 确认 IDEA 没有红色波浪线：@Tool、@ToolParam 能从 org.springframework.ai.tool.annotation 解析到（若报红，多半是依赖或版本不对，回头对照 ch00 版本表）。

package com.example.springai.ch07;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import java.time.LocalDate;

@Component                              // 必须是 Spring bean，Spring AI 才能扫描到它
public class OrderTools {

    /**
     * 一个工具方法。三个要素决定模型能不能用好它：
     * ① 方法名     → 模型看到的工具名（尽量用动词+名词，语义清晰）
     * ② description → ★ 最重要！模型靠它决定"什么时候用这个工具、不用那个"
     * ③ 参数描述    → 模型靠它知道"这个参数从用户的话里怎么抽"
     */
    @Tool(description = """
            查询指定订单号的当前状态与预计发货时间。
            使用时机：当用户询问某个订单的发货情况、物流状态、是否已发货时调用。
            不要用于：查询商品信息、退款进度、账户余额。
            """)                          // 文本块（Java 15+），多行描述更清晰
    public OrderStatus queryOrderStatus(
            @ToolParam(description = "订单号，纯数字字符串，例如 2024001")
            String orderNo) {                 // 参数描述越具体，模型抽参越准

        // ★★★ 这里就是安全边界！绝不能相信模型传来的 orderNo 就是"当前用户的订单"
        String currentUser = SecurityContextHolder.currentUserId();  // 从服务端登录态取，不是从参数取
        if (!orderRepository.belongsTo(orderNo, currentUser)) {
            // 返回明确错误，而不是抛异常——让模型能理解并礼貌回复用户
            return new OrderStatus(orderNo, "NOT_FOUND", null,
                    "系统中不存在该订单，或该订单不属于当前用户");
        }

        Order order = orderRepository.findByNo(orderNo);
        return new OrderStatus(order.orderNo(), order.status(),
                order.promisedDate(), "查询成功");
    }

    /** 无参工具也可以（模型不需要传任何参数）。典型场景：获取"今天日期"这类模型自己不知道的信息。 */
    @Tool(description = "获取当前的日期与时间。当用户说'今天''本周''最近'等相对时间时，必须先调用此工具获取真实日期。")
    public String currentDateTime() {
        return LocalDate.now() + " " + java.time.LocalTime.now().withNano(0);
    }

    /** 工具的返回类型：建议用 record，字段名会进入模型的上下文 */
    public record OrderStatus(String orderNo, String status,
                                LocalDate promisedDate, String message) {}
}

为什么这么写：@Tool 的 description 不是给人看的注释，而是会被序列化进发给模型的「工具定义」里——模型完全靠它来决策。所以描述要写成「给模型的说明书」：做什么、何时用、何时不用、参数长什么样。返回类型用 record 是因为它的字段名天然成为 JSON 的 key，进入模型上下文后语义清晰。

写工具描述的「四要素」模板

▌运行验证：编译通过，且 @Tool 被扫描到

# 在 pom.xml 所在目录执行（只编译，不运行，最快的反馈）
mvn -q compile

期望输出：命令结束、无红色报错，最后一行应是构建成功（-q 下成功时几乎无输出）。

看到什么算通过：终端回到可输入状态且没有 BUILD FAILURE；IDEA 里 OrderTools 的 @Tool 不再报红。此时工具还没被注册到 ChatClient，所以还不能调，但「类本身是对的」这一步先钉死，避免后面问题混在一起。

7.4注册工具的三种方式

工具类（带 @Tool 的 bean）写好后，还要把它「挂到」某个 ChatClient 上，模型才能用到。注意：标题虽写「三种方式」，但生产里实际有六种粒度可选——前三种是注册入口的区别，后三种是 2.0 新增或进阶能力，都讲清楚，方便你按场景选。

▌动手：创建 AssistantConfig 装配 ChatClient

1. 右键 ch07 包 → New → Java Class，名字填 AssistantConfig。
2. 粘贴下方「方式三（默认挂载）」代码（它最贴近生产写法），保存。
3. 确认 OrderTools、DateTimeTools 能注入——即这两个类都已用 @Component 标注且被 Spring 扫描到。

// ---------- 方式一：直接传对象（最简，适合手工指定） ----------
String answer = chatClient.prompt()
        .user("订单 2024001 发货了吗？")
        .tools(new OrderTools(), new DateTimeTools())   // 传实例
        .call()
        .content();

// ---------- 方式二：用 ToolCallbacks 显式转换（可控性更强） ----------
import org.springframework.ai.support.ToolCallbacks;

ToolCallback[] callbacks = ToolCallbacks.from(new OrderTools(), new DateTimeTools());

String answer2 = chatClient.prompt()
        .user("订单 2024001 发货了吗？")
        .toolCallbacks(callbacks)
        .call()
        .content();

// ---------- 方式三：默认挂载（推荐，业务代码最干净） ----------
@Bean
public ChatClient orderChatClient(ChatModel chatModel,
                                    OrderTools orderTools,
                                    DateTimeTools dateTimeTools) {
    return ChatClient.builder(chatModel)
            // 所有通过这个 client 发起的请求都能用这些工具
            .defaultTools(orderTools, dateTimeTools)
            .defaultSystem("你是订单助手。涉及订单数据时必须调用工具查询，禁止凭记忆回答。")
            .build();
}

三种方式的选择

方式四（2.0 新增重点）：函数式工具用 FunctionToolCallback

如果你要暴露的不是一个带 @Tool 的 POJO 方法，而是一个现成的 Function、lambda 或方法引用， 2.0 用 FunctionToolCallback。这是 1.x 里 FunctionCallback + toolNames() 的替代品：

// ❌ 1.x 的写法（2.0 已删除，编译不过）
// @Bean @Description("Get the weather in location")
// Function currentWeather() { return weatherService::getWeather; }
// chatClient.prompt().toolNames("currentWeather");   ← toolNames 没了

// ✅ 2.0：注册成显式的 ToolCallback bean
@Configuration(proxyBeanMethods = false)
class WeatherToolsConfig {

    @Bean
    ToolCallback currentWeather(WeatherService weatherService) {
        return FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
                .description("查询指定城市的当前天气")
                // ★ inputType 决定生成的 JSON Schema，必须给，否则模型不知道该传什么
                .inputType(WeatherRequest.class)
                .build();
    }
}

// 注入后按名字使用（不再靠字符串解析）
@Autowired ToolCallback currentWeather;

chatClient.prompt()
        .user("北京现在天气怎么样？")
        .tools(currentWeather)      // 直接传工具对象
        .call()
        .content();

三种定义风格最终都产出 ToolCallback，走同一条循环，可以随意混用：

方式五：工具太多时，打开渐进式工具披露

这是 2.0 最实用的新能力之一。原理：不再把全部工具定义一次性塞给模型， 而是给模型一个内置的 toolSearchTool，让它用自然语言先"检索"出相关工具， 再只把这几个工具的定义发过去。

<!-- 加一个 starter 即可，不需要改任何 Java 代码 -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-tool-search-advisor</artifactId>
</dependency>

# 打开开关
spring:
  ai:
    chat:
      client:
        tool-search-advisor:
          enabled: true
          # 索引类型：
          #   regex  —— 默认，零额外依赖，按关键词匹配
          #   lucene —— 需要 org.apache.lucene:lucene-core，检索质量更好
          #   vector —— 需要 classpath 上有 VectorStore，语义检索最准
          tool-index-type: regex

方式六：给工具调用加上次数上限（防失控）

2.0 的 DefaultToolCallingManager 内置了调用次数保护，默认就已生效： 单个工具每轮最多 40 次，所有工具合计最多 150 次。超过会抛 ToolCallLimitExceededException。

# 用配置调整
spring:
  ai:
    tools:
      limits:
        max-calls-per-tool-default: 40     # -1 表示不限制
        max-total-tool-calls: 150
        on-limit-exceeded: THROW           # 或 RETURN_ERROR_RESPONSE（把错误当结果回给模型）

// 或者编程式精细控制
ToolCallingManager manager = ToolCallingManager.builder()
        .maxCallsPerTool(40)
        .maxCallsPerTool("search", 10)              // 给某个工具单独设更小的上限
        .excludeToolFromLimit("getCurrentDateTime") // 这个工具不限制
        .maxTotalToolCalls(150)
        .build();

// 装到自己的 ToolCallingAdvisor 上（会替换掉自动注册的那个）
@Bean
ToolCallingAdvisor.Builder<?> toolCallingAdvisorBuilder() {
    return ToolCallingAdvisor.builder()
            .toolCallingManager(manager)
            .advisorOrder(Ordered.HIGHEST_PRECEDENCE + 300);
}

▌运行验证：ChatClient 装配成功（编译 + 启动自检）

# 先确认编译通过（最便宜的反馈）
mvn -q compile

# 再启动，看 ChatClient bean 能不能装配起来
mvn spring-boot:run

期望启动日志（节选）：

...
2025-xx-xx INFO  ... Started SpringaiLabApplication in 3.x seconds
...

看到什么算通过：控制台出现 Started ... in X seconds 且无 APPLICATION FAILED TO START；特别地，没有出现 Consider defining a bean of type 'org.springframework.ai.chat.client.ChatClient' 这类提示。此时还没有 HTTP 接口，curl 会报连接拒绝，这是正常的——这一步只验证「装配对不对」。

7.5返回值、ToolContext 与「结果直出」

工具返回值怎么设计

工具返回什么，直接决定了模型能「看懂」多少。原则一句话：返回值是写给模型看的，不是写给数据库看的。

// ❌ 不好：返回一个复杂的内部实体，字段名模型看不懂
public OrderEntity query(String no) { return repo.find(no); }
// 返回 {"id":1,"ordNo":"2024001","sta":2,"gmtCreate":1709...}
// 模型看到 sta=2 完全不知道是什么意思

// ✅ 好：返回语义清晰的 DTO，字段名自解释，必要时附带说明文本
public record OrderStatus(
        String orderNo,          // 订单号
        String status,           // 已翻译成中文：未发货/已发货/已完成
        String promisedDate,     // 预计发货日期 yyyy-MM-dd
        String message           // 一句话说明，便于模型组织语言
) {}

ToolContext：把上下文信息传进工具（不经过模型）

ToolContext 是工具安全设计的核心机制。它让你把「不能也不应该让模型看到/控制」的信息（当前用户 ID、租户 ID、请求追踪 ID）在调用时注入，模型既看不到也无法伪造。

import org.springframework.ai.chat.model.ToolContext;

/**
     * ★★ ToolContext 是一个非常重要的机制：
     * 它允许你把「不能也不应该让模型看到/控制」的信息传给工具，
     * 例如：当前登录用户的 ID、租户 ID、请求追踪 ID。
     *
     * 这些值由你的代码在调用时注入，模型无法伪造——这是安全性的关键。
     */
    @Tool(description = "查询当前用户自己的全部订单列表")
    public List<OrderStatus> queryMyOrders(ToolContext toolContext) {
        // 从上下文取当前用户，而不是从模型的参数里取！
        String userId  = (String) toolContext.getContext().get("userId");
        String tenantId = (String) toolContext.getContext().get("tenantId");

        return orderRepository.findByUser(tenantId, userId).stream()
                .map(o -> new OrderStatus(o.orderNo(), o.status(),
                        String.valueOf(o.promisedDate()), ""))
                .toList();
    }

调用时由服务端把上下文注入进去（这一步发生在你的 Service 里，模型无感）：

String answer = chatClient.prompt()
        .user("帮我看看我有哪些订单")
        // ★ 由服务端注入，模型看不到也改不了
        .toolContext(Map.of(
                "userId", SecurityContextHolder.currentUserId(),
                "tenantId", SecurityContextHolder.currentTenantId()))
        .call()
        .content();

returnDirect：让工具结果直接返回给用户

/**
 * 有些工具的返回值本身就是最终答案，不需要模型再加工一遍。
 * 例如"导出一份明细报表"——加工反而会改动数据、增加成本。
 * returnDirect = true 时，工具结果会跳过第二次模型调用，直接返回。
 */
@Tool(description = "导出指定订单的完整明细报表（CSV 文本）", returnDirect = true)
public String exportOrderDetail(@ToolParam(description = "订单号") String orderNo) {
    return reportService.toCsv(orderNo);
}

▌运行验证：编译通过，且 ToolContext 用法自洽

mvn -q compile

看到什么算通过：编译成功，且 queryMyOrders(ToolContext) 方法签名与调用处 .toolContext(Map.of(...)) 的 key 命名一致（如都叫 userId、tenantId）。这一步还没法运行时验证 ToolContext 的取值，要等 7.7 整体跑起来后用越权用例（第 ② 步）才能证明它真的「挡住了越权」。

7.6参数校验、异常处理与安全边界

工具里的错误：返回给模型，而不是抛给用户

工具执行失败时的处理，决定了用户体验的成败。下面的代码把「参数校验 → 权限校验 → 业务兜底」三段都写成「返回结构化错误对象」而不是抛异常，这样模型能把错误翻译成人话。

/**
 * 工具执行失败时的两种处理方式，效果差别巨大：
 *
 * ❌ 抛异常 → Spring AI 会把异常信息带回给模型（或直接失败），
 *           用户看到的是"系统错误"，体验极差。
 *
 * ✅ 返回结构化的错误对象 → 模型能"读懂"错误，并组织成礼貌的话回复用户，
 *           例如："没有找到订单 2024001，请确认订单号是否正确？"
 */
@Tool(description = "查询指定订单号的当前状态与预计发货时间")
public OrderStatus queryOrderStatus(
        @ToolParam(description = "订单号，纯数字字符串，例如 2024001") String orderNo) {

    // ---------- ① 参数格式校验：模型可能传 "订单2024001" 或空值 ----------
    if (orderNo == null || !orderNo.matches("\\d{6,20}")) {
        return new OrderStatus(orderNo, "INVALID", null,
                "订单号格式不正确，应为 6~20 位数字。请向用户确认订单号后重试。");
    }

    // ---------- ② 权限校验：绝不接受模型传来的用户身份 ----------
    String userId = SecurityContextHolder.currentUserId();
    if (!orderRepository.belongsTo(orderNo, userId)) {
        // ★ 注意这里不返回"订单属于别人"——那等于泄露了"这个订单存在"的信息
        return new OrderStatus(orderNo, "NOT_FOUND", null,
                "未查询到该订单。请确认订单号是否正确。");
    }

    // ---------- ③ 业务异常兜底：把技术异常翻译成业务语言 ----------
    try {
        Order order = orderRepository.findByNo(orderNo);
        if (order == null) {
            return new OrderStatus(orderNo, "NOT_FOUND", null, "未查询到该订单。");
        }
        return new OrderStatus(order.orderNo(), order.status(),
                String.valueOf(order.promisedDate()), "");
    } catch (Exception e) {
        // 内部异常详情记日志，返回给模型的是"可读的错误说明"
        log.error("查询订单 {} 失败", orderNo, e);
        return new OrderStatus(orderNo, "ERROR", null,
                "订单系统暂时不可用，请稍后重试或转人工客服。");
    }
}

全局异常处理器：统一决定「异常要不要抛」

import org.springframework.ai.tool.execution.ToolExecutionException;
import org.springframework.ai.tool.execution.ToolExecutionExceptionProcessor;

/**
 * 只有当默认策略不满足需求时，才需要自定义。
 * 它是一个函数式接口，只有一个方法，所以可以直接写成 lambda。
 */
@Configuration
public class ToolConfig {

    @Bean
    public ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
        return exception -> {
            // exception 里带着原始异常、工具定义等信息
            log.error("工具执行失败：工具={} 原因={}",
                    exception.getToolDefinition().name(), exception.getMessage());

            // ★ 返回值会作为"工具执行结果"回给模型。
            //   所以这里的话术是"写给模型看的"，要清楚、可行动，不要甩堆栈。
            return "工具执行失败：" + exception.getMessage()
                    + "。请向用户说明该功能暂时不可用，不要重复调用此工具。";
        };
    }
}

工具的安全边界 Checklist

▌运行验证：编译通过，安全校验逻辑就位

mvn -q compile

看到什么算通过：编译成功；并且你能在代码里逐行指出：① 参数格式校验（matches("\\d{6,20}")）、② 权限校验（从 SecurityContextHolder 取身份而非参数）、③ 异常兜底（try/catch 返回错误对象）。这三条都齐，才说明「工具不会裸奔」。真正的运行时越权拦截要到 7.7 第 ② 步用 curl 证明。

7.7完整示例：订单与天气查询助手

下面把前面所有点串成一个可运行的示例：一个订单 + 天气查询助手。先看工程结构，再逐文件讲解，最后给出可复制的验证步骤。本章无配套 lab 代码，请按「自建」口径在 com.example.springai.ch07 包下依次创建这些文件。

▌动手·前置 1：确认 pom.xml 依赖（自建工程的根基）

1. 打开工程根目录的 pom.xml，确认 <parent> 指向 spring-boot-starter-parent 且版本是 4.1.x（如 4.1.1）。
2. 在 <dependencyManagement> 里引入 spring-ai-bom，版本锁 2.0.1——这是全课程版本基准的开关。
3. 在 <dependencies> 里至少加入下面三个 starter：Web（提供 @RestController）、Spring AI 的 OpenAI 模型 starter（提供 ChatModel 与工具能力）、Lombok（可选，本示例用 @Slf4j 需要）。
4. 保存后，IDEA 右下角 Maven 面板点「刷新」，等依赖下载完、无红线。

<!-- 版本基准：Boot 4.1.x + Java 17 + Spring AI 2.0.1 -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.1.1</version>
  <relativePath/>
</parent>

<dependencyManagement>
  <dependencies>
    <!-- ★ 锁死 Spring AI 版本，避免混用 1.x -->
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
  <!-- 提供 ChatModel、工具调用、ToolCallingAdvisor 等全部能力 -->
  <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-model-openai</artifactId></dependency>
  <dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency>
</dependencies>

▌运行验证：依赖齐了，先编译一次

# 在 pom.xml 所在目录执行（最先、最便宜的反馈）
mvn -q compile

看到什么算通过：命令结束无 BUILD FAILURE；特别地，不会出现 Cannot resolve org.springframework.ai:spring-ai-starter-model-openai:2.0.1 这类「找不到依赖」报错。若报找不到，回头检查 spring-ai-bom 的版本与引入方式（必须是 import 作用域的 pom）。这一步把「工程地基」钉死，后面所有文件出问题才不会和依赖混在一起。

▌动手第 0 步：先配好 application.yml（密钥占位符）

1. 打开 src/main/resources/application.yml（没有就 New → File 创建）。
2. 粘贴下方配置，保存。注意 api-key 用的是 ${DEEPSEEK_API_KEY:} 占位符，绝不硬编码真实 key。
3. 确认环境变量 DEEPSEEK_API_KEY 已设置，且 IDEA 是在设置之后启动的（否则进程读不到，见 ch00 的「进程继承」说明）。

spring:
  ai:
    openai:
      base-url: https://api.deepseek.com   # DeepSeek 兼容 OpenAI 协议
      api-key: ${DEEPSEEK_API_KEY:}          # ★ 占位符，key 来自环境变量，不进源码
      chat:
        options:
          model: deepseek-chat              # 默认模型

server:
  port: 8080

logging:
  level:
    org.springframework.ai.chat.client: DEBUG   # 方便看工具循环（7.2 用过）

① 天气工具（演示外部 API 调用 + 超时保护）

1. 右键 ch07 包 → New → Java Class，名字填 WeatherTools，粘贴下方代码，保存。
2. 确认引用到的 WeatherApi、WeatherApiResponse、DailyWeather 等类型：本示例为聚焦工具调用，假设这些外部类型已存在；若你想纯本地跑，可把 weatherApi.get(city) 替换成一个返回固定 WeatherApiResponse 的本地 stub（不影响工具调用教学）。

@Slf4j
@Component
public class WeatherTools {

    @Tool(description = """
            查询指定城市未来 3 天的天气预报。
            使用时机：用户询问天气、气温、是否下雨、穿衣建议时调用。
            不要用于：查询历史天气（本工具只支持未来 3 天）。
            """)
    public WeatherInfo queryWeather(
            @ToolParam(description = "城市名称，中文，例如 北京、上海、深圳；不要带'市'字后缀")
            String city) {

        // 城市名做白名单/格式校验，防止把用户输入拼进 URL 造成注入
        if (city == null || city.isBlank() || city.length() > 20) {
            return new WeatherInfo(city, List.of(), "城市名不合法，请向用户确认城市名称。");
        }

        try {
            // 外部 API 调用必须设超时，否则会把整个请求拖死
            WeatherApiResponse resp = weatherApi.get(city);

            // ★ 关键：把返回值"翻译"成模型友好的中文，而不是原样丢 JSON
            List<DailyWeather> days = resp.getDaily().stream()
                    .limit(3)     // 最多 3 天，避免上下文过长
                    .map(d -> new DailyWeather(
                            d.getDate(),
                            d.getTextDay(),                        // "晴" / "小雨"
                            d.getTempMin() + "~" + d.getTempMax() + "℃",
                            d.getHumidity() + "%"))
                    .toList();

            return new WeatherInfo(city, days, "");
        } catch (Exception e) {
            log.error("查询 {} 天气失败", city, e);
            return new WeatherInfo(city, List.of(), "天气服务暂时不可用，请稍后重试。");
        }
    }

    public record WeatherInfo(String city, List<DailyWeather> days, String message) {}
    public record DailyWeather(String date, String weather,
                                    String temperature, String humidity) {}
}

② 装配带工具的 ChatClient

1. 右键 ch07 包 → New → Java Class，名字填 AssistantConfig，粘贴下方代码，保存。
2. 确认它用 @Configuration 标注，且 OrderTools、WeatherTools 两个 bean 能被注入（它们都带 @Component）。

@Configuration
public class AssistantConfig {

    @Bean("orderAssistantClient")   // 用限定名区分多个 ChatClient
    public ChatClient orderAssistantClient(ChatModel chatModel,
                                             OrderTools orderTools,
                                             WeatherTools weatherTools) {
        return ChatClient.builder(chatModel)
                .defaultSystem("""
                        你是"智汇"公司的智能助手，可以查询订单状态和天气。

                        工作准则：
                        1. 凡是涉及订单数据、实时天气的问题，必须调用工具查询，
                           禁止凭已有知识或猜测回答。
                        2. 调用工具前如果缺少必要参数（如订单号、城市），
                           先向用户追问，不要编造参数。
                        3. 工具返回错误信息时，用友好、明确的语气告知用户，
                           并给出下一步建议。
                        4. 回答控制在 150 字以内。
                        """)
                .defaultTools(orderTools, weatherTools)   // 把工具挂到这个 client 上
                .build();
    }
}

③ 业务服务（注意 ToolContext 的注入）

1. 右键 ch07 包 → New → Java Class，名字填 OrderAssistantService，粘贴下方代码，保存。
2. 确认构造器注入了带 @Qualifier("orderAssistantClient") 的 ChatClient。

@Slf4j
@Service
public class OrderAssistantService {

    private final ChatClient orderAssistantClient;

    public OrderAssistantService(
            @Qualifier("orderAssistantClient") ChatClient orderAssistantClient) {
        this.orderAssistantClient = orderAssistantClient;
    }

    /** 带工具的问答。注意 ToolContext 里只放"服务端可信"的身份信息。 */
    public String ask(String question) {
        return orderAssistantClient.prompt()
                .user(question)
                // ★ 身份信息走 ToolContext，模型看不见也改不了
                .toolContext(Map.of(
                        "userId", SecurityContextHolder.currentUserId(),
                        "tenantId", SecurityContextHolder.currentTenantId()))
                .call()
                .content();
    }

    /** 进阶：手工查看模型到底调用了哪些工具（调试时有价值）。 */
    public String askWithToolTrace(String question) {
        ChatResponse response = orderAssistantClient.prompt()
                .user(question)
                .toolContext(Map.of("userId", SecurityContextHolder.currentUserId()))
                .call()
                .chatResponse();

        var output = response.getResult().getOutput();

        // 如果模型这一轮又发起了工具调用，会出现在这里
        if (output.getToolCalls() != null && !output.getToolCalls().isEmpty()) {
            output.getToolCalls().forEach(tc ->
                    log.info("模型请求调用工具：name={} arguments={} id={}",
                            tc.name(), tc.arguments(), tc.id()));
        }
        return output.getText();
    }
}

④ 接口与验证

1. 右键 ch07 包 → New → Java Class，名字填 OrderAssistantController，粘贴下方代码，保存。
2. 确认类上有 @RestController + @RequestMapping("/api/v1/assistant")，且注入了 OrderAssistantService。
3. 全部文件就位后，执行下面的「▌运行验证」把工程跑起来，再用 4 个 curl 场景逐一验证。

@RestController
@RequestMapping("/api/v1/assistant")
public class OrderAssistantController {

    private final OrderAssistantService service;

    public OrderAssistantController(OrderAssistantService service) {
        this.service = service;
    }

    @PostMapping("/ask")
    public Map<String, String> ask(@RequestBody Map<String, String> body) {
        String answer = service.ask(body.get("question"));
        return Map.of("answer", answer);
    }
}

▌运行验证：把工程跑起来

# 在 pom.xml 所在目录执行（先确认 application.yml 已配好 DeepSeek key 占位符）
mvn spring-boot:run

期望启动日志（节选）：

...
2025-xx-xx INFO  ... Started SpringaiLabApplication in 3.2 seconds
...

看到什么算通过：控制台最后出现 Started ... in X seconds，且没有红色 BUILD FAILURE / APPLICATION FAILED TO START；之后浏览器或 curl 访问 http://localhost:8080 不报「连接拒绝」。此时服务已就绪，可以进 4 个场景验证了。

▌运行验证：四个关键场景（前三个看「调通」，第 ②、④ 个看「安全与可靠」）

把示例跑起来，用 curl 验证四个关键场景。前三个场景对应「能不能调通」，第 ②、④ 个才是本章真正的考点（安全与可靠性）。

# ① 明确引用订单号 → 应触发 queryOrderStatus 工具
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 2024001 什么时候发货？"}'

# 期望日志（askWithToolTrace 或 debug 日志）：
# 模型请求调用工具：name=queryOrderStatus arguments={"orderNo":"2024001"}
# 期望回答："您的订单 2024001 显示未发货，预计 3 月 8 日发出。"

# ② 故意查一个不属于当前用户的订单 → 应返回友好提示而非数据
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"订单 9999999 发货了吗？"}'

# 期望：模型回答"未查询到该订单，请确认订单号是否正确"
# ★ 这一步验证的是权限校验，而不是模型的"自觉"

# ③ 混合任务：订单 + 天气（会触发两次工具调用）
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"我的订单 2024001 发货了吗？另外北京明天天气怎么样？"}'

# 期望：模型分别调用两个工具，最后合并成一段回答

# ④ 缺少参数 → 应追问而不是编造
curl -X POST http://localhost:8080/api/v1/assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"我的订单发货了吗？"}'

# 期望：模型回答"请提供订单号"
# 如果它随便编了一个订单号去查 → 你的系统提示约束不够强

看到什么算通过（逐条）：

• ① 日志出现 name=queryOrderStatus，且返回的是真实发货说明（不是「我不知道」）。
• ② 返回「未查询到该订单」，且绝不是别人的订单数据——这一条没过就是越权事故。
• ③ 一次回答里同时出现了订单状态和天气，日志里能看到两个工具都被调用。
• ④ 模型回问「请提供订单号」之类，没有凭空编造一个订单号去查。

7.8常见坑排错

7.9自测题

7.10实操作业与本章验收

• 能口述工具调用完整时序，说清为什么会有两次（或多次）模型调用，以及它对成本/延迟的影响。
• 能写出一个带「四要素描述」的 @Tool 方法，并知道用 FunctionToolCallback 注册函数式工具、toolNames() 已在 2.0 删除。
• 越权查询返回友好提示（不返回他人数据、不抛 500）；参数缺失时模型会追问而非编造。
• 能说出至少四条工具安全设计原则，并解释为什么身份类信息必须走 ToolContext 而非工具参数。