# 提示词模板

> 用 Markdown 片段定义可通过 /name 调用的提示词模板，支持参数与默认值。

---

LLMS 索引： [llms.txt](/llms.txt)

---

> pi 可以创建提示词模板。让它为你的工作流构建一个吧。

提示词模板是可以展开为完整提示词的 Markdown 片段。在编辑器中输入 `/name` 即可调用模板，其中 `name` 是不含 `.md` 扩展名的文件名。

## 存放位置 {#locations}

Pi 从以下位置加载提示词模板：

- 全局：`~/.pi/agent/prompts/*.md`
- 项目：`.pi/prompts/*.md`（仅在项目受信任后生效）
- 包：`prompts/` 目录或 `package.json` 中的 `pi.prompts` 条目
- 设置：`prompts` 数组，包含文件或目录
- CLI：`--prompt-template <path>`（可重复指定）

使用 `--no-prompt-templates` 可禁用模板自动发现。

## 格式 {#format}

```markdown
---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps
```

- 文件名即为命令名。`review.md` 对应 `/review`。
- `description` 是可选的。如果缺失，则使用第一个非空行。
- `argument-hint` 也是可选的。设置后，该提示会显示在自动补全下拉列表中描述的前面。

### 参数提示 {#argument-hints}

在 frontmatter 中使用 `argument-hint` 可以在自动补全中显示预期的参数。必选参数使用 `<angle brackets>` 表示，可选参数使用 `[square brackets]` 表示：

```markdown
---
description: Review PRs from URLs with structured issue and code analysis
argument-hint: "<PR-URL>"
---
```

在自动补全下拉列表中的渲染效果如下：

```
→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
  is   <issue>        — Analyze GitHub issues (bugs or feature requests)
  wr   [instructions] — Finish the current task end-to-end
  cl   — Audit changelog entries before release
```

## 用法 {#usage}

在编辑器中输入 `/` 加模板名。自动补全会显示可用模板及其描述。

```
/review                           # Expands review.md
/component Button                 # Expands with argument
/component Button "click handler" # Multiple arguments
```

## 参数 {#arguments}

模板支持位置参数、默认值和简单的切片操作：

- `$1`、`$2`……位置参数
- `$@` 或 `$ARGUMENTS` 表示所有参数拼接后的内容
- `${1:-default}` 在第 1 个参数存在且非空时使用该参数，否则使用 `default`
- `${@:-default}` 或 `${ARGUMENTS:-default}` 在参数存在且非空时使用全部参数，否则使用 `default`
- `${@:N}` 表示从第 N 个位置开始的参数（从 1 计数）
- `${@:N:L}` 表示从第 N 个开始的 `L` 个参数

示例：

```markdown
---
description: Create a component
---
Create a React component named $1 with features: $@
```

默认值对可选参数很有用：

```markdown
Summarize the current state in ${1:-7} bullet points.
```

用法：`/component Button "onClick handler" "disabled support"`

## 加载规则 {#loading-rules}

- 在 `prompts/` 目录中发现模板的过程是非递归的。
- 如果要把模板放在子目录中，请通过 `prompts` 设置或包清单显式添加。