Руководство агента Pi Coding: Основы, Пакеты и Песочница

Итог

Pi — это минимальная, расширяемая оболочка для кодирования в терминале, а не универсальная автономная платформа. Его ядро предоставляет файл модели и инструменты оболочки; расширения и пакеты добавляют функциональность как отдельно доверяемое программное обеспечение. Доверие к проекту полезно для контроля локальной загрузки проекта, но это не изоляция: для недоверенной или автономной работы используйте контейнер, виртуальную машину или песочницу с контролируемой политикой.

Проверено 1 сентября 2026 года. Pi 0.84.4 — это терминальная кодирующая оболочка, разработанная для того, чтобы сохранить своё ядро маленьким и переместить настройку в расширения TypeScript, навыки, шаблоны подсказок, темы и пакеты Pi. Отличие важно: расширение или пакет не является функцией, включённой в основное бинарное ядро. Это дополнительный код и инструкции, которым вы решаете доверять.Документация Pi npm пакет

Pi не заменяет все смежные системы. Он наиболее эффективен, когда вы хотите иметь компактный цикл кодирующего агента, который можно расширять целенаправленно. Сам по себе он не является широкой платформой автоматизации для разных каналов, долговременной средой выполнения или песочницей.

Установите поддерживаемый пакет, а затем удалите его чисто

Текущий пакет и пространство имён точные:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
пи --version

--ignore-scripts отключает сценарии жизненного цикла зависимостей во время этой установки; Pi указывает, что для обычной установки npm сценарии установки не требуются. Не копируйте старые @mariozechner команды: поддерживаемый пакет — @earendil-works/pi-coding-agent.Pi quick start

Используйте соответствующую команду менеджера пакетов для удаления глобальной установки npm:

npm удалить -g @earendil-works/pi-coding-agent
команда -v пи || true

Если вы устанавливали через pnpm, Yarn или Bun, используйте соответствующую команду удаления глобальной установки этого менеджера. Удаление CLI не автоматически проверяет или удаляет конфигурацию Pi, сессии или отдельные установленные пакеты; проверьте ~/.pi/agent перед удалением всего, что нужно сохранить.Pi quick start

Для обратимой оценки избегайте глобальной установки полностью:

mkdir -p /tmp/pi-eval/tool
npm install --prefix /tmp/pi-eval/tool --ignore-scripts \
  @earendil-works/pi-coding-agent@0.84.4
/tmp/pi-eval/tool/node_modules/.bin/pi --version

Это проверка установщика, а не проверка безопасности. Проверьте распакованный пакет, его дерево зависимостей и любой пакет, который вы добавите позже, прежде чем дать ему доступ к реальному репозиторию или учетным данным.

К какому слою принадлежит

Слой	Что это такое	Что это не доказывает
Пи-ядро	CLI-агент кодирования, стандартный круг инструментов, интерактивный интерфейс, режим печати/JSON, режим RPC и SDK.	Что ответ модели безопасен, корректен или сдерживается.
Основные инструменты	По умолчанию `read`, `write`, `edit`, и `bash` инструменты, доступные для выбранной модели.	Файловая система или граница процесса с наименьшими привилегиями.
Навыки и шаблоны подсказок	Многоразовые инструкции и подсказки загружаются по запросу.	Инструкции, следующие модели, не могут требовать рискованных действий.
Расширения	Модули TypeScript, которые могут добавлять инструменты, команды, события и пользовательский интерфейс.	Этот добавленный код имеет меньше доступа, чем Pi.
Пакеты Pi	npm, Git или локальные наборы расширений, навыков, подсказок и тем.	Что популярный пакет был проверен или безопасен.
Провайдер	Вход в подписку, API-ключ или локальный маршрутизатор, который поставляет модель.	Что выбранные как контекст файлы хостов остаются локальными.
Песочница	Контейнер, виртуальная машина, микро-ВМ или граница, контролируемая политикой, вокруг процесса или инструментов.	Что только доверие на уровне приложения к проекту содержит рабочую нагрузку.

Собственное руководство по безопасности Pi ясно: встроенные инструменты и расширения работают с разрешениями процесса, который запускает Pi. Доверие проекту определяет, будут ли загружаться ресурсы, локальные для проекта; это не песочница и не ограничивает то, что работающая модель может попросить инструменты сделать.Безопасность Pi

Ядро: намеренно небольшое

Сеанс Pi по умолчанию позволяет модели читать файлы, записывать файлы, редактировать файлы и выполнять команды оболочки. Проходите аутентификацию интерактивно с помощью /login, или настройте поддерживаемый API-ключ перед началом сеанса. Пакет документирует поставщиков подписки, включая Anthropic, OpenAI/Codex и GitHub Copilot, а также длинный список поставщиков API-ключей и маршрут llama.cpp.Поставщики Pi

Ядро имеет несколько способов работы:

Режим	Используйте его для
Интерактивный TUI	Контролируемая задача репозитория, выбор модели, навигация по сессии и явная проверка человеком.
Печать или JSON	Одноразовый запуск или дружественный к автоматизации запуск, который выводит текст или структурированные события.
RPC	Интеграция процесса через stdin/stdout JSONL.
SDK	Встраивание возможностей агента Pi в приложение Node.js.

Эти режимы изменяют форму интеграции, а не границу доверия. Неинтерактивный вызов может быть удобен в CI или скрипте, но он должен получать учетные данные провайдера и должен выполняться только в том же явном контейнере, который вы бы использовали для интерактивного агента.Документация Pi

Изменения в версии 0.84.4

Выпуск v0.84.4 от 28 августа 2026 года добавляет возможность переопределения возможностей терминала для гиперссылок, изображений и truecolor; ui_prompt_start и ui_prompt_end события расширений; RPC clear_queue операция; и экспериментальная deepseek-v4-flash-vision-exp поддержка. Также исправляет важные проблемы с сессией, порядком результатов инструментов и поведением компактификации, включая проблему с возобновленной JSONL, отсутствующей завершающей новой строкой, и время компактификации при большом выводе инструментов.Выпуск Pi v0.84.4

Рассматривайте эту информацию о выпуске как специфичную для версии. Проверьте pi --version перед тем, как полагаться на флажок, поведение инструмента или исправление с этой страницы.

Пакеты — это отдельное программное обеспечение

Пакеты Pi могут включать расширения, навыки, шаблоны подсказок и темы. Pi поддерживает источники npm, Git и локальные пути; установка или удаление пакета обычно изменяет либо глобальный ~/.pi/agent/settings.json , либо проектный .pi/settings.json. Пакет проекта может быть установлен автоматически после того, как проект будет доверен.Документация по пакету Pi

Эта удобство создает серьезное ограничение: документация пакетов Pi утверждает, что пакеты работают с полным доступом к системе, расширения выполняют произвольный код, а навыки могут давать модели команды на выполнение исполняемых файлов. Просмотрите исходный код перед установкой стороннего пакета.Документация по пакету Pi

Используйте краткий контрольный список перед добавлением:

Зафиксируйте имя пакета, версию, издателя, репозиторий источника, лицензию и дату проверки.
Читать package.json, манифест Pi, входное расширение, зависимости и поведение при установке/обновлении.
Определите доступ к файловой системе, запуск дочерних процессов, сетевые вызовы, хранилища учетных данных, серверы MCP и любое обнаружение конфигурации хоста.
Закрепите версию npm или ревизию Git для оценки.
Пробуйте только в изолированной временной рабочей среде, затем протестируйте его удаление и различия в настройках.
Не описывайте поведение пакета как поведение ядра Pi.

Панель проверенного пакета: `pi-mcp-adapter` является сторонним

pi-mcp-adapter является сторонний пакетом Pi, а не ядром Pi. На дату проверки каталог Pi содержал версию 2.31.0, опубликованную 28 августа 2026 года, как пакет расширения/навыка с 12 зависимостями и четырьмя зависимостями коллег. Его заявленный манифест загружает ./index.ts и ./skills; его заявленная цель — токен-эффективный адаптер MCP.Запись каталога Pi

Его репозиторий утверждает, что он может читать стандартные файлы конфигурации MCP и может запускать серверы MCP по требованию, когда используется инструмент. Это может быть полезно, но также расширяет поверхность доверия до обнаружения конфигурации, команд сервера, конечных точек MCP, потоков OAuth и их учетных данных. Собственная документация пакета говорит, что обнаружение конфигурации, специфичной для хоста, по умолчанию выключено, и что он не запускает команды с обнаруженных конфигураций хоста без уведомления; убедитесь в этом поведении, проверив исходный код, который вы устанавливаете, а не только эту статью.Репозиторий pi-mcp-adapter

Ограниченное тестирование использует временную загрузку расширения вместо постоянной установки:

пи -e npm:pi-mcp-adapter@2.31.0

Запускайте его только после проверки исходного кода и только в песочнице, которая не имеет реальных учетных данных MCP или широких монтирований хостов. Для постоянной установки используйте задокументированную команду пакета, затем проверьте настройки и удаление:

пи install npm:pi-mcp-adapter@2.31.0
пи список
пи удалить npm:pi-mcp-adapter
пи список

Загрузки или рейтинг каталога пакетов являются сигналами популярности, а не аудитом безопасности. 1 сентября 2026 года каталог показал pi-mcp-adapter, pi-web-access, и pi-subagents среди записей с высоким числом загрузок; это не переносит поведение или свойства безопасности какого-либо пакета на ядро Pi.Каталог пакетов Pi

Доверие к проекту является входным фильтром, а не средством изоляции

Pi ищет локальные настройки и ресурсы проекта, такие как .pi/extensions, .pi/skills, и проект .agents/skills. Первая интерактивная сессия обычно спрашивает, следует ли доверять этим ресурсам; неинтерактивные режимы используют настроенный по умолчанию вариант, если только флаг однократного одобрения не переопределяет его. Контекстные файлы, такие как AGENTS.md и CLAUDE.md , по-прежнему загружаются, если загрузка контекста не отключена.Безопасность Pi

Это защищает от ситуации, когда репозиторий тайно изменяет настройки или расширения Pi до вашего одобрения. Это не делает безопасными текст из недоверенного репозитория, инъекции подсказок, сгенерированный вывод, команды оболочки или вывод модели. Начинайте работу с неизвестными репозиториями без доверия к проекту, вручную проверяйте их контекстные файлы и используйте изоляцию на уровне операционной системы для любой задачи, которая будет выполнять инструменты.

Выберите реальный шаблон изоляции.

Pi документирует три основных шаблона:

Шаблон	Граница	Важное предупреждение
Расширение Gondolin	Перенаправляет встроенные инструменты и `!` выполняет команды в локальной микро-VM, в то время как сам Pi остаётся на хосте.	Другие пользовательские расширения по-прежнему выполняются там, где работает Pi, если только они сами не делегируют выполнение.
Обычный Docker	Запускает весь процесс Pi в контейнере.	Записываемое подключение монтирования всё ещё изменяет файлы на хосте; API-ключи попадают в контейнер.
OpenShell	Запускает весь процесс Pi в песочнице с управлением политиками.	Требуется активный шлюз и настройка политик.

Для первой задачи лучше скопировать disposable-репозиторий в контейнер или удалённую песочницу, а не монтировать ценный хостовый репозиторий. Монтируйте только то, что нужно задаче, сохраняйте хост ~/.pi/agent выйдите из песочницы, не передавайте рабочие учетные данные и ограничьте исходящий трафик конечной точкой модели и явно требуемыми реестрами. Документация по безопасности Pi также предупреждает, что подключение для чтения/записи дает песочнице прямую возможность изменять файлы хоста.Контейнеризация Pi Безопасность Pi

Pi, Hermes и Herdr: смежные слои, а не замены

Слой продукта	Лучшее описание	Не делайте выводов
Pi	Минимальный, расширяемый каркас для программирования выбранной модели и задачи репозитория.	Что он предоставляет долговечную многопользовательскую операционную платформу или песочницу.
Гермес	Более широкая платформа автономных агентов с профилями, навыками, обменом сообщениями, фоновыми заданиями и множеством интерфейсов взаимодействия.	Что профиль Hermes или настройка разрешений сами по себе обеспечивают контейнирование на уровне ОС.
Herdr	Устойчивая терминальная среда выполнения и оркестровочный слой для длительной работы агентов.	То, что это такой же минимальный каркас для кодирования, как и Pi.

Команда может использовать Pi как узконаправленный каркас для кодирования внутри отдельно выбранной среды выполнения или системы автоматизации. Правильное сравнение, следовательно, слой за слоем: цикл задач, интерфейс расширений, сохранение/оркестрация, доступ к провайдерам и явная изоляция.

Финишная черта, достойная записи

Перед завершением оценки Pi сохраните:

версии Pi и пакетов, URL источников и дату проверки;
движок песочницы и его политику или аргументы Docker;
провайдера/модель, маршрут аутентификации, токен или денежную стоимость и время настройки;
точный запрос и исправления человеком;
запрошенный результат теста, git diff --check, список изменённых путей и финальная разница;
доказательство того, что попытка доступа к файловой системе вне разрешённой области была отклонена песочницей;
настройки установки/удаления пакета до и после; и
результат чистого завершения работы или перезагрузки, если рабочий процесс заявляет о поведении отсоединения/перезагрузки.

Сопроводительный урок предоставляет процедуру одноразового репозитория и настаивает на честной фиксации неудачного предварительного теста. Не заменяйте отсутствующие доказательства песочницы, провайдера или проверки пакета на обнадёживающее сообщение о завершении.

Источники

Запустите это в работу

Нарисуйте границу доверия вокруг каждого установленного пакета и каждой смонтированной директории, а не только вокруг исполняемого файла Pi.

Попробовать

Следуйте сопровождающему уроку первой задачи в песочнице на одноразовой копии после проверки наличия требуемого Docker или OpenShell.

Докажите, что это сработало

Храните вместе версию, источник пакета и версию, модель/провайдер, результат теста, разницу, результат отказа песочницы и результат удаления.

Где это может оплатить

Воспроизводимый, ограниченный рабочий процесс агента может стать более безопасной службой проверки кода или реализации.

Держите в поле зрения

Установите текущий пакет `@earendil-works/pi-coding-agent` с отключенными сценариями жизненного цикла npm; после завершения удалите тот же пакет с помощью npm.
В базовой версии Pi есть четыре стандартных инструмента модели: чтение, запись, редактирование и bash. Навыки, расширения, подсказки, темы и пакеты представляют собой отдельные слои.
Доверие к проекту Pi контролирует загрузку ресурсов проекта; оно не снижает разрешения Pi, его команд оболочки или установленных расширений.
Выпуск 0.84.4 добавляет очистку очереди RPC, переопределения возможностей терминала, события UI-подсказок расширений и экспериментальную поддержку DeepSeek V4 Flash Vision.

Изучите рабочий процесс: учебное задание Pi с песочницей