Pi Durable عملياً: استئناف عمل الوكلاء دون تكرار الآثار

يمكن أن يساعد Pi Durable الوكيل على استئناف عمله بعد إعادة النشر، لكن حفظ محادثته لن يمنعه من إرسال الفاتورة نفسها مرتين.

استئناف العمل يحتاج إلى أكثر من سجل محادثة محفوظ

تخيّل وكيلاً أمضى 40 دقيقة في مهمة صيانة: فحص مستودعاً، وسجّل خطة، وبدأ عملية نشر، ثم استُبدلت الحاوية التي يعمل فيها. قد يوضح سجل المحادثة ما كان الوكيل ينوي فعله، لكن استئناف العمل يحتاج أيضاً إلى معرفة ما اكتمل، وما حُفظ من تغييرات الحالة، وما إذا كانت عملية النشر قد حدثت فعلاً.

يوفر Pi Durable آليات حفظ البيانات وتنفيذ العمل لمعالجة هذه المشكلة. صدر بالتزامن مع Pi 1.0 من مطوري وكيل البرمجة Pi، الذي أصبح الآن تحت مظلة Earendil. وهو مكتبة تبني تطبيقك بالاعتماد عليها، وتوفر مكونات منفصلة لسجل المحادثة وحالة التطبيق والعمل غير المكتمل:

يمكن لعملية تثبيت واحدة (commit) أن تحفظ معاً إدخالات سجل المحادثة، وتغييرات Document، ومهام Task الجديدة، وتحديثات Submission. وبذلك، لا يجد نظام الاستئناف قراراً مسجلاً من دون التحديث المقابل له في حالة التطبيق. لكن هذا الضمان لا يتجاوز حدود التخزين: فلا يمكنه جعل تثبيت معاملة في قاعدة البيانات وتسليم بريد إلكتروني عبر خدمة خارجية عملية واحدة لا تقبل التجزئة.

ثبّت إصدارات محددة، ثم اربط الاستئناف ببدء التشغيل

ابدأ بالحزم المذكورة في المستودع الرسمي:

bashCopy
npm install --save-exact @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

يسجّل الخيار --save-exact إصدارات محددة للاعتماديات المباشرة. أضف كلاً من package.json وملف القفل إلى نظام التحكم بالإصدارات: فما زال Pi Durable تجريبياً، وقد تتغير واجهة API الخاصة به. استخدم الأمثلة الحالية في المستودع لبناء التطبيق كاملاً، ولا تخمّن الوسائط المطلوبة لدوال الإنشاء.

ينبغي أن يشمل تسلسل بدء التشغيل الخطوات التالية:

1. افتح مساحة تخزين SQLite باستخدام openNodeSqliteStorage('./agent.sqlite')، بعد استيرادها من @earendil-works/pi-durable/storage/sqlite/node.
2. مرّر مساحة التخزين إلى Harness.open.
3. استدعِ harness.resume عند كل بدء تشغيل، وقبل قبول أي مدخلات جديدة.
4. أرسل المدخلات الجديدة عبر root.submit.
5. احتفظ بهوية Submission حتى تتمكن الجهات المستدعية من العثور عليه وانتظار اكتماله بعد إعادة التشغيل.

يجب أن تؤدي إعادة تشغيل التطبيق إلى استئناف العمل المحفوظ، لا إلى إرسال الطلب الأصلي كمهمة جديدة.

إذا كان لديك وكيل لفرز الطلبات يعمل عبر webhook، فمرّر مع الإرسال قيمة ثابتة لـ requestId، مثل job-42. وفقاً لـ توثيق Pi Durable وأمثلته، تعيد المحاولة بهذا المعرّف كائن Submission الموجود بالفعل. استخدم المعرّف الثابت للحدث الوارد متى أمكن. فتوليد معرّف جديد عند كل محاولة تسليم يلغي فائدة منع التكرار.

صنّف كل أداة قبل كتابة تعليمات النموذج

تحتاج أدوات وكيل العمليات إلى سياسات مختلفة للاستئناف: فقراءة الإعدادات ليست مثل التحقق من حالة النشر، ولا مثل بدء عملية نشر.

يجعل Pi Durable، من خلال defineTool، أمان إعادة التنفيذ خياراً صريحاً. فإذا انقطع تنفيذ أداة تحمل علامة الأمان، يمكن تشغيلها مجدداً. أما الأداة التي لا تحمل هذه العلامة، فيُبلغ Harness النموذج بانقطاعها، كما يوضح الإعلان الرسمي.

وهذا هو السلوك الافتراضي المناسب. فقد تتوقف العملية بعد أن تقبل خدمة خارجية الطلب، وقبل أن يسجّل الوكيل النتيجة، لتبقى النتيجة غير مؤكدة.

مفتاح منع تكرار الأثر (idempotency key) هو معرّف ثابت يتيح للخدمة التعرّف على الطلبات المتكررة للعملية نفسها. احتفظ بهذا المعرّف عبر جميع المحاولات.

يمكن لـ Document تتبّع الإجراءات المكتملة ومعرّفات العمليات الخارجية. لكنه لا يلغي احتمال التعطل بين نجاح الإجراء الخارجي وتثبيت سجل اكتماله محلياً. لذلك، يحتاج الاستئناف إلى وسيلة للاستعلام من المزوّد أو حسم هذا الغموض بطريقة أخرى.

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

SQLite هو الخيار الافتراضي، لكن التخزين الدائم يحتاج إلى جهة واحدة تديره

إذا كتبت الحاوية الملف ./agent.sqlite في نظام ملفات مؤقت، فستفقد حالتها المحفوظة عند زواله. ضع الملف على وحدة تخزين دائمة قبل اختبار الاستئناف.

يوصي المستودع الرسمي باستخدام SQLite للوكلاء الذين يعملون لفترات طويلة. اختر نظام تخزين آخر لتلبية حاجة محددة، لا لمجرد افتراض أن قاعدة البيانات المضمّنة محدودة بطبيعتها.

يحفظ JSONL سجل JSON واحداً في كل سطر. وصيغته المقروءة مفيدة، لكن الاحتفاظ بالسجل في الذاكرة يجعله خياراً افتراضياً غير مناسب لوكيل يستمر سجله في النمو بلا حد. توفر المكتبة أيضاً واجهة تخزين صغيرة، واختبارات توافق، واختبارات قياس أداء للتنفيذات المخصصة. تساعد هذه الأدوات على التحقق من محوّل التخزين، لكنها لا تجعل أي نظام مقترح يعتمد على Postgres أو تخزين المفتاح والقيمة جاهزاً للإنتاج تلقائياً.

ضع قواعد واضحة للنشر:

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

لن يعيد Pi Durable تشغيل العملية بنفسه. على Server يعمل بنظام Linux، يُعد systemd مع Restart=always خياراً بسيطاً. أما في الحاويات، فاستخدم سياسة لإعادة التشغيل ووحدة تخزين دائمة موصولة بالحاوية. تتولى SQLite حفظ بيانات قاعدة البيانات بشكل دائم. ومع ذلك، تحتاج كل عملية بديلة إلى استدعاء harness.resume.

أضف قدرات للوكيل من دون إخفاء المخاطر التشغيلية

وكيل برمجة يعمل طوال الليل خيار منطقي كتطبيق أول، لأن المستودع الرسمي يتضمن بالفعل مثالاً صغيراً لوكيل برمجة. ولحفظ حالة التخطيط في بيانات منظمة، اتبع مثال مخطط الإجازات واحتفظ بالتقدم في كائنات Document.

تغطي القدرات المدمجة ونقاط التوسعة احتياجات متعددة:

توفر CodingTools، من @earendil-works/pi-durable/tools، أدوات القراءة والكتابة والتحرير وbash. وتشغّلها NodeExecutionEnv، من @earendil-works/pi-durable/env/node، محلياً، لذا فصلاحياتها هي الصلاحيات التي تمنحها لوكيلك.

في محادثة خاصة بالعمليات، يمكن استخدام thread.configure({ tools: { remove: [deploy] } }) لإلغاء الوصول إلى أداة نشر. ضع آليات الموافقة والتدقيق في غلاف للأداة. لا تعتمد على تعليمات النموذج وحدها لتذكّر السياسة.

يمكن للإضافات إضافة أدوات، وخطافات (hooks)، وأقسام لتعليمات النموذج عبر section، وأغلفة عبر wrapTool، ومهام مخصصة عبر defineTask. يتيح النمط الموثّق registry.install(await loadExtension('./ops.ts')) تحميل شيفرة إضافات جديدة أثناء تشغيل الوكيل، لكن التغييرات أثناء التشغيل تحتاج هي الأخرى إلى اختبارات استئناف.

يستخدم المثال الرسمي لتقليص السياق reserveTokens: 16384 وbackgroundTokens: 32768. ويتحكم التقليص في ما يدخل إلى سياق النموذج من دون حذف السجل المحفوظ بشكل دائم.

لا توجد وكلاء فرعية مدمجة. وتوضح الأمثلة كيفية تنفيذ وكيل فرعي كأداة، مع استخدام api.createTask وapi.waitForTask لدعم المهام الفرعية.

اختبر الاستئناف بعد التعطل قبل ترك الوكيل دون إشراف

اختبر انقطاع عملية نشر بعد أن تقبل الخدمة الخارجية الطلب، وقبل أن يحفظ الوكيل نتيجته. فهذا اختبار أفضل للقدرة على التعافي من التعطل مقارنة بإيقاف عملية خاملة والتأكد من ظهور رسائلها مجدداً.

تمثل الأمثلة الرسمية، ضمن packages/durable/test/examples، أفضل نقطة بداية، لأنها تواكب تغييرات API بدرجة لا يستطيع مقال في مدونة مجاراتها. استخدمها لاختبار سير العمل الذي اخترته، ثم أضف حالات تعطل عند نقاط تنفيذ آثاره الخارجية.

يناسب Pi Durable مهام البرمجة الطويلة، وأدوات التخطيط المنظمة، وفرز الطلبات عبر webhook، وسير عمل العمليات ذي سياسات الاستئناف الواضحة. ولا تحتاج إليه للسكربتات التي تعمل مرة واحدة، أو المحادثات عديمة الحالة، أو إذا كان فريقك يحتاج إلى API مستقرة خلال الربع الحالي.

تبقى مسؤولاً عن بيانات اعتماد النموذج، والأدوات، وواجهة المستخدم، ونسخ التخزين الاحتياطية وتنظيفه، والإشراف على العملية، وضوابط أمان الإجراءات الخارجية. يشرح التوثيق أيضاً كيفية تكييف التخزين للعمل مع Bun أو Cloudflare Durable Object، لكن هذه التكاملات تحتاج إلى إعداد.

قائمة التحقق من التنفيذ

• ثبّت باستخدام --save-exact، ثم أضف package.json وملف القفل إلى نظام التحكم بالإصدارات.
• صنّف كل أداة باعتبارها آمنة للتكرار أو بحاجة إلى معالجة الانقطاع، قبل السماح بالتنفيذ دون إشراف.
• أرسل حدث webhook نفسه مرتين باستخدام requestId نفسه، وتأكد من أن الإرسال يعيد Submission الموجود بالفعل.
• أعد تشغيل العملية أثناء دورة استجابة النموذج وأثناء استدعاء أداة، وتأكد من أن harness.resume يستعيد العمل من قاعدة البيانات الدائمة.
• اقطع عملية كتابة خارجية واحدة بعد قبولها، ثم تحقق من أن الاستئناف يحسم نتيجتها من دون تكرارها بشكل أعمى.

مصادر مفيدة

• موقع Pi الرسمي - وكيل Pi ومشروعه.
• إعلان Pi Durable - التصميم والنطاق والطابع التجريبي.
• مستودع Pi الرسمي - ملف README الخاص بـ Pi Durable والأمثلة ضمن packages/durable/test/examples.
• SQLite - قاعدة البيانات التي يعتمد عليها نظام التخزين الموصى به.
• systemd - الإشراف على العمليات في Linux.

الخلاصة

يتيح Pi Durable استئناف العمل بعد انقطاعه، لكن القواعد التي تحدد سلوك أدواتك هي ما يقرر إن كان الاستئناف آمناً. ابدأ بوكيل واحد محدود النطاق، وتخزين SQLite دائم، واختبار تعطل مخطط له عند أخطر إجراء خارجي ينفذه. ولا توسّع استقلاليته إلا عندما يعطي هذا الاختبار نتيجة يمكنك تفسيرها.