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

# 提示詞區塊

提示詞區塊是由 Editor 管理、可重複使用的指示範本。Agent 的指示可結合內嵌文字、內嵌提示詞區塊，以及對獨立版本化提示詞區塊的參照。

Studio 工作流程與常見用途請參閱[提示詞區塊](https://mastra.zisheng.pro/zh-TW/docs/editor/overview)。

## 區塊類型

| 類型                 | 說明                    |
| ------------------ | --------------------- |
| `text`             | 只儲存在 Agent 版本中的任意格式文字 |
| `prompt_block`     | 內嵌於 Agent 版本的提示詞區塊    |
| `prompt_block_ref` | 對獨立儲存且有版本管理之提示詞區塊的參照  |

被參照的區塊會在執行階段解析。缺少或未發布的參照會從最終指示中省略。解析後的非空區塊會以兩個換行字元串接。

下列範例會將已儲存的區塊與內嵌文字附加至 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}}` |

變數名稱必須以字母或底線開頭。後援值必須是以單引號或雙引號括住的字串。沒有後援值的未解析預留位置會保持不變。物件與陣列會序列化為 JSON。其他值則會轉換為字串。

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

## 顯示條件

提示詞區塊可包含顯示條件，用以控制是否將其納入最終指示。每個條件包含三個部分：

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

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

| 運算子                                            | 範例                                | 納入區塊的條件          |
| ---------------------------------------------- | --------------------------------- | ---------------- |
| `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 值 |

群組使用 `AND` 或 `OR` 結合條件。例如，下列群組會為使用付費方案的管理員納入區塊：

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

支援點號路徑。空群組會求值為 `true`，未知的運算子則會求值為 `false`。儲存類型最多支援三層巢狀群組。

沒有條件的區塊一律會納入。

## 程式化 API

透過 `mastra.getEditor().prompt` 存取提示詞區塊。完整方法簽章請參閱 [`prompt` 命名空間](https://mastra.zisheng.pro/zh-TW/reference/editor/mastra-editor)。

建立提示詞區塊：

```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"}}.',
})
```

更新現有區塊：

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

內容變更時，`update()` 會建立新草稿。使用 `list()` 分頁瀏覽已儲存的區塊、使用 `getById()` 擷取單一區塊，並使用 `preview(blocks, context)` 解析範本和帶有草稿參照的條件。

## REST API

Mastra 伺服器的預設前綴為 `/api`。自訂伺服器前綴會變更下列路徑。

| 方法       | 路徑                                               | 說明          |
| -------- | ------------------------------------------------ | ----------- |
| `GET`    | `/api/stored/prompt-blocks`                      | 列出已儲存的提示詞區塊 |
| `POST`   | `/api/stored/prompt-blocks`                      | 建立已儲存的提示詞區塊 |
| `GET`    | `/api/stored/prompt-blocks/:storedPromptBlockId` | 取得已儲存的提示詞區塊 |
| `PATCH`  | `/api/stored/prompt-blocks/:storedPromptBlockId` | 更新已儲存的提示詞區塊 |
| `DELETE` | `/api/stored/prompt-blocks/:storedPromptBlockId` | 刪除已儲存的提示詞區塊 |

## 版本解析

執行階段參照會解析作用中且已發布的區塊。Editor 預覽會解析最新草稿。共用的草稿、發布與還原生命週期請參閱 [Editor 版本管理](https://mastra.zisheng.pro/zh-TW/docs/editor/overview)。