Pi Agent Kernkonzepte

Bevor Sie Pi Agent offiziell verwenden, kann das Verständnis seiner Kernkonzepte und Arbeitsweisen Ihnen helfen, schneller loszulegen.


Pi Agent in einem Satz verstehen

Pi Agent ist ein KI-Programmierassistent, der im Terminal läuft.

Nach dem Start sehen Sie eine Oberfläche, die Chat-Software ähnelt. Geben Sie Anforderungen in natürlicher Sprache ein, und die KI kann Ihren Code lesen, Befehle ausführen und Dateien ändern.


Vier Betriebsmodi

Pi Agent unterstützt vier Betriebsmodi für unterschiedliche Szenarien:

ModeBefehlBeschreibungAnwendungsfall
Interaktiver Moduspi (Standard)Terminal-TUI-Oberfläche, Echtzeit-Konversation, unterstützt alle FunktionenTägliche Entwicklung, interaktive Programmierung
Print-Moduspi -p "prompt"Einmalige Frage-und-Antwort, beendet sich nach Ausgabe des ErgebnissesSkript-Integration, schnelle Abfragen
JSON-Moduspi --mode jsonAlle Ereignisse werden als JSON-Zeilen ausgegeben, geeignet für das Parsen durch ProgrammeToolchain-Integration, Datenanalyse
RPC-Moduspi --mode rpcIntegriert über das JSONL-Protokoll via stdin/stdoutInterprozesskommunikation, Editor-Plug-ins

Der interaktive Modus startet direkt in der TUI-Oberfläche:

$ pi
Pi Agent 0.1.x  |  ~/projects/example-demo
claude-sonnet-4  |  上下文 2%  |  $0.0000
>

Der Print-Modus beendet sich nach der Antwort und eignet sich zur Einbindung in Skripte:

$ pi -p "总结这个项目"
这是一个 TypeScript 命令行工具,核心逻辑位于 src/ 目录,包含会话管理、工具调度和扩展加载三个模块。
Tokens: 1.2k 输入 / 320 输出  |  费用 $0.0081

Der JSON-Modus gibt jedes Ereignis als eine Zeile JSON aus, was das Parsen für Programme erleichtert:

$ pi --mode json -p "总结这个项目"
{"type":"session","id":"a1b2c3d4"}
{"type":"message_start","role":"assistant"}
{"type":"message_end","usage":{"input":1200,"output":320}}

Der RPC-Modus sendet und empfängt JSONL-Nachrichten über stdin/stdout für Aufrufe von Editor-Plugins:

$ pi --mode rpc
{"id":1,"method":"prompt","params":{"message":"列出 src 目录"}}
{"id":1,"result":{"state":"idle","messages":2}}

Als Anfänger verbringst du die meiste Zeit im interaktiven Modus.

Sobald du versiert bist, kann der Print-Modus für die Skriptautomatisierung verwendet werden.


Integrierte Tools

Nach dem Start stellt Pi Agent der KI standardmäßig die folgenden vier integrierten Tools zur Verfügung. Darüber hinaus können optional drei schreibgeschützte Tools—grep, find und ls—aktiviert werden:

Tool-NameFunktionBeispielStandardstatus
readDateiinhalt lesenKI liest src/main.ts, um die Codelogik zu verstehenStandardmäßig aktiviert
writeDateien erstellen oder überschreibenKI erstellt eine neue Datei oder schreibt die gesamte Datei neuStandardmäßig aktiviert
editInhalt in einer Datei präzise ersetzenKI ändert ein paar Codezeilen in einer FunktionStandardmäßig aktiviert
bashShell-Befehle ausführenKI führt Tests aus, installiert Abhängigkeiten und führt lint ausStandardmäßig aktiviert
grepText in Dateien suchenKI sucht, welche Dateien eine bestimmte Funktion aufrufenOptional
findeDateien nach Namen suchenKI findet alle Dateien namens *.test.tsOptional
lsVerzeichnisinhalt auflistenKI sieht sich die Verzeichnisstruktur an, um Module zu findenOptional

Die drei schreibgeschützten Tools werden über den--tools-Parameter manuell aktiviert, zum Beispielpi --tools read,grep,find,ls。


Erweiterungssystem

Pi Agent erweitert seine Funktionalität auf die folgenden fünf Arten:

ErweiterungsmethodeDateiformatZweckSchwierigkeit
ErweiterungenTypeScript(.ts)Benutzerdefinierte Tools, Event-Listener, Befehle und UI-Komponenten registrierenErfordert Programmierung
SkillsMarkdown(SKILL.md)Bietet Workflow-Anweisungen und Skripte für spezialisierte BereicheEs genügt, zu wissen, wie man Markdown schreibt
Prompt-VorlagenMarkdown(.md)Wiederverwendbare Prompts mit ParameterunterstützungAm einfachsten
ThemesJSON(.json)Farbschema der Terminal-Oberfläche anpassenEinfach
Paketenpm/git-ProjekteDie oben genannten vier Arten von Ressourcen paketieren und teilenNach Bedarf

Als Anfänger musst du nicht sofort alle Erweiterungsmethoden verstehen.

Beginne zuerst mit der grundlegenden Nutzung und erkunde das Erweiterungssystem nach und nach, wenn deine Anforderungen wachsen.


Dateiladereihenfolge

Wenn Pi Agent startet, lädt es automatisch Projektanweisungsdateien, sodass du das erwartete Verhalten für die KI definieren kannst:

StufePfadGeltungsbereichPriorität
Globale Konfiguration~/.pi/agent/AGENTS.mdAlle ProjekteNiedrigste Priorität, dient als allgemeine Grundlage
ProjektkonfigurationAGENTS.md oder CLAUDE.md im Projektverzeichnis und in übergeordneten VerzeichnissenAktuelles ProjektHöchste Priorität, kann globale Anweisungen überschreiben

Die Konfiguration auf Projektebene wird geladen, indem vom übergeordneten Verzeichnis aus nach oben durchlaufen wird, und wird schließlich mit der Konfiguration im aktuellen Verzeichnis zusammengeführt.

Wenn du Claude Code bereits verwendet hast, kannst du vorhandene CLAUDE.md-Dateien direkt wiederverwenden; Pi Agent erkennt und lädt sie automatisch.


Sitzungen und Branches

Das Session-System von Pi Agent ist eines seiner unverwechselbarsten Merkmale.

Jede Konversation wird automatisch als Sitzungsdatei gespeichert, im~/.pi/agent/sessions/Verzeichnis.

Intern verwenden Sitzungen eine Baumstruktur: Du kannst von jedem historischen Knoten aus neue Erkundungsrichtungen "abzweigen", ohne frühere Konversationen zu verlieren.

Pi Agent 会话树分叉结构示意

Dies ist sehr nützlich, wenn du mit verschiedenen Implementierungsansätzen experimentieren musst – jeder Gedankengang kann unabhängig erhalten und jederzeit erneut aufgegriffen werden.

Andere Erweiterungen