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éDescriptionUtilisation typique
Enregistrerdes outils personnalisésAjouter de nouvelles fonctions appelables pour l'IAInterroger des systèmes internes, lire/écrire dans des bases de données, encapsuler des API tierces
Enregistrerdes commandes personnaliséesInvoquées par les utilisateurs via /command-nameEnvelopper des prompts courants, exécuter des workflows fixes en un clic
Écouter lesévénements de cycle de vieInsérer de la logique à différentes étapes du travail de l'IAIntercepter les commandes dangereuses, injecter du contexte, enregistrer des journaux d'audit
Enregistrer lesraccourcis clavierAssocier des touches dans l'interface utilisateur du terminalBasculer rapidement entre les panneaux, déclencher des opérations à haute fréquence
Afficherune interface utilisateur personnaliséeAfficher des interfaces interactives dans le terminalComposants 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

// Chemin du fichier : ~/.pi/agent/extensions/my-extension.ts
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.

EmplacementPortéeDescription
~/.pi/agent/extensions/*.tsGlobalValable pour tous les projets, découverte automatique
~/.pi/agent/extensions/*/index.tsGlobalExtensions avec index.ts dans les sous-répertoires
.pi/extensions/*.tsProjetProjet actuel uniquement, nécessite que le projet soit approuvé
.pi/extensions/*/index.tsProjetExtensions 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 paquetObjectif
@earendil-works/pi-coding-agentTypes d'extension (ExtensionAPI, ExtensionContext et divers types d'événements)
typeboxDéfinition de schéma pour les paramètres d'outil
@earendil-works/pi-aiOutils d'IA (tels que StringEnum, pour les énumérations compatibles avec Google)
@earendil-works/pi-tuiComposants 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.

ApprocheRaison
Placez l'extension dans~/.pi/agent/extensions/le répertoirePrend en charge le rechargement à chaud /reload, pas besoin de redémarrer la session après modifications
pi -e ./path.tsUniquement pour des tests temporairesPour 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'extensionLes 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