Install
npm i -g gentle-piلمن يصلح
Gentle Shell يناسب المطورين الذين يستخدمون Pi بالفعل كوكيل برمجة، ويريدون تطويراً مُتحكَّماً به، ويتوقعون أن يستكشف الوكيل قبل تعديل الكود، وأن يسأل فقط عند نقاط القرار الحقيقية، وأن يُبقي المهام الصغيرة المفهومة خطوات صغيرة. الاسم الرسمي لسير العمل اليومي هو Organic Driven Development (ODD): يستكشف الوكيل قبل أن يغيّر أي شيء، ويوضّح القرارات الحقيقية فقط، ويُبقي العمل الصغير المفهوم صغيراً. بعد التثبيت، تتحول جلسة Pi العادية إلى مساحة عمل: تنسيق الوكلاء، والتغييرات الحية وحالة التشغيل، ومراقبة الاستخدام للحسابات المدعومة من مزودين، وعروض diff المدمجة، كلها في واجهة واحدة. وتذكر الوثيقة الرسمية أيضاً SDD/OpenSpec (اختياري)، إضافة إلى subagents وأدلة TDD وreview guardrails وskills وتكاملات memory.
متى لا يصلح أو ما الذي يلزم قبله: إن كنت لا تستخدم Pi، فلا شيء في الوثائق الرسمية عن تشغيله داخل وكلاء آخرين. وإلى أن تكتمل الهجرة الرسمية، تبقى حزمة npm والمستودع بالاسم gentle-pi، أي أن اسم المنتج واسم الحزمة غير متطابقين. أنظمة التشغيل المطلوبة وإصدار Pi اللازم لا ذكر لهما؛ تحقق منهما بنفسك قبل التثبيت.
أول محاولة في 3 دقائق
ابدأ بقبول أثر جانبي وقت التثبيت تذكره الوثيقة الرسمية صراحة: gentle-pi يستبدل امتداد codemode المدمج في Pi بـ compact renderer الخاص به، وبعدها يحذّر Pi عند كل تشغيل من أن النسخة المدمجة لم تُحمَّل. بعبارة أخرى، هذا الأثر الجانبي يقع في خطوة التثبيت لا أثناء تنفيذ مهمة ما؛ وقرار التثبيت من عدمه هو قرار قبول ذلك من عدمه. من يعتمد على سلوك codemode المدمج فليقيّمه أولاً؛ وغيره يمكنه اعتبار تحذير التشغيل أمراً متوقعاً.
المسار الرئيسي الموصى به واحد فقط: ثبّت عالمياً في الطرفية باستخدام npm i -g gentle-pi. بعد التثبيت شغّل gentle-shell، فيفتح Pi ويحمّل حزمة Gentle Shell من مجلده الرئيسي الخاص ~/.gentle-shell/agent؛ وإن أردت التحميل من ~/.pi/agent القائم فأضف --link عند التشغيل. هذا مجرد تبديل لموضع التحميل كما توفره الوثائق الرسمية، وليس طريقة تثبيت ثانية؛ كلا الموضعين مذكور في التعليمات الرسمية، فاختر واحداً.
حسب الوصف الرسمي توجد إشارتا نجاح: الأولى أن ما يُفتح بعد التشغيل جلسة Pi محمَّلة بحزمة Gentle Shell؛ والثانية ظهور تحذير التشغيل بأن codemode المدمج لم يُحمَّل، وهو بالضبط الدليل على أن الاستبدال نافذ. كلتاهما تُلاحظان في أول شاشة بعد التشغيل، دون حاجة لتشغيل أي مهمة تغيّر شيئاً أولاً. للمهمة الأولى اختر مهمة صغيرة تحليلية بحتة على الكود، مثل أن تطلب من الوكيل قراءة وحدة ما وشرح بنيتها وعلاقات الاستدعاء فيها، دون أن يغيّر أي شيء في هذه المرحلة. مسار ODD بطبيعته الاستكشاف أولاً، فلا تغييرات تنشأ هنا؛ أما هل يكتب الوكيل ملفات مباشرة أو ينفذ أوامر أو يصل إلى الشبكة عند تنفيذ المهام لاحقاً فالوثيقة الرسمية لا تذكر، فلا تعتبره حقيقة مؤكدة وتحقق داخل الجلسة قبل أن تدعه يفعل.
حالات استخدام
الحالة الأولى: فهم كود غريب. ابدأ في الجلسة مهمة كهذه: اقرأ وحدة معينة أولاً، واشرح مسؤوليتها واعتماداتها، ولا تعدّل ملفات. هذا هو مسار ODD اليومي — الوكيل يستكشف أولاً ويسأل فقط عن نقاط القرار الحقيقية، والمهام الصغيرة تبقى صغيرة. إن سأل الوكيل بعد الاستكشاف، فبحسب وصف ODD الرسمي ينبغي أن تكون أسئلة تمس القرارات فعلاً. النتيجة المتوقعة شرح مبني على ذلك الاستكشاف؛ وصيغة الرد غير محددة رسمياً، فاحكم على أساس ما تنتجه الجلسة فعلاً.
الحالة الثانية: التحقق أثناء التعديل. اطلب من الوكيل تعديلاً صغيراً بينما تفحص كل تغيير في عرض diff المدمج؛ لوحا التغييرات الحية وحالة التشغيل يريانك ما يفعله الوكيل الآن، وإن كان حسابك لدى مزود مدعوم فظهرت مراقبة الاستخدام في الواجهة نفسها. قيمة هذه الحالة أن عملية التغيير تبقى مرئية: العروض توفرها الوثائق الرسمية، والتغييرات تولدها المهمة، ويمكن مقارنة الجانبين. وما الذي يُغيَّر يُتفق عليه مع الوكيل داخل الجلسة؛ والوثيقة الرسمية تغطي هذه العروض وقدرات الحالة فقط ولا تضمن جودة إعادة الكتابة.
حدود الاستخدام
الأثر الجانبي ونقاط التأكيد: تثبيت gentle-pi يستبدل codemode المدمج في Pi (يتولى المهمة compact renderer)، وتحذير التشغيل سلوك متوقع وليس عطلاً. عدى ذلك، لا شيء في الوثيقة الرسمية عن نطاق تنفيذ الأوامر أو قراءة الملفات وكتابتها أو الوصول إلى الشبكة؛ وقوع هذه السلوكيات أم لا أمر مجهول، فلا تفترض أنه للقراءة فقط. ولا تشرح الوثيقة كيف تُكتب تغييرات الجلسة إلى القرص ولا ما إذا كان كل خطوة تُؤكَّد؛ راقب سلوك الوكيل الفعلي داخل الجلسة ثم قرر الاستمرار.
متطلبات بيئة التشغيل: موجَّه لجلسات Pi ويُثبَّت عالمياً عبر npm؛ وإمكان استخدامه مع وكلاء آخرين واللغات المدعومة من كود أو نص لا ذكر لها. القيود المعلنة رسمياً: تبقى حزمة npm والمستودع بالاسم gentle-pi حتى تكتمل الهجرة، فاستمر اختلاف اسم المنتج عن اسم الحزمة؛ و--link لا يغيّر إلا موضع تحميل الحزمة. ما زال بلا تأكيد: كيفية الإعداد وإلغاء التثبيت، وهل يستعاد codemode المدمج بعد إلغاء التثبيت، وكيفية تفعيل SDD/OpenSpec وsubagents وأدلة TDD وreview guardrails وskills وتكاملات memory كلٌّ على حدة — الوثيقة تذكرها قدرات فقط دون خطوات.