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 FunktionenPis Alternative
MCP-ProtokollintegrationSchreibe das Tool als CLI mit einer README, oder installiere eine MCP-Erweiterung
Sub-AgentsVerwende tmux, um mehrere Sitzungen zu öffnen, oder schreibe deine eigene Erweiterung
Popup zur BerechtigungsbestätigungFühre es in einem Container aus, oder schreibe deine eigene Erweiterung für den Bestätigungsablauf
PlanmodusSchreibe den Plan in eine Datei, oder schreibe eine Erweiterung
Integrierte TodosVerwende eine TODO.md-Datei, oder installiere eine Erweiterung
Bash im HintergrundVerwende 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.

Pi 四层包架构图

Vier Kernpakete

PaketZweckWann Sie es separat verwenden würden
@earendil-works/pi-coding-agentInteraktive Coding-Agent-CLI, der Einstiegspunkt, den Benutzer direkt installieren und verwendenIn den meisten Fällen reicht dies aus
@earendil-works/pi-agent-coreAgent-Runtime, zuständig für die Tool-Call-Schleife und die ZustandsverwaltungWenn Sie selbst einen Nicht-Coding-Agenten bauen möchten
@earendil-works/pi-aiEinheitliche Multi-Anbieter-LLM-API (OpenAI, Anthropic, Google usw.)Wenn Sie nur eine einheitliche Schnittstelle zum Aufrufen mehrerer Modelle möchten
@earendil-works/pi-tuiTerminal-UI-Bibliothek, die Diff-Rendering unterstütztWenn 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:

ModeBeschreibungTypisches Szenario
InteraktivVollständige Terminal-UI-ErfahrungTägliches Coding, dialogorientierte Entwicklung
Print / JSONpi -p "提问"Einmalige Ausgabe;--mode jsonEreignisstrom ausgebenSkript-Automatisierung, Pipeline-Verarbeitung
RPCJSON-Protokollkommunikation über stdin/stdoutIntegration von Nicht-Node-Programmen
SDKAls Bibliothek in Ihre Anwendung einbettenAgent-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:

ProviderVoraussetzungBeschreibung
Claude Pro / MaxAnthropic-AboDie Nutzung durch Drittanbieter-Tools wird pro Token abgerechnet und zählt nicht gegen Ihr Abo-Kontingent
ChatGPT Plus / Pro(Codex)OpenAI-AboOffiziell von OpenAI über Codex für OSS anerkannt
GitHub CopilotCopilot-AboWenn 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:

ProviderUmgebungsvariableKey-Name in auth.json
AnthropicANTHROPIC_API_KEYanthropic
OpenAIOPENAI_API_KEYopenai
Google GeminiGEMINI_API_KEYgoogle
DeepSeekDEEPSEEK_API_KEYdeepseek
GroqGROQ_API_KEYgroq
MistralMISTRAL_API_KEYmistral
xAIXAI_API_KEYxai
OpenRouterOPENROUTER_API_KEYopenrouter
Hugging FaceHF_TOKENhuggingface

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:

SyntaxBedeutungBeispiel
"!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 LiteralWird 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ätSource
1 (höchste)Befehlszeile--api-keyArgumente
2auth.jsonEinträge in ... (API Key oder OAuth-Token)
3Umgebungsvariable
4models.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.

Pi Agent 循环流程图

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.

ToolZweckStandardmäßig aktiviert
readDateiinhalt lesenJa
writeDateien erstellen oder überschreibenJa
editTeilweise Patch-Änderungen an Dateien anwendenJa
bashShell-Befehle ausführenJa
grepDateiinhalt durchsuchenNein (muss über Tool-Optionen aktiviert werden)
findDateien nach Kriterien findenNein (muss über Tool-Optionen aktiviert werden)
lsVerzeichnisinhalt auflistenNein (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:

OrtGeltungsbereichBeschreibung
~/.pi/agent/AGENTS.mdGlobalAllgemeine Anweisungen, die für alle deine Projekte gelten
Des übergeordneten VerzeichnissesAGENTS.mdProjektebeneSucht vom aktuellen Verzeichnis aus Ebene für Ebene nach oben
Des aktuellen VerzeichnissesAGENTS.mdProjektebeneDie 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.

AktionTastenkürzel / BefehlBeschreibung
Modellauswahl öffnen/modeloder Ctrl+LEines aus allen verfügbaren Modellen auswählen
Denkaufwand umschaltenShift+TabZwischen off / minimal / low / medium / high / xhigh / max wechseln
Favoritenmodelle durchschaltenCtrl+P / Shift+Ctrl+PSchnell 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

AktionMethodeBeschreibung
Mehrzeilige EingabeShift+Enter (Ctrl+Enter im Windows Terminal)Einen Zeilenumbruch innerhalb einer Nachricht einfügen
PfadvervollständigungTabDateipfade vervollständigen
Bild einfügenCtrl+V (unter Windows Alt+V verwenden)Du kannst Bilder auch in das Terminal ziehen.
Antwort kopierenCtrl+XLetzte Assistentennachricht kopieren
Externer EditorCtrl+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.

TasteVerhaltenAnwendungsfall
EnterSteuerungsnachricht: 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+EnterFolgenachricht: wird übermittelt, nachdem der Agent vollständig fertig ist.Wenn du eine neue Anforderung hinzufügen möchtest.
EscapeBrich 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 siesteeringModeundfollowUpModeänderst.


Kurzübersicht für gängige Slash-Befehle

Im Editor eingeben/Die Befehlskomplettierung wird eingeblendet. Unten findest du die gängigsten Slash-Befehle.

BefehlFunktion
/login / /logoutOAuth- oder API-Key-Zugangsdaten verwalten
/modelModell wechseln
/scoped-modelsFestlegen, welche Modelle an der Ctrl+P-Schleife teilnehmen
/settingsDenkaufwand, Theme, Nachrichtenzustellung usw. anpassen
/resumeEine Sitzung aus dem Verlauf zum Fortsetzen auswählen
/newEine neue Sitzung starten
/name <名称>Der aktuellen Sitzung einen Anzeigenamen geben
/sessionSitzungsdatei, ID, Nachrichtenanzahl, Token-Nutzung und Kosten anzeigen
/treeZu einem beliebigen Knoten im Sitzungsbaum springen und von dort fortfahren
/forkEine neue Sitzung aus einer historischen Nachricht abzweigen
/cloneDen aktuellen Branch als neue Sitzung kopieren
/compact [提示]Den Kontext manuell komprimieren, optional mit benutzerdefinierten Anweisungen
/copyDie letzte Assistentennachricht in die Zwischenablage kopieren
/export [文件]Die Sitzung als HTML oder JSONL exportieren
/import <文件>Eine Sitzung aus einer JSONL-Datei importieren und wiederherstellen
/shareAls privaten GitHub Gist hochladen, um einen teilbaren HTML-Link zu erzeugen
/reloadTastenbelegungen, Erweiterungen, Skills, Prompts, Themes und Kontextdateien neu laden
/trustVertrauensentscheidung für das aktuelle Projekt speichern
/hotkeysAlle Tastenbelegungen anzeigen
/changelogVerlauf der Versionsupdates anzeigen
/quitPi 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

BefehlVerhaltenUnterschied
/forkEine neue Sitzung aus einer früheren Benutzernachricht forkenVon einem bestimmten Punkt in der Historie neu starten
/cloneDen aktuell aktiven Zweig in eine neue Sitzung klonenEine 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

OrtGeltungsbereich
~/.pi/agent/extensions/*.tsGlobal, gilt für alle Projekte
.pi/extensions/*.tsAuf 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ähigkeitEntsprechende MethodeTypische Verwendung
Benutzerdefinierte Tools registrierenpi.registerTool()Das Modell Ihre Geschäftsschnittstelle aufrufen lassen
Befehle registrierenpi.registerCommand()Eigene Slash-Befehle hinzufügen
Tastenkürzel registrierenpi.registerShortcut()Benutzerdefinierte Tastenkürzel binden
Tool-Aufrufe abfangentool_callEreignisBerechtigungsbestätigung, Umschreiben von Befehlen
Kontext änderncontextEreignisVerlauf filtern, RAG-Inhalte injizieren
Nachrichten injizierenpi.sendMessage()Kontext dynamisch ergänzen
Provider registrierenpi.registerProvider()Auf private Modell-Gateways zugreifen
Benutzerdefinierte UIctx.uiSerieDialoge, 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

OrtGeltungsbereich
~/.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:

FeldErforderlich?Beschreibung
nameErforderlichBis zu 64 Zeichen, nur Kleinbuchstaben, Zahlen und Bindestriche
descriptionErforderlichBis 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

BefehlFunktion
pi listInstallierte Pakete auflisten
pi updateNur Pi selbst aktualisieren
pi update --allPi und alle Pakete aktualisieren
pi update --extensionsNur Pakete aktualisieren, Pi selbst unverändert lassen
pi update --extension <源>Ein bestimmtes Paket aktualisieren
pi configRessourcen 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.

VertrauensstufeVerhaltenEinstellungsmethode
ask(Standard)Interaktive Abfrage; Projektressourcen im nicht-interaktiven Modus ignorierenvon settings.jsondefaultProjectTrust
alwaysProjektressourcen immer vertrauenWie oben, oder verwenden Sie-a / --approve
neverNiemals vertrauen, Projektressourcen ignorierenWie 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 gesamtenpiProzess 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

Weitere Erweiterungen