کالبدشکافی طراحی هارنس Pi

Pi (بسته npm به نام @earendil-works/pi-coding-agent) خود را به عنوان یک «هارنس مینیمال برای ایجنت» (minimal agent harness) توصیف می‌کند. این عبارت ارزش کالبدشکافی دارد: این ابزار خود را «قدرتمندترین ایجنت کدنویسی» یا «بهترین ابزار برنامه‌نویسی هوش مصنوعی» نمی‌نامد، بلکه هویت خود را محکم به واژه هارنس پیوند می‌زند.

در این مقاله، ما از چارچوب پنج زیرسیستم دوره — دستورالعمل‌ها، ابزارها، محیط، وضعیت و بازخورد — برای بررسی Pi استفاده می‌کنیم و نشان می‌دهیم فلسفه طراحی آن چگونه با Claude Code و Codex تفاوت بنیادین دارد. پاسخ از همان ابتدا این است: فلسفه Pi عبارت است از «هسته را مینیمال کن + افزونه‌ها را قابل‌برنامه‌ریزی بساز». این ابزار مهندسی زمینه را فراتر از پرامپت سیستم می‌برد و به کاربران — و حتی به خود Pi — اجازه می‌دهد هارنس را اصلاح کنند، به جای آنکه Pi هارنس را برای شما تعیین کند.

در یک جمله#

ابزار Pi یک هسته مینیمال است: جایگاه رسمی آن عمداً هسته را کوچک نگه می‌دارد و کنترل را به شما بازمی‌گرداند. به تعبیر صفحه اصلی pi.dev: «از Pi بخواهید آنچه می‌خواهید بسازد، یا بسته‌ای را نصب کنید که آن را مطابق میل شما انجام دهد.» این ابزار هارنس را به چهار لایه قابل‌تنظیم تقسیم می‌کند:

• افزونه‌ها (Extensions): هوک‌های TypeScript متصل به رویدادهای چرخه حیات Pi، که سطحی برنامه‌پذیر در سطح زمان اجرا فراهم می‌کنند.
• مهارت‌ها (Skills): بسته‌های قابلیتی بر حسب تقاضا شامل دستورالعمل‌ها و ابزارها، با استفاده از آشکارسازی پیش‌رونده.
• قالب‌های پرامپت (Prompt templates): پرامپت‌های Markdown قابل استفاده مجدد که با وارد کردن /name باز می‌شوند.
• تم‌ها (Themes): ظاهر رابط کاربری متنی ترمینال (TUI).

این رویکرد لایه‌ای خود نوعی طراحی هارنس است: قوانین و افزونه‌ها به طور کامل تعیین می‌کنند که مدل چه چیزی را و چه زمانی می‌تواند ببیند، به جای آنکه این تصمیمات درون هسته هاردکد شده باشند.

حلقه اصلی#

مانند هر ایجنت کدنویسی، Pi اساساً یک حلقه while از «استدلال ← اجرای ابزار ← مشاهده ← استدلال بیشتر» است. آنچه اهمیت دارد خود حلقه نیست، بلکه نحوه مدیریت لایه پیرامون آن توسط Pi است: این ابزار مدیریت زمینه را از «فشرده‌سازی» درون حلقه به «کنترل» بیرون از حلقه گسترش می‌دهد.

زمان اجرای Pi یک رابط برنامه‌ریزی‌پذیر را در دسترس قرار می‌دهد. علاوه بر TUI تعاملی، بخش Programmatic Usage در README سورس کد از حالت‌های اسکریپت‌پذیر print/JSON، پروتکل RPC، و تعبیه‌سازی SDK پشتیبانی می‌کند. این بدان معناست که یک هارنس یکسان می‌تواند مرحله‌به‌مرحله توسط انسان یا به طور خودکار توسط CI/CD یا برنامه‌ای دیگر هدایت شود. این امر پیش‌نیاز حرکت «از کنترل دستی به حلقه‌های خودکار» مطرح‌شده در درس 13 را فراهم می‌سازد: هارنسی که تنها بتواند به صورت تعاملی توسط انسان هدایت شود، هرگز نمی‌تواند وارد یک حلقه خودکار گردد.

زیرسیستم دستورالعمل‌ها: AGENTS.md و SYSTEM.md#

ابزار Pi در نحوه برخورد با دستورالعمل‌ها خویشتن‌دار است، اما سلسله‌مراتب آن شفاف است:

• AGENTS.md: بخش Project Context Files در README سورس کد ترتیب بارگذاری را به صراحت مستند می‌کند: فایل سراسری ~/.pi/agent/AGENTS.md ← پیمایش پوشه‌های والد به سمت بالا سطح به سطح ← دایرکتوری فعلی ./AGENTS.md (همراه با سازگاری با CLAUDE.md). این رویکرد اصل «مخزن به عنوان منبع مرجع» را در عمل پیاده می‌کند — دستورالعمل‌ها فایل هستند، نه یادآوری‌هایی که در چت تایپ شوند.
• SYSTEM.md: مستندات رسمی pi.dev بیان می‌کند که پرامپت سیستم پیش‌فرض می‌تواند برای هر پروژه جایگزین شده یا به آن افزوده شود. این تنها نقطه ورود رسمی Pi برای اصلاح پرامپت سیستم است و به عنوان لایه «خودتوصیفی محیط» نیز عمل می‌کند.

ابزار Pi رسماً تأکید می‌کند که پرامپت سیستم آن مینیمال است. این نشان‌دهنده یک مصالحه صریح است: هسته فهرستی طولانی از قوانین «اگر… آنگاه…» را در خود جا نمی‌دهد. در عوض، نقاط گسترش را باز می‌گذارد تا قوانین تنها در صورت نیاز در قالب مهارت‌ها و افزونه‌ها ظاهر شوند. این مستقیماً یادآور درس 4، «چرا یک فایل دستورالعمل غول‌پیکر شکست می‌خورد» است — ابزار Pi به طور طبیعی از طریق رویکرد «هسته مینیمال + فایل‌های تفکیک‌شده + بارگذاری بر حسب تقاضا» از مشکل فایل دستورالعمل غول‌پیکر دوری می‌کند.

وضعیت و زمینه: جایی که Pi بیشترین جزئیات را دارد#

مهندسی زمینه در Pi شایسته توجه ویژه است، زیرا مفاهیم دوره مانند «پیوستگی زمینه» و «جلوگیری از فساد زمینه» را به سازوکارهای عینی تبدیل می‌کند:

1. فشرده‌سازی برنامه‌پذیر. با نزدیک شدن به سقف زمینه، پیام‌های قدیمی به طور خودکار خلاصه‌سازی می‌شوند. مستندات رسمی pi.dev توضیح می‌دهد که راهبرد فشرده‌سازی خود قابل سفارشی‌سازی است: می‌توانید با افزونه‌ها فشرده‌سازی موضوع‌محور، خلاصه‌های آگاه از کد، یا حتی استفاده از یک مدل متفاوت برای خلاصه‌سازی را پیاده کنید. همچنین README سورس کد جزئیات سازوکار پیش‌فرض را آشکار می‌سازد: فشرده‌سازی خودکار در دو حالت فعال می‌شود (بازیابی از سرریز زمینه / فراتر رفتن از آستانه نگهداری)، نقطه برش تقریباً 20,000 توکن اخیر را حفظ می‌کند، و پیام‌های قبلی در یک «تحویل زمینه» خلاصه شده و به صورت افزایشی در یک زنجیره فشرده می‌شوند. به عبارت دیگر، Pi به مسئله «چگونه فشرده‌سازی کنیم» نه به عنوان یک ثابت قطعی، بلکه به عنوان بخشی از هارنس می‌نگرد.

2. زمینه پویا. مستندات رسمی pi.dev بیان می‌کند که افزونه‌ها می‌توانند پیش از هر نوبت استدلال پیام‌هایی تزریق کنند، تاریخچه پیام‌ها را فیلتر نمایند، RAG را پیاده‌سازی کنند و حافظه بلندمدت بسازند. این فراتر از «فشرده‌سازی هنگام پر شدن زمینه» است: به شما امکان می‌دهد تصمیم بگیرید چه چیزی پیش از رسیدن به پنجره زمینه وارد آن شود. از منظر اهداف دوره در «مشاهده‌پذیر و قابل‌دیباگ ساختن اجرای ایجنت» و «حفظ پیوستگی زمینه»، Pi هر دو را به درون سطح افزونه‌ها سوق می‌دهد.

3. درخت نشست (Session tree). صفحه اصلی pi.dev صراحتاً می‌گوید «نشست‌ها به صورت درخت ذخیره می‌شوند»؛ دستور /tree می‌تواند به هر گره تاریخی بازگردد و از آنجا ادامه دهد، در حالی که تمام شاخه‌ها در همان فایل ذخیره شده‌اند. این امر به گسست‌های زمینه بین‌نشستی که مکرراً در دوره تأکید شده پاسخ می‌دهد — نه با تحمیل خلاصه‌ها برای پل زدن روی شکاف، بلکه از طریق بازپخش ساختاریافته تاریخچه. شاخه‌ها را می‌توان به صورت HTML صادر کرد یا در قالب یک gist برای اشتراک‌گذاری آپلود نمود، که مشاهده‌پذیری را نیز تأمین می‌کند.

زیرسیستم ابزارها: مهارت‌ها و افزونه‌ها#

«ابزارها» در Pi دو لایه دارند:

• مهارت‌ها (Skills): بخش Skills در README سورس کد آن‌ها را صراحتاً به عنوان «بسته‌های قابلیتی مستقل که ایجنت بر حسب تقاضا بارگذاری می‌کند» تعریف می‌نماید. آن‌ها شامل دستورالعمل‌ها و ابزارها بوده و از استاندارد Agent Skills پیروی می‌کنند. آشکارسازی پیش‌رونده اطمینان می‌دهد که جزئیات مهارت تنها هنگام برانگیخته شدن وارد زمینه می‌شوند، بدون آنکه کش پرامپت منفجر شود. این طراحی هارنس از منظر هزینه است: هر توکن اضافی در زمینه باید در هر استنتاج پرداخت شود. بارگذاری مهارت‌ها بر حسب تقاضا بیان دیگری از «نقشه را بده، نه دفترچه راهنما را» است.
• افزونه‌ها (Extensions): هوک‌های TypeScript متصل به رویدادهای چرخه حیات توکار. بخش Hooks در README سورس کد مثال‌های رسمی ارائه می‌دهد: رهگیری دستورات خطرناک (یک گیت مجوز)، ثبت نقطه بررسی وضعیت کد هنگام جابجایی وظایف، محافظت از مسیرها (به عنوان مثال، ممنوعیت نوشتن در .env)، اصلاح خروجی ابزار پیش از ارسال به مدل، و تزریق پیام‌ها از منابع خارجی (ردیاب فایل/وب‌هوک/CI) برای بیدار کردن ایجنت. این APIهای هوک همچنین از @mariozechner/pi-coding-agent/hooks اکسپورت می‌شوند. هارنس جامعه کاربری pi-agent-harness این سطح هوک را بیشتر در قالب افزونه‌های آماده بسته‌بندی کرده است، مانند skill-router، session-summary، extract-patterns، و telemetry.

افزونه‌ها مهم‌ترین تصمیم طراحی Pi هستند: به جای دادن چند کلید تغییر وضعیت به کاربران، Pi کل سطح رویدادهای درون زمان اجرا را در معرض دید قرار می‌دهد. می‌خواهید حافظه اضافه کنید؟ آن را در agent/pre-step تزریق کنید. می‌خواهید رفتار را ثبت کنید؟ در رویدادهای نشست مشترک شوید. می‌خواهید درخواست مدل را تغییر دهید؟ به agent/request هوک بزنید. شما می‌توانید کاری کنید که Pi هارنس خودش را اصلاح کند — این به تعریف «هارنس برنامه‌پذیر» نزدیک‌تر از هر مجموعه‌ای از گزینه‌های پیکربندی است.

بازخورد و راستی‌آزمایی: تبدیل «یادگیری» به بخشی از هارنس#

ابزار Pi به خودی خود شامل گیت‌های تست اجباری نیست (کاربران باید دستورات راستی‌آزمایی را در AGENTS.md مشخص کنند)، اما هارنس جامعه کاربری pi-agent-harness از افزونه‌ها برای ساختاربخشی به «حلقه بازخورد» استفاده می‌کند. بخش Hooks در README رسمی پایه‌ای برای سازوکارهای مشابه فراهم می‌آورد:

• session-summary (یک افزونه pi-agent-harness): مدخل‌های در گردش PROGRESS.md را نگهداری می‌کند — زیرسیستم وضعیت دوره، که برای ردگیری پیشرفت وظایف طولانی‌مدت استفاده می‌شود.
• extract-patterns (یک افزونه pi-agent-harness): درس‌های آموخته‌شده کاندیدا را از نشست‌ها جمع‌آوری کرده و در LESSONS.md ثبت می‌کند — و اصل «بر جای گذاشتن یک تحویل تمیز پیش از پایان هر نشست» را از یک عرف به یک سازوکار تبدیل می‌نماید.
• telemetry (یک افزونه pi-agent-harness): مصرف توکن، هزینه و سنجه‌های مرتبط را ثبت می‌کند — یعنی مشاهده‌پذیری.

همان مخزن جامعه کاربری الگوی کامل‌تری را نشان می‌دهد: VISION.md (اهداف)، PROGRESS.md (پیشرفت)، LESSONS.md (درس‌ها)، و STANDARDS.md (استانداردها) همگی فایل‌های Markdown هستند که در طول نشست‌ها ماندگار می‌مانند. این دقیقاً همان الگوی «مخزن به عنوان منبع مرجع + فایل‌های پیشرفت + سازوکار تحویل» پیشنهادی دوره است، که از طریق سازوکار افزونه‌های Pi به صورت آماده در دسترس قرار گرفته است.

نگاشت به چارچوب دوره#

امتیازدهی به Pi بر اساس پنج زیرسیستم دوره (ذهنی، صرفاً جهت مقایسه):

مصالحه‌های Pi در تضاد آشکار با Claude Code و Codex قرار دارد. ابزار Claude Code قابلیت‌های «حافظه، مجوزها و زیر-ایجنت‌ها» را برای تجربه کاربری آماده درون هسته می‌گذارد؛ Codex اصول «عرف‌های مخزن و ایزوله‌سازی محیط» را پیش‌فرض قرار می‌دهد. اما Pi ترجیح می‌دهد چیزی را برای شما تصمیم‌گیری نکند — بلکه تصمیم‌ها را به نقاط گسترش تبدیل می‌نماید. هزینه این رویکرد آن است که باید یا خودتان افزونه بنویسید یا بسته‌های نوشته‌شده توسط دیگران را نصب کنید.

طرح‌های شایسته الگوبرداری#

1. راهبرد فشرده‌سازی را پلاگین‌پذیر کنید. اینکه «زمینه چگونه فشرده می‌شود» در هارنس شما نباید یک پارامتر هاردکدشده باشد؛ باید یک اینترفیس راهبرد قابل تعویض باشد.
2. از درخت نشست به جای خلاصه‌های اجباری استفاده کنید. بازیابی بین‌نشستی نیازی نیست بر «خلاصه دور قبل» متکی باشد؛ بازپخش ساختاریافته تاریخچه اغلب زیرسیستم وضعیت مطمئن‌تری است.
3. با کش پرامپت مهربان باشید. مهارت‌ها را بر حسب تقاضا بارگذاری کنید، نه اینکه تمام قوانین را به یکباره درون پرامپت سیستم بریزید. این هم مهندسی زمینه است و هم مهندسی هزینه.
4. به ایجنت اجازه دهید هارنس خودش را اصلاح کند. اگر هارنس نقاط گسترش کافی فراهم کند، بهینه‌سازی رفتار ایجنت می‌تواند تا حدی توسط خود ایجنت خودکار شود.

مراجع (منابع اصلی / سورس کد)#

هر ادعایی را می‌توان در منابع اصلی یا سورس کدهای زیر ردگیری کرد:

• pi.dev: جایگاه‌یابی اصلی، «از Pi بخواهید آنچه می‌خواهید بسازد، یا بسته‌ای را نصب کنید که آن را مطابق میل شما انجام دهد»؛ چهار لایه قابل‌تنظیم؛ و درخت‌های نشست («نشست‌ها به صورت درخت ذخیره می‌شوند»، /tree، ذخیره‌سازی تک‌فایلی، خروجی HTML / اشتراک‌گذاری gist).
  https://pi.dev/
• pi.dev · Sessions: فشرده‌سازی پلاگین‌پذیر (موضوع‌محور / آگاه از کد / مدل خلاصه‌ساز جایگزین)، فشرده‌سازی خودکار و سازوکارهای تزریق زمینه پویا.
  https://pi.dev/docs/usage/sessions
• pi.dev · Extensions: افزونه‌ها می‌توانند قبل از هر دور استدلال پیام تزریق کنند، تاریخچه را فیلتر نمایند، RAG انجام دهند و حافظه بلندمدت بسازند.
  https://pi.dev/docs/usage/extensions
• pi.dev · Project Context: معناشناسی جایگزینی / الحاق در SYSTEM.md.
  https://pi.dev/docs/usage/project-context
• Pi Coding Agent README (badlogic/pi-mono): ترتیب بارگذاری سه‌سطحی AGENTS.md (سراسری ← پوشه‌های والد ← پوشه فعلی)، /compact و شرایط تحریک و نقطه برش 20,000 توکنی برای فشرده‌سازی خودکار، مهارت‌های بر حسب تقاضا و استاندارد Agent Skills، چرخه حیات هوک‌ها و چهار کاربرد نمونه رسمی، و استفاده برنامه‌نویسی (JSON / RPC / SDK).
  https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
• pi-agent-harness: افزونه‌های skill-router / session-summary / extract-patterns / telemetry و سیستم فایل‌های VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.
  https://github.com/LabidySabidy/pi-agent-harness

درس‌های مرتبط: درس 2 · هارنس در واقع چیست ｜ درس 5 · زنده نگه‌داشتن زمینه در طول نشست‌ها ｜ درس 13 · از پرامپت‌نویسی دستی تا حلقه‌های خودمختار