Example

把一个 Markdown 文件变成 /review 命令

写出最小的提示词模板,分别展开不带参数和带一个参数的 /review,并看清一个同名的扩展会改变什么。

第 11 章的那个 /review 是一个四行的 Markdown 文件。本页写出真正要紧的最小的提示词模板,分别展开不带参数的 /review 和带一个参数的 /review,然后展示"我的模板不展开"背后的两条顺序规则。这是有文档记载的 Pi 1.0.4 行为,由一次会话测试确认。

写出这个模板

把它保存为 ~/.pi/agent/prompts/review.md(或 <project>/.pi/prompts/review.md),然后在活动会话中运行 /reload。这是本章的模板,为便于阅读取消了转义:

---
description: 评审未提交的 git 变更
argument-hint: "[关注点]"
---
评审未提交的 git 变更(`git status --short`、`git diff`)。
聚焦于 ${1:-正确性、安全性和错误处理}。
发现的问题要简短,按严重程度排序,每一条都附上文件路径。

文件名就是命令名,所以 review.md 就是 /review。description 显示在补全里;省略它,Pi 会用第一个非空行。在 argument-hint 中,<尖括号> 标记一个必需的参数,[方括号] 标记一个可选的参数。${1:-default} 是主力:它读第一个参数,没有时就提供默认值。$@ 和 $ARGUMENTS 则是所有参数用空格连接起来的结果。

一次展开演算

不带参数的 /review 会让默认值留在原处:

聚焦于正确性、安全性和错误处理。

/review concurrency 会恰好替换那一行:

聚焦于并发。

参数遵循 shell 风格的引号规则,所以 /review "API compatibility" 提供的是一个包含空格的参数,而不是两个。在一个以 /t a b c 调用的模板里,完整替换表的表现是:$1 → a,$2 → b,$@ 和 $ARGUMENTS → a b c,${@:2} → b c,${@:2:1} → b,${9:-none} → none。

预期结果

模型被要求运行 到达的用户消息 原因
/review 默认的关注点那一行 ${1:-default} 填上了那个空洞
/review concurrency 聚焦于并发。 参数到来了
/review "API compatibility" 一个带空格的参数 shell 风格的引号

这些是预期的展开,不是来自你这台机器的转录记录。作为支撑的测试是一次已观察的运行:它用一个脚本化的 provider 启动一个真实的 AgentSession,并对 provider 收到的最后一条用户消息的文本做出断言。

“它不展开"的两条规则

一个名为 review 的扩展命令直接胜出:模板永远不会被展开,模型也不会被调用,测试用一个零调用计数把这一点钉住。另外,扩展的 input 处理器会在展开之前看到原始文本 /review concurrency。所以在责怪模板语法之前,先检查是不是有扩展占用了这个名字。常规的提示词目录同样只加载直接的 .md 子项——prompts/nested/deep.md 不会被发现,而一个通过设置或包清单显式选中的文件可以。

机制与局限

有文档记载: 被锁定的 docs/prompt-templates.md 规定了 frontmatter、替换表、展开发生在文本进入智能体之前,以及常规目录只加载直接的 .md 子项。已观察: templates.test.ts 用一个脚本化的 provider 驱动一个真实会话,并对默认值、参数替换、加引号短语的处理、整个替换表、命令优先级、input 的原始文本,以及嵌套文件不被发现做出断言。它没有展示一个真实模型选择任何东西的过程。

模板是一个文件,旁边没有目录。它省下了那段措辞;它不运行仓库自己的检查,而它长大后需要的清单或脚本无处安放。它也是文本,不是一道边界。

完整源码与测试 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.