Erstes Gespräch mit Pi Agent

Nach Abschluss der Installation und Authentifizierungskonfiguration führt dieses Kapitel Sie durch Ihr erstes vollständiges Gesprächserlebnis.

Sie werden sich mit dem Layout der Oberfläche und den grundlegenden Bedienvorgängen vertraut machen.


Pi Agent starten

Wechseln Sie in Ihr Projektverzeichnis und starten Sie Pi Agent:

$ cd ~/projects/example-demo
$ pi

Sie werden sehen, wie die interaktive Oberfläche von Pi Agent im Terminal erscheint.

Pi Agent 交互界面四个区域布局

Die Oberfläche ist in vier Hauptbereiche unterteilt:

BereichPositionAngezeigter Inhalt
StartkopfzeileTopTastenkürzelhinweise, geladene Kontextdateien, Prompt-Vorlagen, Skills, Erweiterungen
NachrichtenbereichMiddleBenutzernachrichten, KI-Antworten, Tool-Aufrufdetails, Benachrichtigungen und Fehler
BearbeitungsbereichUntere EingabezeileDeine Eingabeposition; die Rahmenfarbe gibt die aktuelle Reasoning-Stufe an
Untere StatusleisteBottomArbeitsverzeichnis, Sitzungsname, Token-/Cache-Nutzung, Kontextnutzung, Kosten, aktueller Modellname (Gesamt umfasst KI-Antworten, vom Tool gemeldete Nutzung und Verbrauch für die Zusammenfassungsgenerierung)

Wenn dir die beim Start angezeigten Header-Informationen zu viel sind, kannst du in den EinstellungenquietStartupdie Option aktivieren, um sie auszublenden.


Erste Aufgabe

Nachdem du die Oberfläche geöffnet hast, gib deine erste Anfrage ein und drücke die Eingabetaste:

Help me summarize the structure and main functions of this project.

Pi Agent verwendet integrierte Tools, um deine Projektdateien zu lesen, die Codestruktur zu analysieren und dann eine Zusammenfassung zurückzugeben.

Im Nachrichtenbereich kannst du sehen, was die KI tut – einschließlich der Tools, die sie aufgerufen hat, und der Dateien, die sie gelesen hat.

Die Ausgabe einer vollständigen Konversation sieht so aus:

> read README.md(1.2k 字符)
> read src/main.ts(3.4k 字符)

这是一个基于 TypeScript 的终端编程助手,主要功能分为会话管理、工具调度和扩展加载三部分。
Tokens: 2.4k 输入 / 410 输出  |  费用 $0.0152

Pi Agent bietet standardmäßig vier integrierte Tools: read, write, edit und bash. Für vollständige Details siehe das Kapitel „Überblick über Kernkonzepte“.


Dateien referenzieren

Du kannst in einer Konversation auf bestimmte Dateien verweisen; es gibt zwei Möglichkeiten:

Methode 1: @-Syntax (Suche im Editor)

Tippe in den Bearbeitungsbereich ein@Eine Fuzzy-Suche nach Projektdateien wird automatisch angezeigt:

@src/app.ts 解释这个文件的功能

Methode 2: Kommandozeilenargumente

Übergib Dateiverweise direkt beim Start:

$ pi @README.md "总结一下这个文档"
$ pi @src/app.ts @src/app.test.ts "对比这两个文件"

Du kannst auch auf Bilddateien verweisen:

$ pi -p @screenshot.png "这张截图里显示了什么"

Bilder einfügen

Pi Agent unterstützt das Senden von Bildern in Konversationen; die Vorgehensweise variiert je nach Plattform geringfügig.

PlattformAktionBeschreibung
macOS / LinuxCtrl+VBild aus der Zwischenablage einfügen
WindowsAlt+VBild aus der Zwischenablage einfügen
Unterstützte TerminalsZiehe ein Bild per Drag-and-Drop in das TerminalfensterÜbergebe es als Datei an die Konversation

Ausführen von Befehlen in der Konversation

Sie können Shell-Befehle direkt aus dem Bearbeitungsbereich ausführen, ohne Pi Agent zu verlassen:

!npm run lint
!git diff

Mit!Befehlen, die mit dem Präfix beginnen, werden ausgeführt, und die Ausgabe wird automatisch zur Überprüfung an die KI gesendet.

Führe aus!npm run lintDas Ergebnis ist ähnlich wie:

> pi-agent@1.0.0 lint
> eslint .
0 errors, 0 warnings

Mit!!Befehlen, die mit dem Präfix beginnen, werden ebenfalls ausgeführt, aberwerden nichtdie Ausgabe an die KI senden:

!!echo "这只在本地显示"
这只在本地显示

Die Verwendung!!des Präfixes zum Ausführen von Befehlen, die keine KI-Überprüfung benötigen (z. B. Öffnen von Dateien, Anzeigen von Umgebungsvariablen), kann das Verschwenden des Kontextfensters vermeiden.


Mehrzeilige Eingabe und externer Editor

Große Textblöcke können mit mehrzeiliger Eingabe oder einem externen Editor geschrieben werden; hier sind die relevanten Tastenkürzel.

AktionTastenkürzel
Neue Zeile einfügenShift+Enter (verwenden Sie Ctrl+Enter im Windows-Terminal)
Externen Editor öffnenCtrl+G

Wenn Sie einen großen Textblock eingeben müssen, drücken SieCtrl+G, und der Standard-Editor des Systems wird geöffnet (z. B. nano, vim oder VS Code); nach dem Speichern wird der Inhalt automatisch in den Bearbeitungsbereich von Pi Agent eingefügt.


Nachrichtenwarteschlange

Pi Agent ermöglicht es Ihnen, Nachrichten zu senden, während die KI arbeitet, ohne darauf warten zu müssen, dass sie fertig wird:

TastenkürzelVerhaltenBeschreibung
EnterSteuerungsnachricht sendenWird an die KI gesendet, sobald das aktuelle Tool die Ausführung beendet hat
Alt+EnterFolgenachricht sendenWird gesendet, nachdem die KI ihre gesamte Arbeit abgeschlossen hat
EscapeNachrichten in der Warteschlange abbrechenDie in der Warteschlange befindlichen Nachrichten in den Bearbeitungsbereich wiederherstellen
Alt+UpNachricht aus der Warteschlange abrufenEine Nachricht aus der Warteschlange zur Bearbeitung in den Bearbeitungsbereich zurückholen

In Windows Terminal ist Alt+Enter die Standard-Tastenkombination für den Vollbildmodus. Wenn Pi Agent diese Tastenkombination empfangen soll, lesen SieMultiplattform-Bereitstellungfür Anweisungen zur Neuzuordnung.


Nicht-interaktiver Modus

Neben interaktiven Gesprächen kannst du Pi Agent auch schnell auf folgende Weise verwenden:

Beispiele

# Einmalige Frage-und-Antwort, beendet sich nach der Ausgabe
pi -p "Fasse diese Codebasis zusammen"

# Pipe-Eingabe: Dateiinhalt an die KI übergeben
cat README.md | pi -p "Fasse diesen Text zusammen"

# Einmalige Frage-und-Antwort mit einem Bild
pi -p @screenshot.png "Was ist auf diesem Bild?"

# Benannte Sitzung (für einfaches späteres Fortsetzen)
pi --name "Code-Überprüfung" -p "Überprüfe den Code im Verzeichnis src/"

# Nur-Lese-Modus (Dateiänderungen nicht erlaubt)
pi --tools read,grep,find,ls -p "Code überprüfen, ohne ihn zu verändern"

Der Print-Modus (-p) eignet sich ideal für die Integration in Skripte und CI-Pipelines.


Erstellen einer Projektanweisungsdatei

Um der KI zu helfen, dein Projekt besser zu verstehen, wird empfohlen, eine AGENTS.md-Datei zu erstellen.

Speichere den folgenden Inhalt als Markdown-Datei mit dem PfadProjektstammverzeichnis/AGENTS.md:

Beispiele

# Projektanweisungen

- Führe `npm run check` nach Änderungen am Code aus
- Führe Produktionsmigrationen nicht direkt auf deinem lokalen Rechner aus
- Halte Antworten kurz, ohne übermäßige Erklärungen
- Schreibe Code im TypeScript-Strict-Modus
- Befolge den vorhandenen Code-Stil des Projekts

Pi Agent lädt diese Datei beim Start automatisch.

Er lädt außerdem aus~/.pi/agent/AGENTS.mddie globalen Anweisungen und Anweisungsdateien in übergeordneten Verzeichnissen.

Verwende nach dem Aktualisieren von AGENTS.md den Befehl/reloadzum Hot-Reload; ein Neustart ist nicht nötig.

Wenn du zuvor Claude Code verwendet hast, können vorhandene CLAUDE.md-Dateien von Pi Agent direkt erkannt und genutzt werden, ohne dass sie umbenannt werden müssen.


Oberflächenübersicht

Das Folgende ist eine Schnellreferenz für die wichtigsten Tastenkürzel im interaktiven Modus von Pi Agent:

AktionTastenkürzelBeschreibung
Eingabe absendenEnterDen aktuellen Inhalt des Bearbeitungsbereichs senden; wenn die KI arbeitet, wird er in die Nachrichtenwarteschlange eingereiht (siehe Nachrichtenwarteschlange)
ModellauswahlCtrl+LModellauswahl öffnen
Modell wechselnCtrl+P / Shift+Ctrl+PVorwärts/rückwärts durch Modelle wechseln
Reasoning-LevelShift+TabReasoning-Level durchschalten
Tool-Ausgabe ein-/ausklappenCtrl+OAnzeige der Ergebnisse von Tool-Aufrufen umschalten
Reasoning-Prozess ein-/ausklappenCtrl+TAnzeige des Reasoning-Prozesses der KI umschalten
Vorgang unterbrechenEscapeAktuelle KI-Operation abbrechen (siehe Nachrichtenwarteschlange)
Bearbeitungsbereich leerenCtrl+CDen aktuellen Inhalt des Bearbeitungsbereichs leeren
Letzte Antwort der KI kopierenCtrl+XAntwortinhalt in die Zwischenablage kopieren
Pfad-AutovervollständigungTabDateipfade vervollständigen
Programm beendenCtrl+DProgramm beenden, wenn der Bearbeitungsbereich leer ist
Programm beenden (direkt)/quitSofort beenden
Weitere Erweiterungen