البداية مع opencode-rust: وكيل برمجة بالذكاء الاصطناعي مبني بـ Rust

شنو هو opencode-rust؟

opencode-rust هو وكيل مفتوح المصدر للبرمجة بالذكاء الاصطناعي، مطبّق بلغة Rust. كيوفّر واجهة مستخدم فالطرفية، وتنفيذ الأوامر مرة وحدة، وسيرفر HTTP، ودعم الويب، وتكامل ACP لسيرورات عمل الوكلاء المحليين ديال الذكاء الاصطناعي.

المحرّك كيجمع بين الجلسات، وتنفيذ الأدوات، وMCP، وLSP، وتوجيه المزوّدين، وتخزين SQLite، وجسر إضافات TypeScript. كيخدم بلا Docker ولا أي بيئة حاويات أخرى. كتستعمل Rust باش يبقى استهلاك الموارد محدود، عبر أجسام الطلبات المتدفقة، وسجل المحادثات المعتمد على SQLite، ومخططات الأدوات المخزنة مؤقتاً، وحالة مجمّعة لكل مجلد مع الإخلاء باستعمال LRU وTTL.

اختار طريقة التثبيت

جميع طرق التثبيت المدعومة كتوفّر الأمر opr، ولكن السلوك ديال الأمر كيختلف حسب طريقة التثبيت.

التثبيت باستعمال npm

npm كيدعم Linux وmacOS وWindows، وكيحمّل حزمة ثنائية مسبقة البناء للمنصة الحالية. ما كيكومبيلش المشروع وقت التثبيت.

npm install -g opencode-rust

مشغّل npm هو سكريبت Node كيوجّه الأوامر للمحرّك. حزم المنصات المتوفرة كتشمل macOS ARM64 وx64، وLinux x64 وARM64 ببناءات GNU، وLinux x64 musl، وWindows x64 MSVC.

التثبيت باستعمال Homebrew

فـ macOS ولا Linux، ثبّت صيغة Homebrew بهاد الأمر:

brew install vakandi/tap/opencode-rust

هاد العملية كتثبّت opr بلا ما تحطّ ثنائي opencode فـ مسار Homebrew، وبالتالي ما كيغطّيش على واجهة OpenCode CLI الأصلية. Homebrew كيبني من المصدر، وداكشي علاش كيثبّت سلسلة أدوات Rust كتبعية للبناء.

البناء من المصدر

نسخ المستودع وشغّل المثبّت:

git clone https://github.com/vakandi/opencode-rust.git
cd opencode-rust
./install.sh

المثبّت كيبني الثنائي ديال الإصدار وكيثبّت opr مع اختصارات الوكلاء. كيدير بصمة لمصادر Rust وملفات بيان Cargo، وبالتالي المشروع اللي ما تبدّلش ما كيتعاودش بناؤه. استعمل --force باش تعاود البناء كيفما كانت الحالة.

ملي كتستعمل Homebrew ولا مثبّت المصدر، opr كيكون هو ثنائي المحرّك بحد ذاتو. استعمل أمراً فرعياً صريحاً ملي كتدوز الخيارات:

opr tui --some-flag

مع npm، المشغّل كيوجّه الخيارات للواجهة TUI، وداكشي علاش opr --some-flag كيتفسّر بطريقة مختلفة.

وجّد البيئة

خاص Node.js 18 ولا أحدث لجسر الإضافات ولاطلاق سيرفرات MCP عبر npx، كيفما كانت طريقة التثبيت.

خاصك حتى مفتاح ديال المزوّد قبل أول تشغيل. مثلاً، عيّن مفتاح Anthropic فالـ shell ديالك:

export ANTHROPIC_API_KEY=sk-ant-...

استعمل إعدادات المزوّد وبيانات الاعتماد اللي كيدعمها إعداد OpenCode ديالك. حاول تخلي المفاتيح برا نظام التحكم فالمصدر وبرا سجل الأوامر ديال shell قدر الإمكان.

شغّل أول جلسة

بدا الواجهة التفاعلية TUI

شغّل واجهة الطرفية بهاد الأمر:

opr

الواجهة TUI هي الواجهة التفاعلية الافتراضية. كتعرض الوكيل والموديل النشيطين، وكتدفق مخرجات المساعد، وكتوفّر إكمال الأوامر عبر النافذة المنبثقة ديال /.

شغّل طلب واحد

إلى بغيتي طلب آلي يكمل حتى النهاية، استعمل run:

opr run "check this repo for risks"

بخلاف استدعاء بسيط للمزوّد، run كيسوق الحلقة الكاملة ديال طلب الجلسة. الأدوات كتتنفّذ، والوكلاء الفرعيون اللي كيتسناو كيكملو الخدمة، والعمل فـ الخلفية كيتصرّف فيه كامل قبل ما تخرج العملية.

بدا سيرفر HTTP

باش تعرّض المحرّك عبر سيرفر HTTP ديالو، شغّل:

opr serve --port 3000

السيرفر كيستعمل نفس محرّك الجلسات وكيَدعم البنية التحتية ديال HTTP والتدفق والوكلاء فالمشروع.

استعمل وكلاء مسمّيين

الواجهة TUI فيها الوكيلين المدمجين build وplan. وكيل build هو وكيل التطوير الافتراضي بصلاحيات كاملة، بينما plan مخصّص للتحليل والاستكشاف للقراءة فقط. ضغط على Tab باش تبدّل الوكلاء فالواجهة TUI.

مثبّت المصدر كينشئ حتى اختصارات للوكلاء المسمّيين:

gilfoyle "fix this failing test"
setbon "write 5 ad hooks"
googlebot "audit my meta tags"

هاد الاختصارات كتشغّل طلب واحد مع قيمة --agent المناسبة. إلا عيّطتي على واحد منها بلا طلب، كيطبع معلومات الاستعمال فـ standard error وكيخرج بالحالة 2.

يمكن إعداد وكلاء إضافيين فإعدادات OpenCode ديالك وفمخازن وكلاء oh-my-opencode فـ ~/.omo/omo.jsonc ولا ~/.config/omo/omo.jsonc. إعدادات الوكلاء من هاد المواقع تقدر تغلب الإعداد الافتراضي ديال الإضافة، والوكلاء كيتطابقو باستعمال slugs معيارية حتى إلا اختلفات الأسماء اللي كيبانو.

كوّن المشاريع والجلسات

ملفات الإعدادات كيتدمجو ملي كيقلب النظام لفوق انطلاقاً من مجلد الخدمة. الأسماء المدعومة على مستوى المشروع هي:

• opencode.jsonc
• opencode.json
• .opencode/opencode.jsonc
• .opencode/opencode.json

الإعدادات العامة الافتراضية كتتخزّن فـ ~/.config/opencode/opencode.json ولا النسخة المكافئة ديالها بصيغة JSONC. تعريفات الوكلاء تقدر حتى هي تتخزّن فمواقع oh-my-opencode اللي تذكرات لفوق.

الجلسات كتتخزّن فـ SQLite وكتدعم الإنشاء، والاستمرار، والتفريع، والاستيراد والتصدير، والعلاقات بين الوالد والأبناء. باش تشوف مكان قاعدة البيانات، استعمل:

opr db path

وباش تشوف مواقع تشغيل أخرى، بما فيها مجلد البيانات اللي كيستعملو تجمع الوكلاء الوسيطين، استعمل:

opr debug paths

استعمل أدوات MCP

opencode-rust كيدعم MCP عبر stdio وHTTP. سيرفرات MCP كيتحمّلو من الإعدادات، وكيبداو بالتوازي داخل مهلة قصوى ديال 90 ثانية، وكيتسجلو فنفس سجل الأدوات لكل دورة اللي كيستعملو الوكيل.

هاد الشي كيعني باللي الأدوات اللي كيعرّضها سيرفر MCP تقدر توصل للموديل وتتنفّذ كجزء من دورة ديال الوكيل. تأكد باللي Node.js والحزم المطلوبة ديال سيرفر MCP متوفّرة قبل ما تبدا السيشن.

المشروع كيستعمل JSON مفصول بسطر جديد فالنقل ديال MCP عبر stdio. هاد الشي مختلف على التأطير ديال LSP اللي كيستعمل Content-Length، لذلك إعدادات سيرفر MCP خاصها تستهدف وسائل النقل والتعريفات المتوافقة مع MCP.

تأكد باللي الخدمة فالخلفية كتكمّل

الأمر run كيقبل مهلة زمنية لتفريغ المهام اللي فالخلفية:

opr run --wait-background-timeout 120 "run the requested task"

من بعد الدورة الرئيسية، المحرّك كيتسنى السيشن تولّي فحالة الخمول، كيبثّ إطارات الأطفال المسجّلة من طرف oh-my-opencode، وكيشيّك على حالة الاستمرار. المهلة الافتراضية هي 120 ثانية.

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

إعداد البروكسي المتناوب

المحرّك فيه مُمرّر محلي HTTP وCONNECT كيدوز الطلبات وكيبدّل بين مرشّحي بروكسيات سكنية. كيختار المزوّد اللي داز أطول وقت من آخر استعمال تقريباً كل 120 ثانية، وكيفحص المرشحين قبل الاستعمال، وكيحط الإدخالات المرفوضة فالعزل.

ملف التجميعة الافتراضي كاين فـ:

• macOS: ~/Library/Application Support/opencode/proxy-pool.txt
• Linux: ~/.local/share/opencode/proxy-pool.txt
• Windows: %LOCALAPPDATA%\opencode\proxy-pool.txt

عيّن OPENCODE_PATHS_ROOT باش تبدّل مكان تخزين البيانات. المسار الناتج ديال التجميعة هو $OPENCODE_PATHS_ROOT/opencode/proxy-pool.txt.

الإدخالات كتستعمل المضيف والمنفذ، ومعاهم اختيارياً بيانات الدخول وبيانات وصفية:

198.51.100.10:8080
203.0.113.24:1080
198.51.100.31:3128:myuser:mypass
203.0.113.77:8000 | note:rotates hourly

خلي الملف فيه غير الإدخالات. رغم أن بعض الأمثلة كتعرض السطور اللي كاتبدا بـ # على أساس تعليقات، المحلّل ما كيطبّقش صيغة التعليقات؛ هاد السطور كيتجاهلوها حيث إدخالات غير صالحة. المرشحين اللي فشلو ومعلومات الملكية كيتحافظ عليهم فملفات الأشقاء proxy-quarantine.json وproxy-claims.json.

خاص تشغيل البروكسي يتم عبر opencode_proxy::start() وماشي بتصدير متغيّرات البروكسي يدوياً. خاص العميل يتوصل بإعدادات البروكسي قبل ما يتبنى سجلّ المزوّدين. إلا كانت التجميعة خاوية ولا ما قدرش يقراها، كيرجع خطأ بلا ما يشغّل مستمع غادي يفشل فكل طلب.

استكشف أوامر الواجهة

واجهة CLI فيها أوامر للاستعمال التفاعلي، والسيشنات، والخدمات، والإعدادات، والمصادقة، والوكلاء، وتصحيح الأخطاء، وMCP، ونقل البيانات، والصيانة:

tui      attach   run      serve    web      acp      models
session  stats    db       config   auth     agent    debug
mcp      export   import   github   pr       upgrade  uninstall
generate version

من بين الخيارات المفيدة ديال run كاينين --continue، و--session، و--fork، و--agent، و--format، و--title، و--dir، و--port، و--variant، و--thinking، و--wait-background-timeout.

التطوير والتحقق

إلا كنت خدام على المستودع، شغّل اختبارات وفحوصات مساحة العمل بهاد الأوامر:

cargo test --workspace
cargo build --release --bin opencode
cargo clippy --workspace --all-targets

المستودع منظّم فحزم خاصة بواجهة CLI، والسيرفر، والسيشنات، والوكلاء، والأدوات، والمزوّدين، وMCP، والإضافات، وLSP، والتخزين، وTUI، والصلاحيات، والمسارات، والبروكسي، وأدوات مرتبطة بها. التوثيق الخاص بكل حزمة متوفّر فالمجلد docs/.

الخلاصة

opencode-rust كيوفّر محرّك OpenCode مبني بـ Rust، فيه واجهة TUI تفاعلية، وتنفيذ كامل للسيشنات، ووكلاء قابلين للإعداد، وتكامل مع MCP والإضافات، وتخزين SQLite، وولوج عبر HTTP. بدا بـ npm، ولا Homebrew، ولا ببناء من المصدر، وضبط مفتاح ديال المزوّد، واستعمل opr، ولا opr run، ولا opr serve على حساب سير العمل ديالك.

المشروع منشور برخصة MIT وما عندوش علاقة بفريق OpenCode.