#如何设计 Prompt 版本管理系统

Prompt 一旦进入生产环境，就一定会被修改。

它会因为模型升级而调整，因为业务规则变化而调整，因为线上差评而调整，因为安全问题而调整，也会因为不同用户、不同语言、不同租户而出现多个变体。

如果没有版本管理，Prompt 修改会变成一种高风险操作：不知道谁改了什么，不知道线上正在用哪版，不知道问题能不能复现，也不知道怎么回滚。

Prompt 版本管理系统要解决的不是“保存多份文本”，而是让 Prompt 的变化可控。

#版本系统要回答的问题

一个合格的版本管理系统，至少要能回答这些问题：

• 某个功能当前生产环境使用哪个 Prompt 版本？
• 这个版本是谁创建的，为什么创建？
• 它经过了哪些测试和审批？
• 哪些流量正在使用新版本？
• 某次 AI 输出对应哪个 Prompt、模型和参数？
• 如果新版本出问题，多久能回滚？
• 旧版本是否还能被审计和复现？

这些问题听起来像发布系统，而不是普通配置中心。Prompt 版本管理本质上就是一个面向 AI 行为的发布系统。

#核心数据模型

建议把 Prompt 的稳定身份和具体版本拆开。

prompt_keys 表示一个功能语义，例如 writing.summary、support.reply、code.explain。它应该稳定，不随着内容变化而变化。

prompt_versions 表示某一次具体内容和策略。

还需要一张发布表，记录不同环境、租户或流量规则当前指向哪个版本。

这样做的好处是，版本本身不可变，发布指针可以变化。回滚时不需要改旧内容，只需要把生产指针切回上一个稳定版本。

#版本号怎么设计

版本号可以用语义化版本，也可以用递增版本。关键是团队要约定版本变化的含义。

一种实用规则是：

• major：任务目标、输出协议或安全边界发生变化。
• minor：新增规则、改进语气、调整示例，不破坏调用方。
• patch：修正文案、补充边界约束、小范围修复。

例如 2.1.3 表示第二个大版本下的一次小修复。

如果团队不想维护语义化版本，也可以使用 v42 这种递增版本，但 changelog 必须写清楚影响范围。不要使用“最终版”“线上版”“新版本 2”这种无法排序和审计的命名。

#状态机设计

Prompt 版本应该有明确状态机。

状态机的价值是限制危险操作。例如 draft 不能直接进 production，archived 不能再编辑，production 版本不能原地修改。

推荐的规则是：版本一旦进入 staging，就不要再原地改内容。如果发现问题，回到 draft fork 新版本。这样测试结果、审批记录和内容快照才能保持一致。

#工程化设计

Prompt 版本系统可以分成五个模块。

Admin UI 面向前端工程师很关键。它不只是表单，还应该提供：

• Prompt Diff，突出指令、变量、输出格式的变化。
• 变量预览，输入样例后看到最终渲染结果。
• 测试报告，显示通过率、失败样例、输出差异。
• 发布历史，显示谁在什么时候把哪个版本推到哪个环境。
• 回滚入口，明确回滚目标和影响范围。

Runtime 侧要做 Prompt Resolver。业务代码不应该写死版本号，而是按 prompt_key + environment + tenant/user + experiment 解析当前版本。

type ResolvePromptInput = {
  key: string;
  environment: 'staging' | 'production';
  tenantId?: string;
  userId?: string;
  experimentId?: string;
};

解析结果应该包含模板内容、变量 schema、模型策略、安全策略和版本 id。AI run 日志必须记录这个版本 id。

#流程与权限

Prompt 发布流程建议最少包含四道门。

第一道门是作者自检。作者要填写 changelog、影响范围和测试说明。

第二道门是工程评审。重点看变量、输出协议、token 成本、是否影响前端解析。

第三道门是业务或内容评审。重点看语气、口径、事实边界和用户体验。

第四道门是安全评审。重点看系统指令、工具权限、敏感信息、越权风险和 injection 样例。

权限不要只分“管理员”和“普通用户”。更合理的是按能力拆分：

回滚权限要谨慎但不能太慢。线上事故时，值班人员应该能快速把发布指针切回上一版，同时系统自动记录操作原因。

#测试与发布门禁

Prompt 版本管理系统必须和测试集绑定。否则版本只是文本快照，不能判断质量。

测试集可以分为几类：

• golden cases：代表核心能力的标准样例。
• regression cases：历史线上问题和修复样例。
• format cases：验证 JSON、Markdown、字段枚举和 schema。
• safety cases：提示泄露、越权指令、恶意输入。
• cost cases：超长输入和 token 预算边界。

发布门禁可以是自动规则：

• 格式解析通过率达到 100%。
• 安全样例不得出现高危失败。
• token 成本增长不超过阈值。
• 核心样例人工评分不低于上一版。
• 失败样例必须被 reviewer 确认。

灰度阶段还要看线上指标：

• 用户差评率。
• 重试率。
• 输出解析失败率。
• 平均 token 成本。
• 首 token 时间和总延迟。
• 安全拦截或异常工具调用次数。

新版本只有在测试和线上观测都稳定时，才应该全量。

#常见坑

第一个坑是允许生产版本原地编辑。这样日志里的版本 id 就失去意义，因为同一个版本在不同时间代表不同内容。

第二个坑是只记录 Prompt 内容，不记录模型策略。Prompt 和模型参数共同决定输出，版本系统必须把它们作为一个发布单元管理。

第三个坑是没有环境隔离。staging 和 production 指向同一份可变内容，会导致测试还没结束，线上已经被影响。

第四个坑是灰度只按随机流量，不考虑租户和场景。有些 Prompt 只在特定业务线高风险，灰度规则应该支持租户、用户组、功能入口和实验分组。

第五个坑是回滚只恢复 Prompt，不恢复关联配置。如果新版同时改了输出 schema、前端解析或工具权限，只回滚文本可能不够。发布记录要能描述关联变更。

第六个坑是 changelog 太随意。“优化效果”“调整提示词”没有排查价值。好的 changelog 要写清楚问题、改动、预期影响和风险。

#小结

Prompt 版本管理系统的核心设计，是把“文本修改”变成“可审计发布”。

它需要稳定 key、不可变版本、环境发布指针、状态机、权限、测试门禁、灰度和回滚。对前端工程师来说，这套系统并不陌生：它像配置平台、实验平台和发布平台的结合体，只是管理对象从 UI 配置变成了 AI 行为。

当每次 AI 输出都能追到具体 Prompt 版本，当每次 Prompt 修改都能测试和回滚，团队才真正拥有持续迭代 AI 功能的底气。