Pi Agent 提示词模板
提示词模板是预定义的 Markdown 片段，通过简短命令即可展开为完整提示词，提高重复性工作的效率。
模板概述
提示词模板的工作方式很简单：
- 创建一个 Markdown 文件，定义模板内容
- 在编辑器中输入 /模板名 来调用
- 模板会自动展开并填入编辑器
模板支持参数替换，让同一个模板可以用于不同的具体场景。
创建模板
模板是带有 YAML Frontmatter 的 Markdown 文件。
文件名（不含 .md）即为模板的命令名。
创建一个代码审查模板：
实例
description: 审查当前的 git 暂存变更
---
审查暂存区中的更改（git diff --cached），重点关注：
- 潜在的 bug 和逻辑错误
- 安全问题
- 错误处理和边界情况
- 性能问题
保存到 ~/.pi/agent/prompts/review.md 后，在编辑器中输入 /review 即可展开使用。
模板位置
Pi Agent 会在固定的几个位置查找模板，作用范围各不相同。
| 位置 | 作用范围 |
|---|---|
| ~/.pi/agent/prompts/*.md | 全局模板，所有项目可用 |
| .pi/prompts/*.md | 项目模板，需项目信任后才加载 |
| Pi Packages 的 prompts/ 目录 | 包中的模板 |
| --prompt-template 路径 | 命令行临时加载 |
模板发现是非递归的，prompts/ 子目录中的模板不会被自动加载。
如果模板放在子目录，需要在 settings.json 的 prompts 数组中显式添加该路径。
参数系统
模板支持丰富的参数系统，让同一个模板适应不同场景：
| 语法 | 含义 | 示例 |
|---|---|---|
| $1, $2, $3... | 位置参数 | $1 代表第一个参数 |
| $@ 或 $ARGUMENTS | 所有参数的合并 | 将所有参数用空格连接 |
| ${1:-默认值} | 带默认值的参数 | 参数存在且非空时使用参数，否则用默认值 |
| ${@:N} | 从第 N 个参数开始 | ${@:2} 取第 2 个起的所有参数 |
| ${@:N:L} | 从第 N 个起取 L 个 | ${@:2:3} 取第 2-4 个参数 |
$ARGUMENTS 会把全部参数原样拼接，适合只需要一整段文本的模板：
实例
description: 把一段中文翻译成地道的英文
argument-hint: "<要翻译的中文>"
---
把下面的内容翻译成地道的英文，只输出译文：
$ARGUMENTS
保存为 ~/.pi/agent/prompts/translate.md 后，用 /translate 把这段话翻译成英文 调用。
带参数模板示例
下面的模板组合使用位置参数和尾部参数，适合"类型 + 名称 + 补充说明"这类输入。
实例
description: 使用指定框架创建组件
argument-hint: "<框架> <组件名> [功能描述]"
---
使用 $1 创建一个 $2 组件，功能包括：${@:3}
$1 取第一个参数作为框架，$2 取第二个参数作为组件名。
${@:3} 表示从第三个参数开始的所有内容，用于承载零散的功能描述。
使用方式：
/component React Button "onClick 事件处理" "disabled 状态支持" "loading 加载状态"
展开后的效果：
使用 React 创建一个 Button 组件，功能包括：onClick 事件处理 disabled 状态支持 loading 加载状态
默认值示例
参数缺失时用默认值兜底，模板在不带参数调用时也能正常工作。
实例
description: 总结当前项目状态
---
用 ${1:-5} 个要点总结当前项目的主要变更和状态。
保存到 ~/.pi/agent/prompts/summarize.md 后，用 /summarize 调用。
使用 /summarize 时默认输出 5 个要点。
使用 /summarize 10 时输出 10 个要点。
两种调用的展开结果对比如下：
/summarize → 用 5 个要点总结当前项目的主要变更和状态。 /summarize 10 → 用 10 个要点总结当前项目的主要变更和状态。
argument-hint 参数提示
在 Frontmatter 中设置 argument-hint 可以帮助用户了解模板需要的参数：
实例
description: 从 URL 审查 PR，分析代码和问题
argument-hint: "<PR-URL>"
---
审查以下 PR 的代码变更，重点关注安全性和性能问题：$1
在自动补全下拉菜单中，这个模板会显示为：
→ pr <PR-URL> — 从 URL 审查 PR，分析代码和问题
保存到 ~/.pi/agent/prompts/pr-review.md 后，用 /pr-review https://github.com/runoob/repo/pull/12 调用。
使用 <尖括号> 表示必填参数，[方括号] 表示可选参数。
实用模板示例
下面三个模板覆盖了日常开发中最常见的三类请求，可直接复制后按需调整。
Git 提交信息生成
以下模板按 Conventional Commits 规范生成提交信息。
实例
description: 根据 git diff 生成规范的提交信息
---
查看 git diff --cached 的内容，生成一条规范的 git commit 信息。
遵循 Conventional Commits 规范，格式：type(scope): description
类型包括：feat, fix, refactor, docs, test, chore
保存到 ~/.pi/agent/prompts/commit.md 后，暂存变更再用 /commit 调用。
代码重构请求
以下模板把重构目标拆成明确的检查项，避免 AI 只改格式不动结构。
实例
description: 重构指定的代码模块
argument-hint: "<文件路径或模块名>"
---
重构 $1 的代码，目标：
1. 提高代码可读性
2. 消除重复代码
3. 改善错误处理
4. 保持现有功能不变
修改前请先说明你的重构计划。
保存到 ~/.pi/agent/prompts/refactor.md 后，用 /refactor src/utils/date.ts 调用。
Bug 修复请求
以下模板强制 AI 按固定步骤排查，减少"上来就改代码"的情况。
实例
description: 系统性排查和修复指定的 Bug
argument-hint: "<Bug 描述>"
---
我需要你帮我排查和修复以下 Bug：$1
请按照以下步骤进行：
1. 先理解 Bug 的预期行为和实际行为
2. 找到相关的代码文件
3. 分析可能的原因
4. 提出修复方案
5. 实现修复
6. 验证修复是否正确
在每一步都要说明你的发现和推理。
保存到 ~/.pi/agent/prompts/fix-bug.md 后，用 /fix-bug 登录后列表不刷新 调用。
模板加载规则
模板的发现与加载遵循以下规则，排查"模板没出现"时先看这里。
| 规则 | 说明 |
|---|---|
| 非递归发现 | prompts/ 目录中的模板发现是非递归的，子目录中的模板不会被自动发现 |
| 子目录需显式声明 | 需要加载子目录中的模板时，在 settings.json 的 prompts 数组中显式添加路径 |
| description 回退 | 如果 description 为空，Pi Agent 会使用文件的第一行非空文本作为描述 |
| 禁用自动发现 | 通过 --no-prompt-templates 禁用自动发现，但显式用 --prompt-template 指定的模板仍会加载 |
输入 /模板名 后如果没有出现在补全列表里，先确认文件是否位于 prompts/ 根目录。
放在 .pi/prompts/ 的项目模板还需要先通过项目信任检查，否则同样不会被加载。