promptpack

promptpack

一组提示词模板往往会悄然产生偏差： 有人重命名了某个模板中的变量，却忘了修改它的声明；某个模板声明了不再使用的变量；版本字符串被误写成 1.2 而不是 1.2.0；直到生产环境中的渲染失败，才有人发现。promptpack 会在问题发生前一次性检查整个模板包。你需要提供每个模板的名称、版本、正文和声明的变量，以及你希望执行的任意测试渲染。promptpack 会将每个正文中实际使用的占位符与其声明进行比较，检查每个版本字符串，使用你提供的值确定性地运行渲染，并返回一份报告。不发布、写入或获取任何内容；你描述的模板包就是唯一输入。

占位符的写法为 {{name}}。只有当占位符内部文本经过去除首尾空格后，是由字母、数字和下划线组成的纯名称时，该片段才算占位符——因此，{{ name }} 是 name 的占位符，而 {{}}、{{first name}}、{{user-name}} 和未闭合的 {{ 都是普通文本：渲染时保持原样，也不会出现在报告中。每个模板的占位符是它使用的不同名称，按它们首次出现在正文中的顺序排列。

对于每个模板，报告都会回显其声明的变量，并列出两类发现：没有声明的占位符（missing_declarations，按占位符顺序排列）和没有被任何占位符使用的声明（unused_declarations，按声明顺序排列）。两类发现都没有的模板为 ok；有任意发现的模板为 issues。版本问题比普通发现更严格：版本必须恰好由三个以点分隔的非负整数构成；模板名称重复或声明的变量重复，都会导致整个输入被拒绝，并指出出错路径——格式错误的输入不会产生部分结果。

测试渲染按你提供的顺序运行。每个测试渲染都会指定一个模板，并提供该模板变量的值。该模板中的每个占位符都会替换为提供的值，且替换文本本身不会再次扫描，因此，若某个值恰好包含 {{other}}，它会保持原样。多余的值会被忽略。如果占位符没有提供对应的值，检查不会因此失败：该渲染条目会报告 ok: false，并按占位符顺序列出不同的缺失名称，其余模板和渲染仍会照常报告。指定模板包中不存在的模板名称，或提供非字符串值，都属于格式错误的输入，并会像其他验证失败一样报错。

CLI

npx @reneturcios/promptpack check --input args.json
npx @reneturcios/promptpack --version

args.json 包含完整的参数对象：

{
  "templates": [
    {
      "name": "welcome",
      "version": "1.2.0",
      "body": "Hi {{name}}, welcome to {{ product }}!",
      "variables": ["name", "product"]
    },
    {
      "name": "reminder",
      "version": "0.3.1",
      "body": "Hi {{name}}, your {{plan}} renews soon.",
      "variables": ["name"]
    }
  ],
  "renders": [
    {
      "template": "welcome",
      "values": { "name": "Ada", "product": "Promptpacks" }
    },
    {
      "template": "reminder",
      "values": { "name": "Ada" }
    }
  ]
}

报告以 JSON 格式打印：

{
  "templates": [
    {
      "name": "welcome",
      "version": "1.2.0",
      "placeholders": ["name", "product"],
      "declared": ["name", "product"],
      "missing_declarations": [],
      "unused_declarations": [],
      "status": "ok"
    },
    {
      "name": "reminder",
      "version": "0.3.1",
      "placeholders": ["name", "plan"],
      "declared": ["name"],
      "missing_declarations": ["plan"],
      "unused_declarations": [],
      "status": "issues"
    }
  ],
  "renders": [
    {
      "template": "welcome",
      "ok": true,
      "rendered": "Hi Ada, welcome to Promptpacks!"
    },
    {
      "template": "reminder",
      "ok": false,
      "missing_values": ["plan"]
    }
  ],
  "counts": {
    "templates": 2,
    "with_issues": 1,
    "renders": 2,
    "renders_ok": 1,
    "renders_failed": 1
  }
}

退出代码：成功时为 0，运行时错误时为 1（包括输入文件不可读或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/promptpack mcp

MCP 客户端配置：

{
  "mcpServers": {
    "promptpack": {
      "command": "npx",
      "args": ["-y", "@reneturcios/promptpack", "mcp"]
    }
  }
}

工具

• check_prompt_pack — 检查调用方提供的提示词模板包：模板中使用的占位符与声明的变量是否一致、版本格式，以及使用提供的值进行的确定性测试渲染。

  • templates（数组，必填，至少 1 项）— 要检查的提示词模板，按包内顺序排列；每项包含：
    • name（字符串，必填，不能为空）— 模板名称，在包内必须唯一
    • version（字符串，必填）— 模板版本，必须恰好由三个以点分隔的非负整数组成（例如 "1.2.0"）
    • body（字符串，必填，可以为空）— 模板文本；占位符写作 {{name}}
    • variables（字符串数组，可选）— 模板声明的变量名；未提供时视为 []
  • renders（数组，可选）— 要对该模板包运行的测试渲染；未提供时视为 []；每项包含：
    • template（字符串，必填，不能为空）— 要渲染的模板名称
    • values（对象，必填）— 渲染所用的值：将变量名映射到替换字符串

  返回 {templates, renders, counts}，其中 templates 按输入模板的顺序，为每个输入模板包含一个 {name, version, placeholders, declared, missing_declarations, unused_declarations, status}；renders 按输入顺序，为每项输入渲染包含一个 {template, ok, rendered} 或 {template, ok, missing_values}；counts 为 {templates, with_issues, renders, renders_ok, renders_failed}。

Docker

docker run -i ghcr.io/cloudcorprecords/promptpack
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/promptpack check --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios