在 LLM 应用开发中，prompt 工程是核心瓶颈之一。散乱的提示文本难以复用、版本化和自动化，导致重复编写和调试成本高企。Runprompt 作为一款轻量 CLI 工具，通过执行标准 .prompt 文件，将 prompt 转化为可参数化、可链式的模板系统，实现从手工敲命令到脚本化调用的跃升。该工具特别适用于脚本自动化、数据管道和 CI/CD 场景，支持多模型路由和结构化输出，避免了 LLM API 调用的 boilerplate 代码。
.prompt 文件格式源于 Google 的 dotprompt 规范，采用 YAML frontmatter + Markdown 正文结构。前者定义模型路由、输入/输出 schema，后者为提示模板，支持 {{var}} 变量替换和特殊占位符如 {{STDIN}}。例如，一个基本模板 hello.prompt：
---
model: anthropic/claude-sonnet-4-20250514
---
Say hello to {{name}}!
通过 echo '{"name": "World"}' | ./runprompt hello.prompt，工具自动替换变量并调用指定模型。GitHub 仓库显示，该脚本仅单文件 Python，无依赖，curl 下载即可运行。[1]
更进一步，Runprompt 支持结构化 JSON 输出。通过 output.schema 定义字段类型和描述，实现工具化的解析。例如 extract.prompt：
---
model: anthropic/claude-sonnet-4-20250514
input:
schema:
text: string
output:
format: json
schema:
name?: string, the person's name
age?: number, the person's age
occupation?: string, the person's job
---
Extract info from: {{text}}
输入 echo "John is a 30 year old teacher" | ./runprompt extract.prompt 输出 {"name": "John", "age": 30, "occupation": "teacher"}。可选字段以 ? 结尾，支持复杂类型描述。该功能借鉴工具调用规范，确保输出可机读，便于下游脚本处理。
链式调用是 Runprompt 的亮点：JSON 输出可直接 pipe 到下一个提示。例如，先提取信息，再生成 bio：
echo "John is 30" | ./runprompt extract.prompt | ./runprompt generate-bio.prompt
此模式模拟 prompt 流水线，适用于 ETL、多轮推理或 RAG 管道。相比 Jupyter notebook 或 Web UI，CLI 管道更轻量，支持 bash 脚本封装。
落地参数与清单如下，确保生产级部署：
1. 安装与环境配置
- 下载：
curl -O https://raw.githubusercontent.com/chr15m/runprompt/main/runprompt && chmod +x runprompt
- API Keys（必填，必环境变量）：
| Provider |
模型格式示例 |
Env Var |
| Anthropic |
anthropic/claude-sonnet-4-20250514 |
ANTHROPIC_API_KEY |
| OpenAI |
openai/gpt-4o |
OPENAI_API_KEY |
| Google AI |
googleai/gemini-1.5-pro |
GOOGLE_API_KEY |
| OpenRouter |
openrouter/anthropic/claude-... |
OPENROUTER_API_KEY |
- 默认覆盖：
export RUNPROMPT_MODEL=anthropic/claude-3-haiku-20240307
2. 模板设计清单
- Frontmatter 最小：model，必填。
- 输入 Schema：定义 JSON 输入字段，避免运行时错误。
- 输出 Schema：字段格式
name?: type, description，提升解析准确率 >95%。
- 变量：{{STDIN}} 处理原始 stdin；CLI 参数
--var value 覆盖。
- 提示正文：使用 Markdown，保持 <4K token，避免截断。
3. CLI 参数与最佳实践
./runprompt [options] <file.prompt> [json-stdin]
-v 详细日志（请求/响应）
--model X 覆盖模型
--var Y=Z 覆盖变量
- 重试逻辑：无内置，封装 bash wrapper：
for i in {1..3}; do
result=$(./runprompt prompt.prompt)
[ $? -eq 0 ] && echo "$result" && exit 0
sleep $((i*2))
done
echo "Failed after retries" >&2; exit 1
- 缓存：无内置，使用
jq + 文件存储中间 JSON：
cache="cache.json"
[ -f "$cache" ] || (echo input | ./runprompt > "$cache")
cat "$cache"
- 监控阈值：OpenRouter 等提供 token 使用，脚本中解析响应头；超时设 60s（
timeout 60 ./runprompt）。
- 回滚策略：多模型 fallback，
RUNPROMPT_MODEL=backup-model。
4. 工程化集成
在 HN 讨论中，该工具获 21 points，强调其简洁性适合脚本党。[2] 与 code2prompt 等工具互补，前者打包代码库，此处专注 prompt 执行。总体，Runprompt 降低了 prompt 工程门槛，推动 LLM 从实验到生产。
资料来源：
[1] https://github.com/chr15m/runprompt
[2] https://news.ycombinator.com/ (Show HN 帖子)