Pi: выполните одну первую кодовую задачу в песочнице

Последнее тестирование и обновление: 1 сентября 2026

Pi является минимальной оболочкой для кодирования в терминале. Ее стандартные инструменты модели могут читать, записывать, редактировать и выполнять shell-команды. Это делает ее полезной для задачи с небольшим репозиторием; это также означает, что Pi работает с разрешениями пользователя, который его запускает. Управление доверием к проекту Pi определяет, загружаются ли ресурсы проекта локально. Оно делает не изоляцию инструментов, расширений или shell-команд.Безопасность Pi

Цель этого урока намеренно узкая:

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

Не начинайте, если вы не можете выполнить предварительную проверку песочницы и провайдера. Пробный запуск без учетных данных модели полезен для проверки установки и изоляции, но это не является результатом задания агента.

Шаг 1: назовите границы перед установкой

Это упражнение имеет пять отдельных слоев. Держите их раздельно в своих записях.

Слой	Выбор этого урока
Программный хaрнесс	Pi 0.84.4 только ядро для первого запуска.
Репозиторий	Одноразовая локальная копия, не содержащая учетных данных или личных данных.
Провайдер	Один аккаунт, который вы явно выбираете в песочнице; по возможности используйте краткоживущие или тестовые учетные данные.
Песочница	Docker, OpenShell или другой полностью контролируемый политикой процесс, который вы можете продемонстрировать.
Пробная установка пакета	По желанию и только после записи основных результатов; каждый пакет — это стороннее программное обеспечение.

Pi документирует Docker как шаблон контейнера всего процесса, а OpenShell как шаблон песочницы с управлением политикой. Его расширение Gondolin направляет встроенные инструменты Pi в микро-ВМ, но сам Pi остается на хосте, и другие инструменты расширения все еще могут там работать. Для этой первой задачи предпочтительно использовать песочницу всего процесса.Контейнеризация Pi

Шаг 2: предварительная проверка движка песочницы

Для Docker проверьте доступ как клиента, так и демона перед подготовкой репозитория:

docker --version
docker информация --format '{{.ServerVersion}}'

Если вторая команда сообщает об отказе в доступе или невозможности подключения, остановитесь. Не используйте sudo используйте как временное решение и не утверждайте наличие изоляции Docker, которой вы не получили. Попросите администратора намеренно настроить доступ к демону, используйте одобренную установку Docker без root или выберите доступную среду OpenShell/VM.

Для OpenShell шлюз уже должен быть доступен и выбран. Pi документирует необходимый шаблон как:

openshell шлюз добавить <gateway-urл> --имя <имяe>
openshell шлюз выбрать <имяe>
openshell песочница создать --имя pi-песочница --from пи -- пи

Удаленный шлюз OpenShell не монтирует ваш проект на хосте. Загрузите одноразовый репозиторий в песочницу и затем скачайте его результат. Это безопаснее, чем доступная запись на хосте через bind mount, который позволяет изменениям в песочнице влиять на файлы хоста.Контейнеризация Pi

Шаг 3: собрать одноразовый проект

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

mkdir -p /tmp/pi-first-task/repo
cd /tmp/pi-first-task/repo
git инициализация
кот > package.json <<'EOF'
{
  "name": "pi-first-task",
  "private": true,
  "scripts": { "test": "node --test" }
}
EOF
mkdir -p тест
кот > math.js <<'EOF'
export function add(left, right) {
  return left - right;
}
EOF
кот > test/math.test.js <<'EOF'
import test from 'node:test';
import assert from 'node:assert/strict';
import { add } from '../math.js';

test('add объединяет два числа', () => {
  assert.equal(add(2, 3), 5);
});
EOF
node --тест

Тест должен провалиться, потому что add вычитает. Зафиксируйте намеренно сломанное состояние:

git добавить package.json math.js test/math.test.js
git коммит -m "test: add failing addition exercise"
git статус — короткий

Шаг 4: встроить Pi в явный Docker-образ

Сохраните это Dockerfile.pi рядом с временным репозиторием, а не в проекте, который вам важен:

ИЗ node:24-bookworm-slim

ВЫПОЛНИТЬ apt-get update "
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
ВЫПОЛНИТЬ npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.4

РАБОЧИЙ_КАТАЛОГ /workspace
ТОЧКА_ВХОДА ["pi"]

Соберите его после успешного предварительного запуска демона:

docker сборка -t pi-first-task:0.84.4 -f Dockerfile.pi .

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

Шаг 5: проверьте границу файловой системы до запуска модели

Монтирование репозитория с правами на запись удобно, но намеренно не защищает этот репозиторий от агента. Для проверки отказа смонтируйте его только для чтения и попросите шелл контейнера создать файл вне допустимой области. Это должно завершиться неудачей:

docker запуск --rm \
  --только_для_чтения \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --mount type=bind,source="$PWD",target=/workspace,readonly \
  --точка_входа /bin/sh \
  pi-first-task:0.84.4 \
  -lc «касаться /рабочего пространства/out-of-scope.txt»

Запишите ненулевой статус выхода и ошибку файловой системы только для чтения. Затем докажите, что хост не получил файл:

тест ! -e out-of-scope.txt
printf «песочница сохранена\n»

Это доказывает только проверенную вами политику: контейнер не мог записать в это конкретное монтирование только для чтения. Это не доказывает, что Docker блокирует весь сетевой доступ, все escape-файлы ядра или доступ, разрешённый другими смонтированными путями. Для более прочной конфигурации скопируйте репозиторий в песочницу или используйте удалённую песочницу OpenShell, добавьте явную политику выхода и предоставите только узкий маршрут для провайдера.

Шаг 6: выполнить задачу только для ядра в записываемой одноразовой копии

Для фактического исправления сделайте отдельную копию, которую песочница может изменять:

cd /tmp/pi-first-task
cp -a репозиторий writable-repo
cd writable-repo

Запускайте Pi только с его основными инструментами. Не монтируйте хост ~/.pi/agent; он может содержать сессии, настройки и учетные данные. Следующая команда предоставляет Pi каталог агента локально для контейнера. Она запрашивает аутентификацию провайдера внутри песочницы, или вы можете передать временный тестовый ключ, используя документированную переменную окружения провайдера:

docker запуск --rm -it \
  --mount type=bind,source="$PWD",target=/workspace \
  --mount type=volume,source=pi-first-task-agent,target=/root/.pi/agent \
  --workdir /workspace \
  -e PI_OFFLINE=1 \
  pi-first-task:0.84.4 \
  "Исправьте math.js так, чтобы существующий тест прошел. Работайте только в math.js. Не устанавливайте пакеты, не используйте сеть, не редактируйте тесты, не выполняйте commit и не делайте push. Запустите npm test и git diff --check. Сообщите о каждой команде и измененном файле, затем остановитесь."

В интерактивной сессии выполните аутентификацию с /login только если вы готовы поместить учетные данные этого тестового провайдера в эту песочницу. Предпочтителен ограниченный аккаунт или маршрут инференса песочницы. Pi поддерживает интерактивный вход по подписке и нескольких провайдеров API-ключей; не вставляйте секретные данные для производства в историю терминала или этот урок.Pi quick startПоставщики Pi

Запишите перед принятием результата:

Доказательства	Значение для сохранения
Время настройки	Минуты от сборки образа до готовой сессии модели.
Pi и версия образа	pi --version и тег образа.
Провайдер и модель	Только название; никогда не записывайте секрет.
Токен/стоимость	Отображение сессии Pi или отчет провайдера.
Сбои инструментов	Точные команды, которые не удались, и восстановление.
Человеческая корректировка	Любой предоставленный вами запрос, редактирование или одобрение.
Основной/пакетный дельта	core only для этого первого прохода.

Шаг 7: проверьте вне агента

Выйдите из Pi. На хосте выполните независимо:

cd /tmp/pi-first-task/writable-repo
npm тест
git diff --проверить
git статус — короткий
git diff -- math.js
git diff --только-имя

Принимайте только этот результат:

1. npm test проходит.
2. git diff --check не вызывает ошибок.
3. math.js это единственный изменённый файл.
4. Разница изменяет вычитание на сложение и больше ничего.
5. Ваша ранее проведённая проверка доступной только для чтения монтировки не удалась и не оставила out-of-scope.txt позади.

Если любое условие не выполнено, сохраните доказательства и отметьте запуск как неуспешный. Не превращайте незавершённый запуск в историю успеха.

Шаг 8: тестируйте отсоединение или перезапуск только когда это необходимо

Сессии Pi и срок жизни песочницы отдельны. A docker run --rm контейнер исчезает, когда его процесс Pi завершает работу; это не система отсоединенных рабочих. Если вашему рабочему процессу требуется доказательство перезапуска, сохраните локальный том агента Pi контейнера, запустите новый контейнер и проверьте, видна ли ожидаемая сессия без монтирования состояния Pi хоста.

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

Шаг 9: пробная установка необязательного пакета — второй, отдельно обозначенный запуск

Только после прохождения основного результата вы можете тестировать проверенный пакет. pi-mcp-adapter является одним примером: это сторонний пакет расширения/навыка, а не основная функция Pi. Каталог Pi определяет его версию, зависимости, манифест и команду установки; его репозиторий описывает обработку конфигурации MCP и ленивый запуск сервера. Прочитайте прикрепленный исходный код перед установкой и используйте отдельную одноразовую копию.Запись каталога pi-mcp-adapterРепозиторий pi-mcp-adapter

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

Держите выполнение пакета отдельно:

# Внутри одноразовой песочницы после проверки прикрепленного исходного кода пакета.
пи install npm:pi-mcp-adapter@2.31.0
пи список
# Выполните одну ограниченную, тестируемую задачу.
пи удалить npm:pi-mcp-adapter
пи список

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

Шаг 10: удалите оценку

Удаляйте временное изображение и том только после того, как вы сохранили все необходимые доказательства:

docker том rm pi-first-task-agent
docker изображение rm pi-first-task:0.84.4
rm -rf /tmp/pi-first-task

Если вы выполнили глобальную установку, удалите точно текущий пакет:

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

Обзор ~/.pi/agent вручную перед удалением конфигурации или сессий. Эта команда удаляет npm-пакет, а не все файлы, которые могут быть созданы Pi или сторонним пакетом.

Условия остановки

Остановите и отметьте результат заблокировано, а не импровизируйте вокруг одного из этих условий:

• Невозможно установить изоляцию Docker/OpenShell/VM или проверка отказа не завершается с ожидаемым результатом;
• невозможно проверить установщик или источник пакета;
• нет доступных учетных данных провайдера или подписки для выбранной обратимой задачи;
• репозиторий содержит секреты, личные данные или нерелевантные изменения; или
• запрошенный тест, проверка различий, лимит измененного пути или проверка очистки завершается с ошибкой.

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

Источники

• Документация Pi
• Документация по безопасности Pi
• Документация по контейнеризации Pi
• Документация по пакету Pi
• Документация провайдеров Pi
• Выпуск Pi v0.84.4
• Запись каталога pi-mcp-adapter
• Репозиторий pi-mcp-adapter