第 8 章 · Prompt Templates 提示词模板

本章目标：掌握 pi 提示词模板的存放位置、frontmatter 格式、参数化语法与调用方式，学会组织团队共享模板，并厘清模板与 skills 的分工边界。

8.1 模板是什么：可复用的 Markdown 提示词

Prompt Template 就是一个 Markdown 片段文件：输入 /文件名 即可展开成完整提示词。它解决的是"同一段高质量指令反复手打"的问题——代码评审、提交信息生成、周报汇总这类固定流程的指令，都适合做成模板。

pi 从以下位置发现模板（--no-prompt-templates 可整体禁用）：

~/.pi/agent/prompts/*.md      ← 全局个人模板
.pi/prompts/*.md              ← 项目模板（需项目受信任后加载）
包的 prompts/ 目录             ← 随 pi 包分发
settings.json 的 prompts 数组   ← 显式指定文件或目录
CLI: --prompt-template <path> ← 临时加载（可重复）

发现规则是非递归的

prompts/ 目录下的子目录不会被自动扫描。想用子目录组织模板，必须在 settings 的 prompts 数组里显式列出路径，或走包清单声明。

8.2 Frontmatter 与命令名

文件名（去掉 .md）就是命令名：review.md → /review。frontmatter 支持三个字段：

---
description: Review staged git changes
argument-hint: "<PR-URL>"
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps

• description：可选；缺省时取正文第一个非空行；
• argument-hint：可选；在自动补全下拉里提示参数格式，<尖括号> 表示必填、[方括号] 表示可选。

补全效果（官方示例）：

→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
  wr   [instructions] — Finish the current task end-to-end

8.3 参数化：从固定文案到"函数式"模板

模板支持一套类似 shell 的参数语法，这是它比"纯文本片段"强大的地方：

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

/component Button                 # $1=Button, $@=Button
/component Button "click handler" # 多个参数按位置分配

全部参数语法一览：

语法	含义
$1、$2…	第 N 个位置参数
$@ / $ARGUMENTS	全部参数以空格连接
${1:-default}	参数 1 缺省时使用 default
${@:-default}	全部参数缺省时的默认值
${@:N}	从第 N 个参数开始（1 起始）
${@:N:L}	从第 N 个起取 L 个

组合示例——带默认值的总结模板：

---
description: Summarize session state
---
Summarize the current state in ${1:-7} bullet points.
Focus on ${2:-unfinished work}.

/summarize            # 等价于 "in 7 bullet points, focus on unfinished work"
/summarize 3 blockers # 3 条、聚焦阻塞项

8.4 实战：建一套团队工作流模板

下面是一套可直接落地的最小模板组，放在项目 .pi/prompts/ 里随仓库共享：

<!-- .pi/prompts/cr.md -->
---
description: Structured code review for staged changes
---
Review the staged changes (`git diff --cached`) as a senior reviewer.

Output sections:
1. **Blockers** — must fix before merge (bugs, security, data loss)
2. **Should fix** — design/logic concerns with suggested alternatives
3. **Nits** — style and naming

Rules: cite file:line for every finding; no praise padding;
if the diff is empty, say so and stop.

<!-- .pi/prompts/commit.md -->
---
description: Generate a conventional commit from staged changes
---
Look at `git diff --cached` and write ONE commit message:

- Format: type(scope): imperative subject (<=72 chars)
- Body: what & why, not how; wrap at 100 chars
- Types allowed: feat fix refactor perf test docs chore

Print only the message in a fenced code block.

# 团队成员克隆仓库后即可直接使用：
/cr
/commit

跨团队分发的进阶做法是把模板放进 pi 包的 prompts/ 目录或 package.json 的 pi.prompts 声明里，用 pi install 安装（第 13 章详述）。

8.5 模板 vs Skills：分工边界

两者都是"Markdown + 可选资源"，但定位不同：

维度	Prompt Template	Skill
本质	一段固定指令的展开	一个能力包（工作流+脚本+参考文档）
触发	手动 /name	/skill:name 或 agent 判断任务匹配自动加载
上下文成本	展开后一次性进入对话	渐进披露：平时只有描述占上下文
典型场景	commit 文案、评审清单、周报	PDF 处理、浏览器自动化等复杂能力

经验法则：指令是"一句话能说完的流程"用模板；需要配套脚本、参考文档或按需加载的能力用技能（下一章展开）。

本章小结

• 模板即 Markdown 文件，文件名即命令名；位置有全局/项目/包/settings/CLI 五处，发现不递归；
• frontmatter 三件套：description、argument-hint（<> 必填、[] 可选）、正文；
• 参数语法支持位置参数 $1、全体 $@、默认值 ${1:-d} 与切片 ${@:N:L}；
• 团队共享首选项目 .pi/prompts/（随 git 分发），规模化则打包；
• 模板=固定指令，技能=能力包，按复杂度选择。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 模板文件 review.md 放在 ~/.pi/agent/prompts/ 下，在编辑器中如何调用？

2. 模板里的 ${1:-7} 表示什么？

3. 关于模板目录的发现规则，正确的是？

4. 以下哪个需求更适合做成 Skill 而不是 Prompt Template？

🛠️ 动手实践

1. 把本章的 /cr 和 /commit 模板放进某个真实项目的 .pi/prompts/，各跑一次并按团队口味调整输出格式。
2. 编写一个带 argument-hint 的 /translate <语言> 模板，验证补全下拉中的参数提示。
3. 用 ${@:2} 语法做一个"第一个参数是文件名、其余全是要求"的模板，测试参数切片是否符合预期。

完成练习后，进入下一章：Skills 技能体系。