Pi Coding Agent на практике — от задачи до рабочего скрипта

 

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

Pi Coding Agent идёт другим путём. Это минимальный терминальный harness с четырьмя базовыми инструментами: read, write, edit и bash. Он работает прямо в вашей оболочке, может использовать локальные модели через Ollama и сам замыкает цикл «написал → запустил → увидел ошибку → исправил».

В этой статье мы пройдём полный путь на Ubuntu 24.04 в Yandex Cloud. Установим всё необходимое, подключим локальную модель Qwen, зададим правила безопасности через AGENTS.md и доведём агента до рабочего Bash-скрипта. Без облачных ключей и без сложных orchestration-слоёв.

Все команды и конфиги проверены. Готовый runbook лежит в репозитории серии, чтобы вы могли повторить всё шаг за шагом.

 

Чем Pi coding agent отличается от обычного LLM

Обычный чат с большой языковой моделью работает линейно. Вы описываете задачу. Модель выдаёт код. Вы копируете его в терминал. Получаете ошибку. Возвращаетесь в чат. Объясняете, что сломалось. Получаете новую версию. И так по кругу.

Каждый шаг требует вашего участия. Модель не видит реальный вывод команд и не может сама проверить результат.

Pi Coding Agent устроен иначе. У него есть четыре инструмента, которыми он реально пользуется:

• read — читает содержимое файлов и каталогов;
• write — создаёт новые файлы;
• edit — вносит точечные правки в существующий код;
• bash — выполняет команды в терминале и читает их вывод.

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

Разница не в «умности» конкретной модели. Разница в том, что агент замыкает петлю обратной связи сам.

 

Среда и подготовка

Всё, что описано ниже, проверено на Ubuntu 24.04 в Yandex Cloud. Если у вас уже стоят Ollama и модель Qwen — можно переходить сразу к установке Pi. Если нет — разберём установку полностью, чтобы статья оставалась самодостаточной.

 

Базовые пакеты и Node.js

Pi распространяется как npm-пакет, поэтому нужен Node.js. Сначала обновим индексы и поставим необходимые утилиты:

sudo apt update
sudo apt install -y curl ca-certificates gnupg

Проверим, есть ли уже Node.js:

node --version || echo "Node.js не найден"

Если версия ниже 18 или команда не найдена, ставим актуальную LTS через NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

На момент написания статьи достаточно Node.js 18+, но 20 или 22 работают стабильнее.

 

Установка Ollama

Ollama — это простой способ запускать большие языковые модели локально. Установка занимает одну команду:

curl -fsSL https://ollama.com/install.sh | sh

После установки сервис обычно стартует сам. Проверим:

sudo systemctl enable --now ollama
ollama --version

Если сервис не запустился, команда systemctl status ollama покажет причину.

 

Скачивание модели Qwen

Для coding-задач хорошо подходят модели семейства Qwen-Coder. Начните с относительно лёгкой:

ollama pull qwen2.5-coder:7b

Если есть больше видеопамяти или оперативной памяти, можно взять более свежую и мощную версию (имя уточняйте через ollama list после появления новых тегов). После загрузки проверьте список:

ollama list

Запомните точное имя модели — оно понадобится в конфигурации Pi.

 

Установка Pi Coding Agent

Основной способ — через npm с отключёнными install-скриптами (так рекомендует документация):

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

Альтернатива — официальный установщик:

curl -fsSL https://pi.dev/install.sh | sh

Проверяем версию:

pi --version

На момент написания статьи актуальная версия — 0.84.3. Именно её мы фиксируем в репозитории серии.

 

Настройка Pi под Ollama

Pi хранит конфигурацию провайдеров в каталоге ~/.pi/agent/. Создадим его, если его ещё нет:

mkdir -p ~/.pi/agent

Файл ~/.pi/agent/models.json описывает доступные провайдеры. Для локальной Ollama он выглядит так:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "qwen2.5-coder:7b"
        }
      ]
    }
  }
}

Подставьте точное имя модели из вывода ollama list.

Файл ~/.pi/agent/settings.json задаёт провайдера и модель по умолчанию:

{
  "defaultProvider": "ollama",
  "defaultModel": "qwen2.5-coder:7b"
}

После сохранения конфигурации можно переходить к работе с проектом.

 

AGENTS.md и границы работы

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

Именно здесь мы сразу задаём правила безопасности и предпочтения по стилю кода. Создадим рабочий каталог и инициализируем git:

mkdir -p ~/pi-lab/article-01
cd ~/pi-lab/article-01
git init

Теперь создадим минимальный, но уже полезный AGENTS.md:

# Project Instructions for Pi

- Работай только внутри текущей директории проекта.
- Перед изменением файлов сначала читай их содержимое.
- После любых правок запускай скрипт и читай вывод.
- Не используй sudo и не предлагай его без явной просьбы.
- Предпочитай dry-run и проверку перед разрушительными действиями.
- В Bash-скриптах используй set -euo pipefail.
- Код должен быть понятным и с обработкой ошибок.

Этот файл — первая линия обороны. Он не заменяет полноценный sandbox, но сильно снижает вероятность того, что агент начнёт предлагать опасные команды.

 

Первый pi agent loop на практике

Запускаем Pi в нашем каталоге:

cd ~/pi-lab/article-01
pi

В интерактивной сессии даём конкретную задачу. Чем точнее формулировка, тем меньше лишних итераций:

Создай простой Bash-скрипт disk_check.sh.
Он должен:
- показывать использование корневого раздела в процентах
- если свободно меньше 20%, печатать WARNING в stderr
- завершаться с кодом 0 при норме и 1 при предупреждении
- использовать set -euo pipefail
- быть понятным и shellcheck-friendly

Дальше происходит классический agent loop. Pi:

• читает AGENTS.md и текущее окружение;
• создаёт файл через инструмент write;
• запускает его через bash;
• читает вывод и код возврата;
• при необходимости вносит правки через edit;
• повторяет запуск до получения ожидаемого результата.

Центральная схема этого процесса выглядит так

Вы видите весь цикл в терминале. Агент не прячет промежуточные шаги. Это важно для понимания и контроля.

 

Создаём простой рабочий скрипт

В реальном прогоне агент обычно приходит примерно к такому варианту:

#!/usr/bin/env bash
set -euo pipefail

THRESHOLD=20
USAGE=$(df -P / | awk 'NR==2 {print $5}' | tr -d '%')

if [[ -z "${USAGE}" ]]; then
  echo "ERROR: cannot determine disk usage" >&2
  exit 2
fi

echo "Root filesystem usage: ${USAGE}%"

if (( USAGE > 100 - THRESHOLD )); then
  echo "WARNING: free space below ${THRESHOLD}%" >&2
  exit 1
fi

exit 0

Обратите внимание на несколько деталей, которые агент (при хорошем промпте и AGENTS.md) обычно учитывает:

• set -euo pipefail — скрипт падает при первой же ошибке;
• df -P — портативный формат вывода, меньше сюрпризов с локалью;
• явная проверка, что значение USAGE удалось получить;
• предупреждение уходит в stderr, а обычный вывод — в stdout;
• понятные коды возврата.

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

chmod +x disk_check.sh
./disk_check.sh
echo "Exit code: $?"

Если всё работает — фиксируем в git:

git add disk_check.sh AGENTS.md
git commit -m "article-01: disk_check.sh via Pi agent loop"

Именно связка «агент пишет и чинит → вы принимаете через git» и есть основа всей серии.

 

Минимальная безопасность уже сейчас

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

Работайте под обычным пользователем, а не под root. Держите реальные секреты и production-конфиги вне репозитория. Используйте git как границу принятия изменений: всё, что агент сделал, появляется в рабочей копии, а в основную ветку попадает только после вашего review.

Позже в серии мы усилим эти меры — allowlist команд, containerization, отдельные systemd-сервисы. Сейчас достаточно заложить правильную привычку.

 

Что получилось и куда дальше

Мы установили Node.js, Ollama и модель Qwen, поставили Pi Coding Agent, настроили его на локальную модель, задали правила через AGENTS.md и прошли полный цикл от задачи до рабочего скрипта с самоисправлением.

Готовый runbook со всеми командами лежит в репозитории серии:

docs/article-01-runbook.md

Сам репозиторий:

https://github.com/BigDataSchoolRU/pi-data-platform-lab

В следующей статье перейдём к более серьёзным Bash-скриптам: параметры командной строки, логирование, обработка сигналов, shellcheck и полноценная автоматизация рутинных задач.

 

Ограничения и типичные ошибки

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

Типичные проблемы первой недели и как с ними бороться:

• Pi не видит модель — проверьте ollama list и точное совпадение имени в models.json и settings.json;
• Connection refused к Ollama — systemctl status ollama и перезапуск сервиса;
• агент предлагает sudo — усильте формулировки в AGENTS.md;
• скрипт падает на разборе вывода df — используйте df -P и проверяйте локаль;
• потеряли удачную версию — всегда коммитьте после успешного прогона.

Чем конкретнее задача и чем жёстче AGENTS.md, тем предсказуемее результат.

 

Практические рекомендации

Чтобы повторить всё у себя с минимальными сюрпризами:

• начните с чистой Ubuntu 24.04 и поставьте Node.js, Ollama и модель по runbook;
• установите Pi через npm с флагом —ignore-scripts;
• пропишите ollama в models.json и settings.json;
• создайте отдельный каталог проекта и AGENTS.md с правилами безопасности;
• дайте агенту одну чёткую задачу с критериями успеха;
• доведите цикл до рабочего скрипта и сразу зафиксируйте результат в git.

После этого вы уже готовы к следующей статье серии.

 

Заключение

Pi Coding Agent показывает, что полезный coding-агент не обязан быть тяжёлым и облачным. Четыре инструмента, локальная модель и понятный цикл «написал — запустил — исправил» уже дают ощутимую пользу инженеру данных и системному администратору.

В следующих статьях мы будем наращивать сложность и писать полноценные Bash- и Python-утилиты, работать с существующим кодом, Docker, Kafka и ClickHouse. Но фундамент — именно тот цикл, который мы прошли сегодня.

 

Референсы

• Официальный сайт Pi Coding Agent
• Документация Pi
• Интеграция Pi с Ollama
• Репозиторий серии статей
• Runbook статьи 1