> For the complete documentation index, see [llms.txt](https://doc.duaer.com/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/zh/guides/prompt-version-control-github-retry.md).

# GitHub 提示词版本控制：面向 2027 年企业 AI 团队的实施手册

本文整理自 Duaer 文档站，讨论企业团队如何借助 GitHub 管理提示词版本，涵盖版本化边界、仓库结构、评估门禁、模型固定、回滚观测以及一周内可落地的第一步。

## 为什么提示词不适合沿用常规的 Git 习惯

大多数企业团队接触提示词的方式都很相似：有人把一段长指令粘贴进聊天窗口，输出看起来不错，这段文字便悄悄变成了生产环境的逻辑。几个月后，没人能说清哪一版措辞正在线上运行，是谁修改了拒答规则，也不知道为什么某个周二的一次「小调整」之后回答质量下降了。把提示词放进 GitHub 是显而易见的解决办法，但这个办法背后藏着几个陷阱，因为提示词文件的行为与 Git 最初设计所针对的源代码并不相同。

在普通软件中，一个 diff 通常就能告诉审阅者大部分需要的信息。支付函数里改了一行，就是支付函数里改了一行。提示词的 diff 则不同：在拉取请求里把「简洁」改成「精炼」看似无关紧要，却可能在成千上万次回答中改变语气、篇幅以及边缘情况的处理方式。文字本身清晰可读，但它的实际效果并不会体现在 diff 里。

这意味着，仅靠版本历史只能回答「改了什么」，无法回答「这次改动带来了什么效果」。企业团队两者都需要。应当把每一次提示词提交都视为一个关于模型行为的假设，并为它附上证据。

## 先界定资产边界，再设计仓库结构

在创建仓库之前，先明确你要版本化的单元。跳过这一步的团队，最终会发现提示词散落在笔记本、配置文件、环境变量和应用代码之中。一个可行的边界通常包括系统指令、少样本示例、输出结构定义、工具描述，以及该提示词测试时所用的模型名称和参数。这些内容都会影响行为，因此应当放在同一个版本化的数据包中。

不要把机密信息放进仓库。示例提示词中出现的 API 密钥、客户数据和内部地址，都应在提交前替换为占位符。一旦包含真实客户记录的仓库被克隆到个人笔记本上，它就会成为合规问题。

仓库结构应当便于评审，而不只是便于存储。对于试点项目，一个扁平的文本文件夹勉强可用，但进入生产后就会失效。更好的做法是每个提示词一个目录，其中包含模板文件（纯文本或 YAML）、一个测试用例配套文件，以及一份简短的变更日志，说明每个版本的意图。使用 CODEOWNERS 机制，使面向客户的提示词变更需要产品负责人和领域审阅者签字确认，而不只是工程师批准。

使用标签或发布分支标记每个环境当前部署的版本。应用应引用一个具体的版本号，而不是名为 latest 的指针。会被静默移动的指针，正是预发布环境的编辑在无人决定的情况下流向客户的原因。

## 将每个提示词版本与评估结果关联

这是大多数团队会跳过的一步，却是让 GitHub 真正对提示词产生价值的关键。每个修改提示词的拉取请求，都应通过 GitHub Actions 等 CI 工作流运行一套固定的评估集，并把结果发布在 diff 旁边。评估集应包含具有代表性的输入、已知的边缘情况，以及模型此前出错过的若干案例。评分方式应结合自动化检查（例如结构是否有效、必填字段是否存在）与对抽样结果的人工评审。

目标不是追求满分。目标是让审阅者在合并之前就能看到：这次改动是否改善了某一类案例，又是否削弱了另一类。没有这一步，提示词版本控制只能提供一份整洁的变更历史，却无人能对其进行评估。

一种实用的做法是把评估用例与提示词保存在同一个仓库中，并与之一同版本化。当评估集发生变化时，提交信息应当予以说明。否则，团队可能只是通过删掉困难案例，就让分数看起来有所提升。

## 固定模型版本，而不只是提示词

提示词是针对特定模型和一组参数测试的。如果服务商更新了底层模型，相同的提示词文本也可能产生不同的输出。应当把模型标识符、温度参数以及任何工具配置，与提示词记录在同一个文件中。升级模型时，应将其视为一个新版本，并经过同样的评估门禁。

这在受监管的业务流程中尤为重要，因为团队需要说明是哪一组提示词与模型的组合产生了某个输出。将这种组合存入 Git，可以获得一条审计线索，但它无法取代运行时所需的日志记录。

## 规划回滚与运行时观测

回滚应当只是一处配置修改，即把应用指回上一个版本号。请在真正需要之前测试这条路径。同时配套运行时监控，在记录每条回复的同时记录提示词版本，这样当质量下降时，你就能判断原因是提示词变更、模型变更，还是输入数据的变化。

许多团队发现，真正困难的并不是存储提示词，而是保持已部署版本、其评估结果与随后产生的线上行为之间的关联。当试点项目走向生产时，这种关联恰恰最容易断裂。如果你想更全面地了解这一交接环节为何容易出问题，可以参阅我们的指南[将 AI 试点推进到生产环境](https://doc.duaer.com/zh/guides/ai-pilot-to-production/)，其中更深入地介绍了集成层面的问题。

## 本周可以落地的第一步

不要试图在第一天就为公司内所有提示词做版本化。挑选一个客户或员工每天都会接触的生产提示词，把它的文本、示例和输出结构定义移入 GitHub 仓库中的同一个文件夹。编写十到二十条评估用例，其中至少包含三个过去的失败案例。添加一个 CI 任务，在每个拉取请求上运行这些用例并自动回复结果。指定一名代码负责人和一名领域负责人。最后，让应用读取一个固定的版本号。

对小团队而言，这大约需要几天时间，并会形成一套可以复用到下一个提示词上的工作模式。如果你的团队希望免去手动拼装每个环节的工作，可以访问 https://www.duaer.com 注册，并在 Duaer 中试用，它的设计目标是将提示词资产、评估运行记录和版本历史集中在同一处。建议先用一个真实的提示词进行测试，再决定它是否适合你的技术栈。

如果你希望获得针对自身场景的书面推进路线，请告诉我们你最想先治理哪一个提示词，以及它会涉及哪些系统。我们会回复一份针对该场景的书面落地路线。

https://api.duaer.com/form/c59a907a-3697-4edf-a04d-3ea0fb72fdc8

GitHub 上的提示词版本控制与其说是存储问题，不如说是让每一次变更都可评审、可测试、可回滚的问题；真正做好的团队，会把每一次提示词编辑都当作对生产行为的一次改动来对待。

## 常见问题

### 提示词应该放在 GitHub 仓库的什么位置，如何组织目录？

建议每个提示词使用独立目录，目录内包含模板文件、测试用例文件和变更日志。系统指令、少样本示例、输出结构定义、工具描述以及测试所用的模型和参数都应放在同一个版本化单元中。仓库应便于评审，同时不得包含真实客户数据或密钥。

### 如何在 GitHub 中为提示词修改做自动化评估？

可以通过 GitHub Actions 等 CI 工作流，在每个修改提示词的拉取请求上运行固定的评估集，并把结果发布在 diff 旁边。评估集应覆盖代表性输入、已知边缘情况和历史失败案例，评分结合自动化检查与人工抽样评审。评估用例变化时，提交信息也应说明原因。

### 提示词版本控制需要怎样的权限与审批流程？

面向客户的提示词建议通过 CODEOWNERS 机制设置审批要求，让产品负责人和领域审阅者参与确认，而不只是工程师批准。应用应引用具体的版本号而非 latest 指针，以避免未经决策的变更直接影响生产环境。

