Pi, мінімальная абвязка агента кадавання: пашырэнні, навыкі, сесіі і бяспека
Чаму маленькая тэрмінальная абвязка з чатырма інструментамі і кароткім сістэмным промптам можа перамагчы перагружаных агентаў: усталяванне, мадэлі, дрэвы сесій, пашырэнні, навыкі і пясочніца.
Тэрмінальныя агенты для кодавання, такія як Claude Code, Cursor і OpenCode, сталі звычной часткай кожнага дня багацох распрацоўшчыкаў, особліва пасля таго, як у квеце ў OpenAI была адкрыта для вільнага вжытку версія Codex CLI. Pi — гэта спецыяльна простая установка для кодавання, створаная як адказ на проблемы, якія існуюць у всіх пераказаных вышэй агентах: інструменты постаўляюцца з постаўнымі змянамі.
Прэтэнзія не стосуецца багоў. Рэч у тым, што сама установка змінюецца, і ў зв’язку з гэтым змінюецца і поведзенне модэлю. Інжынеры хочуць інструменты, на якія можна рэлігавацца. Самыя LLM-ы ёсць ненадзеянымі, але прынеймна супакоўкі, якія іх абгрунтаваюць, включаючы інструменты, запрошэнні да дзеяння і все, што ўводзіцца ў ўпрабаванне, можна зробіць надзеянымі.
Claude Code і Codex додаюць многа элементаў у ваш кантэкст, не паказваючы іх у інтэрфейсе, і гэтыя схованыя дадаткі па-свойму парадузуюць працэс выканання задач. Абнаўленні выходзяць аднае раз у дзень, а іноды нават колька разоў у дзень. Працэс, які працуе ідэальна о дзевяць ранку, можа зламацца да дзесятай гадзіны і пачынаць працаваць абсалютна інакша да трох, пры чым сама мадэль застаецца незменнай, а змяніцца толькі інструментарый. Новыя функцыі з’являюцца практычна ў кожны месяц — сярод іх MCP, сабэйенты, рэжым планавання і выканання на фоне, і стае все важкая разумець, што відбываецца за кулісамі.
Адпаведзь Пі — гэта правіло дызайну: калі чагось не трэба, яго не ствараюць. Існуючыя інструменты дадаюць кантэкст непазіруючы, і корыстувальнікі не можуць бачыць, што відбываецца. Гэта і была мотывацыя.
Што стала прычыной мінімалізму
Перш чым створыць Pi, яго создатар Марыо Цехнер адзірнуў таблыцу лідэраў Terminal Bench, дзе выдзеляўся інструмент пад назвай Terminus. Ён дае модэлю толькі адні разы інструмент – інтэрфейс да сесіі tmux. LLM адправляе адзіныя нажатыя клавішы і чытае адпаведны выхід з tmux, каб завершыць заданне. Толькі з гэтага ён практычна завжды патрапляе у трох лепшых і часта займае першае месца.
Гэта паказвае корыстную інтуіцыю: модэлі сэрьза трэнуюцца за дапамогою метода падкрэплення, таму яны вялікі час вядомыя ў тым, што такое інструменты для програмавання, і ім не трэба додатковых элементаў. Pi воплотжае гэю ідэю як мінімалістычны, але расшыруемы інструмент.
Што робіць Pi адным
Асаблівайшая рысь Pi — гэта тое, чаго ён не выклікае, тыя характэрыстыкі, якія іншыя кансольныя агенты спрыяюць як стандартныя. Возьмем MCP: ён падключаецца да сервера, і кожная вакліканая інструментальная дэфініцыя заполняе кантэкст на пачатку кожнай сесіі. Інструменты CLI прыходзяць з файламі README, якія чытаюцца і запускаюцца толькі тады, калі гэта неабходна, таму няма прычыны постаўляць кантэкст на іх сталяк.
Што ёсць у Pi, чаго няма у іншых
Pi быў створаны па прынцыпу аднімання, пры тым як у яго ёсць можлівасці, якіх няма у Claude Code. Расшырэнні і пакеты інсталююцца за дапамою калькі каманд:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
Механізм расшырэння
Расшырэнні пішуцца на адпаведна API, імпортаванаму з пакета Pi:
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
Пашырэнне можа прыўязвацца да такіх запускаеў, як вызовы інструментаў. Адны з прыкладаў — захопленне ад небяспечных каманд шэлу:
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command.includes("rm -rf")) {
const ok = await ctx.ui.confirm(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
1. Установка
Для установкі патрэбна адна команда:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Скрыпт для інсталяцыі ўтварае альтэрнатыву:
curl -fsSL https://pi.dev/install.sh | sh
Існуе два спосабы аўтэнтыфікацыі. Адзін з іх выкарыстоўвае ключ API:
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
Іншы варыянт — аднаўленне прадплатацыі, якая у вас вялікі ўжо:
# Use an existing subscription
pi
/login # Select a provider
За дапамою /login можна выкарыстоўваць існуючыя падпісанні, такія як Anthropic Claude Pro або Max, OpenAI ChatGPT Plus або Pro (Codex) і GitHub Copilot, як і раней. Прагіб для навучэння ўжо ў мінімуме: установіце яго, пачніце размовляць з яным, і ён будзе працаваць.
2. Наладка модэлю
Pi падтрымляе больш чым 15 прадаўцоў LLM. Серэд галоўных з іх:
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
Змена модэляў у мяжах сесіі ўсё абсалютна нормальна:
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
Спецыяльных прадаўцоў можна дадаць у ~/.pi/agent/models.json. Будзь-які API, сумесны з OpenAI, Anthropic чыю Google, працюе проста за дапамой настройкаў, а серверы-роутэры, такія як llama.cpp, можу служыць для запуску локальных модэляў. Тое, што сістэма „не прыкрэплена да прадаўца“, — адна з галоўных пераваг, якія акцэнавае Pi.
3. Калектывнае кераванне
Калектывныя сесіі зберагаюцца у файле JSONL з дрэваобразным структурам, у катэгорыі ~/.pi/agent/sessions/; кожныя звесці маюць поля id і parentId. Заводзячы з гэтай структуры, адзін файл падтрымлівае всі этыя операцыі:
pi -c # Continue the most recent session
pi -r # Select from previous sessions
Команда /tree ўзначальна цікава. Вы можэце вернуцца да будзь-яго момента размовы і продактуваць з таму. Весь хад знаходзіцца ў аднам файле, таму лёгка сказаць "Я хацеў пайсці тым шляхам, якім хадзіў паўгадзіны тымчасу тады" і фактычна так зрабіць.
/compact падсумоввае старыя паведамленні, каб стыснуць кантэкст. Автаматычная стысненне ўвімкнута за замовчаннем, і як толькі кантэкст перапоўнюецца, ён сам адноводзіцца і прабуе зноў.
4. Расшырэнні дакладна
Тут Pi паказвае, для чаго ён насправды прызначаны. Налаштаванне складаецца з чатырох роўней:
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
Пакеты з npm або git карацца так:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
Расшырэннія можаць выконваць усе наступнае:
- Даўаць спецыяльныя інструменты, укладаючы ў тое жа разы замену для вбудованых.
- Ствараць спецыяльных пад-агентоў і рэжымы планавання.
- Забезпечваць контроль прав і захаўненне шляхоў.
- Даўаць элементы інтэрфейсу, такія як лінія статусу, заголовак і футарк.
- Ствараць пункты контроля git або аўтаматычныя коміты.
- Інтэграцыя сервераў MCP.
- Калі хочаце, можна запускаць Doom пад час чакання.
Ключовая ідэя заключаецца ў тым, што кожная функцыя, яку іншыя агенты додаюць у продукт — пад-агенты, рэжымы планавання і попапы з правамі — можа быць створана як расшырэнніе. Такім чынам філасофія заключаецца ў тым, каб ядро заставалася мінімальным.
5. Навыкі
Навыкі — гэта пакеты здольнасцяў, напісаныя на Markdown. Са адпаведнасцю да стандарта Agent Skills, папка, якая мае файл SKILL.md, стварае адзін навык.
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
```
```text ## Steps 1. Perform this action. 2. Then perform that action. ```
Навык можна явна прызначыць за дапамою /skill:name, а агент таксама загружае яго сам, калі задача гэта дазволяе. Ключовы выбор у дыяграматыцы заключаецца у тым, што навыкі прадаюцца ў кантэкст толькі тады, калі гэта неабходна. У змену таму, каб усё падаўціць у сістэмны запрос, яны актываюцца пад час вікорыстоўвання, і самэ гэта дапамагае сістэмнаму запросу застацца блізу тыячы токэнаў.
6. Pi Web, інтэрфейс прыгледчыка
Таксама існуе інтэрфейс прыгледчыка пад назвай Pi Web:
npx @agegr/pi-web@latest
Яго галоўныя фічы:
- Рабочая прастора сесіі для перыявлення, адновлення, перайменавання і выдалення паказаных раней кансэрвацый па праектах.
- Два спосабы стварэння галузей: пачатак новай сесіі з паведамлення або стварэнне галузі ў рамках чынной сесіі.
- Адзірванне файлаў праекта і адображэнне разліків у фармаце Git.
- Змена рабочай дрэвы Git.
- Улогаванне у прадаўца, настройкі модэля, пакета і навыкаў у браузеры.
Паколькі ён дзеліць настройкі і файлы сесіі з каталогам ~/.pi/agent з версіяй для тэрміналу, пераход між браузерам і тэрміналам адбываецца без працы.
7. Памяць
Памяць ў даным случае ёсць простай. Падход такі: Pi не патрабуе окалічнай базы дадзеных для давялікай памяці. У замен існуе тры механізмы:
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
Іншымі словамі, тое, што было зроблена, застаецца ў сесіі, а тое, што хочаце запамятаць, — у файле AGENTS.md. Дадаць «памяць» за дапамою расшырэння таксама ёсць ўзнакомым спосабам прыменення.
8. Абаранець сябе
У Pi няма вбудованага сэндбокса. Операцыі чытання, запісу, рэдагавання і выканання каманды баш выпалююцца з правамі таго, хто яго запускае, і тое ж сама стосуецца расшырэнняў. Гэта робіцца намерна. Напаловы вбудованы сэндбокс у рамках працэса дае толькі выглядна безпечную межу, таму офіцыйная позіцыя — заставіць рэальную ізоляцыю OS, а таксама шарах кантэйнераў чы рэзервных машын. Ненадзорныя рэпазітарыі і запускі без нагляду павінны знаходзіцца ў ізольаванай асяроддзі.
Адна з апцыяў — паклаць усе сераўеры Pi ў Docker, гэта простэйшы падход:
# 1. Put the entire pi environment in Docker (simplest)
Іншы спосаб — запускаць Pi на хосце і направляць выконанне толькі інструментаў у локальную мікро-ВМ:
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
Функцыя пад назвам project trust дадзеяе захаванне для вводу. Яна не дазволяе рэпазітарыям таямніча заменяць настаўкі Pi чы расшырэнні, а па значэнню стандарту запытае падтверджэння для неперакананых праектаў. Аднак яна не запобегае цэлком вставкі команд, таму памятайце пра гэта, калі працуеце з незнайомым кодам чы дакументамі.
9. Стварэнне саваго расшырэння
Найменшае пашырэнне — гэта адзін файл на TypeScript. Яны рэгіструець інструмент:
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
і ён можа дадаць каманды або пераспрыяваць вызовы інструментаў:
pi.registerCommand("stats", {
// Custom command definition }); pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
Занесіце файл у ~/.pi/agent/extensions/ для всіх праектаў, або у .pi/extensions/ для аднаго праекта, і ён будзе автаматычна завантажвацца праз запуск Pi. Для разовага тэста падыйдзе команда pi -e ./my-ext.ts. У офіцыяльным рэпазітарыі ёсць множнае прыклады: автаматычныя коміты, пункты контролю git, інтэграцыя MCP і персональная стысненне дадзеных. На Pi відсутнасць адзінаго з функцыянаў ёсць нормальным станам. Звычайны спосаб — самі яго дадаць або запісаць пакет.
Што вучыць Pi
Для тых, хто стварае сабе сэрвыс-агента, рашэнні Pi ўтвараюць корыстны апавядомленьнік. Не варта выбіраць усепакетны пакет. Пачніце з чатырох інструментаў і сістэмнага запрошэння дыялогу дыяметрам ад аднаго тысячы токенав, і дадавайце толькі тое, што неабходна. Дызайн пачынаецца з таго, што трэба адмаўліць, а не з таго, што трэба дадаць.
Супаўзяныя матэрыялы
- Пяць слоёў агентскага харнесу, з кодам, які не будзе працаваць без іх — практычны апіс пяці мест, дзе агентскі харнес выкананае правіла ў кодзе, ад меж выканання да кантэкстных пайплайнаў, а таксама таго, што можа і не можа падтвердзіць доследжэнне.
- Практычныя прыметкі: стварэнне агента для кодавання ў прыватным воблака: OpenCode + локальны LLM — практычны апіс прыметак: стварэнне агента для кодавання ў прыватным воблака: OpenCode + локальны LLM: контракты, перакрыццяі і слоты для коду, якія можна прыўязаць для команд, якія вікорыстоўваюць гэты патэрн.