Tutoriel de prise en main de Pi Coding Agent
Pi est un agent de codage IA qui s'exécute dans le terminal, similaire à des outils comme Claude Code et OpenAI Codex CLI.
La philosophie officielle de Pi est :« Il existe de nombreux harnais d'agents, mais celui-ci est le vôtre »(Il existe de nombreux outils d'agent, mais celui-ci est le vôtre).
Donnez une phrase à Pi, et il peut lire des fichiers, écrire des fichiers et exécuter des commandes dans le répertoire de votre projet, en appelant de manière répétée le grand modèle de langage jusqu'à ce que la tâche soit terminée.
La philosophie centrale est un noyau minimal associé à une extensibilité extrême, vous permettant de modeler l'outil pour qu'il vous convienne, plutôt que l'inverse, c'est-à-dire de vous adapter à l'outil.
Tutoriel complet sur Pi Agent :https://www.example.com/pi-agent/pi-agent-tutorial.html
Que comprend Pi ?
Pi n'est pas un seul programme, mais une chaîne d'outils composée de quatre paquets npm.
Les utilisateurs ordinaires n'ont qu'à installer le paquet de niveau supérieur@earendil-works/pi-coding-agent, et vous obtenez un agent en ligne de commande prêt à l'emploi.
À qui est-ce destiné
Pi est particulièrement adapté aux scénarios et utilisateurs suivants :
- Développeurs qui préfèrent les flux de travail en terminal et ne veulent pas passer sans cesse entre les IDE et la ligne de commande
- Utilisateurs avancés qui veulent un outil hautement personnalisable—même un outil qui permet à l'Agent de se réécrire lui-même
- Personnes qui ont besoin de se connecter à plusieurs grands modèles de langage à la fois (Anthropic, OpenAI, Google, etc.)
- Développeurs qui veulent intégrer les capacités de l'Agent dans leurs propres programmes (via le SDK ou le mode RPC)
Remarque : Pi s'exécute avec vos permissions utilisateur par défaut et n'a pas de bac à sable intégré. Avant de l'utiliser sur des dépôts non fiables, veuillez lire la section « Notes de sécurité » de cet article.
Philosophie de conception centrale : des primitives, pas des fonctionnalités
Comprendre la philosophie de conception de Pi vous aidera à voir pourquoi il n'intègre délibérément pas de nombreuses fonctionnalités que d'autres Agents possèdent.
Pi appelle ce conceptDes primitives, pas des fonctionnalités(fournir des primitives, pas des fonctionnalités).
Fonctionnalités délibérément non intégrées
Pi n'inclut pas les fonctionnalités suivantes ; il vous permet plutôt de les implémenter à la demande via des extensions ou des outils externes :
| Fonctionnalités non incluses | Alternative de Pi |
|---|---|
| Intégration du protocole MCP | Écrire l'outil comme une CLI avec un README, ou installer une extension MCP |
| Sous-agents | Utiliser tmux pour ouvrir plusieurs sessions, ou écrire votre propre extension |
| Fenêtre contextuelle de confirmation d'autorisation | L'exécuter dans un conteneur, ou écrire votre propre extension de flux de confirmation |
| Mode plan | Écrire le plan dans un fichier, ou écrire une extension |
| Todos intégrés | Utiliser un fichier TODO.md, ou installer une extension |
| Bash en arrière-plan | Utilisez tmux pour une observabilité complète |
Pourquoi faire cela
Pi estime que ces fonctionnalités varient considérablement selon les équipes, et les imposer rendrait l'outil lourd et difficile à adapter aux flux de travail réels.
Son approche consiste donc à : garder un noyau minimal et propre, et transformer toutes les « fonctionnalités » en extensions, compétences, modèles de prompt et thèmes installables, modifiables et partageables.
Vous pouvez même demander à Pi d'écrire ces fonctionnalités pour vous, et une fois écrites, utilisez/reloadreload, et cela fonctionne immédiatement.
Cette phrase mérite d'être retenue :Adaptez Pi à vos flux de travail, pas l'inverse(Faites en sorte que Pi s'adapte à votre flux de travail, et non que vous vous adaptiez à Pi).
Architecture et paquets principaux
Pi se compose de quatre paquets clairement hiérarchisés, les couches supérieures dépendant des couches inférieures.
Celui que vous utilisez habituellementpiLa commande n'est que le point d'entrée fourni par le paquet le plus élevé.
Quatre packages principaux
| Nom du package | Objectif | Quand l'utiliser séparément |
|---|---|---|
@earendil-works/pi-coding-agent | CLI d'Agent de codage interactif, le point d'entrée que les utilisateurs installent et utilisent directement | Dans la plupart des cas, seul celui-ci est nécessaire |
@earendil-works/pi-agent-core | Runtime d'Agent, responsable de la boucle d'appel des outils et de la gestion de l'état | Quand vous voulez créer vous-même un Agent non dédié au codage |
@earendil-works/pi-ai | API LLM unifiée multi-fournisseurs (OpenAI, Anthropic, Google, etc.) | Quand vous voulez simplement une interface unifiée pour appeler plusieurs modèles |
@earendil-works/pi-tui | Bibliothèque d'interface utilisateur pour terminal, prenant en charge le rendu des diffs | Quand vous voulez écrire votre propre application terminal |
Quatre modes d'exécution
Pi n'est pas limité au mode interactif ; il propose quatre modes pour différents scénarios :
| Mode | Description | Scénario typique |
|---|---|---|
| Interactif | Expérience complète d'interface terminal | Codage quotidien, développement conversationnel |
| Print / JSON | pi -p "提问"Sortie ponctuelle ;--mode jsonFlux d'événements de sortie | Automatisation de scripts, traitement de pipeline |
| RPC | Communication par protocole JSON via stdin/stdout | Intégration de programmes non-Node |
| SDK | Intégrer en tant que bibliothèque dans votre application | Intégrer les capacités d'Agent dans vos propres produits |
Installation
Pi propose plusieurs méthodes d'installation, couvrant macOS, Linux et Windows.
L'approche la plus courante consiste à installer globalement via npm, mais vous pouvez également utiliser le script officiel en un clic.
Méthode 1 : Script en un clic (recommandé pour les débutants)
Les utilisateurs de macOS et Linux utilisent curl :
curl -fsSL https://pi.dev/install.sh | sh
Les utilisateurs de Windows utilisent PowerShell :
powershell -c "irm https://pi.dev/install.ps1 | iex"
Méthode 2 : Installation globale npm
Si vous avez déjà installé Node.js, installez-le simplement globalement à l'aide du gestionnaire de paquets.
Notez le--ignore-scriptsparamètre : il ignore les scripts de cycle de vie de l'installation des dépendances. Pi n'a pas besoin de ces scripts pour un usage normal, et l'ajouter est plus sûr.
# npm 安装 npm install -g --ignore-scripts @earendil-works/pi-coding-agent # pnpm 安装 pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent # bun 安装 bun add -g --ignore-scripts @earendil-works/pi-coding-agent
Vérifier l'installation
Après l'installation, vérifiez le numéro de version pour confirmer que l'installation a réussi :
pi --version
Par exemple :
$ pi --version 0.80.6
Désinstaller
La méthode de désinstallation dépend de la façon dont vous l'avez installé à l'origine :
# curl 装的或 npm 装的 npm uninstall -g @earendil-works/pi-coding-agent # pnpm 装的 pnpm remove -g @earendil-works/pi-coding-agent # bun 装的 bun uninstall -g @earendil-works/pi-coding-agent
Remarque : La désinstallation de Pi ne supprimera pas votre configuration. Les paramètres, les identifiants, les enregistrements de session et les paquets Pi installés sont tous conservés dans le
~/.pi/agent/répertoire et doivent être nettoyés manuellement.
Configurer le fournisseur de modèle
Pi lui-même n'inclut pas de grand modèle de langage ; il vous demande de fournir des identifiants d'accès pour au moins un fournisseur de modèle.
Il existe deux méthodes de configuration : la connexion par abonnement ou la clé API.
Méthode 1 : Connexion par abonnement (la plus simple)
Si vous disposez déjà d'un abonnement Claude Pro/Max, ChatGPT Plus/Pro ou GitHub Copilot, vous pouvez vous connecter directement et le réutiliser.
Après avoir démarré Pi, exécutez/login, puis sélectionnez le fournisseur :
# 启动 pi pi # 在 pi 里执行登录命令 /login
Il existe trois fournisseurs d'abonnement facultatifs :
| Provider | Exigence | Description |
|---|---|---|
| Claude Pro / Max | Abonnement Anthropic | L'utilisation d'outils tiers est facturée par Token et n'est pas décomptée de votre quota d'abonnement |
| ChatGPT Plus / Pro（Codex） | Abonnement OpenAI | Officiellement reconnu par OpenAI via Codex pour l'OSS |
| GitHub Copilot | Abonnement Copilot | S'il indique que le modèle n'est pas pris en charge, vous devez d'abord activer le modèle correspondant dans VS Code |
Après la connexion, les identifiants sont stockés dans~/.pi/agent/auth.json, et seront automatiquement actualisés à leur expiration. Pour vous déconnecter, utilisez/logout。
Méthode 2 : clé API (la plus flexible)
Transmettre la clé API via les variables d'environnement est l'approche la plus universelle. Par exemple, en utilisant la clé d'Anthropic :
# 设置环境变量后启动 export ANTHROPIC_API_KEY=sk-ant-... pi
Vous pouvez également exécuter dans Pi/loginet choisissez un fournisseur de type API Key, puis conservez la clé dansauth.json。
Variables d'environnement pour les fournisseurs courants
Pi prend en charge plus de 15 fournisseurs ; les plus courants sont répertoriés ci-dessous :
| Provider | Variable d'environnement | Nom de la clé dans auth.json |
|---|---|---|
| Anthropic | ANTHROPIC_API_KEY | anthropic |
| OpenAI | OPENAI_API_KEY | openai |
| Google Gemini | GEMINI_API_KEY | |
| DeepSeek | DEEPSEEK_API_KEY | deepseek |
| Groq | GROQ_API_KEY | groq |
| Mistral | MISTRAL_API_KEY | mistral |
| xAI | XAI_API_KEY | xai |
| OpenRouter | OPENROUTER_API_KEY | openrouter |
| Hugging Face | HF_TOKEN | huggingface |
Remarque :
auth.jsonLes identifiants dans ... ont la priorité sur les variables d'environnement. Si les deux sont configurés, le premierauth.jsonprévaut.
Structure de auth.json
Si vous souhaitez gérer manuellement les identifiants, vous pouvez modifier directement~/.pi/agent/auth.json. Ce fichier est défini avec des permissions 0600 (lisible et modifiable uniquement par l'utilisateur actuel) lors de sa création :
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." },
"openai": { "type": "api_key", "key": "sk-..." },
"google": { "type": "api_key", "key": "..." }
}
Le champ Key prend également en charge trois formes de syntaxe avancées pour récupérer commodément des valeurs depuis un gestionnaire de mots de passe ou des variables d'environnement :
| Syntaxe | Signification | Exemple |
|---|---|---|
"!command" | Commence par un point d'exclamation, exécute la commande et prend stdout comme clé | "!op read 'op://vault/item/cred'" |
"$variable name" | Récupère la valeur d'une variable d'environnement | "$MY_ANTHROPIC_KEY" |
| Littéral simple | Utilisé directement comme clé | "sk-ant-..." |
Fournisseurs de plateformes cloud
Si vous utilisez des services de modèles basés sur le cloud, Pi prend également en charge Azure OpenAI, Amazon Bedrock, Google Vertex AI, Cloudflare, etc.
Ceux-ci nécessitent généralement une configuration supplémentaire pour le point de terminaison, la région ou le nom de déploiement. Prenons Azure OpenAI comme exemple :
# Azure OpenAI 所需的环境变量 export AZURE_OPENAI_API_KEY=... export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com # 可选：API 版本与部署名映射 export AZURE_OPENAI_API_VERSION=2024-02-01 export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4o=my-gpt4o
Configurer le fournisseur DeepSeek
Pi prend en charge les fournisseurs personnalisés via models.json. Chemin du fichier de configuration :
- Linux / macOS：~/.pi/agent/models.json
- Windows：%USERPROFILE%\.pi\agent\models.json
Tout d'abord, obtenez une clé API depuis la plateforme ouverte DeepSeek :https://platform.deepseek.com/api_keys。
{
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com",
"api": "openai-completions",
"apiKey": "$DEEPSEEK_API_KEY",
"models": [
{
"id": "deepseek-v4-pro",
"name": "DeepSeek V4 Pro",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 1.74,
"output": 3.48,
"cacheRead": 0.145,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
},
{
"id": "deepseek-v4-flash",
"name": "DeepSeek V4 Flash",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 0.14,
"output": 0.28,
"cacheRead": 0.028,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
}
]
}
}
}
Définir les variables d’environnement :
Utilisateurs de Linux / Mac :
export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Utilisateurs de Windows :
$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Entrez dans le répertoire du projet et exécutez la commande pi :
cd /path/to/my-project pi
Entrez/modelOuvrez le sélecteur de modèle, sélectionnez deepseek, puis choisissez DeepSeek-V4-Pro ou DeepSeek-V4-Flash.
Pour plus d’options de configuration, consultez :https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md。
Ordre de résolution des identifiants
Lorsque Pi a besoin d’identifiants pour un fournisseur, il recherche dans l’ordre suivant et utilise le premier trouvé :
| Priorité | Source |
|---|---|
| 1 (la plus élevée) | Ligne de commande--api-keyArguments |
| 2 | auth.jsonEntrées dans ... (clé API ou jeton OAuth) |
| 3 | Variable d'environnement |
| 4 | models.jsonClé d'un fournisseur personnalisé dans ... |
Premier lancement
Après avoir configuré les identifiants, entrez dans votre répertoire de projet et exécutez directement.piDémarrage.
# 进入项目目录 cd /path/to/project # 启动 pi pi
Après le démarrage, saisissez directement une phrase et appuyez sur Entrée, par exemple, demandez-lui d'analyser ce dépôt :
Summarize this repository and tell me how to run its checks.
Pi lira automatiquement les fichiers, exécutera les commandes, puis donnera un résumé et des méthodes de vérification.
Invite de confiance du projet
S'il y en a dans le répertoire courant ou un répertoire parent.piConfiguration, extensions, compétences et autres ressources au niveau du projet, Pi vous demandera d'abord si vous faites confiance à ce projet lors du démarrage interactif.
Cela vise à empêcher un dépôt de charger silencieusement ses extensions ou de modifier les paramètres à votre insu.
Remarque : la décision de confiance est enregistrée dans
~/.pi/agent/trust.json. Mode non interactif (-p、--mode json) ne s'affichera pas, et utilise par défaut ledefaultProjectTrusthandle.
Comment fonctionne l'agent
Chaque fois que vous envoyez un message, Pi démarre une boucle d'agent. Comprendre cette boucle, c'est comprendre comment Pi fonctionne.
Le cœur est la boucle de tours au milieu : le modèle peut appeler des outils à chaque tour, Pi exécute les outils et réinjecte les résultats dans le contexte, puis laisse le modèle continuer, jusqu'à ce que le modèle n'appelle plus d'outils et donne une réponse finale.
Quatre outils intégrés
Par défaut, Pi ne donne que quatre outils au modèle, couvrant les capacités essentielles de lecture, d'écriture et d'exécution du codage.
| Outil | Objectif | Activé par défaut |
|---|---|---|
read | Lire le contenu du fichier | Oui |
write | Créer ou écraser des fichiers | Oui |
edit | Appliquer des modifications partielles de correctif aux fichiers | Oui |
bash | Exécuter des commandes shell | Oui |
grep | Rechercher dans le contenu des fichiers | Non (doit être activé via les options d'outil) |
find | Trouver des fichiers selon des critères | Non (doit être activé via les options d'outil) |
ls | Lister le contenu d'un répertoire | Non (doit être activé via les options d'outil) |
Contrôler les outils disponibles
Vous pouvez contrôler précisément les outils que le modèle peut utiliser via des arguments de ligne de commande.
Cela est utile lorsque vous devez restreindre les capacités de l'Agent, par exemple en le laissant uniquement examiner le code sans effectuer de modifications :
# 只读模式：只允许读取和搜索类工具 pi --tools read,grep,find,ls -p "审查这段代码" # 禁用某个工具，其余保留 pi --exclude-tools ask_question # 关闭所有内置工具，只保留扩展提供的工具 pi --no-builtin-tools -e ./my-extension.ts # 完全禁用工具，纯对话 pi --no-tools -p "解释一下这个概念"
Rappel : Pi s'exécute dans votre répertoire de travail actuel et peut modifier vos fichiers. Il est recommandé de l'utiliser avec un système de contrôle de version tel que git pour pouvoir revenir en arrière facilement à tout moment.
Donnez des instructions au projet avec AGENTS.md
AGENTS.md est le fichier d'instructions de projet de Pi, indiquant au modèle quelles règles le projet a, comment l'exécuter et à quoi faire attention.
Il fonctionne de manière similaire au CLAUDE.md de Claude Code — et Pi prend en charge les deux noms de fichiers.
Écrivez un AGENTS.md
Créez-le dans le répertoire racine du projetAGENTS.md, écrivez les règles que vous souhaitez que le modèle suive :
# 项目指令 - 改完代码后运行 `npm run check`。 - 不要在本地跑生产环境的数据库迁移。 - 回答尽量简洁。
D'où Pi charge-t-il les instructions
Pi charge les fichiers d'instructions depuis plusieurs emplacements au démarrage, par ordre décroissant de portée :
| Emplacement | Portée | Description |
|---|---|---|
~/.pi/agent/AGENTS.md | Global | Instructions générales qui s'appliquent à tous vos projets |
Répertoire parentAGENTS.md | Niveau projet | Recherche en remontant niveau par niveau à partir du répertoire courant |
du répertoire courantAGENTS.md | Niveau projet | Les instructions les plus spécifiques et de plus haute priorité |
Pour les noms de fichiers,AGENTS.mdouCLAUDE.mdn'importe lequel d'entre eux fonctionne ; Pi les reconnaît tous.
Modifier le prompt système
AGENTS.md contient des instructions supplémentaires ajoutées au-delà du prompt système par défaut. Si vous souhaitez un contrôle plus approfondi, vous pouvez remplacer l'intégralité du prompt système.
Le placer dans le projet.pi/SYSTEM.mdremplacera le prompt système par défaut ; le placer.pi/APPEND_SYSTEM.mdsignifie l'ajout (correspondant globalement au~/.pi/agent/fichier du même nom sous).
Remarque : après avoir modifié les fichiers d'instructions, n'oubliez pas d'exécuter dans Pi
/reloadreload, ou de redémarrer Pi, pour que les nouvelles instructions prennent effet.
Opérations courantes en mode interactif
Le mode interactif est la forme de Pi la plus couramment utilisée ; maîtriser quelques opérations clés vous permet de l'utiliser efficacement.
Fichier de référence : @
Saisir dans l'éditeur@Une recherche floue des fichiers du projet s'affiche ; après sélection, le contenu du fichier est envoyé au modèle comme contexte.
Vous pouvez également fournir des fichiers directement en démarrant depuis la ligne de commande :
# 启动时带上一个文件 pi @README.md "总结一下这个文件" # 带上多个文件一起审查 pi @src/app.ts @src/app.test.ts "一起审查这两个文件"
Exécuter une commande shell : !
Dans l'éditeur, en commençant par!saisir une commande l'exécutera directement et enverra la sortie au modèle :
# 运行命令，输出会进入模型上下文 !npm run lint # 两个感叹号：运行但不把输出加进模型上下文 !!npm run build
Changer de modèle et d'effort de réflexion
Pi prend en charge le changement de modèle et d'effort de réflexion en cours de session pour s'adapter à la complexité des différentes tâches.
| Action | Raccourci / Commande | Description |
|---|---|---|
| Ouvrir le sélecteur de modèle | /modelou Ctrl+L | Choisissez-en un parmi tous les modèles disponibles |
| Basculer l’effort de réflexion | Shift+Tab | Parcourir : off / minimal / low / medium / high / xhigh / max |
| Parcourir les modèles favoris | Ctrl+P / Shift+Ctrl+P | Basculer rapidement entre les quelques modèles que vous avez présélectionnés |
Vous pouvez également spécifier le modèle et l’effort de réflexion directement au démarrage :
# 指定厂商和模型 pi --provider openai --model gpt-4o "帮我重构" # 用 厂商/模型 的写法 pi --model openai/gpt-4o "帮我重构" # 用 名称:思考强度 的简写 pi --model sonnet:high "解决这个复杂问题" # 限定可在 Ctrl+P 里循环的模型 pi --models "claude-*,gpt-4o"
Conseils de saisie et d’édition
| Action | Méthode | Description |
|---|---|---|
| Saisie multiligne | Shift+Enter (Ctrl+Enter dans Windows Terminal) | Insérer un saut de ligne dans un message |
| Complétion de chemin | Onglet | Compléter les chemins de fichiers |
| Coller une image | Ctrl+V (utiliser Alt+V sous Windows) | Vous pouvez également glisser-déposer des images dans le terminal. |
| Copier la réponse | Ctrl+X | Copier le dernier message de l'assistant |
| Éditeur externe | Ctrl+G | Ouvrir $VISUAL / $EDITOR pour modifier un texte long |
Interrompre pendant l'exécution
Pendant que l'agent travaille, vous n'avez pas à attendre ; vous pouvez insérer un message à tout moment.
| Touche | Comportement | Cas d'utilisation |
|---|---|---|
| Entrée | Message de pilotage : livré immédiatement après la fin de l'outil en cours, interrompant les outils restants. | Lorsque vous remarquez qu'il dévie, corrigez-le rapidement. |
| Alt+Entrée | Message de suivi : livré après que l'agent a complètement terminé. | Lorsque vous souhaitez ajouter une nouvelle exigence. |
| Échap | Abandonner le travail en cours et restaurer les messages en file d'attente dans l'éditeur. | Lorsque vous voulez arrêter et réorganiser. |
Astuce : dans Windows Terminal, Alt+Entrée bascule en plein écran par défaut ; les raccourcis clavier pour le guidage et les messages de suivi peuvent être modifiés dans les paramètres en
steeringModeetfollowUpModeles modifiant.
Référence rapide des commandes slash courantes
Saisissez dans l'éditeur/L'autocomplétion des commandes s'affichera. Voici les commandes slash les plus courantes.
| Commande | Fonction |
|---|---|
/login / /logout | Gérer les identifiants OAuth ou les clés API |
/model | Changer de modèle |
/scoped-models | Définir quels modèles participent à la boucle Ctrl+P |
/settings | Ajuster l'effort de réflexion, le thème, la livraison des messages, etc. |
/resume | Choisir une session dans l'historique pour continuer |
/new | Démarrer une nouvelle session |
/name <名称> | Donner un nom d'affichage à la session actuelle |
/session | Afficher le fichier de session, l'ID, le nombre de messages, l'utilisation des tokens et le coût |
/tree | Sauter vers n'importe quel nœud de l'arborescence de session et continuer à partir de là |
/fork | Créer une nouvelle session à partir d'un message historique |
/clone | Copier la branche actuelle en tant que nouvelle session |
/compact [提示] | Compacter manuellement le contexte, éventuellement avec des instructions personnalisées |
/copy | Copier le dernier message de l'assistant dans le presse-papiers |
/export [文件] | Exporter la session au format HTML ou JSONL |
/import <文件> | Importer et restaurer une session depuis un fichier JSONL |
/share | Téléverser en tant que GitHub Gist privé pour générer un lien HTML partageable |
/reload | Recharger les raccourcis clavier, les extensions, les compétences, les prompts, les thèmes et les fichiers de contexte |
/trust | Enregistrer la décision de confiance pour le projet actuel |
/hotkeys | Afficher tous les raccourcis clavier |
/changelog | Afficher l'historique des mises à jour de version |
/quit | Quitter Pi |
Gestion des sessions : historique de l'arborescence
Les sessions de Pi ne sont pas une ligne droite ; elles forment un arbre.
Cela signifie que si vous bifurquez à n'importe quel nœud historique, la branche d'origine n'est pas perdue ; toutes les branches existent dans le même fichier de session.
Où sont stockées les sessions
Les sessions sont automatiquement enregistrées dans~/.pi/agent/sessions/, regroupées par répertoire de travail.
Restaurer ou parcourir les sessions historiques à partir de la ligne de commande :
# 继续最近一次会话 pi -c # 浏览并选择一个历史会话 pi -r # 给会话起个名字，方便日后查找 pi --name "my task" # 打开指定的会话文件或 ID pi --session <path|id> # 临时会话，不保存 pi --no-session
Naviguer dans l'arborescence des sessions
use/treeVous pouvez ouvrir la vue arborescente des sessions et accéder à n'importe quel nœud historique pour continuer.
Continuer à partir de là crée une nouvelle branche, tandis que la branche d'origine reste inchangée.
Fork et clonage
| Commande | Comportement | Différence |
|---|---|---|
/fork | Forker une nouvelle session à partir d'un message utilisateur antérieur. | Redémarrer à partir d'un certain point de l'historique. |
/clone | Cloner la branche active courante dans une nouvelle session. | Créer une copie basée sur l'état le plus récent. |
Compresser le contexte
Lorsque la conversation devient longue et approche de la limite de contexte du modèle, Pi compresse automatiquement les messages antérieurs en un résumé.
Vous pouvez également le déclencher manuellement avec/compact, et vous pouvez ajouter une instruction personnalisée lui indiquant quoi conserver dans la compression :
# 在 pi 里手动压缩，并要求保留最近改动 /compact 重点保留最近的改动和错误处理
Exporter et partager
Exporter la session au format HTML pour l’archivage ou la présentation :
# 导出为 HTML 文件 /export my-session.html # 上传为私有 GitHub Gist，得到分享链接 /share
Mode non interactif et intégration
Pi ne sert pas uniquement aux conversations interactives ; il peut aussi être utilisé comme outil en ligne de commande, flux d’événements, service RPC et bibliothèque SDK.
Question ponctuelle : mode print
use-pLaissez Pi répondre puis quitter, adapté à l’appel dans des scripts :
# 直接提问 pi -p "总结一下这个代码库" # 配合管道，把内容喂给 Pi cat README.md | pi -p "总结这段文字" # 带图片提问 pi -p @screenshot.png "这张图里是什么？"
Flux d’événements : mode JSON
--mode jsonProduit tous les événements sous forme de lignes JSON pour faciliter l’analyse programmatique :
# 输出 JSON 事件流 pi --mode json -p "列出 src 下所有 .ts 文件"
Intégration de processus : mode RPC
--mode rpcUtilise le protocole JSON via stdin/stdout, adapté aux programmes non-Node (par ex. Python, Go) pour piloter Pi.
Exporter une session existante
Sans démarrer une nouvelle session, exportez directement un fichier de session existant au format HTML :
# 把会话文件导出为 HTML pi --export session.jsonl output.html
Mode SDK
Si vous souhaitez intégrer les capacités de Pi dans votre propre application Node, vous pouvez utiliser le mode SDK pour l'inclure en tant que bibliothèque.
Il s'agit d'une intégration plus étroite que RPC ; consultez la section SDK dans la documentation officielle :https://pi.dev/docs/latest/sdk。
Extensions
Les extensions sont au cœur de l'extensibilité de Pi. Ce sont des modules TypeScript qui peuvent s'abonner aux événements du cycle de vie, enregistrer des outils personnalisés et ajouter des commandes et des raccourcis.
Les extensions sont chargées via jiti, vous pouvez donc écrire du TypeScript directement sans compilation.
Où placer les extensions
| Emplacement | Portée |
|---|---|
~/.pi/agent/extensions/*.ts | Global, s'applique à tous les projets |
.pi/extensions/*.ts | Au niveau du projet, effectif uniquement pour le projet actuel |
Elle peut aussi se présenter sous forme de sous-répertoire (扩展名/index.ts), ou avecpackage.jsonUn ensemble complet.
Un exemple minimal d'extension
L'extension suivante démontre trois choses : la notification de démarrage, l'interception des commandes dangereuses et l'enregistrement d'un outil personnalisé et d'une commande.
// 文件路径：~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
// 扩展导出一个默认工厂函数，接收 ExtensionAPI
export default function (pi: ExtensionAPI) {
// 1. 监听 session_start 事件：会话启动时弹个通知
pi.on("session_start", async (_event, ctx) => {
ctx.ui.notify("扩展已加载！", "info");
});
// 2. 监听 tool_call 事件：拦截危险的 bash 命令
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
// 弹确认框，用户拒绝就阻止执行
const ok = await ctx.ui.confirm("危险操作！", "允许执行 rm -rf 吗？");
if (!ok) return { block: true, reason: "被用户阻止" };
}
});
// 3. 注册一个自定义工具，模型可以调用它
pi.registerTool({
name: "greet",
label: "打招呼",
description: "按名字向某人打招呼",
parameters: Type.Object({
name: Type.String({ description: "要打招呼的名字" }),
}),
async execute(toolCallId, params, signal, onUpdate, ctx) {
return {
content: [{ type: "text", text: `你好，${params.name}！` }],
details: {},
};
},
});
// 4. 注册一个斜杠命令 /hello
pi.registerCommand("hello", {
description: "打个招呼",
handler: async (args, ctx) => {
ctx.ui.notify(`你好 ${args || "world"}！`, "info");
},
});
}
Après avoir écrit, utilisez-ele paramètre pour charger temporairement à des fins de test :
# 临时加载一个扩展来测试 pi -e ./my-extension.ts
Que peuvent faire les extensions
Les capacités des extensions vont bien au-delà de ce qui précède ; elles peuvent intervenir dans presque toutes les parties du flux de travail Pi :
| Capacité | Méthode correspondante | Utilisation typique |
|---|---|---|
| Enregistrer des outils personnalisés | pi.registerTool() | Permettre au modèle d'appeler votre interface métier |
| Enregistrer des commandes | pi.registerCommand() | Ajoutez vos propres commandes slash |
| Enregistrer des raccourcis | pi.registerShortcut() | Lier des raccourcis personnalisés |
| Intercepter les appels d’outils | tool_callÉvénement | Confirmation des autorisations, réécriture des commandes |
| Modifier le contexte | contextÉvénement | Filtrer l’historique, injecter du contenu RAG |
| Injecter des messages | pi.sendMessage() | Compléter dynamiquement le contexte |
| Enregistrer des fournisseurs | pi.registerProvider() | Accéder à des passerelles de modèles privées |
| Interface utilisateur personnalisée | ctx.uiSéries | Boîtes de dialogue, barre d'état, composants |
Astuce : le dépôt Pi contient plus de 50 extensions d'exemple, couvrant les sous-agents, le mode de planification, les contrôles de permission, l'exécution SSH, le bac à sable, etc. C'est la meilleure référence pour apprendre le développement d'extensions.
Compétences
Les compétences sont un autre type de paquet de capacités réutilisables. La différence avec les extensions est que les compétences sont principalement des instructions et des scripts pour le modèle, chargés à la demande.
Pi implémente le standard Agent Skills, il peut donc directement utiliser les compétences d'outils comme Claude Code et OpenAI Codex.
Fonctionnement des compétences
Les compétences utilisent le principe de divulgation progressive.
Au démarrage, Pi ne place que le nom et la description de chaque compétence dans le prompt système ; lorsqu'une tâche correspond, le modèle utilisereadl'outil pour charger la description complète de la compétence.
Ainsi, vous pouvez installer de nombreuses compétences sans saturer le contexte dès le départ.
Où placer les compétences
| Emplacement | Portée |
|---|---|
~/.pi/agent/skills/ | Global |
~/.agents/skills/ | Global (partagé entre les outils) |
.pi/skills/ | Niveau projet (nécessite que le projet soit approuvé) |
.agents/skills/ | Niveau projet (partagé entre les outils) |
Structure d'une compétence
Une compétence est un répertoire contenantSKILL.mdrépertoire, et le reste des fichiers peut être organisé librement.
my-skill/
├── SKILL.md # 必需：前置信息 + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 按需加载的详细文档
│ └── api-reference.md
└── assets/
└── template.json
Comment écrire SKILL.md
Le haut de SKILL.md est le frontmatter, et en dessous se trouve le corps d'instructions pour le modèle :
--- name: my-skill description: 这个技能做什么、什么时候用。要写具体。 --- # My Skill ## Setup 首次使用前运行一次： ```bash cd /path/to/skill && npm install ``` ## Usage ```bash ./scripts/process.sh <input> ```
Les deux champs les plus importants du frontmatter :
| Champ | Obligatoire ? | Description |
|---|---|---|
name | Requis | Jusqu'à 64 caractères, uniquement des lettres minuscules, des chiffres et des traits d'union |
description | Requis | Jusqu'à 1024 caractères, détermine quand le modèle charge cette compétence. Soyez précis. |
Rappel :
descriptionLa qualité de sa rédaction détermine directement si le modèle utilisera cette compétence au bon moment. Écrire « Traiter les fichiers PDF, extraire le texte et les tableaux, remplir des formulaires, fusionner plusieurs PDF » est bien mieux que d'écrire « Aider à traiter les PDF ».
Invoquer manuellement les compétences
Il se peut que le modèle ne charge pas toujours une compétence de lui-même. Vous pouvez utiliser/skill:名称Forcer le chargement et l'exécution :
# 加载并执行技能 /skill:brave-search # 带参数加载技能 /skill:pdf-tools extract
Gestion des paquets Pi
Les extensions, les compétences, les modèles de prompt et les thèmes peuvent tous être empaquetés en packages Pi et partagés/installés via npm ou git.
Pi dispose d'un ensemble intégré de commandes de gestion de packages, vous permettant d'étendre les capacités comme si vous installiez des plugins.
Installation et désinstallation
# 从 npm 安装一个包 pi install npm:@foo/pi-tools # 从 git 仓库安装 pi install git:github.com/badlogic/pi-doom # 项目本地安装（加 -l） pi install npm:@foo/pi-tools -l # 卸载 pi remove npm:@foo/pi-tools
Mises à jour et consultation
| Commande | Fonction |
|---|---|
pi list | Lister les packages installés |
pi update | Mettre à jour uniquement Pi lui-même |
pi update --all | Mettre à jour Pi et tous les packages |
pi update --extensions | Mettre à jour uniquement les paquets, laisser Pi lui-même inchangé |
pi update --extension <源> | Mettre à jour un paquet spécifié |
pi config | Activer ou désactiver des ressources dans le paquet |
Notes de sécurité
La sécurité est un élément essentiel à comprendre avant d'utiliser Pi. Le modèle de sécurité de Pi diffère de celui de nombreux outils Agent et nécessite votre coopération active.
Aucun bac à sable intégré
Pi n'inclut pas de bac à sable intégré, il s'exécute en tant que l'utilisateur qui l'a lancé et dispose de toutes les permissions de cet utilisateur.
Les outils intégrés peuvent lire et écrire des fichiers et exécuter des commandes shell ; les extensions sont des modules TypeScript avec les mêmes permissions que le processus Pi.
C'est intentionnel : Pi doit pouvoir travailler sur du code source local, invoquer les chaînes d'outils du projet et s'intégrer dans l'environnement de développement. Un bac à sable en processus incomplet ferait croire à tort qu'il s'agit d'une frontière de sécurité, alors qu'en réalité il dépend toujours du shell, du système de fichiers et des identifiants de l'hôte.
Important : l'isolation réelle doit provenir du système d'exploitation ou des frontières de conteneur/virtualisation, et non de l'intérieur de Pi.
Confiance du projet
La confiance du projet détermine si Pi charge les paramètres, ressources, extensions et paquets au niveau du projet.
Lorsqu’un répertoire contient.pi/settings.json、.pi/extensions、.pi/skills、.pi/SYSTEM.mdet un contenu similaire, Pi exigera une confirmation de confiance avant le chargement.
| Niveau de confiance | Comportement | Méthode de paramétrage |
|---|---|---|
ask(Par défaut) | Invite interactive ; ignorer les ressources du projet en mode non interactif | de settings.jsondefaultProjectTrust |
always | Toujours faire confiance aux ressources du projet | Identique à ci-dessus, ou utilisez-a / --approve |
never | Ne jamais faire confiance, ignorer les ressources du projet | Identique à ci-dessus, ou utilisez-na / --no-approve |
Les décisions de confiance sont enregistrées dans~/.pi/agent/trust.json, consignées par chemin de répertoire, la décision du répertoire parent le plus proche étant prioritaire.
Remarque : la confiance accordée au projet n'est qu'une « garde de chargement d'entrée » qui empêche les dépôts de modifier silencieusement vos paramètres ou extensions, maisne peut pas sécuriser du code, des prompts ou des sorties de modèle non fiables. L'injection de prompt dans les fichiers, commentaires et documentation des dépôts est un risque inhérent aux agents locaux, et Pi ne peut pas l'empêcher de manière fiable.
Gestion des tâches non fiables ou sans surveillance
Pour les dépôts non fiables, le code généré qui nécessite une surveillance rapprochée, ou l'automatisation sans surveillance, la recommandation officielle est d'exécuter Pi dans un environnement isolé.
Pratiques recommandées :
- Mettez tout le
piprocessus dans un conteneur, une machine virtuelle ou un bac à sable distant - Ne montez que les chemins d'espace de travail auxquels l'Agent doit accéder
- Sauf si nécessaire, ne montez pas celui de l'hôte
~/.pi/agent(qui contient vos identifiants et sessions) - Ne transmettez que les clés API minimales nécessaires, ou utilisez des identifiants à court terme
- Restreignez l'accès réseau lorsque la tâche ne nécessite pas Internet
- Examinez les diffs et les sorties avant de copier les résultats vers un système fiable
Rappel : Si vous montez l'espace de travail de l'hôte dans le conteneur en mode lecture-écriture, les écritures à l'intérieur du conteneur modifieront quand même les fichiers de l'hôte. Pour une protection renforcée contre les écritures accidentelles, utilisez des montages en lecture seule, ou copiez les fichiers dans et hors du bac à sable.
Ressources et communauté
Ressources officielles
- Dépôt GitHub :github.com/earendil-works/pi
- Site officiel :pi.dev
- Documentation officielle :pi.dev/docs/latest
- Paquet npm :@earendil-works/pi-coding-agent