Разбор дизайна harness в Pi

Pi (npm-пакет @earendil-works/pi-coding-agent) называет себя «minimal agent harness» — минималистичным harness для agent. Эту формулировку стоит разобрать: Pi не называет себя «самым мощным coding agent» или «лучшим инструментом AI-программирования», а жёстко привязывает своё позиционирование к слову harness.

В этой статье мы разберём Pi через фреймворк пяти подсистем курса — инструкции, инструменты, среда, состояние и обратная связь — и посмотрим, чем его философия принципиально отличается от Claude Code и Codex. Сразу дадим ответ: философия Pi — «минимальное ядро + программируемые расширения»; инженерия контекста выходит за пределы системного prompt, а менять harness предлагается пользователю (и даже самому Pi), вместо того чтобы Pi решал за вас, каким должен быть harness.

Позиционирование в одном предложении

Pi — минималистичное ядро: официальное позиционирование намеренно делает ядро небольшим и возвращает вам право принимать решения. На главной странице pi.dev это сформулировано так: «Ask Pi to build what you want, or install a package that does it your way». Pi разделяет harness на четыре настраиваемых уровня:

• Extensions: TypeScript-hooks, подключаемые к событиям жизненного цикла Pi; программируемая поверхность уровня runtime.
• Skills: загружаемые по требованию пакеты возможностей с инструкциями и инструментами; progressive disclosure.
• Prompt templates: повторно используемые Markdown-prompts, разворачиваемые вводом /name.
• Themes: внешний вид TUI.

Само такое разделение на уровни уже является дизайном harness: то, что увидит модель и когда именно она это увидит, полностью определяется правилами и extensions, а не жёстко зашивается в ядро.

Основной цикл

Как и любой coding agent, Pi в своей основе представляет собой цикл while: «рассуждение → выполнение инструмента → наблюдение → новое рассуждение». Примечателен не сам цикл, а то, как Pi работает с его внешним слоем: управление контекстом расширяется от внутренней «compaction» до внешнего «контроля» цикла.

Runtime Pi предоставляет программируемый интерфейс. В разделе Programmatic Usage исходного README, помимо интерактивного TUI, описаны скриптовые режимы печати/JSON, RPC-протокол и встраивание через SDK. Поэтому одним и тем же harness можно управлять вручную, шаг за шагом, либо автоматически — из CI/CD или другой программы. Это необходимое условие перехода «от ручного управления к автоматическому циклу» из лекции 13 об инженерии циклов: если harness допускает только интерактивное управление человеком, он никогда не сможет перейти к автоматическому циклу.

Подсистема инструкций: AGENTS.md и SYSTEM.md

Pi сдержанно работает с «инструкциями», но выстраивает чёткую иерархию:

• AGENTS.md: раздел Project Context Files исходного README явно задаёт порядок загрузки: глобальный ~/.pi/agent/AGENTS.md → последовательный обход родительских каталогов вверх → ./AGENTS.md в текущем каталоге (CLAUDE.md также поддерживается). Так реализуется принцип «репозиторий — источник истины»: инструкции находятся в файлах, а не в напоминаниях из окна чата.
• SYSTEM.md: в официальной документации pi.dev сказано, что стандартный системный prompt можно заменить (replace) или дополнить (append) для конкретного проекта. Это единственная официальная точка входа, через которую Pi позволяет менять «системный prompt», и одновременно его слой «самоописания среды».

Pi подчёркивает, что его системный prompt минималистичен. За этим стоит явный компромисс: ядро не заполняется длинными правилами вида «если… то…»; вместо этого предоставляются точки расширения, а правила появляются в виде skills и extensions только тогда, когда нужны. Это напрямую перекликается с лекцией 4 «Почему один гигантский файл инструкций не работает»: сочетание «минимальное ядро + разделение файлов + загрузка по требованию» естественным образом позволяет Pi избежать проблемы гигантского файла инструкций.

Состояние и контекст: наиболее детально проработанная часть Pi

Инженерия контекста в Pi заслуживает особого внимания: такие понятия курса, как «непрерывность контекста» и «предотвращение деградации контекста», здесь воплощены в конкретных механизмах.

1. Программируемая compaction. При приближении к пределу контекста старые сообщения автоматически сворачиваются в summary. В официальной документации pi.dev говорится, что сама стратегия compaction настраивается: с помощью extensions можно реализовать тематическую compaction, учитывающее код summary или даже поручить создание summary другой модели. В исходном README также описаны детали стандартного механизма: автоматическая compaction запускается в двух случаях — при восстановлении после переполнения контекста или при превышении порога сохранения; точка разбиения сохраняет примерно 20 тысяч последних token, а предшествующие сообщения сворачиваются в «context handoff» и далее проходят последовательную цепную compaction. Иными словами, Pi считает способ compaction не неизменяемой константой, а частью harness.

2. Динамический контекст (Dynamic context). В официальной документации pi.dev сказано, что перед каждым раундом рассуждения extensions могут внедрять сообщения, фильтровать историю сообщений, реализовывать RAG и строить долговременную память. Это следующий шаг после подхода «выполнить compaction, когда контекст заполнится»: вы решаете, что попадёт в окно, ещё до входа контекста в него. Pi переносит на поверхность extensions сразу две задачи курса — «сделать работу agent наблюдаемой и отлаживаемой» и «сохранять непрерывность контекста».

3. Дерево session (Session tree). На главной странице pi.dev прямо сказано: «sessions are stored as trees»; команда /tree позволяет вернуться к любой исторической точке и продолжить работу, а все ветви сохраняются в одном файле. Это решает многократно подчёркнутую в курсе проблему «разрыва контекста между session» не жёстким склеиванием через summary, а структурированным воспроизведением истории. Ветви можно экспортировать в HTML или загрузить как gist для публикации — заодно решается и задача наблюдаемости.

Подсистема инструментов: skills и extensions

«Инструменты» Pi разделены на два уровня:

• Skills: раздел Skills исходного README даёт точное определение — «self-contained capability packages that the agent loads on-demand», то есть автономные пакеты возможностей с инструкциями и инструментами, загружаемые по требованию и соответствующие стандарту Agent Skills. Благодаря progressive disclosure подробности skill попадают в контекст только при срабатывании и не переполняют prompt cache. Это дизайн harness с точки зрения стоимости: за каждый дополнительный token в контексте приходится платить при каждом рассуждении; загружать skills по требованию — ещё одна форма принципа «дайте карту, а не инструкцию».
• Extensions: TypeScript-hooks, подключаемые к встроенным событиям жизненного цикла. В разделе Hooks исходного README приведены официальные примеры применения: перехват опасных команд (шлюз permissions), checkpoint состояния кода при переключении задачи, защита путей (например, запрет записи в .env), изменение вывода инструмента до передачи модели, а также внедрение внешних сообщений (из наблюдателя файлов, Webhook или CI) для пробуждения agent. Эти hooks API также экспортируются из @mariozechner/pi-coding-agent/hooks. Сообщественный harness pi-agent-harness дополнительно оборачивает поверхность hooks в готовые extensions: skill-router, session-summary, extract-patterns, telemetry и другие.

Extensions — главное дизайнерское решение Pi: пользователь получает не несколько переключателей, а всю поверхность внутренних событий runtime. Хотите добавить память? Внедрите её в agent/pre-step. Хотите записывать поведение? Подпишитесь на события session. Хотите изменить запрос модели? Подключитесь к agent/request. Можно даже поручить Pi изменить собственный harness — это гораздо ближе к определению «программируемого harness», чем любые параметры конфигурации.

Обратная связь и верификация: даже «обучение» становится частью harness

В самом Pi нет обязательного тестового шлюза — команды верификации пользователь должен указать в AGENTS.md. Но сообщественный harness pi-agent-harness структурирует «цикл обратной связи» посредством extensions, а раздел Hooks официального README описывает основу для подобных механизмов:

• session-summary (extension в pi-agent-harness): поддерживает скользящие записи в PROGRESS.md — это подсистема состояния из курса, отслеживающая прогресс длительных задач.
• extract-patterns (extension в pi-agent-harness): собирает из session кандидатов на извлечённые уроки и сохраняет их в LESSONS.md, превращая правило «перед завершением каждой session подготовить handoff» из договорённости в механизм.
• telemetry (extension в pi-agent-harness): записывает расход token, стоимость и другие показатели — наблюдаемость.

Тот же репозиторий сообщества дополнительно подтверждает этот паттерн: VISION.md (цель), PROGRESS.md (прогресс), LESSONS.md (опыт), STANDARDS.md (стандарты) — всё это Markdown-файлы с сохранением данных между session. Это в точности рекомендованная курсом схема «репозиторий как источник истины + файл прогресса + механизм handoff», превращённая механизмом extensions Pi в готовый к использованию слой.

Сопоставление с фреймворком курса

Оценим Pi по пяти подсистемам курса (субъективно, для сравнения):

Подсистема	Реализация Pi	Оценка
Инструкции	Иерархическая загрузка AGENTS.md + SYSTEM.md	Чёткая иерархия, но сами правила должен писать пользователь
Инструменты	Загрузка skills по требованию + hooks полного жизненного цикла extensions	Очень мощная реализация, превращающая систему инструментов в программируемую поверхность
Среда	SYSTEM.md для самоописания среды; среда runtime объявляется пользователем в AGENTS.md	Механизм открыт, но воспроизводимость зависит от описания пользователя
Состояние	Дерево session + настраиваемая compaction + PROGRESS.md	Очень мощная реализация; непрерывность между session и восстанавливаемость — её основа
Обратная связь	Команды верификации определяет пользователь; механизированные session-summary / extract-patterns	Механизм предоставлен, содержимое задаёт пользователь

Выбор Pi резко контрастирует с Claude Code и Codex: Claude Code встраивает «память, permissions и subagent» в ядро и предоставляет их из коробки; Codex делает стандартными «соглашения репозитория и изоляцию среды»; Pi предпочитает ничего не решать за вас, превращая право выбора в точки расширения. Цена этого решения — необходимость писать extensions самостоятельно либо устанавливать чужие пакеты.

Дизайнерские решения, которые стоит перенять

1. Сделайте стратегию compaction подключаемой. Способ compaction контекста в вашем harness должен быть не жёстко заданным параметром, а заменяемым интерфейсом стратегии.
2. Используйте дерево session вместо жёсткого summary. Восстановление между session не обязательно строить на «summary предыдущего раунда»: структурированное воспроизведение истории часто оказывается более надёжной подсистемой состояния.
3. Учитывайте prompt cache. Загружайте skills по требованию и не помещайте все правила в системный prompt сразу: это одновременно инженерия контекста и инженерия стоимости.
4. Позвольте agent изменять собственный harness. Если поверхность расширения harness достаточно открыта, оптимизацию поведения agent можно частично автоматизировать силами самого agent.

Источники (оригинальные материалы / исходный код)

Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:

• Официальный сайт pi.dev: исходная формулировка позиционирования «Ask Pi to build what you want, or install a package that does it your way», четыре настраиваемых уровня и дерево session («sessions are stored as trees», /tree, сохранение в одном файле, экспорт HTML и публикация gist).
  https://pi.dev/
• Официальная документация pi.dev · Sessions: подключаемая compaction (topic-based / code-aware / другая модель для summary), автоматическая compaction и динамическое внедрение контекста.
  https://pi.dev/docs/usage/sessions
• Официальная документация pi.dev · Extensions: extensions могут перед каждым раундом рассуждения внедрять сообщения, фильтровать историю, выполнять RAG и строить долговременную память.
  https://pi.dev/docs/usage/extensions
• Официальная документация pi.dev · Project Context: семантика replace / append для SYSTEM.md.
  https://pi.dev/docs/usage/project-context
• README исходного кода Pi Coding Agent (badlogic/pi-mono): трёхуровневый порядок загрузки AGENTS.md (глобальный → родительские каталоги → текущий каталог), условия запуска /compact и автоматической compaction, точка разбиения в 20 тысяч token, загрузка Skills по требованию и стандарт Agent Skills, жизненный цикл Hooks с четырьмя официальными примерами, Programmatic Usage (JSON / RPC / SDK).
  https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
• Репозиторий сообщества pi-agent-harness: extensions skill-router / session-summary / extract-patterns / telemetry и система файлов VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.
  https://github.com/LabidySabidy/pi-agent-harness

Связанные лекции: лекция 2 «Что такое harness на самом деле» ｜ лекция 5 «Как сохранять непрерывность контекста в задачах между session» ｜ лекция 13 «От ручного управления к автоматическому циклу»