Объяснение конфигурации Pi Agent
Pi Agent использует конфигурационные файлы в формате JSON, поддерживая как глобальную конфигурацию, так и конфигурацию уровня проекта.
Расположение файла конфигурации
Pi Agent читает конфигурацию из двух фиксированных путей, и у них разные приоритеты.
| Путь к файлу | Область действия | Описание |
|---|---|---|
| ~/.pi/agent/settings.json | Глобальные (все проекты) | Общая конфигурация, применимая ко всем проектам |
| .pi/settings.json | Уровень проекта | Действует только для текущего проекта и переопределяет глобальную конфигурацию |
Вы можете напрямую редактировать JSON-файл или использовать команду/settingsв интерактивном режиме для изменения общих параметров.
Конфигурация модели и рассуждений
Следующие элементы конфигурации управляют тем, какой провайдер и модель используются по умолчанию, и как распределяется бюджет рассуждений.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| defaultProvider | string | - | Провайдер по умолчанию, например, "anthropic", "openai" |
| defaultModel | string | - | ID модели по умолчанию |
| defaultThinkingLevel | string | - | Уровень рассуждений по умолчанию, варианты: off / minimal / low / medium / high / xhigh / max |
| hideThinkingBlock | логическое значение | false | Скрывать процесс рассуждений ИИ по умолчанию |
| showCacheMissNotices | логическое значение | false | Показывать уведомления о промахах кэша |
| thinkingBudgets | объект | - | Настроить бюджет токенов для каждого уровня |
Пример настраиваемого бюджета рассуждений:
Пример
"thinkingBudgets": {
"minimal": 1024,
"low": 4096,
"medium": 10240,
"high": 32768
}
}
Следует отметить, что приведённые ниже значения предназначены только для демонстрации и не являются официальными значениями по умолчанию.
Значение каждого уровня и соответствующий ему пример бюджета приведены ниже:
| Уровень | Применимый сценарий | Пример бюджета |
|---|---|---|
| минимальный | Почти без рассуждений, цель — максимально быстрый ответ | 1024 |
| low | Простые вопросы и ответы, а также небольшие изменения | 4096 |
| средний | Выбор по умолчанию для повседневных задач программирования | 10240 |
| высокий | Сложный рефакторинг и диагностика сложных проблем | 32768 |
Конфигурация интерфейса и отображения
Следующие параметры конфигурации управляют внешним видом темы, макетом редактора и поведением при запуске.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| theme | string | "dark" | Название темы |
| externalEditor | string | Автоматически выбирается в зависимости от системы | Команда внешнего редактора, открываемого с помощью Ctrl+G |
| quietStartup | логическое значение | false | Скрыть информацию в заголовке при запуске |
| collapseChangelog | логическое значение | false | Показывать ли свёрнутый список изменений после обновлений |
| editorPaddingX | число | 0 | Горизонтальный отступ редактора (0-3) |
| outputPad | число | 1 | Горизонтальные отступы области сообщений (0 или 1) |
| autocompleteMaxVisible | число | 5 | Максимальное количество отображаемых вариантов автодополнения (3-20) |
Рекомендуемая конфигурация внешнего редактора для пользователей VS Code:
Пример
"externalEditor": "code --wait"
}
--waitПараметр гарантирует, что Pi Agent возобновит работу только после того, как VS Code закроет файл; в противном случае Pi Agent продолжит выполнение сразу после открытия редактора.
Конфигурация сети
Следующие параметры конфигурации управляют прокси, который Pi Agent использует при доступе к API моделей.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| httpProxy | string | - | URL HTTP-прокси (только для глобальной конфигурации) |
Настройка прокси (для сред, таких как материковый Китай, где требуется прокси для доступа к API):
Пример
"httpProxy": "http://127.0.0.1:7890"
}
Конфигурация сжатия контекста
Когда контекст приближается к своему лимиту, Pi Agent автоматически сжимает исторические сообщения. Эти настройки управляют тем, когда запускается сжатие и что сохраняется.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| compaction.enabled | логическое значение | истина | Включить автоматическое сжатие |
| compaction.reserveTokens | число | 16384 | Токены, зарезервированные для ответа LLM |
| compaction.keepRecentTokens | число | 20000 | Количество последних токенов, сохраняемых несжатыми |
Конфигурация повторных попыток
Следующие элементы конфигурации определяют поведение автоматических повторных попыток после сбоев запросов, включая количество повторов и интервал отсрочки.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| retry.enabled | логическое значение | истина | Включить автоматические повторные попытки |
| retry.maxRetries | число | 3 | Максимальное количество повторных попыток |
| retry.baseDelayMs | число | 2000 | Базовая задержка повторной попытки (миллисекунды), экспоненциальная задержка: 2s, 4s, 8s |
| retry.provider.timeoutMs | число | Значение по умолчанию SDK | Тайм-аут запроса (миллисекунды) |
| retry.provider.maxRetries | число | 0 | Количество повторных попыток на уровне провайдера |
Рекомендуется оставлятьretry.provider.maxRetriesего равным 0, если только вам действительно не нужны повторы на уровне провайдера.
Установка значения больше 0 может привести к тому, что повторы на уровне SDK будут блокировать Pi Agent при превышении лимитов использования, вместо того чтобы позволить механизму повторных попыток Pi Agent обработать это.
Конфигурация доставки сообщений
Следующие элементы конфигурации управляют тем, когда и как сообщения, которые вы вставляете в диалог, отправляются модели.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| steeringMode | string | "one-at-a-time" | Стратегия отправки управляющих сообщений: "all" или "one-at-a-time" |
| followUpMode | string | "one-at-a-time" | Стратегия отправки последующих сообщений |
| transport | string | "auto" | Протокол передачи: "sse", "websocket", "websocket-cached", "auto" |
Конфигурация терминала и изображений
Следующие элементы конфигурации управляют тем, как изображения отображаются в терминале и как они обрабатываются перед отправкой модели.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| terminal.showImages | логическое значение | истина | Отображать изображения в терминале |
| terminal.imageWidthCells | число | 60 | Ширина встроенного изображения (ячейки терминала) |
| images.autoResize | логическое значение | истина | Масштабировать изображения до размеров в пределах 2000x2000 |
| images.blockImages | логическое значение | false | Блокировать отправку всех изображений в LLM |
Конфигурация оболочки
Следующие элементы конфигурации управляют оболочкой и префиксом команды, используемыми, когда Pi Agent выполняет команды bash.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| shellPath | string | - | Пользовательский путь к оболочке |
| shellCommandPrefix | string | - | Префикс для каждой команды bash |
| npmCommand | string[] | - | Пользовательская команда для операций с пакетами npm |
Пример использования таких инструментов, как mise или asdf, для управления версией Node.js:
Пример
"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
Конфигурация циклического переключения моделей
Следующие элементы конфигурации управляют тем, какие модели можно увидеть при циклическом переключении моделей с помощью Ctrl+P.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| enabledModels | string[] | - | Список моделей, доступных при циклическом переключении с Ctrl+P, поддерживает подстановочные знаки |
Пример
"enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}
Правила слияния конфигурации
Конфигурация проекта (.pi/settings.json) переопределяет глобальную конфигурацию (~/.pi/agent/settings.json).
Вложенные объекты используютслияние, а не замену. Следующий пример иллюстрирует это.
Глобальный файл конфигурации ~/.pi/agent/settings.json:
Пример
"theme": "dark",
"compaction": { "enabled": true, "reserveTokens": 16384 }
}
Файл конфигурации проекта .pi/settings.json:
Пример
"compaction": { "reserveTokens": 8192 }
}
В эффективной конфигурации после слияния theme принимает глобальное значение dark, compaction.enabled принимает глобальное значение true, а compaction.reserveTokens переопределяется конфигурацией проекта на 8192.
Иными словами, конфигурация проекта переопределяет только те поля, которые она явно объявляет, а все остальные поля продолжают использовать глобальную конфигурацию.
Пример полной конфигурации
Ниже приведён типичный глобальный файл конфигурации:
Пример
"defaultProvider": "anthropic",
"defaultModel": "claude-sonnet-4-20250514",
"defaultThinkingLevel": "medium",
"theme": "dark",
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
},
"retry": {
"enabled": true,
"maxRetries": 3
},
"enabledModels": ["claude-*", "gpt-4o"],
"warnings": {
"anthropicExtraUsage": true
},
"packages": ["pi-skills"]
}
warnings.anthropicExtraUsage — это логическое значение, по умолчанию равное true.
Оно выдаёт напоминание, когда аутентификация подписки Anthropic может повлечь дополнительное платное использование.
packages — это конфигурация фильтра установленных пакетов, используемая для указания, какие пакеты загружать.
Другие расширения