شرح agent-purge: تدبير موحّد لتعليمات النظام وPersona ديال Coding Agent

شنو هو agent-purge

agent-purge هو أداة لتدبير تعليمات النظام ديال بزاف ديال Coding Agent. كل Agent يقدر يقرا التعليمات عبر بارامترات التشغيل، ملفات الإعداد، Hooks ولا الإضافات، وagent-purge كيغلف هاد الاختلافات باش يقدر المستخدم يدير الحقن والتبديل والتراجع انطلاقاً من نفس محتوى Persona.

المشروع كيدعم ثلاثة ديال المودات:

• replace: كيستعمل النص الكامل ديال Persona وكيعوّض به تعليمات النظام المستهدفة.
• append: كيزيد النص الكامل ديال Persona فآخر التعليمات الحالية.
• off: كيطفي الحقن وكيرجع التغييرات.

يمكن تبديل المودات مباشرة. منين كتطفي المفتاح العام ديال الويب ولا كتستعمل --mode off، الأداة كترجع التغييرات المرتبطة للحالة الأصلية، بلا ما تخلي بقايا ديال الحقن المُدار.

الآلية والوظائف الأساسية

ثلاث قنوات موحّدة

agent-purge كيستعمل ثلاثة ديال القنوات باش يتأقلم مع Harness مختلفين. القنوات الثلاثة كاملين كيستعملو فالنهاية محتوى الملف الحالي personas/<id>.md.

• install: كيكتب كتلة إعداد مُدارة فـ Harness المستهدف، وقد يستعمل Markdown ولا Hooks ولا آلية الإضافات. هادي إعدادات دائمة، وكتخدم حتى ملي شي واحد آخر كيشغل Harness المعني مباشرة.
• shim: كيحط غلاف بنفس اسم الأمر فالأولوية فـ PATH، ومن بعد كيحوّل الاستدعاء لـ agent-purge <h>، وبهذا كيتكلف بالأمر الأصلي اللي كيتكتب مباشرة.
• slash: كيسمح بالتبديل مباشرة داخل الجلسة باستعمال /purge on ولا /purge off ولا /purge status، بلا ما يبدل إعدادات القرص.

محلي وقابل للتراجع

المشروع كيبدل غير المواضع المرتبطة بالتعليمات، وما كيبدلش الملفات الثنائية وما كيكسّرش ولا كيدوز من الترخيص. الحالة كتتحفظ فالجهاز المحلي داخل state.json وما كتترفعش. تقدر ترجع للحالة الأصلية عبر إلغاء التثبيت، أو فكّ التحكم، أو طفي المود.

agent-purge uninstall <h>
agent-purge disarm
agent-purge <h> --mode off

القنوات اللي كيدعمها كل Harness خاصها تتحدد حسب نتيجة الكشف وقت التشغيل فالجهاز المحلي.

المتطلبات قبل التثبيت

باش تشغل agent-purge خاصك Node.js 20 ولا إصدار أحدث. المشروع ما فيه حتى اعتماد خارجي، وتقدر تثبتو بشكل عالمي عبر npm، ولا تستعمل npx مباشرة باش تفتح لوحة الويب.

التثبيت والتشغيل الأول

الطريقة الأولى: التثبيت العالمي

npm i -g agent-purge

من بعد ما يكمل التثبيت، تقدر تشغلو مباشرة:

agent-purge web

العنوان الافتراضي للوحة المحلية هو http://127.0.0.1:7788. حلّ هاد العنوان فالمتصفح باش تشوف وتدبّر Persona وحالة Harness والمفتاح العام.

الطريقة الثانية: التشغيل عبر npx

إلا ما بغيتيش تدير التثبيت العالمي قبل، تقدر تشغل مباشرة:

npx agent-purge web

مجلد البيانات

الإعدادات وPersona ما كيتحطوش فمجلد حزمة npm، وبهذا ترقية الحزمة ما كتغطّيش على بيانات المستخدم. المكان الافتراضي هو:

• Linux وmacOS: ~/.agent-purge/
• Windows: C:\Users\<ديالك>\.agent-purge\

المجلد كيضم بالأساس state.json وpersonas/. فأول تشغيل، الأداة كتولّد قالب البداية neutral.md داخل مجلد Persona.

إلا سبق ليك استعملتي الإصدار 0.1.x، فأول تشغيل للإصدار الجديد غادي ينقل أوتوماتيكياً البيانات اللي كانت فمجلد الحزمة، مع الاحتفاظ بالملفات الأصلية.

تخصيص مكان تخزين البيانات

تقدر تحدد مجلد مستقل للبيانات باستعمال متغير البيئة AGENT_PURGE_HOME. هاد الشي مناسب إلا بغيتي تدير نسخ احتياطية لـ Persona، تفرّق بين بيئات الخدمة، ولا تحط الإعدادات فقرص آخر.

Linux أو macOS

export AGENT_PURGE_HOME=/path/to/your/data

Windows

setx AGENT_PURGE_HOME D:\ap-data

من بعد الإعداد، خاصك تشغل agent-purge فجلسة طرفية جديدة باش تتأكد أن متغير البيئة خدام.

فهم وتدبير Persona

كل Persona كيقابلها ملف personas/<id>.md. الملف مكوّن من Frontmatter والنص، والنص هو المحتوى اللي كيتكتب فعلياً فتعليمات النظام.

Frontmatter كيدعم الحقول التالية:

• description: شرح Persona، وكيبان فلائحة الويب وفخرج agent-purge ls.
• desc: حقل الشرح القديم، وما زال مدعوماً.
• order: معلومات اختيارية للترتيب.
• harness: معلومات اختيارية لمطابقة Harness.
• model: معلومات اختيارية لمطابقة النموذج.

فلوحة الويب، ملي كتبدل غير الاسم والشرح، المفاتيح الأخرى ديال Frontmatter كيبقاو محفوظين وما كيتغطاوش كاملين.

عرض Persona

agent-purge ls

هاد الأمر كيعرض جميع Persona وكيعلّم على المطابقة الحالية. وكيتكلف حتى بعرض حالة تثبيت Harness اللي تكتاشفات وقت التشغيل، والإصدار، وطبقة الحقن، ومدى توفر كل قناة.

تبديل Persona الحالية

agent-purge use <id>

هنا <id> هو المعرف الاسمي ديال ملف Persona داخل مجلد personas/. من بعد التبديل، الاستدعاءات المُدارة من بعد غادي تستعمل هاد Persona.

تحديد Persona لاستدعاء واحد فقط

إلا ما بغيتيش تبدل الاختيار العام الحالي، تقدر تحدد Persona أخرى غير فهاد الاستدعاء:

agent-purge pi --persona <id>

هاد الطريقة مناسبة للتجارب المؤقتة مع تأثير تعليمات مختلفة، ومن بعد نهاية الاستدعاء ما غاديش تولّي هاد Persona هي الاختيار الافتراضي للاستدعاءات الجاية.

أمثلة أساسية للاستعمال

تشغيل لوحة الويب

agent-purge web

من بعد دخل لـ http://127.0.0.1:7788. اللوحة كتسمح لك تشوف الحالة وتتحكم فالمفتاح العام. ملي كتطفي المفتاح العام، كيتراجع الحقن.

تشغيل Codex باستعمال Persona الحالية

agent-purge codex

agent-purge كيعالج التشغيل حسب Backend المعني وبيئة الجهاز المحلي، وكيحاول يطبق Persona الحالية باستعمال الآلية المتاحة فعلياً فداك Harness.

طرح سؤال لمرة وحدة على pi

agent-purge pi --ask "راجع من فضلك منطق معالجة الأخطاء فهاد المشروع"

هاد الأمر كيشغل استدعاء واحد باستعمال Persona الحالية، وكيعتبر المحتوى اللي من بعد --ask هو السؤال ديال هاد الجولة.

التبديل المباشر داخل الجلسة

بالنسبة لـ Harness اللي كيدعمو قناة Slash، تقدر تستعمل داخل الجلسة:

/purge on
/purge status
/purge off

• /purge on: تفعيل حقن Persona.
• /purge status: عرض الحالة الحالية.
• /purge off: طفي الحقن بلا ما يبدل إعدادات القرص.

كيفاش تتأكد أن الحقن خدام بصح

matrix.json كيحفظ مصفوفة القدرات الثابتة، ولكن التصريح الثابت ماشي بالضرورة هو نفس الحالة الحقيقية فالجهاز الحالي. اختلاف الإصدارات، وطريقة التثبيت، والتغييرات فـ Harness نفسه، كلها تقدر تأثر على توفر القنوات.

لهذا خاصك تعطي الأولوية للمعلومات ديال وقت التشغيل اللي كيعطيها agent-purge ls ولا لوحة الويب. هاد المعلومات كتعكس:

• واش Harness مثبت ولا لا.
• إصدار Harness اللي تكتاشف.
• واش التعليمات كاينة فطبقة الحقن SYS ولا USER.
• واش القنوات الثلاثة install وshim وslash متاحة.

إلا كان تعارض بين جدول القدرات الثابت ونتيجة الكشف وقت التشغيل، اعتمد نتيجة وقت التشغيل.

تقنيات متقدمة للاستعمال

تحضير Persona متعددة للمهام المختلفة

تقدر تدير عدة ملفات Markdown داخل personas/، مثلاً ملفات منفصلة لمراجعة الكود، واقتراحات إعادة الهيكلة، ولا التعاون اليومي فالتطوير. استعمل description باش توضّح الاستعمال، واستعمل order لتبديل ترتيب العرض؛ وإلا بغيتي تحدد نطاق المطابقة، تقدر تستعمل الحقلين harness ولا model.

قبل التبديل شغّل:

agent-purge ls

ومن بعد ما تتأكد من Persona المستهدفة نفّذ:

agent-purge use <id>

التمييز بين الإعداد الدائم والتجربة المؤقتة

• إلا بغيتي المفعول يبقى دائماً، استعمل قناة install اللي كيدعمها Harness المستهدف.
• إلا بغيتي حتى الأمر الأصلي اللي كتكتبو مباشرة يتكلف به agent-purge، استعمل قناة shim.
• إلا بغيتي غير تجرب فالجلسة الحالية، فضّل قناة slash ولا بارامتر --persona لاستدعاء واحد.

إمكانية استعمال شي قناة خاصها تبقى دائماً مرتبطة بنتيجة الكشف وقت التشغيل.

خلي مسار للرجوع قبل التعديل

رغم أن المشروع كيحفظ الحالة وكيقدم عمليات قابلة للتراجع، من الأفضل عملياً تتأكد أولاً من Persona الحالية، وHarness المستهدف، والمود المفعّل. من بعد ما تسالي الاختبار، تقدر تتراجع بهاد الطرق:

agent-purge uninstall <h>
agent-purge disarm

وتقدر حتى تبدل لـ --mode off، ولا تطفي المفتاح العام من لوحة الويب.

ما تعتبرش التشغيل العادي دليلاً على نجاح الحقن

بالنسبة لبرامج سطح المكتب المغلقة اللي كتكون فيها تعليمات النظام فالخادم ولا داخل ملف ثنائي مغلق، agent-purge غير كيشغلها كيف ما هي، وما كينفذش حقن التعليمات. ملي كتشغل agent-purge <h>، الأداة كتوضح السبب اللي مانع الحقن، وما كتدّعيش أن الحقن خدم.

نظرة سريعة على بنية المشروع

• bin/: مدخل CLI.
• lib/: منطق الحالة وPersona والحقن والقنوات والكشف.
• backends/: بارامترات تشغيل Harness المختلفة ومعالجة جملة الهوية.
• web/: اللوحة المحلية، ومنها server.mjs وui.html.
• bench/: قياس نسبة نجاح الحقن وسكريبتات التحكيم، مخصصة للتطوير وما كتدخلش فالتشغيل العادي.
• matrix.json: مصفوفة القدرات الثابتة.

حدود الأمان والخصوصية والامتثال

agent-purge مخصّص للـ Harness الرسمي المحلي اللي عند المستخدم الحق يدبّرو، وكيستعمل فهندسة البرومبتات وتقييم المتانة. ما كيبدّلش الملفات الثنائية، وما كيتجاوزش التفويض، وما كيرفعش الحالة المحلية للخارج، وما خاصّوش يتستعمل فالأنظمة اللي ما عندكش عليها ترخيص.

• استعملو غير فالأجهزة والبرامج وبيئات التجارب المطابقة للقوانين اللي عندك الحق تتحكم فيها.
• ممنوع تستعملو فالهجمات غير المرخّصة، واستغلال الثغرات، وسرقة البيانات، والتسلل غير القانوني، ولا نشر الحمولات الخبيثة.
• ممنوع مخالفة القوانين والأنظمة المعمول بها، وشروط خدمات النماذج، وسياسات منع إساءة الاستعمال.
• المشروع كيتوفّر بموجب رخصة MIT «كما هو»، والمستخدم مسؤول على المدخلات والمخرجات وطريقة الاستعمال ديالو.
• إلى استعرت اسم المشروع، أو الأفكار، أو الكود، أو البرومبتات، خاصك تدير الإسناد وتبيّن المصدر حسب التصريح الموجود فالمستودع.

README كيتضمن حتى قيود صارمة على الولوج لسيرفرات ومواقع فمناطق معيّنة. قبل الاستعمال الفعلي، خاصك تقرا كامل تصريح إخلاء المسؤولية والامتثال الموجود فالمستودع، وتتأكد بلي نطاق العمليات ديالك مطابق للمتطلبات ديالو.

الخلاصة

agent-purge كيوحّد مداخل البرومبتات المختلفة ديال Coding Agent، اللي ماشي متناسقة، فمفاهيم بحال Persona وinstall وshim وslash، وكيقدّم كونصول ويب، وكشف أثناء التشغيل، وإمكانية التراجع القابلة للعكس. فالبداية، تقدر تثبّت الأداة، وتحلّ كونصول الويب، وتشغّل agent-purge ls باش تتأكد من الدعم، ومن بعد تختار Persona لتشغيل الـ Harness المستهدف. فالتجارب المؤقتة، الأفضل تستعمل Persona لمرة وحدة ولا التبديل السخون أثناء الجلسة؛ أما الإعدادات الدائمة، خاصك ما تفعّلش القنوات المستمرة حتى تتأكد من القدرات أثناء التشغيل ومن حدود الامتثال.