Premiers pas avec l'extension Pi Agent
Les extensions sont le moyen le plus puissant de personnaliser Pi Agent : vous pouvez écrire des outils, commandes et écouteurs d'événements personnalisés en TypeScript.
Qu'est-ce qu'une extension
Une extension est un module TypeScript qui peut effectuer les opérations suivantes.
| Capacité | Description | Utilisation typique |
|---|---|---|
| Enregistrerdes outils personnalisés | Ajouter de nouvelles fonctions appelables pour l'IA | Interroger des systèmes internes, lire/écrire dans des bases de données, encapsuler des API tierces |
| Enregistrerdes commandes personnalisées | Invoquées par les utilisateurs via /command-name | Envelopper des prompts courants, exécuter des workflows fixes en un clic |
| Écouter lesévénements de cycle de vie | Insérer de la logique à différentes étapes du travail de l'IA | Intercepter les commandes dangereuses, injecter du contexte, enregistrer des journaux d'audit |
| Enregistrer lesraccourcis clavier | Associer des touches dans l'interface utilisateur du terminal | Basculer rapidement entre les panneaux, déclencher des opérations à haute fréquence |
| Afficherune interface utilisateur personnalisée | Afficher des interfaces interactives dans le terminal | Composants tels que les barres de progression, les listes et les boîtes de dialogue de confirmation |
Votre première extension : Hello World
L'extension suivante illustre trois capacités à la fois : l'écoute d'événements, l'enregistrement d'outils et l'enregistrement de commandes.
Exemple
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
export default function (pi: ExtensionAPI) {
// Déclenché au démarrage de la session
pi.on("session_start", async (_event, ctx) => {
ctx.ui.notify("Mon extension a été chargée !", "info");
});
// Intercepter les commandes dangereuses
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command?.includes("rm -rf")) {
const ok = await ctx.ui.confirm("Opération dangereuse !", "Êtes-vous sûr de vouloir exécuter rm -rf ?");
if (!ok) return { block: true, reason: "Utilisateur bloqué" };
}
});
// Enregistrer un outil personnalisé
pi.registerTool({
name: "greet",
label: "Saluer",
description: "Saluer la personne spécifiée",
parameters: Type.Object({
name: Type.String({ description: "Le nom de la personne à saluer" }),
}),
async execute(toolCallId, params) {
return {
content: [{ type: "text", text:`Hello, ${params.name}!` }],
details: {},
};
},
});
// Register a custom command
pi.registerCommand("hello", {
description: "Saluer le monde",
handler: async (args, ctx) => {
ctx.ui.notify(`Hello ${args || "World"}!`, "info");
},
});
}
La vérification d'événement à la ligne 13 utilise l'approche la plus simpleevent.toolName; vous pouvez également utiliser des gardes de type pour restreindre l'événement à un type d'événement spécifique, voir le chapitre Système d'événements.
Démarrez Pi Agent avec le paramètre pi -e pour charger cette extension à des fins de test :
$ pi -e ~/.pi/agent/extensions/my-extension.ts Loading extension: /Users/example/.pi/agent/extensions/my-extension.ts my-extension 加载成功(1 个工具、1 个命令) 我的扩展已加载!
La dernière ligne est la notification affichée par ctx.ui.notify dans l'événement session_start, ce qui indique que l'extension a pris effet.
Emplacements de chargement des extensions
Pi Agent découvre automatiquement les extensions dans plusieurs répertoires fixes, et vous pouvez également spécifier explicitement des chemins.
| Emplacement | Portée | Description |
|---|---|---|
| ~/.pi/agent/extensions/*.ts | Global | Valable pour tous les projets, découverte automatique |
| ~/.pi/agent/extensions/*/index.ts | Global | Extensions avec index.ts dans les sous-répertoires |
| .pi/extensions/*.ts | Projet | Projet actuel uniquement, nécessite que le projet soit approuvé |
| .pi/extensions/*/index.ts | Projet | Extensions des sous-répertoires du projet |
En plus des arguments de ligne de commande, vous pouvez également écrire un tableau de chemins dans le champ extensions de settings.json ; les chemins de répertoire sont développés selon les règles des répertoires d'extensions.
Exemple
"extensions": [
"/Users/example/.pi/agent/extensions/quick-notify.ts",
"/Users/example/.pi/agent/extensions/team-tools"
]
}
Le premier élément est une extension à fichier unique, et le second est une extension de type répertoire ; remplacez-les par vos propres emplacements d’extension lors de l’utilisation réelle.
Structure des fichiers d’extension
Une extension peut être un simple fichier .ts ou un répertoire avec un fichier d’entrée.
Extension à fichier unique
La forme la plus simple, adaptée aux petites extensions :
~/.pi/agent/extensions/ └── my-extension.ts
Extension de type répertoire (avec index.ts)
Adaptée aux extensions multi-fichiers :
~/.pi/agent/extensions/
└── my-extension/
├── index.ts # 入口文件(导出默认函数)
├── tools.ts # 辅助模块
└── utils.ts # 工具函数
Extension avec dépendances
Adaptée aux extensions volumineuses qui nécessitent des paquets npm :
~/.pi/agent/extensions/
└── my-extension/
├── package.json # 声明依赖和入口
├── node_modules/ # npm install 后生成
└── src/
└── index.ts
Les extensions s’exécutent avec vos autorisations système et peuvent exécuter du code arbitraire.
Installez uniquement des extensions provenant de sources fiables.。
Mécanisme de chargement des extensions
Les extensions sont chargées via le chargementjiti; le code TypeScript peut s'exécuter directement sans compilation.
Si votre fonction de fabrique renvoie une Promise, Pi Agent attend qu'elle se termine avant de poursuivre le processus de démarrage.
Cela signifie que vous pouvez effectuer des opérations asynchrones pendant l'initialisation de l'extension, comme la récupération d'une configuration distante.
Paquets d'importation disponibles
Ces paquets sont intégrés à Pi Agent et peuvent être importés directement dans les extensions.
| Nom du paquet | Objectif |
|---|---|
| @earendil-works/pi-coding-agent | Types d'extension (ExtensionAPI, ExtensionContext et divers types d'événements) |
| typebox | Définition de schéma pour les paramètres d'outil |
| @earendil-works/pi-ai | Outils d'IA (tels que StringEnum, pour les énumérations compatibles avec Google) |
| @earendil-works/pi-tui | Composants TUI, pour un rendu personnalisé |
Ces paquets principaux intégrés sont fournis par Pi lui-même ; listez-les simplement comme peerDependencies, et ne les intégrez pas dans votre extension.
Vos propres dépendances d'exécution doivent être écrites dans le champ dependencies de package.json.
Lorsque Pi installe des paquets d'extension, il effectue par défaut une installation de production (npm install --omit=dev), donc les devDependencies ne sont pas disponibles à l'exécution.
D'autres paquets npm peuvent également être utilisés—ajoutez un package.json dans le répertoire de l'extension et exécutez npm install.
Conseils de développement
Ces retours d'expérience peuvent vous aider à éviter des détours, surtout lors du choix de la méthode de chargement.
| Approche | Raison |
|---|---|
| Placez l'extension dans~/.pi/agent/extensions/le répertoire | Prend en charge le rechargement à chaud /reload, pas besoin de redémarrer la session après modifications |
| pi -e ./path.tsUniquement pour des tests temporaires | Pour une utilisation à long terme, placez l'extension dans le répertoire ~/.pi/agent/extensions/ et laissez Pi Agent la découvrir automatiquement. |
| Ne démarrez pas de ressources en arrière-plan dans la fonction de fabrique d'extension | Les processus, sockets, observateurs de fichiers, minuteurs, etc. doivent être démarrés dans l'événement session_start |
| Nettoyez les ressources au niveau de la session dans l'événement session_shutdown | Évitez les handles et écouteurs résiduels après avoir changé de session |
Intégration plus poussée
Outre l'écriture d'extensions, l'équipe officielle fournit également deux voies d'intégration programmatique.
Les projets Node ou TypeScript peuvent directement utiliser@earendil-works/pi-coding-agentle SDK exporté : utilisez createAgentSession pour créer des sessions, vous abonner aux événements et prompt pour envoyer des messages.
Cette approche s'exécute dans le même processus que Pi et dispose de définitions de types complètes.
Pour les appels inter-langages ou lorsqu'une isolation de processus est nécessaire, passez àpi --mode rpc, et communiquez avec le processus Pi via le protocole JSONL.
Les deux voies partagent le même modèle d'événements que les extensions ; le choix dépend principalement de si vous avez besoin d'un processus indépendant.
Autres extensions