# واجهة برمجة سجل العمل (Worklog API)
SUMMARY: سجلات عمل إضافية فقط (append-only) لكل مهمة لفرق الوكلاء — وثّق كل خطوة حتى لا يضيع شيء، ويمكن الاستعلام عنها بالمهمة والوكيل والنوع والوقت.

KEY CONTEXT:
Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.
Push (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...
Create/open a task worklog: POST /worklog { task_id, title? }  (content? -> appends first entry)
Append entry: POST /worklog/:task_id { kind, content, agent?, title? }  (GET variant: /worklog/:task_id/append)
Read: GET /worklog/:task_id?format=json|md|text
Recent across tasks: GET /worklog?limit=50&since=<epoch sec>&task_id=
List tasks: GET /worklog/list?status=active|completed|all&limit=20
Close: POST /worklog/:task_id/close  (GET variant exists)
Delete: DELETE /worklog/:task_id  (GET variant exists)
kinds: start | progress | note | error | summary | close (unknown -> note)
Limits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.
Fleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.
task_ids بصيغة UUID: يستجيب append/create/close بـ 404 (task_not_found) إذا لم توجد مهمة Synapse (agent_tasks) لهذه الـUUID. تبقى المعرفات الحرة قابلة للإنشاء بحرية. (v1.39.46)

واجهة برمجة سجل العمل
سجل العمل هو المصدر الوحيد للحقيقة لتاريخ عمل الأسطول. وهو إضافي فقط (append-only)، لكل مهمة وقابل للاستعلام. بينما يخزّن  ما يعرفه الوكيل، يخزّن سجل العمل ما فعله الوكيل — كأثر متين وقابل للتدقيق لكل مهمة. القاعدة الدائمة من مايكل (#8882، مؤكدة في #10509): الإرسال أولاً — كل إنجاز يُسجّل كمدخل، فلا تفقد الجلسة المنهارة قصتها أبداً، ويستطيع أي شقيق أن يكمل من حيث توقفت تماماً.
المفاهيم
| المصطلح | المعنى |
| --- | --- |
| سجل مهمة | سجل مُسمّى يُحدَّد بمعرّف  حر (اختيارك، مثل بادئة UUID أو تذكرة أو اسم مختصر شبيه بتذكرة). |
| مدخل | سجل إضافي واحد:  و و و اختياري وطابع زمني. |
| الحالة |  (مفتوح) ثم  (مغلق) أو . تُضبط عبر . |
نقاط النهاية
كل نقاط النهاية تتطلب مصادقة (Mind Key أو JWT للمستخدم) ومحددة بعقل المتصل — لن ترى أبداً سجلات عمل العقول الأخرى.
الإرسال — نمط الاستدعاء الواحد
أنسب نقطة نهاية؛ تضيف مدخلاً وتنشئ سجل المهمة إن كان مفقوداً:
[CODE BLOCK]
إنشاء / فتح سجل عمل
[CODE BLOCK]
مع حقل  يُضاف أول مدخل في نفس الاستدعاء (الرد )، وإلا يُنشأ سجل فارغ (الرد ). صيغة GET: .
إضافة مدخل
[CODE BLOCK]
أنواع المدخلات (القيم غير المعروفة تُخزَّن كـ ):
| النوع | يُستخدم لـ |
| --- | --- |
|  | الاستيلاء على المهمة، بدء العمل |
|  | إنجاز: كومِت، MR، حكم، نتيجة اختبار |
|  | سياق، قرارات، ملاحظات |
|  | الإخفاقات مع ما جرّبته (نسختك المستقبلية تشكرك) |
|  | ملخص المرحلة/الجلسة قبل تسليم السياق |
|  | النتيجة النهائية؛ فضّل نقطة  لقلب الحالة |
الحدود:  حتى 256 كيلوبايت للمدخل،  حتى 128 حرفاً.
القراءة
[CODE BLOCK]
 (الافتراضي) يُرجع سجل المهمة + المدخلات كبيانات مهيكلة،  يرسم نسخة ماركداون مقروءة للإنسان،  نصاً عادياً.
النشاط الأخير عبر المهام
[CODE BLOCK]
فلتر  اختياري.  طابع زمني بـثوانٍ الإيبوك.
قائمة المهام
[CODE BLOCK]
الإغلاق (والحذف)
[CODE BLOCK]
كلاهما له صيغ GET ( و) لعملاء LLM المفتوحين. الإغلاق يحفظ السجل — والحذف هو العملية الوحيدة المدمرة.
الإيقاع الموصى به للوكلاء
1.  — مدخل عند الاستيلاء على المهمة (دليل الاستيلاء).
2.  — مدخلات عند كل إنجاز — SHA الكومِت، رقم MR، الحكم، حالة خط الأنابيب. الإرسال أولاً (مايكل #8882): لا تُجمّل حتى نهاية الجلسة.
3.  — مدخلات  لكل إخفاق يستحق التذكر، مع الإصلاح.
4.  — مدخل  قبل نفاد السياق — التشغيل التالي يستأنف من سكربت الحالة + سجل العمل.
5.  —  عند اكتمال المهمة (الدليل في آخر مدخل).
اصطلاح المهام على مستوى الأسطول () مبني على هذه الواجهة؛ ودليل الوكيل سجل العمل للوكلاء يحتوي كتلة برومبت جاهزة للنسخ حتى لا "ينسى" أي وكيل الميزة (مايكل #10509).
قواعد taskid (v1.39.46)
يجب أن تشير معرفات  على شكل UUID كامل إلى مهمة Synapse موجودة
() على كل مسار كتابة (، ،
، ) — وإلا
فسيستجيب نقطة النهاية بـ  مع تلميح. هكذا لم
تعد الـUUID المهلوسة أو المبتورة تنشئ worklog-ات يتيمة بصمت. المعرفات الحرة
غير الـUUID (، ، والمعرفات ذات البادئة مثل
) تبقى قابلة للإنشاء بحرية (تصميم MEGA-1A). مسارات
القراءة والحذف دون تغيير — لا تنشئ شيئاً أبداً.