模板、变量与版本管理
本节目标
把散落在代码中的字符串升级为有负责人、有版本、有评测证据的工程资产。
模板的组成
将稳定内容与变量分开：
policy：任务目标、输出契约、不可违反的边界；examples：经过审核的少量样例；context：检索到的证据，带来源；input：本次用户数据；metadata：模板版本、语言、实验组，不发给模型的字段应留在程序侧。
不要直接用 Python str.format() 接收任意含花括号的 JSON 文本，也不要通过执行模板表达式来渲染用户输入。选择只替换已声明变量的简单渲染器，并对长度、类型和来源做校验。
模板放在哪里
稳健的默认基线是把提示正文、schema 与案例当作应用代码旁的受审查资产：进入版本控制，经过 code review，并能随应用版本回滚。供应商托管功能若仍存在，只能作为动态的发布或运行机制；仓库内经测试的资产与发布映射才是可审计事实来源。
这是动态能力，不能沿用旧教程。按 OpenAI 2026-07-21 的提示工程、迁移与弃用页面，可复用 prompt objects 于 2026-06-03 宣布弃用，v1/prompts 与相关对象计划在 2026-11-30 停止服务；官方迁移方向是把提示内容移入应用代码，用类型化参数、仓库评审、测试和发布流程管理。该时间线只描述 OpenAI 当前公告，不代表其他供应商，也不保证未来不会调整。
版本不是文件名上的 v2
一个可复现调用至少记录：
prompt_id: ticket-router
prompt_version: 1.3.0
schema_version: 1.1.0
model_configuration_id: provider-alias-2026-07
evaluation_set: routing-golden-2026-07文字修正但行为预期不变可作补丁版本；字段或规则变化应提升较大版本并迁移消费者。具体采用何种版本策略不重要，关键是旧请求能定位到当时的提示、schema 和配置。版本字符串本身仍可能“忘记升级”，因此关键实验还应记录提示、schema 与数据集的内容哈希；本库项目会拒绝案例声明的版本与代码内资产不一致。
发布流程
- 提交提示和 schema 的小范围变更。
- 在固定离线样例与受控线上影子流量上评测。
- 检查总体指标和关键切片，尤其是高风险失败。
- 小流量灰度，监控解析错误、延迟、用量和人工纠正。
- 达到门槛后扩大；保留快速回退到前一版本的能力。
不要在同一次实验中同时换提示、模型、检索和后处理，否则无法归因。
隐私与日志
默认不记录完整原始提示。记录哈希、版本、字段长度、脱敏错误类别和请求 ID 往往已经足够。确需保留样本时，先确定访问权限、保留期和删除流程。密钥只能来自环境变量或密钥管理服务，不能写入模板。
练习与自测
设计一份提示变更记录，至少包含变更原因、预期改善的失败类别、评测集版本、通过门槛、回退条件和负责人。自测：三个月后能否复现某次错误输出使用的确切合同？
掌握检查
- 提示正文、schema、案例和模型配置都拥有可追溯版本。
- 变量有明确类型、长度与来源，高权限策略不与用户文本拼接。
- 一次实验只改变一个主要因素，并预先写好发布与回退门槛。
- 使用供应商托管对象前，我会核对当前生命周期与迁移公告。
下一步
进入 评测驱动迭代，为发布流程补上可执行的证据。
参考资料
- OpenAI：Prompt engineering（访问于 2026-07-21）
- OpenAI：Migrate from prompt objects（访问于 2026-07-21）
- OpenAI：API deprecations—Reusable prompts（访问于 2026-07-21）
- Anthropic：Prompt engineering overview（访问于 2026-07-21）