Enregistrement des commandes et raccourcis de Pi Agent

Enregistrez des commandes personnalisées, des raccourcis clavier et des options CLI via des extensions pour que Pi Agent s'adapte mieux à votre flux de travail.


Enregistrer des commandes personnalisées

Utilisationpi.registerCommand()Enregistrez des commandes que les utilisateurs peuvent invoquer avec /.

L'extension suivante illustre à la fois une commande de base et une commande avec auto-complétion des paramètres :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/stats-command.ts

// Commande de base
pi.registerCommand("stats", {
  description: "Afficher les statistiques pour la session en cours", // Requis, affiché dans la liste d'auto-complétion pour /
  handler: async (args, ctx) => {
    const count = ctx.sessionManager.getEntries().length;
    ctx.ui.notify(`Total ${count}messages`, "info");
  }
});

// Commande avec auto-complétion des paramètres
pi.registerCommand("deploy", {
  description: "Déployer vers l'environnement spécifié",
  // Définir l'auto-complétion des paramètres ; prefix est le préfixe du paramètre que l'utilisateur a déjà saisi
  getArgumentCompletions: (prefix) => {
    const envs = ["dev", "staging", "prod"];
    const items = envs
      .filter(e => e.startsWith(prefix))
      .map(e => ({ value: e, label: e }));
    return items.length > 0 ? items : null; // Renvoie null lorsqu'il n'y a pas de correspondance
  },
  handler: async (args, ctx) => {
    if (!args) {
      ctx.ui.notify("Utilisation : /deploy <nom de l'environnement>", "warning");
      return;
    }
    ctx.ui.notify(`Déploiement vers ${args}environnement...`, "info");
  },
});

Après avoir enregistré, exécutez /reload pour charger l'extension, puis tapez /stats dans la zone de l'éditeur pour voir l'effet :

/stats
共 42 条消息

Si plusieurs extensions enregistrent des commandes portant le même nom, Pi Agent conserve tous les enregistrements et ajoute des suffixes numériques dans l'ordre de chargement, par exemple /review:1 et /review:2.

Cela évite les conflits de nommage entre extensions.


Extensions envoyant proactivement des messages

En plus de répondre passivement aux commandes et aux événements, les extensions peuvent aussi piloter proactivement la conversation.

pi.sendMessage(message, deliverAs?)Utilisé pour injecter des messages personnalisés,pi.sendUserMessage(text, deliverAs?)simule une saisie utilisateur.

deliverAs a trois valeurs : steer est la valeur par défaut, qui insère le message dans le tour courant ; followUp l'ajoute après ce tour ; nextTurn démarre un nouveau tour (uniquement pris en charge par sendMessage).

sendUserMessage déclenche toujours une réponse, car pour l'IA il s'agit d'un véritable énoncé utilisateur.

Lors de l'appel de ces deux méthodes pendant la sortie en streaming, vous devez fournir explicitement deliverAs, sinon une erreur sera immédiatement levée.

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/follow-up.ts
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension

// Simuler une demande complémentaire de l'utilisateur : l'ajouter après la fin de l'exécution de tous les outils actuels
pi.sendUserMessage("Après le déploiement, veuillez également consulter les journaux de l'environnement de production", {
  deliverAs: "followUp",
});

// Injecter uniquement des informations de référence dans le contexte, sans simuler un énoncé utilisateur
pi.sendMessage({
  customType: "deploy-context",
  content: "La cible de déploiement actuelle est la production",
  display: true,
}, {
  deliverAs: "steer", // Valeur par défaut, insérée dans le tour actuel
});

sendMessage prend également en charge triggerTurn: true, ce qui déclenche immédiatement une réponse LLM lorsque l'agent est inactif.

Le choix entre les deux est simple : utilisez sendUserMessage si vous voulez que l'IA réponde réellement, et sendMessage si vous souhaitez uniquement fournir des informations de référence.


Contexte de commande (ExtensionCommandContext)

Le gestionnaire de commande reçoit unExtensionCommandContextExtensionCommandContext, qui hérite de ExtensionContext.

En plus du contexte normal, il fournit également les méthodes suivantes :

MéthodeDescription
ctx.getSystemPromptOptions()Lire l'entrée de base pour construire le prompt système (contextFiles, skills, etc.), disponible uniquement dans le contexte de commande.
ctx.waitForIdle()Attendre que l'IA soit complètement au repos (y compris les tentatives, la compaction et les messages de suivi tous terminés).
ctx.newSession(options)Créer une nouvelle session, avec la possibilité de spécifier une session parente et une logique d'initialisation.
ctx.fork(entryId, options)Créer une nouvelle session à partir d'une entrée spécifiée.
ctx.navigateTree(targetId, options)Naviguer vers une position spécifiée dans l'arbre de session.
ctx.switchSession(sessionPath, options)Passer à un autre fichier de session.
ctx.reload()Effectuer le même processus de rechargement à chaud que /reload.

La commande suivante liste toutes les sessions du projet actuel sous forme de liste de sélection ; une fois qu'une session est sélectionnée, on bascule directement vers celle-ci :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/switch-session.ts
import { SessionManager } from "@earendil-works/pi-coding-agent";

pi.registerCommand("switch", {
  description: "Basculer vers une autre session",
  handler: async (args, ctx) => {
    // Lister toutes les sessions du projet actuel
    const sessions = await SessionManager.list(ctx.cwd);
    if (sessions.length === 0) {
      ctx.ui.notify("Aucune session disponible", "warning");
      return;
    }

    // Afficher une liste de sélection
    const choice = await ctx.ui.select(
      "Sélectionnez la session vers laquelle basculer :",
      sessions.map(s => s.file),
    );

    if (choice) {
      // Passer à la session sélectionnée
      await ctx.switchSession(choice, {
        withSession: async (ctx) => {
          ctx.ui.notify("Session changée", "info");
        },
      });
    }
  },
});
/switch
┌ 选择要切换的会话:
│ > ~/.pi/agent/sessions/my-project/abc123.jsonl
│   ~/.pi/agent/sessions/my-project/def456.jsonl
└
已切换会话

Notes sur le remplacement de session: le ctx dans le callback withSession est un contexte tout nouveau.

N'utilisez pas l'ancien objet pi ni le ctx capturé dans les callbacks de commande ; ils deviennent invalides après le remplacement de session.


Enregistrer les raccourcis clavier

Utilisationpi.registerShortcut()Enregistrez des raccourcis clavier personnalisés.

Ce qui suit associe "Toggle Plan Mode" à une combinaison de touches qui n'est pas encore utilisée par une liaison intégrée :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/plan-shortcut.ts

pi.registerShortcut("ctrl+shift+g", {
  description: "Basculer le mode Plan",
  handler: async (ctx) => {
    ctx.ui.notify("Mode Plan basculé !", "info");
  },
});

Après le démarrage, appuyez sur la combinaison de touches pour le déclencher :

已切换 Plan 模式!

Avant de choisir une combinaison de touches, consultez le tableau des raccourcis par défaut pour éviter de remplacer les liaisons intégrées.

Par exemple, ctrl+shift+p est déjà utilisé par "Switch to Previous Model" ; enregistrer à nouveau la même combinaison de touches provoquera un conflit entre les deux comportements.

Le format du raccourci esttouche modificatrice + touche, par ex. ctrl+shift+g, alt+x, etc.


Enregistrer des indicateurs CLI

Utilisationpi.registerFlag()Ajouter des arguments CLI personnalisés à la commande pi.

L'exemple suivant enregistre un indicateur booléen --plan pour que l'IA produise d'abord un plan avant d'agir :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/plan-flag.ts

pi.registerFlag("plan", {
  description: "Démarrer en mode Plan",
  type: "boolean",
  default: false,
});

// Vérifier la valeur du drapeau dans le code de l'extension
// Remarque : pi.getFlag() n'a de valeur qu'une fois l'analyse des arguments de ligne de commande terminée,
// il est donc recommandé de placer la vérification dans une fonction de rappel d'événement plutôt qu'au niveau supérieur du module d'extension.
// L'évaluation du module au niveau supérieur se produit pendant le chargement de l'extension, et à ce stade, on lit toujours la valeur par défaut false.
pi.on("before_agent_start", async (event, ctx) => {
  if (!pi.getFlag("plan")) return; // Si --plan n'est pas activé, n'apporter aucune modification
  return {
    systemPrompt: event.systemPrompt
      + "\n\nMode Plan : proposer d'abord un plan, puis exécuter après confirmation de l'utilisateur.",
  };
});

Utilisation :

$ pi --plan "帮我实现用户认证功能"

Communication inter-extensions

Utilisationpi.eventsPartager des événements entre extensions.

L'émetteur n'a pas besoin de savoir qui écoute, et l'auditeur n'a pas besoin de savoir d'où vient l'événement :

Exemple

// Chemin de fichier : ~/.pi/agent/extensions/deploy-events.ts

// Extension A : envoyer des événements
pi.events.emit("deploy:completed", {
  env: "production",
  timestamp: Date.now(),
});

// Extension B : écouter les événements (généralement écrit dans un autre fichier d'extension)
pi.events.on("deploy:completed", (data) => {
  console.log(`Déploiement terminé : ${data.env}`);
});

Obtenir les commandes enregistrées

Utilisationpi.getCommands()Obtenir toutes les commandes disponibles dans la session actuelle.

L'exemple suivant enregistre une commande /my-commands pour lister toutes les commandes enregistrées par les extensions :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/list-commands.ts

pi.registerCommand("my-commands", {
  description: "Lister toutes les commandes enregistrées par les extensions",
  handler: async (args, ctx) => {
    const commands = pi.getCommands();

    // Catégoriser par source
    const extCommands = commands.filter(
      c => c.source === "extension"
    );
    const templates = commands.filter(
      c => c.source === "prompt"
    );
    const skills = commands.filter(
      c => c.source === "skill"
    );

    // Afficher le résultat pour éviter de seulement calculer sans produire de sortie
    ctx.ui.notify(
`Commandes d'extension ${extCommands.length}:`
        + extCommands.map(c => "/" + c.name).join("、"),
      "info"
    );
    console.table(commands);
  },
});
/my-commands
扩展命令 2 个:/stats、/deploy

Chaque entrée de commande contient les champs suivants :

ChampTypeDescription
namestringNom de la commande, invoqué sous la forme /name dans la zone de l'éditeur.
descriptionstringDescription de la commande, affichée dans la liste d'autocomplétion
sourcestringType de source : extension, prompt, skill, etc.
sourceInfoobjetMétadonnées détaillées de la source, par exemple le chemin de l’extension qui l’a enregistré

Gestion dynamique des outils

Activer et désactiver les outils à l’exécution.

Un cas d’utilisation typique consiste à désactiver temporairement les outils d’écriture afin que l’IA puisse seulement lire mais pas modifier pendant une même tâche :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/manage-tools.ts

// Obtenir la liste des outils actuellement activés
const active = pi.getActiveTools();
// Par exemple : ["read", "bash", "edit", "write"]

// Obtenir les métadonnées de tous les outils enregistrés
const all = pi.getAllTools();

// Filtrer les outils intégrés
const builtinTools = all.filter(
  t => t.sourceInfo.source === "builtin"
);

// Filtrer les outils enregistrés par les extensions
const extTools = all.filter(
  t => t.sourceInfo.source !== "builtin"
    && t.sourceInfo.source !== "sdk"
);

// Activer dynamiquement les outils personnalisés (en conservant les outils existants)
pi.setActiveTools([...new Set([...active, "my_tool"])]);

// Passer en mode lecture seule : ne conserver que les outils de type lecture,
// en excluant bash / edit / write ; dans cet état, l'IA ne peut pas exécuter de commandes ni modifier de fichiers
pi.setActiveTools(["read", "grep", "find", "ls"]);

Ici, setActiveTools et le paramètre en ligne de commande--tools / --exclude-toolsagissent sur le même ensemble d'outils.

Le paramètre CLI détermine l'ensemble initial au démarrage, tandis que setActiveTools l'ajuste dynamiquement à l'exécution ; les deux peuvent être utilisés ensemble.

Les modifications transmises à setActiveTools doivent être additives ; supprimer des outils actuellement activés dans le même appel fera perdre l'optimisation du chargement différé.

De plus, l'activation d'outils avec promptSnippet ou promptGuidelines reconstruira l'invite système ; même si le modèle prend en charge le chargement différé, cela peut invalider le préfixe d'invite mis en cache.

Autres extensions