Prompt 为什么需要版本管理？
简化版
Prompt 是影响生产行为的代码和配置，必须版本化才能复现回答、做回归、灰度和快速回滚。版本不应只包含一段文本，还要绑定模型、模板变量 schema、示例、工具定义、检索配置和输出契约；每次变更记录原因、评测结果与兼容性，发布后按版本监控质量、成本和安全。
详细版
采用不可变 prompt_id@version，语义化区分破坏性契约变更、行为调整和不影响行为的元数据修订。源文件进入 Git 评审，注册表保存渲染资产与依赖 manifest；线上请求记录版本和最终 Prompt 哈希，禁止在原版本上静默编辑。
发布流程是离线 golden set、安全与格式门禁，随后 canary/A-B 分桶，再逐步放量。缓存 key、指标和日志都带版本，发生问题一键切回已验证版本。回滚 Prompt 时还要检查 schema、解析器与模型兼容，不能只替换文本造成接口错配。
编辑 -> 评审 -> 不可变版本 -> 离线回归 -> 灰度 -> 放量
| |
└--- 回滚 <---┘完整版教学
一、没有版本为何无法复现
同一个用户问题今天和昨天输出不同，可能来自 Prompt、模型、temperature、检索数据或工具描述。若线上 Prompt 被直接覆盖，只知道“当前文本”，历史事故就无法重放。不可变版本把某次行为绑定到确定资产。
复现单位应是完整运行 manifest，而非单文件。动态变量值可以因隐私只保存哈希或受控快照，但模板、依赖版本和来源 ID 必须记录。版本管理的第一价值是回答“当时到底运行了什么”。
二、版本边界包含哪些依赖
Prompt 行为由系统消息、few-shot、output schema、工具定义、模型与检索共同决定。示例更新即使主模板不变，也可能改变输出；schema 改字段则会破坏解析器。把这些依赖纳入 manifest，才能判断兼容性。
prompt: support_answer@2.3.0
model: model-x@2026-09-01
examples: support_cn@7
schema: answer@2
tools: support_tools@4
retrieval_profile: hybrid@9记忆钩子：Prompt 版本不是文本的文件名，而是一次模型行为所依赖资产的锁文件。
三、版本号如何表达变化
可借鉴语义化版本：主版本表示输出契约、权限语义等破坏性变化；次版本表示兼容的行为改进；补丁版本表示小修。但生成行为没有严格二进制兼容，版本号只是沟通工具，是否兼容仍由测试证明。
| 变更 | 建议版本 | 必要动作 |
|---|---|---|
| 删除/改名输出字段 | major | 消费者迁移 |
| 增加 optional 字段 | minor | 兼容测试 |
| 改 few-shot | minor | 行为回归 |
| 修注释不进模型 | patch | 基础检查 |
| 更换模型 | 新 manifest | 全量回归 |
禁止复用版本号发布不同内容，注册表可用内容哈希保证不可变。
四、变更评审应看什么
Diff 不只看文字是否通顺，还要说明问题、假设、影响切片、Token 变化和安全边界。自动检查未绑定变量、角色结构、schema、一致术语和禁止泄密。评审者应能看到旧新版本在固定样本上的成对输出，而非只看模板 diff。
变更说明包含回滚条件和 owner。紧急修复也创建新版本，可缩短流程但不能原地修改；事后补齐测试和复盘。这样团队不会失去事故时间线。
五、回归与发布门禁
每版跑核心任务、历史失败、边界注入、格式和成本集。开放输出用规则、校准 Judge 与人工抽查组合，报告切片而非只有平均分。若输出 Token 增长 40%，即使质量略升也可能超预算。
先在 1% canary 验证解析和严重安全，再逐步到 10%、50%、100%。A/B 分桶按用户或会话稳定，指标带版本标签。发布工具阻止没有测试报告的版本直接成为默认。
六、缓存和状态为什么要感知版本
语义缓存若只按用户问题做 key，发布新版后可能继续返回旧 Prompt 生成的答案，实验被污染。key 至少包含 Prompt/模型/检索/权限相关版本。缓存失效策略随发布执行，不能期待 TTL 慢慢过期。
多轮会话也要决定固定旧版还是中途迁移。固定版体验一致，但长期会话停留旧策略；迁移需重新构造状态并检查 schema。安全热修复应强制迁移，普通风格改动可新会话生效。
七、回滚并不只是切文本
新 Prompt 可能依赖 schema v2 和新解析器，单独回到旧文本却仍用 v2 消费者，会产生错误。部署单元应包含兼容依赖，回滚到完整 manifest。数据库或外部动作若已发生，Prompt 回滚也无法撤销，需要业务补偿。
保持最近多个已验证版本热可用，并定期演练。触发条件可为格式失败率、任务成功率、安全事件或 P95 超阈值。回滚后继续保存故障版本流量和证据，不要立即覆盖现场。
八、常见误区与追问
- 误区：Prompt 只是文案，存 Git 历史就够了。 还需绑定模型、示例、schema、检索和发布状态。
- 误区：小改一个词不需要回归。 模型行为非线性，小改也可能影响边界样本。
- 误区：回滚就是复制旧 Prompt。 必须回滚兼容的完整依赖 manifest。
- 追问：线上热修复怎么办？ 创建不可变紧急版本、canary 后切流量，不能覆盖旧版本。
- 追问：如何复现含动态 RAG 的请求？ 保存索引版本、文档 ID、得分和最终上下文哈希/受控快照。
- 追问：版本号还是内容哈希？ 版本号供人理解，内容哈希保证不可变，两者一起用。
九、加强记忆
Prompt 版本管理可记成“全依赖、不可变、有评测、能灰度、整包回滚”。把模板、模型、示例、schema、工具和检索锁成 manifest；每次改动保留原因与成对结果；缓存、日志和指标都带版本；出事切回完整已验证组合。这样 Prompt 才真正具备生产软件应有的可追溯性。