Dotprompt：可执行的生成式AI提示模板

Dotprompt 是一种用于生成式AI的可执行提示模板文件格式。它设计为与编程语言和模型提供商无关，以实现最大的使用灵活性。Dotprompt 在流行的 Handlebars 模板语言基础上扩展了针对生成式AI的特定功能。

包版本

包	版本	注册表
核心库
dotprompt (JS/TS)		npm
dotpromptz (Python)		PyPI
dotpromptz-handlebars (Python)		PyPI
dotprompt-go (Go)		pkg.go.dev
dotprompt-rs (Rust)		crates.io
dotprompt-java (Java)		Maven Central
IDE 扩展
dotprompt-vscode		VS Marketplace
dotprompt-jetbrains		JetBrains
dotprompt-vim	-	GitHub
dotprompt-emacs	-	GitHub
Web 编辑器
dotprompt-monaco		npm
dotprompt-codemirror		npm
工具
tree-sitter-dotprompt		npm
promptly		npm

CI 状态

工作流	状态	描述
语言测试
Go		Go 库测试
Python		Python dotprompt 测试
JavaScript		JS/TS 库测试
Java		Java 库测试
Rust		Rust 库测试
Bazel		Bazel 构建与测试
Handlebarrz		Python Handlebars 测试
IDE 和编辑器插件
VS Code		VS Code 扩展
IDE 插件		Vim、Emacs、JetBrains
Web 编辑器		Monaco、CodeMirror
Tree-sitter		语法与解析器
代码质量
Go Lint		golangci-lint

什么是可执行的提示模板？

可执行的提示模板不仅包含提示文本，还包含元数据以及如何将该提示与生成式 AI 模型结合使用的说明。以下是使 Dotprompt 文件具备可执行性的关键点：

• 元数据包含：Dotprompt 文件包含关于模型配置、输入要求和预期输出格式的元数据。这些信息通常存储在文件开头的 YAML 前置内容部分中。

• 自包含实体：由于 Dotprompt 文件包含了执行提示所需的所有必要信息，因此它可以被视为一个自包含的实体。这意味着你可以直接“运行”一个 Dotprompt 文件，而无需在代码中进行额外的配置或设置。

• 模型配置：文件指定了要使用的模型以及如何对其进行配置（例如温度、最大标记数）。

• 输入模式：它定义了提示所期望的输入数据结构，从而支持验证和类型检查。

• 输出格式：文件可以指定模型输出的预期格式，用于解析和验证。

• 模板化：提示文本本身使用 Handlebars 语法，允许根据输入变量动态插入内容。

这些特性的结合使得 Dotprompt 文件可以被视为一个可执行单元，从而简化了与 AI 模型协作的过程，并确保同一提示在不同场景下的使用一致性。

示例 .prompt 文件

以下是一个从给定文本中提取结构化数据的 Dotprompt 文件示例：

---
model: googleai/gemini-2.5-pro
input:
  schema:
    text: string
output:
  format: json
  schema:
    name?: string, 人的全名
    age?: number, 人的年龄
    occupation?: string, 人的职业
---

请从给定文本中提取所需信息。如果某项信息不存在，则在输出中省略该字段。

文本: {{text}}

这个 Dotprompt 文件：

1. 指定了使用 googleai/gemini-2.5-pro 模型。
2. 定义了一个期望 text 字符串作为输入的模式。
3. 指定了输出应为 JSON 格式。
4. 提供了预期输出的模式，包括姓名、年龄和职业字段。
5. 使用 Handlebars 语法 ({{text}}) 将输入文本插入到提示中。

当执行此提示时，它将接收一个文本输入，使用指定的 AI 模型进行分析，并返回一个包含提取信息的结构化 JSON 对象。

安装

本入门指南的剩余部分将使用包含在 Genkit 中的参考 Dotprompt 实现，Genkit 是面向应用开发者的 GenAI SDK。若要使用其他 Dotprompt 实现，请参阅实现列表。

首先，使用 NPM 安装必要的包。这里我们将使用来自 Google 的 Gemini API 作为模型实现：

npm i genkit @genkit-ai/googleai

安装完成后，您需要设置环境并初始化 Dotprompt 系统。以下是一个基本设置示例：

import { genkit } from "genkit";
import { googleAI } from "@genkit-ai/googleai";

// 使用 GoogleAI 提供者和 Dotprompt 插件配置 Genkit
const ai = genkit({
  plugins: [googleAI()],
  // promptDir: 'prompts', /* 这是默认值 */
});

// 现在您已经可以使用 Dotprompt 了！

注意： 您需要将 Google AI API 密钥设置为 GOOGLE_API_KEY 环境变量，或者将其作为选项传递给 googleAI() 插件配置。

完成上述设置后，您现在可以在项目中创建 .prompt 文件，并在代码中使用它们。例如，如果您有一个名为 extractInfo.prompt 的文件，内容与前面的示例相同，您可以这样使用它：

const extractInfo = ai.prompt("extractInfo");

const { output } = await extractInfo({
  text: "John Doe 是一名 35 岁的软件工程师，居住在纽约。",
});

console.log(output);
// 输出：{ "name": "John Doe", "age": 35, "occupation": "software engineer" }

通过这种设置，您可以充分利用 Dotprompt 的强大功能，使您的 AI 交互更加结构化、可重用且易于维护。

按照这些步骤操作，您将拥有一个可用的 Dotprompt 基本设置。在此基础上，您可以创建更复杂的提示模板，将其集成到您的应用程序中，并以结构化、基于模板的方式充分发挥生成式 AI 的潜力。

贡献

我们欢迎贡献！请参阅我们的开发指南，了解以下内容：

• 各种语言的代码风格和 linting 要求
• 测试要求
• Git 提交信息规范

提交信息格式

我们使用 Conventional Commits 规范，并以包名称作为作用域：

feat(dotpromptz): 添加新的辅助函数
fix(dotprompt-go): 解决解析边缘情况
docs(dotprompt-java): 更新 API 文档

作用域	包
dotprompt	JavaScript/TypeScript (js/)
dotpromptz	Python dotpromptz (python/dotpromptz/)
dotpromptz-handlebars	Python Handlebars (python/handlebarrz/)
dotprompt-go	Go (go/)
dotprompt-rs	Rust (rs/)
dotprompt-java	Java (java/)
dotprompt-vscode	VS Code 扩展
dotprompt-jetbrains	JetBrains 插件
tree-sitter-dotprompt	Tree-sitter 语法
promptly	.prompt 文件的 CLI 工具

完整的作用域列表和指南请参阅 GEMINI.md。

Dotprompt 快速上手指南

Dotprompt 是一种可执行的生成式 AI 提示词模板文件格式。它基于 Handlebars 模板语法扩展，支持在文件中直接定义模型配置、输入/输出 Schema 及元数据，实现语言无关且自包含的提示词管理。

环境准备

• 操作系统：Windows, macOS, Linux
• 运行时依赖：
  • Node.js (推荐 v18 或更高版本)
  • npm 或 yarn 包管理器
• API 密钥：需要拥有 Google AI API Key (或其他支持的模型提供商密钥)

安装步骤

本指南基于 Genkit SDK（Dotprompt 的参考实现）进行演示。

1. 初始化项目并安装依赖 在项目目录下运行以下命令，安装核心库及 Google AI 插件：

   npm i genkit @genkit-ai/googleai
   

   国内加速建议：如果 npm 下载缓慢，建议使用淘宝镜像源： npm config set registry https://registry.npmmirror.com

2. 配置环境变量 设置你的 Google AI API 密钥。在终端执行：

   export GOOGLE_API_KEY="你的_API_密钥"
   

   (Windows PowerShell: $env:GOOGLE_API_KEY="你的_API_密钥")

基本使用

1. 创建提示词文件

在项目根目录创建 prompts 文件夹（默认目录），并在其中新建一个名为 extractInfo.prompt 的文件。

文件内容 (prompts/extractInfo.prompt)：

---
model: googleai/gemini-2.5-pro
input:
  schema:
    text: string
output:
  format: json
  schema:
    name?: string, the full name of the person
    age?: number, the age of the person
    occupation?: string, the person's occupation
---

Extract the requested information from the given text. If a piece of information
is not present, omit that field from the output.

Text: {{text}}

该文件定义了：

• 模型：使用 gemini-2.5-pro。
• 输入：期望接收一个 text 字符串。
• 输出：强制返回 JSON 格式，并定义了字段结构。
• 模板：使用 {{text}} 动态插入变量。

2. 编写调用代码

新建一个 TypeScript 文件（如 index.ts），编写以下代码加载并执行提示词：

import { genkit } from "genkit";
import { googleAI } from "@genkit-ai/googleai";

// 初始化 Genkit 并加载 Google AI 插件
const ai = genkit({
  plugins: [googleAI()],
  // promptDir: 'prompts', /* 默认为 'prompts' 目录 */
});

async function main() {
  // 加载名为 'extractInfo' 的 prompt 文件
  const extractInfo = ai.prompt("extractInfo");

  // 执行提示词，传入符合 input schema 的数据
  const { output } = await extractInfo({
    text: "John Doe is a 35-year-old software engineer living in New York.",
  });

  console.log(output);
  // 预期输出: { "name": "John Doe", "age": 35, "occupation": "software engineer" }
}

main().catch(console.error);

3. 运行结果

执行代码后，Dotprompt 会自动读取 .prompt 文件中的元数据，调用指定模型，并根据定义的 Output Schema 将结果解析为结构化 JSON 对象返回。