Pi Agent Entwicklung benutzerdefinierter Tools
Registriere benutzerdefinierte Tools über Extension, sodass die KI die von dir geschriebenen Funktionen aufrufen kann, um bestimmte Aufgaben zu erledigen.
Grundlagen der Tool-Registrierung
Verwendungpi.registerTool()Registriere ein KI-aufrufbares Tool:
Beispiel
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";
// Eine Todo-Liste definieren (In-Memory-Speicher)
let todos: string[] = [];
export default function (pi: ExtensionAPI) {
// Zustand beim Start aus der Sitzung wiederherstellen
pi.on("session_start", async (_event, ctx) => {
todos = [];
for (const entry of ctx.sessionManager.getBranch()) {
if (entry.type === "message"
&& entry.message.role === "toolResult"
&& entry.message.toolName === "todo") {
todos = entry.message.details?.todos ?? [];
}
}
});
pi.registerTool({
name: "todo",
label: To-do-Liste,
description: Verwalte die To-do-Liste des Projekts,
// Kurze Beschreibung, angezeigt im Abschnitt „Verfügbare Tools“ des System-Prompts
promptSnippet: Projekt-Todos verwalten: list listet auf, add fügt hinzu, done schließt ab,
// Nutzungsrichtlinien, angehängt an den Abschnitt „Guidelines“ des System-Prompts
promptGuidelines: [
Verwende das Todo-Tool zur Aufgabenplanung; bearbeite Todo-Dateien nicht direkt,
],
parameters: Type.Object({
// StringEnum gewährleistet Google-API-Kompatibilität
action: StringEnum(["list", "add", "done"] as const),
text: Type.Optional(Type.String({
description: Beim Hinzufügen: Beschreibung des Eintrags. Beim Abschließen: Eintragsnummer oder Beschreibung
})),
}),
// Abwärtskompatibel mit dem alten Parameterformat
prepareArguments(args) {
if (!args || typeof args !== "object") return args;
const input = args as { action?: string; oldAction?: string };
// Alte Felder neuen Feldern zuordnen
if (typeof input.oldAction === "string"
&& input.action === undefined) {
return { ...input, action: input.oldAction };
}
return args;
},
async execute(toolCallId, params, signal, onUpdate, ctx) {
if (signal?.aborted) {
return {
content: [{ type: "text", text: Vorgang abgebrochen }]
};
}
// Fortschrittsaktualisierung senden
onUpdate?.({
content: [{ type: "text", text:`Verarbeite: ${params.action}` }],
});
switch (params.action) {
case "list":
return {
content: [{
type: "text",
text: todos.length === 0
? Todo-Liste ist leer
: todos.map((t, i) => `${i + 1}. ${t}`).join("\n"),
}],
details: { todos: [...todos] },
};
case "add":
if (!params.text) {
throw new Error(Die add-Operation erfordert einen text-Parameter);
}
todos.push(params.text);
// Der 5. Parameter ctx ist der Erweiterungskontext; hier verwenden wir ihn, um eine Benachrichtigung im Terminal aufpoppen zu lassen
ctx.ui.notify(`Todo hinzugefügt: ${params.text}`, "info");
return {
content: [{
type: "text",
text:`Hinzugefügt: ${params.text}(insgesamt ${todos.length}Element(e))`,
}],
details: { todos: [...todos] },
};
case "done":
if (!params.text) {
throw new Error(Die done-Operation erfordert einen text-Parameter);
}
const idx = todos.findIndex(
t => t.includes(params.text!)
);
if (idx === -1) {
return {
content: [{
type: "text",
text:`Kein passendes Element gefunden: ${params.text}`
}],
details: { todos: [...todos] },
};
}
const removed = todos.splice(idx, 1)[0];
return {
content: [{
type: "text",
text:`Abgeschlossen: ${removed}(verbleibend ${todos.length}Element(e))`,
}],
details: { todos: [...todos] },
};
default:
throw new Error(Unbekannte Operation);
}
},
});
}
Nach der Registrierung entscheidet die KI autonom, wann sie das Todo-Tool basierend auf description und promptSnippet aufruft.
Wenn der Benutzer beispielsweise sagt: "Füge 'Wochenbericht schreiben' zu meiner To-do-Liste hinzu", führt die KI den folgenden Aufruf aus:
tool_call: todo
{
"action": "add",
"text": "写周报"
}
Nachdem execute ausgeführt wurde, lautet der an die KI zurückgegebene Text wie folgt:
待办已新增:写周报(共 1 项)
Nach Erhalt dieses Ergebnisses bestätigt die KI dem Benutzer in natürlicher Sprache, z. B.: "'Wochenbericht schreiben' zur To-do-Liste hinzugefügt; derzeit insgesamt 1 Eintrag."
Neben dem Wiederaufbau des Zustands aus den Details in toolResult gibt es einen weiteren Weg für die Persistenz über Neustarts hinweg:pi.appendEntry()。
Es schreibt benutzerdefinierte Einträge direkt in die Sitzungsdatei; in Kombination mitpi.registerEntryRenderer()können sie auch im Gesprächsverlauf gerendert werden.
Benutzerdefinierte Einträge gelangen nicht in den LLM-Kontext, daher verbrauchen sie keine Tokens.
Sie werden jedoch mit der Sitzung gespeichert und im /tree-Zweig beibehalten.
Tool-Definition erklärt
Das Konfigurationsobjekt von registerTool enthält die folgenden Felder, wobei name, parameters und execute den Kern bilden.
| Feld | Type | Erforderlich | Beschreibung |
|---|---|---|---|
| name | string | Ja | Die eindeutige Kennung des Tools; die KI ruft es unter diesem Namen auf |
| label | string | Ja | Anzeigename des Tools |
| description | string | Ja | Funktionsbeschreibung des Tools; die KI verwendet sie, um zu entscheiden, wann das Tool verwendet werden soll |
| parameters | TypeBox-Schema | Ja | Typdefinition der Tool-Parameter |
| promptSnippet | string | nein | Einzeilige Zusammenfassung im Abschnitt „Verfügbare Tools“ |
| promptGuidelines | string[] | nein | Richtlinien, die an den Abschnitt „Guidelines“ des System-Prompts angehängt werden |
| prepareArguments | Funktion | nein | Transformiert Parameter vor der Schema-Validierung, wird für die Kompatibilität mit alten Formaten verwendet |
| execute | async-Funktion | Ja | Die tatsächliche Ausführungslogik des Tools |
Jede Richtlinie in promptGuidelines mussausdrücklich den Tool-Namen nennen。
Schreibe nicht „when using this tool...“; schreibe stattdessen „when using my_tool...“, weil die KI nicht erkennen kann, auf welches Tool sich „this“ bezieht.
execute-Funktion erklärt
Die execute-Funktion empfängt die folgenden Parameter:
| Parameter | Type | Beschreibung |
|---|---|---|
| toolCallId | string | Eindeutige ID des Tool-Aufrufs |
| params | Generisches T | Vom Schema validiertes Parameterobjekt |
| signal | AbortSignal | undefined | Abbruchsignal, ausgelöst, wenn der Benutzer Escape drückt |
| onUpdate | Funktion | Callback zum Senden von Fortschrittsaktualisierungen |
| ctx | ExtensionContext | Erweiterungskontext, der UI, Sitzung und weitere Funktionen bereitstellt |
Format des Rückgabewerts:
Beispiel
return {
// An das LLM gesendeter Inhalt (erforderlich)
content: [{ type: "text", text: Vorgang abgeschlossen }],
// Benutzerdefinierte Detaildaten, die zum Wiederaufbau des Zustands und zum Rendern verwendet werden (optional)
details: { result: "..." },
// Nutzungsstatistiken für verschachtelte LLM-Aufrufe (optional)
usage: nestedModelUsage,
// Beendigungsflag: wenn alle Tools im selben Batch terminate zurückgeben
// Überspringt nachfolgende LLM-Aufrufe (optional)
terminate: true,
};
Um die Tool-Ausführung als fehlgeschlagen zu markieren, verwendethrow new Error(), und versuche nicht, das Fehler-Flag im Rückgabewert zu setzen.
Nur durch das Auslösen einer Ausnahme kannst du isError auf true setzen und dem LLM mitteilen, dass ein Fehler aufgetreten ist.
StringEnum und Typsicherheit
Verwenden SieStringEnumanstelle von Type.Union/Type.Literal, um Enum-Parameter zu definieren:
Beispiel
import { StringEnum } from "@earendil-works/pi-ai";
// Korrekt: Google-API-kompatibel
parameters: Type.Object({
action: StringEnum(["list", "add", "done"] as const),
})
// Falsch: nicht Google-API-kompatibel
parameters: Type.Object({
action: Type.Union([
Type.Literal("list"),
Type.Literal("add"),
Type.Literal("done"),
]),
})
Sicherheits-Warteschlange für Dateiänderungen
Wenn Ihr Tool Dateien ändert, verwenden SiewithFileMutationQueue(), um an der Warteschlange für Dateiänderungen teilzunehmen:
Beispiel
import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";
// Der folgende Ausschnitt befindet sich in der execute-Funktion von registerTool
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
// Den Pfad zu einem absoluten Pfad auflösen
const absolutePath = resolve(ctx.cwd, params.path);
return withFileMutationQueue(absolutePath, async () => {
// Sicherstellen, dass das Verzeichnis existiert
await mkdir(dirname(absolutePath), { recursive: true });
// Den aktuellen Inhalt lesen
const current = await readFile(absolutePath, "utf8");
// Die Änderung anwenden
const next = current.replace(params.oldText, params.newText);
// In die Datei zurückschreiben
await writeFile(absolutePath, next, "utf8");
return {
content: [{ type: "text", text:`Aktualisiert ${params.path}` }],
details: {},
};
});
}
Die Warteschlange für Dateiänderungen stellt sicher, dass gleichzeitige Änderungen an derselben Datei einander nicht überschreiben — wenn das integrierte Bearbeitungswerkzeug und dein benutzerdefiniertes Werkzeug dieselbe Datei gleichzeitig ändern, werden sie in einer Warteschlange ausgeführt.
Kürzung der Ausgabe
Die Tool-Ausgabe muss gekürzt werden, um ein Auffüllen des LLM-Kontextfensters zu vermeiden. Die integrierten Grenzwerte sind 50KB (etwa 10,000 Tokens) und 2000 Zeilen:
Beispiel
import {
truncateHead,
formatSize,
DEFAULT_MAX_BYTES,
DEFAULT_MAX_LINES,
} from "@earendil-works/pi-coding-agent";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
// Der folgende Ausschnitt befindet sich in der execute-Funktion von registerTool
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
// Eine echte Datei lesen, um den zurückzugebenden Text zu erhalten
const output = await readFile(resolve(ctx.cwd, params.file), "utf8");
// Den Anfangsbereich behalten (geeignet für Dateilesevorgänge, Suchergebnisse)
const truncation = truncateHead(output, {
maxLines: DEFAULT_MAX_LINES,
maxBytes: DEFAULT_MAX_BYTES,
});
let result = truncation.content;
// Hänge eine Hinweiszeile an, wenn gekürzt wird, damit die KI weiß, dass der Inhalt unvollständig ist
if (truncation.truncated) {
result += `\n\n[Ausgabe gekürzt: ${truncation.outputLines}/`;
result += `${truncation.totalLines}Zeilen`;
result += `(${formatSize(truncation.outputBytes)}/`;
result += `${formatSize(truncation.totalBytes)})]`;
}
return {
content: [{ type: "text", text: result }],
};
}
Bei einer großen Protokolldatei, die die Grenzen überschreitet, enthält der vom Tool zurückgegebene Text am Ende einen Kürzungshinweis:
[2026-08-31 10:02:11] server started on port 3000 [2026-08-31 10:02:12] GET / 200 12ms [2026-08-31 10:02:12] GET /static/app.js 200 4ms ... [输出已截断:2000/8642 行(49.9KB/210.3KB)]
Die Kürzung ist nicht optional。
Übergroße Tool-Ausgabe kann Kontextüberlauf, Komprimierungsfehler und eine beeinträchtigte Modellleistung verursachen. Kürzen Sie Tool-Ausgaben immer.
Überschreiben integrierter Tools
Sie können integrierte Tools überschreiben, indem Sie Tools mit demselben Namen registrieren (read, bash, powershell, edit, write, grep, find, ls).
$ pi -e ./tool-override.ts
Unten wird registerTool verwendet, um das integrierte read-Tool zu überschreiben und für jede gelesene Datei einen Protokolleintrag hinzuzufügen:
Beispiel
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
export default function (pi: ExtensionAPI) {
// Überschreiben durch Verwendung desselben Namens wie beim integrierten Tool; hier fügen wir nur Protokollierung zu read hinzu
pi.registerTool({
name: "read",
label: "Datei lesen",
description: "Dateiinhalt lesen und Zugriff im Terminal protokollieren",
parameters: Type.Object({
path: Type.String({ description: "Der Pfad der zu lesenden Datei" }),
}),
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
const absolutePath = resolve(ctx.cwd, params.path);
const text = await readFile(absolutePath, "utf8");
// Zusätzliche Funktion: ein Zugriffsprotokoll aufzeichnen
console.log(`[read] ${params.path}(${text.length}Zeichen)`);
// Rückgabestruktur konsistent mit dem integrierten read halten
return {
content: [{ type: "text", text }],
};
},
});
}
Nach dem Laden dieser Erweiterung gibt die KI jedes Mal, wenn sie eine Datei liest, eine [read]-Protokollzeile im Terminal aus.
Beim Überschreiben werden Renderer (renderCall/renderResult) slotweise geerbt – wenn Sie renderCall weglassen, wird weiterhin der integrierte renderCall verwendet.
So können Sie integrierten Tools Protokollierung oder Berechtigungssteuerung hinzufügen, ohne die UI neu zu schreiben.
Aber für promptSnippet und promptGuidelines werden sienichtvon integrierten Tools geerbt; sie müssen explizit definiert werden.
Es gibt eine weitere, subtilere Einschränkung: Ihre Implementierung muss exakt der Ergebnisform des integrierten Tools entsprechen, einschließlich des Felds details.
Nehmen Sie read als Beispiel: Die Eingabeparameter müssen zwei optionale Parameter unterstützen, offset und limit, damit die KI beim seitenweisen Lesen großer Dateien den erwarteten Inhalt erhalten kann.
Die details im Rückgabewert müssen ebenfalls der Form ReadToolDetails des integrierten read entsprechen; andernfalls fehlen der UI-Darstellung Informationen und auch die Sitzungsstatusverfolgung wird beeinträchtigt.
Das obige Log-Erweiterungsbeispiel dient nur zur Veranschaulichung. Wenn Sie das integrierte read offiziell überschreiben, vervollständigen Sie bitte die Parameter und details gemäß der integrierten Implementierung.
Weitere Erweiterungen