Pi Agent Nicht-interaktiver Modus
Neben interaktiver Konversation bietet Pi Agent auch drei nicht-interaktive Modi, geeignet für Skriptintegration, automatisierte Arbeitsabläufe und Kommunikation zwischen Programmen.
Print-Modus (-p)
Der Print-Modus ist der am häufigsten verwendete nicht-interaktive Modus; er führt eine einmalige Frage-und-Antwort aus, gibt das Ergebnis aus und beendet sich.
Grundlegende Verwendung
Die einfachste Form besteht darin, eine Frage direkt nach -p zu setzen, und die KI beendet sich nach der Antwort.
$ pi -p "帮我总结一下这个项目的结构" 这是一个 TypeScript + Vite 项目，源码集中在 src/ 目录下。 入口文件是 src/main.ts，工具函数位于 src/utils/，共 18 个模块。
Verwende @, um auf eine Datei zu verweisen, sodass die KI den Inhalt der angegebenen Datei liest:
$ pi -p @README.md "这段文档的主要内容是什么" 这份 README 介绍了安装步骤、环境变量配置和三条常用命令。
Verwende eine Pipe, um die Befehlsausgabe direkt an die KI zu übergeben, geeignet für die Verarbeitung von Text wie Protokollen und Dokumenten:
$ cat README.md | pi -p "用三句话总结这段文字" 1. 项目要求 Node 20 以上版本。 2. 安装依赖后先把 .env.example 复制为 .env. 3. 日常调试用 npm run dev，发布构建用 npm run build.
@ kann auch auf Bilder verweisen, sodass die KI Bildinhalte analysieren kann:
$ pi -p @screenshot.png "图片中显示的错误信息是什么" 截图中的报错是 Module not found: Can't resolve './utils/format'， 说明 src/index.ts 里的相对路径拼写有误。
Verwende --name, um die Sitzung zu benennen; du kannst diesen Thread später im interaktiven Modus fortsetzen:
$ pi --name "快速审查" -p "审查 src/ 目录下的代码质量" 代码整体质量良好，有 3 处可以改进： 1. src/api/user.ts 缺少对分页参数的校验。 2. src/utils/format.ts 的日期格式化未处理时区。 3. src/db/query.ts 的裸抛异常建议补充错误码。
Ein Modell angeben
Verwende --provider zusammen mit --model, um ein Modell anzugeben, oder kombiniere beide zur Form provider/model.
$ pi --provider openai --model gpt-4o -p "帮我重构这段代码的逻辑" 重构建议：把 src/service/order.ts 中 120 行的 createOrder 拆成 校验参数、计算金额、落库三个函数，并为每个函数补充单元测试。
Die folgende kombinierte Form ist vollständig äquivalent zur vorherigen, nur kürzer zu schreiben:
$ pi --model openai/gpt-4o -p "帮我重构这段代码的逻辑"
Das Anhängen eines Doppelpunkts und einer Reasoning-Stufe nach dem Modellnamen steuert die Denktiefe dieses Aufrufs:
$ pi --model sonnet:high -p "这个复杂的算法有什么潜在问题" 主要风险有三点：递归深度没有上限会导致栈溢出； 缓存键未包含用户身份，存在越权读取的可能； 批量写入缺少事务包裹，失败时会出现半提交状态。
In --model, können sowohl das Suffix:thinking(wie sonnet:high) als auch der Parameter--thinking--reasoning-effort die Reasoning-Stufe festlegen.
Es wird empfohlen, nur eine davon zu verwenden, um schwer zu debuggende Inkonsistenzen zwischen den beiden Formen zu vermeiden.
Verwende --models, um den verfügbaren Modellbereich einzuschränken, und trenne mehrere Modelle durch Kommas:
$ pi --models "claude-*,gpt-4o" -p "审查代码" 审查完成：共发现 2 个阻塞问题和 5 个改进建议， 详细列表已按严重程度排序。
Tool-Steuerung
Die Steuerung, welche Tools die KI über Kommandozeilenparameter verwenden kann, ist der Schlüssel, um den nicht-interaktiven Modus sicher in Skripten auszuführen.
Pi Agent hat 7 integrierte Tools auf Nicht-Windows-Plattformen: read, write, edit, bash, grep, find, ls.
Unter Windows wird bash durch powershell ersetzt.
Verwende --tools als Whitelist, um nur die angegebenen Tools beizubehalten; zum Beispiel einen schreibgeschützten Modus, der keine Dateien ändert:
$ pi --tools read,grep,find,ls -p "审查代码不修改" 审查结果：共 4 个问题，其中 1 个涉及并发写入， 完整报告已输出到终端，本次未修改任何文件。
Verwende --exclude-tools, um angegebene Tools auszuschließen:
$ pi --exclude-tools bash -p "分析代码但不执行命令" 分析结论：该模块的性能瓶颈在循环内的重复文件读取， 建议把目录列表提到循环外，预计可减少 80% 的 I/O.
Verwende --no-builtin-tools, um alle integrierten Tools zu deaktivieren; die KI kann nur basierend auf dem Gesprächsinhalt antworten, während Erweiterungen und benutzerdefinierte Tools weiterhin verfügbar bleiben:
$ pi --no-builtin-tools -p "纯问答" Quicksort 的平均时间复杂度是 O(n log n)， 最坏情况是 O(n^2)，出现在已排序数组上选取首元素为主元时。
Wenn zusätzlich Erweiterungen und benutzerdefinierte Tools deaktiviert werden sollen, wechsle zu --no-tools.
JSON-Modus (--mode json)
Der JSON-Modus gibt alle Ereignisse im JSON Lines-Format (JSONL) aus und eignet sich für das Parsen und die Verarbeitung durch Programme.
$ pi --mode json "总结项目结构"
{"type":"session","version":3,"id":"019f8c2e-7a41-7b3d-9e5f-2c6a1d84b0e7","timestamp":"2026-08-31T02-40-11-000Z","cwd":"/Users/example/projects/example-demo"}
{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{...}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{...}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}
Die erste Zeile ist ein Sitzungsmetadaten-Header, der Formatversion, Sitzungs-ID, Zeitstempel und Arbeitsverzeichnis aufzeichnet.
Jede weitere Zeile ist ein unabhängiges JSON-Ereignis, das den Ereignistyp und die zugehörigen Daten enthält.
Dieser Modus eignet sich für die folgenden Szenarien:
| Szenario | Beschreibung |
|---|---|
| Datenverarbeitungs-Pipeline | Den Ereignisstrom in Nachverarbeitungsskripte einspeisen und Zeile für Zeile parsen/verarbeiten |
| Verhaltensüberwachung und -analyse | Jeden Tool-Aufruf und jeden Entscheidungsprozess der KI aufzeichnen und analysieren |
| Benutzerdefinierte Toolchain | Baue deinen eigenen automatisierten Workflow auf dem Ereignisstrom auf |
RPC-Modus (--mode rpc)
Der RPC-Modus implementiert Interprozesskommunikation über das JSONL-Protokoll via stdin/stdout.
Er ermöglicht einem anderen Programm, Befehle über die Standardeingabe zu senden und Antworten von der Standardausgabe zu lesen.
Der RPC-Modus unterstützt ein erweitertes UI-Protokoll, wodurch Remote-Clients interaktive Elemente wie Bestätigungsdialoge und Auswahllisten darstellen können.
Dieser Modus eignet sich für die folgenden Szenarien:
| Szenario | Beschreibung |
|---|---|
| Editor-Plugins | Integriere Pi Agent in Editor-Erweiterungen wie VS Code |
| Benutzerdefiniertes Frontend | Erstelle deine eigene Pi Agent-Oberfläche basierend auf dem RPC-Protokoll |
| Hintergrunddienste | Bette Pi Agent als Unterprozess in ein größeres System ein |
Der RPC-Modus und der JSON-Modus sind fortgeschrittene Funktionen, die sich an Entwickler richten.
Als Anfänger benötigst du höchstwahrscheinlich nur den interaktiven Modus und den Print-Modus.
Wenn Sie Pi Agent in Ihre Toolchain integrieren müssen, können Sie zurückkommen und diese beiden Modi eingehend studieren.
Modusvergleich
Die Unterschiede zwischen den drei nicht interaktiven Modi zeigen sich hauptsächlich in Interaktivität und Ausgabeformat; wählen Sie einfach entsprechend der folgenden Tabelle.
| Mode | Befehl | Interaktivität | Ausgabeformat | Geeignete Szenarien |
|---|---|---|---|---|
| Interaktiver Modus | pi (Standard) | Echtzeit-Konversation | Terminal-TUI-Darstellung | Tägliche Entwicklung, interaktive Programmierung |
| Print-Modus | pi -p | One-Shot-Antwort | Nur Text | Skript-Integration, schnelle Abfragen |
| JSON-Modus | pi --mode json | Ereignisstrom (nicht interaktiv) | JSONL-Ereignisstrom | Programm-Parsing, Pipeline-Verarbeitung |
| RPC-Modus | pi --mode rpc | Kontinuierliche Kommunikation | Bidirektionales JSONL-Protokoll | Editor-Integration, Prozesskommunikation |
CLI-Parameter-Kurzreferenz
Die folgende Tabelle listet häufige Parameter des pi-Befehls nach Zweck gruppiert auf; sie können zusammen mit den Befehlen im interaktiven Modus verwendet werden.
| Kategorie | Parameter | Beschreibung |
|---|---|---|
| Modelloptionen | --provider name | KI-Anbieter angeben |
| Modelloptionen | --model pattern | Modell-ID angeben; unterstützt die Formate provider/id und :thinking |
| Modelloptionen | --api-key key | API-Key direkt übergeben (höchste Priorität) |
| Modelloptionen | --thinking level | Reasoning-Stufe: off/minimal/low/medium/high/xhigh/max |
| Modelloptionen | --models patterns | Kommagetrennte Liste von Modellen, die den Bereich für das Wechseln mit Ctrl+P einschränkt |
| Sitzungsoptionen | -c, --continue | Die letzte Sitzung fortsetzen |
| Sitzungsoptionen | -r, --resume | Frühere Sitzungen durchsuchen und auswählen |
| Sitzungsoptionen | --session path|id | Angegebene Sitzungsdatei oder UUID verwenden |
| Sitzungsoptionen | --fork path|id | Eine neue Sitzung von der angegebenen Sitzung abzweigen |
| Sitzungsoptionen | --name, -n name | Anzeigenamen der Sitzung festlegen |
| Sitzungsoptionen | --no-session | Sitzung nicht aufzeichnen |
| Sitzungsoptionen | --export <input> [output] | Sitzung als HTML exportieren (Ausgabepfad kann weggelassen werden) |
| Tool-Optionen | --tools, -t list | Bestimmte Tools auf die Whitelist setzen |
| Tool-Optionen | --exclude-tools, -xt list | Bestimmte Tools deaktivieren |
| Tool-Optionen | --no-builtin-tools, -nbt | Alle integrierten Tools deaktivieren |
| Tool-Optionen | --no-tools, -nt | Alle Tools deaktivieren (reiner Konversationsmodus) |
| Ressourcenoptionen | -e, --extension source | Erweiterungen laden (wiederholbar) |
| Ressourcenoptionen | --skill path | Skills laden (wiederholbar) |
| Ressourcenoptionen | --theme path | Themes laden (wiederholbar) |
| Weitere Optionen | -a, --approve | Projektlokalen Dateien für diesen Lauf vertrauen |
| Weitere Optionen | --no-context-files, -nc | Automatisches Laden von AGENTS.md/CLAUDE.md deaktivieren |