Système d'événements de Pi Agent
Le système d'événements est le mécanisme central des extensions.
En écoutant les événements du cycle de vie, vous pouvez insérer une logique personnalisée à différentes étapes du travail de l'IA.
Aperçu du cycle de vie
Voici tous les événements déclenchés pendant le cycle de vie de Pi Agent, du démarrage à la sortie :
Dans chaque tour, les événements context, provider et tool se déclenchent en séquence, en bouclant sur plusieurs tours lorsque des appels d'outils sont effectués.
Les parties en pointillés indiquent que l'étape peut être déclenchée plusieurs fois par plusieurs événements.
Pour le moment de déclenchement d'autres événements tels que input, before_agent_start, resources_discover et agent_settled, voir la référence rapide complète des événements ci-dessous.
Événements principaux expliqués
Cette section sélectionne les 5 événements les plus fréquemment utilisés et explique leur moment de déclenchement ainsi que les conventions de valeur de retour.
input — Interception de l'entrée
Déclenché avant que l'entrée utilisateur ne soit traitée ; vous pouvez transformer, intercepter ou traiter directement l'entrée :
Exemple
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("input", async (event, ctx) => {
// event.text - texte d'entrée brut
// event.images - images jointes
// event.source - "interactive" | "rpc" | "extension"
// Transformer l'entrée : ajouter une instruction au début de l'entrée
if (event.text.startsWith("?quick ")) {
return {
action: "transform",
text:`Réponse brève : ${event.text.slice(7)}`
};
}
// Traiter directement : répondre sans passer par le LLM
if (event.text === "ping") {
ctx.ui.notify("pong", "info");
return { action: "handled" };
}
// Ignorer les messages injectés par l'extension
if (event.source === "extension") {
return { action: "continue" };
}
return { action: "continue" }; // Par défaut : traiter normalement
});
| valeur de l'action | Effet |
|---|---|
| "continue" | Ne modifie pas l'entrée ; poursuit le flux de traitement normal |
| "transform" | Poursuit le traitement après avoir modifié l'entrée ; les transformations de plusieurs gestionnaires s'enchaînent |
| "handled" | Prend complètement le contrôle, en sautant l'appel au LLM (le premier gestionnaire qui renvoie cette valeur prend effet) |
Les effets réels de deux implémentations typiques sont les suivants.
Lorsque l'entrée est?quick hello world, le texte réellement envoyé au LLM a été réécrit :
简短回复:hello world
Lorsque l'entrée estping, le LLM n'est pas appelé ; seule une notification s'affiche dans le terminal :
pong
L'événement d'entrée se déclenche avant l'expansion des Skill et templateavant, donc ce que vous voyez est l'entrée brute.
/skill:foo et /template ne sont pas encore étendus à ce stade.
tool_call — Interception des appels d'outils
Déclenché avant l'exécution de l'outil ; vous pouvez modifier les arguments ou bloquer l'exécution :
Exemple
// les instructions import se placent en haut du module ; l'extrait pi.on ci-dessous se trouve dans le corps de la fonction factory de l'extension
// isToolCallEventType est un garde de type et doit être importé depuis le paquet officiel
import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
pi.on("tool_call", async (event, ctx) => {
// Bloquer les commandes bash dangereuses
if (isToolCallEventType("bash", event)) {
// event.input est { command: string; timeout?: number }
const dangerous = ["rm -rf /", "mkfs.", "dd if=", "> /dev/sda"];
// Vérifier d'abord si c'est dangereux, puis décider s'il faut l'autoriser
if (dangerous.some(cmd =>
event.input.command.includes(cmd))) {
return { block: true, reason: "La commande dangereuse a été bloquée" };
}
// Ajouter le chargement des variables d'environnement uniquement après que la vérification a réussi
event.input.command = `source ~/.profile\n${event.input.command}`;
}
// Journaliser toutes les opérations de lecture de fichiers
if (isToolCallEventType("read", event)) {
// event.input est { path: string; offset?: number; limit?: number }
ctx.ui.notify(`Lecture du fichier: ${event.input.path}`, "info");
}
});
Si l’IA tente d’exécuterrm -rf /, l’outil ne s’exécutera pas, et le terminal affichera la raison du blocage :
Dangerous command has been blocked.
event.inputest modifiable — le modifier directement affecte l’exécution de l’outil.
tool_result — Modification des résultats d’outil
Déclenché après la fin de l’exécution de l’outil ; vous pouvez modifier le résultat retourné au LLM :
Exemple
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("tool_result", async (event, ctx) => {
// event.toolName - nom de l’outil
// event.content - contenu renvoyé au LLM
// event.details - données de détail
// event.isError - indique s’il s’agit d’une erreur
// Exemple : ajouter des numéros de ligne aux résultats de read
if (event.toolName === "read" && !event.isError) {
const lines = event.content
.filter(c => c.type === "text")
.map(c => c.text)
.join("\n")
.split("\n")
.map((line, i) => `${i + 1}: ${line}`)
.join("\n");
return {
content: [{ type: "text", text: lines }],
};
}
});
Le contenu d'origine du fichier de deux lignes devient une forme numérotée par ligne lorsqu'il est transmis au LLM :
1: import { readFile } from "node:fs/promises";
2: export async function load() {
context — Modification du contexte LLM
Déclenché avant chaque appel LLM ; vous pouvez filtrer ou modifier les messages :
Exemple
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("context", async (event, ctx) => {
// event.messages - copie profonde des messages de contexte actuels ; modifiable sans risque
// Filtrer les messages d'un type spécifique
const filtered = event.messages.filter(m => {
// Supprimer les messages avec le type personnalisé "debug"
if (m.type === "custom" && m.customType === "debug") {
return false;
}
return true;
});
return { messages: filtered };
});
before_agent_start — Injection de messages
Déclenché avant que l'IA ne commence à traiter l'entrée utilisateur ; vous pouvez injecter des messages supplémentaires ou modifier le prompt système :
Exemple
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("before_agent_start", async (event, ctx) => {
// event.prompt - le texte du prompt de l'utilisateur
// event.systemPrompt - le prompt système actuellement configuré
return {
// Injecter un message persistant (stocké dans la session et envoyé au LLM)
message: {
customType: "my-context",
content:`L'heure actuelle est ${new Date().toISOString()}`,
display: true,
},
// Ajouter au prompt système
systemPrompt: event.systemPrompt
+ "\n\nVeuillez utiliser le chinois dans toutes les réponses.",
};
});
Référence rapide complète des événements
Plusieurs événements apparaissaient également dans le diagramme ASCII de la section précédente ; ils sont ici listés ensemble par ordre de déclenchement pour faciliter la consultation.
| Événement | Moment de déclenchement | Modifiable | Bloquable |
|---|---|---|---|
| project_trust | Avant de charger les ressources du projet ; confirmer s'il faut faire confiance au projet actuel | non | Oui (les extensions du projet ne sont pas chargées en cas de refus) |
| session_start | Lorsque la session démarre ou reprend | non | non |
| resources_discover | Déclenché après session_start (au démarrage/rechargement) | Oui (peut uniquement ajouter des Skills, des modèles de prompt et des chemins de thème ; ne peut pas ajouter ou supprimer des extensions) | non |
| input | Avant que l'entrée utilisateur ne soit traitée | Oui (peut transformer l'entrée) | Oui (le gestionnaire prend le relais) |
| before_agent_start | Avant que l'IA ne commence à traiter l'entrée utilisateur | Oui (peut injecter des messages, modifier le prompt système) | non |
| agent_start | Lorsque la boucle de l'agent démarre | non | non |
| message_start / message_update | Pendant la génération de message (message_update est le delta de streaming de l'assistant) | non | non |
| message_end | Lorsque les messages user, assistant et toolResult sont finalisés | Oui (peut retourner { message } pour remplacer le message final ; role doit correspondre) | non |
| turn_start | Au début de chaque tour | non | non |
| context | Avant chaque appel LLM | Oui (peut filtrer les messages) | non |
| before_provider_headers | Avant l'envoi des en-têtes de requête HTTP | Oui (peut ajouter ou modifier les en-têtes de requête) | non |
| before_provider_request | Avant que le corps de la requête ne soit envoyé au modèle | Oui (retourner une valeur non undefined remplace l'intégralité de la charge utile de la requête, plutôt que d'abandonner la requête) | non |
| after_provider_response | Après réception de la réponse HTTP, avant que le corps en streaming soit consommé | Non (peut seulement lire le statut/les en-têtes pour observation) | non |
| tool_execution_start | Lorsque l'outil commence à s'exécuter | non | non |
| tool_call | Avant l'exécution de l'outil | Oui (event.input est modifiable) | Oui (block: true) |
| tool_execution_update | Lorsqu'une progression est générée pendant l'exécution de l'outil | non | non |
| tool_result | Après la fin de l'exécution de l'outil | Oui (le contenu retourné peut être modifié) | non |
| tool_execution_end | Lorsque l'exécution de l'outil se termine | non | non |
| turn_end | À la fin de chaque tour | non | non |
| agent_end | Lorsque la boucle de l'agent se termine | non | non |
| agent_settled | Après qu'un cycle d'interaction soit entièrement stabilisé | non | non |
| session_before_switch | Avant que /new ou /resume soit exécuté | non | Oui (return { cancel: true }) |
| session_before_fork | Avant l'exécution de /fork ou /clone | non | Oui (return { cancel: true }) |
| session_before_compact | Avant l'exécution de la compression (manuelle /compact, seuil, dépassement du contexte) | Oui (résumé de compression personnalisable) | Oui (return { cancel: true }) |
| session_shutdown | Déclenché avant la destruction de la session ; quit, /new, /resume, /fork, /reload le déclenchent tous (la raison est quit/reload/new/resume/fork) | non | non |
Points clés de la gestion des événements
Lors de l'écriture de gestionnaires d'événements, les points suivants déterminent si le code est robuste.
| Méthode | Objectif |
|---|---|
| Plusieurs extensions écoutent le même événement | Exécutés en séquence selon l'ordre de chargement des extensions ; la valeur de retour précédente affecte les gestionnaires suivants |
| Retourner{ block: true, reason: "..." } | Bloquer l'opération ; la raison sera affichée à l'utilisateur et à l'IA |
| Retourner{ cancel: true } | Annuler les opérations telles que le changement de session |
| Utiliserctx.signal | Répondre aux signaux d'annulation dans les opérations asynchrones ; abandonner lorsque l'utilisateur appuie sur Échap |
| Utiliserctx.uiSérie de méthodes | Interagir avec l'utilisateur, comme notify, confirm, select, etc. |
| utiliserctx.hasUIProtéger les appels de dialogue | En modes Print/JSON/RPC, les méthodes de type dialogue ne sont pas disponibles ou sans effet ; vérifier avant d'appeler |
| utiliserctx.mode === "tui"Protéger les API spécifiques à TUI | custom(), les fabriques de composants, l'entrée terminal, etc. ne sont valides qu'en mode interactif |
Autres extensionsNe démarrez pas de ressources en arrière-plan (processus, sockets, timers, etc.) dans la fonction factory de l'extension.
Différez le démarrage des ressources jusqu'à l'événementsession_start, et nettoyez danssession_shutdown.