Plantillas de prompts de Pi Agent

Las plantillas de prompts son fragmentos de Markdown predefinidos que se pueden expandir a prompts completos mediante un comando corto, mejorando la eficiencia en trabajos repetitivos.


Descripción general de las plantillas

La forma de trabajar de las plantillas de prompts es muy simple:

  1. Crea un archivo Markdown que defina el contenido de la plantilla.
  2. Escribe en el editor/nombre-de-plantillapara invocarla.
  3. La plantilla se expande automáticamente y se rellena en el editor.

Las plantillas admiten sustitución de parámetros, lo que permite que la misma plantilla se utilice en diferentes escenarios concretos.


Crear plantillas

Las plantillas son archivos Markdown con YAML Frontmatter.

El nombre del archivo (sin .md) es el nombre del comando de la plantilla.

Crea una plantilla de revisión de código:

Ejemplo

---
description: Revisar los cambios actuales en el área de staging de git
---
Revisa los cambios en el área de staging (git diff --cached), prestando especial atención a:
- Posibles bugs y errores lógicos
- Problemas de seguridad
- Manejo de errores y casos límite
- Problemas de rendimiento

Guarda en~/.pi/agent/prompts/review.mdDespués, en el editor escribe/reviewy ya se puede expandir y usar.


Ubicación de las plantillas

Pi Agent busca plantillas en varias ubicaciones fijas, con diferentes ámbitos de aplicación.

UbicaciónÁmbito
~/.pi/agent/prompts/*.mdPlantilla global, disponible en todos los proyectos.
.pi/prompts/*.mdPlantilla de proyecto, se carga solo después de que se confíe en el proyecto.
Directorio prompts/ de Pi PackagesPlantilla dentro de un paquete
Ruta de --prompt-templateCarga temporal desde la línea de comandos

La detección de plantillas esno recursiva, por lo que las plantillas en subdirectorios de prompts/ no se cargan automáticamente.

Si la plantilla se coloca en un subdirectorio, debes agregar explícitamente esa ruta en el array prompts de settings.json.


Sistema de parámetros

Las plantillas admiten un sistema de parámetros enriquecido, lo que permite que la misma plantilla se adapte a diferentes escenarios:

SintaxisSignificadoEjemplo
$1, $2, $3...Parámetros posicionales$1 representa el primer parámetro.
$@ o $ARGUMENTSLa combinación de todos los parámetros.Concatena todos los parámetros con espacios.
${1:-valor predeterminado}Parámetro con valor predeterminadoUsa el parámetro si existe y no está vacío; de lo contrario, usa el valor predeterminado.
${@:N}Desde el enésimo parámetro en adelante${@:2} toma todos los parámetros a partir del segundo.
${@:N:L}Tomar L parámetros a partir del enésimo${@:2:3} toma los parámetros del 2 al 4.

$ARGUMENTS concatena todos los parámetros tal cual, adecuado para plantillas que solo necesitan un bloque de texto completo.

Ejemplo

---
description: Traducir un texto en chino a un inglés natural
argument-hint: "<chino a traducir>"
---
Traduce el siguiente contenido a un inglés natural, solo emite la traducción:
$ARGUMENTS

Guarda como~/.pi/agent/prompts/translate.mdDespués, usa`/translate` para traducir este párrafo al ingléspara invocarlo.

Ejemplo de plantilla con parámetros

La siguiente plantilla combina parámetros posicionales y parámetros finales, adecuada para entradas como "tipo + nombre + descripción adicional".

Ejemplo

---
description: Crear un componente usando el framework especificado
argument-hint: "<framework> <nombre-del-componente> [descripción-funcional]"
---
Usa $1 para crear un componente $2, con las siguientes funciones: ${@:3}

$1 toma el primer parámetro como framework, $2 toma el segundo parámetro como nombre del componente.

${@:3} representa todo el contenido a partir del tercer parámetro, para contener descripciones de funciones dispersas.

Forma de uso:

/component React Button "onClick 事件处理" "disabled 状态支持" "loading 加载状态"

Efecto después de expandir:

使用 React 创建一个 Button 组件,功能包括:onClick 事件处理 disabled 状态支持 loading 加载状态

Ejemplo de valor predeterminado

Cuando falta un parámetro, se usa el valor predeterminado como respaldo, por lo que la plantilla también funciona cuando se invoca sin parámetros.

Ejemplo

---
description: Resumir el estado actual del proyecto
---
Usa ${1:-5} puntos para resumir los principales cambios y el estado del proyecto actual.

Guarda en~/.pi/agent/prompts/summarize.mdDespués, usa/summarizepara invocarlo.

Al usar/summarizese generan 5 puntos por defecto.

Al usar/summarize 10se generan 10 puntos.

La comparación de los resultados de expansión de las dos invocaciones es la siguiente:

/summarize
→ 用 5 个要点总结当前项目的主要变更和状态。

/summarize 10
→ 用 10 个要点总结当前项目的主要变更和状态。

Sugerencia de parámetros argument-hint

Configurar en Frontmatterargument-hintPuede ayudar a los usuarios a comprender los parámetros que necesita la plantilla:

Ejemplo

---
description: Revisar el PR desde la URL, analizar el código y los problemas
argument-hint: "<PR-URL>"
---
Revisa los cambios de código del siguiente PR, prestando especial atención a problemas de seguridad y rendimiento: $1

En el menú desplegable de autocompletado, esta plantilla se mostrará como:

→ pr   &lt;PR-URL&gt;  — 从 URL 审查 PR,分析代码和问题

Guarda en~/.pi/agent/prompts/pr-review.mdDespués, usa/pr-review https://github.com/ejemplo/repo/pull/12para invocarlo.

Usar<corchetes angulares>indican parámetros obligatorios,[corchetes]indican parámetros opcionales.


Ejemplos prácticos de plantillas

Las siguientes tres plantillas cubren los tres tipos de solicitudes más comunes en el desarrollo diario. Puedes copiarlas y ajustarlas según sea necesario.

Generación de mensajes de confirmación de Git

La siguiente plantilla genera mensajes de confirmación según la especificación Conventional Commits.

Ejemplo

---
description: Generar un mensaje de confirmación estándar basado en git diff
---
Revisa el contenido de git diff --cached y genera un mensaje de confirmación de git estándar.
Sigue la especificación Conventional Commits, formato: type(scope): description
Los tipos incluyen: feat, fix, refactor, docs, test, chore

Guarda en~/.pi/agent/prompts/commit.mdDespués, tras stagear los cambios, usa/commitpara invocarlo.

Solicitud de refactorización de código

La siguiente plantilla divide los objetivos de refactorización en elementos de verificación claros, evitando que la IA solo cambie el formato sin modificar la estructura.

Ejemplo

---
description: Refactorizar el módulo de código especificado
argument-hint: "<ruta-de-archivo-o-nombre-de-módulo>"
---
Refactoriza el código de $1, objetivos:
1. Mejorar la legibilidad del código
2. Eliminar código duplicado
3. Mejorar el manejo de errores
4. Mantener las funcionalidades existentes sin cambios

Antes de modificar, explica primero tu plan de refactorización.

Guarda en~/.pi/agent/prompts/refactor.mdDespués, usa/refactor src/utils/date.tspara invocarlo.

Solicitud de corrección de bugs

La siguiente plantilla obliga a la IA a seguir pasos fijos de investigación, reduciendo la tendencia a "modificar el código directamente".

Ejemplo

---
description: Investigar y corregir sistemáticamente el Bug especificado
argument-hint: "<descripción-del-Bug>"
---
Necesito que me ayudes a investigar y corregir el siguiente Bug: $1

Por favor, sigue los siguientes pasos:
1. Primero comprende el comportamiento esperado y el comportamiento real del Bug
2. Encuentra los archivos de código relevantes
3. Analiza las posibles causas
4. Propón un plan de corrección
5. Implementa la corrección
6. Verificar que la corrección sea correcta

En cada paso, explica tus hallazgos y razonamiento.

Guardar en~/.pi/agent/prompts/fix-bug.mddespués, usar/fix-bug la lista no se actualiza después de iniciar sesiónllamar.


Reglas de carga de plantillas

El descubrimiento y la carga de plantillas siguen las siguientes reglas. Cuando soluciones el problema de "la plantilla no aparece", revisa esto primero.

ReglaDescripción
Descubrimiento no recursivoEl descubrimiento de plantillas en el directorio prompts/ esno recursivode modo que las plantillas en subdirectorios no se descubren automáticamente.
Los subdirectorios deben declararse explícitamenteCuando necesites cargar plantillas en subdirectorios, agrega explícitamente la ruta en el arreglo prompts de settings.json.
Respaldo de descriptionSidescriptionestá vacío, Pi Agent usará la primera línea de texto no vacía del archivo como descripción.
Deshabilitar el descubrimiento automáticoMediante--no-prompt-templatesdeshabilitar el descubrimiento automático, pero explícitamente usando--prompt-templatelas plantillas especificadas aún se cargarán.

Después de ingresar /nombre-de-plantilla, si no aparece en la lista de autocompletar, primero verifica si el archivo está en el directorio raíz de prompts/.

Las plantillas de proyecto ubicadas en .pi/prompts/ también deben pasar primero la verificación de confianza del proyecto; de lo contrario, tampoco se cargarán.

Otras extensiones