وثائق arabcode

ما هو arabcode؟

arabcode هو أول وكيل ذكاء اصطناعي مفتوح المصدر يعمل داخل الطرفية (CLI/TUI) ويعرض العربية كما ينبغي، اتجاه RTL صحيح، وتشكيل يربط الحروف بأشكالها، وتحديد ونسخ منطقي، وإدخال عربي داخل حقل الأوامر. تحت الغطاء هو وكيل برمجة كامل القدرات: يفهم مشروعك، ويقرأ ويكتب الملفات، وينفّذ الأوامر معك، ويتكامل مع خوادم اللغة والأدوات الخارجية.

• العربية الكاملةاتجاه RTL صحيح وتشكيل يربط الحروف، وتحديد ونسخ منطقي، وإدخال عربي داخل الطرفية، لا توفّره أدوات الطرفية الأخرى.
• وكيل برمجة حقيقييقرأ ويعدّل الملفات، وينفّذ أوامر الصدفة، ويبحث في المشروع بذكاء برمجي مدعوم بـ LSP.
• استقلالية عن المزوّدأكثر من 75 مزوّدًا للموديلات، وموديلات محلية تعمل على جهازك، بدّل بينها بحرية بحسب المهمة.
• طرفية أولًاأداة CLI/TUI بالكامل تعمل على ماك ولينكس وويندوز، مع أوضاع غير تفاعلية للأتمتة والخوادم.

المتطلبات

التثبيت

يعمل arabcode على ماك ولينكس وويندوز (ويندوز و PowerShell مدعومان دعمًا كاملًا). اختر منصّتك أدناه.

git clone https://github.com/abdallhx2/arabcode \
  && cd arabcode \
  && bun install \
  && bun run --cwd packages/arabcode dev

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

arabcode --version   # اعرض رقم الإصدار
arabcode             # شغّل الواجهة النصية

إزالة التثبيت

بعد الإزالة، احذف كذلك مدخل PATH المرتبط من ملف إعداد طرفيتك (~/.bashrc أو ~/.zshrc) أو من متغيّرات بيئة ويندوز.

البدء السريع، من صفر إلى أول محادثة

1. افتح مجلد مشروعك وشغّل الأداة:

   cd ~/my-app && arabcode

2. اربط موديلًا (ابدأ بموديل مجاني دون بطاقة):

   /connect

3. وثّق مشروعك للوكيل مرة واحدة (يُنشئ AGENTS.md):

   /init

4. اكتب طلبك بالعربية مباشرة، مثلًا:

   اشرح كيف تُدار المصادقة في @src/auth.ts
   ثم أضف اختبارًا لحالة انتهاء صلاحية التوكن

أوضاع build / plan

وكيلان مدمجان تتنقّل بينهما بمفتاح Tab:

الفائدة: راجِع الخطة قبل التنفيذ لتقليل التعديلات الخاطئة على كود حسّاس أو إنتاجي. تُستدعى بجانبها وكلاء فرعية جاهزة مثل general للبحث متعدّد الخطوات وexplore للتنقّل في الكود.

الأوامر، CLI و TUI

تعمل مع arabcode بطريقتين متكاملتين: الواجهة النصية التفاعلية (TUI) بأوامرها المسبوقة بشرطة مائلة داخل المحادثة، وسطر الأوامر (CLI) بأوامره الفرعية للأتمتة والسكربتات. هذا مرجع موحّد لكلتيهما.

أوامر الواجهة النصية (TUI)

تُكتب داخل حقل المحادثة مسبوقةً بـ /. لكثير منها اختصار لوحة مفاتيح مقابل. مفتاح القائد (leader) الافتراضي ctrl+x.

أوامر سطر الأوامر (CLI)

الأعلام العامّة

متغيّرات البيئة المفيدة

الجلسات واللقطات

يحفظ arabcode لقطة (snapshot) لكل جلسة تسمح بالرجوع إلى أي رسالة سابقة، بما في ذلك استعادة تعديلات الملفات لحظة تلك النقطة، بدل التراجع خطوة بخطوة أو فقدان العمل.

• لقطات وتراجع دقيقإذا سلك الوكيل مسارًا خاطئًا في تعديل معقّد، ارجع إلى نقطة محدّدة بأمر /undo أو استعِد الحالة كاملة.
• جلسات متوازيةشغّل أكثر من مهمة في آنٍ واحد على المشروع نفسه، وانتقل بينها بلا تعارض.
• عرض / حذف / تصديرsession list وsession delete وexport إلى JSON أو import من ملف أو رابط مشاركة.
• شفافية التكلفةأمر stats يعرض استهلاك التوكنز والتكلفة، مفيد إذا كنت تدير عدة مشاريع أو عملاء.

المشاركة

أنشئ رابطًا عامًّا لمشاركة محادثة كاملة عبر أمر /share داخل الواجهة النصية، مفيد لطلب مراجعة أو توثيق حل أو تعليم زميل. عند المشاركة يولّد arabcode رابطًا فريدًا للجلسة، ويزامن محتوى المحادثة، وينسخ الرابط إلى الحافظة مباشرة.

الأوامر

أوضاع المشاركة

يتحكّم مفتاح share في ملف الإعداد بسلوك المشاركة على ثلاثة أوضاع:

• manual افتراضيلا تُشارَك الجلسات تلقائيًا، وتنشئ الرابط يدويًا بأمر /share عند الحاجة.
• autoمشاركة تلقائية لكل جلسة جديدة، مع توليد رابط لكل واحدة.
• disabledتعطيل المشاركة كليًا. يمكن فرضه على الفريق بأكمله عبر arabcode.json في المشروع لبيئات الامتثال المغلقة.

{
  "$schema": "https://arabcode.dev/config.json",
  "share": "manual"
}

الأوضاع غير التفاعلية

يغطّي arabcode كل سيناريوهات الأتمتة، من سكربت bash بسيط إلى خادم API إنتاجي:

واجهة الويب

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

web مقابل serve

ضبط الخادم والمنفذ

تتحكّم الأعلام نفسها في كلا الأمرين، أو اضبطها دائمًا في قسم server بملف الإعداد:

arabcode web --port 4096 --hostname 0.0.0.0
arabcode web --cors http://localhost:5173

النماذج والمزوّدون

يدعم arabcode أكثر من 75 مزوّدًا عبر AI SDK وModels.dev، OpenAI و Anthropic Claude و Google Gemini و AWS Bedrock و Groq و Azure و OpenRouter و GitHub Copilot وغيرها، إضافة إلى الموديلات المحلية. لست مقيّدًا بمزوّد واحد.

ابدأ مجانًا، دون بطاقة

أسهل بداية هي النماذج المجانية المتاحة عبر بوّابة الموديلات: شغّل /connect واختر بوّابة النماذج المجانية، ثم /models لاختيار موديل. لا تحتاج بطاقة أو رصيدًا.

ربط مزوّد بمفتاحك الخاص

أضِف مفتاح الـ API عبر /connect داخل الواجهة، أو من سطر الأوامر:

arabcode auth login     # اختر مزوّدًا وأدخل مفتاح الـ API
arabcode auth list      # اعرض المزوّدين المسجّلين
arabcode auth logout    # احذف بيانات اعتماد مزوّد

تُخزَّن المفاتيح محليًا في ملف auth.json ضمن مجلد بيانات arabcode.

ضبط المزوّد في ملف الإعداد

خصّص أي مزوّد عبر قسم provider. مثال: تغيير عنوان القاعدة (baseURL) لتوجيه الطلبات عبر وسيط أو نقطة نهاية مخصّصة.

{
  "$schema": "https://arabcode.dev/config.json",
  "provider": {
    "anthropic": {
      "options": { "baseURL": "https://api.anthropic.com/v1" }
    }
  }
}

لإخفاء موديلات من منتقي /models استخدم blacklist، أو whitelist لإبقاء المدرَجة فقط.

الموديلات المحلية

شغّل موديلاتك على جهازك: يدعم arabcode أي خادم متوافق مع OpenAI، مثل Ollama و LM Studio و llama.cpp، عبر ضبط baseURL على نقطة النهاية المحلية، أو عبر متغيّر البيئة LOCAL_ENDPOINT.

{
  "$schema": "https://arabcode.dev/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder": { "name": "Qwen3 Coder (local)" }
      }
    }
  }
}

ملف الإعداد

يُضبط arabcode عبر ملف إعداد بصيغة JSON أو JSONC (يقبل التعليقات)، ويُتحقّق منه مقابل مخطّط $schema. ضعه في جذر مشروعك باسم arabcode.json (آمن لحفظه في نظام الإصدار للفريق)، أو في مجلد الإعداد العام لتطبيقه على كل جلساتك. ويمكن توجيهه إلى مسار مخصّص عبر متغيّر البيئة ARABCODE_CONFIG، أو تمرير محتواه مباشرة عبر ARABCODE_CONFIG_CONTENT.

مواقع ملف الإعداد

يقبل الامتداد .json و.jsonc على حدٍّ سواء. وتُوضع الوكلاء والأوامر والإضافات الخاصّة بالمشروع في مجلد .arabcode/.

ترتيب الدمج والأسبقية

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

1. الإعداد البعيد (.well-known/arabcode) — إعدادات المؤسّسة الافتراضية.

2. الإعداد العام (~/.config/arabcode/arabcode.json) — تفضيلاتك الشخصية.

3. إعداد مخصّص عبر ARABCODE_CONFIG.

4. إعداد المشروع (arabcode.json في الجذر).

5. مجلدات .arabcode/ — الوكلاء والأوامر والإضافات.

6. إعداد مضمّن عبر ARABCODE_CONFIG_CONTENT — تجاوزات وقت التشغيل.

7. إعداد مُدار (يفرضه مسؤول النظام) — أعلى أسبقية وغير قابل للتجاوز.

{
  "$schema": "https://arabcode.dev/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "default_agent": "build",
  "instructions": ["./CONTRIBUTING.md", "docs/guidelines.md"],
  "permission": { "bash": "ask", "edit": "ask" },
  "share": "manual",
  "autoupdate": true
}

أهم المفاتيح

إعداد الخادم

عند تشغيل arabcode serve أو arabcode web، يتحكّم قسم server في المنفذ واسم المضيف واكتشاف الشبكة (mDNS) وقائمة أصول CORS المسموح بها:

{
  "$schema": "https://arabcode.dev/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

ملف AGENTS.md و /init

ملف AGENTS.md هو ملف التعليمات الخاص بمشروعك: يوثّق التقنيات وأسلوب الكود والبنية وأوامر البناء والاختبار والاصطلاحات، ويُقرأ تلقائيًا في كل جلسة (مكافئ لـ CLAUDE.md).

أمر /init يحلّل مشروعك ويولّد الملف أو يحسّنه: يفحص ملفات المستودع المهمّة، ويوثّق أوامر البناء والاختبار والبنية والاصطلاحات، ويحافظ على المحتوى القائم إن وُجد. يُنصح بحفظه في نظام الإصدار لاتساق الفريق.

• قواعد المشروعملف AGENTS.md في جذر المشروع يسري على العمل داخل ذلك المجلد وفروعه.
• قواعد عامةملف في مجلد الإعداد العام يسري على كل جلساتك، مثالي لتفضيلاتك الشخصية غير المشتركة مع الفريق.
• توافق مع .claudeيقرأ arabcode ملف CLAUDE.md ومجلد .claude إن وُجدا، فتستخدم أدواتك السابقة بأقل تعديل.

ولإدراج ملفات إضافية استخدم مفتاح instructions في ملف الإعداد، وهو يقبل مسارات محلية وأنماط glob وروابط بعيدة.

الأوامر المخصّصة

حوّل المهام المتكرّرة (فحص PR، تجميع سياق issue، توليد مكوّن) إلى أمر واحد. كل أمر ملف Markdown في مجلد الأوامر، العام أو مجلد .arabcode/commands في المشروع، واسم الملف يصبح اسم الأمر (مثلًا test.md ← /test).

---
description: توليد مكوّن
agent: build
---
أنشئ مكوّن React باسم $1 بلغة TypeScript.
افحص البنية الحالية أولًا: !`ls src/components`
واتبع نمط الملف @src/components/Button.tsx

مفاتيح الـ frontmatter الشائعة: description وagent وmodel وsubtask لإجبار استدعاء وكيل فرعي.

الاختصارات

اختصارات الواجهة النصية قابلة للتخصيص كلها. مفتاح القائد (leader) الافتراضي هو ctrl+x ويسبق كثيرًا من الأوامر. لتعطيل أي اختصار اضبط قيمته على "none".

تُضبط الاختصارات والثيم في ملف tui.json.

الصلاحيات ووضع YOLO

يتحكّم قسم permission في الموافقة على العمليات. لكل قاعدة ثلاث نتائج ممكنة:

• allowتُنفَّذ العملية دون طلب موافقة.
• askيُطلب منك التأكيد قبل التنفيذ.
• denyتُمنع العملية كليًا.

تشمل أنواع الصلاحيات edit وbash وwebfetch وread وtask وغيرها. وتدعم أنماط bash البدائل: * يطابق أي عدد من الأحرف و? حرفًا واحدًا، مع فوز آخر قاعدة مطابقة.

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "deny",
      "src/**": "allow"
    }
  }
}

يمكن تجاوز الصلاحيات لكل وكيل عبر agent.<name>.permission، وتُدمج قواعد الوكيل مع الإعداد العام وتُقدَّم عليه.

الوكلاء المخصّصة

أنشئ فريقًا من الوكلاء المتخصّصين (مراجع أمان، كاتب توثيق، خبير اختبارات) لنتائج أدق لكل مجال بدل وكيل عام واحد. الوكلاء نوعان:

أنشئ وكيلًا تفاعليًا بأمر arabcode agent create، أو عرّفه بملف Markdown فيه YAML frontmatter للإعداد وجسم النص كـ system prompt:

---
description: يكشف الثغرات الأمنية
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
أنت خبير أمان. حدّد عيوب التحقق من المدخلات ومشاكل
المصادقة ومخاطر تسريب البيانات وثغرات الاعتماديات.

مفاتيح الإعداد: mode (primary/subagent/all) وmodel وtemperature وprompt وpermission وsteps (أقصى عدد تكرارات).

خوادم MCP و Code Mode

توسّع arabcode بأدوات خارجية عبر Model Context Protocol، محلية أو بعيدة، فتندمج تلقائيًا مع الموديل بجانب الأدوات المدمجة. يتيح لك ذلك تكاملًا مباشرًا مع قواعد البيانات والـ APIs وأنظمة الملفات.

{
  "$schema": "https://arabcode.dev/config.json",
  "mcp": {
    "local-tools": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-server"],
      "enabled": true,
      "environment": { "API_KEY": "{env:MY_API_KEY}" }
    },
    "remote-tools": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:TOKEN}" }
    }
  }
}

تُدار الخوادم كذلك من سطر الأوامر عبر arabcode mcp add | list | auth (مع دعم مصادقة OAuth). ويتيح Code Mode تشغيل سكربتات تنسيق (orchestration) مقيّدة فوق أدوات MCP بدل استدعائها واحدة تلو الأخرى، كفاءة أعلى في المنطق المعقّد.

تكامل LSP

يدعم arabcode بروتوكول خوادم اللغة (Language Server Protocol) لذكاء برمجي حقيقي، اقتراحات دقيقة، ومعرفة الأنواع، وتنقّل في الكود، وكشف الأخطاء، وليس مجرد تحليل نصي. تُحمَّل خوادم اللغة المناسبة للمشروع تلقائيًا، ويمكن ضبطها عبر مفتاح lsp في ملف الإعداد.

الفائدة: فهم أعمق لبنية الكود يقلّل الأخطاء الناتجة عن تخمين النوع أو المرجع، ويجعل تعديلات الوكيل أكثر دقّة.

نظام Skills

يكتشف arabcode الـ skills والوكلاء المبنية على ملفات تلقائيًا، ويخزّن مساراتها كمسارات ملفات حقيقية، فتعيد استخدام منطق متخصّص محفوظ مسبقًا بدل إعادة شرحه في كل جلسة.

وبفضل التوافق مع بنية .claude، يقرأ arabcode ما لديك من skills وملف CLAUDE.md إن وُجدا في المشروع، ويمكن التحكم في ذلك عبر متغيّرات البيئة ARABCODE_DISABLE_CLAUDE_CODE وARABCODE_DISABLE_CLAUDE_CODE_SKILLS.

تكامل GitHub

استدعِ arabcode مباشرة داخل مستودعك: اذكره في تعليق على issue أو PR فيقرأ سياق النقاش، ويكتب الكود، وينشئ فرعًا، ويفتح طلب دمج، كل ذلك داخل GitHub Actions.

التثبيت السريع

أسهل طريقة هي الأمر التفاعلي الذي يثبّت تطبيق GitHub، وينشئ ملف الـ workflow، ويضبط الأسرار (secrets):

الاستخدام

بعد التثبيت، اكتب /arabcode (أو /ac) في تعليق على issue أو PR أو مراجعة كود، متبوعًا بطلبك:

ملف الـ workflow

للتثبيت اليدوي، أضِف الملف التالي في .github/workflows/arabcode.yml، وخزّن مفتاح مزوّدك في Settings ← Secrets and variables ← Actions:

name: arabcode
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  arabcode:
    if: |
      contains(github.event.comment.body, '/arabcode') ||
      contains(github.event.comment.body, '/ac')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
          persist-credentials: false
      - uses: abdallhx2/arabcode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-5

خيارات الإعداد (with)

أحداث التحفيز المدعومة

كما يمكن استخدام اشتراك GitHub Copilot (Pro/Business/Enterprise) كمزوّد مصادقة مباشر بدل مفتاح API منفصل، انظر قسم النماذج والمزوّدون.

Plugins و SDK

ابنِ أدوات وتكاملات مخصّصة فوق arabcode كمنصّة، لا كتطبيق جاهز فقط:

• نظام Plugins قابل للتوسّعواجهات hook مسمّاة وواجهة plugin حديثة تعمل مع Effect و Promise. ثبّت إضافة بأمر arabcode plugin <module>.
• SDK كاملبثّ أحداث حيّ (live event stream)، ووصول للجلسات النشطة، وسجل جلسات مقسّم صفحات، ونقاط نهاية لطلبات الصلاحيات.

استكشاف الأخطاء

العربية تظهر مقطّعة أو معكوسة

تأكّد أنك تستخدم طرفية تدعم Unicode والتشكيل بشكل جيّد، مثل WezTerm أو Alacritty أو Ghostty أو Kitty. بعض الطرفيات القديمة لا تدعم دمج الحروف العربية.

الأمر غير موجود بعد التثبيت

تأكّد أن مجلد تثبيت arabcode ضمن متغيّر PATH، على ماك/لينكس هو $HOME/.arabcode/bin، وعلى ويندوز %LOCALAPPDATA%\arabcode\bin. أعِد فتح الطرفية بعد التعديل.

استدعاء الأدوات لا يعمل مع موديل محلي

اختر موديلًا بدعم قوي لاستدعاء الأدوات (مثل Qwen-Coder أو DeepSeek-Coder)، وزِد قيمة سياق النموذج (num_ctx) في Ollama إلى نحو 16k،32k.

فشل المصادقة أو الموديل غير متاح

أعِد المصادقة عبر /connect وتحقّق من صلاحية المفتاح. أشِر إلى الموديل بالصيغة الصحيحة <providerId>/<modelId> (مثل openai/gpt-4.1)، واستعرض المتاح بأمر arabcode models.

السجلّات ووضع التتبّع

لتشخيص أعمق، شغّل arabcode بمستوى تسجيل مفصّل أو اطبع السجلّات في الطرفية مباشرة:

arabcode --log-level DEBUG   # تفاصيل تشخيصية دقيقة
arabcode --print-logs        # طباعة السجلّات في الطرفية مباشرة

تُحفَظ ملفات السجلّ بأسماء مؤرّخة (مثل 2025-01-09T123456.log)، ويُبقى على أحدث 10 ملفات منها.

مواقع الملفات المهمّة

يحتوي مجلد البيانات على بيانات الاعتماد (auth.json) والسجلّات وبيانات الجلسات لكل مشروع.

خطوات إعادة الضبط

• امسح الذاكرة المؤقّتةاحذف مجلد ~/.cache/arabcode بالكامل عند سلوك غير متوقّع.
• عطّل الإضافاتشغّل arabcode --pure للتشغيل بلا إضافات، أو احذف مفتاح plugin من الإعداد لعزل المشكلة.
• أعِد المصادقةاستخدم /connect داخل الواجهة لإعادة ربط المزوّد إذا فشلت المصادقة.
• حافظة لينكسيتطلّب النسخ واللصق أدوات مثل xclip/xsel (X11) أو wl-clipboard (Wayland).
• واجهة الويب على ويندوزتأكّد من تثبيت WebView2 Runtime.