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
| Terminal | Método de instalación | Motivo de la recomendación |
|---|---|---|
| iTerm2 | brew install --cask iterm2 | Soporte nativo de True Color, buena visualización de imágenes, funciones completas |
| Kitty | brew install --cask kitty | Renderizado acelerado por GPU, rápido |
| Warp | brew install --cask warp | Terminal 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ón | Atajos de teclado en Windows | Atajos de teclado en macOS/Linux |
|---|---|---|
| Pegar imagen | Alt+V | Ctrl+V |
| Entrada multilínea | Ctrl+Enter | Shift+Enter |
| Enviar mensaje de seguimiento | Ctrl+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
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.
| Elemento | Descripción |
|---|---|
| Ruta de almacenamiento | La 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ágenes | La visualización de imágenes puede estar limitada en algunos terminales |
| Portapapeles | La integración del portapapeles de Termux solo admite texto; pegar imágenes no está disponible |
| Experiencia de entrada | Se 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.
| Ventaja | Descripción |
|---|---|
| Persistencia de sesión | Incluso si SSH se desconecta, Pi Agent sigue ejecutándose en segundo plano |
| Diseño de múltiples ventanas | Una ventana ejecuta Pi Agent, otra ventana para ver el código |
| Desarrollo remoto | Usar Pi Agent después de conectarse por SSH al servidor |
Configuración recomendada
Agrega en ~/.tmux.conf:
Ejemplo
# 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ón | Valor sugerido | Descripción |
|---|---|---|
| True Color | Habilitado | Asegúrate de que el terminal admita color de 24 bits |
| Fuente | Fuente 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íneas | Para ver grandes cantidades de salida de IA y mensajes históricos |
| Terminal de VS Code | Establece minimumContrastRatio en 1 | Asegura 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
# 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 -cOtras extensiones