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ähigkeitBeschreibungTypische Verwendung
Registrieren Siebenutzerdefinierte ToolsNeue aufrufbare Funktionen für die KI hinzufügenInterne Systeme abfragen, Datenbanken lesen/schreiben, Drittanbieter-APIs wrappen
Registrieren Siebenutzerdefinierte BefehleVon Benutzern über /command-name aufgerufenGängige Prompts bündeln, feste Workflows mit einem Klick ausführen
Abhören vonLebenszyklus-EreignissenLogik an verschiedenen Phasen der KI-Arbeit einfügenGefährliche Befehle abfangen, Kontext injizieren, Audit-Logs aufzeichnen
Registrieren vonTastaturkürzelnTasten in der Terminal-UI belegenSchnell zwischen Panels wechseln, hochfrequente Operationen auslösen
Anzeigen vonbenutzerdefinierter UIInteraktive Oberflächen im Terminal rendernKomponenten 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

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

OrtGeltungsbereichBeschreibung
~/.pi/agent/extensions/*.tsGlobalGilt für alle Projekte, automatisch entdeckt
~/.pi/agent/extensions/*/index.tsGlobalErweiterungen mit index.ts in Unterverzeichnissen
.pi/extensions/*.tsProjektNur aktuelles Projekt, erfordert Projektvertrauen
.pi/extensions/*/index.tsProjektErweiterungen 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.

PaketnameZweck
@earendil-works/pi-coding-agentErweiterungstypen (ExtensionAPI, ExtensionContext und verschiedene Ereignistypen)
typeboxSchemadefinition für Tool-Parameter
@earendil-works/pi-aiKI-Tools (wie StringEnum, für Google-kompatible Enums)
@earendil-works/pi-tuiTUI-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.

AnsatzGrund
Lege die Erweiterung in das Verzeichnis~/.pi/agent/extensions/the directoryUnterstützt /reload Hot Reload, kein Neustart der Sitzung nach Änderungen nötig
pi -e ./path.tsNur zum temporären TestenFü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-FunktionProzesse, Sockets, Datei-Watcher, Timer usw. sollten im session_start-Ereignis gestartet werden
Bereinige Ressourcen auf Sitzungsebene im session_shutdown-EreignisVermeide 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