Déploiement multiplateforme de Pi Agent

Pi Agent prend en charge l'exécution sur Windows, macOS, Linux et Android (Termux).

Ce chapitre couvre l'essentiel de la configuration pour chaque plateforme.


Configuration de macOS

macOS est une plateforme prise en charge de premier ordre pour Pi Agent, et la plupart des fonctionnalités fonctionnent immédiatement.

Terminaux recommandés

TerminalMéthode d'installationRaison de la recommandation
iTerm2brew install --cask iterm2Prise en charge native de True Color, bon rendu d'image, fonctionnalités riches
Kittybrew install --cask kittyRendu accéléré par GPU, rapide
Warpbrew install --cask warpTerminal moderne, fonctionnalités d'IA intégrées

Vérifier la prise en charge de True Color

$ echo $COLORTERM
truecolor

Alias de shell

Pi Agent exécute bash en mode non interactif (c.-à-d.,bash -c) par défaut, il ne développe pas automatiquement vos alias de shell.

Mécanisme principal : permettre à Pi de reconnaître les alias de shell. Pour utiliser des alias personnalisés dans Pi, écrivez la configuration suivante dans ~/.pi/agent/settings.json (ou ~/.atomic/agent/settings.json) afin qu'il charge activement votre fichier de configuration de shell (tel que ~/.zshrc ou ~/.bashrc) au démarrage :

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

Remarque :Veuillez remplacer le chemin ~/.zshrc par le chemin réel de votre fichier de configuration de shell.


Configuration Windows

Sous Windows, vous pouvez exécuter Pi Agent via un terminal natif ou WSL2. L'essentiel est de choisir le bon terminal et de résoudre les conflits de raccourcis.

Méthode d'installation recommandée

Sous Windows, il est recommandé d'utiliserWindows Terminalavec WSL2, ou d'utiliser directement Node.js.

Installer Git for Windows

Pi utilise Git Bash par défaut pour exécuter des commandes sous Windows.

Au démarrage, il recherche dans l'ordre, y compris le chemin par défautC:\Program Files\Git\bin\bash.exe。

Si Git for Windows n'est pas installé, bash ne sera pas trouvé au démarrage ; il suffit d'installer Git for Windows pour résoudre ce problème.

Si vous ne voulez pas utiliser Git Bash, vous pouvez égalementshellPathconfigurer un autre bash, ou viadefaultToolsbasculer vers l'outil PowerShell.

Installer Node.js

depuisnodejs.orgTéléchargez l'installateur, ou utilisez winget :

# PowerShell
> winget install OpenJS.NodeJS.LTS

Installer Pi Agent

Exécutez ce qui suit dans PowerShell ou CMD dans Windows Terminal :

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

Raccourcis spécifiques à Windows

FonctionRaccourci WindowsRaccourci macOS/Linux
Coller une imageAlt+VCtrl+V
Saisie multiligneCtrl+EntréeShift+Enter
Envoyer un message de suiviCtrl+Q (envoyer), Alt+Q (récupérer)Alt+Entrée

Sous Windows, Ctrl+Q envoie les messages de suivi et Alt+Q récupère les messages en file d'attente par défaut ; aucun remappage n'est nécessaire.

La configuration n'est nécessaire que si vous souhaitez passer à Alt+Enter.

Dans Windows Terminal, Alt+Enter correspond par défaut au raccourci plein écran.

Si vous souhaitez que Pi Agent reçoive ce raccourci, vous devez supprimer ou remapper le raccourci plein écran dans les paramètres de Windows Terminal.

Recherchez "toggleFullscreen" dans les paramètres et remplacez son raccourci par une autre combinaison.

Ensuite, définissez la liaison de pi'sapp.message.followUpsur alt+enter.

Comportement de suspension

Les terminaux natifs Windows ne prennent pas en charge le contrôle des tâches Unix.

Sous Windows natif, Ctrl+Z est lié à l'annulation de l'édition ; vous devez lier votre propre raccourci pour la suspension.

Sous WSL, utilisez Alt+Z pour suspendre ; Ctrl+Z peut toujours suspendre les processus, et fg peut les remettre à l'état normal.


Configuration de Termux (Android)

Pi Agent peut s’exécuter sur les appareils Android via Termux.

Étapes d'installation

Installez d’abord Termux lui-même. Récupérez le dernier paquet d’installation depuis F-Droid, puis exécutez les commandes suivantes dans Termux.

Exemple

# 1. Mettre à jour les paquets et installer Node.js et l’outil en ligne de commande termux-api
pkg update && pkg upgrade
pkg install nodejs termux-api

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

# 3. Vérifier l’installation
pi --version

# 4. Avant d’utiliser le stockage partagé pour la première fois, exécutez-la une fois pour accorder l’accès à des chemins tels que le répertoire Downloads
termux-setup-storage

En plus de Termux lui-même, vous devez également installer l’application Termux:API sur votre téléphone.

Cette application peut également être obtenue depuis F-Droid ; les capacités d'intégration de l'appareil telles que le presse-papiers en dépendent.

Si vous installez uniquement le paquet en ligne de commande termux-api sans installer l'application Termux:API, les commandes associées ne fonctionneront pas.

Notes

L'environnement Termux diffère de celui d'un Linux classique ; veuillez garder à l'esprit les points suivants.

ItemDescription
Chemin de stockageLe chemin d'accès au stockage de Termux diffère de celui d'un Linux classique ; utilisez ~/storage/shared/ pour accéder au stockage partagé, et exécutez termux-setup-storage avant la première utilisation.
Affichage d'imageL'affichage des images peut être limité sur certains terminaux
ClipboardL'intégration du presse-papiers de Termux ne prend en charge que le texte ; le collage d'images n'est pas disponible
Expérience de saisieIl est recommandé d'utiliser un clavier Bluetooth ou un clavier OTG pour une meilleure expérience d'édition

Intégration de tmux

Pi Agent fonctionne normalement dans les sessions tmux.

Avantages

Mettre Pi Agent dans tmux vise principalement la persistance et les capacités multi-fenêtres.

AvantageDescription
Persistance de sessionMême si SSH se déconnecte, Pi Agent continue de s'exécuter en arrière-plan
Disposition multi-fenêtresExécutez Pi Agent dans une fenêtre et consultez le code dans une autre
Développement à distanceUtilisez Pi Agent après vous être connecté à un serveur en SSH

Configuration recommandée

Ajoutez ce qui suit à ~/.tmux.conf :

Exemple

# Chemin du fichier : ~/.tmux.conf
# Assurer la prise en charge de True Color
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"

# Activer le rapport étendu des touches et transmettre les combinaisons de touches au format CSI-u
# Sans ces deux lignes, Maj+Entrée dans tmux se dégrade en une simple touche Entrée
set -g extended-keys on
set -g extended-keys-format csi-u

# Augmenter le tampon de défilement (utile lors de la visualisation de grandes sorties d'IA)
set -g history-limit 50000

Parmi celles-ci, les deux lignes extended-keys constituent la configuration essentielle ; elles garantissent que des combinaisons de touches telles que Shift+Enter et Ctrl+Enter sont correctement transmises à pi.

extended-keys-format csi-u nécessite tmux 3.5 ou une version supérieure ; vous pouvez utilisertmux -Vpour vérifier la version.

$ tmux -V
tmux 3.5a

Sans ces deux lignes, Shift+Enter dans tmux se dégrade en un simple Enter, et la saisie multiligne enverra directement le message.

Si la version de tmux est comprise entre 3.2 et 3.4, omettez la ligne csi-u ; pi prend toujours en charge le format xterm par défaut de tmux.


Optimisation des paramètres du terminal

Quel que soit le terminal que vous utilisez, les paramètres suivants affecteront directement la qualité d'affichage de Pi Agent.

ParamètreValeur recommandéeDescription
Couleurs vraiesActiverAssurez-vous que le terminal prend en charge les couleurs 24 bits
FontPolice à chasse fixe (par ex. JetBrains Mono, Fira Code)Garantir l'alignement du code et l'affichage des caractères spéciaux
Tampon de défilement (scrollback)Au moins 10000 lignesVisualiser de grandes quantités de sorties d'IA et de messages historiques
Terminal VS CodeDéfinir minimumContrastRatio sur 1Garantir un rendu fidèle des couleurs du thème

Configuration du terminal intégré de VS Code

Ajoutez la configuration suivante au fichier settings.json de VS Code ; le chemin du fichier est~/Library/Application Support/Code/User/settings.json(macOS):

Exemple

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

Recommandations d'alias shell

Voici un ensemble complet d'alias Pi Agent, compatibles multiplateformes. Vous pouvez les ajouter à ~/.zshrc, ~/.bashrc, ou à un fichier de configuration shell équivalent :

Exemple

# Chemin du fichier : ~/.zshrc (pour les utilisateurs de bash, ~/.bashrc)
# Alias courants de Pi Agent
alias pin='pi --name'           # Démarrer une session nommée
alias pic='pi -c'               # Continuer la session la plus récente
alias pir='pi -r'               # Reprendre une session historique
alias piq='pi -p'               # Questions-réponses rapides et ponctuelles
alias pip='pi --print'          # Mode d'impression (identique à -p)
alias pif='pi --fork'           # Forker une session
alias pii='pi --no-session'     # Mode temporaire (non enregistré)
alias piro='pi --tools read,grep,find,ls'  # Mode lecture seule
alias pirev='pi -p "Examiner les modifications de code indexées (git diff --cached)"'

Si vous utilisez le shell fish, remplacez alias par abbr ou utilisez la syntaxe d'alias de fish.

# fish shell 使用 abbr 定义缩写
abbr -a pic pi -c
Autres extensions