Шаблон промпта Pi Agent
Шаблоны промптов — это предопределённые фрагменты Markdown, которые можно развернуть в полные промпты с помощью короткой команды, что повышает эффективность при повторяющейся работе.
Обзор шаблонов
Принцип работы шаблонов промптов прост:
- Создайте файл Markdown, чтобы определить содержимое шаблона
- Введите в редакторе/template-name, чтобы вызвать его
- Шаблон автоматически разворачивается и заполняет редактор
Шаблоны поддерживают подстановку параметров, что позволяет использовать один и тот же шаблон в разных конкретных сценариях.
Создание шаблона
Шаблоны — это файлы Markdown с YAML-метаданными.
Имя файла (без .md) — это имя команды шаблона.
Создайте шаблон для проверки кода:
Пример
description: Просмотрите текущие подготовленные изменения git
---
Просмотрите изменения в области подготовки (git diff --cached), обращая внимание на:
- Потенциальные баги и логические ошибки
- Проблемы безопасности
- Обработка ошибок и граничные случаи
- Проблемы производительности
Сохраните в~/.pi/agent/prompts/review.mdЗатем введите в редакторе/review, чтобы развернуть и использовать его.
Расположение шаблона
Pi Agent ищет шаблоны в нескольких фиксированных местах, каждое из которых имеет свою область действия.
| Расположение | Область действия |
|---|---|
| ~/.pi/agent/prompts/*.md | Глобальные шаблоны, доступные всем проектам |
| .pi/prompts/*.md | Шаблоны проекта, загружаемые только после того, как проект признан доверенным |
| Каталог prompts/ в Pi Packages | Шаблоны в пакете |
| --prompt-template path | Временная загрузка из командной строки |
Поиск шаблонов —нерекурсивныйШаблоны в подкаталогах prompts/ не будут загружаться автоматически.
Если шаблоны помещены в подкаталоги, нужно явно добавить путь в массив prompts в settings.json.
Система параметров
Шаблоны поддерживают богатую систему параметров, позволяя одному и тому же шаблону адаптироваться к разным сценариям:
| Синтаксис | Значение | Пример |
|---|---|---|
| $1, $2, $3... | Позиционные параметры | $1 представляет первый параметр |
| $@ или $ARGUMENTS | Конкатенация всех параметров | Объединить все параметры через пробелы |
| ${1:-default} | Параметр со значением по умолчанию | Использовать параметр, если он существует и не пуст, иначе использовать значение по умолчанию |
| ${@:N} | Начиная с N-го параметра | ${@:2} берёт все параметры начиная со 2-го |
| ${@:N:L} | Взять L параметров начиная с N-го | ${@: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 Подсказка по параметрам
Настройка в Frontmatterargument-hintможет помочь пользователям понять параметры, необходимые шаблону:
Пример
description: Провести ревью PR по URL, проанализировать код и проблемы
argument-hint: "<PR-URL>"
---
Проверьте изменения кода в следующем PR, уделяя особое внимание проблемам безопасности и производительности: $1
В выпадающем меню автодополнения этот шаблон будет отображаться как:
→ pr <PR-URL> — 从 URL 审查 PR，分析代码和问题
Сохраните в~/.pi/agent/prompts/pr-review.mdЗатем используйте/pr-review https://github.com/example/repo/pull/12чтобы вызвать.
Используйте<угловые скобки>для обязательных параметров,[квадратные скобки]для необязательных параметров.
Практические примеры шаблонов
Следующие три шаблона охватывают три самых распространённых типа запросов в повседневной разработке, их можно скопировать и адаптировать по необходимости.
Генерация сообщения коммита Git
Следующий шаблон генерирует сообщения коммитов в соответствии со спецификацией Conventional Commits.
Пример
description: Сгенерируйте сообщение коммита в формате Conventional Commits на основе git diff
---
Просмотрите содержимое git diff --cached и сгенерируйте сообщение git-коммита в формате Conventional Commits.
Следуйте спецификации Conventional Commits, формат: type(scope): description
Типы включают: feat, fix, refactor, docs, test, chore
Сохраните в~/.pi/agent/prompts/commit.mdПосле этого проиндексируйте изменения и используйте/commitдля вызова.
Запрос на рефакторинг кода
Следующий шаблон разбивает цели рефакторинга на понятные пункты проверки, не позволяя ИИ менять только форматирование, не затрагивая структуру.
Пример
description: Рефакторинг указанного модуля кода
argument-hint: "<путь к файлу или имя модуля>"
---
Выполните рефакторинг кода $1, цели:
1. Улучшить читаемость кода
2. Устранить дублирование кода
3. Улучшить обработку ошибок
4. Сохранить существующую функциональность без изменений
Перед внесением изменений, пожалуйста, объясните ваш план рефакторинга.
Сохраните в~/.pi/agent/prompts/refactor.mdЗатем используйте/refactor src/utils/date.tsдля вызова.
Запрос на исправление ошибки
Следующий шаблон заставляет ИИ выполнять диагностику по фиксированным шагам, снижая склонность «немедленно изменять код».
Пример
description: Систематически выявляйте и исправляйте указанную ошибку
argument-hint: "<Описание ошибки>"
---
Мне нужно, чтобы вы помогли мне диагностировать и исправить следующую ошибку: $1
Пожалуйста, выполните следующие шаги:
1. Сначала поймите ожидаемое и фактическое поведение ошибки
2. Найдите соответствующие файлы кода
3. Проанализируйте возможные причины
4. Предложите план исправления
5. Реализуйте исправление
6. Убедитесь, что исправление верно
Объясняйте свои выводы и рассуждения на каждом шаге.
Сохраните в~/.pi/agent/prompts/fix-bug.mdзатем используйте/fix-bug Список не обновляется после входадля вызова.
Правила загрузки шаблонов
Обнаружение и загрузка шаблонов подчиняются приведённым ниже правилам. Если вы устраняете неполадку «шаблон не отображается», сначала проверьте здесь.
| Правило | Описание |
|---|---|
| Нерекурсивное обнаружение | Обнаружение шаблонов в каталоге prompts/ являетсянерекурсивным; шаблоны в подкаталогах не будут автоматически обнаружены |
| Подкаталоги должны быть явно объявлены | Когда нужно загрузить шаблоны из подкаталога, явно добавьте путь в массив prompts в settings.json |
| Резервный вариант для description | Еслиdescriptionпусто, Pi Agent будет использовать первую непустую строку файла в качестве description |
| Отключить автоматическое обнаружение | При использовании--no-prompt-templatesавтоматическое обнаружение отключено, но шаблоны, явно указанные с помощью--prompt-template, всё равно будут загружены |
Другие расширенияПосле ввода /template name, если он не появляется в списке автодополнения, сначала проверьте, находится ли файл в корневой директории prompts/.
Шаблоны проекта, размещённые в .pi/prompts/, также должны сначала пройти проверку доверия к проекту, иначе они тоже не будут загружены.