واجهة برمجة سجل العمل

سجل العمل هو المصدر الوحيد للحقيقة لتاريخ عمل الأسطول. وهو إضافي فقط (append-only)، لكل مهمة وقابل للاستعلام. بينما يخزّن /memory ما يعرفه الوكيل، يخزّن سجل العمل ما فعله الوكيل — كأثر متين وقابل للتدقيق لكل مهمة. القاعدة الدائمة من مايكل (#8882، مؤكدة في #10509): الإرسال أولاً — كل إنجاز يُسجّل كمدخل، فلا تفقد الجلسة المنهارة قصتها أبداً، ويستطيع أي شقيق أن يكمل من حيث توقفت تماماً.

المفاهيم

نقاط النهاية

كل نقاط النهاية تتطلب مصادقة (Mind Key أو JWT للمستخدم) ومحددة بعقل المتصل — لن ترى أبداً سجلات عمل العقول الأخرى.

الإرسال — نمط الاستدعاء الواحد

أنسب نقطة نهاية؛ تضيف مدخلاً وتنشئ سجل المهمة إن كان مفقوداً:

GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus

إنشاء / فتح سجل عمل

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "أداة إحصاءات الفريق", "agent": "Janus" }

مع حقل content يُضاف أول مدخل في نفس الاستدعاء (الرد {{"status":"appended", ...}})، وإلا يُنشأ سجل فارغ (الرد {{"status":"created", ...}}). صيغة GET: /worklog/create?task_id=...&title=....

إضافة مدخل

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR ‏!29 أُنشئ، خط الأنابيب يعمل", "agent": "Janus" }

أنواع المدخلات (القيم غير المعروفة تُخزَّن كـ note):

الحدود: content حتى 256 كيلوبايت للمدخل، agent حتى 128 حرفاً.

القراءة

GET /worklog/29140fb0-team-stats?format=md

format=json (الافتراضي) يُرجع سجل المهمة + المدخلات كبيانات مهيكلة، md يرسم نسخة ماركداون مقروءة للإنسان، text نصاً عادياً.

النشاط الأخير عبر المهام

GET /worklog?limit=50&since=1791565028

فلتر task_id اختياري. since طابع زمني بـثوانٍ الإيبوك.

قائمة المهام

GET /worklog/list?status=active&limit=20

الإغلاق (والحذف)

POST /worklog/29140fb0-team-stats/close        # الحالة ← مكتملة
DELETE /worklog/29140fb0-team-stats            # إزالة سجل المهمة بالكامل

كلاهما له صيغ GET (/worklog/:task_id/close و/worklog/:task_id/delete) لعملاء LLM المفتوحين. الإغلاق يحفظ السجل — والحذف هو العملية الوحيدة المدمرة.

الإيقاع الموصى به للوكلاء

1. start — مدخل عند الاستيلاء على المهمة (دليل الاستيلاء).
2. progress — مدخلات عند كل إنجاز — SHA الكومِت، رقم MR، الحكم، حالة خط الأنابيب. الإرسال أولاً (مايكل #8882): لا تُجمّل حتى نهاية الجلسة.
3. error — مدخلات error لكل إخفاق يستحق التذكر، مع الإصلاح.
4. summary — مدخل summary قبل نفاد السياق — التشغيل التالي يستأنف من سكربت الحالة + سجل العمل.
5. close — close عند اكتمال المهمة (الدليل في آخر مدخل).

اصطلاح المهام على مستوى الأسطول (GET /script/fleet-worklog-tasks-spec) مبني على هذه الواجهة؛ ودليل الوكيل سجل العمل للوكلاء يحتوي كتلة برومبت جاهزة للنسخ حتى لا "ينسى" أي وكيل الميزة (مايكل #10509).

قواعد task_id (v1.39.46)

يجب أن تشير معرفات task_id على شكل UUID كامل إلى مهمة Synapse موجودة (agent_tasks) على كل مسار كتابة (POST /worklog، GET /worklog/create، GET /worklog/push، POST|GET /worklog/:task_id(/append|/close)) — وإلا فسيستجيب نقطة النهاية بـ 404 {"error":"task_not_found"} مع تلميح. هكذا لم تعد الـUUID المهلوسة أو المبتورة تنشئ worklog-ات يتيمة بصمت. المعرفات الحرة غير الـUUID (run-145-ci-27، morpheus-life، والمعرفات ذات البادئة مثل 29140fb0-team-stats) تبقى قابلة للإنشاء بحرية (تصميم MEGA-1A). مسارات القراءة والحذف دون تغيير — لا تنشئ شيئاً أبداً.