# المراجع

> هذه وثائق OpenCode V1. أحدث الوثائق، الخاصة بـ OpenCode V2، موجودة على https://opencode.ai/docs/llms.txt.

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

تُضبط المراجع بأسماء مستعارة في `opencode.json` أو `opencode.jsonc`.

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}
```

---

## الأدلة المحلية

استخدم `path` للإشارة إلى دليل محلي.

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}
```

يمكن أن تكون المسارات:

- نسبية إلى ملف الإعدادات الذي يعرّف المرجع
- مطلقة، مثل `/home/user/docs`
- نسبية إلى مجلد المنزل، مثل `~/docs`

يمكنك أيضًا استخدام صيغة مختصرة على شكل نص:

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": "../docs",
  },
}
```

---

## مستودعات Git

استخدم `repository` للإشارة إلى مستودع Git. ينشئ OpenCode نسخة من المستودع في ذاكرة التخزين المؤقت المحلية للمستودعات، ويتيح الشيفرة المصدرية المسحوبة كدليل مرجعي.

```jsonc title="opencode.jsonc"
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}
```

يقبل `repository` عناوين URL الخاصة بـ Git، ومراجع host/path، والصيغة المختصرة `owner/repo` الخاصة بـ GitHub. يحدد الحقل الاختياري `branch` فرعًا أو ref. بدون `branch`، يستخدم OpenCode الفرع الافتراضي للمستودع.

يمكنك استخدام الصيغة المختصرة على شكل نص عندما لا تحتاج إلى فرع أو وصف أو خيارات أخرى:

```jsonc title="opencode.jsonc"
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}
```

:::note
تُحدَّث مراجع Git بشكل غير متزامن. قد يستغرق المستودع المُعدّ حديثًا بعض الوقت حتى ينتهي استنساخه أو تحديثه.
:::

---

## وصف الاستخدام

أضِف `description` لتوضيح متى يجب على الوكيل استخدام مرجع ما.

```jsonc title="opencode.jsonc"
{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}
```

يُضمّن OpenCode المراجع التي لها أوصاف في سياق الوكيل. يجب أن تكون الأوصاف قصيرة ومحددة بما يكفي للتمييز بين المراجع ذات المحتوى المتشابه. تبقى المراجع التي لا أوصاف لها متاحة عبر الإكمال التلقائي والاستخدام المباشر، لكن لا يُعلَن عنها للوكلاء.

---

## إخفاء عناصر الإكمال التلقائي

اضبط `hidden` على `true` لاستبعاد مرجع من الإكمال التلقائي `@` في TUI.

```jsonc title="opencode.jsonc"
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}
```

يؤثر `hidden` على الإكمال التلقائي فقط. يبقى المرجع المخفي الذي له وصف مُضمَّنًا في سياق الوكيل.

---

## استخدام المراجع

تظهر المراجع المُعدّة في الإكمال التلقائي `@` في TUI. اكتب `@alias` لإرفاق جذر المرجع، أو `@alias/` للبحث عن ملفات بداخله.

```text
Compare this implementation with @sdk/src/client.ts
```

يتلقى الوكلاء أيضًا في سياق النظام المسارات المحلولة وأوصاف المراجع المُعدّة التي لها أوصاف، لذا يمكنهم فحص المرجع عندما يكون ذا صلة دون أن تحتاج إلى إرفاقه يدويًا.

يسمح OpenCode تلقائيًا بأدلة المراجع ضمن حدود إذن الأدلة الخارجية. تظل أذونات الأدوات العادية سارية؛ فمثلًا، الوكيل الذي لا يستطيع تعديل الملفات لا يحصل على صلاحية التعديل لمجرد أن دليلًا ما مُعدّ كمرجع.

---

## حقول الإعداد

| الحقل         | محلي | Git | الوصف                                                          |
| ------------- | ---- | --- | -------------------------------------------------------------- |
| `path`        | نعم  | لا  | دليل المرجع المحلي                                             |
| `repository`  | لا   | نعم | عنوان URL لـ Git، أو host/path، أو قيمة `owner/repo` من GitHub |
| `branch`      | لا   | نعم | فرع Git أو ref اختياري                                         |
| `description` | نعم  | نعم | إرشاد يصف متى يُستخدم المرجع                                   |
| `hidden`      | نعم  | نعم | إخفاء المرجع من الإكمال التلقائي `@` في TUI                    |

لا يمكن أن تكون الأسماء المستعارة للمراجع فارغة، أو أن تحتوي على `/`، أو مسافات بيضاء، أو علامات backtick، أو فواصل.