把提示词放进 Git 管理,真正要配置的往往是三样东西:目录与命名的约定、随文件一起提交的元数据(版本号、变量清单、归属人),以及能在日志里追溯的运行时版本标识。采用“放在共享盘里、靠文件名区分版本”的做法,基本上没法回退,也没法判断线上出问题的是哪一版。建议先把一个提示词目录按下面的骨架整理好,再接入 CI 校验和发布 tag。
提示词与 Git 结合,关键是让每个提示词都有稳定的 id、可读的版本文件和一份声明变量与当前版本的 manifest,并用 Git commit 或 tag 作为运行时版本标识写入日志。适合有一定量提示词、需要多人改动和回退的场景;如果提示词一天改十几次、需要线上热更新,或包含密钥等信息,就不适合全放在仓库里,需要拆分配置来源。
先确认当前场景和目标
先判断现在属于哪一类情况:提示词由固定几个人维护、改动频率不高、上线前有人 review,那么用 Git 管理,成本很低,收益也明确;提示词由运营直接在后台编辑、每次都要即时生效,那么 Git 更适合做“发布源”,也就是按版本发布,不宜当作“实时编辑入口”。这两种情况的处理方式不同,不要混着做。
需要先确认的几件事:
- 提示词总数和改动频率,决定要不要按目录分组,以及是否需要 manifest 索引。
- 提示词里有没有占位变量(如
{{order_id}}),变量名是否与代码里的传参一致。 - 仓库里是否会出现密钥、内部数据、真实用户样例;一旦有,就必须先拆分出去。
- 线上调用侧能否拿到并记录版本标识(commit 短哈希或 tag),拿不到就先补日志字段。
按这个顺序处理
第一步是确定目录结构。每个提示词一个目录,版本用文件区分,manifest 指向当前使用的版本:

prompts/
support_triage/
manifest.yaml
v1.md
v2.md
order_summary/
manifest.yaml
v1.md
第二步是写 manifest,把版本、变量、归属人集中声明。下面是一份可替换的通用示例,字段名可以按团队习惯改:
id: support_triage
current: v2
owner: cs-platform
model: <模型名>
variables:
- order_id
- user_tier
change_note: 改动原因写在 PR 描述里,这里只留一句摘要
第三步是给提示词正文加上与 manifest 对齐的头部信息,方便单文件查看时也能确认身份:

---
id: support_triage
version: v2
variables: [order_id, user_tier]
---
你是一名客服助理,请结合订单 {{order_id}} 和用户等级 {{user_tier}} 给出处理建议。
第四步是加一个校验脚本,放进 CI 的必过检查。脚本只做两件事:manifest 指向的文件是否存在,正文里用到的变量和 manifest 声明的变量是否一致。这是一个通用骨架,按实际仓库路径替换即可:
import pathlib, re, sys, yaml
errors = []
for d in pathlib.Path("prompts").iterdir():
if not d.is_dir():
continue
m = yaml.safe_load((d / "manifest.yaml").read_text(encoding="utf-8"))
cur = d / f"{m['current']}.md"
if not cur.exists():
errors.append(f"{d.name}: current={m['current']} 对应文件不存在")
continue
used = set(re.findall(r"\{\{\s*(\w+)\s*\}\}", cur.read_text(encoding="utf-8")))
declared = set(m.get("variables") or [])
if used != declared:
errors.append(f"{d.name}: 变量不一致 used={sorted(used)} declared={sorted(declared)}")
if errors:
print("\n".join(errors))
sys.exit(1)
print("ok")
第五步是把版本标识接到运行时。发布时打一个 tag(如 prompt-2024-xx 这类团队自定的命名),调用侧把 commit 短哈希和提示词 id 一起写进日志或追踪字段。下面只是拼接逻辑的骨架,不是某个 SDK 的真实接口:
import pathlib, subprocess
commit = subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], text=True).strip()
body = pathlib.Path("prompts/support_triage/v2.md").read_text(encoding="utf-8")
version_tag = f"support_triage@v2+{commit}"
# 调用模型时,把 version_tag 写入日志/追踪字段,正文另行传入
第六步是提交与评审约定:一次提交只改一个提示词、提交信息写清 id 和版本,保护主分支、要求 review,发布用 tag 而不是靠分支名表达状态。

改完后怎么验证
验证分三层,逐层确认即可:
- 本地或 CI 跑校验脚本,预期输出
ok、退出码为 0;再故意把正文里的{{order_id}}改成{{orderid}},预期脚本报变量不一致并以非零退出,确认拦截生效。 - 用旧 tag 检出一次(例如
git checkout <上一个 tag>),再跑校验脚本,预期同样通过,说明历史版本仍可加载,回退路径可用。 - 触发一次实际调用,检查日志或追踪里是否出现
support_triage@v2+<commit>这类标识;如果日志里只有提示词正文而没有版本标识,说明第五步没接上。
预期信号是:同一份提示词在仓库、运行日志、发布 tag 三处能对上同一个版本号。对不上就说明中间某一处是手工维护的,需要改成从同一来源取。
容易忽略的边界
- 变量名是代码与提示词之间的约定,重命名变量必须同步改代码,否则校验脚本通过、运行时照样报错;建议变量改名和代码改动放在同一个 PR。
- 提示词里不要写密钥、真实用户数据或内部业务规则原文;需要引用时用占位符,由运行时注入。
- 不要把 Git 分支当作环境(dev/staging/prod 各一条长期分支),容易出现分支互相合并、环境和版本对不上;用 tag 或发布记录表达上线版本更清楚。
- 模型参数(温度、最大输出长度)与提示词放在同一份 manifest 里便于对照,但两者变更节奏不同,参数调整不一定需要新提示词版本,版本号是否升要事先约定。
- 如果提示词需要后台实时编辑、或一天改很多次,Git 这条路会变成频繁提交和频繁发布,此时更合适的是把 Git 当作基线版本,运行时配置另存,并保持两者可对比。
- 回退建议:优先
git revert到目标版本对应的提交,重新走一次发布;如果调用侧有提示词缓存,回退后要确认缓存已刷新,再观察日志里的版本标识是否变成目标版本。