OpenCode: من البداية إلى الاحتراف — دليل الإعداد

دليل موضوعي وخالٍ من الضجيج لتحويل تثبيت OpenCode العادي إلى بيئة برمجة احترافية. استناداً إلى أبحاث عملية (Data Leads Future, DEV.to, Medium) واختبارات واقعية. آخر تحديث: 2026-07-29

1. التثبيت

OpenCode مكتوب بلغة Go، ويتم توزيعه كملف ثنائي واحد. يتطلب bun كاعتماد تشغيل.

التثبيت بأمر واحد

curl -fsSL https://opencode.ai/install | bash

في حالة الفشل

يعتمد OpenCode على bun. إذا كانت بيئتك تمنع التثبيت التلقائي:

npm install -g bun

ثم أعد تشغيل script التثبيت، أو ثبته يدوياً من opencode.ai.

ما تحصل عليه

• opencode CLI — واجهة TUI طرفية (Bubble Tea، تعمل بلوحة المفاتيح)
• OpenCode Desktop — تطبيق رسومي مستقل (موصى به للاستخدام اليومي)
• إضافات VS Code / Cursor / Zed — عبر متجر الإضافات

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

تطبيق سطح المكتب أكثر كفاءة بشكل ملحوظ للعمل اليومي. يدعم أصلاً Workspaces (git worktrees)، وهو ما لا تفعله TUI. هذا وحده يستحق التثبيت.

ومع ذلك، قم بتثبيت CLI أولاً — بعض الإضافات وأدوات الإعداد تتحقق من وجود أمر OpenCode أثناء التهيئة.

التحقق من التثبيت

opencode --version

يجب أن ترى رقم الإصدار (الحالي: 1.15+).

2. تكوين المزود (حرج)

هذا هو الخطأ الأكثر شيوعاً. يدعم OpenCode أكثر من 75 مزود LLM، لكن طريقة تكوينهم مهمة.

❌ الطريقة الخاطئة

ترى أن نموذجك ليس في القائمة، لذا تضغط على "مزود مخصص" وتدخل: معرف النموذج، URL الأساسي، مفتاح API.

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

✅ الطريقة الصحيحة

1. افتح OpenCode Desktop → الإعدادات → المزودون
2. انتقل إلى أسفل القائمة
3. اضغط على "إظهار المزيد من المزودين"
4. ابحث عن مزودك الفعلي (مثل OpenRouter, Together, Fireworks)
5. أدخل مفتاح API لذلك المزود

بمجرد التكوين، جميع النماذج من ذلك المزود تظهر مع بيانات تعريف كاملة.

العثور على معرف المزود الخاص بك

OpenCode يحفظه هنا:

~/.local/share/opencode/auth.json

النماذج المجانية المتاحة

• Big Pickle — نموذج مخفي متاح مجاناً
• DeepSeek V4 Flash — MoE محسن للكفاءة (284B إجمالي، 13B نشط)
• Nemotron 3 Super — MoE هجين من NVIDIA (120B، 12B نشط)

المزودون الموصى بهم (مدفوع)

3. إعداد الطرفية والمنصة

macOS / Linux

OpenCode يكتشف $SHELL تلقائياً. لا حاجة لأي إجراء.

Windows

OpenCode Desktop يستخدم PowerShell افتراضياً. مشكلتان: بعض البيئات تمنع PowerShell، واللغات غير الإنجليزية تسبب أخطاء في ترميز الأحرف. الحل: تعيين متغير البيئة SHELL، أو استخدام WSL / Git Bash.

4. AGENTS.md — ذاكرتك طويلة المدى

هذا أكثر شيء مؤثر يمكنك إعداده.

ماذا يفعل AGENTS.md

ثلاثة أشياء:

1. يثبت حقائق المشروع. بدون AGENTS.md، كل جلسة جديدة تجعل LLM يفحص المشروع بأكمله من الصفر.

2. يضيق توزيعات الاحتمالات (يقلل الهلوسة). LLMs تولد إجابات احتمالية. AGENTS.md يحول التوزيعات نحو اتفاقياتك.

3. يمنع أخطاء الاعتماديات. اكتب أدواتك في AGENTS.md.

إنشاء AGENTS.md

قم بتشغيل /init في OpenCode. تقوم IA بتحليل مشروعك وإنشاء خط أساس.

ما يحتويه AGENTS.md الجيد

# نظرة عامة على المشروع

Eva هي منصة مساعد IA شخصي. مستودع أحادي مع:
- Backend Python (FastAPI) في `/backend`
- Frontend React + TypeScript في `/frontend`
- إضافات خادم MCP في `/mcp-servers`

# الرصة التكنولوجية

- Python 3.14+ مع async/await في كل مكان
- React 19 + Tailwind CSS 4 لواجهة المستخدم
- Bun كبيئة تشغيل JavaScript

# الأوامر

- `uv sync --prerelease=allow` — مزامنة اعتماديات Python
- `bun install` — تثبيت اعتماديات الواجهة الأمامية
- `pytest` — تشغيل اختبارات Python

# اتفاقيات البرمجة

- تلميحات الأنواع: استخدم دائماً `str | None`، أبداً `Optional[str]`
- الاستيراد: المكتبة القياسية أولاً، ثم الطرف الثالث، ثم المحلية
- الغير متزامن: استخدم `async def` لجميع وظائف الإدخال/الإخراج

# قواعد البنية

- خدمات backend تتواصل عبر تمرير الرسائل، وليس الاستيراد المباشر
- خوادم MCP هي عمليات مستقلة وليست وحدات مدمجة

5. العاملان المدمجان: Plan vs Build

عامل Build (افتراضي)

وصول كامل للأدوات. استخدمه للمهام الواضحة لا لبس فيها. لا تستخدمه للمهام المعقدة أو الغامضة.

عامل Plan

وضع تحليل للقراءة فقط. يطرح أسئلة توضيحية. ينتج خطة تنفيذ.

سير العمل الاحترافي: كل متطلب جديد → عامل Plan → ملف خطة → جلسة جديدة → عامل Build

6. وضع سير عمل التخطيط (v1.15+)

تفعيله

export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

المراحل الخمس

7. Workspaces — التطوير المتوازي

تطبيق سطح المكتب لديه Workspaces، مبنية على git worktrees. انقر بزر الماوس الأيمن على أيقونة المشروع → تفعيل Workspace.

8. انضباط الجلسات

المشكلة: تدهور السياق — LLMs لديها تحيز للأولوية والحداثة.

القاعدة: بعد كل إنجاز رئيسي، ابدأ جلسة جديدة.

9. الأوامر المخصصة

حدد أوامر slash مخصصة كملفات .opencode/commands/<name>.md مع frontmatter و placeholder $ARGUMENTS.

10. العوامل المخصصة

• عام: ~/.config/opencode/agents/<name>.md
• مشروع: <project>/.opencode/agents/<name>.md

11. سير العمل للمشاريع المعقدة

صباحاً: مزامنة وتخطيط → تنفيذ: Build → مراجعة: إغلاق الحلقة

12. توقعات التكلفة

OpenCode Go: اشتراك $10/شهر.

13. مسار التقدم

المرحلة 2: OpenSpec (SDD) → المرحلة 3: Reflection → المرحلة 4: Loop Engineering

قائمة التحقق السريعة

• OpenCode CLI + Desktop مثبتان
• تم تكوين المزود عبر "إظهار المزيد من المزودين"
• تم تشغيل /init لإنشاء AGENTS.md
• OPENCODE_EXPERIMENTAL_PLAN_MODE=true مفعل
• تم إنشاء عامل مخصص واحد على الأقل