إنتقل إلى المحتوى الرئيسي

تفاصيل المساهمة الداخلية

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

إرشادات المساهمة العامة، توقعات طلبات السحب، وأوامر التحقق الكاملة موجودة في CONTRIBUTING.md و AGENTS.md في جذر المستودع. هذه الصفحة تركّز على بنية الكود وأنماط التنفيذ.

ما تغطيه هذه الصفحة​

استخدم هذه الصفحة عندما تحتاج إلى:

  • إضافة أو تعديل موائم مزوّد
  • إضافة أو تعديل أداة
  • إضافة أو تعديل موائم قناة
  • تتبع إنشاء بيئة التشغيل أو إعداد AgentLoop
  • لمس الذاكرة، البوابة، الأمان، تجميع المحث، أو توجيه المزوّدين
  • كتابة اختبارات تحتاج إلى محاكاة أجزاء من بيئة التشغيل
  • تحديد ما إذا كان نوع معيّن يجب أن يعيش في src/contracts/

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

توزيع الكود​

تنظّم EstaCoda الكود حسب مجال التشغيل. من أهم المجلدات تحت src/:

المجلدالمسؤولية
src/runtime/إنشاء بيئة التشغيل، ربط حلقة الوكيل، دمج حلقة المزوّد، وبناء الجلسات
src/providers/موائمات المزوّدين، بيانات المزوّدين، حل مسارات النماذج، ومساعدات تنفيذ المزوّد
src/tools/تعريفات الأدوات الأصلية، مزوّدو الأدوات، وخطة تسجيل الأدوات
src/prompt/تجميع المحث، إعداد سجل المزوّد، الاختزال، وحزم السياق
src/memory/الذاكرة المحلية، تكامل الذاكرة الخارجية، الاسترجاع، الفهرسة، والاختزال
src/security/ثقة مساحة العمل، الموافقات، تقييم الأوامر، وبناء سياسة الأمان
src/channels/موائمات القنوات، بوابة القنوات، ومساعدات التسليم
src/gateway/مشرف البوابة، الخطافات، المرونة، ودورة حياة الخدمة
src/cron/أدوات ومخزن مهام cron
src/delegation/تفويض الوكلاء الفرعيين، مشغلات الأطفال، وتشخيصات التفويض
src/workflow/تنفيذ سير العمل الدائم وحالة سير العمل
src/evolution/مراجعة تطور الوكيل، المقترحات، القيود، ومسارات التصدير
src/knowledge/دعم رسم علاقات الكود وذاكرة المعرفة
src/lifecycle/مساعدات التثبيت، التحديث، الإزالة، وحفظ الحالة
src/packs/تثبيت الحزم، السجل، وتصنيف المخاطر
src/setup/الإعداد الأولي، محرر الإعداد، التحقق، ونصوص الإعداد المحلية
src/acp/تكامل محرر ACP
src/cli/أوامر CLI، حلقة الجلسة التفاعلية، ومسار التشغيل
src/config/تحميل إعدادات التشغيل، حل الملفات الشخصية، ومسارات حالة EstaCoda
src/contracts/عقود TypeScript المشتركة بين الأنظمة الفرعية

اعتبر هذا الجدول خريطة عملية، وليس قائمة حصرية. نظام الملفات هو مصدر الحقيقة.

حدود الاستيراد​

استخدم العقود المشتركة للحدود بين الأنظمة الفرعية. أبقِ وحدات التنفيذ خلف واجهات صغيرة وواضحة.

قواعد عملية:

  • يمكن للأنظمة الطرفية أن تستورد من src/contracts/، وبشكل محدود من src/config/.
  • يجب أن تتجنب الأنظمة الطرفية استيراد كود تركيب بيئة التشغيل.
  • src/runtime/ منطقة تركيب. من الطبيعي أن تربط الأنظمة ببعضها.
  • يمكن لمداخل CLI والبوابة استدعاء إنشاء بيئة التشغيل.
  • يمكن للاختبارات أن تستورد أسطحًا أعمق عندما يتطلب السلوك المختبر ذلك.

src/index.ts هو مدخل CLI. يقرأ خيارات CLI المبكرة، يتعامل مع الإعداد والأوامر التي لا تحتاج إلى آثار جانبية، يحمّل الإعدادات، يفتح قاعدة بيانات الجلسات، وينشئ بيئة تشغيل CLI عبر createRuntime().

عندما تضيف اعتمادًا بين نظامين فرعيين، اسأل أولًا ما إذا كان نوع عقد أو دالة حدية صغيرة سيجعل الملكية أوضح.

العقود​

العقود العابرة للأنظمة الفرعية تعيش في src/contracts/.

الملفما يعرّفه
provider.tsمعرفات المزوّدين، ملفات النماذج، طلبات واستجابات المزوّدين، أحداث البث، وبيانات المسار
tool.tsتعريفات الأدوات، فئات المخاطر، مزوّدو الأدوات، ومعالجات الأدوات
channel.tsرسائل القنوات، الردود، قدرات الموائمات، وموائمات القنوات
memory.tsسجلات الذاكرة، سياق الذاكرة للمحث، وعقود مزوّد الذاكرة الخارجية
security.tsأوضاع الموافقة، نوع البيئة، ومدخلات سياسة الأمان
session.tsسجلات الجلسات، الرسائل، الأحداث، والتشخيصات
runtime-event.tsأحداث بيئة التشغيل أثناء العمل

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

لا تغيّر عقدًا فقط لأن تنفيذًا جديدًا أُضيف. غيّر العقد عندما تتغير الحدود نفسها.

أمثلة:

  • المزوّد الجديد غالبًا يطبّق عقد ProviderAdapter الموجود.
  • القناة الجديدة غالبًا تطبّق عقد ChannelAdapter الموجود.
  • خلفية ذاكرة خارجية جديدة غالبًا تطبّق عقد مزوّد الذاكرة الخارجية الموجود.
  • قدرة جديدة تعبر أكثر من نظام فرعي قد تحتاج إلى تغيير عقد واختبارات لكل تنفيذ متأثر.

تركيب بيئة التشغيل​

createRuntime() في src/runtime/create-runtime.ts هو سطح التركيب الأساسي. يبني البنية المشتركة لبيئة التشغيل، مثل السجلات، المخازن، بنية الذاكرة، دورة حياة المتصفح، دعم cron، تحميل المهارات، مدخلات سجل المزوّدين، وربط سياسة الأمان.

البناء الخاص بالجلسة يتم عبر AgentLoopBuilder في src/runtime/agent-loop-builder.ts.

المرحلةمدة الحياةأمثلة
بنية بيئة التشغيلمدة حياة العملية أو بيئة التشغيلالمخازن، السجلات، الإعدادات المشتقة من الملف الشخصي، دورة حياة المتصفح، مخزن cron، الخدمات المشتركة
بناء الجلسةمدة حياة الجلسةسجل الأدوات، أدوات الجلسة، حلقة المزوّد، حلقة الوكيل، مدير التفويض

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

قد تستخدم جلسات البوابة RuntimeCache من src/runtime/runtime-cache.ts. التخزين المؤقت يعتمد على سياق الجلسة ويُبطَل عندما تتغير بصمة بيئة التشغيل.

إضافة مزوّد​

موائمات المزوّدين تطبّق ProviderAdapter من src/contracts/provider.ts.

الدوال المطلوبة:

الدالةالغرض
health(endpointOverride?)فحص توفر الموائم
listModels()إرجاع ملفات النماذج القابلة للتشغيل من الموائم
complete(request, options)تنفيذ طلب غير بثي

الدوال الاختيارية:

الدالةالغرض
stream(request, options)تنفيذ طلب بث عندما يدعمه المزوّد

الخطوات المعتادة:

  1. أضف تنفيذ المزوّد تحت src/providers/.
  2. طبّق عقد المزوّد الموجود.
  3. أضف أو حدّث بيانات المزوّد فقط عندما يحتاج المسار إلى بيانات تتجاوز التنفيذ نفسه.
  4. سجّل الموائم في المكان الذي يُبنى فيه سجل المزوّدين.
  5. أضف اختبارات لتشكيل الطلب، الاعتمادات، قائمة النماذج، معالجة الأخطاء، وأي سلوك رجوع احتياطي.
  6. حدّث بيئة تشغيل المزوّد فقط إذا تغير سلوك التشغيل أو حدود دعم المزوّد.

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

إضافة أداة​

الأدوات تُعرّف في src/tools/ وتُعرض عبر مزوّدي أدوات.

الأداة المسجلة تتضمن:

الخاصيةالغرض
nameمعرّف ثابت يراه النموذج
descriptionوصف يراه النموذج
inputSchemaJSON Schema للمدخلات المقبولة
riskClassفئة الخطر للموافقة والتنفيذ
toolsetsمجموعات القدرات التي تعرض الأداة أو ترشحها
progressLabelتسمية قصيرة للحالة أثناء تشغيل الأداة
maxResultSizeCharsحد لنص النتيجة المرسل للنموذج
isAvailable()فحص توفر الأداة في بيئة التشغيل أو الجلسة
run(input, context)معالج الأداة

فئات خطر الأدوات الحالية:

read-only-local
read-only-network
workspace-write
external-side-effect
credential-access
destructive-local
shared-state-mutation
spend-money
sandbox-escape

تسجيل الأدوات مركزي عبر toolRegistrationPlan في src/tools/index.ts.

المرحلةالاستخدام المعتاد
pre-skill-visibilityالأدوات الأساسية قبل تثبيت رؤية المهارات
post-skill-visibilityالأدوات التي تعرضها المهارات المحملة
post-memory-providerالأدوات التي تعتمد على إعداد مزوّد الذاكرة
post-tool-executorالأدوات التي تعتمد على بنية منفّذ الأدوات

الخطوات المعتادة:

  1. أضف أو حدّث مزوّد أداة تحت src/tools/.
  2. استخدم أضيق riskClass صحيح.
  3. تحقّق من المسارات، الأوامر، عناوين URL، الاعتمادات، والأهداف الخارجية قبل أي أثر جانبي.
  4. أرجع أخطاء منظمة بدل الرمي للحالات المتوقعة من المستخدم أو بيئة التشغيل.
  5. سجّل المزوّد في المرحلة المناسبة.
  6. أضف اختبارات مركزة للنجاح، الفشل، الرفض، وسلوك الحدود.
  7. حدّث بيئة تشغيل الأدوات إذا تغيرت دلالات التنفيذ.

لا توسّع الموافقات على الأوامر، فحوصات الثقة، أو التعامل مع المسارات لجعل الأداة أسهل في الاستدعاء.

إضافة موائم قناة​

موائمات القنوات تطبّق ChannelAdapter من src/contracts/channel.ts.

حقول ودوال شائعة:

الحقل أو الدالةالغرض
kindمعرّف القناة مثل telegram أو discord أو email
deliveryقدرات التسليم والبث الاختيارية
start(handler)بدء موائم طويل العمر وتمرير الرسائل الداخلة إلى البوابة
stop()إيقاف موارد الموائم بشكل نظيف
receive(event)تحويل حدث منصة إلى حدث أو رسالة قناة
send(reply)تسليم رد
getCapabilities()إرجاع بيانات القدرات الثابتة
pollOnce()جلب رسائل داخلة بنمط polling
pair()تشغيل مسار ربط
joinVoiceChannelForMessage()الانضمام إلى قناة صوتية لرسالة
leaveVoiceChannelForMessage()مغادرة قناة صوتية لرسالة

الخطوات المعتادة:

  1. أضف الموائم تحت src/channels/.
  2. طبّق عقد ChannelAdapter.
  3. أضف دعم الإعداد والتشغيل في المكان الذي يُنشأ فيه الموائم.
  4. أضف أو حدّث سياسة مصادقة القناة إذا كانت القناة تقبل مستخدمين بعيدين.
  5. استخدم مسار مرونة البوابة للموائمات طويلة العمر عندما يكون ذلك مناسبًا.
  6. أضف اختبارات للمصادقة، تحويل الرسائل، سلوك الطابور، التسليم، والإيقاف.
  7. حدّث البوابة الداخلية إذا تغير سلوك المشرف أو البوابة.

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

أنماط الاختبار​

تستخدم الاختبارات Vitest وتعمل على Node.js. يمكن أن يكون Bun مفيدًا للسرعة محليًا، لكنه ليس خط الأساس المدعوم.

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

الهدفالنمط المفضل
سلوك المزوّدمحاكاة ProviderAdapter أو استخدام مساعدات الاختبار المحلية
تخزين الجلساتاستخدام InMemorySessionDB أو SQLite في مجلد مؤقت
سلوك نظام الملفاتاستخدام مجلدات مؤقتة وتجنب home الحقيقي
جلسات بيئة التشغيلتفضيل AgentLoopBuilder أو اختبارات Runtime مركزة بدل إعداد كامل غير لازم
سلوك القناةاختبار المصادقة، تحويل الرسائل، الطوابير، والتنظيف دون اعتمادات حية
سلوك الأماناختبار مسارات السماح والرفض معًا

أوامر مركزة:

pnpm exec vitest run src/providers/<file>.test.ts
pnpm exec vitest run src/tools/<file>.test.ts
pnpm exec vitest run src/channels/<file>.test.ts

التحقق القياسي للمستودع مذكور في AGENTS.md. لا تقل إن فحصًا نجح إلا إذا شغّلته فعلًا.

معالجة الأخطاء​

استخدم أبسط شكل خطأ يحافظ على تدفق التحكم والتشخيصات.

النمطمتى يستخدم
Result<Ok, Err>حالات فشل متوقعة يجب على المستدعي التفرع بناءً عليها
throwخرق الثوابت، أخطاء المبرمج، والحالات غير المتوقعة
AggregateErrorعدة حالات فشل مستقلة
AbortControllerإلغاء طلبات المزوّد، الأدوات، الأدوار، والعمل طويل المدى

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

حدود الحالة والإعدادات​

حالة التشغيل تنتمي إلى home الخاص بـ EstaCoda، وليس إلى مسارات عشوائية داخل المصدر.

الحدالقاعدة
الحالة العامةحالة مشتركة تحت ~/.estacoda/، مثل اختيار الملف النشط، الثقة، الموافقات، الجلسات، الذاكرة المشتركة، الحزم، وحل الملفات الشخصية
حالة الملف الشخصيحالة مرتبطة بملف شخصي تحت ~/.estacoda/profiles/<id>/، مثل الإعداد، .env الخاص بالملف، ملفات الذاكرة، المهارات، السجلات، حالة البوابة، ومجلدات الوسائط أو التخزين المؤقت
حالة مساحة العملثقة مساحة العمل حالة عامة مرتبطة بمسار الدليل؛ لا تعامل ملفات المشروع كإعداد موثوق
قاعدة بيانات الجلساتاستمرار الجلسات يتم عبر مسار قاعدة بيانات الجلسات المكوّن
الإعدادبيئة التشغيل تحمّل إعداد ملف شخصي واحد لكل تشغيل؛ اعتمادات المزوّدين تُحل عبر أسماء متغيرات البيئة المكوّنة ودعم .env الخاص بالملف الشخصي

إذا أضفت ملف حالة جديدًا، قرر هل هو عام، مرتبط بملف شخصي، مرتبط بجلسة، أم مؤقت. استخدم محللات المسارات الموجودة في src/config/ بدل تثبيت مسار home يدويًا.

التغييرات الحساسة أمنيًا​

هذه الأسطح تحتاج مراجعة إضافية:

السطحسبب الحساسية
ثقة مساحة العملتتحكم فيما إذا كان يمكن لـ EstaCoda العمل داخل دليل
موافقات الأدواتتتحكم فيما إذا كانت الأفعال الخطرة يمكن أن تعمل
تنفيذ الأوامرقد يتحول إلى تنفيذ كود محلي
التعامل مع المساراتقد يتحول إلى تجاوز مسارات أو وصول غير مقصود للملفات
الأسرار والإعدادقد يسرّب مفاتيح API، رموز bots، مسارات خاصة، أو اعتمادات
البوابة والقنواتيمكن لمستخدمين بعيدين إرسال رسائل وموافقات
الذاكرةسياق دائم قد يؤثر على السلوك المستقبلي
المهارات والحزمالتعليمات والأدوات المحملة قد تغيّر سلوك بيئة التشغيل
تجميع المحثالمحتوى غير الموثوق قد يؤثر على سلوك المزوّد

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

لا تجمع التغييرات الحساسة أمنيًا مع إعادة هيكلة غير مرتبطة.

مهام شائعة​

إضافة ملف نموذج​

  1. حدّث مسار كتالوج المزوّد أو النموذج الذي يستخدمه ذلك المزوّد.
  2. اضبط بيانات القدرة مثل contextWindowTokens و supportsTools و supportsVision و supportsStructuredOutput و apiMode عندما تنطبق.
  3. أضف أو حدّث اختبارات تحميل الكتالوج، حل المسار، الأسماء البديلة، تشخيصات المزوّد، وسلوك الرجوع الاحتياطي.

إضافة intent أصلي​

  1. غيّر src/contracts/intent.ts فقط إذا تغير عقد intent.
  2. أضف سلوك توجيه حتمي في الموجّه أو النظام المناسب.
  3. أضف المعالج في حلقة الوكيل أو في اعتراض قبل الحلقة عند الحاجة.
  4. اختبر التعرف، المعالجة، النتائج الإيجابية الخاطئة، النتائج السلبية الخاطئة، والمطالبات الملتبسة.

إضافة حدث تشخيصي​

  1. أضف شكل الحدث إلى العقد المناسب إذا كان الحدث يُحفظ أو يعبر حدود الأنظمة.
  2. أرسله من النظام الذي يملكه.
  3. أبقِ الحمولة عامة وآمنة من الأسرار.
  4. أضف اختبارات للحدث وللحقول التي يجب حذفها.

إضافة gateway hook​

  1. أضف اسم الخطاف ونوع الحمولة في سجل خطافات البوابة.
  2. أرسله من المشرف أو طبقة المرونة.
  3. أبقِ الحمولة خالية من نص الرسالة الخام، الرموز، الأسرار، والمعرّفات غير اللازمة.
  4. أضف اختبارات لإرسال الخطاف والتنظيف.

ملفات تستحق الفحص​

ابدأ بهذه الملفات عند تتبع التفاصيل الداخلية:

الملفما يوضحه
src/index.tsمدخل CLI وإنشاء بيئة تشغيل CLI
src/runtime/create-runtime.tsبناء بنية بيئة التشغيل
src/runtime/agent-loop-builder.tsبناء الجلسة ومراحل تسجيل الأدوات
src/runtime/runtime-cache.tsسلوك تخزين بيئة التشغيل مؤقتًا للبوابة
src/contracts/provider.tsعقود طلبات واستجابات وموائمات المزوّدين
src/contracts/tool.tsتعريفات الأدوات، المزوّدون، وفئات المخاطر
src/contracts/channel.tsرسائل القنوات، التسليم، القدرات، وعقود الموائمات
src/config/runtime-config.tsتحميل الإعدادات وتطبيعها
src/security/security-policy-factory.tsبناء سياسة الأمان
src/prompt/prompt-assembly.tsترتيب بناء المحث وإعداد سجل المزوّد

صفحات مرتبطة​