تحليل تصميم harness في Pi

يصف Pi (حزمة npm‏ @earendil-works/pi-coding-agent) نفسه بأنه «minimal agent harness»—أي agent harness بالغ البساطة. وهذه عبارة تستحق التفكيك: فهو لا يصف نفسه بأنه «أقوى coding agent»، ولا «أفضل أداة برمجة بالذكاء الاصطناعي»، بل يرسخ موقعه في كلمة harness تحديدًا.

نحلل في هذه المقالة Pi باستخدام إطار الأنظمة الفرعية الخمسة في الدورة (التعليمات، والأدوات، والبيئة، والحالة، والتغذية الراجعة)، لنرى كيف تختلف فلسفة تصميمه جذريًا عن Claude Code وCodex. وإليك الجواب مقدمًا: فلسفة Pi هي «تقليص النواة إلى الحد الأدنى + جعل التوسعة قابلة للبرمجة»؛ فهي تدمج هندسة السياق خارج موجّه النظام، وتترك للمستخدم (بل ولـ Pi نفسه) تعديل harness، بدل أن يقرر Pi‏ harness بالنيابة عنك.

التعريف في جملة واحدة

Pi نواة شديدة البساطة: يتعمد تعريفه الرسمي تصغير النواة وإعادة سلطة القرار إليك—وتقول الصفحة الرئيسية لـ pi.dev حرفيًا: «اطلب من Pi بناء ما تريده، أو ثبّت حزمة تنفذه بطريقتك». ويقسّم harness إلى أربع طبقات قابلة للتخصيص:

• Extensions: hooks بلغة TypeScript مرتبطة بأحداث دورة حياة Pi، وهي واجهة برمجية على مستوى runtime.
• Skills: حزم قدرات تُحمّل عند الطلب، وتتضمن تعليمات وأدوات، وفق progressive disclosure.
• قوالب الموجّهات (Prompt templates): موجّهات Markdown قابلة لإعادة الاستخدام، تتوسع عند إدخال /name.
• السِّمات (Themes): مظهر TUI.

إن فكرة التقسيم الطبقي هذه في ذاتها تصميم لـ harness: يُترك تحديد «ما الذي يراه النموذج، ومتى يراه» بالكامل للقواعد والامتدادات، بدل ترسيخه داخل النواة.

الحلقة الجوهرية

Pi، مثل سائر coding agent، هو في جوهره حلقة while من «استدلال ← تنفيذ أداة ← ملاحظة ← استدلال مجدد». وما يستحق الاهتمام ليس الحلقة نفسها، بل كيفية تعامل Pi مع غلافها الخارجي: إذ وسّع إدارة السياق من «compaction» داخل الحلقة إلى «التحكم» خارجها.

يعرّض runtime الخاص بـ Pi واجهة برمجية—فإلى جانب TUI التفاعلية، تدعم فقرة Programmatic Usage في README للشيفرة المصدرية أوضاع الطباعة/JSON القابلة للبرمجة، وبروتوكول RPC، والتضمين عبر SDK. ويعني ذلك أن الإنسان يستطيع قيادة harness نفسه خطوة بخطوة، كما يستطيع CI/CD أو برنامج آخر قيادته آليًا. وهذا هو الشرط السابق لعبارة «من القيادة اليدوية إلى الحلقة التلقائية» في المحاضرة الثالثة عشرة: إذا لم يكن بالإمكان تشغيل harness إلا بالتفاعل البشري، فلن يدخل حلقة تلقائية أبدًا.

النظام الفرعي للتعليمات: AGENTS.md وSYSTEM.md

يتعامل Pi مع «التعليمات» بانضباط، لكن بتدرج واضح:

• AGENTS.md: يحدد قسم Project Context Files في README للشيفرة المصدرية ترتيب التحميل بوضوح—الملف العام ~/.pi/agent/AGENTS.md ← اجتياز الأدلة الأب صعودًا، مستوى بعد مستوى ← دليل العمل الحالي ./AGENTS.md (مع توافق أيضًا مع CLAUDE.md). وهذا تطبيق لمبدأ «المستودع هو مصدر الحقيقة»—فالتعليمات ملفات، لا تذكيرات في مربع محادثة.
• SYSTEM.md: تقول وثائق pi.dev الرسمية إنه يمكن، على مستوى المشروع، استبدال (replace) موجّه النظام الافتراضي أو الإضافة إليه (append). وهذه هي القناة الرسمية الوحيدة التي يتيحها Pi لتعديل «موجّه النظام»، كما أنها طبقة «الوصف الذاتي للبيئة» فيه.

تؤكد Pi رسميًا أن موجّه النظام نفسه شديد البساطة. ويكمن وراء ذلك اختيار واضح: لا تحشو النواة بقواعد مطولة من قبيل «إذا... فعندئذ...»، بل تترك نقاط توسعة لا تظهر فيها القواعد، على هيئة مهارات وامتدادات، إلا عند الحاجة. وهذا ينسجم مباشرة مع المحاضرة الرابعة، «لماذا يفشل ملف التعليمات العملاق الواحد؟»—إذ يتجنب Pi المشكلة بطبيعته عبر «نواة شديدة البساطة + تقسيم الملفات + التحميل عند الطلب».

الحالة والسياق: أكثر ما يفصله Pi دقة

تستحق هندسة السياق في Pi تحليلًا خاصًا، لأنها تحول مفاهيم الدورة مثل «استمرارية السياق» و«منع فساد السياق» إلى آليات ملموسة:

1. جعل Compaction قابلًا للبرمجة. عندما يقترب السياق من حده الأقصى، تُلخص الرسائل القديمة تلقائيًا—وتوضح وثائق pi.dev الرسمية أن استراتيجية compaction نفسها قابلة للتخصيص: يمكنك استخدام extension لتنفيذ compaction بحسب الموضوع، أو تلخيص واعٍ بالشيفرة، أو حتى استخدام نموذج مختلف للتلخيص. ويعرض README للشيفرة المصدرية تفاصيل الآلية الافتراضية أيضًا: ينطلق compaction التلقائي في حالتين (التعافي من تجاوز السياق / تجاوز عتبة الاحتفاظ)، وتبقي نقطة القطع أحدث 20 ألف token تقريبًا، بينما تُلخّص الرسائل الأسبق في «context handoff» وتخضع لـ compaction تسلسلي على مراحل. أي إن Pi لا يعامل «كيفية compaction» كثابت غير قابل للتغيير، بل كجزء من harness.

2. السياق الديناميكي (Dynamic context). تقول وثائق pi.dev الرسمية إن extensions تستطيع حقن الرسائل قبل كل جولة استدلال، وترشيح سجل الرسائل، وتنفيذ RAG، وبناء ذاكرة طويلة الأجل. وهذا يتجاوز «compaction بعد امتلاء السياق»: فهو يتيح لك أن تقرر ما يدخل النافذة وما لا يدخلها قبل وصول السياق إليها. ويقابل ذلك في الدورة «جعل عملية تشغيل الـ agent قابلة للرصد والتصحيح» و«الحفاظ على استمرارية السياق»؛ وقد نقل Pi كليهما إلى واجهة extensions.

3. شجرة session (Session tree). تذكر الصفحة الرئيسية لـ pi.dev صراحة أن "sessions are stored as trees"، وأن /tree يستطيع العودة إلى أي عقدة تاريخية ومواصلة العمل منها، مع حفظ جميع الفروع في ملف واحد. وهذا يحل مشكلة «انقطاع السياق بين sessions» التي تكرر الدورة التشديد عليها—لا بربط صلب عبر ملخص، بل بإعادة تشغيل السجل المنظم. ويمكن تصدير الفروع إلى HTML أو رفعها كـ gist للمشاركة، فتُحل قابلية الرصد في الوقت نفسه.

النظام الفرعي للأدوات: Skills وExtensions

تتكون «أدوات» Pi من طبقتين:

• Skills: يعرّفها قسم Skills في README للشيفرة المصدرية بوضوح بأنها "self-contained capability packages that the agent loads on-demand"؛ أي حزم قدرات تُحمّل عند الطلب، وتضم تعليمات وأدوات، وتتبع معيار Agent Skills. ولا تدخل تفاصيل skill السياق إلا عند تشغيلها بفضل progressive disclosure، فلا تفجّر prompt cache. وهذا تصميم لـ harness من زاوية التكلفة: كل token إضافية في السياق تُدفع تكلفتها في كل استدلال؛ لذا فإن تحميل Skills عند الطلب تعبير آخر عن «قدّم خريطة، لا دليل تعليمات».
• Extensions: hooks بلغة TypeScript متصلة بأحداث دورة الحياة المضمّنة—ويورد قسم Hooks في README للشيفرة المصدرية أمثلة رسمية للاستخدام: اعتراض الأوامر الخطرة (بوابة permissions)، وإنشاء checkpoint لحالة الشيفرة عند تبديل المهمة، وحماية المسارات (مثل منع الكتابة في .env)، وتعديل ناتج الأداة قبل تسليمه إلى النموذج، وحقن رسائل من الخارج (مراقبة ملف/Webhook/CI) لإيقاظ الـ agent. وتُصدّر واجهات API لهذه hooks أيضًا في @mariozechner/pi-coding-agent/hooks. أما harness المجتمعي pi-agent-harness فيغلف واجهة hooks كذلك في extensions جاهزة مثل skill-router وsession-summary وextract-patterns وtelemetry.

Extensions هي أهم قرارات تصميم Pi: فهو لا «يمنح المستخدم بضعة مفاتيح»، بل يعرض كامل واجهة الأحداث الداخلية لـ runtime. أتريد إضافة ذاكرة؟ احقنها عند agent/pre-step. أتريد تسجيل السلوك؟ اشترك في أحداث session. أتريد تعديل طلب النموذج؟ اربطه بـ agent/request. ويمكنك أن تجعل Pi يعدّل harness الخاص به بنفسه—وهذا أقرب إلى تعريف «harness قابل للبرمجة» من أي «خيار إعداد».

التغذية الراجعة والتحقق: تحويل «التعلم» نفسه إلى harness

لا يتضمن Pi نفسه بوابة اختبار إلزامية (على المستخدم كتابة أوامر التحقق في AGENTS.md)، لكن harness المجتمعي pi-agent-harness يستخدم extensions لتنظيم «حلقة التغذية الراجعة»، كما يقدّم قسم Hooks في README الرسمي أساسًا لآليات مشابهة:

• session-summary (امتداد pi-agent-harness): يحتفظ بإدخالات متجددة في PROGRESS.md—وهذا هو النظام الفرعي للحالة في الدورة، أي تتبع تقدم المهام الطويلة.
• extract-patterns (extension في pi-agent-harness): يجمع الدروس المستفادة المرشحة من session، ويرسخها في LESSONS.md—فيحوّل «إجراء تسليم جيد قبل نهاية كل session» من اتفاق إلى آلية.
• telemetry (امتداد pi-agent-harness): يسجل استخدام token والتكلفة وغيرها—أي قابلية الرصد.

ويبرهن المستودع المجتمعي نفسه على هذا النمط: VISION.md (الهدف)، وPROGRESS.md (التقدم)، وLESSONS.md (الخبرات)، وSTANDARDS.md (المعايير)، وكلها ملفات Markdown تُحفظ عبر sessions. وهذا النمط مطابق تمامًا لتوصية الدورة «المستودع هو مصدر الحقيقة + ملف تقدم + آلية تسليم»، لكن آلية Extensions في Pi حولته إلى طبقة جاهزة للاستخدام.

المواءمة مع إطار الدورة

تقييم Pi وفق الأنظمة الفرعية الخمسة للدورة (تقييم شخصي للمقارنة):

النظام الفرعي	تطبيق Pi	التقييم
التعليمات	تحميل AGENTS.md طبقيًا + SYSTEM.md	تدرج واضح، لكن على المستخدم كتابة القواعد نفسها
الأدوات	تحميل المهارات عند الطلب + خطافات امتداد تغطي دورة الحياة كلها	قوي جدًا، فقد حوّل نظام الأدوات إلى سطح قابل للبرمجة
البيئة	وصف ذاتي للبيئة عبر SYSTEM.md؛ ويصرّح المستخدم ببيئة التشغيل في AGENTS.md	الآلية مفتوحة، لكن قابلية إعادة الإنتاج تعتمد على وصف المستخدم
الحالة	شجرة جلسة + ضغط قابل للتخصيص + PROGRESS.md	قوي جدًا، فالعمل عبر الجلسات وقابلية الاستعادة في صميمه
التغذية الراجعة	يعرّف المستخدم أوامر التحقق؛ وتحوّلها session-summary / extract-patterns إلى آليات	الآلية متوفرة، والمحتوى على المستخدم

يشكل اختيار Pi تباينًا واضحًا مع Claude Code / Codex: يضمّن Claude Code «الذاكرة وpermissions وsubagents» كلها في النواة لتعمل فورًا؛ ويجعل Codex «مواصفات المستودع وعزل البيئة» افتراضيين؛ بينما يختار Pi ألّا يقرر شيئًا نيابة عنك—بل يحوّل سلطة القرار إلى نقاط توسعة. والثمن هو أن تكتب extensions بنفسك أو تثبّت حزمًا كتبها آخرون.

تصميمات جديرة بالاقتباس

1. جعل استراتيجية compaction قابلة للتوصيل. لا ينبغي أن تكون «كيفية compaction للسياق» في harness معلمة ثابتة، بل واجهة استراتيجية قابلة للاستبدال.
2. استخدام شجرة session بدل الملخص الصلب. لا يلزم أن تعتمد الاستعادة عبر sessions على «ملخص الجولة السابقة»؛ فإعادة التشغيل المنظمة للسجل نظام حالة أكثر موثوقية غالبًا.
3. مراعاة prompt cache. إن تحميل Skills عند الطلب وعدم حشر جميع القواعد في system prompt مرة واحدة هندسة للسياق وللتكلفة معًا.
4. تمكين الـ agent من تعديل harness الخاص به. إذا كان سطح توسعة harness مفتوحًا بما يكفي، فيمكن للـ agent نفسه تنفيذ «تحسين سلوك الـ agent» بصورة شبه تلقائية.

المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)

يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:

• pi.dev: عبارة التعريف الأصلية "Ask Pi to build what you want, or install a package that does it your way"، والطبقات الأربع القابلة للتخصيص، وشجرة session ("sessions are stored as trees"، و/tree، والحفظ في ملف واحد، والتصدير إلى HTML / المشاركة عبر gist).
  https://pi.dev/
• pi.dev — Sessions: compaction القابل للتوصيل (بحسب الموضوع / واعٍ بالشيفرة / استبدال نموذج التلخيص)، ووصف آلية compaction التلقائي وحقن السياق الديناميكي.
  https://pi.dev/docs/usage/sessions
• وثائق pi.dev الرسمية · Extensions: تستطيع الامتدادات حقن الرسائل قبل كل جولة استدلال، وترشيح السجل، وتنفيذ RAG، وبناء ذاكرة طويلة الأجل.
  https://pi.dev/docs/usage/extensions
• وثائق pi.dev الرسمية · Project Context: دلالات replace / append في SYSTEM.md.
  https://pi.dev/docs/usage/project-context
• Pi Coding Agent README ‏(badlogic/pi-mono): ترتيب تحميل AGENTS.md في ثلاث درجات (العام ← الأدلة الأب ← الدليل الحالي)، وشروط تشغيل /compact وcompaction التلقائي ونقطة القطع عند 20 ألف token، وتحميل Skills عند الطلب ومعيار Agent Skills، ودورة حياة Hooks وأمثلة الاستخدام الرسمية، وProgrammatic Usage ‏(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

المحاضرات ذات الصلة: المحاضرة الثانية · ما هو Harness بالضبط؟ ｜ المحاضرة الخامسة · الحفاظ على استمرارية سياق المهام عبر sessions ｜ المحاضرة الثالثة عشرة · من القيادة اليدوية إلى الحلقة التلقائية