كيفاش تجهّز Shim لوكلاء البرمجة بالذكاء الاصطناعي المحلي أولا

شنو هو Shim؟

Shim هو وكيل ذكاء اصطناعي صغير ومحلي فالأصل، مصمّم للمستخدمين ديال الطرفية. كيوفّر واجهة موحّدة لربط واجهات برمجة النماذج المدعومة، وAgent Skills، وخوادم Model Context Protocol، بلا ما يحتاج تطبيق مكتبي، ولا خدمة كتخدم فالخلفية، ولا قاعدة بيانات، ولا Docker، ولا Node.js، ولا Python.

Shim كيتوزّع على شكل ملف تنفيذي ثابت، وكيستعمل JSON العادي للإعدادات وملفات JSONL كتزاد فيها الجلسات بلا تعديل المحتوى السابق. مفاتيح API كيتقراو من متغيّرات البيئة، وما كيتكتبوش فإعدادات Shim.

Shim هو harness، وماشي محرّك للاستدلال. أوزان النماذج المحلية خاصها تخدم عبر خادم للاستدلال بحال Ollama أو LM Studio أو llama.cpp أو أي خدمة أخرى متوافقة. النماذج المستضافة خاصها تكون متاحة عبر واجهة HTTP مدعومة.

الميزات الرئيسية

• تحكّم بالمحادثة وبأوامر صريحة: كتب طلبات التسيير باللغة العادية أو استعمل واجهة CLI الكاملة القابلة للبرمجة النصية.
• توجيه الأوامر محلياً: نموذج محلي صغير اختياري يقدر يحوّل طلبات التسيير لأوامر Shim مسموح بها.
• مزودو نماذج متعددون: Shim كيدعم واجهات متوافقة مع OpenAI، وAnthropic Messages، وإعدادات مسبقة للمزودين المحليين، ونقاط نهاية مخصّصة.
• Agent Skills: كيكتاشف ملفات SKILL.md وكيحمّل التعليمات الكاملة ديالها غير ملي كيكون محتاجها.
• الربط مع MCP: ربط خوادم MCP عبر stdio أو Streamable HTTP، وإتاحة الأدوات ديالها للوكيل.
• ضوابط الصلاحيات: اختار بين القراءة فقط، أو التنفيذ بعد التأكيد، أو التنفيذ التلقائي.
• حالة قابلة للنقل: الإعدادات والجلسات كيتستعملو فيها ملفات JSON وJSONL عادية.
• بلا تتبّع: نشاط الشبكة محدود فاستدعاءات النماذج الصريحة، وتنزيل المهارات، والاكتشاف المحلي، وخوادم MCP المكوّنة.

ثبّت Shim

الخيار 1: حمّل إصداراً

حمّل الملف التنفيذي الثابت المناسب لـ Windows أو macOS أو Linux من صفحة إصدارات Shim. حطّ الملف التنفيذي فـ PATH ديال النظام، ومن بعد هيّأ Shim:

shim setup
shim

إلى شغّلتي الملف التنفيذي اللي حمّلتيه مباشرة من المجلد الحالي فـ PowerShell، استعمل .\shim.exe.

الخيار 2: ثبّت باستعمال Go

إلى كان Go 1.25 أو إصدار أحدث متوفّر، ثبّت Shim بهاد الأوامر:

go install github.com/Balanov/shim/cmd/shim@v0.1.0
shim setup

الخيار 3: بنِ من المصدر

نسخ المستودع، شغّل الاختبارات ديالو، وبنِ الملف التنفيذي:

git clone https://github.com/Balanov/shim.git
cd shim
go test ./...
go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim
./shim setup

المستودع فيه حتى scripts/build.ps1 لـ Windows وscripts/build.sh لأنظمة Unix.

ربط نموذج

اكتاشف خوادم النماذج المحلية

إلى كان Ollama أو LM Studio أو llama.cpp أو خادم محلي آخر متوافق خدام من قبل، طلب من Shim يكتاشف النماذج المتاحة ويكوّنها:

shim model discover --add

ما كيتضمّنش Shim أوزان النماذج وما كينزّلهاش فصمت. خادم النماذج هو اللي كيبقى مسؤول على تشغيل النموذج المحلي.

زِد مزوّداً مستضافاً

Shim فيه إعدادات مسبقة لـ OpenAI وOpenRouter وAnthropic وGemini وGitHub Models وHugging Face، وزيد عليهم مزودين محليين آخرين. عيّن بيانات الاعتماد ديال المزود فمتغيّر البيئة قبل ما تزيد النموذج.

مثلاً، مستخدمو PowerShell يقدرو يكوّنو OpenRouter بهاد الشكل:

$env:OPENROUTER_API_KEY = "..."
shim model add openrouter your/model --name main --use
shim model test main

متغيّرات بيانات اعتماد أخرى كتضم OPENAI_API_KEY وANTHROPIC_API_KEY وGEMINI_API_KEY وGITHUB_TOKEN وHF_TOKEN. استعمل الآلية العادية ديال نظام التشغيل أو الصدفة ديالك لتدبير الأسرار بشكل دائم. ما تحطّش مفاتيح API فإعدادات مشروع Shim.

أمثلة على إضافة نماذج مستضافة:

shim model add openrouter anthropic/claude-sonnet-4.5 --name claude --use
shim model add openai gpt-5 --name gpt --use
shim model add huggingface org/model --name hf --use

زِد نقطة نهاية مخصّصة

بالنسبة لأي نقطة نهاية مدعومة ومتوافقة مع OpenAI، عطِ عنوان URL الأساسي ومعرّف النموذج:

shim model add custom my-model --name mine \
  --base-url http://127.0.0.1:8000/v1 --use

المزوّد المخصّص يقدر يستعمل محوّل OpenAI متوافق أو محوّل Anthropic. بيانات الاعتماد اختيارية وقابلة للتهيئة بالنسبة للخدمات المخصّصة.

شغّل أول مهمة للوكيل

استعمل تشغيل لمرة واحدة

أكثر طريقة آمنة لفحص مستودع هي تشغيل بوضع القراءة فقط:

shim run --read-only "explain this repository"

بالنسبة لمهمة كتحتاج تعديل الملفات وتشغيل أوامر التحقّق، استعمل --yes للموافقة على الإجراءات فداك التشغيل، و--verbose باش تحصل على مخرجات إضافية:

shim run --yes --verbose "fix the tests and verify the result"

استعمل --yes غير ملي تكون واثق من مساحة العمل، والنموذج، والمهمة المطلوبة.

بدا الطرفية التفاعلية

شغّل Shim بلا أمر فرعي باش تبدا جلسة تفاعلية:

shim

من بعد تقدر تدخل طلباً للوكيل بحال:

fix the failing tests in this repository

شغّل shim help باش تشوف جميع الأوامر المتاحة.

تحكّم فـ Shim باللغة العادية

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

shim router use ollama/qwen3:4b

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

استعمل نقطة نهاية ديال نموذج على loopback إلا كان خاص التوجيه يبقى فالجهاز ديالك. الراوتر كيتكلف غير بتفسير الأوامر؛ أما النموذج الأساسي المختار كيتكلف بالمحادثة العادية باللغات اللي كيدعمها.

إضافة مهارات للوكيل

Shim كيقلب على ملفات SKILL.md فالمجلد العام skills/ اللي حدّ الإعدادات ديالو، وفمجلدات مساحة العمل .shim/skills/ و.agents/skills/ و.claude/skills/.

فالأول، كيتزاد فـ system prompt غير سميات المهارات والأوصاف ديالها. التعليمات الكاملة كيتحمّلها عند الحاجة باستعمال load_skill، وهاد الشي كينقص من المحتوى غير الضروري فـ prompt.

زيد المهارات انطلاقاً من مرجع ديال مستودع، أو رابط GitHub، أو مسار محلي:

shim skill add owner/repository
shim skill add https://github.com/owner/repository
shim skill add ./local/skill-or-collection

فحص المهارات المثبتة ودوّرها بهاد الأوامر:

shim skill list
shim skill show name
shim skill remove name

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

ربط خوادم MCP

إضافة خادم Stdio

المثال التالي كيسجل خادم ملفات MCP للمجلد الحالي، كيعرض الأدوات ديالو، وكيستعمل أداة مباشرة:

shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
shim mcp tools filesystem
shim mcp call filesystem list_allowed_directories '{}'

إضافة خادم Streamable HTTP

سجل نقطة نهاية بعيدة من نوع Streamable HTTP بإعطائها سميّة ورابط:

shim mcp add internal https://mcp.example.com/mcp

عرض الخوادم المكوّنة أو حيدها بهاد الأوامر:

shim mcp list
shim mcp remove filesystem

أدوات MCP كيتعرضو بأسامي بحال mcp_filesystem_list_allowed_directories. فالوضع الافتراضي ديال الصلاحيات، استدعاءات MCP كتحتاج التأكيد.

تقدر تزيد ترويسات HTTP ومتغيرات البيئة ديال stdio من خلال إعدادات Shim بصيغة JSON. القيم كدعم توسيع ${ENV_VAR}، وبهذا كتقدر تخلي الأسرار فالبيئة بدل ملفات الإعدادات.

اختيار وضع الصلاحيات

Shim كيبدا افتراضياً فالوضع ask. قراية ملفات مساحة العمل وعرضها والبحث فيها مسموحين، بينما كتابة الملفات وتعديلها وأوامر shell واستدعاءات MCP كتحتاج التأكيد.

اختار السياسة العامة ديال الصلاحيات بهاد الأوامر:

shim permissions read-only
shim permissions ask
shim permissions auto

• read-only: كيعطل الكتابة وأوامر shell واستدعاءات MCP.
• ask: كيطلب التأكيد على العمليات المهمة.
• auto: كيخلي الوكيل يخدم بلا مطالبات بالتأكيد.

إلا كانت التغييرات مؤقتة، فضّل shim run --read-only أو shim run --yes بدل ما تبدل الإعداد العام الافتراضي.

Shim ماشي sandbox ديال نظام التشغيل. أوامر shell وخوادم MCP كيتشغلو بصلاحيات حساب المستخدم ديالك. استعمل container أو آلة افتراضية أو sandbox ديال نظام التشغيل مع المهام غير الموثوقة.

أدوات الملفات ديال Shim كترفض تجاوز المسارات المعجمي والهروب عبر الروابط الرمزية من مساحة العمل، ولكن هاد الفحوصات ما كتقدرش تحاصر عملية خبيثة. اعتبر مخرجات النموذج ومحتوى المستودعات والمهارات وردود MCP بيانات غير موثوقة.

تدبير الجلسات والإعدادات

فحص الجلسات، بدا جلسة جديدة ونقية، أو كمل جلسة سابقة:

shim session list
shim session new
shim run --resume SESSION_ID "continue"

استعمل أوامر التشخيص والإعدادات ملي كتكون كتقلب على سبب مشكل:

shim status
shim doctor
shim config path
shim config show

ملف الإعدادات الرئيسي هو shim/config.json فالمكان اللي كيخصصو نظام التشغيل لإعدادات المستخدم. تقدر تبدل المسار بمتغير البيئة SHIM_CONFIG أو بالخيار --config. سجلات الجلسات كتتخزن فملفات JSONL كتزاد فيها المعطيات فقط، حدّ ملف الإعدادات.

نصائح متقدمة

1. بدا بوضع القراءة فقط. استعمل --read-only لتحليل المستودع قبل ما تسمح بالتعديلات أو بتنفيذ الأوامر.
2. جرّب إعدادات النماذج. من بعد ما تزيد مزوداً، شغل shim model test NAME باش تتحقق من الاتصال وبيانات الاعتماد.
3. خلي التوجيه محلياً. عيّن نموذج loopback كراوتر ملي خاص تصنيف الأوامر باللغة الطبيعية يبقى فالحاسوب ديالك.
4. استعمل توسيع البيئة لأسرار MCP. أشر إلى ${ENV_VAR} فالإعدادات بدل ما تخزن القيم السرية مباشرة.
5. فضّل صلاحيات كل تشغيل. استعمل --read-only و--yes للمهام الفردية بدل ما تخلي السياسة العامة على auto.
6. راجع تعليمات الأطراف الخارجية. فحص المهارات المحمّلة وخذ بعين الاعتبار سلوك خادم MCP قبل منح الولوج إلى shell أو الملفات أو الشبكة.
7. شغل التشخيص أولاً. أوامر بحال shim status وshim doctor تقدر تعاون فالتعرف على مشاكل الإعدادات قبل تشغيل الوكيل.

الخلاصة

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