> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Prompt blocks

Prompt block 是由 Editor 管理的可复用指令模板。Agent 的指令可以组合内联文本、嵌入式 prompt block，以及对独立版本化 prompt block 的引用。

有关 Studio 工作流和常见用法，请参阅 [Prompt block](https://mastra.zisheng.pro/docs/editor/overview)。

## Block 类型

| 类型                 | 描述                          |
| ------------------ | --------------------------- |
| `text`             | 仅存储在 Agent 版本中的自由格式文本       |
| `prompt_block`     | 嵌入在 Agent 版本中的 prompt block |
| `prompt_block_ref` | 对独立存储和版本化的 prompt block 的引用 |

引用的 block 会在运行时解析。缺失或未发布的引用会从最终指令中省略。解析后的非空 block 使用两个换行符连接。

以下示例将已存储的 block 和内联文本附加到 Agent：

```typescript
import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: [
    { type: 'prompt_block_ref', id: 'brand-voice' },
    { type: 'text', content: 'Answer only questions about Acme products.' },
  ],
})
```

## 模板值

模板会在运行时从 request context 解析值。

| 语法                        | Request context              | 输出                 |
| ------------------------- | ---------------------------- | ------------------ |
| `{{userName}}`            | `{ userName: 'Maya' }`       | `Maya`             |
| `{{user.name}}`           | `{ user: { name: 'Maya' } }` | `Maya`             |
| `{{task \|\| 'request'}}` | `{}`                         | `request`          |
| `{{missingValue}}`        | `{}`                         | `{{missingValue}}` |

变量名必须以字母或下划线开头。Fallback 必须是单引号或双引号字符串。没有 fallback 的未解析占位符会保持不变。对象和数组会序列化为 JSON，其他值会转换为字符串。

通过 [request context](https://mastra.zisheng.pro/docs/server/request-context) 传递值。Editor 不会读取单独的 Agent `variables` 字段。

## 显示条件

Prompt block 可以包含显示条件，用于控制是否将其纳入最终指令。每个条件包含三部分：

- **Key**：要检查的 request context 字段，例如 `user.role` 或 `account.plan`。
- **Operator**：要执行的比较，例如 `equals`、`contains` 或 `exists`。
- **Value**：用于比较的值。`exists` 和 `not_exists` operator 不需要此值。

例如，仅当 request context 包含 `{ user: { role: 'admin' } }` 时，条件 `user.role` `equals` `admin` 才会包含该 block。

| Operator                                       | 示例                                | 包含该 block 的条件    |
| ---------------------------------------------- | --------------------------------- | ---------------- |
| `equals` / `not_equals`                        | `user.role` 等于 `admin`            | 字段严格等于或不等于该值     |
| `contains` / `not_contains`                    | `user.tags` 包含 `beta`             | 字符串包含该值，或数组包含该项  |
| `greater_than` / `less_than`                   | `order.total` 大于 `100`            | 数值字段大于或小于该值      |
| `greater_than_or_equal` / `less_than_or_equal` | `account.seats` 大于或等于 `10`        | 数值字段大于等于或小于等于该值  |
| `in` / `not_in`                                | `user.region` 位于 `['US', 'CA']` 中 | 字段在或不在给定数组中      |
| `exists` / `not_exists`                        | `account.plan` 存在                 | 字段具有或不具有非 null 值 |

Group 使用 `AND` 或 `OR` 组合条件。例如，以下 group 会为使用付费方案的管理员包含一个 block：

```typescript
const rules = {
  operator: 'AND',
  conditions: [
    {
      field: 'user.role',
      operator: 'equals',
      value: 'admin',
    },
    {
      field: 'account.plan',
      operator: 'in',
      value: ['pro', 'enterprise'],
    },
  ],
}
```

支持点路径。空 group 的求值结果为 `true`，未知 operator 的求值结果为 `false`。存储类型最多支持三层嵌套 group。

不带条件的 block 始终会被包含。

## 编程 API

通过 `mastra.getEditor().prompt` 访问 prompt block。完整的方法签名请参阅 [`prompt` 命名空间](https://mastra.zisheng.pro/reference/editor/mastra-editor)。

创建 prompt block：

```typescript
import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.prompt.create({
  id: 'brand-voice',
  name: 'Brand voice',
  description: 'Acme tone and style guidelines',
  content: 'Write in a friendly, concise tone. Address the user as {{userName || "there"}}.',
})
```

更新现有 block：

```typescript
await editor.prompt.update({
  id: 'brand-voice',
  content: 'Write in a friendly, concise tone. Greet the user by name when available.',
})
```

内容发生变化时，`update()` 会创建新草稿。使用 `list()` 对已存储 block 进行分页，使用 `getById()` 获取单个 block，使用 `preview(blocks, context)` 通过草稿引用解析模板和条件。

## REST API

Mastra 的默认服务器前缀为 `/api`。自定义服务器前缀会更改下列路径。

| 方法       | 路径                                               | 描述                  |
| -------- | ------------------------------------------------ | ------------------- |
| `GET`    | `/api/stored/prompt-blocks`                      | 列出已存储的 prompt block |
| `POST`   | `/api/stored/prompt-blocks`                      | 创建已存储的 prompt block |
| `GET`    | `/api/stored/prompt-blocks/:storedPromptBlockId` | 获取已存储的 prompt block |
| `PATCH`  | `/api/stored/prompt-blocks/:storedPromptBlockId` | 更新已存储的 prompt block |
| `DELETE` | `/api/stored/prompt-blocks/:storedPromptBlockId` | 删除已存储的 prompt block |

## 版本解析

运行时引用会解析当前已发布 block。Editor 预览会解析最新草稿。有关共享的草稿、发布和恢复生命周期，请参阅 [Editor 版本控制](https://mastra.zisheng.pro/docs/editor/overview)。