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:
- Crea un archivo Markdown que defina el contenido de la plantilla.
- Escribe en el editor/nombre-de-plantillapara invocarla.
- 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/*.md | Plantilla global, disponible en todos los proyectos. |
| .pi/prompts/*.md | Plantilla de proyecto, se carga solo después de que se confíe en el proyecto. |
| Directorio prompts/ de Pi Packages | Plantilla dentro de un paquete |
| Ruta de --prompt-template | Carga 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:
| Sintaxis | Significado | Ejemplo |
|---|---|---|
| $1, $2, $3... | Parámetros posicionales | $1 representa el primer parámetro. |
| $@ o $ARGUMENTS | La combinación de todos los parámetros. | Concatena todos los parámetros con espacios. |
| ${1:-valor predeterminado} | Parámetro con valor predeterminado | Usa 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 <PR-URL> — 从 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.
| Regla | Descripción |
|---|---|
| Descubrimiento no recursivo | El 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ícitamente | Cuando necesites cargar plantillas en subdirectorios, agrega explícitamente la ruta en el arreglo prompts de settings.json. |
| Respaldo de description | Sidescriptionestá vacío, Pi Agent usará la primera línea de texto no vacía del archivo como descripción. |
| Deshabilitar el descubrimiento automático | Mediante--no-prompt-templatesdeshabilitar el descubrimiento automático, pero explícitamente usando--prompt-templatelas plantillas especificadas aún se cargarán. |
Otras extensionesDespué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.