Pi Agent: неинтерактивный режим
Помимо интерактивного диалога, Pi Agent также предоставляет три неинтерактивных режима, подходящих для интеграции скриптов, автоматизированных рабочих процессов и обмена данными между программами.
Режим печати (-p)
Режим печати — наиболее часто используемый неинтерактивный режим; он выполняет одноразовый вопрос-ответ, выводит результат и завершает работу.
Базовое использование
Простейшая форма — указать вопрос сразу после -p, и ИИ завершает работу после ответа.
$ pi -p "帮我总结一下这个项目的结构" 这是一个 TypeScript + Vite 项目，源码集中在 src/ 目录下。 入口文件是 src/main.ts，工具函数位于 src/utils/，共 18 个模块。
Используйте @ для ссылки на файл, чтобы ИИ прочитал содержимое указанного файла:
$ pi -p @README.md "这段文档的主要内容是什么" 这份 README 介绍了安装步骤、环境变量配置和三条常用命令。
Используйте конвейер, чтобы передать вывод команды напрямую ИИ; подходит для обработки текста, например журналов и документов:
$ cat README.md | pi -p "用三句话总结这段文字" 1. 项目要求 Node 20 以上版本。 2. 安装依赖后先把 .env.example 复制为 .env. 3. 日常调试用 npm run dev，发布构建用 npm run build.
@ также может ссылаться на изображения, позволяя ИИ анализировать содержимое изображения:
$ pi -p @screenshot.png "图片中显示的错误信息是什么" 截图中的报错是 Module not found: Can't resolve './utils/format'， 说明 src/index.ts 里的相对路径拼写有误。
Используйте --name, чтобы задать имя сеанса; позже вы сможете продолжить эту ветку в интерактивном режиме:
$ pi --name "快速审查" -p "审查 src/ 目录下的代码质量" 代码整体质量良好，有 3 处可以改进： 1. src/api/user.ts 缺少对分页参数的校验。 2. src/utils/format.ts 的日期格式化未处理时区。 3. src/db/query.ts 的裸抛异常建议补充错误码。
Указание модели
Используйте --provider вместе с --model, чтобы указать модель, или объедините их в форму provider/model.
$ pi --provider openai --model gpt-4o -p "帮我重构这段代码的逻辑" 重构建议：把 src/service/order.ts 中 120 行的 createOrder 拆成 校验参数、计算金额、落库三个函数，并为每个函数补充单元测试。
Приведённая ниже объединённая форма полностью эквивалентна предыдущей, только короче для записи:
$ pi --model openai/gpt-4o -p "帮我重构这段代码的逻辑"
Добавление двоеточия и уровня рассуждений после имени модели управляет глубиной мышления этого вызова:
$ pi --model sonnet:high -p "这个复杂的算法有什么潜在问题" 主要风险有三点：递归深度没有上限会导致栈溢出； 缓存键未包含用户身份，存在越权读取的可能； 批量写入缺少事务包裹，失败时会出现半提交状态。
В --model, суффикс:thinking(например, sonnet:high) и параметр--thinking--reasoning-effort могут оба задавать уровень рассуждений.
Рекомендуется использовать только один из них, чтобы избежать трудноотлаживаемых несоответствий между двумя формами.
Используйте --models, чтобы ограничить доступный набор моделей, разделяя несколько моделей запятыми:
$ pi --models "claude-*,gpt-4o" -p "审查代码" 审查完成：共发现 2 个阻塞问题和 5 个改进建议， 详细列表已按严重程度排序。
Управление инструментами
Управление тем, какие инструменты ИИ может использовать, через параметры командной строки — ключ к безопасному запуску неинтерактивного режима в скриптах.
Pi Agent имеет 7 встроенных инструментов на платформах, отличных от Windows: read, write, edit, bash, grep, find, ls.
В Windows bash заменяется на powershell.
Используйте --tools в качестве белого списка, чтобы оставить только указанные инструменты; например, режим только для чтения, который не изменяет никакие файлы:
$ pi --tools read,grep,find,ls -p "审查代码不修改" 审查结果：共 4 个问题，其中 1 个涉及并发写入， 完整报告已输出到终端，本次未修改任何文件。
Используйте --exclude-tools, чтобы исключить указанные инструменты:
$ pi --exclude-tools bash -p "分析代码但不执行命令" 分析结论：该模块的性能瓶颈在循环内的重复文件读取， 建议把目录列表提到循环外，预计可减少 80% 的 I/O.
Используйте --no-builtin-tools, чтобы отключить все встроенные инструменты; ИИ может отвечать только на основе содержимого диалога, при этом расширения и пользовательские инструменты остаются доступными:
$ pi --no-builtin-tools -p "纯问答" Quicksort 的平均时间复杂度是 O(n log n)， 最坏情况是 O(n^2)，出现在已排序数组上选取首元素为主元时。
Когда нужно также отключить расширения и пользовательские инструменты, переключитесь на --no-tools.
Режим JSON (--mode json)
Режим JSON выводит все события в формате JSON Lines (JSONL), подходящем для программного парсинга и обработки.
$ 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":[...]}
Первая строка — это заголовок метаданных сессии, в котором записаны версия формата, идентификатор сессии, отметка времени и рабочий каталог.
Каждая последующая строка — это независимое событие JSON, содержащее тип события и соответствующие данные.
Этот режим подходит для следующих сценариев:
| Сценарий | Описание |
|---|---|
| Конвейер обработки данных | Подавайте поток событий в скрипты постобработки и разбирайте/обрабатывайте его построчно |
| Мониторинг и анализ поведения | Записывайте и анализируйте каждый вызов инструмента и процесс принятия решений ИИ |
| Пользовательская цепочка инструментов | Создавайте собственный автоматизированный рабочий процесс на основе потока событий |
Режим RPC (--mode rpc)
Режим RPC реализует межпроцессное взаимодействие через протокол JSONL поверх stdin/stdout.
Он позволяет другой программе отправлять команды через стандартный ввод и читать ответы из стандартного вывода.
Режим RPC поддерживает расширенный протокол UI, позволяя удалённым клиентам отображать интерактивные элементы, такие как диалоги подтверждения и списки выбора.
Этот режим подходит для следующих сценариев:
| Сценарий | Описание |
|---|---|
| Плагины для редакторов | Интегрируйте Pi Agent в расширения редакторов, такие как VS Code |
| Пользовательский фронтенд | Создайте собственный интерфейс Pi Agent на основе протокола RPC |
| Фоновые службы | Встройте Pi Agent как подпроцесс в более крупную систему |
Режим RPC и режим JSON — это продвинутые функции, предназначенные для разработчиков.
Если вы новичок, скорее всего, вам понадобятся только интерактивный режим и режим Print.
Когда вам нужно интегрировать Pi Agent в вашу цепочку инструментов, вы можете вернуться и подробно изучить эти два режима.
Сравнение режимов
Различия между тремя неинтерактивными режимами в основном проявляются в интерактивности и формате вывода; просто выбирайте согласно таблице ниже.
| Mode | Команда | Интерактивность | Формат вывода | Применимые сценарии |
|---|---|---|---|---|
| Интерактивный режим | pi (по умолчанию) | Общение в реальном времени | Отрисовка TUI в терминале | Ежедневная разработка, интерактивное программирование |
| Режим печати | pi -p | Одноразовый ответ | Обычный текст | Интеграция со скриптами, быстрые запросы |
| Режим JSON | pi --mode json | Поток событий (неинтерактивный) | Поток событий JSONL | Парсинг программой, конвейерная обработка |
| Режим RPC | pi --mode rpc | Непрерывное общение | Двунаправленный протокол JSONL | Интеграция с редактором, взаимодействие процессов |
Краткий справочник параметров CLI
В таблице ниже перечислены общие параметры команды pi, сгруппированные по назначению; их можно использовать вместе с командами в интерактивном режиме.
| Категория | Параметр | Описание |
|---|---|---|
| Параметры модели | --provider name | Указать провайдера ИИ |
| Параметры модели | --model pattern | Указать ID модели; поддерживаются форматы provider/id и :thinking |
| Параметры модели | --api-key key | Передать API-ключ напрямую (наивысший приоритет) |
| Параметры модели | --thinking level | Уровень рассуждений: off/minimal/low/medium/high/xhigh/max |
| Параметры модели | --models patterns | Список моделей через запятую, ограничивающий диапазон переключения Ctrl+P |
| Параметры сеанса | -c, --continue | Продолжить последнюю сессию |
| Параметры сеанса | -r, --resume | Просмотреть и выбрать исторические сеансы |
| Параметры сеанса | --session path|id | Использовать указанный файл сеанса или UUID |
| Параметры сеанса | --fork path|id | 从指定的会话派生新会话 |
| Параметры сеанса | --name, -n name | Задать отображаемое имя сеанса |
| Параметры сеанса | --no-session | Не записывать сеанс |
| Параметры сеанса | --export <input> [output] | Экспортировать сеанс в HTML (путь вывода можно опустить) |
| Параметры инструментов | --tools, -t список | Добавить указанные инструменты в белый список |
| Параметры инструментов | --exclude-tools, -xt список | Отключить указанные инструменты |
| Параметры инструментов | --no-builtin-tools, -nbt | Отключить все встроенные инструменты |
| Параметры инструментов | --no-tools, -nt | Отключить все инструменты (режим чистого диалога) |
| Параметры ресурсов | -e, --extension source | Загрузить расширения (можно повторять) |
| Параметры ресурсов | --skill path | Загрузить навыки (можно повторять) |
| Параметры ресурсов | --theme путь | Загрузить темы (можно повторять) |
| Другие параметры | -a, --approve | Доверять локальным файлам проекта для этого запуска |
| Другие параметры | --no-context-files, -nc | Отключить автоматическую загрузку AGENTS.md/CLAUDE.md |