Primera conversación con Pi Agent

Después de completar la instalación y la configuración de autenticación, este capítulo te guiará a través de tu primera experiencia completa de conversación.

Te familiarizarás con la distribución de la interfaz y las operaciones básicas.

Iniciar Pi Agent

Entra en el directorio de tu proyecto e inicia Pi Agent:

$ cd ~/projects/ejemplo-demo
$ pi

Verás la interfaz interactiva de Pi Agent en la terminal.

La interfaz se divide en cuatro áreas principales:

Si crees que la información del encabezado que se muestra al inicio es demasiada, puedes habilitar en la configuraciónquietStartupla opción para ocultarlo.

La primera tarea

Una vez en la interfaz, escribe tu primera solicitud y pulsa Enter:

Ayúdame a resumir la estructura y las funciones principales de este proyecto.

Pi Agent utilizará herramientas integradas para leer los archivos de tu proyecto, analizar la estructura del código y luego devolver un resumen.

Puedes ver en el área de mensajes las operaciones que está ejecutando la IA, incluido qué herramientas ha llamado y qué archivos ha leído.

La salida de una conversación completa es similar a:

> read README.md（1.2k 字符）
> read src/main.ts（3.4k 字符）

这是一个基于 TypeScript 的终端编程助手，主要功能分为会话管理、工具调度和扩展加载三部分。
Tokens: 2.4k 输入 / 410 输出  |  费用 $0.0152

Pi Agent ofrece por defecto cuatro herramientas integradas: read, write, edit y bash. La explicación completa se encuentra en el capítulo «Visión general de conceptos básicos».

Referenciar archivos

Puedes referenciar archivos específicos en la conversación de dos maneras:

Método 1: sintaxis @ (búsqueda en el editor)

Escribe en el área de edición@y aparecerá automáticamente una búsqueda difusa de archivos del proyecto:

@src/app.ts 解释这个文件的功能

Método 2: parámetros de línea de comandos

Pasa directamente referencias de archivos al iniciar:

$ pi @README.md "总结一下这个文档"
$ pi @src/app.ts @src/app.test.ts "对比这两个文件"

También puedes referenciar archivos de imagen:

$ pi -p @screenshot.png "这张截图里显示了什么"

Pegar imágenes

Pi Agent admite el envío de imágenes en la conversación; el método de operación varía ligeramente según la plataforma.

Ejecutar comandos en la conversación

Puedes ejecutar comandos de shell directamente desde el área de edición sin salir de Pi Agent:

!npm run lint
!git diff

con!Los comandos que empiecen con dicho prefijo se ejecutarán y la salida se enviará automáticamente a la IA para que la revise.

El resultado de ejecutar!npm run lintes similar a:

> [email protected] lint
> eslint .
0 errors, 0 warnings

con!!Los comandos que empiecen con ... también se ejecutarán, peronoenviarán la salida a la IA:

!!echo "这只在本地显示"
这只在本地显示

Al usar!!el prefijo para ejecutar comandos que no necesitan ser revisados por la IA (como abrir archivos o ver variables de entorno), evitarás desperdiciar la ventana de contexto.

Entrada multilínea y editor externo

Los textos largos pueden escribirse con entrada multilínea o un editor externo. A continuación se muestran los atajos de teclado relacionados.

Cuando necesites introducir un texto largo, pulsaCtrl+GSe abrirá el editor predeterminado del sistema (como nano, vim o VS Code). Tras guardar, el contenido se rellenará automáticamente en el área de edición de Pi Agent.

Cola de mensajes

Pi Agent permite enviar mensajes mientras la IA está trabajando, sin necesidad de esperar a que termine:

En Windows Terminal, Alt+Enter es el atajo de pantalla completa de forma predeterminada. Si quieres que Pi Agent reciba este atajo, consultaDespliegue multiplataformalas instrucciones en ... para reasignarlo.

Modo no interactivo

Además del diálogo interactivo, también puedes usar Pi Agent rápidamente de las siguientes maneras:

El modo Print (-p) es muy adecuado para integrarlo en scripts y flujos de CI.

Crear un archivo de instrucciones del proyecto

Para que la IA entienda mejor tu proyecto, se recomienda crear un archivo AGENTS.md.

Guarda el siguiente contenido como archivo Markdown, con la rutaDirectorio raíz del proyecto/AGENTS.md：

Pi Agent cargará automáticamente este archivo al iniciar.

También cargará las instrucciones globales de~/.pi/agent/AGENTS.mdy los archivos de instrucciones en el directorio padre.

Después de actualizar AGENTS.md, usa/reloadel comando para recargar en caliente sin necesidad de reiniciar.

Si antes usabas Claude Code, los archivos CLAUDE.md existentes pueden ser reconocidos y utilizados directamente por Pi Agent, sin necesidad de renombrarlos.

Resumen de la interfaz

A continuación se muestra una referencia rápida de los principales atajos de teclado del modo interactivo de Pi Agent: