# ‏AGENTS.md يخبر OpenCode بقواعدك. Maguyva تريه الكود.

Canonical source: https://maguyva.ai/ar/for-opencode

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

يقرأ OpenCode ملف AGENTS.md ليعرف كيف يعمل، ويستدعي خوادم MCP لكل ما عدا ذلك. Maguyva خادم MCP بعيد يمنح OpenCode خريطة قابلة للاستعلام عن مستودعك، مع مسارات الملفات وأرقام الأسطر.

> إدخال بعيد واحد تحت mcp. لا شيء يعمل محليًا.

## ما يجب معرفته عن OpenCode

أربع حقائق خاصة بـOpenCode.

### opencode.json

أضف الخادم تحت `mcp` في ملف `opencode.json` الخاص بمشروعك، أو في `~/.config/opencode/opencode.json` لكل المشاريع.

### type: remote

يتصل OpenCode بنقطة نهاية Maguyva عبر HTTP. لا شيء يعمل محليًا ولا حاجة إلى Node.js.

### مرجع إلى متغير بيئة

يستبدل OpenCode متغيرات البيئة في إعداده، فتصبح الترويسة `Bearer {env:MAGUYVA_API_KEY}` ويبقى المفتاح خارج الملف الذي تودعه في Git.

### حدّد النطاق لكل وكيل

كل خادم MCP يضيف تعريفات أدوات إلى السياق. يستطيع OpenCode تعطيل أدوات خادم ما على مستوى عام بنمط glob مثل `"maguyva*": false` ثم تفعيلها للوكلاء الذين يحتاجونها فقط.

## ‏AGENTS.md اتفاق عمل. استخدمه.

```text
> /init
# يمسح المستودع ويكتب AGENTS.md
```

يقرأ OpenCode ملف `AGENTS.md` في جذر المشروع، و`~/.config/opencode/AGENTS.md` للقواعد الشخصية. إن لم يوجد `AGENTS.md`، يرجع إلى `CLAUDE.md`. احتفظ به لـ:

- أوامر البناء والاختبار والـlint.
- الأعراف والحدود التي ينبغي أن يحترمها الوكيل.
- إشارات إلى الوثائق المهمة.

المسح عند `/init` ملخص، لا فهرس. لا يخبر OpenCode من يستدعي الدالة التي أُضيفت أمس.

## حين لا يكفي AGENTS.md

ثلاث فجوات يملؤها OpenCode بـgrep والصبر.

### ‏// الملخص ليس فهرسًا

يستطيع AGENTS.md تسمية الحزم المهمة. لكنه لا يستطيع سرد كل رمز وموقع استدعاء، ولا ينبغي أن يحاول.

### ‏// grep يجد السلاسل لا المستدعين

لا يستطيع التطابق النصي التمييز بين استدعاء حقيقي وتعليق، أو mock، أو دالة بالاسم نفسه في فئة أخرى.

### ‏// الملف ينحرف

يكون AGENTS.md صحيحًا يوم كتابته. الكود يواصل التغيّر؛ أما الملف فيتغيّر حين يتذكر أحدهم تحديثه.

## Maguyva كخادم MCP بعيد في OpenCode

إدخال واحد تحت mcp يمنح OpenCode:

- **11 أداة على مستودعك المفهرس**: بحث دلالي وهيكلي (AST) وبالرسم البياني ونصي، إضافة إلى البحث عن الرموز والعناصر المعتمدة واسترجاع الملفات.
- **إجابات مع مسارات الملفات وأرقام الأسطر**: عبر أكثر من 285 لغة.
- **الإجابات نفسها لكل نموذج**: يعمل OpenCode مع مزوّدي نماذج كثيرين. تعيد Maguyva الخريطة نفسها أيًّا كان النموذج الذي يسأل.

> ‏AGENTS.md يخبر OpenCode *كيف يعمل*.
> Maguyva تمنح OpenCode *ما يعمل انطلاقًا منه*.

## سيرا عمل

اسأل الخريطة من الطرفية نفسها.

### 01. أعد تسمية نوع مشترك عبر الحزم

```text
opencode> أعد تسمية OrderStatus إلى FulfillmentStatus

dependency_search("OrderStatus", dependents)
  23 مرجعًا عبر 8 حزم
structural_search(switch_statement, "OrderStatus")
  4 عبارات switch شاملة

→ يعدّل OpenCode القائمة كاملة، بما فيها عبارات switch.
[exit 0]
```

عبارات switch الشاملة هي بالضبط ما يفوته البحث النصي ويكتشفه المترجم متأخرًا.

### 02. ميّز الكود عن التوثيق

```text
opencode> أين يُقرأ FEATURE_BULK_EXPORT؟

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← توثيق فقط

→ مساران في الكود، ووثيقة واحدة قديمة.
[exit 0]
```

تعود التطابقات الدقيقة مع مساراتها، فيميّز OpenCode الكود عن التوثيق قبل أن يعدّل أيًّا منهما.

## الإعداد في OpenCode

ثلاث خطوات. خطة Free: 3 مستودعات, حتى 50 ألف سطر مُفهرَس من المستودع، بلا بطاقة.

### 01. افهرس مستودعًا على maguyva.ai

اختر واحدًا تعرفه جيدًا، لتتمكَّن من التحقق من الإجابات.

### 02. أضف Maguyva تحت mcp في opencode.json

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. صدّر مفتاحك وتحقق من الاتصال

اضبط `MAGUYVA_API_KEY` في الصدفة التي تشغّل OpenCode. يعرض `opencode mcp list` كل خادم مُعَدّ؛ ثم اطرح سؤالًا واحدًا تعرف إجابته مسبقًا.

تشرح [وثائق MCP](https://opencode.ai/docs/mcp-servers/) الخاصة بـOpenCode مهلات الانتظار وOAuth وصلاحيات الأدوات لكل وكيل.

## افهرس مستودعًا واحدًا تعرفه جيدًا.

اتصل بـOpenCode عبر MCP، ثم اطرح سؤالًا واحدًا يمكنك التحقق منه.