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

# Prompt block

Prompt block 是由 Editor 管理、可重用的指令 template。Agent 的指令可結合 inline 文字、嵌入式 prompt block，以及對獨立版本化 prompt block 的引用。

Studio 工作流程及常見用途請參閱 [Prompt block](https://mastra.zisheng.pro/zh-HK/docs/editor/overview)。

## Block 類型

| 類型                 | 描述                         |
| ------------------ | -------------------------- |
| `text`             | 只儲存在 Agent 版本中的自由格式文字      |
| `prompt_block`     | 嵌入 Agent 版本的 prompt block  |
| `prompt_block_ref` | 對獨立儲存及版本化 prompt block 的引用 |

被引用的 block 會在執行階段解析。遺失或未發佈的引用會從最終指令中略過。解析後的非空 block 會以兩個換行符連接。

以下範例將已儲存的 block 及 inline 文字附加至 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.' },
  ],
})
```

## Template 值

Template 會在執行階段從 request context 解析值。

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

變數名稱必須以字母或底線開首。Fallback 必須是以單引號或雙引號括起的字串。沒有 fallback 而無法解析的 placeholder 會維持不變。物件和陣列會序列化為 JSON，其他值則會轉換為字串。

請透過 [request context](https://mastra.zisheng.pro/zh-HK/docs/server/request-context) 傳入值。Editor 不會讀取另一個 Agent `variables` 欄位。

## 顯示條件

Prompt block 可包含顯示條件，用於控制它是否包括在最終指令內。每個條件分為三部分：

- **鍵：** 要檢查的 request context 欄位，例如 `user.role` 或 `account.plan`。
- **運算子：** 要進行的比較，例如 `equals`、`contains` 或 `exists`。
- **值：** 要比較的值。`exists` 和 `not_exists` 運算子不需要值。

例如，條件 `user.role` `equals` `admin` 只會在 request context 包含 `{ user: { role: 'admin' } }` 時加入 block。

| 運算子                                            | 範例                                            | 加入 block 的情況    |
| ---------------------------------------------- | --------------------------------------------- | --------------- |
| `equals` / `not_equals`                        | `user.role` equals `admin`                    | 欄位嚴格等於或不等於該值    |
| `contains` / `not_contains`                    | `user.tags` contains `beta`                   | 字串包含該值，或陣列包含該項目 |
| `greater_than` / `less_than`                   | `order.total` greater than `100`              | 數值欄位高於或低於該值     |
| `greater_than_or_equal` / `less_than_or_equal` | `account.seats` greater than or equal to `10` | 數值欄位達到或超越該值     |
| `in` / `not_in`                                | `user.region` in `['US', 'CA']`               | 欄位在或不在提供的陣列中    |
| `exists` / `not_exists`                        | `account.plan` exists                         | 欄位有或沒有非 null 值  |

群組以 `AND` 或 `OR` 組合條件。例如，以下群組會為使用付費方案的管理員加入 block：

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

支援以點號表示的路徑。空群組的評估結果為 `true`，未知運算子的結果為 `false`。儲存類型最多支援三層巢狀群組。

沒有條件的 block 一律會加入。

## 編程 API

透過 `mastra.getEditor().prompt` 存取 prompt block。完整方法簽名請參閱 [`prompt` namespace](https://mastra.zisheng.pro/zh-HK/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()` 會建立新 draft。使用 `list()` 分頁瀏覽已儲存的 block、`getById()` 擷取一個 block，以及 `preview(blocks, context)` 透過 draft 引用解析 template 和條件。

## REST API

Mastra 伺服器的預設 prefix 是 `/api`。自訂伺服器 prefix 會更改以下路徑。

| 方法       | 路徑                                               | 描述                  |
| -------- | ------------------------------------------------ | ------------------- |
| `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 預覽則解析最新 draft。共用的 draft、發佈和還原生命週期請參閱 [Editor 版本控制](https://mastra.zisheng.pro/zh-HK/docs/editor/overview)。