Основные концепции Pi Agent
Прежде чем официально использовать Pi Agent, понимание его основных концепций и принципов работы поможет вам быстрее начать работу.
Понимание Pi Agent в одном предложении
Pi Agent — это ИИ-ассистент для программирования, работающий в терминале.
После запуска вы увидите интерфейс, похожий на чат-программу. Вводите требования на естественном языке, и ИИ сможет читать ваш код, выполнять команды и изменять файлы.
Четыре режима работы
Pi Agent поддерживает четыре режима работы для разных сценариев:
| Mode | Команда | Описание | Сценарий использования |
|---|---|---|---|
| Интерактивный режим | pi (по умолчанию) | Терминальный интерфейс TUI, общение в реальном времени, поддерживает все функции | Ежедневная разработка, интерактивное программирование |
| Режим печати | pi -p "prompt" | Одноразовый вопрос-ответ, завершается после вывода результата | Интеграция со скриптами, быстрые запросы |
| Режим JSON | pi --mode json | Все события выводятся в виде строк JSON, подходит для программного разбора | Интеграция с цепочкой инструментов, анализ данных |
| Режим RPC | pi --mode rpc | Интеграция через протокол JSONL по stdin/stdout | Межпроцессное взаимодействие, плагины редакторов |
Интерактивный режим сразу запускается в интерфейсе TUI:
$ pi Pi Agent 0.1.x | ~/projects/example-demo claude-sonnet-4 | 上下文 2% | $0.0000 >
Режим Print завершается после ответа, подходит для вставки в скрипты:
$ pi -p "总结这个项目" 这是一个 TypeScript 命令行工具，核心逻辑位于 src/ 目录，包含会话管理、工具调度和扩展加载三个模块。 Tokens: 1.2k 输入 / 320 输出 | 费用 $0.0081
Режим JSON выводит каждое событие как строку JSON, что упрощает разбор программами:
$ pi --mode json -p "总结这个项目"
{"type":"session","id":"a1b2c3d4"}
{"type":"message_start","role":"assistant"}
{"type":"message_end","usage":{"input":1200,"output":320}}
Режим RPC отправляет и принимает сообщения JSONL через stdin/stdout для вызовов плагинов редактора:
$ pi --mode rpc
{"id":1,"method":"prompt","params":{"message":"列出 src 目录"}}
{"id":1,"result":{"state":"idle","messages":2}}
Как новичок, вы будете проводить большую часть времени, работая в интерактивном режиме.
Когда вы освоитесь, режим Print можно использовать для автоматизации скриптов.
Встроенные инструменты
После запуска Pi Agent по умолчанию предоставляет ИИ следующие четыре встроенных инструмента. Кроме того, три инструмента только для чтения — grep, find и ls — можно включить опционально:
| Название инструмента | Функция | Пример | Статус по умолчанию |
|---|---|---|---|
| read | Чтение содержимого файла | ИИ читает src/main.ts, чтобы понять логику кода | Включено по умолчанию |
| write | Создание или перезапись файлов | ИИ создаёт новый файл или перезаписывает весь файл | Включено по умолчанию |
| edit | Точная замена содержимого в файле | ИИ изменяет несколько строк кода в функции | Включено по умолчанию |
| bash | Выполнять shell-команды | ИИ запускает тесты, устанавливает зависимости и запускает lint | Включено по умолчанию |
| grep | Поиск текста в файлах | ИИ ищет, какие файлы вызывают определённую функцию | Optional |
| найти | Поиск файлов по имени | ИИ находит все файлы *.test.ts | Optional |
| ls | Список содержимого каталога | ИИ просматривает структуру каталогов, чтобы найти модули | Optional |
Три инструмента только для чтения включаются с помощью параметра--toolsвручную, напримерpi --tools read,grep,find,ls。
Система расширений
Pi Agent расширяет свою функциональность следующими пятью способами:
| Метод расширения | Формат файла | Назначение | Сложность |
|---|---|---|---|
| Расширения | TypeScript（.ts） | Регистрация пользовательских инструментов, обработчиков событий, команд и компонентов пользовательского интерфейса | Требуется программирование |
| Навыки | Markdown（SKILL.md） | Предоставляет инструкции по рабочим процессам и скрипты для специализированных областей | Достаточно уметь писать на Markdown |
| Шаблоны промптов | Markdown（.md） | Переиспользуемые промпты с поддержкой параметров | Самый простой |
| Темы | JSON（.json） | Настройка цветовой схемы интерфейса терминала | Простая |
| Пакеты | Проекты npm/git | Упаковка и обмен четырьмя вышеуказанными типами ресурсов | По мере необходимости |
Как новичку, вам не нужно сразу понимать все методы расширения.
Начните с базового использования, а затем постепенно изучайте систему расширений по мере роста ваших потребностей.
Порядок загрузки файлов
Когда Pi Agent запускается, он автоматически загружает файлы инструкций проекта, позволяя вам определить ожидаемое поведение для ИИ:
| Уровень | Путь | Область действия | Приоритет |
|---|---|---|---|
| Глобальная конфигурация | ~/.pi/agent/AGENTS.md | Все проекты | Самый низкий, служит общей базовой основой |
| Конфигурация проекта | AGENTS.md или CLAUDE.md в каталоге проекта и родительских каталогах | Текущий проект | Наивысший, может переопределять глобальные инструкции |
Конфигурация уровня проекта загружается путем обхода вверх от родительского каталога и в конечном итоге объединяется с конфигурацией в текущем каталоге.
Если вы раньше использовали Claude Code, вы можете напрямую повторно использовать существующие файлы CLAUDE.md; Pi Agent автоматически распознает и загрузит их.
Сессии и ветки
Система сессий Pi Agent — одна из её самых отличительных особенностей.
Каждая беседа автоматически сохраняется как файл сессии, хранится в~/.pi/agent/sessions/каталоге.
Внутри сессии используют древовидную структуру: вы можете «ответвлять» новые направления исследования от любого исторического узла, не теряя предыдущие беседы.
Это очень полезно, когда нужно экспериментировать с разными подходами к реализации — каждую линию рассуждений можно сохранять независимо и возвращаться к ней в любое время.
Другие расширения