提示词模板
提示词模板把 Markdown 文件变成带 shell 风格参数替换的斜杠命令;这里是 frontmatter、替换表,以及模板从哪里加载。
你在第 11 章键入的 /review 是真实存在的——它就住在 .pi/prompts/review.md,四行 frontmatter 加三行正文。本章讲的是这个文件能做的一切,以及同样重要的、它不能做的事。
prompt-templates.md 给出的单行总结是:模板把 Markdown 文件变成可复用的 / 命令。当你本来会重复键入同一条提示词,而又不想添加可执行行为或更大的一组支撑指令时,你就需要一个模板。
这个文件
---
description: 评审未提交的 git 变更
argument-hint: "[关注点]"
---
评审未提交的 git 变更(`git status --short`、`git diff`)。
聚焦于 ${1:-正确性、安全性和错误处理}。
发现的问题要简短,按严重程度排序,每一条都附上文件路径。
文件名就是命令名,所以 review.md 会以 /review 的形式可用。description 出现在命令补全里;如果你省略它,Pi 会用第一个非空行。
argument-hint 是可选的。用 <尖括号> 表示必需的参数,用 [方括号] 表示可选的参数——所以 [focus] 在补全菜单里显示为可选,而 npm run <suite> 显示为必需。
在一个活动会话中添加或修改模板之后,运行 /reload。
参数替换
| 语法 | 结果 |
|---|---|
$1、$2… |
一个位置参数 |
$@ 或 $ARGUMENTS |
所有参数以空格连接 |
${1:-default} |
第一个参数,或者一个默认值 |
${@:-default} |
所有参数,或者一个默认值 |
${@:N} |
从第 N 个位置开始的参数 |
${@:N:L} |
从第 N 个位置开始的 L 个参数 |
${1:-default} 是主力。这里把整个机制放在一处——同一个模板文件,用三种方式调用:
/review
/review concurrency
/review "API compatibility"
评审未提交的 git 变更(`git status --short`、`git diff`)。
聚焦于正确性、安全性和错误处理。
发现的问题要简短,按严重程度排序,每一条都附上文件路径。
评审未提交的 git 变更(`git status --short`、`git diff`)。
聚焦于并发。
发现的问题要简短,按严重程度排序,每一条都附上文件路径。
第二个代码块是第一个加了一个参数后的样子:只有一行变了,而它之所以变,是因为参数到来了。没有 :- 默认值,光秃秃的 /review 就会在 正确性 现在所在的位置展开出一个字面上的空洞。
参数遵循 shell 风格的引号规则,所以第三次调用提供的是一个包含空格的参数,而不是两个。这就是你如何传入一个短语而不让它被拆开。
一个值得使用的展开
---
description: 起草一份简短的实现计划
argument-hint: "<目标>"
---
为 ${1:-<描述这个目标>} 起草一份简短的实现计划。
恰好输出三个小节:
1. 步骤(编号,取最小的有用顺序)
2. 要改动的文件(本仓库中的路径)
3. 如何验证(命令,以及成功是什么样子)
默认值不是填充物。它告诉模型当参数缺失时期望的输入是什么形状,这与第 10 章在验收检查上用的是同一个技巧。
${@:2} 是另一个值得知道的写法——它让一个模板把自己参数的尾段传给同一个正文里的第二条命令:
---
description: 带关注重点和严重程度下限来评审 diff
argument-hint: "<关注点> [最低严重程度]"
---
以关注点 "${1:-正确性}" 运行 /review。
然后用 ${@:2} 运行 /plan。
从按键到模型的路径
值得画一次,因为其中有两个步骤正是人们会忘记的,而它们都是模板可能被拦截的地方。
flowchart TD
K["你键入 /review concurrency"] --> IN["input 事件<br/>扩展看到的是原始文本"]
IN --> M{"有一条名为 review 的<br/>扩展命令吗?"}
M -->|是| E["那条命令运行<br/>不发生模板展开"]
M -->|"否"| EXP["展开<br/>$1 $2 ${@:2} 被替换"]
EXP --> P["提示词模板加载:<br/>先用户,再项目,再显式路径,再包"]
P --> UM["成为一条用户消息"]
UM --> AG["进入智能体"]
两个先后顺序承载了全部要点。input 事件发生在展开之前,所以扩展的输入处理器看到的是字面上的命令文本及其参数。而一个同名的扩展命令会直接胜出——模板根本不会被展开。这两点都有文档记载,也都能解释那个常见的"我的模板不展开"反馈。
加载顺序也值得记住:先用户配置,再项目配置,再显式路径,最后是包,其中项目模板只有在信任被授予之后才会到来。
展开发生在何时
how-pi-works.md 精确地安置了模板:提示词模板在编辑器输入成为一条用户消息之前展开它。prompt-templates.md 补上了一个重要细节:
Pi 在生成的文本进入智能体之前展开模板。扩展先通过
input事件收到原始输入,除非一个同名的扩展命令处理了它。
所以,一个注册了名为 review 的命令的扩展会胜过同名模板;否则,扩展的 input 处理器会在展开之前看到 /review concurrency。如果你正在调试一个看起来不展开的模板,先检查是不是有扩展占用了这个名字。
模板从哪里加载
一个模板可以来自个人配置、项目配置、一个显式路径,或一个 Pi 包。项目配置只有在项目信任被授予之后才会加载。
pi --prompt-template ./review.md
pi -np --print "/review" # -np disables discovered templates; explicit paths still load
项目模板在信任被授予之后成为编辑器里的命令。在信任一个不熟悉的项目之前先审阅它们的内容——模板是一个人选择运行的文本,但它仍然不是你写的文本。
发现机制有个怪癖
常规的提示词目录只加载直接的 .md 子项。嵌套的 Markdown 文件需要通过设置或包清单显式选中,而显式路径和 glob 可以收窄发现范围。
{
"packages": [
{
"source": "./my-templates",
"prompts": ["./deep/nested/*.md"]
}
]
}
如果你写的模板没有出现在 / 菜单里,先检查嵌套,再检查语法。
这个一贯示例:/review
回到评审守卫。这是第 11 章的推演案例 2,没有变化,以下是它给你带来和不带来的东西:
- 它省下了那段措辞。值得拥有。
- 它接受一个关注点参数,而
${1:-correctness, ...}正是让/review在完全没有参数时也可用的东西。 - 它不在评审之前运行仓库自己的检查。那需要一条命令,而模板除了请模型代劳之外无法发出命令。
错误:“技能是一个由模型去填写的提示词模板。” 正确:模板在你键入它的名字时展开,每一次都是。技能则是通过描述被通告给模型,并且只在任务匹配时才加载,而
skills.md直截了当地说"一个模型可能加载不了一个相关的技能"——这正是/skill:name存在的原因。
让模板保持窄
文档自己的框定就是约束:没有可执行行为,没有更大的一组支撑指令。一个长得超出一屏、并且开始引用文件的模板,是在告诉你它想成为一个技能。
这不是风格偏好。这道鸿沟是机械性的:模板是一个文件,旁边没有目录,所以一个打包进来的清单或它需要运行的脚本无处安放。第 13 章的存在是因为这个形状,而不是因为技能是一个做得更规范的模板。
运行了什么
examples/ch12-templates/ 把本章的 review.md 放进一个用户提示词目录,并把 /review 送过一个真实会话,检查 provider 收到的那条用户消息:
${1:-default}:没有参数时应用默认值,而传入concurrency时关注点变成并发;- 一个加了引号的短语
"API compatibility"是一个参数; - 在一个模板里用上整个替换表,参数为
a b c:$1是a,$2是b,$@和$ARGUMENTS是a b c,${@:2}是b c,${@:2:1}是b,${9:-none}是none; - 一个同名的扩展命令胜过模板,而模型从未被询问;
- 扩展的
input处理器在展开之前看到原始文本/review concurrency; - 嵌套目录里的模板不会按惯例被发现。
全部与本章相符。