Управление контекстом Pi Agent

Управление контекстом — ключевой навык для эффективного использования Pi Agent.

В этой главе объясняется, как управлять поведением ИИ с помощью файлов окружения и как управлять контекстом беседы.


Обзор файлов контекста

Pi Agent автоматически загружает файлы инструкций проекта при запуске, позволяя ИИ понять соглашения, команды и предпочтения вашего проекта.

Эти файлы сообщают ИИ, «как работать в этом проекте».


AGENTS.md / CLAUDE.md

Это самые важные файлы контекста для Pi Agent, загружаемые в следующем порядке:

  1. ~/.pi/agent/AGENTS.md- Глобальные инструкции, действующие для всех проектов
  2. Пройдите вверх по родительским каталогам от текущего каталога в поисках AGENTS.md или CLAUDE.md
  3. 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
Другие расширения