Pi Agent-Erweiterung: Erste Schritte
Extensions sind der leistungsstärkste Weg, Pi Agent anzupassen – Sie können benutzerdefinierte Tools, Befehle und Event-Listener in TypeScript schreiben.
Was ist eine Extension?
Eine Extension ist ein TypeScript-Modul, das Folgendes tun kann.
| Fähigkeit | Beschreibung | Typische Verwendung |
|---|---|---|
| Registrieren Siebenutzerdefinierte Tools | Neue aufrufbare Funktionen für die KI hinzufügen | Interne Systeme abfragen, Datenbanken lesen/schreiben, Drittanbieter-APIs wrappen |
| Registrieren Siebenutzerdefinierte Befehle | Von Benutzern über /command-name aufgerufen | Gängige Prompts bündeln, feste Workflows mit einem Klick ausführen |
| Abhören vonLebenszyklus-Ereignissen | Logik an verschiedenen Phasen der KI-Arbeit einfügen | Gefährliche Befehle abfangen, Kontext injizieren, Audit-Logs aufzeichnen |
| Registrieren vonTastaturkürzeln | Tasten in der Terminal-UI belegen | Schnell zwischen Panels wechseln, hochfrequente Operationen auslösen |
| Anzeigen vonbenutzerdefinierter UI | Interaktive Oberflächen im Terminal rendern | Komponenten wie Fortschrittsbalken, Listen und Bestätigungsdialoge |
Deine erste Erweiterung: Hello World
Die folgende Erweiterung demonstriert drei Fähigkeiten gleichzeitig: Ereignisüberwachung, Tool-Registrierung und Befehlsregistrierung.
Beispiel
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
export default function (pi: ExtensionAPI) {
// Ausgelöst, wenn die Sitzung startet
pi.on("session_start", async (_event, ctx) => {
ctx.ui.notify("Meine Erweiterung wurde geladen!", "info");
});
// Gefährliche Befehle abfangen
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command?.includes("rm -rf")) {
const ok = await ctx.ui.confirm("Gefährliche Operation!", "Möchtest du wirklich rm -rf ausführen?");
if (!ok) return { block: true, reason: "Vom Benutzer blockiert" };
}
});
// Benutzerdefiniertes Tool registrieren
pi.registerTool({
name: "greet",
label: "Begrüßen",
description: "Begrüße die angegebene Person",
parameters: Type.Object({
name: Type.String({ description: "Der Name der zu begrüßenden Person" }),
}),
async execute(toolCallId, params) {
return {
content: [{ type: "text", text:`Hello, ${params.name}!` }],
details: {},
};
},
});
// Einen benutzerdefinierten Befehl registrieren
pi.registerCommand("hello", {
description: "Begrüße die Welt",
handler: async (args, ctx) => {
ctx.ui.notify(`Hello ${args || "World"}!`, "info");
},
});
}
Die Ereignisprüfung in Zeile 13 verwendet den einfachstenevent.toolNameAnsatz; du kannst auch Type Guards verwenden, um das Ereignis auf einen bestimmten Ereignistyp einzugrenzen, siehe das Kapitel Event System.
Starte Pi Agent mit dem Parameter pi -e, um diese Erweiterung zum Testen zu laden:
$ pi -e ~/.pi/agent/extensions/my-extension.ts Loading extension: /Users/example/.pi/agent/extensions/my-extension.ts my-extension 加载成功(1 个工具、1 个命令) 我的扩展已加载!
Die letzte Zeile ist die Benachrichtigung, die von ctx.ui.notify im Ereignis session_start eingeblendet wurde; sie zeigt an, dass die Erweiterung wirksam geworden ist.
Ladeorte für Erweiterungen
Pi Agent entdeckt automatisch Erweiterungen in mehreren festen Verzeichnissen, und Sie können auch explizit Pfade angeben.
| Ort | Geltungsbereich | Beschreibung |
|---|---|---|
| ~/.pi/agent/extensions/*.ts | Global | Gilt für alle Projekte, automatisch entdeckt |
| ~/.pi/agent/extensions/*/index.ts | Global | Erweiterungen mit index.ts in Unterverzeichnissen |
| .pi/extensions/*.ts | Projekt | Nur aktuelles Projekt, erfordert Projektvertrauen |
| .pi/extensions/*/index.ts | Projekt | Erweiterungen in Projekt-Unterverzeichnissen |
Zusätzlich zu Befehlszeilenargumenten können Sie auch ein Array von Pfaden im Feld extensions von settings.json schreiben; Verzeichnispfade werden gemäß den Regeln für das Erweiterungsverzeichnis erweitert.
Beispiel
"extensions": [
"/Users/example/.pi/agent/extensions/quick-notify.ts",
"/Users/example/.pi/agent/extensions/team-tools"
]
}
Das erste Element ist eine Einzeldatei-Erweiterung und das zweite eine Verzeichnis-Erweiterung; ersetzen Sie sie in der tatsächlichen Verwendung durch Ihre eigenen Erweiterungsspeicherorte.
Dateistruktur der Erweiterung
Eine Erweiterung kann eine einzelne .ts-Datei oder ein Verzeichnis mit einer Einstiegsdatei sein.
Einzeldatei-Erweiterung
Die einfachste Form, geeignet für kleine Erweiterungen:
~/.pi/agent/extensions/ └── my-extension.ts
Verzeichnis-Erweiterung (mit index.ts)
Geeignet für Mehrdatei-Erweiterungen:
~/.pi/agent/extensions/
└── my-extension/
├── index.ts # 入口文件(导出默认函数)
├── tools.ts # 辅助模块
└── utils.ts # 工具函数
Erweiterung mit Abhängigkeiten
Geeignet für große Erweiterungen, die npm-Pakete erfordern:
~/.pi/agent/extensions/
└── my-extension/
├── package.json # 声明依赖和入口
├── node_modules/ # npm install 后生成
└── src/
└── index.ts
Erweiterungen werden mit Ihren Systemberechtigungen ausgeführt und können beliebigen Code ausführen.
Installieren Sie Erweiterungen nur aus vertrauenswürdigen Quellen.。
Mechanismus zum Laden von Erweiterungen
Erweiterungen werden überjitigeladen; TypeScript-Code kann direkt ohne Kompilierung ausgeführt werden.
Wenn Ihre Factory-Funktion ein Promise zurückgibt, wartet Pi Agent, bis es abgeschlossen ist, bevor der Startvorgang fortgesetzt wird.
Das bedeutet, dass Sie während der Initialisierung von Erweiterungen asynchrone Vorgänge ausführen können, z. B. das Abrufen einer Remote-Konfiguration.
Verfügbare Import-Pakete
Diese Pakete sind in Pi Agent integriert und können direkt in Erweiterungen importiert werden.
| Paketname | Zweck |
|---|---|
| @earendil-works/pi-coding-agent | Erweiterungstypen (ExtensionAPI, ExtensionContext und verschiedene Ereignistypen) |
| typebox | Schemadefinition für Tool-Parameter |
| @earendil-works/pi-ai | KI-Tools (wie StringEnum, für Google-kompatible Enums) |
| @earendil-works/pi-tui | TUI-Komponenten, für benutzerdefiniertes Rendering |
Diese integrierten Kernpakete werden von Pi selbst bereitgestellt; liste sie einfach als peerDependencies auf und bündle sie nicht in deine Erweiterung ein.
Deine eigenen Laufzeitabhängigkeiten müssen im Feld dependencies der package.json eingetragen werden.
Wenn Pi Erweiterungspakete installiert, führt es standardmäßig eine Produktionsinstallation durch (npm install --omit=dev), daher sind devDependencies zur Laufzeit nicht verfügbar.
Andere npm-Pakete können ebenfalls verwendet werden – füge eine package.json im Erweiterungsverzeichnis hinzu und führe npm install aus.
Entwicklungstipps
Diese Erfahrungswerte können dir helfen, Umwege zu vermeiden, besonders bei der Wahl der Lademethode.
| Ansatz | Grund |
|---|---|
| Lege die Erweiterung in das Verzeichnis~/.pi/agent/extensions/the directory | Unterstützt /reload Hot Reload, kein Neustart der Sitzung nach Änderungen nötig |
| pi -e ./path.tsNur zum temporären Testen | Für die langfristige Nutzung lege die Erweiterung in das Verzeichnis ~/.pi/agent/extensions/ und lasse Pi Agent sie automatisch erkennen. |
| Starte keine Hintergrundressourcen in der Erweiterungs-Factory-Funktion | Prozesse, Sockets, Datei-Watcher, Timer usw. sollten im session_start-Ereignis gestartet werden |
| Bereinige Ressourcen auf Sitzungsebene im session_shutdown-Ereignis | Vermeide zurückgebliebene Handles und Listener nach dem Wechseln von Sitzungen |
Weitere Integration
Neben dem Schreiben von Erweiterungen bietet das offizielle Team auch zwei programmatische Integrationswege.
Node- oder TypeScript-Projekte können direkt das exportierte SDK von@earendil-works/pi-coding-agentverwenden: Verwende createAgentSession, um Sitzungen zu erstellen, Ereignisse zu abonnieren und mit prompt Nachrichten zu senden.
Dieser Ansatz läuft im selben Prozess wie Pi und bietet vollständige Typdefinitionen.
Für sprachübergreifende Aufrufe oder wenn Prozessisolierung benötigt wird, wechsle zupi --mode rpcund kommuniziere mit dem Pi-Prozess über das JSONL-Protokoll.
Beide Wege nutzen dasselbe Ereignismodell wie Erweiterungen; welcher gewählt wird, hängt hauptsächlich davon ab, ob du einen unabhängigen Prozess benötigst.
Andere Erweiterungen