المراجع
تمنح المراجع OpenCode وصولًا إلى أدلة خارج المشروع الحالي. استخدمها لإتاحة التوثيق، أو المكتبات المشتركة، أو الأمثلة، أو مستودع آخر أثناء عملك.
تُضبط المراجع بأسماء مستعارة في opencode.json أو 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 للإشارة إلى دليل محلي.
{
"references": {
"docs": {
"path": "../docs",
},
},
}يمكن أن تكون المسارات:
- نسبية إلى ملف الإعدادات الذي يعرّف المرجع
- مطلقة، مثل
/home/user/docs - نسبية إلى مجلد المنزل، مثل
~/docs
يمكنك أيضًا استخدام صيغة مختصرة على شكل نص:
{
"references": {
"docs": "../docs",
},
}استخدم repository للإشارة إلى مستودع Git. ينشئ OpenCode نسخة من المستودع في ذاكرة التخزين المؤقت المحلية للمستودعات، ويتيح الشيفرة المصدرية المسحوبة كدليل مرجعي.
{
"references": {
"effect": {
"repository": "Effect-TS/effect",
"branch": "main",
},
},
}يقبل repository عناوين URL الخاصة بـ Git، ومراجع host/path، والصيغة المختصرة owner/repo الخاصة بـ GitHub. يحدد الحقل الاختياري branch فرعًا أو ref. بدون branch، يستخدم OpenCode الفرع الافتراضي للمستودع.
يمكنك استخدام الصيغة المختصرة على شكل نص عندما لا تحتاج إلى فرع أو وصف أو خيارات أخرى:
{
"references": {
"effect": "Effect-TS/effect",
},
}أضِف description لتوضيح متى يجب على الوكيل استخدام مرجع ما.
{
"references": {
"design-system": {
"path": "../design-system",
"description": "Use when implementing UI components or design tokens",
},
},
}يُضمّن OpenCode المراجع التي لها أوصاف في سياق الوكيل. يجب أن تكون الأوصاف قصيرة ومحددة بما يكفي للتمييز بين المراجع ذات المحتوى المتشابه. تبقى المراجع التي لا أوصاف لها متاحة عبر الإكمال التلقائي والاستخدام المباشر، لكن لا يُعلَن عنها للوكلاء.
اضبط hidden على true لاستبعاد مرجع من الإكمال التلقائي @ في TUI.
{
"references": {
"internal": {
"path": "../internal",
"description": "Use for internal implementation details",
"hidden": true,
},
},
}يؤثر hidden على الإكمال التلقائي فقط. يبقى المرجع المخفي الذي له وصف مُضمَّنًا في سياق الوكيل.
تظهر المراجع المُعدّة في الإكمال التلقائي @ في TUI. اكتب @alias لإرفاق جذر المرجع، أو @alias/ للبحث عن ملفات بداخله.
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، أو فواصل.