Implementación multiplataforma de Pi Agent

Pi Agent se puede ejecutar en Windows, macOS, Linux y Android (Termux).

Este capítulo presenta los puntos clave de configuración para cada plataforma.


Configuración para macOS

macOS es una plataforma de soporte de primera clase para Pi Agent; la mayoría de las funciones funcionan sin configuración adicional.

Terminal recomendado

TerminalMétodo de instalaciónMotivo de la recomendación
iTerm2brew install --cask iterm2Soporte nativo de True Color, buena visualización de imágenes, funciones completas
Kittybrew install --cask kittyRenderizado acelerado por GPU, rápido
Warpbrew install --cask warpTerminal moderna, integración de funciones de IA

Verificar soporte de True Color

$ echo $COLORTERM
truecolor

Alias de shell

Pi Agent ejecuta bash en modo no interactivo (es decir,bash -c), por defecto no expande automáticamente tus alias de shell.

Mecanismo clave: hacer que Pi reconozca los alias de shell. Para usar alias personalizados en Pi, escribe la siguiente configuración en ~/.pi/agent/settings.json (o ~/.atomic/agent/settings.json), para que cargue activamente tu archivo de configuración de shell (por ejemplo, ~/.zshrc o ~/.bashrc) al inicio:

{
  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
}

Nota:Cambia la ruta ~/.zshrc por la ruta real del archivo de configuración de shell que uses.


Configuración para Windows

En Windows, puedes ejecutar Pi Agent mediante el terminal nativo o WSL2; la clave es elegir el terminal correcto y manejar los conflictos de atajos de teclado.

Método de instalación recomendado

En Windows se recomienda usarWindows Terminaljunto con WSL2 o usar directamente Node.js.

Instalar Git for Windows

Pi usa Git Bash por defecto para ejecutar comandos en Windows.

Al iniciar, busca en orden, incluida la ruta predeterminadaC:\Program Files\Git\bin\bash.exe。

Si Git for Windows no está instalado, no se encontrará bash al iniciar; instalar Git for Windows lo resuelve.

Si no quieres usar Git Bash, también puedesshellPathconfigurar otro bash, o mediantedefaultToolscambiar a la herramienta PowerShell.

Instalar Node.js

desdenodejs.orgDescarga el instalador o usa winget:

# PowerShell
> winget install OpenJS.NodeJS.LTS

Instalar Pi Agent

Ejecuta en PowerShell o CMD de Windows Terminal:

# PowerShell
> npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Atajos de teclado específicos de Windows

FunciónAtajos de teclado en WindowsAtajos de teclado en macOS/Linux
Pegar imagenAlt+VCtrl+V
Entrada multilíneaCtrl+EnterShift+Enter
Enviar mensaje de seguimientoCtrl+Q (enviar), Alt+Q (recuperar)Alt+Enter

En Windows, por defecto se usa Ctrl+Q para enviar mensajes de seguimiento y Alt+Q para recuperar mensajes en cola, sin necesidad de remapear.

Solo necesitas configuración si quieres cambiar a Alt+Enter.

En Windows Terminal, Alt+Enter es el atajo de pantalla completa por defecto.

Si quieres que Pi Agent reciba este atajo, debes eliminar o remapear el atajo de pantalla completa en la configuración de Windows Terminal.

Busca "toggleFullscreen" en la configuración y cambia su atajo a otra combinación.

Luego vincula la combinación de Piapp.message.followUpcomo alt+enter.

Comportamiento de suspensión

El terminal nativo de Windows no admite el control de trabajos de Unix.

En Windows nativo, Ctrl+Z está asignado a deshacer edición; para suspender, debes asignar un atajo tú mismo.

En WSL, usa Alt+Z para suspender; Ctrl+Z aún puede suspender procesos y, junto con fg, se puede volver a la normalidad.


Configuración de Termux (Android)

Pi Agent se puede ejecutar en dispositivos Android mediante Termux.

Pasos de instalación

Primero instala Termux en sí; obtén el paquete de instalación más reciente desde F-Droid y luego ejecuta los siguientes comandos en Termux.

Ejemplo

# 1. Actualiza los paquetes e instala Node.js y la herramienta de línea de comandos termux-api
pkg update && pkg upgrade
pkg install nodejs termux-api

# 2. Instala Pi Agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 3. Verifica la instalación
pi --version

# 4. Antes de usar el almacenamiento compartido por primera vez, ejecuta una vez para autorizar el acceso a rutas como el directorio de descargas
termux-setup-storage

Además de Termux, también necesitas instalar la aplicación Termux:API en tu teléfono.

Esta aplicación también se puede obtener desde F-Droid; capacidades de integración del dispositivo como el portapapeles dependen de ella.

Si solo instalas el paquete de línea de comandos termux-api y no la aplicación Termux:API, los comandos correspondientes no funcionarán.

Precauciones

El entorno de Termux difiere del Linux convencional; ten en cuenta los siguientes puntos.

ElementoDescripción
Ruta de almacenamientoLa ruta de acceso al almacenamiento de Termux difiere del Linux convencional; usa ~/storage/shared/ para acceder al almacenamiento compartido. Antes del primer uso, ejecuta termux-setup-storage
Visualización de imágenesLa visualización de imágenes puede estar limitada en algunos terminales
PortapapelesLa integración del portapapeles de Termux solo admite texto; pegar imágenes no está disponible
Experiencia de entradaSe recomienda usar un teclado Bluetooth o un teclado OTG para una mejor experiencia de edición

Integración con tmux

Pi Agent puede funcionar correctamente en sesiones de tmux.

Ventajas

Poner Pi Agent en tmux sirve principalmente para obtener persistencia y capacidad de múltiples ventanas.

VentajaDescripción
Persistencia de sesiónIncluso si SSH se desconecta, Pi Agent sigue ejecutándose en segundo plano
Diseño de múltiples ventanasUna ventana ejecuta Pi Agent, otra ventana para ver el código
Desarrollo remotoUsar Pi Agent después de conectarse por SSH al servidor

Configuración recomendada

Agrega en ~/.tmux.conf:

Ejemplo

# Ruta del archivo: ~/.tmux.conf
# Asegurar soporte de True Color
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"

# Habilitar el reporte de teclas extendidas y reenviar combinaciones de teclas en formato CSI-u
# Sin estas dos líneas, Shift+Enter en tmux degenera en un Enter normal
set -g extended-keys on
set -g extended-keys-format csi-u

# Aumentar el búfer de retroceso (útil al ver grandes cantidades de salida de IA)
set -g history-limit 50000

Las dos líneas de extended-keys son la configuración clave; su función es permitir que combinaciones como Shift+Enter y Ctrl+Enter se transmitan correctamente a pi.

extended-keys-format csi-u requiere tmux 3.5 o superior; puedes usartmux -Vpara ver la versión.

$ tmux -V
tmux 3.5a

Sin agregar estas dos líneas, Shift+Enter en tmux degenera en un Enter normal, y la entrada multilínea enviará el mensaje directamente.

Si la versión de tmux está entre 3.2 y 3.4, omita la línea csi-u; pi aún admite el formato xterm predeterminado de tmux.


Optimización de la configuración del terminal

Independientemente del terminal que uses, las siguientes configuraciones afectarán directamente la visualización de Pi Agent.

Elemento de configuraciónValor sugeridoDescripción
True ColorHabilitadoAsegúrate de que el terminal admita color de 24 bits
FuenteFuente monoespaciada (como JetBrains Mono, Fira Code)Asegura la alineación del código y la visualización de caracteres especiales
Buffer de retroceso (scrollback)Al menos 10000 líneasPara ver grandes cantidades de salida de IA y mensajes históricos
Terminal de VS CodeEstablece minimumContrastRatio en 1Asegura que los colores del tema se rendericen con precisión

Configuración del terminal integrado de VS Code

Agrega la siguiente configuración al settings.json de VS Code, la ruta del archivo es~/Library/Application Support/Code/User/settings.json(macOS):

Ejemplo

{
  "terminal.integrated.minimumContrastRatio": 1,
  "terminal.integrated.fontFamily": "JetBrains Mono",
  "terminal.integrated.fontSize": 13
}

Sugerencias de alias de shell

A continuación se muestra un conjunto completo de alias de Pi Agent, compatible con todas las plataformas, que se puede agregar a ~/.zshrc, ~/.bashrc o un archivo de configuración de shell equivalente:

Ejemplo

# Ruta del archivo: ~/.zshrc (para usuarios de bash, ~/.bashrc)
# Alias comunes de Pi Agent
alias pin='pi --name'           # Iniciar sesión con nombre
alias pic='pi -c'               # Continuar sesión reciente
alias pir='pi -r'               # Reanudar sesión histórica
alias piq='pi -p'               # Pregunta y respuesta rápidas de una sola vez
alias pip='pi --print'          # Modo Print (igual que -p)
alias pif='pi --fork'           # Sesión bifurcada (fork)
alias pii='pi --no-session'     # Modo temporal (no guardar)
alias piro='pi --tools read,grep,find,ls'  # Modo de solo lectura
alias pirev='pi -p "Revisar los cambios de código en el área de preparación (git diff --cached)"'

Si usas fish shell, cambia alias por abbr o usa la sintaxis de alias de fish.

# fish shell 使用 abbr 定义缩写
abbr -a pic pi -c
Otras extensiones