L01-09 PromptTemplate 与外部化

全局中心内容：提示词是配置，不是代码。 全局讲解主线：硬编码有什么错 → 模板引擎与目录约定 → 外置加载 → 现场改文件看效果变化。

P1 · 产出页

中心内容：改一句提示词，不用重新打包。

页面内容
- resources/prompts/*.st 集中管理
- 变量占位、版本标识
- 开发环境改完即生效
讲解技巧
- 用工作量对比开场：「调 prompt 是每天要做十几次的事，每次发版你受得了吗？」。
- 预告本节最后会现场改一个文件、刷新页面看风格变化。
时长：20s

中心内容：把配置写死在代码里，在任何技术栈都是坏味道。

页面内容
- 改一个字要编译部署
- 无法版本对比，出问题不知道是谁改的
- 同样角色设定在五处各写一遍
- 字符串拼接即注入入口
讲解技巧
- 类比迁移：「这等于把 application.yml 的内容写死在 Java 类里」。一句话让所有人立刻理解。
- 第四点现场演示：用户输入里带 % 时 String.format 直接抛异常。
时长：2min

中心内容：StringTemplate 处理转义，手写 format 会炸。

页面内容
- .st 语法：你是一个{role}，请用{tone}回答
- 引擎负责转义，避免特殊字符破坏结构
- 手写 String.format 遇 % 抛异常
讲解技巧
- 现场演示 % 炸掉：这是真实会发生的线上事故，比讲道理有力得多。
- 一句话结论：永远用模板变量，不要拼字符串。
时长：2min 30s

中心内容：默认 classpath，开发期切文件系统，平台化再上配置中心。

页面内容
- ClassPathResource：打包进 jar，部署简单（生产默认）
- 文件系统：改完即生效（本地调优 / 容器挂载）
- 配置中心：热更新、灰度、A/B（04-02）
讲解技巧
- 给出演进路径而不是三选一：不同阶段用不同方式，不是非此即彼。
- 强调第二阶段用 @ConditionalOnProperty 隔离，生产绝不能开——谁改了挂载目录就能改模型行为。
时长：2min

中心内容：按复用性分目录，不按业务模块分。

页面内容
- system/ 角色（assistant、code-reviewer）
- task/ 任务（ticket-extract、summarize、classify）
- guard/ 护栏（safety-prefix）
讲解技巧
- 解释为什么按复用性分：角色和护栏被多个业务复用，按业务分会导致重复。
- 举反例：按业务分成 order/、payment/，两边各写一份「不得输出密钥」，改的时候漏一处就是漏洞。
时长：2min 30s

中心内容：改模板必须同步改 @version。

页面内容
- 顶部 @version v1.2 + @author + @change
- 版本号写进日志
- 线上出问题时第一个要确认的就是「用的哪版」
讲解技巧
- 讲一个排查场景：「线上效果突然变差，你第一个要问的是哪版 prompt 在跑。没有版本号，只能靠猜」。
- 给出可执行约定：改模板必须改版本号，把它写进 Code Review 清单。
时长：3min

中心内容：用 tpl.create(Map) 生成 Prompt，别手工拼。

页面内容
- PromptRegistry.of("system/assistant")
- tpl.create(Map.of(...))
- chatClient.prompt(prompt).user(question)
- system 与 user 分离
讲解技巧
- 强调 system/user 分离的两个理由：模型对 system 遵循度更高；system 固定时部分厂商支持前缀缓存降本（埋 02-15 伏笔）。
- 展示 PromptRegistry 里「模板不存在时抛清晰错误」的设计——模糊的 NPE 最浪费时间。
时长：4min

中心内容：改一个字，回答风格立刻变。

页面内容
- 改外部 assistant.st：直接给结论 → 先讲历史背景
- 刷新页面，风格变化
- 三条避坑：变量改名静默输出 {xxx}、别拼用户输入、改了要改版本号
讲解技巧
- 这个现场演示是全节高潮：不重启、不打包，风格就变了。这一刻学员会真正接受「prompt 是配置」。
- 第一条避坑给防御做法：校验渲染结果中不得再出现 {，出现就抛异常。
时长：2min

项	内容
课前必做	准备好 `prompt-workspace/` 目录与热加载开关；预演一次改文件看效果
最容易超时处	P4 的演进路径，容易展开讲配置中心选型——收住，说「04-02 讲」
学员最常问	「能不能让运营改 prompt？」答：配置中心阶段可以，但要加审批与回滚
现场备用	热加载不生效 → 用重启方式演示，主线（外置 + 版本）不受影响