Gestión de contexto de Pi Agent
La gestión de contexto es una habilidad central para usar Pi Agent de manera eficiente.
Este capítulo explica cómo controlar el comportamiento de la IA mediante archivos de entorno y cómo gestionar el contexto de la conversación.
Descripción general de los archivos de contexto
Al iniciarse, Pi Agent carga automáticamente el archivo de instrucciones del proyecto, para que la IA conozca las normas, comandos y preferencias de tu proyecto.
Estos archivos le dicen a la IA «cómo trabajar en este proyecto».
AGENTS.md / CLAUDE.md
Estos son los archivos de contexto más importantes de Pi Agent; el orden de carga es:
- ~/.pi/agent/AGENTS.md- Instrucciones globales, aplicables a todos los proyectos
- AGENTS.md o CLAUDE.md en los directorios padre, recorriéndolos hacia arriba desde el directorio actual
- AGENTS.md o CLAUDE.md en el directorio actual
A continuación se muestra un ejemploAGENTS.mdcompleto ubicado en el directorio raíz del proyecto:
Ejemplo
## Estándares de código
- Todo el código usa el modo estricto de TypeScript
- Las funciones deben tener anotaciones de tipo de valor de retorno
- Usa ESLint y Prettier para mantener un estilo de código consistente
## Flujo de trabajo
- Después de modificar el código, ejecuta `npm run check` para validar
- Antes de confirmar, ejecuta `npm test` para asegurar que las pruebas pasen
- No ejecutes migraciones de base de datos de producción directamente en local
## Consejos de seguridad
- No escribas claves de API o contraseñas en el código
- Usa variables de entorno para configuraciones sensibles
## Estilo de respuesta
- Mantén las respuestas concisas, no expliques en exceso el código obvio
- Cuando surja un problema, primero da una solución y luego explica la causa
Después de actualizar AGENTS.md, usa/reloadel comando para recargar en caliente sin necesidad de reiniciar Pi Agent.
Si tienes tanto AGENTS.md como CLAUDE.md, Pi Agent carga AGENTS.md con prioridad.
Si usabas Claude Code anteriormente, puedes reutilizar directamente tu CLAUDE.md existente.
Si existe AGENTS.override.md en el directorio, este reemplaza a AGENTS.md y CLAUDE.md de ese directorio al cargarse.
Si deseas deshabilitar la carga de archivos de contexto, usa el parámetro de línea de comandos:
$ pi --no-context-files $ pi -nc # 短形式
SYSTEM.md
SYSTEM.md se usa para reemplazar por completo el prompt del sistema predeterminado de Pi Agent; si solo deseas añadir contenido, usa APPEND_SYSTEM.md.
Ambos se dividen en dos niveles: global y de proyecto. Las rutas y funciones son las siguientes:
| Archivo | Nivel | Función |
|---|---|---|
| ~/.pi/agent/SYSTEM.md | Global | Reemplaza el prompt del sistema predeterminado |
| Directorio raíz del proyecto/.pi/SYSTEM.md | Proyecto | Reemplaza el prompt del sistema predeterminado |
| ~/.pi/agent/APPEND_SYSTEM.md | Global | Añade después del prompt del sistema predeterminado |
| Directorio raíz del proyecto/.pi/APPEND_SYSTEM.md | Proyecto | Añade después del prompt del sistema predeterminado |
En la mayoría de los casos no necesitas modificar el prompt del sistema.
AGENTS.md ya cubre la gran mayoría de las necesidades de personalización.
SYSTEM.md es adecuado para escenarios que requieren una personalización profunda del comportamiento de la IA; una modificación inadecuada puede afectar el rendimiento de la IA.
Compacción de contexto (Compaction)
Cuando la conversación se vuelve muy larga, la ventana de contexto (context window) de la IA se va llenando gradualmente.
Pi Agent resuelve este problema mediante la compacción de contexto (Compaction): resume automáticamente las partes más antiguas de la conversación en un breve resumen, liberando espacio en el contexto.
Compacción automática
De forma predeterminada, Pi Agent activa automáticamente la compacción cuando el contexto se acerca al límite del modelo.
El comportamiento de compacción está controlado por~/.pi/agent/settings.jsonla configuración `compaction` en:
Ejemplo
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}
| Elemento de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| compaction.enabled | boolean | true | Si se habilita la compacción automática |
| compaction.reserveTokens | number | 16384 | Número de tokens reservados para la respuesta del LLM |
| compaction.keepRecentTokens | number | 20000 | Número de tokens recientes que se conservan sin comprimir |
La condición de activación es que los tokens de contexto superen el espacio disponible después de restar reserveTokens de contextWindow.
El momento de verificación es después de cada ejecución de herramienta y antes de que se envíe el siguiente mensaje del usuario.
Compacción manual
También puedes activar la compacción manualmente en cualquier momento:
/compact
Al comprimir, puedes agregar instrucciones personalizadas para indicar a la IA en qué debe centrarse al resumir:
/compact 重点关注错误修复和 API 变更
La compacción es irreversible solo para el contexto de la conversación actual.
Los mensajes originales comprimidos se conservan íntegros en el archivo de sesión; usa /tree para volver al nodo anterior a la compacción y recuperar los detalles.
Si deseas hacer una copia de seguridad completa antes de comprimir, se recomienda usar /clone.
/clone copia por completo la rama activa actual a un nuevo archivo de sesión, adecuado para respaldar antes de comprimir.
/fork solo parte de un mensaje histórico del usuario; el contenido posterior no se incluye en la nueva sesión.
Visualización del proceso de razonamiento
Los modelos que admiten salida de razonamiento piensan antes de responder.
Puedes controlar la visualización del proceso de razonamiento con los siguientes ajustes:
| Ajuste | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| hideThinkingBlock | boolean | false | Oculta el proceso de razonamiento y solo muestra la respuesta final |
| showCacheMissNotices | boolean | false | Muestra avisos de fallo de caché y también los avisos de uso de tokens generados por la compacción y el resumen de ramas |
UsaCtrl+Tpara alternar la visualización del proceso de razonamiento en cualquier momento durante la conversación.
Recarga en caliente (/reload)
Si necesitas reiniciar después de modificar la configuración depende de qué hayas cambiado.
La siguiente tabla resume cómo se aplican los cambios comunes; para los elementos marcados como «No», basta con ejecutar /reload:
| Cambio | Requiere reinicio | Descripción |
|---|---|---|
| AGENTS.md o CLAUDE.md (archivos de contexto) | no | Se recargan inmediatamente después de ejecutar /reload |
| Extensions (extensiones) | no | Se recargan inmediatamente después de ejecutar /reload |
| Skills (habilidades) | no | Se recargan inmediatamente después de ejecutar /reload |
| Plantillas de prompt | no | Se recargan inmediatamente después de ejecutar /reload |
| Archivos de tema | no | Se recargan inmediatamente después de ejecutar /reload |
| Configuración de atajos de teclado | no | Se recarga inmediatamente después de ejecutar /reload |
| Ciertos ajustes en ~/.pi/agent/settings.json | Sí | Algunas configuraciones se leen una vez al inicio |
| Paquetes de extensiones recién instalados | Sí | Las dependencias de paquetes se resuelven en la fase de inicio |
| Credenciales de auth.json | Sí | Las credenciales se cargan en la fase de inicio |
Ver el uso de contexto
La barra de estado inferior muestra en tiempo real el uso de tokens y el costo del contexto actual.
Usa/sessionel comando para ver información más detallada:
/session
Ejemplo de salida:
Session file: ~/.pi/agent/sessions/--Users-ejemplo-projects-ejemplo-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl Session ID: abc123-def456 Messages: 42 Tokens: 85,432 Cost: $0.52 Current model: claude-sonnet-4-20250514Otras extensiones