المسرد
الكيانات الأساسية
قسم بعنوان “الكيانات الأساسية”Agent: عامل ذكاء اصطناعي له هوية ودور ومهارات ومحوّل. ينتمي إلى مساحة عمل واحدة بالضبط. هو الفاعل الأساسي في النظام.
Adapter: المشغّل الذي ينفّذ جولة الوكيل. يُشحَن اثنان: Control Center (built-in)، وهو الإطار داخل العملية الذي يتحدث إلى مزوّدي النماذج، وClaude Code عبر claude -p. Cursor وCodex وAnthropic وOpenAI وسائرها مزوّدون على المحوّل المضمّن، لا واجهات سطر أوامر منفصلة. انظر إدارة المحوّلات والنماذج.
Workspace: مستأجر العزل الأعلى. يجمع الوكلاء والمستودعات والمساحات والتذاكر والذاكرة وخطوط الأنابيب. العزل بنيوي لا عرفي: لكل مساحة عمل ملف SQLite خاص (<dataDir>/<workspaceId>/workspace.db)، فقراءة عبر مساحات العمل لا تُترجَم أصلًا. كل مسار داخل التطبيق مسبوق بـ /workspaces/:workspaceId. انظر خريطة المسارات.
Forge: مضيف شفرة: GitHub أو GitLab أو Bitbucket Cloud. مضيف الشفرة خاصية لكل مستودع، تُقرأ من بعيد origin عند التسجيل، وهو يختار محوّل واجهة ذلك المستودع وبيانات اعتماده. تستطيع مساحة العمل الواحدة أن تضم مستودعات على الثلاثة، والأسطح التي تجمع (الوارد، وطابور طلبات السحب) تنتشر على كل مضيف ممثَّل وتدمج النتائج، وتعزل الأعطال حتى لا يفرّغ مضيف يتعذّر الوصول إليه البقية. تختلف المضيفات فيما تدعمه. انظر جدول القدرات في ربط مضيف شفرة.
Repo: مستودع Git مسجَّل داخل مساحة عمل واحدة. نطاقه مساحة العمل: تسجيل شجرة الخروج نفسها في مساحتي عمل يعطي صفّين مستقلين بمعرّفين، وهوية المستودع عبر مساحات العمل هي مسار نظام الملفات لا المعرّف. يشترط التسجيل شجرة عمل Git يشير بعيد origin فيها إلى مضيف شفرة مدعوم. يحمل كل مستودع مضيف الشفرة ذاك (github / gitlab / bitbucket)، وهو يختار محوّل الواجهة وبيانات الاعتماد المستخدَمة له.
Isolated repo: شجرة عمل خاصة بمساحة العمل لمستودع مسجَّل. نسخ عند الكتابة عبر rift حيث تُشحَن تلك المكتبة الأصلية، وgit worktree على Windows. تُجهَّز لكل مساحة: تشترك كل محادثات تلك المساحة في شجرة خروج واحدة، فلا يعدّل الوكلاء المصدر.
Space: حاوية تعاون نطاقها مساحة العمل، فيها مشاركون من البشر والوكلاء، ووضع Mode محفوظ، وحالة تجهيز، ونوع SpaceKind (topic / agentPeer / system / pr / slack) يقرّر كيف تُقسَّم وتُكتم وتُشار وكيف تُجمَع كنفاية. تملك أشجار العمل المعزولة التي تشترك فيها محادثاتها (نسخ عند الكتابة عبر rift، وgit worktree على Windows).
Conversation: مجرى رسائل واحد داخل Space، له معرّفه وسجله وسياق تشغيل الوكيل. المحادثات داخل المساحة أنداد على مستوى واحد، فلا مجرى أساسي ولا مجرى «رئيسي». تُفتح كل واحدة لسان محرر، وتُجمَع حالة عدم القراءة للمساحة عبرها كلها.
Thread: Conversation ضُبط فيها anchorMessageId: مربوطة برسالة واحدة في محادثة شقيقة داخل Space نفسها، بسياق وكيل جديد يُبذَر من رسالة الارتكاز تلك. عمقها مستوى واحد، فالخيوط لا ترتكز على خيوط.
Ticket: تجميع وحدة العمل. محايد للمزوّد: local افتراضيًا، مع محوّلات مزامنة لـ Linear وGitHub Issues وJira Cloud وClickUp، وإن كان لا يوجد سطح داخل التطبيق ينشئ اتصال مزامنة. يدعم التسلسل والروابط والتفويض. الإسناد إلى وكيل يسجّل الملكية ولا يُرسل شيئًا، والإسناد إلى فريق هو الاستثناء (TeamRoutingService يُرسل القائد).
Pipeline: سير عمل قائم على DAG يسلسل الخطوات (إرسال وكيل، وسكربتات، وشروط). تعرّفه القوالب، ويُنفَّذ تشغيلات.
كائنات القيمة
قسم بعنوان “كائنات القيمة”AgentRole: دور معدَّد (CEO وcoder وreviewer وQA وdesigner وsecurity وdevops وPM وgeneral). يحدّد الشخصية والوصول إلى الذاكرة والتسلسل.
AgentSkills: مجموعة معرّفات مهارات لا تراعي حالة الأحرف، تحقن السياق المناسب في المطالبات عند الإرسال.
Skill source: مستودع GitHub مسجَّل لكل مساحة عمل كفهرس مهارات. غير موثوق بالبناء: بيانات المستودع الوصفية للعرض فقط، وكل تثبيت يمر ببوابة الفحص المغلق عند الفشل قبل أن يصل أي محتوى إلى القرص أو إلى مطالبة. انظر تثبيت المهارات وإدارتها.
skills-lock.json: بيان المهارات المثبّتة لكل مساحة عمل: لكل مهارة مستودعها المصدر ومسارها داخل المستودع والإيداع المثبَّت عليه وتجزئة محتوى مجمَّعة. التثبيت والتحديث وإلغاء التثبيت يبقونها حالية، وverify_skills يطابقها مع القرص.
Agent run gateway (بوابة تشغيل الوكيل): نقطة loopback على cc_server تفرض سياسة الإجراءات داخل البيئة المعزولة للوكيل. يُوجَّه إليها كل دفع إلى GitHub يقوم به الوكيل، فيُفحص مقابل قاعدة الدفع إلى مستودع بعيد ثم يُمرَّر برمز كتابة لا يحمله الوكيل أبدًا؛ وتُفحص أوامر Bash في Claude Code عبر خطاف على النقطة نفسها. انظر البيئة المعزولة والأمان.
Mode: chat أو plan أو review أو orchestrate. يُخزَّن لكل مساحة، فيستطيع الوكيل الواحد أن يكون في أوضاع مختلفة في مساحات مختلفة، وتشترك كل محادثات المساحة فيه. يضبط موجّه النظام وقواعد الكتابة في البيئة المعزولة وقائمة سماح أدوات MCP. يعرض حقل الكتابة chat وplan وorchestrate فقط، ويُسمّى chat «الوكيل».
SandboxBackend: microvm (آلة افتراضية محصورة، وهي الخلفية الوحيدة ذات حد نواة، وتُطبَّق على الطرفيات التفاعلية)، أو native (Seatbelt على macOS، وbubblewrap على Linux وWSL2)، أو none. يُسبَر مرة عند الإقلاع، وnative يُطبَّق على إرسال الوكيل حين يتاح، فيلف واجهة Claude Code وأداة bash في الإطار. Windows بلا خلفية أصلية، ويحتاج Linux إلى bwrap وsocat، فالتشغيلات هناك بلا غلاف، و--sandbox off انسحاب متعمّد.
Rig: آلة مؤقتة يمكن التخلص منها يقودها وكيل لحظة بلحظة: متصفح محصور أو سطح مكتب Linux، أو محاكي Android أو محاكي iOS يديرهما المضيف، أو طرفية محصورة. تُشاهَد مباشرة على مسارها الكامل الدقة، ويُفرض التولّي على الخادم. نطاقها المحادثة حتى يخاطب لسان الإنسان واستدعاءات الوكيل browser_use / computer_use / mobile_use / ios_use آلة افتراضية واحدة. انظر المنصات والحاويات المعزولة.
Enclosure: حد المنصة الأقوى المدعوم بآلة افتراضية: حد نواة، وقرص تراكب يُرمى، وبوابة شبكة ترفض افتراضيًا، ووسيط بيانات اعتماد. منصات Android وiOS مؤقتة لكنها تستخدم شبكة يديرها المضيف ولا تدّعي هذا الحد. قيادة أي منصة تستخدم صنف الضوابط enclosureControl.
RunCost: حصيلة الرموز والتكلفة (رموز الدخل، ورموز الخرج، والتكلفة المقدَّرة بالسنت) لتشغيل وكيل واحد.
WakeReason: سبب إرسال الوكيل. ست قيم: رسالة مستخدم، وإسناد تذكرة، وإعادة إرسال للاستعادة بعد فشل، واكتمال تذكرة فرعية، ونبضة متابعة مجدولة، وخطوة خط أنابيب.
المنافذ
قسم بعنوان “المنافذ”SandboxPort: يدير دورة حياة البيئة المعزولة (السبر، والإطلاق، والأحداث، والتنفيذ، والتدمير).
CredentialBrokerPort: يُصدر بيانات اعتماد محصورة النطاق لإطلاق البيئة المعزولة — للقراءة فقط في بيئة الوكيل، والكتابة محصورة في مسار الدفع على الخادم — ويلغيها عند التفكيك.
GitRepoInspectorPort: يستخرج البيانات الوصفية (المالك، والمستودع، والفرع) من مسار مستودع Git محلي.
EmbeddingPort: ينتج متجهات تضمين نصي بمعيار واحد للبحث الدلالي.
NotificationPort: يعرض إشعارات سطح المكتب الأصلية مع احترام بوابات التصنيف والمسار.
TicketProviderPort: حد محايد للمزوّد إلى خلفية تذاكر (إنشاء، وجلب، وسرد، وتحديث، وانتقال، وإسناد).
PipelineEnginePort: يبدأ تشغيل خط أنابيب من قالب، ويفصل المستدعين عن المحرّك الملموس.
خدمات النطاق
قسم بعنوان “خدمات النطاق”AgentDispatchService: يطلق تشغيلات الوكيل: يجهّز المستودعات المعزولة، ويبني المطالبات، وينشئ سجلات التشغيل، ويعيد مجاري أحداث حية.
TicketWorkflowService: محرّك دورة حياة التذاكر في النطاق الخالص، بنقطة اختناق للتعديل بتزامن متفائل وفرض لعزل مساحة العمل. مخطط انتقاله يلزم الوكلاء والأتمتة فقط، وتغييرات الواجهة التي يقودها المستخدم تمرّر force: true وتتجاوزه. لا يوجد مُرسِل تذاكر لمُسنَد إليه وكيل: AgentDispatchService يملك الإرسال، وإسناد تذكرة إلى وكيل لا يبدأ تشغيلًا. إسناد تذكرة إلى فريق هو الاستثناء (TeamRoutingService يُرسل القائد).
PipelineEngine: ينسّق تنفيذ التشغيل: يبدأ التشغيلات، ويجدول الخطوات، ويحفظ الحالة، ويعالج الموجّهات والالتقاءات والمتابعة عند الفشل، ويستأنف التشغيلات الجارية بعد إعادة التشغيل.
PipelineTriggerDispatcher: يشترك في أحداث النطاق ويبدأ تلقائيًا تشغيلات خطوط الأنابيب المطابقة للمشغّلات المفعّلة.
MemoryAccessPolicy: يحسم أذونات ذاكرة دور الوكيل على النطاقات ويفرضها.
HarnessCostCalculator: يسعّر استخدام رموز الإطار المضمّن إلى RunCost من فهرس models.dev. يكتب الإرسال تلك الحصيلة على سجل التشغيل.
BudgetEnforcementService: يحسب الإنفاق الشهري لكل وكيل وحظرًا قبل الإرسال (checkInvocationBlock). لا يستشير ذلك الحظر إلا مُصلِحات الاستعادة (OrphanRunReaper وStrandedTicketReconciler)، لا إرسال مستخدم أو وكيل عادي.
BudgetGovernanceService: يقيّم الإنفاق الشهري لكل وكيل بعد كل تشغيل: العتبة اللينة تسجّل حادثة تحذير، والاستنفاد يسجّل حادثة صارمة ويقلب دورة حياة الوكيل إلى paused.
الأحداث
قسم بعنوان “الأحداث”DomainEventBus: ناقل بث نشر واشتراك داخل العملية للتواصل بين الميزات. الأحداث منمَّطة، والمشتركون يستهلكون مجاري on<T>().
DomainEvent: الواجهة الأساسية. لكل حدث occurredAt. الفئات الرئيسة: مساحة العمل/الوكيل، وطلب السحب/المراجعة، والمراسلة، والتذاكر، وخط الأنابيب، والاجتماعات/التقويم، والهوية، والمنصات، والرصد.
الاجتماعات والتقويم
قسم بعنوان “الاجتماعات والتقويم”Meeting: جلسة اجتماع تُسجَّل محليًا وتُنسَخ نصيًا. يلتقط الميكروفون وصوت النظام، وينسخ على الجهاز بنموذج ASR قابل للاختيار (Parakeet TDT v3 افتراضيًا، والبدائل Parakeet TDT v2 وWhisper large-v3-turbo وWhisper base.en)، ويفصل المتحدثين، ويلخّص إلى ملاحظات وبنود إجراء وقرارات. يُثبَّت نموذج ASR المختار قسرًا عند الإقلاع، وتضيء عمليات التسجيل بعد إعادة تشغيل واحدة. نطاقه مساحة العمل، ويبقى على الجهاز.
MeetingSegment: نافذة صوت منسوخة واحدة، موسومة بالمتحدّث (me/them) مع تسمية فصل للمتحدثين وإزاحات بالملي ثانية.
MeetingActionItem / MeetingDecision: مخرجات منظَّمة يستخرجها خط أنابيب التلخيص وتُخزَّن صفوفًا منفصلة. تستطيع بنود الإجراء أن ترتبط بتذكرة.
CalendarEvent: بند Google Calendar متزامن، نطاقه مساحة عمل وحساب متصل. يختلف عن Meeting: الحدث التزام مجدول، وMeeting جلسة مسجَّلة. الربط واحد لواحد عبر MeetingCalendarLink.
CalendarAccount: حساب Google متصل، لكل مساحة عمل وبريد. تُخزَّن رموز تحديث OAuth على الخادم بمفاتيح google_* في <dataDir>/secrets.json ولا تصل إلى عميل، ويكتمل تدفق رمز الجهاز على الخادم. يحرّك علم authExpiredAt شريط إعادة الاتصال.
مصطلحات البنية
قسم بعنوان “مصطلحات البنية”Clean Architecture: قاعدة الاعتماد: العرض → التطبيق/الموفّرات → النطاق ← البنية التحتية. النطاق بلا أي استيراد من البنية التحتية.
Ports and adapters: يعرّف النطاق واجهات مجردة (منافذ)، وتقدّم البنية التحتية تنفيذات ملموسة (محوّلات). جذر التركيب يربطها.
Shared kernel: كيانات core/domain/ وكائنات القيمة والمنافذ والخدمات المشتركة بين 3 ميزات فأكثر.
Feature-first: تُنظَّم الشفرة حسب مجال العمل (الوكلاء، وخطوط الأنابيب، والمراسلة) لا حسب الطبقة التقنية.
تعدد اللاعبين والهوية وسرعة العمل
قسم بعنوان “تعدد اللاعبين والهوية وسرعة العمل”Principal: قيمة مختومة توحّد البشر والوكلاء كتجريد الفاعل الواحد: UserPrincipal(userId) أو AgentPrincipal(agentId). كل رسالة وتذكرة ومراجعة وخطة وسجل تشغيل يُنسَب عبر Principal.
User: هوية بشرية، تُخزَّن في global.db فهي عامة عبر مساحات العمل. الطرف الذي ينشئ مساحة العمل يصير مالكها، ويُختَم على Workspace.ownerUserId مع صف عضوية بدور المالك في العملية نفسها. ينضم الآخرون بدعوة أو عبر SSO.
WorkspaceMember / WorkspaceRole: صف عضوية يربط User بـ Workspace عند دور (owner / admin / member / viewer / guest). العضوية هي حد الوصول، ومفتاح الاقتران لا يقوم مقامها. منح كل مستودع تمنع العضوية من أن تعطي صلاحيات أوسع من مضيف الشفرة.
ParticipantPresence: وعي عابر لـ Principal (الحالة، والموضع، والمؤشر، والكتابة، وحالة الوكيل الحية وتكلفة التشغيل الجارية). لا يُحفَظ، ويمر عبر محور الخادم، ويُرشَّح بمنح المستودع قبل التوزيع.
Follow-mode: انقر صورة رمزية لتركب إطار رؤيتها إلى أن تفعل شيئًا، ثم تنفصل. يعمل للبشر وللوكلاء («راقب وكيلًا يعمل»).
Autonomy dial: ضبط لكل مساحة ولكل وكيل، propose-only / act-with-approval / act-freely، يُنفَّذ كملف تعريف مسمّى فوق مخزن ضوابط الإجراء.
ActionClass: مجموعة مغلقة من 13 صنف أثر (fileDelete وgitPush وprCreate وnetworkEgress وprocessSpawn وenclosureControl، …). كل أداة مغيِّرة تصرّح بأصنافها، ويحسم محرّك الضوابط allow / prompt / deny لكل نطاق (space > agent > workspace > mode preset > built-in default).
WriteLedger / idempotency key: كل تعديل يحمل مفتاح تكرارية يولّده العميل (UUIDv7، لكل فعل منطقي). السجل الخاص بمساحة العمل يزيل التكرار قبل أن يعمل المعالِج، والإعادة تعيد النتيجة الأصلية مطابقة بايتًا ببايت. يجعل إعادة الاتصال وتعدد العملاء آمنين بالبناء.
Needs me inbox: طابور عابر للركائز بقاعدة صارمة: لا يظهر البند إلا إذا كان يعطّل شيئًا (وكيلًا، أو دمجًا، أو مزامنة) أو يطلب المشغّل صراحة.
Plan Studio: سطح التخطيط التفاعلي: خطط بمخطط DAG منمَّط قابلة للتحرير، مع التكلفة والوقت والمخاطرة لكل خطوة، وموافقة جزئية.
Review compute: حوسبة مراجعة طلب سحب على الخادم (مجموعات مشتقة من المخطط، ومخططات منمَّطة، وفروق بصرية، وفروق عقد الواجهة، وبوابات متعددة المحاور) تُقدَّم عبر review_studio.* وتُطوى في لسان المراجعة.
Review space: مساحة الإسناد الوحيدة لطلب السحب (وضع review، ونوع pr)، تُنشأ على نحو تكراري وتُربَط بطلب السحب عبر ReviewSpaceAssociation. يودع كل مراجع نتائجه فيها، وهذا ما يجعلها قابلة للمقارنة، وشجرة عملها المعزولة فيها طلب السحب مُخرَجًا عند رأسه.
Review node: وحدة نتيجة مراجعة الذكاء الاصطناعي المنظَّمة: النوع (bug أو suggestion أو recommendation أو question أو ticket)، والأولوية من P0 إلى P3، وثلاثية فرز من فئة وشدّة وجهد، ومرساة ملف وسطر، وإصلاح مقترح اختياري، ودرجة ثقة. تُودَع بـ add_review_node، ويُحسَب الحكم من العُقد لا من النثر.
Consensus-ready: حالة عقدة المراجعة التي لا تُبلَغ إلا حين يؤكّد مراجع نظير النتيجة، ولا يستطيع الوكيل تأكيد نتيجته. زر النشر على GitHub في لسان المراجعة يرسل كل نتيجة مفتوحة متبقية (selection: all_open)، وأداة MCP publish_review_to_github ما زالت تفترض النتائج التي أكّدها الأقران فقط.
Review level: سياسة مساحة العمل (light أو balanced أو thorough) تضبط أي المراجعين يُوزَّعون (المهندس فقط، ثم +qa+architect، ثم +security+perf) وأين تُعرَض النتائج دون العتبة. لا تحذف نتيجة أبدًا.
Review axis: أحد خمسة مسارات تسجيل لكل مراجعة: correctness وsecurity وtestGap مأخوذة من نتائج المراجعين، وvisual وapiContract حتميان. المحاور المبوَّبة تُطوى في الحكم ولا تستطيع إلا أن تجعله أشد، وبوابة partial أو unavailable تُبقي الحكم بدل أن تمرّره.
Review verdict: ship أو hold أو block. أي نتيجة P0 بثقة لا تقل عن 0.7 تمنع، وأي P0 آخر أو أي P1 يُبقي، وغير ذلك ship. محور مبوَّب فاشل يفرض block ولا تستطيع النتائج أن تصوّت ضدّه.
الأسطول والتقييمات
قسم بعنوان “الأسطول والتقييمات”cc_worker: ثنائي منفّذ أسطول بلا واجهة بـ Dart خالص. يقترن بـ cc_server، ويصرّح بقدرات مضيفه، ويسحب مهامًا مؤجَّرة، وينفّذها، ويبث أحداث العملية عائدة. يحتفظ بلا حالة دائمة: خادم مرجعي واحد، وعدد N من الأطراف الصامتة.
JobSpec: المواصفة المنمَّطة لكل ما يمكن تنفيذه (تشغيل وكيل، وخطوة خط أنابيب، وفهرسة شفرة، وتصيير ذهبي، ومعيار أداء، ودفعة تقييم).
Eval suite: تعريف تقييم نطاقه مساحة العمل (مطالبة، ووكيل مستهدف ووضع، ومقيّمون). تُبذَر خمس حزم مبدئية عند إنشاء مساحة العمل، وتسردها قابلية الملاحظة ← الجودة.
النشر والعملاء
قسم بعنوان “النشر والعملاء”Thin-client architecture: لا يفتح أي عميل قاعدة البيانات، وتملك عملية cc_server بلا واجهة البيانات وتقدّمها عبر WebSocket RPC. كل عميل (حاسوب، وويب، وهاتف) عارض فوق اتصال RPC الواحد ذاك.
cc_server: ثنائي الخادم بلا واجهة (Dart خالص، بلا محرّك Flutter). يملك قاعدة Drift/SQLite، ويقدّم repo-RPC عبر WebSocket، ويشغّل خدمات الخلفية (خطوط الأنابيب، وMCP، والمُصلِحات).
ServerConnectionMode: كيف يبلغ تطبيق الحاسوب خادمه: local (تشغيل cc_server على هذا الجهاز، وهو الافتراضي) أو remote (الاتصال بواحد في مكان آخر). عميل الويب remote دائمًا.
RemoteRpcClient: عميل JSON-RPC المستقل عن النقل الذي يستخدمه كل عميل خفيف للتحدث إلى خادمه، عبر WSS أو loopback أو المرحّل بوسيط.
Per-call workspace scoping: الخادم بلا حالة، ولا ربط لمساحة عمل لكل جلسة، فلا يشترك عملاء متعددون على خادم واحد في «مساحة عمل حالية». كل repo/call وsub/subscribe خاص بمساحة عمل يجب أن يحمل workspace_id في وسائطه، ويُرفض المعرّف الغائب أو غير المسجَّل قبل فتح أي قاعدة. يُبوَّب الوصول بعد ذلك بعضوية مساحة العمل والدور، لا بالجلسة.
cc_remote: العميل الخفيف للهاتف، وهو PWA ويب بـ Flutter يتحكم بالأسطول عن بُعد عبر المرحّل بوسيط، بسياسة أدوات ترفض افتراضيًا.
cc_signaling_server: وسيط مرحّل WebSocket بلا حالة يستضيف غرفًا مشروطة بدعوة: مرحّل بسيط يمرّر الإطارات المختومة طرفًا لطرف فقط، ولا يحتفظ ببيانات التطبيق، ولا يرى PSK الاقتران.