Pi Coding Agent Einsteiger-Tutorial
Pi ist ein KI-Coding-Agent, der im Terminal läuft, ähnlich wie Tools wie Claude Code und OpenAI Codex CLI.
Pis offizielle Philosophie lautet:„Es gibt viele Agent-Harnesses, aber dieser hier ist dein“(Es gibt viele Agent-Tools, aber dieses hier ist deins).
Gib Pi einen Satz, und es kann Dateien lesen, Dateien schreiben und Befehle in deinem Projektverzeichnis ausführen, wobei es wiederholt das große Sprachmodell aufruft, bis die Aufgabe abgeschlossen ist.
Die Kernphilosophie ist ein minimaler Kernel plus extreme Erweiterbarkeit, sodass du das Tool so formen kannst, dass es zu dir passt, statt umgekehrt dich an das Tool anzupassen.
Pi Agent Komplett-Tutorial:https://www.example.com/pi-agent/pi-agent-tutorial.html

Was Pi enthält
Pi ist kein einzelnes Programm, sondern eine Toolchain aus vier npm-Paketen.
Normale Benutzer müssen nur das oberste Paket installieren@earendil-works/pi-coding-agent, und du erhältst einen sofort einsatzbereiten Kommandozeilen-Agent.
Für wen ist es gedacht
Pi eignet sich besonders für die folgenden Szenarien und Benutzer:
- Entwickler, die Terminal-Workflows bevorzugen und nicht ständig zwischen IDEs und der Kommandozeile hin- und herwechseln möchten
- Fortgeschrittene Benutzer, die ein tief anpassbares Tool möchten – sogar eines, das dem Agenten ermöglicht, sich selbst umzuschreiben
- Personen, die gleichzeitig eine Verbindung zu mehreren großen Sprachmodellen herstellen müssen (Anthropic, OpenAI, Google usw.)
- Entwickler, die Agent-Funktionen in ihre eigenen Programme einbetten möchten (über SDK- oder RPC-Modus)
Hinweis: Pi läuft standardmäßig mit deinen Benutzerberechtigungen und hat keine integrierte Sandbox. Bevor du es auf nicht vertrauenswürdigen Repositories einsetzt, lies bitte den Abschnitt „Sicherheitshinweise“ in diesem Artikel.
Kern-Designphilosophie: Grundbausteine, nicht Features
Wenn du Pis Designphilosophie verstehst, hilft dir das zu erkennen, warum viele Funktionen, die andere Agents haben, bewusst nicht „eingebaut“ werden.
Pi nennt dieses KonzeptGrundbausteine, nicht Features(Grundbausteine bereitstellen, keine Features).
Bewusst nicht integrierte Funktionen
Pi enthält die folgenden Funktionen nicht; stattdessen kannst du sie bei Bedarf über Erweiterungen oder externe Tools implementieren:
| Nicht enthaltene Funktionen | Pis Alternative |
|---|---|
| MCP-Protokollintegration | Schreibe das Tool als CLI mit einer README, oder installiere eine MCP-Erweiterung |
| Sub-Agents | Verwende tmux, um mehrere Sitzungen zu öffnen, oder schreibe deine eigene Erweiterung |
| Popup zur Berechtigungsbestätigung | Führe es in einem Container aus, oder schreibe deine eigene Erweiterung für den Bestätigungsablauf |
| Planmodus | Schreibe den Plan in eine Datei, oder schreibe eine Erweiterung |
| Integrierte Todos | Verwende eine TODO.md-Datei, oder installiere eine Erweiterung |
| Bash im Hintergrund | Verwende tmux für vollständige Beobachtbarkeit |
Warum das Ganze
Pi ist der Ansicht, dass diese Funktionen von Team zu Team stark variieren, und sie zwangsweise einzubauen würde das Tool aufblähen und es schwer machen, es an tatsächliche Arbeitsabläufe anzupassen.
Der Ansatz ist also: einen sauberen, minimalen Kern beibehalten und alle „Features“ in installierbare, schreibbare, teilbare Erweiterungen, Skills, Prompt-Vorlagen und Themes verwandeln.
Du kannst Pi sogar bitten, diese Funktionen für dich zu schreiben, und sobald sie geschrieben sind, verwende/reloadreload, und es funktioniert sofort.
Es lohnt sich, sich diesen Satz zu merken:Passe Pi an deine Arbeitsabläufe an, nicht umgekehrt(Lass Pi sich an deinen Workflow anpassen, nicht du an Pi).
Architektur und Kernpakete
Pi besteht aus vier klar geschichteten Paketen, wobei die oberen Schichten von den unteren abhängen.
Das, was du normalerweise verwendestpiDer Befehl ist nur der Einstiegspunkt, den das oberste Paket bereitstellt.
Vier Kernpakete
| Paket | Zweck | Wann Sie es separat verwenden würden |
|---|---|---|
@earendil-works/pi-coding-agent | Interaktive Coding-Agent-CLI, der Einstiegspunkt, den Benutzer direkt installieren und verwenden | In den meisten Fällen reicht dies aus |
@earendil-works/pi-agent-core | Agent-Runtime, zuständig für die Tool-Call-Schleife und die Zustandsverwaltung | Wenn Sie selbst einen Nicht-Coding-Agenten bauen möchten |
@earendil-works/pi-ai | Einheitliche Multi-Anbieter-LLM-API (OpenAI, Anthropic, Google usw.) | Wenn Sie nur eine einheitliche Schnittstelle zum Aufrufen mehrerer Modelle möchten |
@earendil-works/pi-tui | Terminal-UI-Bibliothek, die Diff-Rendering unterstützt | Wenn Sie Ihre eigene Terminal-Anwendung schreiben möchten |
Vier Betriebsmodi
Pi ist nicht auf den interaktiven Modus beschränkt; es bietet vier Modi für verschiedene Szenarien:
| Mode | Beschreibung | Typisches Szenario |
|---|---|---|
| Interaktiv | Vollständige Terminal-UI-Erfahrung | Tägliches Coding, dialogorientierte Entwicklung |
| Print / JSON | pi -p "提问"Einmalige Ausgabe;--mode jsonEreignisstrom ausgeben | Skript-Automatisierung, Pipeline-Verarbeitung |
| RPC | JSON-Protokollkommunikation über stdin/stdout | Integration von Nicht-Node-Programmen |
| SDK | Als Bibliothek in Ihre Anwendung einbetten | Agent-Fähigkeiten in Ihre eigenen Produkte integrieren |
Installation
Pi bietet mehrere Installationsmethoden für macOS, Linux und Windows.
Am häufigsten wird global über npm installiert, aber Sie können auch das offizielle Ein-Klick-Skript verwenden.
Methode 1: Ein-Klick-Skript (für Anfänger empfohlen)
macOS- und Linux-Benutzer verwenden curl:
curl -fsSL https://pi.dev/install.sh | sh
Windows-Benutzer verwenden PowerShell:
powershell -c "irm https://pi.dev/install.ps1 | iex"
Methode 2: Globale npm-Installation
Wenn Sie Node.js bereits installiert haben, installieren Sie es einfach global mit dem Paketmanager.
Beachten Sie den--ignore-scriptsParameter: Er überspringt die Lifecycle-Skripte der Abhängigkeitsinstallation. Pi benötigt diese Skripte für die normale Verwendung nicht, und das Hinzufügen ist sicherer.
# npm 安装 npm install -g --ignore-scripts @earendil-works/pi-coding-agent # pnpm 安装 pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent # bun 安装 bun add -g --ignore-scripts @earendil-works/pi-coding-agent
Installation überprüfen
Prüfen Sie nach der Installation die Versionsnummer, um die erfolgreiche Installation zu bestätigen:
pi --version
Zum Beispiel:
$ pi --version 0.80.6
Deinstallieren
Die Deinstallationsmethode hängt davon ab, wie Sie es ursprünglich installiert haben:
# curl 装的或 npm 装的 npm uninstall -g @earendil-works/pi-coding-agent # pnpm 装的 pnpm remove -g @earendil-works/pi-coding-agent # bun 装的 bun uninstall -g @earendil-works/pi-coding-agent
Hinweis: Das Deinstallieren von Pi löscht Ihre Konfiguration nicht. Einstellungen, Anmeldeinformationen, Sitzungsaufzeichnungen und installierte Pi-Pakete werden alle im
~/.pi/agent/Verzeichnis aufbewahrt und müssen manuell bereinigt werden.
Modellanbieter konfigurieren
Pi selbst enthält kein großes Sprachmodell; es erfordert, dass Sie Zugangsdaten für mindestens einen Modellanbieter bereitstellen.
Es gibt zwei Konfigurationsmethoden: Abo-Anmeldung oder API-Key.
Methode 1: Abo-Anmeldung (am einfachsten)
Wenn Sie bereits ein Claude Pro/Max-, ChatGPT Plus/Pro- oder GitHub Copilot-Abo haben, können Sie sich direkt anmelden und es weiterverwenden.
Führen Sie nach dem Start von Pi/loginaus und wählen Sie dann den Anbieter:
# 启动 pi pi # 在 pi 里执行登录命令 /login
Es gibt drei optionale Abo-Anbieter:
| Provider | Voraussetzung | Beschreibung |
|---|---|---|
| Claude Pro / Max | Anthropic-Abo | Die Nutzung durch Drittanbieter-Tools wird pro Token abgerechnet und zählt nicht gegen Ihr Abo-Kontingent |
| ChatGPT Plus / Pro(Codex) | OpenAI-Abo | Offiziell von OpenAI über Codex für OSS anerkannt |
| GitHub Copilot | Copilot-Abo | Wenn angezeigt wird, dass das Modell nicht unterstützt wird, müssen Sie zuerst das entsprechende Modell in VS Code aktivieren |
Nach der Anmeldung werden die Anmeldeinformationen gespeichert in~/.pi/agent/auth.json, und werden bei Ablauf automatisch erneuert. Zum Abmelden verwenden Sie/logout。
Methode 2: API-Key (am flexibelsten)
Die Übergabe des API-Key über Umgebungsvariablen ist der universellste Ansatz. Zum Beispiel mit dem Key von Anthropic:
# 设置环境变量后启动 export ANTHROPIC_API_KEY=sk-ant-... pi
Sie können auch in Pi ausführen/loginund wählen Sie einen Anbieter vom Typ API Key und speichern Sie den Key inauth.json。
Umgebungsvariablen für gängige Anbieter
Pi unterstützt mehr als 15 Anbieter; die gängigsten sind unten aufgeführt:
| Provider | Umgebungsvariable | Key-Name in auth.json |
|---|---|---|
| Anthropic | ANTHROPIC_API_KEY | anthropic |
| OpenAI | OPENAI_API_KEY | openai |
| Google Gemini | GEMINI_API_KEY | |
| DeepSeek | DEEPSEEK_API_KEY | deepseek |
| Groq | GROQ_API_KEY | groq |
| Mistral | MISTRAL_API_KEY | mistral |
| xAI | XAI_API_KEY | xai |
| OpenRouter | OPENROUTER_API_KEY | openrouter |
| Hugging Face | HF_TOKEN | huggingface |
Hinweis:
auth.jsonAnmeldeinformationen in ... haben Vorrang vor Umgebungsvariablen. Wenn beide konfiguriert sind, setzt sich erstereauth.jsondurch.
Struktur von auth.json
Wenn Sie Anmeldeinformationen manuell verwalten möchten, können Sie direkt bearbeiten~/.pi/agent/auth.json. Diese Datei erhält beim Erstellen die Berechtigungen 0600 (nur für den aktuellen Benutzer lesbar und schreibbar):
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." },
"openai": { "type": "api_key", "key": "sk-..." },
"google": { "type": "api_key", "key": "..." }
}
Das Feld Key unterstützt außerdem drei erweiterte Syntaxformen, um Werte bequem aus einem Passwortmanager oder Umgebungsvariablen abzurufen:
| Syntax | Bedeutung | Beispiel |
|---|---|---|
"!command" | Beginnt mit einem Ausrufezeichen, führt den Befehl aus und verwendet stdout als Key | "!op read 'op://vault/item/cred'" |
"$variable name" | Ruft den Wert einer Umgebungsvariable ab | "$MY_ANTHROPIC_KEY" |
| Einfaches Literal | Wird direkt als Key verwendet | "sk-ant-..." |
Cloud-Plattform-Anbieter
Wenn Sie cloudbasierte Modelldienste nutzen, unterstützt Pi auch Azure OpenAI, Amazon Bedrock, Google Vertex AI, Cloudflare usw.
Diese erfordern normalerweise zusätzliche Konfiguration für Endpunkt, Region oder Bereitstellungsnamen. Nehmen Sie Azure OpenAI als Beispiel:
# Azure OpenAI 所需的环境变量 export AZURE_OPENAI_API_KEY=... export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com # 可选:API 版本与部署名映射 export AZURE_OPENAI_API_VERSION=2024-02-01 export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4o=my-gpt4o
DeepSeek-Anbieter konfigurieren
Pi unterstützt benutzerdefinierte Anbieter über models.json. Der Pfad zur Konfigurationsdatei:
- Linux / macOS:~/.pi/agent/models.json
- Windows:%USERPROFILE%\.pi\agent\models.json
Rufen Sie zunächst einen API Key von der DeepSeek Open Platform ab:https://platform.deepseek.com/api_keys。
{
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com",
"api": "openai-completions",
"apiKey": "$DEEPSEEK_API_KEY",
"models": [
{
"id": "deepseek-v4-pro",
"name": "DeepSeek V4 Pro",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 1.74,
"output": 3.48,
"cacheRead": 0.145,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
},
{
"id": "deepseek-v4-flash",
"name": "DeepSeek V4 Flash",
"contextWindow": 1000000,
"maxTokens": 384000,
"input": ["text"],
"reasoning": true,
"cost": {
"input": 0.14,
"output": 0.28,
"cacheRead": 0.028,
"cacheWrite": 0
},
"compat": {
"requiresReasoningContentOnAssistantMessages": true,
"thinkingFormat": "deepseek",
"reasoningEffortMap": {
"minimal": "high",
"low": "high",
"medium": "high",
"high": "high",
"xhigh": "max"
}
}
}
]
}
}
}
Umgebungsvariablen festlegen:
Linux-/Mac-Benutzer:
export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Windows-Benutzer:
$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Wechseln Sie in das Projektverzeichnis und führen Sie den Befehl pi aus:
cd /path/to/my-project pi
Geben Sie/modelein, um den Modellumschalter zu öffnen, wählen Sie deepseek und dann DeepSeek-V4-Pro oder DeepSeek-V4-Flash.
Weitere Konfigurationsoptionen finden Sie unter:https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md。
Auflösungsreihenfolge der Anmeldeinformationen
Wenn Pi Anmeldeinformationen für einen Anbieter benötigt, sucht es in der folgenden Reihenfolge und verwendet die erste gefundene:
| Priorität | Source |
|---|---|
| 1 (höchste) | Befehlszeile--api-keyArgumente |
| 2 | auth.jsonEinträge in ... (API Key oder OAuth-Token) |
| 3 | Umgebungsvariable |
| 4 | models.jsonKey eines benutzerdefinierten Anbieters in ... |
Erster Start
Wechseln Sie nach dem Konfigurieren der Anmeldeinformationen in Ihr Projektverzeichnis und starten Sie direkt.piStarten.
# 进入项目目录 cd /path/to/project # 启动 pi pi
Geben Sie nach dem Start direkt einen Satz ein und drücken Sie die Eingabetaste, zum Beispiel: Bitten Sie es, dieses Repository zu analysieren:
Summarize this repository and tell me how to run its checks.
Pi liest automatisch Dateien, führt Befehle aus und gibt dann eine Zusammenfassung und Methoden zur Überprüfung.
Projekt-Vertrauensabfrage
Wenn im aktuellen Verzeichnis oder in einem übergeordneten Verzeichnis.piKonfiguration, Erweiterungen, Skills und andere projektspezifische Ressourcen vorhanden sind, fragt Pi Sie beim interaktiven Start zuerst, ob Sie diesem Projekt vertrauen.
Dies soll verhindern, dass ein Repository ohne Ihr Wissen stillschweigend seine Erweiterungen lädt oder Einstellungen ändert.
Hinweis: Die Vertrauensentscheidung wird gespeichert in
~/.pi/agent/trust.json. Nicht-interaktiver Modus (-p、--mode json) wird nicht angezeigt und verwendet standardmäßig dendefaultProjectTrusthandle.
Wie der Agent funktioniert
Jedes Mal, wenn du eine Nachricht sendest, startet Pi eine Agent-Schleife. Diese Schleife zu verstehen bedeutet zu verstehen, wie Pi funktioniert.
Der Kern ist die Turn-Schleife in der Mitte: Das Modell kann in jedem Turn Tools aufrufen, Pi führt die Tools aus und packt die Ergebnisse zurück in den Kontext, dann lässt es das Modell fortfahren, bis das Modell keine Tools mehr aufruft und eine abschließende Antwort gibt.
Vier integrierte Tools
Standardmäßig gibt Pi dem Modell nur vier Tools, die die Kernfähigkeiten Lesen, Schreiben und Ausführen beim Programmieren abdecken.
| Tool | Zweck | Standardmäßig aktiviert |
|---|---|---|
read | Dateiinhalt lesen | Ja |
write | Dateien erstellen oder überschreiben | Ja |
edit | Teilweise Patch-Änderungen an Dateien anwenden | Ja |
bash | Shell-Befehle ausführen | Ja |
grep | Dateiinhalt durchsuchen | Nein (muss über Tool-Optionen aktiviert werden) |
find | Dateien nach Kriterien finden | Nein (muss über Tool-Optionen aktiviert werden) |
ls | Verzeichnisinhalt auflisten | Nein (muss über Tool-Optionen aktiviert werden) |
Verfügbare Tools steuern
Du kannst über Kommandozeilenargumente genau steuern, welche Tools das Modell verwenden darf.
Das ist nützlich, wenn du die Fähigkeiten des Agenten einschränken musst, zum Beispiel damit er nur Code überprüft, ohne Änderungen vorzunehmen:
# 只读模式:只允许读取和搜索类工具 pi --tools read,grep,find,ls -p "审查这段代码" # 禁用某个工具,其余保留 pi --exclude-tools ask_question # 关闭所有内置工具,只保留扩展提供的工具 pi --no-builtin-tools -e ./my-extension.ts # 完全禁用工具,纯对话 pi --no-tools -p "解释一下这个概念"
Erinnerung: Pi läuft in deinem aktuellen Arbeitsverzeichnis und kann deine Dateien ändern. Es wird empfohlen, es mit Versionskontrolle wie git zu verwenden, um jederzeit einfach zurückzusetzen.
Dem Projekt mit AGENTS.md Anweisungen geben
AGENTS.md ist Pis Projektanweisungsdatei; sie teilt dem Modell mit, welche Regeln das Projekt hat, wie man es ausführt und worauf man achten muss.
Es funktioniert ähnlich wie Claude Codes CLAUDE.md – und Pi unterstützt beide Dateinamen.
Eine AGENTS.md schreiben
Erstelle sie im ProjektstammverzeichnisAGENTS.md, schreibe die Regeln, denen das Modell folgen soll:
# 项目指令 - 改完代码后运行 `npm run check`。 - 不要在本地跑生产环境的数据库迁移。 - 回答尽量简洁。
Woher lädt Pi Anweisungen
Pi lädt Anweisungsdateien beim Start von mehreren Orten, in absteigender Reihenfolge ihres Geltungsbereichs:
| Ort | Geltungsbereich | Beschreibung |
|---|---|---|
~/.pi/agent/AGENTS.md | Global | Allgemeine Anweisungen, die für alle deine Projekte gelten |
Des übergeordneten VerzeichnissesAGENTS.md | Projektebene | Sucht vom aktuellen Verzeichnis aus Ebene für Ebene nach oben |
Des aktuellen VerzeichnissesAGENTS.md | Projektebene | Die spezifischsten Anweisungen mit der höchsten Priorität |
Für Dateinamen,AGENTS.mdoderCLAUDE.mdfunktioniert jeder davon; Pi erkennt alle.
System-Prompt ändern
AGENTS.md sind zusätzliche Anweisungen, die über den Standard-System-Prompt hinaus angehängt werden. Wenn du eine gründlichere Kontrolle möchtest, kannst du den gesamten System-Prompt ersetzen.
Wenn du sie im Projekt.pi/SYSTEM.mdablegst, ersetzt sie den Standard-System-Prompt; wenn du sie in.pi/APPEND_SYSTEM.mdablegst, bedeutet das Anhängen (global entspricht~/.pi/agent/die gleichnamige Datei unter).
Hinweis: Nach dem Ändern von Anweisungsdateien denke daran, in Pi
/reloadreload, oder starte Pi neu, damit die neuen Anweisungen wirksam werden.
Häufige Operationen im interaktiven Modus
Der interaktive Modus ist die am häufigsten verwendete Form von Pi; wenn du ein paar wichtige Operationen beherrschst, kannst du ihn effizient nutzen.
Datei referenzieren: @
Im Editor eingeben@Eine Fuzzy-Suche nach Projektdateien wird angezeigt; nach der Auswahl wird der Dateiinhalt als Kontext an das Modell gesendet.
Du kannst Dateien auch direkt beim Start von der Kommandozeile mitgeben:
# 启动时带上一个文件 pi @README.md "总结一下这个文件" # 带上多个文件一起审查 pi @src/app.ts @src/app.test.ts "一起审查这两个文件"
Shell-Befehl ausführen: !
Im Editor, beginnend mit!wird ein eingegebener Befehl direkt ausgeführt und die Ausgabe an das Modell gesendet:
# 运行命令,输出会进入模型上下文 !npm run lint # 两个感叹号:运行但不把输出加进模型上下文 !!npm run build
Modell und Denkaufwand umschalten
Pi unterstützt das Umschalten von Modellen und Denkaufwand mitten in der Sitzung, um sich an die Komplexität unterschiedlicher Aufgaben anzupassen.
| Aktion | Tastenkürzel / Befehl | Beschreibung |
|---|---|---|
| Modellauswahl öffnen | /modeloder Ctrl+L | Eines aus allen verfügbaren Modellen auswählen |
| Denkaufwand umschalten | Shift+Tab | Zwischen off / minimal / low / medium / high / xhigh / max wechseln |
| Favoritenmodelle durchschalten | Ctrl+P / Shift+Ctrl+P | Schnell zwischen den wenigen von dir vorausgewählten Modellen wechseln |
Du kannst das Modell und den Denkaufwand auch direkt beim Start angeben:
# 指定厂商和模型 pi --provider openai --model gpt-4o "帮我重构" # 用 厂商/模型 的写法 pi --model openai/gpt-4o "帮我重构" # 用 名称:思考强度 的简写 pi --model sonnet:high "解决这个复杂问题" # 限定可在 Ctrl+P 里循环的模型 pi --models "claude-*,gpt-4o"
Tipps für Eingabe und Bearbeitung
| Aktion | Methode | Beschreibung |
|---|---|---|
| Mehrzeilige Eingabe | Shift+Enter (Ctrl+Enter im Windows Terminal) | Einen Zeilenumbruch innerhalb einer Nachricht einfügen |
| Pfadvervollständigung | Tab | Dateipfade vervollständigen |
| Bild einfügen | Ctrl+V (unter Windows Alt+V verwenden) | Du kannst Bilder auch in das Terminal ziehen. |
| Antwort kopieren | Ctrl+X | Letzte Assistentennachricht kopieren |
| Externer Editor | Ctrl+G | $VISUAL / $EDITOR öffnen, um langen Text zu bearbeiten |
Während der Ausführung unterbrechen
Während der Agent arbeitet, musst du nicht warten; du kannst jederzeit eine Nachricht einfügen.
| Taste | Verhalten | Anwendungsfall |
|---|---|---|
| Enter | Steuerungsnachricht: wird sofort nach Beendigung des aktuellen Tools übermittelt und unterbricht die verbleibenden Tools. | Wenn du bemerkst, dass es vom Kurs abkommt, korrigiere es umgehend. |
| Alt+Enter | Folgenachricht: wird übermittelt, nachdem der Agent vollständig fertig ist. | Wenn du eine neue Anforderung hinzufügen möchtest. |
| Escape | Brich die aktuelle Arbeit ab und stelle in der Warteschlange befindliche Nachrichten wieder im Editor her. | Wenn du anhalten und neu organisieren möchtest. |
Tipp: In Windows Terminal ist Alt+Enter standardmäßig der Vollbild-Umschalter; die Tastenbelegungen für Steuerungs- und Folgenachrichten können in den Einstellungen geändert werden, indem du sie
steeringModeundfollowUpModeänderst.
Kurzübersicht für gängige Slash-Befehle
Im Editor eingeben/Die Befehlskomplettierung wird eingeblendet. Unten findest du die gängigsten Slash-Befehle.
| Befehl | Funktion |
|---|---|
/login / /logout | OAuth- oder API-Key-Zugangsdaten verwalten |
/model | Modell wechseln |
/scoped-models | Festlegen, welche Modelle an der Ctrl+P-Schleife teilnehmen |
/settings | Denkaufwand, Theme, Nachrichtenzustellung usw. anpassen |
/resume | Eine Sitzung aus dem Verlauf zum Fortsetzen auswählen |
/new | Eine neue Sitzung starten |
/name <名称> | Der aktuellen Sitzung einen Anzeigenamen geben |
/session | Sitzungsdatei, ID, Nachrichtenanzahl, Token-Nutzung und Kosten anzeigen |
/tree | Zu einem beliebigen Knoten im Sitzungsbaum springen und von dort fortfahren |
/fork | Eine neue Sitzung aus einer historischen Nachricht abzweigen |
/clone | Den aktuellen Branch als neue Sitzung kopieren |
/compact [提示] | Den Kontext manuell komprimieren, optional mit benutzerdefinierten Anweisungen |
/copy | Die letzte Assistentennachricht in die Zwischenablage kopieren |
/export [文件] | Die Sitzung als HTML oder JSONL exportieren |
/import <文件> | Eine Sitzung aus einer JSONL-Datei importieren und wiederherstellen |
/share | Als privaten GitHub Gist hochladen, um einen teilbaren HTML-Link zu erzeugen |
/reload | Tastenbelegungen, Erweiterungen, Skills, Prompts, Themes und Kontextdateien neu laden |
/trust | Vertrauensentscheidung für das aktuelle Projekt speichern |
/hotkeys | Alle Tastenbelegungen anzeigen |
/changelog | Verlauf der Versionsupdates anzeigen |
/quit | Pi beenden |
Sitzungsverwaltung: Baumverlauf
Pi-Sitzungen sind keine gerade Linie; sie sind ein Baum.
Das bedeutet, dass der ursprüngliche Zweig nicht verloren geht, wenn Sie an einem beliebigen historischen Knoten forken; alle Zweige existieren in derselben Sitzungsdatei.
Wo werden Sitzungen gespeichert
Sitzungen werden automatisch gespeichert in~/.pi/agent/sessions/, gruppiert nach Arbeitsverzeichnis.
Historische Sitzungen über die Kommandozeile wiederherstellen oder durchsuchen:
# 继续最近一次会话 pi -c # 浏览并选择一个历史会话 pi -r # 给会话起个名字,方便日后查找 pi --name "my task" # 打开指定的会话文件或 ID pi --session <path|id> # 临时会话,不保存 pi --no-session
Im Sitzungsbaum navigieren
Verwenden Sie/treeSie können die Sitzungsbaumansicht öffnen und zu einem beliebigen historischen Knoten springen, um fortzufahren.
Wenn Sie von dort aus fortfahren, wird ein neuer Zweig erstellt, während der ursprüngliche Zweig unverändert bleibt.
Forken und Klonen
| Befehl | Verhalten | Unterschied |
|---|---|---|
/fork | Eine neue Sitzung aus einer früheren Benutzernachricht forken | Von einem bestimmten Punkt in der Historie neu starten |
/clone | Den aktuell aktiven Zweig in eine neue Sitzung klonen | Eine Kopie basierend auf dem neuesten Zustand erstellen |
Kontext komprimieren
Wenn das Gespräch lang wird und sich dem Kontextlimit des Modells nähert, komprimiert Pi frühere Nachrichten automatisch zu einer Zusammenfassung.
Sie können es auch manuell auslösen mit/compact, und Sie können eine benutzerdefinierte Anweisung hinzufügen, die angibt, was bei der Komprimierung beibehalten werden soll:
# 在 pi 里手动压缩,并要求保留最近改动 /compact 重点保留最近的改动和错误处理
Exportieren und Teilen
Die Sitzung als HTML für die Archivierung oder Präsentation exportieren:
# 导出为 HTML 文件 /export my-session.html # 上传为私有 GitHub Gist,得到分享链接 /share
Nicht-interaktiver Modus und Integration
Pi ist nicht nur für interaktive Gespräche gedacht; es kann auch als Kommandozeilen-Tool, Ereignisstrom, RPC-Dienst und SDK-Bibliothek verwendet werden.
Einmalige Frage: print-Modus
Verwenden Sie-pPi antworten lassen und dann beenden, geeignet für den Aufruf in Skripten:
# 直接提问 pi -p "总结一下这个代码库" # 配合管道,把内容喂给 Pi cat README.md | pi -p "总结这段文字" # 带图片提问 pi -p @screenshot.png "这张图里是什么?"
Ereignisstrom: JSON-Modus
--mode jsonGibt alle Ereignisse als JSON-Zeilen aus, um sie einfach programmatisch zu parsen:
# 输出 JSON 事件流 pi --mode json -p "列出 src 下所有 .ts 文件"
Prozessintegration: RPC-Modus
--mode rpcVerwendet das JSON-Protokoll über stdin/stdout, geeignet für Nicht-Node-Programme (z. B. Python, Go), um Pi zu steuern.
Bestehende Sitzung exportieren
Ohne eine neue Sitzung zu starten, eine bestehende Sitzungsdatei direkt nach HTML exportieren:
# 把会话文件导出为 HTML pi --export session.jsonl output.html
SDK-Modus
Wenn Sie die Funktionen von Pi in Ihre eigene Node-Anwendung einbetten möchten, können Sie den SDK-Modus verwenden, um es als Bibliothek einzubinden.
Dies ist eine engere Integration als RPC; siehe den SDK-Abschnitt in der offiziellen Dokumentation:https://pi.dev/docs/latest/sdk。
Erweiterungen
Erweiterungen sind der Kern der Erweiterbarkeit von Pi. Sie sind TypeScript-Module, die Lebenszyklus-Ereignisse abonnieren, benutzerdefinierte Tools registrieren und Befehle sowie Tastenkürzel hinzufügen können.
Erweiterungen werden über jiti geladen, sodass Sie TypeScript direkt ohne Kompilierung schreiben können.
Wo Erweiterungen abgelegt werden
| Ort | Geltungsbereich |
|---|---|
~/.pi/agent/extensions/*.ts | Global, gilt für alle Projekte |
.pi/extensions/*.ts | Auf Projektebene, nur für das aktuelle Projekt wirksam |
Es kann auch in Form eines Unterverzeichnisses vorliegen (扩展名/index.ts), oder mitpackage.jsoneinem vollständigen Paket.
Ein minimales Beispiel für eine Erweiterung
Die folgende Erweiterung demonstriert drei Dinge: eine Benachrichtigung beim Start, das Abfangen gefährlicher Befehle und das Registrieren eines benutzerdefinierten Tools und eines Befehls.
// 文件路径:~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
// 扩展导出一个默认工厂函数,接收 ExtensionAPI
export default function (pi: ExtensionAPI) {
// 1. 监听 session_start 事件:会话启动时弹个通知
pi.on("session_start", async (_event, ctx) => {
ctx.ui.notify("扩展已加载!", "info");
});
// 2. 监听 tool_call 事件:拦截危险的 bash 命令
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
// 弹确认框,用户拒绝就阻止执行
const ok = await ctx.ui.confirm("危险操作!", "允许执行 rm -rf 吗?");
if (!ok) return { block: true, reason: "被用户阻止" };
}
});
// 3. 注册一个自定义工具,模型可以调用它
pi.registerTool({
name: "greet",
label: "打招呼",
description: "按名字向某人打招呼",
parameters: Type.Object({
name: Type.String({ description: "要打招呼的名字" }),
}),
async execute(toolCallId, params, signal, onUpdate, ctx) {
return {
content: [{ type: "text", text: `你好,${params.name}!` }],
details: {},
};
},
});
// 4. 注册一个斜杠命令 /hello
pi.registerCommand("hello", {
description: "打个招呼",
handler: async (args, ctx) => {
ctx.ui.notify(`你好 ${args || "world"}!`, "info");
},
});
}
Nach dem Schreiben verwenden Sie-eParameter, um sie zum Testen vorübergehend zu laden:
# 临时加载一个扩展来测试 pi -e ./my-extension.ts
Was können Erweiterungen tun
Die Möglichkeiten von Erweiterungen gehen weit über das oben Genannte hinaus; sie können in fast jeden Teil des Pi-Workflows eingreifen:
| Fähigkeit | Entsprechende Methode | Typische Verwendung |
|---|---|---|
| Benutzerdefinierte Tools registrieren | pi.registerTool() | Das Modell Ihre Geschäftsschnittstelle aufrufen lassen |
| Befehle registrieren | pi.registerCommand() | Eigene Slash-Befehle hinzufügen |
| Tastenkürzel registrieren | pi.registerShortcut() | Benutzerdefinierte Tastenkürzel binden |
| Tool-Aufrufe abfangen | tool_callEreignis | Berechtigungsbestätigung, Umschreiben von Befehlen |
| Kontext ändern | contextEreignis | Verlauf filtern, RAG-Inhalte injizieren |
| Nachrichten injizieren | pi.sendMessage() | Kontext dynamisch ergänzen |
| Provider registrieren | pi.registerProvider() | Auf private Modell-Gateways zugreifen |
| Benutzerdefinierte UI | ctx.uiSerie | Dialoge, Statusleiste, Komponenten |
Tipp: Im Pi-Repository gibt es mehr als 50 Beispielerweiterungen, die Sub-Agents, Planungsmodus, Berechtigungs-Gates, SSH-Ausführung, Sandbox usw. abdecken. Es ist die beste Referenz zum Erlernen der Erweiterungsentwicklung.
Skills
Skills sind eine weitere Art wiederverwendbarer Fähigkeitspakete. Der Unterschied zu Erweiterungen besteht darin, dass Skills hauptsächlich Anweisungen und Skripte für das Modell sind, die bei Bedarf geladen werden.
Pi implementiert den Agent Skills-Standard und kann daher direkt Skills aus Tools wie Claude Code und OpenAI Codex verwenden.
So funktionieren Skills
Skills nutzen das Prinzip der progressiven Offenlegung.
Beim Start fügt Pi nur den Namen und die Beschreibung jedes Skills in den System-Prompt ein; wenn eine Aufgabe passt, verwendet das ModellreadTool, um die vollständige Skill-Beschreibung zu laden.
Auf diese Weise kannst du viele Skills installieren, ohne den Kontext von Anfang an zu füllen.
Wo Skills abgelegt werden
| Ort | Geltungsbereich |
|---|---|
~/.pi/agent/skills/ | Global |
~/.agents/skills/ | Global (toolübergreifend geteilt) |
.pi/skills/ | Projektebene (erfordert, dass dem Projekt vertraut wird) |
.agents/skills/ | Projektebene (toolübergreifend geteilt) |
Struktur eines Skills
Ein Skill ist ein Verzeichnis, das Folgendes enthältSKILL.mdVerzeichnis, und der Rest der Dateien kann frei organisiert werden.
my-skill/
├── SKILL.md # 必需:前置信息 + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 按需加载的详细文档
│ └── api-reference.md
└── assets/
└── template.json
Wie man SKILL.md schreibt
Der obere Teil von SKILL.md ist Frontmatter, und darunter befindet sich der Anweisungstext für das Modell:
--- name: my-skill description: 这个技能做什么、什么时候用。要写具体。 --- # My Skill ## Setup 首次使用前运行一次: ```bash cd /path/to/skill && npm install ``` ## Usage ```bash ./scripts/process.sh <input> ```
Die zwei wichtigsten Felder im Frontmatter:
| Feld | Erforderlich? | Beschreibung |
|---|---|---|
name | Erforderlich | Bis zu 64 Zeichen, nur Kleinbuchstaben, Zahlen und Bindestriche |
description | Erforderlich | Bis zu 1024 Zeichen, bestimmt, wann das Modell diesen Skill lädt. Sei präzise. |
Hinweis:
descriptionWie gut er geschrieben ist, bestimmt direkt, ob das Modell diesen Skill zum richtigen Zeitpunkt verwendet. "PDF-Dateien verarbeiten, Text und Tabellen extrahieren, Formulare ausfüllen, mehrere PDFs zusammenführen" zu schreiben, ist weit besser als "Beim Verarbeiten von PDFs helfen."
Skills manuell aufrufen
Das Modell lädt einen Skill möglicherweise nicht immer von selbst. Du kannst/skill:名称Erzwungen laden und ausführen:
# 加载并执行技能 /skill:brave-search # 带参数加载技能 /skill:pdf-tools extract
Pi-Paketverwaltung
Erweiterungen, Skills, Prompt-Vorlagen und Themes können alle als Pi-Pakete verpackt und über npm oder git geteilt/installiert werden.
Pi verfügt über eine integrierte Reihe von Paketverwaltungsbefehlen, mit denen du Fähigkeiten erweitern kannst, genau wie beim Installieren von Plugins.
Installation und Deinstallation
# 从 npm 安装一个包 pi install npm:@foo/pi-tools # 从 git 仓库安装 pi install git:github.com/badlogic/pi-doom # 项目本地安装(加 -l) pi install npm:@foo/pi-tools -l # 卸载 pi remove npm:@foo/pi-tools
Aktualisierungen und Anzeigen
| Befehl | Funktion |
|---|---|
pi list | Installierte Pakete auflisten |
pi update | Nur Pi selbst aktualisieren |
pi update --all | Pi und alle Pakete aktualisieren |
pi update --extensions | Nur Pakete aktualisieren, Pi selbst unverändert lassen |
pi update --extension <源> | Ein bestimmtes Paket aktualisieren |
pi config | Ressourcen im Paket aktivieren oder deaktivieren |
Sicherheitshinweise
Sicherheit ist ein wesentlicher Teil, den man verstehen muss, bevor man Pi verwendet. Pis Sicherheitsmodell unterscheidet sich von vielen Agent-Tools und erfordert deine aktive Mitarbeit.
Keine integrierte Sandbox
Pi enthält keine integrierte Sandbox, es läuft als der Benutzer, der es gestartet hat, und besitzt alle Berechtigungen dieses Benutzers.
Integrierte Tools können Dateien lesen und schreiben und Shell-Befehle ausführen; Erweiterungen sind TypeScript-Module mit denselben Berechtigungen wie der Pi-Prozess.
Das ist beabsichtigt: Pi muss mit lokalem Quellcode arbeiten, Projekt-Toolchains aufrufen und sich in die Entwicklungsumgebung integrieren. Eine unvollständige In-Process-Sandbox würde die Leute zu der Annahme verleiten, sie sei eine Sicherheitsgrenze, während sie in Wirklichkeit weiterhin auf die Shell, das Dateisystem und die Anmeldeinformationen des Hosts angewiesen ist.
Wichtig: Echte Isolation muss vom Betriebssystem oder von Container-/Virtualisierungsgrenzen kommen, nicht aus dem Inneren von Pi.
Projektvertrauen
Projektvertrauen bestimmt, ob Pi projektbezogene Einstellungen, Ressourcen, Erweiterungen und Pakete lädt.
Wenn ein Verzeichnis.pi/settings.json、.pi/extensions、.pi/skills、.pi/SYSTEM.mdund ähnliche Inhalte enthält, verlangt Pi vor dem Laden Vertrauen.
| Vertrauensstufe | Verhalten | Einstellungsmethode |
|---|---|---|
ask(Standard) | Interaktive Abfrage; Projektressourcen im nicht-interaktiven Modus ignorieren | von settings.jsondefaultProjectTrust |
always | Projektressourcen immer vertrauen | Wie oben, oder verwenden Sie-a / --approve |
never | Niemals vertrauen, Projektressourcen ignorieren | Wie oben, oder verwenden Sie-na / --no-approve |
Vertrauensentscheidungen werden gespeichert in~/.pi/agent/trust.json, aufgezeichnet nach Verzeichnispfad, wobei die Entscheidung des nächstgelegenen übergeordneten Verzeichnisses Vorrang hat.
Hinweis: Projektvertrauen ist nur eine „Eingabe-Ladeschutzmaßnahme“, die verhindert, dass Repositories stillschweigend Ihre Einstellungen oder Erweiterungen ändern, aberkann nicht dafür sorgen, dass nicht vertrauenswürdiger Code, Prompts oder Modellausgaben sicher sind. Prompt-Injection in Repository-Dateien, Kommentaren und Dokumentation ist ein inhärentes Risiko lokaler Agenten, und Pi kann es nicht zuverlässig verhindern.
Umgang mit nicht vertrauenswürdigen oder unbeaufsichtigten Aufgaben
Für nicht vertrauenswürdige Repositories, generierten Code, der eine genaue Überwachung erfordert, oder unbeaufsichtigte Automatisierung ist die offizielle Empfehlung, Pi in einer isolierten Umgebung auszuführen.
Empfohlene Vorgehensweisen:
- Setzen Sie den gesamten
piProzess in einen Container, eine virtuelle Maschine oder eine Remote-Sandbox - Nur Workspace-Pfade einbinden, auf die der Agent zugreifen soll
- Sofern nicht erforderlich, mounten Sie nicht das Verzeichnis des Hosts
~/.pi/agent(das Ihre Anmeldeinformationen und Sitzungen enthält) - Nur die minimal erforderlichen API-Schlüssel übergeben oder kurzlebige Anmeldeinformationen verwenden
- Netzwerkzugriff einschränken, wenn die Aufgabe kein Internet erfordert
- Diffs und Ausgaben überprüfen, bevor Ergebnisse zurück auf ein vertrauenswürdiges System kopiert werden
Erinnerung: Wenn Sie den Host-Workspace im Lese-/Schreibmodus in den Container mounten, ändern Schreibvorgänge im Container weiterhin Host-Dateien. Für stärkeren Schutz vor versehentlichen Schreibvorgängen verwenden Sie schreibgeschützte Mounts oder kopieren Dateien in die Sandbox hinein und wieder heraus.
Ressourcen und Community
Offizielle Ressourcen
- GitHub-Repository:github.com/earendil-works/pi
- Offizielle Website:pi.dev
- Offizielle Dokumentation:pi.dev/docs/latest
- npm-Paket:@earendil-works/pi-coding-agent