System prompt 定义了 Agent 的角色、语气和约束。Yao 支持一个默认提示词，以及多套可在运行时选择的命名预设。
## 默认提示词
`prompts.yml` 放在 Assistant 目录的根目录，是默认 system prompt，每次对话开始时都会发送给 LLM，除非被覆盖。
```yaml
# assistants/my-assistant/prompts.yml
- role: system
content: |
You are a helpful writing assistant.
Focus on clarity and brevity.
Ask for clarification when the request is ambiguous.
```
这里通常只使用 `system` role，但引擎不强制限制 role 类型。
### 上下文变量
在提示词内容中使用内置变量：
```yaml
- role: system
content: |
Today is $SYS.DATE ($SYS.WEEKDAY). Current time: $SYS.TIME.
User locale: $CTX.LOCALE. User ID: $CTX.USER_ID.
```
| 变量 | 值 |
|------|-----|
| `$SYS.DATE` | 当前日期，如 `2026-04-20` |
| `$SYS.TIME` | 当前时间，如 `14:30:00` |
| `$SYS.DATETIME` | 日期 + 时间 |
| `$SYS.TIMEZONE` | 系统时区 |
| `$SYS.WEEKDAY` | 星期几，如 `Monday` |
| `$CTX.LOCALE` | 用户语言，如 `en-us` |
| `$CTX.USER_ID` | 当前用户 ID |
| `$CTX.TEAM_ID` | 当前团队 ID |
| `$CTX.CHAT_ID` | 当前会话 ID |
| `$ENV.KEY` | 任意环境变量 |
### 嵌入外部文件
引用 `assets/` 目录下的外部文件。支持的类型：`.md`、`.txt`、`.yml`、`.yaml`、`.json`。
```yaml
- role: system
content: |
@assets/guidelines.md
@assets/examples.txt
@assets/config.json
```
文件内容在加载时内联展开。
## 多套预设
创建 `prompts/` 目录存放额外的命名预设。每个文件以文件名（去掉扩展名）作为预设标识符。
```
assistants/my-assistant/
├── prompts.yml ← 默认提示词（始终加载，除非被覆盖）
└── prompts/
├── edit.yml ← 预设名："edit"
└── review.yml ← 预设名："review"
```
每个预设文件与 `prompts.yml` 格式相同：
```yaml
# assistants/my-assistant/prompts/edit.yml
- role: system
content: |
You are now in edit mode. The user is revising existing content.
Focus on improving clarity and fixing errors.
Preserve the original intent.
```
## 在 Create Hook 中切换预设
在 `Create` Hook 中返回 `prompt_preset`，为当前请求选择预设：
```typescript
// assistants/my-assistant/src/index.ts
export function Create(
ctx: agent.Context,
messages: agent.Message[]
): agent.Create {
// 从 URL 参数检测编辑模式
const isEdit = ctx.route?.includes("?mode=edit");
if (isEdit) {
return { messages, prompt_preset: "edit" };
}
return { messages }; // 使用默认提示词
}
```
`prompt_preset` 的值对应 `prompts/` 目录下的文件名。如果预设不存在，会回退到默认的 `prompts.yml`。
**真实示例** —— `yao-mark` 根据 URL 是否包含 canvas ID 在 `create`（默认）和 `edit` 提示词之间切换：
```typescript
// From yaobots/assistants/yao/mark/src/index.ts
const existing = detectAndLoadExisting(ctx);
if (existing) {
return { messages, prompt_preset: "edit" };
}
return { messages };
```
## 嵌套预设键
`prompts/` 目录支持子目录，预设键用 `.` 分隔：
```
prompts/
├── chat.yml ← 键："chat"
├── task.yml ← 键："task"
└── analysis/
└── deep.yml ← 键："analysis.deep"
```
```typescript
return { messages, prompt_preset: "analysis.deep" };
```
## 禁用全局提示词
如果 Yao 实例配置了全局 system prompt，可以选择退出：
**按 Assistant 禁用**（在 `package.yao` 中）：
```json
{
"name": "My Assistant",
"connector": "$ENV.DEFAULT_CONNECTOR",
"disable_global_prompts": true
}
```
**按请求禁用**（在 Create Hook 中）：
```typescript
return {
messages,
disable_global_prompts: true,
};
```
## 下一步
Agent 已有明确的角色。接下来为它添加工具。
→ **[接入 MCP 工具](./add-tools)**
