Управление контекстом Pi Agent
Управление контекстом — ключевой навык для эффективного использования Pi Agent.
В этой главе объясняется, как управлять поведением ИИ с помощью файлов окружения и как управлять контекстом беседы.
Обзор файлов контекста
Pi Agent автоматически загружает файлы инструкций проекта при запуске, позволяя ИИ понять соглашения, команды и предпочтения вашего проекта.
Эти файлы сообщают ИИ, «как работать в этом проекте».
AGENTS.md / CLAUDE.md
Это самые важные файлы контекста для Pi Agent, загружаемые в следующем порядке:
- ~/.pi/agent/AGENTS.md- Глобальные инструкции, действующие для всех проектов
- Пройдите вверх по родительским каталогам от текущего каталога в поисках AGENTS.md или CLAUDE.md
- AGENTS.md или CLAUDE.md в текущем каталоге
Ниже представленAGENTS.md— полный пример, размещённый в корневом каталоге проекта:
Пример
## Стандарты кода
- Весь код использует строгий режим TypeScript
- Функции должны иметь аннотации типа возвращаемого значения
- Используйте ESLint и Prettier для поддержания единообразного стиля кода
## Рабочий процесс
- Запускайте `npm run check` для проверки после изменений кода
- Запускайте `npm test` перед коммитом, чтобы убедиться, что тесты проходят
- Не запускайте миграции производственной базы данных напрямую на локальной машине
## Заметки по безопасности
- Не записывайте API-ключи или пароли в код
- Используйте переменные окружения для чувствительной конфигурации
## Стиль ответов
- Отвечайте кратко и не объясняйте очевидный код слишком подробно
- При возникновении проблем сначала предложите исправление, затем объясните причину
После обновления AGENTS.md используйте команду/reloadдля горячей перезагрузки, перезапускать Pi Agent не нужно.
Если у вас есть и AGENTS.md, и CLAUDE.md, Pi Agent сначала загрузит AGENTS.md.
Если вы ранее использовали Claude Code, вы можете напрямую переиспользовать существующий CLAUDE.md.
Если в каталоге существует AGENTS.override.md, он будет загружен вместо AGENTS.md и CLAUDE.md из этого каталога.
Чтобы отключить загрузку контекстных файлов, используйте аргумент командной строки:
$ pi --no-context-files $ pi -nc # 短形式
SYSTEM.md
SYSTEM.md используется для полной замены системного промпта Pi Agent по умолчанию. Если вы хотите только добавить содержимое, используйте вместо этого APPEND_SYSTEM.md.
Оба имеют глобальный и проектный уровни; пути и эффекты приведены ниже:
| Файл | Уровень | Эффект |
|---|---|---|
| ~/.pi/agent/SYSTEM.md | Глобальный | Заменяет системный промпт по умолчанию |
| Корень проекта/.pi/SYSTEM.md | Проект | Заменяет системный промпт по умолчанию |
| ~/.pi/agent/APPEND_SYSTEM.md | Глобальный | Добавляется после системного промпта по умолчанию |
| Корень проекта/.pi/APPEND_SYSTEM.md | Проект | Добавляется после системного промпта по умолчанию |
В большинстве случаев вам не нужно изменять системный промпт.
AGENTS.md уже может покрывать подавляющее большинство потребностей в кастомизации.
SYSTEM.md подходит для сценариев, требующих глубокой кастомизации поведения ИИ; неправильные изменения могут повлиять на работу ИИ.
Сжатие контекста
Когда разговор становится очень длинным, контекстное окно ИИ постепенно заполняется.
Pi Agent решает это с помощью сжатия контекста — он автоматически суммирует содержимое предыдущего разговора в краткое резюме, освобождая место в контексте.
Автоматическое уплотнение
По умолчанию Pi Agent автоматически запускает сжатие, когда контекст приближается к лимиту модели.
Поведение сжатия~/.pi/agent/settings.jsonуправляется конфигурацией сжатия в:
Пример
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| compaction.enabled | логическое значение | истина | Включать ли автоматическое сжатие |
| compaction.reserveTokens | число | 16384 | Количество токенов, зарезервированных для ответов LLM |
| compaction.keepRecentTokens | число | 20000 | Количество последних токенов, сохраняемых несжатыми |
Условие срабатывания — когда токены контекста превышают доступное пространство после вычитания reserveTokens из contextWindow.
Проверка выполняется после завершения каждого выполнения инструмента и перед отправкой следующего запроса пользователя.
Ручное сжатие
Вы также можете в любой момент вручную запустить сжатие:
/compact
При сжатии вы можете добавить пользовательские инструкции, чтобы указать ИИ, на чём сосредоточиться при составлении сводки:
/compact 重点关注错误修复和 API 变更
Сжатие необратимо только для текущего контекста разговора.
Сжатые исходные сообщения по-прежнему полностью сохраняются в файле сессии. Используйте /tree, чтобы вернуться к узлу перед сжатием и получить детали.
Если вы хотите сохранить полную резервную копию перед сжатием, рекомендуется /clone.
/clone полностью копирует текущую активную ветку в новый файл сессии; подходит для резервного копирования перед сжатием.
/fork начинает только с определённого исторического сообщения пользователя, и содержимое после него не будет перенесено в новую сессию.
Отображение процесса вывода
Модели, поддерживающие вывод рассуждений, будут думать перед ответом.
Вы можете управлять отображением процесса рассуждений с помощью следующих настроек:
| Настройка | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| hideThinkingBlock | логическое значение | false | Скрыть процесс рассуждений и показывать только окончательный ответ |
| showCacheMissNotices | логическое значение | false | Показывать подсказки о промахах кэша, а также подсказки об использовании токенов, создаваемые при сжатии и сводках ветвей |
ИспользуйтеCtrl+T, чтобы в любой момент во время разговора переключать отображение/скрытие процесса рассуждений.
Горячая перезагрузка (/reload)
Нужно ли перезапускать после изменения конфигурации, зависит от того, что вы изменили.
В таблице ниже показано, как вступают в силу распространённые изменения. Для пунктов с пометкой "Нет", просто выполните /reload:
| Изменяемый пункт | Требуется перезапуск? | Описание |
|---|---|---|
| AGENTS.md или CLAUDE.md (файлы контекста) | нет | Перезагрузить сразу после выполнения /reload |
| Расширения | нет | Перезагрузить сразу после выполнения /reload |
| Навыки | нет | Перезагрузить сразу после выполнения /reload |
| Шаблоны промптов | нет | Перезагрузить сразу после выполнения /reload |
| Файлы темы | нет | Перезагрузить сразу после выполнения /reload |
| Настройка сочетаний клавиш | нет | Перезагрузить сразу после выполнения /reload |
| Некоторые настройки в ~/.pi/agent/settings.json | Да | Часть конфигурации считывается один раз при запуске |
| Недавно установленные пакеты расширений | Да | Зависимости пакетов разрешаются при запуске |
| Учётные данные auth.json | Да | Учётные данные загружаются при запуске |
Просмотр использования контекста
Нижняя строка состояния отображает использование токенов и стоимость текущего контекста в реальном времени.
Используйте/sessionкоманду, чтобы просмотреть более подробную информацию:
/session
Пример вывода:
Session file: ~/.pi/agent/sessions/--Users-example-projects-example-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl Session ID: abc123-def456 Messages: 42 Tokens: 85,432 Cost: $0.52 Current model: claude-sonnet-4-20250514Другие расширения