IDE
بيئة التطوير في كاظمه خلفية برمجة مستقلة عن وسيلة النقل: خدمة واحدة للويب، وواجهة الطرفية، وأوامر /ide في الدردشة، وCLI داخل العملية (kazma ask / kazma acp). تمرّ التعديلات دائمًا عبر LocalToolRegistry فلا يمكن تجاوز HITL.
محرّر الويب (Hands 0.11): CodeMirror 5 fromTextArea على /ide (سمة nord،
--bg-deep). تُكتب بايتات الملف في <textarea> أولًا، ثم يغلّفها CodeMirror
لأرقام الأسطر والتلوين. وإن حُجب الـ CDN يبقى الملف ظاهرًا نصًا عاديًا. كان
Monaco+Alpine طريقًا مسدودًا (تعليق المتصفح / تبويبات فارغة) وقد أُزيل. وعلى
تعديلات الوكيل للملفات الموجودة أن تستخدم file_apply_patch أو
file_apply_patch_set (old_string/new_string فريدين أو diff موحّد)، لا
file_write للملف كاملًا.
فهرس الشيفرة: يجد codebase_search (وGET /api/ide/codebase?q=) التعريفات
عبر فهرس رموز SQLite لكل مساحة عمل (tree-sitter إن ثبّت
pip install -e ".[index]"، وإلا فالتعابير النمطية) إضافة إلى ripgrep حي. ثبّت rg
لنتائج نصية أسرع. مفتاح الإيقاف KAZMA_CODE_INDEX=0.
ما الذي يقرؤه البحث: في مستودع git يقرأ الفهرس وfile_search الخاص
بالوكيل الملفات التي يحتفظ بها المستودع: الملفات المتتبَّعة، والملفات غير
المتتبَّعة التي لا يستثنيها .gitignore. أما المجلد المستثنى (مستودع مستنسخ، أو
مخرجات بناء) فيُترك، إلا إذا سمّيته مسارًا للبحث. والمجلد الذي لا يقع داخل أي
مستودع يُتصفَّح كاملًا. وفي الحالتين تُتخطّى البيئات وذاكرات التخزين المؤقت
ومخرجات البناء ومجلد بيانات كاظمه.
الذكاء اللغوي: محرّر الويب تلوين صياغة فقط (أوضاع CodeMirror).
ما زال POST /api/ide/lsp موجودًا للتلميح/الإكمال/التعريف/
التشخيصات (Python/JSON داخل العملية؛ والرموز تعيد استخدام فهرس الشيفرة) لكنه
غير مربوط في واجهة CodeMirror. مفتاح الإيقاف KAZMA_IDE_LSP=0. ولحلقة تحرير
احترافية، استخدم kazma acp في Zed.
تستخدم قراءات حالة Git وتاريخه وفروقه سياسة خيارات صريحة، ولا تحتاج بطاقة موافقة. تُرفض خيارات إخراج الملفات ووسائط المسارات خارج مساحة العمل قبل تشغيل Git. تعطّل القراءات fsmonitor وexternal diff وtextconv ومساعدات checkout-filter، وتحافظ على إعداد المشغّل لنهايات الأسطر. تعيد الخيارات غير المدعومة خطأً، ولا تتحول إلى تنفيذ صدفة. يستخدم إنشاء الفروع والتغييرات الأخرى مسار موافقة سجل الأدوات القائم. تُثبّت شجرة العمل على مساحة العمل النشطة حتى لو سمّت إعدادات Git المحلية مجلدًا آخر.
تمنع القراءات أيضًا الجلب التلقائي للكائنات الناقصة من مستودعات الاستنساخ
الجزئي، الذي قد يشغّل مساعدات اتصال مضبوطة. يعيد الكائن الناقص خطأً؛ اجلبه
بتنفيذ طرفية موافَق عليه قبل المحاولة مجددًا. يجب أن يدعم Git المثبّت
--no-lazy-fetch؛ وإلا تُرفض القراءة مع إرشاد للترقية. يفحص Git ذلك في كل قراءة.
تُقارن المستودعات ذات مرشحات checkout المخصصة دون تلك التحويلات، ولذلك قد تظهر فروق في الملفات الخام. استخدم أمر طرفية موافَقًا عليه عند الحاجة إلى تحويلات المستودع المخصصة.
المكوّنات
Section titled “المكوّنات”| الجزء | الوحدة |
|---|---|
| الخدمة | kazma_core/ide/service.py |
| حقن سياق البيئة | ide/env_context.py |
| مساحة العمل لكل مهمة | ide/workspace_scope.py |
| واجهة Web API | kazma_ui/ide_api.py + صفحة /ide |
| واجهة الطرفية | شاشة المحرّر في kazma_tui |
| الدردشة | أوامر /ide المائلة في البوابة |
تحديد مساحة العمل (يجب أن يبقى متسقًا)
Section titled “تحديد مساحة العمل (يجب أن يبقى متسقًا)”كل أداة ملفات، وخدمة IDE، وواجهة برمجة مساحة العمل، وكتلة البيئة، تسأل دالة
واحدة هي kazma_core.workspace.binding.resolve_active_root()
(file_write._get_workspace() هو اسمها التوافقي):
workspace_scopeContextVar الخاص بكل مهمة (مهمة سرب موجَّهة إلى مستودع واحد)- صف WorkspaceStore النشط (ما اختاره Switch Repo أو عملية استنساخ)
- التثبيت من
configure_workspace()على مستوى العملية - متغير البيئة
KAZMA_WORKSPACE - الصندوق الرملي الافتراضي:
<data dir>/workspace
المسار النسبي المُعطى لأداة وكيل يعني هذا المجلد، وليس أبدًا دليل العمل الخاص
بعملية الخادم (binding.resolve_tool_path). يتطلب الإنتاج سياسة صريحة لمساحات
العمل: security.workspace_roots يضبطها المشرف أو KAZMA_WORKSPACE_ROOT.
يرفض اختيار مساحة العمل أو إنشاؤها أو تبديلها المسارات خارج الجذور المحلولة،
بما فيها الروابط الرمزية. وإذا ضُبط جذر البيئة أيضًا فلا توسّعه السياسة
المحفوظة. واجتياز المسارات محجوب بـ normpath + فحوصات الاحتواء.
منح المسارات (الوصول خارج مساحة العمل)
Section titled “منح المسارات (الوصول خارج مساحة العمل)”الوصول خارج مساحة العمل النشطة مرفوض افتراضيًا، لكن يمكن فتحه
بإذن. المرجع الموثوق: kazma_core/workspace/path_policy.py +
workspace/path_grants.py، موصولان عبر IdeService.resolve، وfile_read /
file_write، وسرد الملفات/بحثها/حذفها/الإلحاق بها، وفحوصات مسارات الصدفة.
| الطريقة | الأثر |
|---|---|
| الدردشة (بسلاسة) | حين تفشل أداة ملفات على مسار خارج مساحة العمل، يستدعي الوكيل request_path_access (بطاقة HITL من فئة الخطر). وعند الموافقة تُنشأ منحة جلسة (مدتها نحو ساعة) وتعيد الأداة المحاولة. |
| صفحة مساحة العمل / API | مساحة العمل ← مجلدات خارج مساحة العمل: جذور إضافية دائمة (workspace.extra_roots، GET/PUT /api/workspace/extra-roots: path، mode: read | write، label)، تُعرض وتُضاف وتُحذف هناك. يجب أن يكون الجذر الجديد مسارًا كاملًا لمجلد موجود، لا قرصًا كاملًا، ولا مجلدًا يحوي تثبيت كاظمه أو بياناتها. تبقى حتى تُزال. |
منح القراءة لا تسمح بالكتابة أبدًا. وتخبر رسائلُ الرفض الوكيلَ كيف يطلب منحة، فتبقى الحلقة سلسة بدل الإخفاق القاطع.
العمليات
Section titled “العمليات”| الإجراء | HITL | ملاحظات |
|---|---|---|
| القراءة / السرد / البحث | آمن عادةً | محصور بمساحة العمل |
| البحث في الشيفرة | آمن | codebase_search / GET /api/ide/codebase — الرموز + ripgrep |
| الذكاء اللغوي | آمن | خلفية /api/ide/lsp موجودة؛ محرّر الويب CodeMirror تلوين فقط |
| الكتابة / الحذف | أدوات خطرة | موافقة الرسم البياني أو الناقل |
| تطبيق الرقعة | خطر (file_apply_patch / file_apply_patch_set) | بحث واستبدال أو diff موحّد؛ بطاقة HITL واحدة للمجموعة؛ HITL نفسها للكتابة |
| مراجعة رقعة أو رفضها | استعادة من نقطة الحفظ | تعرض المراجعة كل ملف تغيّر منذ نقطة الحفظ التي أُخذت قبل الرقعة، ومنها الملف الذي أُنشئ بعدها. ورفض جزء أو ملف كامل يستعيده من تلك النقطة: ملفٌ تحمله نقطة الحفظ فقط، ضمن المسارات التي يجوز للأدوات الكتابة فيها، مع الإبقاء على نهايات أسطره (/api/ide/checkpoints/*) |
| التشغيل / run_file / الصدفة | خطر | سياسة shell_exec / python_exec؛ ويمنع force في Docker صدفة المضيف إلا مع KAZMA_HOST_SHELL=1 |
| Git status / diff / log | آمن | git للقراءة فقط عملية فرعية في مساحة العمل (ليست shell_exec بـ HITL) |
| Git commit / push / clean | خطر | أدوات مهارة git الأصلية |
| الإرسال إلى السرب | — | يُرفق سياق البيئة للعمّال |
دردشة الذكاء الاصطناعي من IDE
Section titled “دردشة الذكاء الاصطناعي من IDE”تعيد الدردشة المدركة للملف استخدام /api/chat/stream (لا مسار وكيل موازٍ). ويُحقن سياق البيئة فيرى النموذج الفرع والمستودع والأدوات المتاحة.