Conceptos clave de Pi Agent
Antes de usar Pi Agent formalmente, entender sus conceptos clave y su forma de trabajar te ayudará a empezar más rápido.
Entender Pi Agent en una frase
Pi Agent es un asistente de programación con IA que se ejecuta en la terminal.
Al iniciarlo verás una interfaz similar a un software de chat. Introduce tus necesidades en lenguaje natural y la IA podrá leer tu código, ejecutar comandos y modificar archivos.
Cuatro modos de ejecución
Pi Agent admite cuatro modos de ejecución para diferentes escenarios:
| Modo | Comando | Descripción | Escenario aplicable |
|---|---|---|---|
| Modo interactivo | pi (predeterminado) | Interfaz TUI en terminal, conversación en tiempo real, admite todas las funciones. | Desarrollo diario, programación interactiva |
| Modo Print | pi -p "prompt" | Consulta de una sola vez, sale después de mostrar el resultado. | Integración de scripts, consultas rápidas |
| Modo JSON | pi --mode json | Todos los eventos se emiten como líneas JSON, adecuado para el análisis por programas. | Integración de cadenas de herramientas, análisis de datos |
| Modo RPC | pi --mode rpc | Integración mediante protocolo JSONL por stdin/stdout | Comunicación entre procesos, complementos de editor |
El modo interactivo se inicia directamente y entra a la interfaz TUI:
$ pi Pi Agent 0.1.x | ~/projects/ejemplo-demo claude-sonnet-4 | 上下文 2% | $0.0000 >
El modo Print sale después de responder, adecuado para incluir en scripts:
$ pi -p "总结这个项目" 这是一个 TypeScript 命令行工具，核心逻辑位于 src/ 目录，包含会话管理、工具调度和扩展加载三个模块。 Tokens: 1.2k 输入 / 320 输出 | 费用 $0.0081
El modo JSON emite cada evento como una línea JSON, facilitando el análisis por programas:
$ pi --mode json -p "总结这个项目"
{"type":"session","id":"a1b2c3d4"}
{"type":"message_start","role":"assistant"}
{"type":"message_end","usage":{"input":1200,"output":320}}
El modo RPC envía y recibe mensajes JSONL a través de stdin/stdout para que los complementos del editor lo llamen:
$ pi --mode rpc
{"id":1,"method":"prompt","params":{"message":"列出 src 目录"}}
{"id":1,"result":{"state":"idle","messages":2}}
Como principiante, trabajarás la mayor parte del tiempo en modo interactivo.
Cuando tengas más experiencia, el modo Print puede usarse para automatizar scripts.
Herramientas integradas
Al iniciarse, Pi Agent otorga a la IA las siguientes cuatro herramientas integradas por defecto; además, hay tres herramientas de solo lectura (grep, find, ls) que se pueden activar opcionalmente:
| Nombre de la herramienta | Función | Ejemplo | Estado por defecto |
|---|---|---|---|
| read | Leer contenido de archivo | La IA lee src/main.ts para entender la lógica del código. | Habilitado por defecto |
| write | Crear o sobrescribir archivo | La IA crea un archivo nuevo o reescribe todo el archivo. | Habilitado por defecto |
| edit | Reemplazar con precisión el contenido de un archivo | La IA modifica algunas líneas de código en una función. | Habilitado por defecto |
| bash | Ejecutar comandos de shell | La IA ejecuta pruebas, instala dependencias y ejecuta el linter. | Habilitado por defecto |
| grep | Buscar texto en archivos | La IA busca en qué archivos se llama a una función. | Activación opcional |
| find | Buscar archivos por nombre | La IA encuentra todos los archivos llamados *.test.ts | Activación opcional |
| ls | Listar contenido del directorio | La IA examina la estructura del directorio para localizar módulos. | Activación opcional |
Las tres herramientas de solo lectura se activan--toolsmanualmente mediante el parámetro, por ejemplo.pi --tools read,grep,find,ls。
Sistema de extensiones
Pi Agent amplía sus funciones mediante las siguientes cinco formas:
| Forma de extensión | Formato de archivo | Uso | Dificultad |
|---|---|---|---|
| Extensions (extensiones) | TypeScript（.ts） | Registrar herramientas personalizadas, escuchas de eventos, comandos y componentes de UI. | Requiere programación |
| Skills (habilidades) | Markdown（SKILL.md） | Proporciona instrucciones de flujo de trabajo y scripts en dominios especializados. | Basta con saber escribir Markdown |
| Prompt Templates (plantillas de indicaciones) | Markdown（.md） | Indicaciones reutilizables con soporte para parámetros. | El más simple |
| Themes (temas) | JSON（.json） | Personaliza la combinación de colores de la interfaz de terminal. | Simple |
| Packages (paquetes) | Proyectos npm/git | Empaquetar y compartir los cuatro recursos anteriores | Según la necesidad |
Como principiante, no necesitas entender todas las formas de extensión de inmediato.
Comienza por el uso básico y explora gradualmente el sistema de extensiones a medida que crezcan tus necesidades.
Orden de carga de archivos
Al iniciarse, Pi Agent carga automáticamente los archivos de instrucciones del proyecto, permitiéndote definir las normas de comportamiento de la IA:
| Nivel | Ruta | Alcance | Prioridad |
|---|---|---|---|
| Configuración global | ~/.pi/agent/AGENTS.md | Todos los proyectos | La más baja, como línea base general |
| Configuración de proyecto | AGENTS.md o CLAUDE.md en el directorio del proyecto y directorios superiores | Proyecto actual | La más alta, puede sobrescribir las instrucciones globales |
La configuración de nivel de proyecto se carga recorriendo hacia arriba desde los directorios superiores y finalmente se combina con la configuración del directorio actual.
Si usabas Claude Code anteriormente, puedes reutilizar directamente los archivos CLAUDE.md existentes; Pi Agent los reconocerá y cargará automáticamente.
Sesiones y ramas
El sistema de sesiones de Pi Agent es una de sus características más distintivas.
Cada conversación se guarda automáticamente como un archivo de sesión~/.pi/agent/sessions/en el directorio correspondiente.
El interior de la sesión es una estructura de árbol: puedes "bifurcar" nuevas direcciones de exploración en cualquier nodo histórico sin perder las conversaciones anteriores.
Esto es muy útil cuando necesitas probar diferentes enfoques de implementación: cada idea se puede conservar de forma independiente y revisar en cualquier momento.
Otras extensiones