Prompt Registry Pattern：将 Prompt 视作稳定的 API

发布: 1个月前 (2026年3月6日 GMT+8 23:43)

7 分钟阅读

原文: Dev.to

Source: Dev.to

请提供您希望翻译的具体文本内容，我将按照要求保留源链接、格式和代码块，仅翻译正文部分。谢谢！

介绍

如果你曾经构建过一个小的“AI 助手”脚本（或仅仅在 ChatGPT 中复制粘贴提示），你可能已经体会过这种痛苦：

一个提示在星期二表现很好。
你在星期三修改了一句话。
到星期五……一切都表现不同，你却无法解释原因。

我们对代码、模式和 API 进行版本管理。但我们常常把提示当作一次性便利贴来对待。

把提示视为稳定的 API。 为它们命名、设定版本、接受标准和变更日志。然后让你的应用（或团队）通过 ID 来引用提示，而不是通过“某人今天剪贴板里的随意文字”。

目标不是官僚主义。目标是让提示的更改 可审计、可评审且可逆。

当此模式特别有用时

提示被多个人使用
提示在生产环境中运行（代理、自动化、支持机器人）
输出格式很重要（JSON、表格、差异）
您想进行 A/B 测试或安全迭代

“注册表”是什么样子

您不需要数据库。从仓库中的一个文件夹开始。

prompts/
  README.md
  registry.yml
  bug_triage/
    v1.md
    v2.md
  code_review/
    v1.md

两条小规则

每个提示都有一个 ID（例如 bug_triage）。
每个提示都有版本（例如 v1、v2）。

添加一个小的索引文件，以便人和工具能够发现已有的内容。

# prompts/registry.yml
bug_triage:
  latest: v2
  owner: "platform"
  tags: ["support", "json"]
  description: "Turns user bug reports into a minimal reproduction plan"

code_review:
  latest: v1
  owner: "devex"
  tags: ["diff", "quality"]
  description: "Reviews code changes and returns a risk-focused checklist"

现在您的自动化可以说：“使用 bug_triage@latest”，或者 “使用 bug_triage@v1 以获得旧行为”。

可扩展的提示文件模板

将提示拆分为 元数据（前置块）和内容。

---
id: bug_triage
version: v2
status: active
input_contract:
  - user_report: string
output_contract:
  - summary: string
  - suspected_area: string
  - repro_steps: string[]
  - questions: string[]
acceptance_criteria:
  - "Output is valid JSON"
  - "repro_steps is a list of imperative steps"
  - "questions are actionable and minimal"
changelog:
  - "v2: added explicit JSON schema + reduced verbosity"
---

You are a senior support engineer. Your job is to turn a raw user bug report into a minimal reproduction plan.

Constraints:
- Return **only JSON**.
- Do not invent stack traces.
- If information is missing, ask questions instead of guessing.

JSON schema:
{
  "summary": "...",
  "suspected_area": "...",
  "repro_steps": ["..."],
  "questions": ["..."]
}

User report:
{{user_report}}

为什么这样有帮助

前置块可以被工具解析。
正文对人类友好。
验收标准使评审客观（“我们是否破坏了 JSON？”）。

按 ID 调用提示（而不是粘贴）

import { loadPrompt } from "./prompt-registry";

const prompt = loadPrompt("bug_triage", { version: "latest" });
const text = prompt.render({ user_report });

const response = await llm.generate({
  model: "...",
  temperature: 0.2,
  prompt: text,
});

重要细节

记录解析后的版本。如果 latest 解析为 v2，请将其与本次运行一起存储，以便以后能够复现相同的行为。

最小化的“prompt CI”，防止静默破坏

一旦提示被放入文件，你就可以对它们进行测试。

轻量级设置：

一个小的测试语料库（接近真实的输入）
一个运行器，对这些输入执行提示
一个验证器，检查输出契约

示例测试用例

{
  "prompt": "bug_triage",
  "version": "v2",
  "input": {
    "user_report": "App crashes when I click Save. It started after updating yesterday. Windows 11."
  },
  "assert": {
    "json": true,
    "hasKeys": ["summary", "suspected_area", "repro_steps", "questions"],
    "maxQuestions": 5
  }
}

你的验证器可以很简单（JSON 解析 + 键是否存在 + 基本长度检查）。你并不是在证明提示“完美”；而是要防止明显的回归。这正是注册表发挥作用的地方：提示的更改会变成带有测试信号的可审查差异。

何时升级提示版本

将版本视作 API：

Patch（就地编辑），当您修正拼写错误或添加说明而不改变输出时。
Minor（新版本），当您更改约束、输出字段或语气时。
Major（新 ID 或突破性的 “v3”），当下游使用者很可能会因此出错时。

经验法则

如果您需要告诉同事 “注意，结果会有所不同”，就升级版本。

Bonus: 保持 “latest” 与 “pinned” 两条通道

团队通常希望两者兼备：

Pinned 提示用于生产工作流（bug_triage@v2）
Latest 提示用于探索（bug_triage@latest）

这使您能够快速迭代，而不会意外更改生产行为。

小规模开始

您可以在一小时内采用此模式：

创建 prompts/。
添加您已经重复使用的 2–3 条提示。
分配 ID + 版本。
为每个提示编写一个验收标准。

根据我的经验，第一次通过说 “哦，那个运行使用的是 v1，但今天我们使用的是 v2” 来修复 bug 时……您就不会再回头了。

如果您尝试了，我很想听听您选择的结构（每个提示一个文件夹、YAML 索引、JSON 索引，或任何适合您技术栈的方式）。