أدوات الوكيل المضمّنة

هذه هي الأدوات المربوطة بالخادم التي تسجّلها بيئة تشغيل الوكيل المضمّن مباشرة — خادم اللغة، والبحث البنيوي، والمصحّح، والنوى، والأسئلة، والتحكم في العمال — بخلاف أدوات MCP التي تجسّرها، وأدوات الملفات والبحث والصدفة العامة الآتية من بيئة تشغيل الإطار. تغيب عن سجل MCP: لن يراها عميل MCP خارجي، لأن كل واحدة مربوطة بمورد حي في جهة الخادم — عملية خادم لغة، أو محوّل تصحيح، أو مفسّر — يخص تشغيلًا واحدًا.

لا تُسجَّل أداة هنا إلا حين يُربَط موردها الداعم بالتشغيل — مشرف لخادم اللغة أو للتصحيح، أو محلّل tree-sitter، أو مصنع نوى، أو منفذ أسئلة، أو قائمة عمال vibe. اكتشاف خادم لغة أو محوّل تصحيح لنسخة العمل هذه فحص لاحق منفصل (status / adapters): تبقى تلك الأدوات على السطح ليسأل الوكيل لماذا لا شيء صالح للاستخدام، بدل أن يخمّن.

مستويات الموافقة

تُعلن كل أداة مستوى، والمستوى يقرّر أي الأسطح تراها — لا مجرد ما إذا كانت تفتح مطالبة. وضع التخطيط والوكلاء الفرعيون للقراءة فقط سقفهم read، فالأداة من مستوى write أو exec غائبة عن مخططهم تمامًا.

المستوى	المعنى	الأدوات هنا
read	بلا آثار جانبية	lsp وast_grep وask_user وأدوات vibe_* الخمس
write	تغيّر الملفات	lsp_rename وast_edit وresolve
exec	تبدأ عملية أو تتحكم فيها	debug وeval

---

lsp — استعلامات خادم اللغة

تُسجَّل حين يملك التشغيل مشرف خادم لغة ودليل عمل. قدرة الخادم على الإجابة فعلًا تُكتشَف عند الاستدعاء، بوصفها تقاطعًا: لا بد أن توجد علامة جذر و أن يُحَل مسار ثنائي الخادم. أي منهما وحده يعني ألا يبدأ خادم — وstatus يقول ذلك — بدل تخمين صامت.

تُحدَّد المواضع بـ line وسلسلة فرعية في symbol، لا بالعمود أبدًا. النموذج الذي يُطلَب منه عمود يخمّن، والتخمين الخطأ يُحَل إلى رمز آخر على السطر نفسه — جواب يبدو صحيحًا وهو عن شيء غيره. إغفال symbol في فعل تنقّل خطأ، لا تخمين للعمود الأول.

الإجراء	الوسائط	ما يُعاد
diagnostics	file (أو "*")	أخطاء وتحذيرات؛ و"*" يشغّل فاحص المشروع بدل ذلك
definition	file وline وsymbol	أين يُصرَّح بالرمز
type_definition	file وline وsymbol	أين يُصرَّح بنوعه
implementation	file وline وsymbol	التنفيذات الملموسة
references	file وline وsymbol	كل استخدام، بحد 50
hover	file وline وsymbol	التوقيع وتعليق التوثيق
symbols	query أو file	بحث في مساحة العمل بـ query (بحد 100)؛ ورموز المستند بـ file (بحد 200)
code_actions	file وline وsymbol	الإصلاحات السريعة التي يعرضها الخادم
status	—	أي الخوادم تعمل، ولأي جذور
reload	—	يعيد تشغيل الخادم لهذا الجذر

التشخيصات عند الكتابة

المكسب ليس في الأداة. write وedit وapply_patch مغلَّفة: بعد الكتابة يُزامَن الملف ويُحفَظ عبر خادم اللغة، ولا تُدمَج في نتيجة الأداة إلا التشخيصات المُستحدَثة. يعلم الوكيل أنه كسر البناء لحظة كسره، من غير أن يتذكّر أن يسأل.

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

lsp_rename — إعادة تسمية على نطاق المشروع

أداة منفصلة من مستوى write لسبب واحد بالضبط: المستوى يقرّر الظهور. دمج إعادة التسمية في lsp إما يمنح مستكشفًا للقراءة فقط القدرة على إعادة كتابة المستودع، وإما يضع كل hover خلف مطالبة موافقة.

الوسيط	المعنى
file	أين يوجد الرمز
line	سطر يبدأ من 1
symbol	سلسلة فرعية تعرّفه على ذلك السطر
new_name	الاسم الجديد

---

ast_grep — بحث بنيوي

يجد الشفرة بـالشكل لا بالنص. يطابق $NAME أي عقدة، ويطابق $$$NAME تتالي أشقاء، و$_ بدل عام لا يربط شيئًا.

الخاصية التي تجعله مُطابِقًا لا تعبيرًا نمطيًا بخطوات إضافية: المتغيّر الوصفي إذا تكرّر في نمط واحد فلا بد أن يلتقط النص نفسه.

ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")

يطابق حارسًا يتخلّص مما اختبره، ولا يطابق حارسًا يتخلّص من شيء غيره.

الوسيط	المعنى
pattern	شذرة شفرة بمتغيّرات وصفية
path	ملف أو دليل للبحث؛ والافتراضي مساحة العمل كلها
language	معرّف قواعد نحوية من المجموعة المشحونة (dart وpython وrust وc، …). يُستنتَج حين يسمّي path ملفًا
max_results	الافتراضي 50

يُحلَّل النمط بقواعد الملف النحوية نفسها

فيطابق dispose(x) الاستدعاء مهما تباعد أو التُفّ أو عُلِّق — ولا يطابق المحارف نفسها داخل نص حرفي أو تعليق.

تُحلَّل الشذرة في سقالة، لا عارية

dispose(x) إذا حُلّل في المستوى الأعلى من Dart فهو توقيع دالة سليم. يجرّب مُصرِّف النمط سلّمًا من السياقات (عبارة، تعبير، عضو صنف، تصريح) ويأخذ أول سياق يقبل الشذرة. النمط الذي لا يقبله أي سياق يُبلَّغ بتعذّر تحليله، بدل أن يُبحث عنه ثم لا يُوجَد في صمت.

ast_edit — إعادة كتابة بنيوية مُجهَّزة

المطابقة نفسها، مع قالب rewrite تُستبدَل فيه المتغيّرات الوصفية. لا يُكتَب شيء. يُجهَّز التغيير، وتسمّي النتيجة edit_id.

ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")
→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"

الوسيط	المعنى
pattern	ما يُطابَق
rewrite	ما يُوضَع مكانه، مع استبدال $NAME
path	النطاق؛ والافتراضي مساحة العمل كلها
language	معرّف اللغة

resolve — تثبيت تغيير مُجهَّز أو تجاهله

الوسيط	المعنى
edit_id	من نتيجة (proposed)
action	accept أو discard

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

---

debug — قيادة المصحّح

تُسجَّل حين يملك التشغيل مشرف جلسة تصحيح ودليل عمل ومعرّف محادثة. قدرة المحوّل على البدء فعلًا تُكتشَف عند الاستدعاء، بقاعدة التقاطع نفسها التي لخادم اللغة (علامة جذر و ثنائي). مستوى exec، وليست آمنة للتوازي (الجلسة حالة تمتد عبر الاستدعاءات، فتجاوز continue لـ stack يقرأ إطارًا سبق أن تحرّك).

جلسة واحدة لكل محادثة، بمهلة TTL صارمة (30 دقيقة). يُرفَض launch ثانٍ بدل أن يحل محل الأول في صمت.

العملية	الوسائط	ملاحظات
adapters	—	أي المحوّلات صالحة هنا، ولماذا لا
status	—	هل هناك جلسة قيد التشغيل، وأين توقفت
breakpoints	file وlines[]	lines الفارغ يمسح الملف. يجوز ضبطها قبل الإطلاق
launch	program وargs[]	يبدأ البرنامج متوقفًا عند نقاط الإيقاف
attach	port	يتصل بهدف تصحيح يعمل أصلًا
continue	thread_id?	يتابع حتى التوقف التالي
pause	thread_id?	يوقفه حيث هو
step_over / step_in / step_out	thread_id?	يتقدّم خطوة واحدة
threads	—	معرّفات الخيوط وأسماؤها
stack	thread_id?	الإطارات، بحد 30
scopes	frame_id	نطاقات الإطار، ولكل منها reference
variables	reference	الأبناء، بحد 50، والقيم بحد 400 محرفًا
evaluate	expression وframe_id?	يُقيَّم في نطاق الإطار نفسه
output	—	stdout وstderr لهدف التصحيح، بحد
terminate	—	ينهي الجلسة ويقتل المحوّل

المحوّلات

المعرّف	الأمر	علامات الجذر
dart	dart debug_adapter	pubspec.yaml
debugpy	python3 -m debugpy.adapter	pyproject.toml وsetup.py وrequirements.txt
lldb	lldb-dap	Cargo.toml وCMakeLists.txt
delve	dlv dap	go.mod

يفضّل debugpy مجلد .venv/bin أو venv/bin المحلي للمشروع على $PATH: مفسّر python على $PATH بيئة أخرى، والاتصال من البيئة الخطأ يفشل بشكل يُقرأ على أنه شفرة مكسورة.

---

eval — مفسّرات دائمة

خلية Python أو JavaScript تبقى متغيراتها ووارداتها والبيانات المحمّلة بين الاستدعاءات. مستوى exec، وليست آمنة للتوازي.

الوسيط	المعنى
code	الخلية
description	مطلوب. من 5 إلى 10 كلمات لعنوان نص المحادثة
language	python (الافتراضي) أو javascript
reset	يتخلّص من المفسّر ويبدأ نظيفًا أولًا

• يُعاد آخر تعبير كما يفعل الدفتر.
• يعمل display()، ويُعرَض إطار pandas جدولًا، ويعود شكل matplotlib صورة يعرضها نص المحادثة.
• اصطلاحات IPython التي تُكتَب تلقائيًا — %pip و%cd و!cmd و%%bash و%%timeit — تُعاد كتابتها شفرة عادية. يُخلي %pip أيضًا sys.modules، فيرى import التالي ما ثُبّت للتو.

استدعاء أدواتك من داخل خلية

contents = tool("read", {"path": "lib/auth.dart"})

يعيد الجسر الدخول إلى سجل أدوات الإطار، فتُطبَّق الضوابط والموافقة وكل غلاف كما تُطبَّق على استدعاء يصدره النموذج. يسلك أنبوب النواة نفسه لا مقبس loopback: بلا منفذ، وبلا سر، وبلا قاعدة خروج.

مهلة الخلية ميزانية خمول (الافتراضي 5 دقائق)، وتُعلَّق ما دام استدعاء مجسَّر معلّقًا، فلا تُقتَل خلية تتفرّع إلى وكلاء فرعيين في منتصف التفريع.

أين تعمل النواة

في الحاوية المعزولة للمحادثة إن كانت لها واحدة، وعلى المضيف فيما عدا ذلك. لا تقلع حاوية معزولة لتصل إلى هناك — القاعدة نفسها التي تمنع إقلاع تبويب المنصة تلقائيًا.

---

ask_user — سؤال الإنسان

مستوى read. الوسيلة الوحيدة التي يسأل بها تشغيل المشغّل أي شيء. تعرض بطاقة مرقّمة في المحادثة وتحجب حتى يجيب أحد، أو يتخطى، أو تنتهي مهلة السؤال. لا تكتب السؤال رسالة دردشة أبدًا — فذلك ينهي الجولة.

الوسيط	المعنى
question	ما يُسأل
context	اختياري: لماذا تسأل، وما الذي يتوقف على الجواب
options[]	خيارات، كل منها {label, description?}
allow_free_text	هل يُقبَل جواب مكتوب
multi_select	هل يجوز اختيار عدة خيارات

التخطي نجاح: تابع بافتراض معلَن ولا تسأل مرة أخرى. انتهاء المهلة خطأ بالتعليمات نفسها. مطالبات الإذن («أأفعل هذا؟») بوابة منفصلة، وتُعرَض بالبطاقة نفسها في المحادثة.

لا تُسجَّل إلا حين يوجد منفذ أسئلة ومساحة هدف معًا. من غير إنسان متصل يفشل الاستدعاء بدل أن يحجب إلى الأبد — وضع الإغلاق عند الفشل نفسه الذي يأخذه prompt في الضوابط حين لا يكون هناك معتمِد متصل.

---

vibe_* — توجيه عمال الخلفية

لا تُسجَّل إلا ما دام وضع vibe مفعّلًا. الخمس كلها من مستوى read: البوابة على أدوات العامل، حيث يجري التعديل فعلًا.

الأداة	الوسائط	ملاحظات
vibe_spawn	brief وlabel وtier?	يعيد فورًا؛ ويواصل العامل
vibe_send	worker_id وmessage	يلحق بالتكليف ويعيد التشغيل
vibe_wait	worker_id وtimeout_seconds?	يحجب حتى يستقر
vibe_kill	worker_id	يوقفه
vibe_list	—	المستوى والحالة والوقت المنقضي وآخر نتيجة

tier هو fast (عمل آلي بمواصفة واضحة) أو good (تصميم، أو تقدير، أو مراجعة ما أنتجه عامل fast).