دمج OpenCode مع نماذج CodingPlanX المخصصة

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

---

🌟 مقدمة عن المشروع

OpenCode هو مساعد برمجة بالذكاء الاصطناعي للطرفية مفتوح المصدر بنسبة 100%. وهو مشابه في تصميمه لـ Claude Code ولكنه يوفر مرونة فائقة وقدرات تخصيص. غير مرتبط بأي مزود خدمة ذكاء اصطناعي محدد، يدعم التبديل السلس بين نماذج متعددة، يتميز بتكامل LSP (بروتوكول خادم اللغة) الأصلي، ويتمتع بواجهة مستخدم طرفية (TUI) صديقة للمحترفين.

1. الميزات الأساسية لـ OpenCode

OpenCode هو وكيل برمجة ذكاء اصطناعي مفتوح المصدر تم تطويره بواسطة فريق SST، وصُمم خصيصًا للمحترفين ومستخدمي الطرفية بكثافة:

• 🔓 مفتوح المصدر 100%: استنادًا إلى ترخيص MIT، الكود شفاف تمامًا.
• 🧠 دعم النماذج المتعددة: يمكن تكوينه والتبديل بسلاسة بين Claude و OpenAI و Google Gemini وغيرها.
• ⚡ دعم LSP الأصلي: بروتوكول خادم اللغة المدمج يوفر تحليلاً ذكيًا وتنقلًا سريعًا ودقيقًا للغاية في الكود.
• 🖥️ أولوية TUI: صُمم لمستخدمي الطرفية بواسطة مستخدمين مخضرمين لـ Neovim، ويمكن تشغيله بالكامل عبر لوحة المفاتيح.
• 🌐 بنية C/S: يدعم القيادة عن بُعد؛ قم بتشغيل الخادم محليًا وتحكم فيه عن بُعد عبر الهاتف المحمول أو جهاز كمبيوتر آخر.
• 🔄 وكلاء مدمجون مزدوجون: يتضمن build (وصول كامل للقراءة/الكتابة للتطوير الرئيسي) و plan (للقراءة فقط للتحليل والتخطيط) بشكل افتراضي.

2. oh-my-opencode (تحسين موصى به)

oh-my-opencode هو إضافة التحسين القصوى لـ OpenCode، والمعروف في المجتمع باسم "OpenCode on steroids" (OpenCode المنشط). يوفر تجربة برمجة ذكاء اصطناعي احترافية جاهزة للاستخدام.

ميزات التحسين الأساسية:

• وكلاء فرعيون غير متزامنين: قدرات معالجة المهام المتوازية المشابهة لـ Claude Code، مما يحسن الكفاءة بشكل كبير في المهام المعقدة.
• تكوينات الوكلاء المنسقة: تم تكوينه مسبقًا بأدوار وكلاء احترافية متعددة (مثل المهندس المعماري، أمين المكتبة، المستكشف).
• أدوات AST المتقدمة: تدعم إعادة الهيكلة الذكية، والتحليل العميق للكود، والبحث عن الرموز، والميزات المتقدمة الأخرى.
• وضع Ultrawork: ببساطة أضف ultrawork إلى المطالبة (prompt) لتمكين وضع المعالجة المتوازية المطلق تلقائيًا.

نظرة عامة على أدوار الوكلاء المدمجة:

---

🚀 التثبيت والتكوين

الخطوة 1: تثبيت البرنامج الرئيسي لـ OpenCode

يتطور OpenCode بسرعة كبيرة، لذا يوصى باستخدام البرنامج النصي الرسمي لتثبيت أحدث إصدار (الوثائق الرسمية):

# التثبيت السريع باستخدام curl (موصى به)
curl -fsSL https://opencode.ai/install | bash

# أو استخدام مديري حزم Node.js
npm install -g opencode  # bun / pnpm / yarn تعمل أيضًا

# يمكن لمستخدمي macOS أيضًا استخدام Homebrew
brew install opencode

الخطوة 2: تثبيت oh-my-opencode (موصى به بشدة)

يوفر oh-my-opencode قوالب تكوين احترافية جاهزة للاستخدام، مما يوفر عليك عناء الضبط اليدوي الممل:

bunx oh-my-opencode install

💡 تلميح: ستدخل عملية التثبيت في معالج تفاعلي يسألك عن اشتراكات الذكاء الاصطناعي التي لديك (مثل Claude، ChatGPT). يرجى تحديد المربعات وفقًا لموقفك الفعلي.

الخطوة 3: تكوين نقاط نهاية واجهة برمجة تطبيقات CodingPlanX والنماذج

هذه هي الخطوة الأكثر أهمية! يرجى استخدام محرر نصوص لإنشاء أو تعديل ملف التكوين: ~/.config/opencode/opencode.json.

🎯 حول اختيار النموذج: يستخدم قالب التكوين أدناه نماذج سلسلة Claude و سلسلة GPT Codex المقدمة من CodingPlanX. وهي تؤدي أداءً هو الأفضل في مختلف معايير البرمجة الموثوقة وتعتبر الثنائي الذهبي للمطورين.

انسخ محتوى JSON التالي بالكامل واستبدل به ملف opencode.json الخاص بك:

<details open=""> <summary><b>انقر لتوسيع كود تكوين opencode.json الكامل</b></summary>

{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.codingplanx.ai/v1"
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.codingplanx.ai"
      }
    }
  },

  "model": "anthropic/claude-opus-4-5-20251101",
  "small_model": "anthropic/claude-haiku-4-5-20251001",
  "default_agent": "build",

  "permission": {
    "read": "allow", "list": "allow", "glob": "allow", "grep": "allow",
    "codesearch": "allow", "lsp": "allow",
    "edit": "ask", "bash": "ask", "webfetch": "ask", "websearch": "ask",
    "external_directory": "deny", "doom_loop": "ask"
  },

  "agent": {
    "plan": {
      "mode": "primary",
      "description": "Planning/Breakdown/Tech Spec (Read-only to prevent accidental code changes)",
      "model": "anthropic/claude-opus-4-5-20251101",
      "temperature": 0.1,
      "prompt": "You are a senior tech lead. Goal: Break down requirements into actionable steps (including acceptance criteria/risks/rollbacks). Default to read-only; do not modify files or run commands. If execution is truly needed, explain why and suggest switching to build/codex.",
      "permission": { "edit": "deny", "bash": "deny", "webfetch": "deny", "websearch": "deny", "doom_loop": "deny" }
    },

    "build": {
      "mode": "primary",
      "description": "Main Development (End-to-end implementation/debugging/fixing tests) - Claude Opus 4.6",
      "model": "anthropic/claude-opus-4-5-20251101",
      "temperature": 0.2,
      "prompt": "You are the primary software engineering agent. Priorities: Minimum viable changes, readability, testability. Briefly explain your plan before making changes. After changing, you must provide: key diff points, how to verify locally (commands), and potential edge cases.",
      "permission": { "edit": "allow", "bash": "allow", "webfetch": "ask", "websearch": "ask", "doom_loop": "ask" }
    },

    "codex": {
      "mode": "primary",
      "description": "Refactoring/Migration/Major Changes (Codex) - GPT-5.2",
      "model": "openai/gpt-5.2-2025-12-11",
      "temperature": 0.2,
      "prompt": "You are a Codex-style engineering agent, excelling at large-scale refactoring, migrations, code reviews, and complex toolchain collaboration. Prioritize keeping the project runnable: step-by-step commits, verifiable at each step. Add safeguards and tests first when uncertain.",
      "permission": { "edit": "allow", "bash": "allow", "webfetch": "ask", "websearch": "ask", "doom_loop": "ask" }
    },

    "review": {
      "mode": "subagent",
      "description": "Code Review/Second Brain (Read-only) - GPT-5.1-Codex-Max",
      "model": "openai/gpt-5.1-codex-max",
      "temperature": 0.1,
      "prompt": "You are a strict code reviewer. Output: 1) Key risks (bugs/security/concurrency/edge cases) 2) Maintainability suggestions 3) Minimal modification suggestions (pseudo-diff is fine) 4) Necessary test points. Default to read-only; do not modify files or run commands.",
      "permission": { "edit": "deny", "bash": "deny", "webfetch": "deny", "websearch": "deny", "doom_loop": "deny" }
    },

    "explore": {
      "mode": "subagent",
      "description": "Rapid Code Scanning/Locating Files/Context Summarization (Read-only) - Claude Haiku 4.5",
      "model": "anthropic/claude-haiku-4-5-20251001",
      "temperature": 0.1,
      "prompt": "You are a rapid exploration sub-agent: Use minimal steps to locate relevant files/functions/call chains, providing clear paths and summaries. Default to read-only; do not modify files or run commands.",
      "permission": { "edit": "deny", "bash": "deny" }
    },

    "general": {
      "mode": "subagent",
      "description": "General Research/Documentation/Solution Comparison (Medium cost) - Claude Sonnet 4.6",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "temperature": 0.2,
      "prompt": "You are a general analysis sub-agent: Focused on explaining, weighing options, writing documentation, and comparing solutions. Default to read-only; avoid modifying code if possible.",
      "permission": { "edit": "deny", "bash": "deny" }
    },

    "think": {
      "mode": "subagent",
      "description": "Assisted Thinking/Deducing Edge Cases (Read-only) - GPT-5.2",
      "model": "openai/gpt-5.2-2025-12-11",
      "temperature": 0.2,
      "prompt": "You are a reasoning and edge-case deduction sub-agent: Provide structured analysis and suggestions regarding design, exception paths, concurrency/consistency, and performance bottlenecks. Default to read-only.",
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

</details>

---

الخطوة 4: تكوين مفاتيح API

نظرًا لأننا قمنا بتكوين مزودين اثنين (Anthropic و OpenAI)، فأنت بحاجة إلى ربط مفاتيح API التي حصلت عليها من CodingPlanX داخل OpenCode.

1. اكتب opencode في الطرفية لبدء البرنامج.
2. في مربع الحوار، اكتب أمر /connect.
3. تكوين Claude:
   • حدد Anthropic -> حدد Manually enter API Key (إدخال مفتاح API يدويًا).
   • الصق مفتاح API الخاص بـ CodingPlanX واضغط على Enter للحفظ.
4. تكوين OpenAI:
   • اكتب /connect مرة أخرى.
   • حدد OpenAI -> حدد Manually enter API Key (إدخال مفتاح API يدويًا).
   • الصق مفتاح API الخاص بـ CodingPlanX واضغط على Enter للحفظ.
5. اكتب /exit للخروج، ثم أعد تشغيل opencode حتى يسري التكوين.

🔐 ملاحظة: يتم حفظ مفاتيح API الخاصة بك بأمان محليًا في ملف ~/.local/share/opencode/auth.json.

---

💡 نصائح الاستخدام المتقدم

بعد إكمال التكوين، اكتب opencode في الطرفية لبدء الدردشة:

> مرحبًا، يرجى قراءة ملف package.json في الدليل الحالي وتقديم نبذة عن هذا المشروع.

1. ⚡ Ultrawork (وضع التوازي المطلق)

إذا قمت بتثبيت oh-my-opencode، فما عليك سوى إضافة ultrawork (أو ulw باختصار) إلى المطالبة الخاصة بك، وسيقوم OpenCode باستدعاء الوكيل الرئيسي لتقسيم المهمة وتوزيعها على الوكلاء الفرعيين في الخلفية للمعالجة المتوازية:

> ultrawork ساعدني في إعادة هيكلة وحدة المصادقة في دليل src/auth وإضافة اختبارات الوحدة.

2. 🎯 صيغة @ لاستدعاء الوكيل المستهدف

يمكنك استخدام رمز @ لإرسال مهام محددة بدقة إلى الوكلاء المحترفين الذين قمنا بتكوينهم في ملف JSON:

> @review ساعدني في مراجعة منطق login.ts الملتزم به حديثًا بحثًا عن أي ثغرات أمنية.
> @explore ابحث عن جميع نقاط نهاية API في المشروع التي تستدعي getUserInfo.
> @general ساعدني في مقارنة ما إذا كان من الأفضل استخدام React Context أو Redux للمشروع الحالي.

3. 🔄 مفتاح Tab للتبديل السريع بين الأوضاع

اضغط على مفتاح Tab في مربع الإدخال للتبديل بسرعة بين الوكلاء الرئيسيين:

• build: الوضع الرئيسي، مع صلاحيات كاملة لقراءة/كتابة الملفات وتنفيذ أوامر الطرفية.
• plan: الوضع الآمن، صلاحيات للقراءة فقط، يُستخدم لتقسيم المتطلبات الأولية، وتحليل البنية، والتخطيط التقني لمنع الذكاء الاصطناعي من تعديل الكود عن طريق الخطأ.

---

🛠️ الأسئلة الشائعة واستكشاف الأخطاء وإصلاحها

س1: فشل اتصال API أو انتهت المهلة؟

• تحقق مما إذا كان baseURL في ملف opencode.json صحيحًا.
• تحقق مما إذا كانت الطرفية بها تعارضات مع البروكسي (عادةً ما يؤدي استخدام IP مباشر إلى تجاوز مشكلات بروكسي النظام).

س2: يظهر خطأ "Model not found" (النموذج غير موجود) أو النموذج غير متوفر؟

• تأكد من أن معرف النموذج في ملف التكوين (مثل claude-opus-4-5-20251101) يتطابق تمامًا مع قائمة النماذج المقدمة رسميًا من CodingPlanX. لا تخطئ في كتابتها.

س3: إضافة oh-my-opencode تُظهر خطأ؟

• الإضافة في مرحلة تطوير سريعة. إذا واجهت خطأ، فحاول التحديث: bunx oh-my-opencode update.
• لمزيد من مشكلات التكوين، يرجى الرجوع إلى الوثائق الرسمية لـ oh-my-opencode.

---

🔗 قراءة إضافية والخطوات التالية

• 🌐 الموقع الرسمي لـ OpenCode | مستودع GitHub