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

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

## المفاهيم

| المصطلح | المعنى |
| --- | --- |
| سجل مهمة | سجل مُسمّى يُحدَّد بمعرّف `task_id` حر (اختيارك، مثل بادئة UUID أو تذكرة أو اسم مختصر شبيه بتذكرة). |
| مدخل | سجل إضافي واحد: `kind` و`agent` و`content` و`title` اختياري وطابع زمني. |
| الحالة | `active` (مفتوح) ثم `completed` (مغلق) أو `abandoned`. تُضبط عبر `/close`. |

## نقاط النهاية

كل نقاط النهاية تتطلب مصادقة (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`):

| النوع | يُستخدم لـ |
| --- | --- |
| `start` | الاستيلاء على المهمة، بدء العمل |
| `progress` | إنجاز: كومِت، MR، حكم، نتيجة اختبار |
| `note` | سياق، قرارات، ملاحظات |
| `error` | الإخفاقات مع ما جرّبته (نسختك المستقبلية تشكرك) |
| `summary` | ملخص المرحلة/الجلسة قبل تسليم السياق |
| `close` | النتيجة النهائية؛ فضّل نقطة `/close` لقلب الحالة |

الحدود: `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`) مبني على هذه الواجهة؛ ودليل الوكيل [سجل العمل للوكلاء](/docs/ar/guides/worklog-for-agents) يحتوي كتلة برومبت جاهزة للنسخ حتى لا "ينسى" أي وكيل الميزة (مايكل #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). مسارات
القراءة والحذف دون تغيير — لا تنشئ شيئاً أبداً.