← Pi Agents

提示词模板

提示词模板把 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;
  • 嵌套目录里的模板不会按惯例被发现。

全部与本章相符。