AI 工作流里的提示词怎么集中管理不散落？

学完这篇，你能把散落在代码注释、聊天记录、Notion 页面和同事脑子里的提示词收拢到一个 Git 仓库里统一管理，并让程序按名字和版本号去取，而不是到处复制粘贴字符串。

第一步：建一个独立的提示词仓库，先定目录结构

这一步要做的，是把提示词从业务代码里拆出来，单独成一个 Git 仓库，做完你会得到一个可以独立提交、独立回滚的提示词目录。

在本机执行：

mkdir ai-prompts && cd ai-prompts
git init
mkdir -p prompts/support prompts/writing prompts/analysis

目录按「业务场景」分，不按「模型」分。因为同一个场景可能先跑 GPT-4o 再换 Claude，按模型分会让你每次换模型都要搬家。每个提示词一个文件，文件名用小写英文加连字符，例如 prompts/support/refund-reply.yaml。

注意：不要把提示词写成 prompt_v2_final_真的最终版.txt。版本交给 Git 管，文件名只描述用途。

第二步：用 YAML 给每个提示词加元数据头

这一步要做的，是让每个提示词文件自带身份信息，做完后你打开任意一个文件就知道它给谁用、跑什么模型、谁负责。

prompts/support/refund-reply.yaml 内容示例：

id: support.refund-reply
version: 1.0.0
owner: zhangsan@example.com
model: gpt-4o
temperature: 0.3
updated_at: 2025-06-01
variables:
  - order_id
  - user_message
content: |
  你是电商客服。用户订单号是 {{order_id}}，用户说：{{user_message}}
  请用不超过 120 字回复，先共情，再给结论，最后给下一步操作。

三个字段必须有：id（全局唯一，程序按它取）、version（语义化版本）、owner（出问题找谁）。

注意：variables 列表要和你 content 里的 {{ }} 占位符严格对应。后面 CI 会检查这一项，不写会直接报错。

第三步：写一个加载器，让代码按 id 取提示词

这一步要做的，是写 30 行左右的 Python 把文件读进内存，做完后业务代码里再也不会出现长提示词字符串。

环境要求 Python 3.11 以上，安装依赖：

pip install PyYAML==6.0.2 jinja2==3.1.4

在同仓库建 loader.py：

import yaml, pathlib
from jinja2 import Template

ROOT = pathlib.Path(__file__).parent / "prompts"
_cache = {}

def load(prompt_id: str, **kwargs):
    if prompt_id not in _cache:
        for f in ROOT.rglob("*.yaml"):
            data = yaml.safe_load(f.read_text(encoding="utf-8"))
            if data["id"] == prompt_id:
                _cache[prompt_id] = data
                break
        else:
            raise KeyError(f"未找到提示词 {prompt_id}")
    data = _cache[prompt_id]
    return Template(data["content"]).render(**kwargs)

调用方只写一行：

prompt = load("support.refund-reply", order_id="A123", user_message="我要退款")

改提示词只改 YAML，不改 Python，业务代码零改动。

第四步：用 CI 卡住格式错误

这一步要做的，是在合并前自动检查 YAML 是否合法、变量是否对齐、id 是否重复，做完后坏提示词进不了主分支。

在仓库建 .github/workflows/lint.yml：

name: lint-prompts
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install PyYAML==6.0.2
      - run: python scripts/check.py

scripts/check.py 做三件事：解析每个 YAML；检查 variables 里的每个名字在 content 中都以 {{名字}} 出现；把所有 id 收集起来查重，重复就 sys.exit(1)。

注意：id 重复是最隐蔽的坑——加载器遍历到第一个匹配就返回，重复 id 会让某个提示词永远不生效，而且不报错。所以查重必须在 CI 里做，不能靠人看。

第五步（可选）：接一个在线平台做灰度

如果团队需要非开发同学改提示词、或要做 A/B 测试，可以在 Git 之上再叠一层 Langfuse（自建版 Docker 镜像 langfuse/langfuse:2）或 Dify。做法是：Git 仍是唯一事实来源，CI 通过后把 YAML 推送到平台生成一个「生产版本号」，代码读取时先读平台缓存、失败则回落本地文件。

注意：别让平台变成第二个事实来源。规则定死——只在平台上改、改完必须回写 Git，否则半年后你又有两份提示词了。

小结

• 提示词单独建仓库，按业务场景分目录，文件名只描述用途。
• 每个 YAML 必须有 id、version、owner，变量用 {{ }} 并在 variables 里声明。
• 业务代码只调用 load("场景.id", **参数)，不出现提示词字符串。
• CI 必须查三件事：YAML 合法、变量对齐、id 不重复。
• 在线平台只做分发和灰度，Git 始终是唯一事实来源。