CH 02提示词与对话

2.1消息角色分工：为什么不能把所有话塞进一句话

新手最常见的写法是把所有要求揉成一段话：「你是一个客服，现在用户问 X，请按 Y 格式回答」。能跑，但问题很多：规则和用户输入混在一起，用户一句「忽略上面的要求」就可能把规则冲掉（提示词注入）；示例和问题混在一起，模型经常把示例当问题来回答。

为什么角色分层是必要的？因为模型在内部对「系统指令 / 用户数据 / 历史回答」的权重处理是不同的。系统消息被当作最高优先级的背景设定，用户消息被当作本轮待处理的数据，助手消息被当作对话历史。把这三类内容塞进同一段文本，等于主动放弃了模型本身就支持的「分层权重」能力，还会让提示词注入变得极易得手。

正确做法是利用消息角色把不同性质的内容分层：

在 ChatClient 里怎么写

两种写法都常用：第一种用 ChatClient 的角色方法，最简洁；第二种手工构造消息列表，需要精细控制多轮历史时用（例如把数据库里读出的历史消息原样拼回去）。

String answer = chatClient.prompt()
        .system("你是一名银行合规助手，只依据用户提供的资料回答；资料中没有的信息必须回答「资料中未提及」。")
        .user(question)
        .call()
        .content();

Prompt prompt = new Prompt(List.of(
        new SystemMessage("你是银行合规助手……"),
        new UserMessage("上一轮的问题"),
        new AssistantMessage("上一轮的答案"),
        new UserMessage("这一轮的问题")));
ChatResponse response = chatModel.call(prompt);

开始动手前：3 步环境自检（跳过这步，后面 90% 的报错都查不出来）

本章所有示例都跑在配套的 springai-pro/lab 工程里。动手之前先花三分钟把下面三件事确认掉——任何一步没过都不要往下走。带着环境问题去调业务代码，报错信息会互相干扰，排查时间翻几倍。

1. 确认 JDK 版本（Spring AI 2.0 的硬性底线是 Java 17）：

   java -version

   预期输出（主版本号 ≥ 17 即可，17 / 21 / 25 都行）：

   openjdk version "17.0.11" 2024-04-16
   OpenJDK Runtime Environment (build 17.0.11+9)
   OpenJDK 64-Bit Server VM (build 17.0.11+9, mixed mode)

   不通过怎么办：显示 1.8.x 或 11.x → 编译时必报 invalid target release: 17，去装 JDK 17 或 21；装完还要在 IDEA 的 File → Project Structure → Project 里把 SDK 和 Language level 都切到 17。
   提示 'java' 不是内部或外部命令 → JDK 没装，或装了没进 PATH。

2. 确认工程能编译（第一次执行会下载依赖，3~10 分钟属正常）：

   cd lab
   mvn -q compile

   预期输出：命令结束、没有 BUILD FAILURE，终端回到可输入状态。-q 是安静模式，正常情况下几乎什么都不打印——「什么都没输出」就是好消息。

   不通过怎么办：两类最常见错误见本节末尾的排错卡（依赖下载失败 / 找不到符号）。

3. 确认密钥与模型配置。打开 src/main/resources/application.yml，确认这两处：

   spring:
     ai:
       openai:
         api-key: ${DEEPSEEK_API_KEY:}         # ← 由环境变量提供
         base-url: https://api.deepseek.com    # ← 换厂商改这一行
         chat:
           options:
             model: deepseek-chat              # ← 换厂商改这一行

   再确认环境变量真的存在。在你准备用来启动应用的终端里执行（只打印一行空白 = 变量没设上）：

   # Git Bash
   echo $DEEPSEEK_API_KEY
   
   # CMD
   echo %DEEPSEEK_API_KEY%

   预期输出：打印出你的密钥字符串（形如 sk-xxxxxxxx）。

   不通过怎么办：打印空白 → 环境变量没设。设完之后必须重开终端、并重启 IDEA——IDEA 是在启动那一刻继承环境变量的，不重启它读不到新值（这是「明明配了却还是 401」的头号原因）。

动手：搭好本章「实验室」骨架（建议自建）

本章 2.1~2.4 的技巧，配套 lab 没有内置控制器，需要你自己建一个「实验室」把他们串起来联调：一个 PromptSkillsService 放所有 demo 方法，一个 PromptController 暴露实验接口。下面先把角色相关的两个方法建好，后面每节往里追加方法即可。

1. 在 IDEA 左侧 Project 视图展开 src/main/java/com/example/springai/ch02，在 ch02 包上右键 → New → Java Class。

2. 在弹出的对话框 Name 处输入 PromptSkillsService（注意大小写，和包名同级），回车。把下面内容整段粘贴进去并保存（Ctrl+S）：

   package com.example.springai.ch02;
   
   import org.springframework.ai.chat.client.ChatClient;
   import org.springframework.ai.chat.messages.AssistantMessage;
   import org.springframework.ai.chat.messages.Message;
   import org.springframework.ai.chat.messages.SystemMessage;
   import org.springframework.ai.chat.messages.UserMessage;
   import org.springframework.stereotype.Service;
   
   import java.util.ArrayList;
   import java.util.List;
   import java.util.Map;
   
   @Service
   public class PromptSkillsService {
   
       private final ChatClient chatClient;
   
       public PromptSkillsService(ChatClient chatClient) {
           this.chatClient = chatClient;
       }
   
       // 2.1 写法一：角色方法
       public String roleDemo(String question) {
           return chatClient.prompt()
                   .system("你是一名银行合规助手，只依据用户提供的资料回答；资料中没有的信息必须回答「资料中未提及」。")
                   .user(question)
                   .call()
                   .content();
       }
   
       // 2.1 写法二：消息列表（支持把历史原样拼回）
       public String messagesDemo(String question, List<Map<String, String>> history) {
           List<Message> messages = new ArrayList<>();
           messages.add(new SystemMessage("你是银行合规助手，只依据用户提供的资料回答。"));
           if (history != null) {
               for (Map<String, String> m : history) {
                   if ("user".equals(m.get("role"))) {
                       messages.add(new UserMessage(m.get("content")));
                   } else {
                       messages.add(new AssistantMessage(m.get("content")));
                   }
               }
           }
           messages.add(new UserMessage(question));
           return chatClient.prompt().messages(messages).call().content();
       }
   }

3. 同样在 ch02 包上右键 → New → Java Class，Name 输入 PromptController，回车，粘贴下面内容并保存：

   package com.example.springai.ch02;
   
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   import java.util.List;
   import java.util.Map;
   
   @RestController
   @RequestMapping("/api/v1/prompt")
   public class PromptController {
   
       private final PromptSkillsService service;
   
       public PromptController(PromptSkillsService service) {
           this.service = service;
       }
   
       public record RoleReq(String question) {}
       public record MessagesReq(String question, List<Map<String, String>> history) {}
   
       @PostMapping("/role")
       public String role(@RequestBody RoleReq r) {
           return service.roleDemo(r.question());
       }
   
       @PostMapping("/messages")
       public String messages(@RequestBody MessagesReq r) {
           return service.messagesDemo(r.question(), r.history());
       }
   }

4. 编译确认骨架能编过（不启动也能先卡掉语法/依赖错误）：

   mvn -q compile

   预期输出：命令结束、没有红色 BUILD FAILURE，终端回到可输入状态（-q 只输出警告/错误，正常时几乎静默）。看到 BUILD SUCCESS 或干净退出即算通过。

5. 启动应用（任一方式）：

   # 方式一：Maven 插件
   mvn spring-boot:run
   
   # 方式二：IDEA 里直接运行 SpringaiLabApplication 的 main 方法

   看到日志里 Started SpringaiLabApplication 即启动成功（端口 8080）。

6. 验证「写法一」角色方法——发一条合规问题：

   curl -X POST http://localhost:8080/api/v1/prompt/role \
     -H "Content-Type: application/json" \
     -d '{"question":"这笔转账需要几级审批？"}'

   接口返回的是一段纯文本（不是 JSON，因为 Controller 直接返回 String）。它每次措辞都不同，不要逐字比对，按下面的结构判据核对：

   【输出形态样例 · 措辞会变，结构必须一致】
   关于这笔转账的审批级别，资料中未提及。
   建议您联系柜台或拨打客服热线核实具体审批流程。

   逐条对照（三条全中才算通过）：

   • ① 语气是「银行合规助手」的口吻，不像随口聊天；
   • ② 出现「资料中未提及」或同义表述 —— 这是你写在 .system() 里的硬规则，它出现就证明系统消息生效了；
   • ③ 没有凭空编造审批级别（比如自己说「需要三级审批」）。

   对不上怎么查：②没出现 → 系统消息没传到模型，或模型在自由发挥，把 .system() 改成「即使不知道也必须原样回复『资料中未提及』」再试；③没通过 → 提示词约束强度不够，这正是 2.8 节要解决的问题。

7. 验证「写法二」消息列表——带一条历史，确认历史被当成上下文：

   curl -X POST http://localhost:8080/api/v1/prompt/messages \
     -H "Content-Type: application/json" \
     -d '{"question":"那物流问题呢？","history":[{"role":"user","content":"我下单三天了还没发货"},{"role":"assistant","content":"物流"}]}'

   这一轮要验证的核心是：历史消息有没有真的拼进 Prompt。模型看不到你的 Java 代码，只能从「回答像不像知道上文」来判断。

   【输出形态样例 · 措辞会变，关键判据不变】
   您是问物流方面的问题吗？关于您下单三天还未发货的情况，我可以帮您进一步查询物流状态。

   逐条对照（三条全中才算通过）：

   • ① 回答里出现「物流」二字 —— 它承接的是 history 里那条 assistant 回复；
   • ② 没有失忆表现（不会反问「您想咨询什么问题」）；
   • ③ 对照实验（强烈建议做一次）：把同一条命令里的 "history":[…] 整段删掉、只留 {"question":"那物流问题呢？"} 再发一遍，观察回答明显变「懵」。两次结果的差异，就是你亲眼看到的「历史有没有拼进去」的证据——这比读十遍文档都管用。

   对不上怎么查：如果它表现得像第一次对话，说明 history 没被拼进去。查两点：① MessagesReq 的字段名有没有拼错（必须是 history）；② 请求 JSON 里 history 是否真的传了 —— null 时循环直接跳过、不报错，只会"失忆"，这也是很隐蔽的坑，所以判据要盯回答内容而不是盯日志。

2.2PromptTemplate：把提示词变成可维护的代码

硬编码提示词的问题：需求一变就要改 Java 代码、测试用例全失效、同一条规则在 5 个地方复制粘贴。解决办法是把提示词变成带占位符的模板。为什么要模板化？因为提示词本质上是一种「带参数的文本」，把它当字符串写死，就等于把「配置」混进了「代码」——后期根本没法让产品/算法同学维护，也没法做 A/B 测试。

四步写法（最基础、最透明）

1. 在 PromptSkillsService 中追加下面这个方法（粘贴到类的最后一个 } 之前）：

   // 2.2 四步写法
   public String templateDemo(String role, String audience, String maxWords, String question) {
       String template = """
               你是一名{role}，请针对{audience}回答下面的问题。
   
               回答要求：
               1. 先用一句话给出结论；
               2. 再分点说明理由，每点不超过 30 字；
               3. 总长度不超过 {maxWords} 字。
   
               问题：{question}
               """;
       org.springframework.ai.chat.prompt.PromptTemplate promptTemplate =
               org.springframework.ai.chat.prompt.PromptTemplate.builder()
                       .template(template)
                       .build();
       org.springframework.ai.chat.prompt.Prompt prompt = promptTemplate.create(Map.of(
               "role", role,
               "audience", audience,
               "maxWords", maxWords,
               "question", question));
       return chatClient.prompt().messages(prompt.getInstructions()).call().content();
   }

2. 在 PromptController 中追加路由与请求体（粘贴到类内、其他 @PostMapping 之后）：

       public record TemplateReq(String role, String audience, String maxWords, String question) {}
   
       @PostMapping("/template")
       public String template(@RequestBody TemplateReq r) {
           return service.templateDemo(r.role(), r.audience(), r.maxWords(), r.question());
       }

3. 编译并启动（mvn -q compile 通过后再 mvn spring-boot:run），发请求：

   curl -X POST http://localhost:8080/api/v1/prompt/template \
     -H "Content-Type: application/json" \
     -d '{"role":"资深 Java 架构师","audience":"刚入职的应届生","maxWords":"200","question":"什么是依赖注入？"}'

   预期输出：一段「先结论、再分点、总长≤200 字」的回答。看到结构符合三条要求即算通过。

用 ChatClient 的链式模板（更简洁，推荐）

上面的四步可以浓缩成 ChatClient 的一行链式调用：用 .user(u -> u.text(...).param(...)) 直接写模板和参数。可读性更好，也更符合第 1 章养成的 fluent 习惯。

1. 在 PromptSkillsService 追加：

   // 2.2 链式模板
   public String fluentDemo(String role, String audience, String question) {
       return chatClient.prompt()
               .system(s -> s.text("你是{role}，面向{audience}作答。")
                       .param("role", role)
                       .param("audience", audience))
               .user(u -> u.text("请回答：{question}")
                       .param("question", question))
               .call()
               .content();
   }

2. 在 PromptController 追加：

       public record FluentReq(String role, String audience, String question) {}
   
       @PostMapping("/fluent")
       public String fluent(@RequestBody FluentReq r) {
           return service.fluentDemo(r.role(), r.audience(), r.question());
       }

3. 验证：

   curl -X POST http://localhost:8080/api/v1/prompt/fluent \
     -H "Content-Type: application/json" \
     -d '{"role":"资深客服","audience":"普通用户","question":"怎么申请退款？"}'

   接口返回纯文本，按下面四条核对：

   【输出形态样例 · 措辞会变，特征不变】
   您好，关于退款申请，您可以这样操作：
   1. 进入「我的订单」，找到对应订单；
   2. 点击「申请退款」，选择退款原因；
   3. 提交后 1~3 个工作日原路退回。

   逐条对照：

   • ① 是「客服对普通用户」的通俗口吻，没有堆技术术语（说明 {audience} 生效）；
   • ② 回答围绕「怎么申请退款」展开，没有跑题；
   • ③ 回答里没有字面的 {role} / {audience} / {question}。

   这节的意义：和上面「四步写法」比，输出质量应该差不多——差别只在代码更短。如果你发现两者结果明显不同，八成是参数名写错了（.param("role", …) 里的字符串必须和模板占位符同名）。

import org.springframework.ai.template.st.StTemplateRenderer;

PromptTemplate t = PromptTemplate.builder()
        .renderer(StTemplateRenderer.builder()
                .startDelimiterToken('<')     // 占位符改用 <xxx>
                .endDelimiterToken('>')
                .build())
        .template("请把 <text> 翻译成 <lang>，输出格式保持 {\"k\":\"v\"} 不变")
        .build();

1. 在 PromptSkillsService 追加（注意这里换成了 < > 定界符，模板里的 {"k":"v"} 因此被原样保留）：

   // 2.2 换定界符（推荐解法）
   public String translateDemo(String text, String lang) {
       org.springframework.ai.chat.prompt.PromptTemplate t =
               org.springframework.ai.chat.prompt.PromptTemplate.builder()
                       .renderer(org.springframework.ai.template.st.StTemplateRenderer.builder()
                               .startDelimiterToken('<')
                               .endDelimiterToken('>')
                               .build())
                       .template("请把 <text> 翻译成 <lang>，输出格式保持 {\"k\":\"v\"} 不变")
                       .build();
       org.springframework.ai.chat.prompt.Prompt prompt = t.create(Map.of("text", text, "lang", lang));
       return chatClient.prompt().messages(prompt.getInstructions()).call().content();
   }

2. 在 PromptController 追加：

       public record TranslateReq(String text, String lang) {}
   
       @PostMapping("/translate")
       public String translate(@RequestBody TranslateReq r) {
           return service.translateDemo(r.text(), r.lang());
       }

3. 验证——{"k":"v"} 应原样出现在输出里，不被吃掉：

   curl -X POST http://localhost:8080/api/v1/prompt/translate \
     -H "Content-Type: application/json" \
     -d '{"text":"你好世界","lang":"English"}'

   预期输出：形如「Translate 你好世界 to English, output format keep {"k":"v"} unchanged」的翻译说明——关键是 {"k":"v"} 仍在。看到花括号没丢即算通过。

2.3把提示词外置成文件（工程化必备）

企业项目里提示词通常由产品/算法同学维护，不该埋在 Java 代码里。放进 src/main/resources/prompts/，好处是：改提示词不用重新编译、可以做版本管理、非开发人员也能编辑。

动手：在 IDEA 里建提示词文件（最容易建错位置的一步）

1. 在 IDEA 的 Project 视图里，找到 src/main/resources。在 resources 上右键 → New → Package，输入 prompts，回车（注意是 Package，不是 Directory——Package 保证路径规范；这里 resources 下建 package 实际就是建目录 prompts/）。

2. 在刚建好的 prompts 目录上右键 → New → File，输入完整文件名 system-customer-service.st（含 .st 后缀，不能只写 system-customer-service），回车。

3. 把下面内容整段粘贴进该文件并保存（这就是与配套 lab 完全一致的客服系统提示）：

   # 你是"智汇"公司的智能客服，工号 AI-001。
   #
   # 【提示词版本管理】（教程 2.3 的工程化建议）
   #   - 本文件纳入 Git 管理，改名时带版本号（system-customer-service-v2.st）
   #   - 每次修改在下面追加一行：日期 / 修改人 / 改了什么 / 为什么改
   #   - 第 10 章做评测时，需要把「提示词版本」和「效果指标」关联起来
   #
   # 2026-09-28 首次创建，与教程 ch02 2.3 节内容一致
   
   你是"智汇"公司的智能客服，工号 AI-001。
   
   ## 你的职责
   协助用户处理订单查询、退换货、发票开具三类问题。
   
   ## 硬性规则
   1. 只回答上述三类问题，其他问题礼貌说明并回复"转人工"。
   2. 涉及订单信息时必须先调用工具查询，禁止凭记忆编造订单号或金额。
   3. 用户情绪激动时，第一句先共情，再处理问题。
   4. 任何情况下不得承诺具体赔付金额。
   
   ## 输出风格
   简洁、专业、有耐心。每条回复不超过 150 字。

4. 先编译验证资源被拷贝（这一步很关键——写在 Java 里加载文件，若文件没进 classpath，运行时才爆，难查）：

   mvn -q compile

   然后用系统文件管理器（或 IDEA 的 target/classes/prompts/）确认出现了 system-customer-service.st。看到该文件即算通过——说明资源已随编译拷贝进 classpath。

5. 同样在 prompts 目录上右键 → New → File，输入 order-query.st，粘贴下面内容（2.3「写法二」练习用，含占位符）：

   你是订单查询助手。请根据订单号 {orderNo} 查询并回答用户的问题。
   如果订单号无法识别，请回复"请提供正确的订单号"。

   再次 mvn -q compile，确认 target/classes/prompts/order-query.st 也出现了。

.st 是 Spring AI 约定提示词模板文件的后缀（system template 的简写，也可用作普通模板）。

在代码里加载它——ClassPathResource 会自动去 resources 目录下找文件，写 "prompts/system-customer-service.st" 即可，不用写 src/main/resources 前缀：

1. 在 PromptSkillsService 追加（单引号转义 '<' '/>' 这里不需要，因为本模板没有花括号冲突）：

   // 2.3 文件模板（写法二：单次请求带占位符）
   public String orderDemo(String orderNo) {
       return chatClient.prompt()
               .user(u -> u.text(new org.springframework.core.io.ClassPathResource("prompts/order-query.st"))
                       .param("orderNo", orderNo))
               .call()
               .content();
   }

2. 在 PromptController 追加：

       public record OrderReq(String orderNo) {}
   
       @PostMapping("/order")
       public String order(@RequestBody OrderReq r) {
           return service.orderDemo(r.orderNo());
       }

3. 启动后验证：

   curl -X POST http://localhost:8080/api/v1/prompt/order \
     -H "Content-Type: application/json" \
     -d '{"orderNo":"2024001"}'

   接口返回纯文本，按下面三条核对：

   【输出形态样例 · 措辞会变，关键值不变】
   订单号 2024001 的查询请求已收到。
   （本示例未接入真实订单系统，如需真实查询请提供具体查询维度。）

   逐条对照：

   • ① 输出里必须出现 2024001 —— 证明 .param("orderNo", …) 把值填进了模板；
   • ② 出现的不是「请提供订单号」这类索要输入的话（那说明占位符没被替换）；
   • ③ 没有出现字面的 {orderNo}。

   对不上怎么查：③出现字面 {orderNo} → 说明加载到的模板没走渲染，或参数名拼错。回头确认两处：文件确实在 src/main/resources/prompts/order-query.st；.param("orderNo", orderNo) 的 key 与模板里 {orderNo} 完全一致。

2.4少样本提示（Few-shot）：用示例代替解释

有些格式要求，用文字描述十遍都不如给两个例子。少样本提示的本质是把示例放进消息历史，让模型模仿模式。为什么示例比规则管用？因为大模型本质是「下一个 token 预测器」，给它看一个「输入→输出」的成对样本，它就能在内隐空间里拟合出这种映射，这比用自然语言描述「请按此格式」稳定得多。

方式一：用 AssistantMessage 构造示例对（最标准）

1. 在 PromptSkillsService 追加：

   // 2.4 方式一：示例对
   public String fewShotMessages(String question) {
       List<Message> messages = new ArrayList<>();
       messages.add(new SystemMessage("你是工单分类器。请把用户描述归类到：退款/物流/质量/其他，只输出类别名。"));
       messages.add(new UserMessage("我下单三天了还没发货"));
       messages.add(new AssistantMessage("物流"));
       messages.add(new UserMessage("收到的东西外壳裂了"));
       messages.add(new AssistantMessage("质量"));
       messages.add(new UserMessage(question));
       return chatClient.prompt().messages(messages).call().content();
   }

2. 在 PromptController 追加：

       public record FewShotReq(String question) {}
   
       @PostMapping("/few-shot/messages")
       public String fewShotMessages(@RequestBody FewShotReq r) {
           return service.fewShotMessages(r.question());
       }

3. 验证（期望返回 退款）：

   curl -X POST http://localhost:8080/api/v1/few-shot/messages \
     -H "Content-Type: application/json" \
     -d '{"question":"钱什么时候退给我"}'

   这条命令可以精确断言：

   【预期输出】
   退款

   逐条对照：

   • ① 输出就是「退款」两个字（允许首尾空格或一个句号，去掉后应完全相等）；
   • ② 不是一整句解释（出现「根据您的描述，这属于退款问题…」说明系统提示里「只输出类别名」没被遵守）；
   • ③ 不是 物流 / 质量 / 其他。

   为什么这条能精确断言：因为分类结果是四选一的枚举值，不是自由文本。凡是「从封闭集合里选一个」的任务，预期结果都能这样写死 —— 第 3 章的结构化输出会把这种可断言性做到极致。

方式二：写在模板里（更省 Token，适合简单任务）

1. 在 PromptSkillsService 追加：

   // 2.4 方式二：模板里的示例
   public String fewShotTemplate(String question) {
       String fewShotTemplate = """
               把用户描述归类到 [退款/物流/质量/其他]，只输出类别名。
   
               示例：
               输入：我下单三天了还没发货    输出：物流
               输入：收到的东西外壳裂了      输出：质量
               输入：怎么申请开发票          输出：其他
   
               输入：{userInput}
               输出：""";
       org.springframework.ai.chat.prompt.PromptTemplate pt =
               org.springframework.ai.chat.prompt.PromptTemplate.builder().template(fewShotTemplate).build();
       org.springframework.ai.chat.prompt.Prompt prompt = pt.create(Map.of("userInput", question));
       return chatClient.prompt().messages(prompt.getInstructions()).call().content();
   }

2. 在 PromptController 追加：

       @PostMapping("/few-shot/template")
       public String fewShotTemplate(@RequestBody FewShotReq r) {
           return service.fewShotTemplate(r.question());
       }

3. 验证（期望返回 其他）：

   curl -X POST http://localhost:8080/api/v1/few-shot/template \
     -H "Content-Type: application/json" \
     -d '{"question":"怎么申请开发票"}'

   预期输出：单独一个词 其他。看到分类正确即算通过。

思维链（CoT）：让模型「先想后答」

1. 在 PromptSkillsService 追加：

   // 2.4 思维链（CoT）
   public String cotDemo(String problem) {
       String t = """
               请按以下步骤回答，并保留每一步的计算过程：
               步骤1：写出原价与折扣率；
               步骤2：计算折后价；
               步骤3：减去优惠券；
               步骤4：用一行给出最终答案，格式为「最终答案：XXX 元」。
   
               题目：%s
               """.formatted(problem);
       return chatClient.prompt().user(t).call().content();
   }

2. 在 PromptController 追加：

       public record CotReq(String problem) {}
   
       @PostMapping("/cot")
       public String cot(@RequestBody CotReq r) {
           return service.cotDemo(r.problem());
       }

3. 验证：

   curl -X POST http://localhost:8080/api/v1/cot \
     -H "Content-Type: application/json" \
     -d '{"problem":"一个订单原价 899 元，打 8 折后又用了 50 元券，最终多少钱？"}'

   这道题的数字可以手算验证，所以整条输出都能拿来对照：899 × 0.8 = 719.2，再减 50 = 669.2。

   【输出形态样例 · 中间措辞会变，四个步骤与最终数字必须一致】
   步骤1：原价 899 元，折扣率 8 折（即 0.8）。
   步骤2：折后价 = 899 × 0.8 = 719.2 元。
   步骤3：减去 50 元优惠券：719.2 − 50 = 669.2 元。
   步骤4：最终答案：669.2 元

   逐条对照：

   • ① 四个步骤都在（说明 CoT 的「分步」生效）；
   • ② 步骤2 的结果是 719.2；
   • ③ 最后一行形如 最终答案：669.2 元，数字必须正好是 669.2；
   • ④ 最后一行只有答案，不掺其他话 —— 这是给第 3 章「把推理过程和结构化结果分开」做铺垫。

   对不上怎么查：③算成别的数 → 模型算术出错，正是 CoT 要解决的问题，可把步骤写得更死（如「步骤3：用步骤2的结果减去 50」）再试；④最后一行掺了话 → 在提示词里再强调「最后一行只能有这一句」。

2.5多轮上下文与 ChatMemory 初探

大模型本身没有记忆。它每次调用都是「无状态」的——你以为它在跟你聊天，其实是你每一轮都把前面所有对话重新发了一遍。这一点必须刻在脑子里，否则你永远理解不了为什么「Token 越聊越多、越聊越慢、最后报上下文超限」。

Spring AI 的做法：用 ChatMemory 管理对话历史，再用一个 Advisor 自动把它注入到每次请求里。这样业务代码里你只要说「把这段记忆挂上」，每轮请求就会自动带上历史。

1. 在 PromptSkillsService 追加一个「带记忆」的演示（这里用内存窗口记忆，每次调用必须传 conversationId）：

   // 2.5 多轮记忆初探（内存窗口，仅演示）
   public String memoryDemo(String conversationId, String message) {
       org.springframework.ai.chat.memory.ChatMemory mem =
               org.springframework.ai.chat.memory.MessageWindowChatMemory.builder()
                       .maxMessages(20)
                       .build();
       ChatClient memoryClient = chatClient.mutate()
               .defaultAdvisors(org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor
                       .builder(mem).build())
               .build();
       return memoryClient.prompt()
               .user(message)
               .advisors(a -> a.param(
                       org.springframework.ai.chat.memory.ChatMemory.CONVERSATION_ID, conversationId))
               .call()
               .content();
   }

2. 在 PromptController 追加：

       public record MemoryReq(String conversationId, String message) {}
   
       @PostMapping("/memory")
       public String memory(@RequestBody MemoryReq r) {
           return service.memoryDemo(r.conversationId(), r.message());
       }

3. 编译确认能编过：

   mvn -q compile

   无 BUILD FAILURE 即算通过（完整「多轮+隔离」的验收放在 2.7 节三个 curl，那里才是正式验收动作）。

2.6多模态消息：让模型「看图」

主流模型都支持图片输入。Spring AI 用统一的 Media 对象表达多模态内容：一张图片就是一个 Media，和文本一起放进去，模型就能「边看边答」。

1. 在 PromptSkillsService 追加（这里用远程 URL 图片，最稳，不依赖本地资源）：

   // 2.6 多模态：远程 URL 图片
   public String multimodalDemo(String imageUrl) {
       org.springframework.ai.content.Media media = new org.springframework.ai.content.Media(
               org.springframework.util.MimeTypeUtils.IMAGE_JPEG,
               new org.springframework.core.io.UrlResource(java.net.URI.create(imageUrl)));
       return chatClient.prompt()
               .user(u -> u.text("请识别这张图片里的所有文字，并整理成表格。")
                       .media(media))
               .call()
               .content();
   }

2. 在 PromptController 追加：

       public record MultimodalReq(String imageUrl) {}
   
       @PostMapping("/multimodal")
       public String multimodal(@RequestBody MultimodalReq r) {
           return service.multimodalDemo(r.imageUrl());
       }

3. 编译并启动。注意：deepseek-chat 不支持图片，本接口需把 application.yml 的 base-url 与 model 改成视觉模型（如 qwen-vl-max / gpt-4o / glm-4v）后再测。

   mvn -q compile

   无 BUILD FAILURE 即算通过（功能验证需要视觉模型，属扩展练习，不计入本章必做验收 —— 但如果你想真跑通，走下面两条路之一）。

用 message 对象手工构造（需要同时放文本和图片时）

UserMessage msg = UserMessage.builder()
        .text("这张发票的金额和开票日期分别是多少？")
        .media(new Media(MimeTypeUtils.IMAGE_PNG, new ClassPathResource("images/invoice.png")))
        .build();

String answer = chatModel.call(new Prompt(List.of(msg)))
        .getResult().getOutput().getText();

2.7完整示例：智能客服对话接口

把本章所有能力串起来：外置系统提示 + 多轮记忆 + 会话隔离。下面三份文件与配套 lab 的 ch02 包逐字一致，是本站的「标准答案」。

本章实验接口清单（联调时照抄进 Apifox）

前 9 个是 2.1~2.4 的练习接口（配套 lab 未内置，按上面「实验室」原则自建时照此命名即可）；最后一个客服接口的代码在下文逐行给出。

动手：创建客服三件套（标准答案，逐字一致）

1. 在 IDEA 的 ch02 包上右键 → New → Java Class，Name 输入 CustomerServiceConfig，回车，把下面内容整段粘贴并保存（不要改动任何一行）：

   package com.example.springai.ch02;
   
   import org.springframework.ai.chat.client.ChatClient;
   import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
   import org.springframework.ai.chat.memory.ChatMemory;
   import org.springframework.ai.chat.memory.MessageWindowChatMemory;
   import org.springframework.ai.chat.model.ChatModel;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.core.io.ClassPathResource;
   
   @Configuration
   public class CustomerServiceConfig {
   
       /**
        * 客服记忆容器：内存版滑动窗口，最多保留 20 条消息。
        * 第 6 章会把它换成 JDBC/Redis 实现，接口不变，改这一处即可。
        */
       @Bean
       public ChatMemory customerChatMemory() {
           return MessageWindowChatMemory.builder()
                   .maxMessages(20)
                   .build();
       }
   
       /**
        * 客服专用 ChatClient。
        * 注意用 @Qualifier 或方法名区分，避免和全局那个 ChatClient 冲突——
        * 所以这里把 bean 名字显式写成 customerServiceChatClient。
        */
       @Bean
       public ChatClient customerServiceChatClient(ChatModel chatModel,
                                                   ChatMemory customerChatMemory) {
           return ChatClient.builder(chatModel)
                   // 系统提示从文件加载：改提示词不用重新编译
                   .defaultSystem(new ClassPathResource("prompts/system-customer-service.st"))
                   // 挂上记忆 Advisor
                   .defaultAdvisors(MessageChatMemoryAdvisor.builder(customerChatMemory).build())
                   .build();
       }
   }

2. 同样在 ch02 包上右键 → New → Java Class，Name 输入 CustomerServiceService，粘贴下面内容并保存：

   package com.example.springai.ch02;
   
   import org.springframework.ai.chat.client.ChatClient;
   import org.springframework.ai.chat.memory.ChatMemory;
   import org.springframework.beans.factory.annotation.Qualifier;
   import org.springframework.stereotype.Service;
   
   @Service
   public class CustomerServiceService {
   
       private final ChatClient chatClient;
   
       // 显式指定 bean 名，避免容器里有多个 ChatClient 时的歧义
       public CustomerServiceService(
               @Qualifier("customerServiceChatClient") ChatClient chatClient) {
           this.chatClient = chatClient;
       }
   
       /**
        * 多轮对话。
        *
        * @param userId    用户标识：决定"这是谁的记忆"
        * @param sessionId 会话标识：同一用户可能有多个并行会话（网页/App/小程序）
        * @param message   用户本轮输入
        */
       public String chat(String userId, String sessionId, String message) {
           // 会话 ID 的拼装规则要在全项目统一，第 6 章会抽成工具类
           String conversationId = userId + ":" + sessionId;
   
           return chatClient.prompt()
                   .user(u -> u.text("{message}")
                              .param("message", message))
                   // ★ 必须传，否则所有用户共享同一段记忆（严重事故）
                   .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
                   .call()
                   .content();
       }
   }

3. 再建 CustomerServiceController，粘贴下面内容并保存：

   package com.example.springai.ch02;
   
   import org.springframework.web.bind.annotation.PostMapping;
   import org.springframework.web.bind.annotation.RequestBody;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   import jakarta.validation.Valid;
   import jakarta.validation.constraints.NotBlank;
   
   @RestController
   @RequestMapping("/api/v1/customer-service")
   public class CustomerServiceController {
   
       private final CustomerServiceService service;
   
       public CustomerServiceController(CustomerServiceService service) {
           this.service = service;
       }
   
       /**
        * ★ 教程片段里只写了 @RequestBody，但那样 @NotBlank 是"摆设"——
        *   必须再补一个 @Valid，Spring MVC 才会真正执行校验（字段为空白时返回 400）。
        */
       @PostMapping("/chat")
       public ChatResponse chat(@Valid @RequestBody ChatRequest req) {
           String reply = service.chat(req.userId(), req.sessionId(), req.message());
           return new ChatResponse(req.sessionId(), reply);
       }
   
       /**
        * 请求体。
        * userId 在真实项目里应从登录态（JWT/Session）取，不能由前端传——
        * 前端传的话，任何人都能伪造别人的 userId 读取别人的对话历史。
        * 这里为了教学简化，先放请求体里。
        */
       public record ChatRequest(
               @NotBlank String userId,
               @NotBlank String sessionId,
               @NotBlank String message) {}
   
       public record ChatResponse(String sessionId, String reply) {}
   }

4. 关键依赖检查（很多人漏这步，导致 @Valid 不生效）：打开 pom.xml，确认有 spring-boot-starter-validation 依赖。没有就加上：

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-validation</artifactId>
   </dependency>

   只有存在这个 starter，@Valid + @NotBlank 才会真正执行校验；否则 @NotBlank 形同虚设，空白字段也能通过。

5. 编译确认三件套能编过（此时容器里有两个 ChatClient，靠 @Qualifier 区分，不应报 bean 冲突）：

   mvn -q compile

   无 BUILD FAILURE 即算通过。

6. 启动应用（mvn spring-boot:run 或运行 SpringaiLabApplication），日志出现 Started SpringaiLabApplication 即成功。

运行验证（本章正式验收动作）

1. 第 1 轮：告诉客服一个订单号。

   curl -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"u1001","sessionId":"s1","message":"我的订单号是 2024001，帮我看看发货了吗"}'

   预期输出（这一轮不做严格断言，只要不是报错就行）：

   【输出形态样例 · 措辞会变】
   您好，已为您查询到订单 2024001 的信息。请稍等，我正在核实发货状态……
   （本示例未接入真实订单系统，如需真实物流信息请以官方渠道为准。）

   逐条对照：① 是客服口吻（称呼「您」、语气专业）；② 没有报 401 / 500 这类错误；③ 回复里提到了订单号 2024001。
   本轮的作用是「喂数据」——真正要看的是第 2 轮。

2. 第 2 轮：故意不说订单号，看它记不记得。

   curl -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"u1001","sessionId":"s1","message":"我刚才说的订单号是多少？"}'

   预期输出：模型能答出 2024001 → 说明记忆生效、身份隔离正确。

3. 第 3 轮：换一个 sessionId，验证会话隔离。

   curl -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"u1001","sessionId":"s2","message":"我刚才说的订单号是多少？"}'

   预期输出：模型回答「你没有提供过订单号」之类 → 说明隔离生效（s2 是另一段记忆）。

4. 额外验证：空字段应被 @Valid 拦下，返回 400。

   curl -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"","sessionId":"s1","message":""}'

   怎么看状态码：默认 curl 只打印响应体、不显示 400，很多同学因此误以为「返回了 200」。加上 -i 才会打印响应头。建议改用下面这条命令：

   curl -i -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"","sessionId":"s1","message":""}'

   【预期输出 · 状态码是确定的】
   HTTP/1.1 400 Bad Request
   Content-Type: application/json
   ...
   （响应体里通常带 MethodArgumentNotValidException 或具体字段名提示）

   逐条对照：① 第一行是 HTTP/1.1 400（不是 200）；② 响应体提到了校验失败。
   对不上怎么查：第一行是 200 OK → 说明 @Valid 漏了，或 pom.xml 缺 spring-boot-starter-validation，见本节排错卡第 4 条。

一键冒烟测试：写一个脚本，把 12 个接口全跑一遍

手工敲 curl 容易漏、容易改错参数。把验证动作固化成脚本，是「能跑通」和「可重复验证」之间的分水岭——脚本可以每次改完代码就重跑一遍，不用回忆上次敲了什么。

1. 在工程根目录（lab/，与 pom.xml 同级）新建 smoke-test.sh：IDEA 里右键工程根 → New → File，输入文件名 smoke-test.sh。

2. 粘贴下面内容并保存。脚本已经把「应用没启动」「密钥没配」这两种情况单独拦出来，免得你对着报错发呆：

   #!/usr/bin/env bash
   # 第 2 章冒烟测试 · 把本章全部接口跑一遍
   # 用法：在 Git Bash 里执行  bash smoke-test.sh
   BASE="http://localhost:8080"
   PASS=0; FAIL=0
   
   # 统一请求函数：$1=名称  $2=路径  $3=JSON 请求体
   req() {
     local name="$1" path="$2" body="$3"
     out=$(curl -s -X POST "$BASE$path" -H "Content-Type: application/json" -d "$body" 2>&1)
     if [ -z "$out" ]; then
       echo "[X] $name  无响应 —— 应用没启动，或端口不是 8080"
       FAIL=$((FAIL+1)); return
     fi
     case "$out" in
       *Unauthorized*|*401*)
         echo "[X] $name  401 —— API 密钥不对，或没配到环境变量"
         FAIL=$((FAIL+1)); return ;;
     esac
     echo "[OK] $name"
     echo "     返回：$(echo "$out" | head -c 120)"
     PASS=$((PASS+1))
   }
   
   echo "===== 第 2 章冒烟测试开始 ====="
   req "2.1 角色方法"   "/api/v1/prompt/role"     '{"question":"这笔转账需要几级审批？"}'
   req "2.1 消息列表"   "/api/v1/prompt/messages" '{"question":"那物流问题呢？","history":[{"role":"user","content":"我下单三天了还没发货"},{"role":"assistant","content":"物流"}]}'
   req "2.2 四步模板"   "/api/v1/prompt/template" '{"role":"资深 Java 架构师","audience":"刚入职的应届生","maxWords":"200","question":"什么是依赖注入？"}'
   req "2.2 链式模板"   "/api/v1/prompt/fluent"   '{"role":"资深客服","audience":"普通用户","question":"怎么申请退款？"}'
   req "2.2 换定界符"   "/api/v1/prompt/translate" '{"text":"你好世界","lang":"English"}'
   req "2.3 文件模板"   "/api/v1/prompt/order"    '{"orderNo":"2024001"}'
   req "2.4 示例对"     "/api/v1/prompt/few-shot/messages" '{"question":"钱什么时候退给我"}'
   req "2.4 模板示例"   "/api/v1/prompt/few-shot/template" '{"question":"怎么申请开发票"}'
   req "2.4 思维链"     "/api/v1/prompt/cot"      '{"problem":"一个订单原价 899 元，打 8 折后又用了 50 元券，最终多少钱？"}'
   
   echo "--- 多轮记忆与会话隔离（这三条要靠人工看内容）---"
   req "2.7 第1轮 喂订单号" "/api/v1/customer-service/chat" '{"userId":"u1001","sessionId":"s1","message":"我的订单号是 2024001，帮我看看发货了吗"}'
   req "2.7 第2轮 应记得"   "/api/v1/customer-service/chat" '{"userId":"u1001","sessionId":"s1","message":"我刚才说的订单号是多少？"}'
   req "2.7 第3轮 应隔离"   "/api/v1/customer-service/chat" '{"userId":"u1001","sessionId":"s2","message":"我刚才说的订单号是多少？"}'
   
   echo ""
   echo "===== 结果：成功 $PASS / 失败 $FAIL ====="
   echo "人工核对：第2轮返回应含 2024001；第3轮返回不应含 2024001。"

3. 运行它：

   cd lab
   bash smoke-test.sh

   预期输出（12 个接口逐个打印，最后给统计）：

   ===== 第 2 章冒烟测试开始 =====
   [OK] 2.1 角色方法
        返回：关于这笔转账的审批级别，资料中未提及。
   [OK] 2.1 消息列表
        返回：您是在问物流相关的问题吗……
   （中间省略）
   ===== 结果：成功 12 / 失败 0 =====
   人工核对：第2轮返回应含 2024001；第3轮返回不应含 2024001。

   逐条对照：① 没有任何 [X] 开头的行；② 末尾是「成功 12 / 失败 0」。出现 [X] 时，行尾的提示已经告诉你方向——「无响应」查应用是否启动，「401」查密钥。

要不要写自动化测试？——先分清「能测什么」

看到「测试」两个字，很多同学的第一反应是写 JUnit。但这里有一个反直觉的事实必须先讲清楚：调真实大模型的接口，不适合写单元测试。

一句话原则：测「你写的代码」，不测「模型生成的文本」。下面这份测试全部满足「不联网、不花钱、秒级跑完」三个条件。

1. 在 src/test/java/com/example/springai/ch02 下新建 PromptTemplateTest.java（目录不存在就一层层建；src/test/java 在 IDEA 里通常显示为绿色）。

2. 整段粘贴并保存。这里的三条断言都是确定性的字符串/逻辑判断，不涉及任何模型调用：

   package com.example.springai.ch02;
   
   import org.junit.jupiter.api.Test;
   import org.springframework.ai.chat.prompt.PromptTemplate;
   
   import java.util.Map;
   
   import static org.junit.jupiter.api.Assertions.assertEquals;
   import static org.junit.jupiter.api.Assertions.assertTrue;
   
   /**
    * 只测「确定性逻辑」：不调模型、不联网、不花钱。
    * 运行：mvn test
    */
   class PromptTemplateTest {
   
       /** 占位符能被正确替换 —— 提示词工程的地基 */
       @Test
       void 占位符应被替换成实际参数() {
           PromptTemplate t = PromptTemplate.builder()
                   .template("请把 {text} 翻译成 {lang}")
                   .build();
   
           String rendered = t.render(Map.of("text", "你好", "lang", "English"));
   
           assertEquals("请把 你好 翻译成 English", rendered);
       }
   
       /** JSON 花括号必须原样保留（对应 2.2 节「换定界符」那个坑） */
       @Test
       void 换定界符后_json花括号应原样保留() {
           PromptTemplate t = PromptTemplate.builder()
                   .renderer(org.springframework.ai.template.st.StTemplateRenderer.builder()
                           .startDelimiterToken('<')
                           .endDelimiterToken('>')
                           .build())
                   .template("请把 <text> 翻译成 <lang>，格式保持 {\"k\":\"v\"} 不变")
                   .build();
   
           String rendered = t.render(Map.of("text", "你好", "lang", "English"));
   
           assertTrue(rendered.contains("{\"k\":\"v\"}"),
                   "JSON 花括号被模板引擎吃掉了，实际输出：" + rendered);
       }
   
       /** conversationId 的拼装规则必须全项目统一（对应 2.7 节会话隔离） */
       @Test
       void 会话ID应按用户与会话拼接() {
           String userId = "u1001";
           String sessionId = "s1";
   
           String conversationId = userId + ":" + sessionId;
   
           assertEquals("u1001:s1", conversationId);
           assertTrue(conversationId.contains(":"), "必须含分隔符，否则不同组合可能撞车");
       }
   }

   两点说明：① 方法名用中文完全没问题，JUnit 5 支持，而且中文名在测试报告里更好读；② 上面代码里 <text> 在网页上已被转义显示，从这个页面直接复制就是正确的尖括号，不需要手工改。

   若你的 IDE 提示 render 方法不存在（不同小版本 API 可能有细微差异），等价写法是 t.create(map).getInstructions().get(0).getText() —— 以 IDE 补全给出的方法为准。

3. 运行测试：

   cd lab
   mvn test

   预期输出（关键看 Tests run 那几行和结尾的 BUILD SUCCESS）：

   [INFO] Running com.example.springai.ch02.PromptTemplateTest
   [INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.4 s
   [INFO] BUILD SUCCESS

   逐条对照：① Tests run: 3（三条都跑到了）；② Failures: 0, Errors: 0；③ 结尾 BUILD SUCCESS。

2.8提示词工程实战模板（可直接套用）

一条高质量的系统提示词，通常包含下面 7 个部分。做第 11 章项目时，按这个骨架写就行：

2.9常见坑排错

2.10自测题

2.11实操作业与本章验收

• 能说明四种消息类型（System/User/Assistant/ToolResponse）各自的用途，并手写出多轮对话的消息列表。
• 能把一段硬编码提示词改造成「外置文件 + 模板参数」的形式，并解释 {} 与 JSON 花括号冲突的解法（换 < > 定界符 / 单引号转义）。
• 客服用例的三个 curl 全部符合预期（含会话隔离验证：换 sessionId 后模型说没提供过订单号），且空字段返回 400。
• 能解释为什么模型没有记忆，以及 Token 随轮次近平方级增长的原因与控制手段。
• 能说清 @Qualifier 与 @Primary 的区别，以及 @Valid+@NotBlank 为何必须组合且依赖 validation starter。

2.12动手清单与自查表（照着核对）

本章零件最多、最容易"写了一半就乱"。下面这张清单把要建的文件、每步怎么验、卡住去哪查三件事固定下来。建议边写边勾。

① 你要建的文件（建一个，勾一个）

② 分步验收：从零到跑通（每步都有预期输出）

1. 编译：mvn -q compile。预期：BUILD SUCCESS。

2. 启动，确认日志里出现 Started SpringaiLabApplication。

3. 先验 2.1 的两种写法（基础中的基础）：

   curl -s -X POST http://localhost:8080/api/v1/prompt/role \
     -H "Content-Type: application/json" \
     -d '{"question":"一句话说明什么是提示词模板"}'

   预期：一段正常中文回答。

4. 验 2.2 的模板渲染（重点看参数真的被填进去了）：

   curl -s -X POST http://localhost:8080/api/v1/prompt/template \
     -H "Content-Type: application/json" \
     -d '{"role":"银行合规助手","audience":"普通储户","maxWords":150,"question":"什么是存款保险"}'

   预期：回答以「银行合规助手」口吻、面向普通储户、长度大约 150 字以内。

   看到什么算通过：三个占位符都生效。若回答口吻不对或没提"储户" → 参数名写错或方法只传了 question。

5. 验 2.4 的少样本分类（本章唯一可精确断言的一处）：

   curl -s -X POST http://localhost:8080/api/v1/prompt/few-shot/messages \
     -H "Content-Type: application/json" \
     -d '{"question":"我要退款"}'

   预期：返回体里只有一个分类词，必须等于 退款（不是一句话、不是解释）。

   对不上怎么查：模型把示例当问题回答了 → 回去检查提示词里有没有写「以下是示例，请勿回答示例」。

6. 验 2.7 的记忆与隔离（本章正式验收动作，三轮必须连做、中间不能重启应用）：

   # 第 1 轮：先告诉它订单号
   curl -s -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"u1001","sessionId":"s1","message":"我的订单号是 2024001，帮我看看"}'
   
   # 第 2 轮：同 userId + 同 sessionId（应记得订单号）
   curl -s -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"u1001","sessionId":"s1","message":"刚才那个订单号是多少？"}'
   
   # 第 3 轮：换成另一个 sessionId（应"失忆"）
   curl -s -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"u1001","sessionId":"s2","message":"刚才那个订单号是多少？"}'

   预期与判据：

   • 第 1 轮：客服口吻回答，并围绕 2024001 展开。
   • 第 2 轮：必须答出 2024001——答不出说明记忆没生效（见下方"对不上怎么查"）。
   • 第 3 轮：回答「你没提供过订单号」之类——必须答不出，答得出说明会话没隔离。

   对不上怎么查：① 三轮之间应用有没有重启过——内存版记忆重启即失忆；② 前两轮的 userId 与 sessionId 是否严格一致（大小写、空格都算）；③ 日志里 CONVERSATION_ID 的值是否每次都传了、且非 null（2.0 漏传会直接抛 IllegalArgumentException）。

7. 验参数校验（反例）：故意漏掉一个字段：

   curl -i -s -X POST http://localhost:8080/api/v1/customer-service/chat \
     -H "Content-Type: application/json" \
     -d '{"userId":"","sessionId":"s1","message":""}'

   预期：首行 HTTP/1.1 400。看到什么算通过：必须不是 200。

   拿到 200 怎么查：说明 @NotBlank 是个"摆设"——检查参数上有没有同时写 @Valid（只写 @NotBlank 不生效），以及 pom 里有没有 spring-boot-starter-validation。

8. 跑一次批量冒烟（把 12 个接口一次过一遍，省得一个个敲）：

   # 工程根目录下的冒烟脚本（2.7 节已给出内容）
   bash smoke-test.sh

   预期：逐条打印 HTTP 状态 + 是否通过，末尾汇总通过数。失败行的提示语会直接告诉你方向（"无响应"=应用没起，"401"=密钥问题）。

③ 卡住了去哪查（症状 → 定位）