بنية تخزين البيانات الثنائية والقطع الأثرية

يصف هذا المستند كيفية قيام وكيل الترميز بتخزين الحمولات الكبيرة/الثنائية خارج جلسة JSONL، وكيفية استمرار مخرجات الأدوات المقتطعة، وكيفية تحليل عناوين URL الداخلية (artifact://، agent://) إلى البيانات المخزنة.

سبب وجود نظامَي تخزين

يستخدم وقت التشغيل آليتَين مختلفتَين للاستمرارية لأشكال بيانات مختلفة:

البيانات الثنائية المعنونة بالمحتوى (blob:sha256:<hash>): تخزين عام موجّه للثنائيات يُستخدم لاستخراج حمولات base64 للصور الكبيرة من إدخالات الجلسة المستمرة.
القطع الأثرية محددة النطاق بالجلسة (ملفات تحت <sessionFile-without-.jsonl>/): ملفات نصية لكل جلسة تُستخدم للمخرجات الكاملة للأدوات ومخرجات الوكلاء الفرعيين.

هما مفصولان عمداً:

يُحسّن تخزين البيانات الثنائية إلغاء التكرار والمراجع الثابتة بواسطة تجزئة المحتوى،
يُحسّن تخزين القطع الأثرية أدوات الجلسة للإلحاق فقط واسترجاع المستخدم/الأداة بواسطة معرفات محلية.

حدود التخزين والتخطيط على القرص

حد مخزن البيانات الثنائية (عام)

ينشئ SessionManager الكائن BlobStore(getBlobsDir())، لذا تقع ملفات البيانات الثنائية في دليل بيانات ثنائية مشترك عام (وليس في مجلد جلسة).

تسمية ملفات البيانات الثنائية:

مسار الملف: <blobsDir>/<sha256-hex>
بدون امتداد
سلسلة المرجع المخزنة في الإدخالات: blob:sha256:<sha256-hex>

الآثار المترتبة:

يتحلل نفس المحتوى الثنائي عبر الجلسات إلى نفس التجزئة/المسار،
الكتابات تكون مكافئة على مستوى المحتوى،
يمكن أن تتجاوز البيانات الثنائية أي ملف جلسة فردي.

حد القطع الأثرية (محلي للجلسة)

يشتق ArtifactManager دليل القطع الأثرية من مسار ملف الجلسة:

ملف الجلسة: .../<timestamp>_<sessionId>.jsonl
دليل القطع الأثرية: .../<timestamp>_<sessionId>/ (احذف .jsonl)

تشترك أنواع القطع الأثرية في هذا الدليل:

ملفات مخرجات الأدوات المقتطعة: <numericId>.<toolType>.log (لـ artifact://)
ملفات مخرجات الوكيل الفرعي: <outputId>.md (لـ agent://)

مخططات تخصيص المعرف والاسم

معرفات البيانات الثنائية: تجزئة المحتوى

تحسب BlobStore.put() SHA-256 على البايتات الثنائية الخام وتُعيد:

hash: ملخص سداسي عشري،
path: <blobsDir>/<hash>،
ref: blob:sha256:<hash>.

لا يُستخدم عداد محلي للجلسة.

معرفات القطع الأثرية: عدد صحيح تصاعدي محلي للجلسة

يفحص ArtifactManager ملفات القطع الأثرية *.log الموجودة عند الاستخدام الأول لإيجاد الحد الأقصى للمعرف الرقمي الموجود ويضبط nextId = max + 1.

سلوك التخصيص:

تنسيق الملف: {id}.{toolType}.log
المعرفات هي سلاسل متسلسلة ("0"، "1"، …)
لا يُكتب فوق القطع الأثرية الموجودة عند الاستئناف لأن الفحص يحدث قبل التخصيص.

إذا كان دليل القطع الأثرية مفقوداً، يُعيد الفحص قائمة فارغة ويبدأ التخصيص من 0.

معرفات مخرجات الوكيل (`agent://`)

يُخصص AgentOutputManager المعرفات لمخرجات الوكيل الفرعي بصيغة <index>-<requestedId> (مدمجة اختيارياً تحت بادئة الأصل، مثل 0-Parent.1-Child). يفحص ملفات .md الموجودة عند التهيئة لمواصلة الفهرس التالي عند الاستئناف.

تدفق بيانات الاستمرارية

1) مسار إعادة كتابة استمرارية إدخال الجلسة

قبل كتابة إدخالات الجلسة (#rewriteFile / الاستمرارية التزايدية)، يستدعي SessionManager الدالة prepareEntryForPersistence() (عبر truncateForPersistence).

السلوكيات الرئيسية:

اقتطاع السلاسل الكبيرة: تُقطع السلاسل الضخمة ويُضاف إليها اللاحقة "[Session persistence truncated large content]".
تجريد الحقول العابرة: تُحذف partialJson وjsonlEvents من الإدخالات المستمرة.
استخراج الصور إلى بيانات ثنائية:
- يُطبق فقط على كتل الصور في مصفوفات content،
- فقط عندما لا تكون data مرجع بيانات ثنائية بالفعل،
- فقط عندما يبلغ طول base64 الحد الأدنى (BLOB_EXTERNALIZE_THRESHOLD = 1024)،
- يستبدل base64 المضمّن بـ blob:sha256:<hash>.

يُبقي هذا جلسة JSONL مضغوطة مع الحفاظ على إمكانية الاسترداد.

2) مسار إعادة ترطيب تحميل الجلسة

عند فتح جلسة (setSessionFile)، وبعد عمليات الترحيل، يُشغّل SessionManager الدالة resolveBlobRefsInEntries().

لكل كتلة صورة رسالة/رسالة مخصصة تحتوي على blob:sha256:<hash>:

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

إذا كانت البيانات الثنائية مفقودة:

تسجّل resolveImageData() تحذيراً،
تُعيد سلسلة المرجع الأصلية دون تغيير،
يستمر التحميل (بدون عطل قسري).

3) مسار تسرب/اقتطاع مخرجات الأداة

يُشغّل OutputSink المخرجات المتدفقة في bash/python/ssh والمنفذين المرتبطين.

السلوك:

يُعقّم كل جزء ويُلحق بمخزن الذيل في الذاكرة.
عندما تتجاوز البايتات في الذاكرة عتبة التسرب (DEFAULT_MAX_BYTES، 50KB)، يُعلّم الحوض المخرجات على أنها مقتطعة.
إذا كان مسار قطعة أثرية متاحاً، يفتح الحوض كاتب ملفات ويكتب:
- المحتوى المؤقت الموجود مرة واحدة،
- جميع الأجزاء اللاحقة.
يُقلَّص المخزن في الذاكرة دائماً إلى نافذة الذيل للعرض.
تُعيد dump() ملخصاً يتضمن artifactId فقط عند إنشاء حوض الملفات بنجاح.

التأثير العملي:

يُظهر واجهة المستخدم/إعادة أداة الذيل المقتطع،
يُحفظ المخرج الكامل في ملف قطعة أثرية ويُشار إليه بـ artifact://<id>.

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

نموذج وصول URL

مراجع `blob:`

blob:sha256:<hash> هو مرجع استمرارية داخل حمولات إدخال الجلسة، وليس مخطط URL داخلي يعالجه الموجّه. يتم التحليل بواسطة SessionManager أثناء تحميل الجلسة.

`artifact://<id>`

يعالجه ArtifactProtocolHandler:

يتطلب دليل قطع أثرية جلسة نشطة،
يجب أن يكون المعرف رقمياً،
يُحلَّل بمطابقة بادئة اسم الملف <id>.،
يُعيد نصاً خاماً (text/plain) من ملف .log المطابق،
عند الغياب، يتضمن الخطأ قائمة بمعرفات القطع الأثرية المتاحة.

سلوك الدليل المفقود:

إذا كان دليل القطع الأثرية غير موجود، يُطلق استثناء No artifacts directory found.

`agent://<id>`

يعالجه AgentProtocolHandler عبر <artifactsDir>/<id>.md:

يُعيد النموذج البسيط نص markdown،
يُجري نموذجا /path أو ?q= استخراج JSON،
لا يمكن الجمع بين استخراج المسار والاستعلام،
إذا طُلب الاستخراج، يجب أن يُحلَّل محتوى الملف بصيغة JSON.

سلوك الدليل المفقود:

يُطلق استثناء No artifacts directory found.

سلوك المخرج المفقود:

يُطلق استثناء Not found: <id> مع المعرفات المتاحة من ملفات .md الموجودة.

تكامل أداة القراءة:

تدعم read ترقيم الصفحات بالإزاحة/الحد لقراءات URL الداخلية غير الاستخراجية،
ترفض offset/limit عند استخدام استخراج agent://.

دلالات الاستئناف والتفرع والنقل

الاستئناف

يفحص ArtifactManager ملفات {id}.*.log الموجودة عند أول تخصيص ويواصل الترقيم.
يفحص AgentOutputManager معرفات مخرجات .md الموجودة ويواصل الترقيم.
يُعيد SessionManager ترطيب مراجع البيانات الثنائية إلى base64 عند التحميل.

التفرع

يُنشئ SessionManager.fork() ملف جلسة جديد بمعرف جلسة جديد وارتباط parentSession، ثم يُعيد مسارات الملفات القديمة/الجديدة. تُعالج نسخة القطع الأثرية بواسطة AgentSession.fork():

يحاول النسخ التكراري لدليل القطع الأثرية القديم إلى دليل القطع الأثرية الجديد،
يُتحمّل الدليل القديم المفقود،
تُسجَّل أخطاء النسخ غير ENOENT كتحذيرات ويكتمل التفرع على أي حال.

آثار المعرفات بعد التفرع:

إذا نجح النسخ، تواصل عدادات القطع الأثرية في الجلسة الجديدة بعد الحد الأقصى للمعرف المنسوخ،
إذا فشل النسخ/تجاوزه، تبدأ معرفات قطع أثرية الجلسة الجديدة من 0.

آثار البيانات الثنائية بعد التفرع:

البيانات الثنائية عامة ومعنونة بالمحتوى، لذا لا يلزم نسخ دليل البيانات الثنائية.

الانتقال إلى مسار عمل جديد

يُعيد SessionManager.moveTo() تسمية ملف الجلسة ودليل القطع الأثرية إلى دليل الجلسة الافتراضي الجديد، مع منطق التراجع إذا فشلت خطوة لاحقة. يُحافظ هذا على هوية القطع الأثرية مع إعادة توطين نطاق الجلسة.

معالجة الأعطال ومسارات الرجوع

الحالة	السلوك
ملف البيانات الثنائية مفقود أثناء إعادة الترطيب	التحذير والاحتفاظ بسلسلة المرجع `blob:sha256:` في الذاكرة
قراءة البيانات الثنائية ENOENT عبر `BlobStore.get`	تُعيد `null`
دليل القطع الأثرية مفقود (`ArtifactManager.listFiles`)	تُعيد قائمة فارغة (يمكن بدء التخصيص من جديد)
دليل القطع الأثرية مفقود (`artifact://` / `agent://`)	يُطلق استثناء صريح `No artifacts directory found`
معرف القطعة الأثرية غير موجود	يُطلق استثناء مع قائمة بالمعرفات المتاحة
فشل تهيئة كاتب القطعة الأثرية في OutputSink	يواصل مع الاقتطاع بالذيل فقط (بدون قطعة أثرية للمخرج الكامل)
لا يوجد ملف جلسة (بعض مسارات المهام)	تعود أداة المهمة إلى دليل قطع أثرية مؤقت لمخرجات الوكيل الفرعي

استخراج البيانات الثنائية مقابل قطع الأثرية للمخرج النصي

استخراج البيانات الثنائية يُخصص لحمولات الصور الثنائية داخل محتوى إدخال الجلسة المستمرة؛ يستبدل base64 المضمّن في JSONL بمراجع محتوى ثابتة.
القطع الأثرية ملفات نصية عادية لمخرجات التنفيذ ومخرجات الوكيل الفرعي؛ يمكن عنونتها بواسطة معرفات محلية للجلسة عبر عناوين URL الداخلية.

يتقاطع النظامان بشكل غير مباشر فقط (كلاهما يُقلل من تضخم جلسة JSONL) لكن لهما هوية وعمر ومسارات استرداد مختلفة.

ملفات التنفيذ

src/session/blob-store.ts — تنسيق مرجع البيانات الثنائية، والتجزئة، والوضع/الأخذ، ومساعدات الاستخراج/التحليل.
src/session/artifacts.ts — نموذج دليل قطع أثرية الجلسة وتخصيص معرف القطعة الأثرية الرقمي.
src/session/streaming-output.ts — سلوك اقتطاع OutputSink/التسرب إلى الملف وبيانات الملخص.
src/session/session-manager.ts — تحويلات الاستمرارية، وإعادة ترطيب البيانات الثنائية عند التحميل، وتفاعلات تفرع/نقل الجلسة.
src/session/agent-session.ts — نسخ دليل القطع الأثرية أثناء التفرع التفاعلي.
src/tools/output-utils.ts — تمهيد مدير قطع أثرية الأداة وتخصيص مسار القطعة الأثرية لكل أداة.
src/internal-urls/artifact-protocol.ts — محلّل artifact://.
src/internal-urls/agent-protocol.ts — محلّل agent:// + استخراج JSON.
src/sdk.ts — توصيل موجّه URL الداخلي ومحلّل دليل القطع الأثرية.
src/task/output-manager.ts — تخصيص معرف مخرجات الوكيل محدد النطاق بالجلسة لـ agent://.
src/task/executor.ts — كتابة قطع أثرية مخرجات الوكيل الفرعي (<id>.md) والرجوع إلى دليل القطع الأثرية المؤقت.