@euhenio/pi-buddy

Русский · English

Тамагочи для pi: питомец живёт в полосе справа от поля ввода и реагирует на работу агента — идёт, пока агент работает, виляет хвостом после успешного хода, грустит на ошибках, засыпает в простое.

Исходный код на GitHub · Сообщить об ошибке

30 секунд: основные возможности на настоящих спрайтах питомцев. Постановочное демо.

Установка

pi install ./pi-buddy                              # из локальной папки
pi install git:github.com/e-davidenko/pi-buddy      # из git
pi install npm:@euhenio/pi-buddy                   # из npm

Попробовать без установки: pi -e ./pi-buddy.

Если раньше расширение лежало файлом в ~/.pi/agent/extensions/buddy.ts — удалите тот файл, иначе будут две команды /buddy. Питомец сохранится: его состояние в ~/.pi/agent/buddy.json.

Язык

Поддерживаются русский и английский: /buddy lang ru, /buddy lang en и /buddy lang auto. Команды, ключи видов и тем не переводятся; имя питомца сохраняется. Существующие питомцы без настройки языка остаются на русском. Новые используют auto: первое непустое значение LC_ALL, LC_MESSAGES, LANG; русская локаль выбирает ru, все остальные (включая C и POSIX) — en. Настройка общая для терминалов и сохраняется при hatch; в режиме auto каждый терминал использует своё окружение. Переключение очищает текущую реплику и игровую сцену.

Анимация

У каждого питомца — пиксельный спрайт и 30 кадров: моргание, свои «фирменные» движения в простое (кот машет хвостом и умывается, утка кивает, сова подмигивает, дракон пускает дымок…), ходьба, пока агент работает, прыжки от радости, позы «лежит», «грустит» и «спит» с дыханием. Во время работы агента питомец показывает, чем тот занят: думает, ищет (агент читает код), работает (правит файлы), настороже (команда в терминале), сидит и ждёт (тесты, сборка, субагенты), а на зелёных тестах подаёт голос. Позы у каждого свои: собака нюхает след и гавкает, кот крадётся и закапывает баг, утка ныряет хвостом вверх и высиживает билд в гнезде, сова листает книгу и ухает, дракон роет сокровища и выдыхает пламя, призрак ищет с лупой и пугает «бу!», аксолотль роет песок и пускает пузыри, блоб шлёпает ложноножками. Каждая поза активности держится не меньше 5 секунд. Смена анимаций идёт через базовую стойку, без резких скачков. В простое питомец иногда сам берёт любимую игрушку.

Субагенты — «стая»

Когда агент запускает субагентов (инструмент subagent из примеров pi и похожие — task, delegate, spawn_agents…), над питомцем появляются его мини-копии (щенки, котята, утята…), по одному на субагента (до трёх, остальные — +N). Каждый щенок показывает, чем занят его субагент: нюхает, копает, сидит на тестах, виляет хвостом на ✓, грустит на ✗; в цепочке (chain) следующие ждут своей очереди. Сам питомец в это время сидит и «пасёт стаю», а когда все вернутся — гавкает. Фоновые запуски pi-subagents (async) тоже понимает: инструмент возвращается сразу, а стая бегает, пока субагент действительно не закончит (живой статус берётся из его status.json). Опыт за работу субагентов начисляется питомцу родительской сессии (сами дочерние pi-процессы состояние не трогают).

Команды

В чате можно попросить агента: «добавь питомцу фраз про Kafka» — он вызовет инструмент buddy_phrases.

Чтобы выбрать собаку без меню, введи полную команду в одной строке: /buddy choose veo_px — пиксельный ВЕО, /buddy choose gsd — немецкая овчарка. Имя, уровень и опыт сохранятся. Если после /buddy choose меню не видно, нажми Esc и используй одну из команд из показанного списка.

Свои фразы и обучение

/buddy learn генерирует фразы на активном языке. Инструмент buddy_phrases принимает необязательный locale: "ru" | "en" для явного выбора языка; по умолчанию используется текущий. Качество формулировок зависит от модели. Если во время обучения сменить язык или вид, ответ сохранится в исходный набор, который будет указан в уведомлении.

Новый формат файла:

{
  "version": 2,
  "locales": {
    "ru": {
      "common": { "done": ["ещё один баг побеждён!"] },
      "species": { "cat": { "hello": ["мяу, снова кодим?"] } }
    },
    "en": {
      "common": { "done": ["another bug defeated!"] },
      "species": {}
    }
  }
}

Пользовательские фразы дополняют только свой язык. Старые файлы читаются как русский набор; первое изменение или /buddy phrases переводит файл в v2, сохраняя оригинал в buddy-phrases.json.bak. Чтение само по себе файл не меняет. Перед откатом на версию без поддержки v2 восстановите старый файл из .bak, сохранив отдельно v2 с новыми фразами. Повреждённые данные и неизвестные версии не перезаписываются шаблоном. После ручной правки нужен /reload; выученные фразы подключаются сразу. phrases clean проверяет все языки. Ограничение — 34 видимых графемы без метки позы; метки @stand:, @walk:, @lie:, @sit: должны подходить теме.

Записи защищены блокировкой и атомарной заменой. При занятом файле команда сообщает ошибку — повторите её. Ручные правки делайте, когда обучение не выполняется. /buddy play принимает также стабильный id игрушки (ball, bone и другие); прежние русские названия продолжают работать на английском.

Файлы

• ~/.pi/agent/buddy.json — состояние питомца
• ~/.pi/agent/buddy.json.bak — предыдущая сохранённая версия для восстановления
• ~/.pi/agent/buddy-phrases.json — свои и выученные фразы

Опыт сохраняется после каждого хода модели, в конце запроса и раз в 30 секунд во время работы. Терминалы сливают прогресс под общей файловой блокировкой (buddy.json.lock), поэтому их одновременные сохранения не перезаписывают друг друга. Дочерние процессы без интерфейса прогресс не сохраняют. При ошибке сохранения прогресс остаётся в памяти до следующей попытки, а pi показывает предупреждение. Если основной файл повреждён, читается резервная копия. Если обе версии не читаются, расширение сообщает об ошибке, а не создаёт нового питомца поверх старого состояния. Команда /buddy hatch после подтверждения создаёт нового питомца со сбросом опыта, сохраняя настройки интерфейса. Если диалог подтверждения недоступен, введи /buddy hatch confirm.

Ручная игра не даёт XP. Ошибка инструмента и неуспешное возвращение стаи отнимают 10 пунктов радости; бонус за завершение даётся только при успехе. Все правила ухода, настроения и общего прогресса описаны в правилах поведения.

Расширение само в сеть не ходит. /buddy learn обращается к модели pi; buddy_phrases сохраняет фразы, переданные агентом.

Ошибки и предложения

Нашли ошибку или хотите предложить улучшение? Создайте issue на GitHub. Перед этим проверьте существующие обсуждения — возможно, проблема уже известна.

Для сообщения об ошибке укажите версии pi и pi-buddy, ОС и терминал, шаги для повторения, ожидаемое и фактическое поведение. Если проблема связана с отображением, приложите скриншот.

Устройство кода

Расширение — обычные TypeScript-модули: pi загружает их сам, сборка не нужна, зависимостей нет. extensions/buddy.ts — точка входа, весь код в src/, разложен по слоям (зависимости идут только внутрь):

После npm ci: тесты домена, приложения и хранилища — npm test, проверка типов — npm run typecheck.

Структура каталогов и добавление языка: руководство по локализации.