15  Prompt 模板

15.1 Prompt 模板概述

Prompt 模板是可复用的 Markdown 片段，通过斜杠命令（/name）快速展开为完整的提示词。模板支持参数展开，让你可以为常见工作流创建标准化的提示词。

例如，创建一个 /review 模板，每次代码审查时只需输入 /review 即可展开为包含详细审查要点的大段提示词。

15.2 模板位置

Pi 从以下位置加载 Prompt 模板：

位置	作用域	说明
~/.pi/agent/prompts/*.md	全局	所有项目共享
.pi/prompts/*.md	项目级	需项目受信任后加载
包的 prompts/ 目录	包级	通过 Pi 包分发
settings.json 的 prompts 数组	配置	指定文件或目录
--prompt-template <path>	CLI	仅本次运行

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

Note

模板发现是非递归的——只扫描 prompts/ 目录顶层的 .md 文件。如果需要子目录中的模板，通过 settings 或包清单显式添加。

15.3 格式

每个模板是一个 Markdown 文件，文件名（不含 .md）即为命令名：

文件名	命令
review.md	/review
component.md	/component
pr.md	/pr

15.3.1 基本格式

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

15.3.2 Frontmatter 字段

字段	必需	说明
description	❌	模板描述，显示在自动补全中。省略时使用第一行非空文本
argument-hint	❌	参数提示，显示在描述之前的自动补全中

15.3.3 参数提示（Argument Hints）

使用 argument-hint 在自动补全中显示期望的参数：

---
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

使用 <angle brackets> 表示必选参数，[square brackets] 表示可选参数：

argument-hint: "<required> [optional]"

15.4 使用方式

在编辑器中输入 / 后跟模板名：

/review                    # 展开 review.md
/component Button          # 带参数展开
/component Button "click"  # 多参数

15.5 参数支持

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

15.5.1 位置参数

语法	说明
$1, $2, …	位置参数
$@ 或 $ARGUMENTS	所有参数连接
${1:-default}	参数 1 存在时用参数 1，否则用 default
${@:-default}	所有参数存在时用所有参数，否则用 default
${@:N}	从第 N 个位置开始的参数（1 索引）
${@:N:L}	从第 N 个位置开始取 L 个参数

15.5.2 参数示例

模板文件 component.md：

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

使用：

/component Button "onClick handler" "disabled support"

展开为：

Create a React component named Button with features: "onClick handler" "disabled support"

15.5.3 默认值示例

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

不带参数使用 /summary 时，默认使用 7 个要点。 带参数使用 /summary 3 时，使用 3 个要点。

15.6 实用模板示例

15.6.1 代码审查模板

~/.pi/agent/prompts/review.md：

---
description: Comprehensive code review of staged changes
argument-hint: "[focus-area]"
---
Review the staged changes (`git diff --cached`). Focus on ${1:-general quality}:

- **Bugs**: Logic errors, edge cases, off-by-one errors
- **Security**: Input validation, auth issues, data exposure
- **Performance**: N+1 queries, unnecessary re-renders, memory leaks
- **Maintainability**: Naming, comments, code organization
- **Testing**: Missing tests, test quality, coverage gaps

Output format:
1. Summary of changes
2. Issues found (by severity)
3. Suggestions for improvement

15.6.2 PR 创建模板

~/.pi/agent/prompts/pr.md：

---
description: Create a pull request from current branch
---
Help me create a pull request for the current branch.

1. Run `git log main..HEAD --oneline` to see commits
2. Run `git diff main...HEAD` to see all changes
3. Generate a PR title following conventional commits format
4. Write a detailed PR description including:
   - What changed and why
   - How to test
   - Breaking changes (if any)
   - Screenshots (if UI changes)

Use the format: `$1` for additional context.

15.6.3 调试模板

~/.pi/agent/prompts/debug.md：

---
description: Debug an issue systematically
argument-hint: "<error-description>"
---
Help me debug this issue: $@

Follow this debugging process:
1. **Understand**: Reproduce and understand the error
2. **Isolate**: Find the minimal reproduction case
3. **Investigate**: Trace the code path and identify root cause
4. **Fix**: Propose a fix with explanation
5. **Verify**: Suggest tests to prevent regression

15.7 加载规则

• 模板发现在 prompts/ 目录中是非递归的
• 如需子目录中的模板，通过 prompts settings 或包清单显式添加
• 同名模板按优先级覆盖：项目级 > 包级 > 全局
• 模板在发送或排队之前展开

Tip

将团队常用的提示词模板放在项目的 .pi/prompts/ 目录中，通过 git 共享给所有团队成员，确保每个人都使用相同的提示词标准。