Skip to content

README.ar.md

Latest commit

 

History

History
328 lines (227 loc) · 25.7 KB

README.ar.md

File metadata and controls

328 lines (227 loc) · 25.7 KB
Raw

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt

هذه ترجمة مجتمعية. ملف README.md الإنجليزي هو مصدر الحقيقة وقد يكون أحدث.

Magic Context

سياق غير محدود. ذاكرة تدير نفسها. جلسة واحدة، مدى الحياة.
الحُصين لوكلاء البرمجة، وجزء من CortexKit.

npm @cortexkit/magic-context npm @cortexkit/opencode-magic-context npm @cortexkit/pi-magic-context Discord stars MIT License

أنت لا توظف مطورا لمهمة واحدة ثم تطرده عندما يسلّمها.
توقف عن فعل ذلك مع وكيلك.

ما هو Magic Context؟ · البدء السريع · CortexKit · السياق · الالتقاط · التوحيد · الاستدعاء · Docs · Configuration · Dashboard · 💬 Discord

ما هو Magic Context؟

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

وكلاء البرمجة يعملون بالعكس. كل مهمة هي موظف جديد بلا ذاكرة عن مشروعك، وفي نهاية كل جلسة تطرده وتبدأ من الصفر. وفي منتصف المهمة يواجهون حتى توقفات "compaction" التي تكسر التدفق وتفقد بصمت ما كانوا يعرفونه. هذا فقدان ذاكرة تقدمي، وهو ما يحدث عندما يتضرر الحُصين.

Magic Context يعطيهم واحدا. إنه الحُصين لوكلاء البرمجة، جزء الدماغ الذي يشكل الذكريات ويوحدها ويستدعيها، بالكامل في الخلفية. لا تعود الجلسة مقاولاً قابلاً للرمي، بل تصبح زميلا طويل الأمد كان موجودا طوال المشروع:

  • الالتقاط. عندما يضغط historian تاريخك، يرفع المعرفة الدائمة (القرارات، القيود، الأعراف) إلى ذاكرة المشروع. تحصل على نظام ذاكرة مجانا من العمل الذي تقوم به بالفعل.
  • التوحيد. أثناء الليل، تفعل وكلاء dreamer ما يفعله النوم لك: تتحقق من الذكريات مقابل قاعدة الشيفرة، وتنظم التكرارات والإدخالات القديمة، وترقي ما يتكرر.
  • الاستدعاء. تظهر الذكريات المناسبة تلقائيا في كل دور، ويمكن للوكيل البحث عند الطلب عبر الذكريات والمحادثات السابقة وتاريخ git. عبر الجلسات، وعبر OpenCode و Pi.

وعدان: وكيلك لا يتوقف أبدا لإدارة سياقه (لا توقفات compaction ولا تدفق مكسور)، ولا ينسى أبدا.

شغل جلسة واحدة لكل مشروع واتركها تعمل لأسابيع أو أشهر أو سنوات. ستتذكر كل ما بنيتموه معا.

البدء السريع

شغل معالج الإعداد التفاعلي. يكتشف نماذجك، ويضبط كل شيء، ويتعامل مع التوافق.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex

أو شغله مباشرة (أي OS):

npx @cortexkit/magic-context@latest setup

يكتشف المعالج تلقائيا أي harnesses لديك (OpenCode أو Pi أو كلاهما)، يضيف plugin، يعطل compaction المدمج، يساعدك على اختيار نماذج historian و dreamer و sidekick، ويحل التعارضات مع plugins أخرى لإدارة السياق. استهدف harness محددا باستخدام --harness opencode أو --harness pi.

لماذا نعطل compaction المدمج؟ Magic Context يدير السياق بنفسه. compaction الخاص بالمضيف سيتداخل مع عملياته المؤجلة الواعية للـ cache وسيضغط مرتين.

الإعداد اليدوي (OpenCode): أضف plugin وأوقف compaction في opencode.json، ثم ضع magic-context.jsonc في <project>/.cortexkit/ (أو في ~/.config/cortexkit/ للإعدادات الافتراضية على مستوى المستخدم). راجع مرجع التهيئة.

{
  "plugin": ["@cortexkit/opencode-magic-context"],
  "compaction": { "auto": false, "prune": false }
}

Pi: npx @cortexkit/magic-context@latest setup --harness pi (يتطلب Pi >= 0.74.0). إضافة Pi تشارك قاعدة البيانات نفسها مع OpenCode؛ ذكريات المشروع و embeddings تتجمع عبر الاثنين.

استكشاف الأخطاء: npx @cortexkit/magic-context@latest doctor يكتشف harnesses تلقائيا، يفحص التعارضات (compaction و OMO hooks و DCP)، يتحقق من plugin وشريط TUI الجانبي، يشغل فحص سلامة على قاعدة البيانات، ويصلح ما يستطيع. أضف --issue لإنشاء تقرير bug جاهز للإرسال.

يعمل بالطريقة نفسها في مشروع جديد تماما أو مشروع طويل العمر: ثبته، أعد تشغيل harness، وسيبدأ Magic Context بالتقاط السياق من تلك اللحظة. لا يملأ جلسات OpenCode أو Pi السابقة للتثبيت.

التوافق مع plugins أخرى لإدارة السياق

Magic Context يملك إدارة السياق من البداية إلى النهاية، لذلك يعطل نفسه إذا كان plugin آخر يقوم بهذا العمل. تشغيل مديرين للسياق في وقت واحد سيضغط تاريخك مرتين ويزعزع prompt cache. عند البدء يفحص ما يلي؛ setup و doctor يساعدانك على حل كل نقطة، وحتى تحل يبقى Magic Context متوقفا (fail-safe) ويخبرك بالسبب:

  • OpenCode built-in compaction (compaction.auto / compaction.prune): Magic Context يستبدله. Setup يوقفه.
  • DCP (opencode-dcp): plugin منفصل لتقليم السياق. لا يمكن تشغيلهما معا؛ أزله من قائمة plugin.
  • oh-my-opencode (OMO): يقدم setup تعطيل hooks الثلاثة المتداخلة:
    • preemptive-compaction: يشغل compaction يتعارض مع historian.
    • context-window-monitor: يحقن تحذيرات استخدام تتداخل مع nudges الخاصة بـ Magic Context.
    • anthropic-context-window-limit-recovery: يشغل compaction طارئا يتجاوز historian.

شغل npx @cortexkit/magic-context@latest doctor في أي وقت لإعادة الفحص والإصلاح تلقائيا.

جزء من CortexKit

الدماغ ليس عضوا واحدا. وكذلك وكيل البرمجة القادر.

CortexKit عائلة من plugins، كل واحد منها مبني على منطقة مختلفة من الدماغ. ثبت واحدا وسيصبح وكيلك أكثر حدة. ثبت الثلاثة وسيملك دماغا.

Plugin المنطقة ماذا يفعل
Magic Context (أنت هنا) الحُصين والفص الصدغي الإنسي سياق ذاتي الإدارة وذاكرة طويلة الأمد. يبقي الجلسات تعمل بلا توقفات compaction بينما يشكل معرفة المشروع ويوحدها ويستدعيها عبر الجلسات.
AFT القشرة الحسية الحركية يدرك بنية الشيفرة ويتصرف عليها بدقة. IDE و OS حقيقيان لوكيلك.
Alfonso (قريبا) القشرة أمام الجبهية تحكم تنفيذي. يخطط ويفكك العمل ويختار الوكلاء والنماذج ويقرر متى يسأل ويتحقق ويعمل commit.

Magic Context هو 1 من 3 plugins ستحتاجها فقط. هو يتذكر؛ AFT يدرك ويتصرف؛ Alfonso يقرر. يشتركون في مخزن CortexKit واحد، فتتجمع الذاكرة عبر harnesses والأدوات.

⚡ إدارة السياق

جلسة غير محدودة تدير نفسها. تمتلئ نافذة السياق أثناء العمل، والحل المعتاد، compaction، يوقف الوكيل ليقرأ كل شيء من جديد. Magic Context يتعامل مع ذلك باستمرار في الخلفية، فتستمر الجلسة.

  • تجزئة historian: يضغط historian في الخلفية التاريخ الخام القديم إلى حجرات متدرجة، وهي ملخصات زمنية تحل محل الرسائل القديمة. تحمل كل حجرة درجة أهمية، فتظل النافذة الحية صغيرة دون فقد الخيط. التلخيص لا يحتاج عضلات البرمجة لدى وكيلك الأساسي، لذا يمكنك تشغيل historian على نموذج رخيص أو حتى محلي بالكامل بينما يبقى الوكيل الرئيسي في أعلى مستوى.
  • عرض بالتلاشي: تعرض الحجرات بالدقة المناسبة للحظة عبر قاعدة حتمية بلا LLM تضبط نفسها على نافذة سياق النموذج. التاريخ القديم يتلاشى بسلاسة بدلا من السقوط فجأة، ولأنها حتمية يظهر التاريخ نفسه دائما بالطريقة نفسها.
  • الوكيل يلمح إلى ما يجب إسقاطه، أو لا يفعل: مع تفعيل التخفيض الموجه بالوكيل، يستدعي الوكيل ctx_reduce لتمييز مخرجات أدوات قديمة أو رسائل طويلة للإزالة. الإسقاطات تصطف وتراعي cache، وتطبق فقط في لحظات آمنة للـ cache، فلا يربك التخفيض الـ cache. أوقفه وسيبقى الوكيل خارج إدارة السياق تماما: تزال المخرجات القديمة تلقائيا حسب العمر، مع ضغط caveman اختياري لأقدم نص.
  • تخطيط ثابت للـ cache: كل هذا منظم بحيث لا يلغي العمل الخلفي أبدا بادئة prompt المخزنة في cache. يبقى cache طوال الجلسة.

النتيجة: جلسة واحدة تعمل لأشهر، بلا توقفات compaction وبتكلفة منخفضة عند مزودي الأسعار المعتمدة على cache. يمكنك مشاهدة ذلك في TUI الخاص بـ OpenCode، حيث يعرض شريط جانبي حي تفصيل السياق حسب المصدر، حالة historian، وأعداد الذاكرة، ويتحدث بعد كل رسالة.

اختياري (مغلق افتراضيا): caveman text compression يضغط تدريجيا أقدم نص user و assistant بقاعدة عمرية حتمية، للجلسات التي تعمل مع تعطيل التخفيض الموجه بالوكيل.

🧠 الالتقاط

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

يمكن للوكيل أيضا تسجيل الذكريات صراحة، رغم أن معظمها يلتقط تلقائيا له:

  • ctx_memory: اكتب أو احذف معرفة عابرة للجلسات مباشرة ضمن تصنيف صغير (PROJECT_RULES, ARCHITECTURE, CONSTRAINTS, CONFIG_VALUES, NAMING).
ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")

الوعي الزمني (مفعل افتراضيا) يمنح الوكيل إحساسا بالوقت، مع علامات فجوة مثل +2h 15m بين الرسائل وحجرات مؤرخة، حتى يستطيع التفكير في مدى قدم حدث ما. اضبط temporal_awareness: false لإيقافه.

🌙 التوحيد

ما يفعله النوم للذاكرة. يعمل وكيل dreamer اختياري ليلا للحفاظ على جودة الذاكرة، منشئا جلسات فرعية مؤقتة لكل مهمة:

  • تحقق: افحص الذكريات تدريجيا مقابل codebase الحالي (المسارات، configs، الأنماط) وأصلح أو أزل الحقائق القديمة.
  • نظم: امسح حوض الذاكرة كله لدمج المكررات، وشد الصياغة، وأرشف الإدخالات منخفضة القيمة أو الزائدة.
  • صنف: قيّم أهمية كل ذاكرة ونطاقها وقابليتها الآمنة للمشاركة دون إزعاج prompt cache الحي.
  • حافظ على docs: أبق ARCHITECTURE.md و STRUCTURE.md محدثين من تغييرات codebase.
  • ذكريات المستخدم: رقّ الملاحظات المتكررة عن طريقة عملك (أسلوب التواصل، تركيز review، أنماط العمل) إلى <user-profile> ينتقل مع كل جلسة.
  • Smart notes: قيّم الملاحظات المؤجلة التي أصبح surface_condition لها صحيحا وأظهر الجاهزة.

لأنه يعمل أثناء الخمول، يناسب dreamer النماذج المحلية، حتى البطيئة. لا أحد ينتظر. شغل run في أي وقت باستخدام /ctx-dream.

🔎 الاستدعاء

الذاكرة الصحيحة في اللحظة الصحيحة. في كل دور، تحقن ذكريات المشروع النشطة وتاريخ الجلسة المضغوط تلقائيا وبثبات للـ cache. وعند الطلب يلجأ الوكيل إلى:

  • ctx_search: استعلام واحد عبر ثلاث طبقات في وقت واحد: memories للمشروع، تاريخ conversation الخام، و git commits المفهرسة. Semantic embeddings مع fallback للنص الكامل.

    ctx_search(query="why did we pick event sourcing for orders")

  • ctx_expand: أعد نطاق تاريخ مضغوط إلى transcript الأصلي U:/A: عندما يحتاج الوكيل إلى التفاصيل الدقيقة.

  • ctx_note: scratchpad للنوايا المؤجلة. تعود الملاحظات عند حدود طبيعية (بعد commits، بعد historian runs، عند انتهاء todos). تحمل Smart notes شرطا مفتوحا يراقبه dreamer.

يعمل الاستدعاء عبر الجلسات (ترث الجلسة الجديدة كل شيء) وعبر harnesses (اكتب ذاكرة في OpenCode واسترجعها في Pi).

تلميحات البحث التلقائي (مفعلة افتراضيا) تشغل ctx_search في الخلفية كل دور وتهمس بـ "استدعاء غامض" عندما يوجد شيء ذو صلة، مثل شبه تذكر ملاحظة كتبتها. تضيف شذرات مضغوطة فقط، وليس المحتوى الكامل أبدا؛ اضبط memory.auto_search.enabled: false لإيقافها. Git commit indexing (اختياري) يجعل تاريخ مشروعك قابلا للبحث الدلالي كمصدر رابع لـ ctx_search، فعّله بـ memory.git_commit_indexing.enabled: true.

أدوات الوكيل بنظرة سريعة

الأداة القسم ماذا تفعل
ctx_reduce السياق تصف محتوى tagged قديما للإزالة مع مراعاة cache
ctx_memory الالتقاط تكتب أو تحذف ذكريات دائمة عابرة للجلسات
ctx_search الاستدعاء تبحث في الذكريات وتاريخ المحادثات و git commits
ctx_expand الاستدعاء تفك ضغط نطاق تاريخ إلى transcript
ctx_note الاستدعاء نوايا مؤجلة و smart notes يقيمها dreamer

الأوامر

الأمر الوصف
/ctx-status عرض debug: tags، pending drops، cache TTL، حالة nudge، تقدم historian، تغطية الحجرات، ميزانية التاريخ
/ctx-flush إجبار كل العمليات المصطفة فورا، مع تجاوز cache TTL
/ctx-recomp إعادة بناء الحجرات من التاريخ الخام (يقبل نطاق start-end). استخدمه عندما تبدو الحالة المخزنة خاطئة
/ctx-session-upgrade ترقية هذه الجلسة إلى أحدث تنسيق تاريخ: إعادة بناء الحجرات وترحيل ذكريات المشروع
/ctx-aug تشغيل sidekick augmentation على prompt: استرجاع ذكريات ذات صلة عبر نموذج منفصل
/ctx-dream تشغيل صيانة dreamer عند الطلب: صيانة الذاكرة و docs و smart notes ومراجعة user-profile

تطبيق سطح المكتب

تطبيق سطح مكتب مرافق لتصفح وإدارة حالة Magic Context خارج الطرفية.

⬇️ Download for macOS · Windows · Linux

  • متصفح الذاكرة: ابحث وصف وحرر ذكريات المشروع حسب الفئة والمشروع.
  • تاريخ الجلسة: تصفح الحجرات والملاحظات لأي جلسة عبر تنقل زمني.
  • تشخيص cache: خط زمني فوري لـ cache hit/miss واكتشاف سبب bust.
  • إدارة dreamer: اعرض تاريخ dream-run، شغل runs، وافحص نتائج المهام.
  • محرر التهيئة: تحرير قائم على النماذج لكل إعداد، بما في ذلك سلاسل model fallback.
  • عارض السجلات: live-tailing للسجلات مع بحث.

يقرأ مباشرة من قاعدة بيانات SQLite الخاصة بـ Magic Context. لا خادم إضافي ولا API. التحديثات التلقائية مدمجة.

التهيئة

توجد الإعدادات في magic-context.jsonc. لكل شيء قيم افتراضية معقولة؛ تندمج تهيئة المشروع فوق إعدادات المستخدم. للمرجع الكامل، ضبط cache TTL، عتبات execute لكل نموذج، اختيار نماذج historian و dreamer، مزودي embeddings، وإعدادات الذاكرة، راجع CONFIGURATION.md أو مرجع التهيئة على docs.cortexkit.io.

مواقع التهيئة (موقع CortexKit مشترك واحد، المشروع يتجاوز المستخدم):

  1. <project-root>/.cortexkit/magic-context.jsonc
  2. ~/.config/cortexkit/magic-context.jsonc

هل ترقي من إصدار سابق؟ تنقل تهيئتك الحالية إلى هنا تلقائيا عند أول تشغيل (يترك أثر .MOVED_READPLEASE في المسار القديم).

التخزين

كل الحالة الدائمة تعيش في قاعدة بيانات SQLite محلية تحت مخزن CortexKit المشترك (~/.local/share/cortexkit/magic-context/context.db، أو ما يعادله XDG على Windows؛ قواعد OpenCode القديمة داخل المجلد تهاجر عند أول تشغيل). إذا تعذر فتح قاعدة البيانات، يعطل Magic Context نفسه ويبلغك. ترتبط الذكريات بـ هوية مشروع مستقرة مشتقة من repo، فتتبع المشروع عبر worktrees و clones و forks بدلا من ارتباطها بمسار مجلد.

يكتب Magic Context أيضا إلى بضعة مواقع أخرى:

المسار ماذا الاستمرارية
~/.local/share/cortexkit/magic-context/context.db قاعدة SQLite، tags، حجرات، ذكريات، وكل الحالة الدائمة (XDG-equivalent على Windows) يجب أن تستمر. فقدانها يفقد الذاكرة/التاريخ.
~/.local/share/cortexkit/magic-context/models/ Cache محلي لنموذج embeddings (~90 MB Xenova/all-MiniLM-L6-v2 ONNX)، ينزل عند أول استخدام عندما تكون embeddings المحلية مفعلة يجب أن يستمر، وإلا يعاد تنزيله كل تشغيل. لا يستخدم عند memory.enabled: false أو عند تهيئة backend embeddings من نوع openai_compatible/ollama.
${TMPDIR}/opencode/magic-context/magic-context.log (pi/ for Pi) سجل تشخيص قابل للرمي.

بيئات معزولة / مؤقتة (Docker، CI، حاويات قابلة للرمي): اربط دليل ~/.local/share/cortexkit/magic-context/ على volume دائم كي تبقى قاعدة البيانات و cache النموذج بين التشغيلات. إذا كان cache النموذج فقط مؤقتا، يعاد تنزيل النموذج ببساطة؛ وإذا كانت قاعدة البيانات مؤقتة، فلن تتراكم الذاكرة والتاريخ. لتجنب تنزيل نموذج ~90 MB بالكامل، اضبط memory.enabled: false أو وجه embedding إلى backend بعيد openai_compatible/ollama.

تاريخ النجوم

Star History Chart

التطوير

المتطلبات: Bun ≥ 1.0

bun install         # Install dependencies
bun run build       # Build the plugin
bun run typecheck   # Type-check without emitting
bun test            # Run tests
bun run lint        # Lint (Biome)
bun run format      # Format (Biome)

يتطلب تنفيذ Dream خادم OpenCode حيا (ينشئ dreamer جلسات فرعية مؤقتة). استخدم /ctx-dream داخل OpenCode للصيانة عند الطلب.

المساهمة

Bug reports و pull requests مرحب بها. للتغييرات الأكبر، افتح issue أولا لمناقشة النهج. شغل bun run format قبل الإرسال؛ يرفض CI الشيفرة غير المنسقة.

الترخيص

MIT