BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/extensions.mdx
View on GitHub---
title: "الامتدادات"
description: "قدرة اختيارية في مجموعة الأدوات للكتل المخصصة المعزولة ولمرة واحدة. يظل رمز التطبيق هو المسار الافتراضي للسلوك الدائم."
---
# الامتدادات
الامتدادات هي **قدرة اختيارية في مجموعة الأدوات للكتل المخصصة المعزولة**. تكون معطلة افتراضيًا، ويجب أن يفعّلها القالب صراحة. يستخدمها Analytics للتصورات المخصصة التي تُطلب صراحة ولمرة واحدة. للسلوك الدائم، عدّل رمز التطبيق.
إذا كنت قد استخدمت QuickBooks Online، فقد رأيت النموذج: QBO يشحن منتجًا محاسبيًا أساسيًا، ويضع المستخدمون طبقة على عناصر واجهة مستخدم صغيرة مخصصة - تقرير مخصص، وآلة حاسبة لكشوف المرتبات، ومدقق قواعد الضرائب - التي تعيش داخل نفس التطبيق وتستخدم نفس البيانات. الإضافات هي نسخة الوكيل الأصلية لهذه الفكرة، باستثناء أن المستخدمين لديك لا يكتبون أي تعليمات برمجية. يصفون ما يريدون، والوكيل يبنيه.
التأطير مهم: الإضافة ليست عبارة عن وضع حماية عام "افعل ما تريد". إنه **تطبيق صغير يعمل على توسيع قالب معين** - البريد والتحليلات والتقويم والقصاصات والتصميم - ويستخدم actions لهذا القالب وبياناته. ملحق البريد يقرأ رسائل البريد الإلكتروني. يقرأ ملحق Analytics مقاييس لوحة المعلومات. يعمل ملحق التقويم على الحدث المفتوح. إنهم يشعرون وكأنهم جزء من المنتج المضيف لأنهم _هم_ جزء من المنتج المضيف.
> **تضيف الامتدادات واجهة مستخدم، لكنها لا تعيد كتابة واجهة التطبيق
> المضيف.** يظهر الامتداد في صفحته الخاصة أو داخل [فتحة](#slots) مسماة
> يوفّرها القالب. ولا يمكنه إدراج عناصر داخل مكونات أصلية عشوائية — مثل
> وضع عنصر بجوار كل حاضر في التقويم — ما لم يوفّر القالب فتحة في ذلك الموضع.
> وللتخصيص الأعمق، غيّر القالب في مستودعك ومسار التطوير الخاص بك. يمكن للوكيل
> المضمّن المساعدة فقط عندما يمنحه المضيف عمدًا أدوات كتابة
> repository/workspace؛ أما الامتدادات فهي طبقة سريعة لا تتطلب النشر.
هناك ثلاثة أشياء تجعل الإضافات تعمل:
- **لا يوجد تعليمات برمجية، ولا يوجد نشر.** يكتبها الوكيل وستكون مباشرة في ثوانٍ. مخزنة في قاعدة البيانات، وليس الريبو.
- **الوصول الكامل إلى بيانات القالب.** يمكن للإضافات استدعاء نفس actions الذي يستدعيه الوكيل - `list-emails` في البريد، و`list-decks` في الشرائح، و`list-recordings` في Clips - بحيث يكون لديهم كل ما يحتويه التطبيق المضيف.
- **وحدة تخزين مدمجة.** يحتوي كل ملحق على مخزن قيمة مفتاح خاص به لكل مستخدم / لكل مؤسسة، لذا يمكنه حفظ الحالة دون إضافة جدول SQL جديد.
تكون الامتدادات معطلة افتراضيًا. لتمكينها، اضبط
`extensionTools: true` على كل من `createAgentChatPlugin()` و
`createCoreRoutesPlugin()`. يضيف الأول actions وإرشادات الوكيل، ويسمح الثاني
بالإنشاء الموثق عبر `POST /_agent-native/extensions`. يبقى وقت تشغيل العزل
ومسارات القراءة والتعديل والروابط الحالية متاحًا للتوافق.
<Diagram id="doc-block-xo599j" title={"جسر الرمل"} summary={"يعمل الامتداد HTML في إطار iframe معزول ولا يصل إلى المضيف إلا من خلال مجموعة ثابتة من مساعدي الجسر - يتم تحديد نطاق كل مكالمة والتحقق من الوصول إليها."}>
```html
<div class="ext-bridge">
<div class="diagram-card sandbox" data-rough>
<span class="diagram-pill warn">Sandboxed iframe</span
><small class="diagram-muted"
>Alpine.js HTML · no host cookies, session, or DOM</small
>
<div class="ext-helpers">
<span class="diagram-pill">appAction</span
><span class="diagram-pill">appFetch</span
><span class="diagram-pill">dbQuery</span
><span class="diagram-pill">extensionData</span
><span class="diagram-pill">extensionFetch</span>
</div>
</div>
<div class="diagram-arrow diagram-accent" aria-hidden="true">↔</div>
<div class="diagram-col">
<div class="diagram-box">
قالب المضيف<br /><small class="diagram-muted"
>إجراءات، SQL محدد النطاق تلقائيا</small
>
</div>
<div class="diagram-box">
Secret proxy<br /><small class="diagram-muted"
><code>${keys.NAME}</code>، مقفل بالنطاق</small
>
</div>
<div class="diagram-box">
واجهات API خارجية<br /><small class="diagram-muted"
>عبر extensionFetch فقط</small
>
</div>
</div>
</div>
```
```css
.ext-bridge {
display: flex;
align-items: center;
gap: 16px;
flex-wrap: wrap;
}
.ext-bridge .sandbox {
display: flex;
flex-direction: column;
gap: 8px;
padding: 16px 18px;
flex: 1;
min-width: 240px;
}
.ext-bridge .ext-helpers {
display: flex;
flex-wrap: wrap;
gap: 6px;
margin-top: 4px;
}
.ext-bridge .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
}
.ext-bridge .diagram-arrow {
font-size: 24px;
}
```
</Diagram>
يمكن أيضًا أن تكون الامتدادات ** مدعومة بالريبو في وضع الملف المحلي **. في سير العمل هذا،
يعلن `agent-native.json` عن مجلد `extensions`، ولكل ملحق
بيان `extension.json` بالإضافة إلى ملف إدخال HTML، ويقوم التطبيق بعرض تلك الملفات
الملفات من خلال نفس وضع الحماية. يتم تحرير الامتدادات المدعومة بالملفات عن طريق التغيير
ملفات الريبو؛ تحافظ الإضافات المدعومة بقاعدة البيانات على إنشاء/تحرير/مشاركة وقت التشغيل
التجربة الموضحة أدناه.
## معرض سريع {#gallery}
الامتدادات الحقيقية التي ينشئها الأشخاص بالفعل، مجمعة حسب النموذج الذي يعيشون فيه. كل واحدة منها عبارة عن شيء واحد مركّز - وليست سكينًا للجيش السويسري.
### البريد
يقوم المستخدم بقراءة بريد إلكتروني من `priya@acme.com`. ما نوع الأداة التي قد تساعدك في هذا الأمر؟
- **ملاحظات جهة الاتصال** — لوحة ملاحظات لاصقة مثبتة على الشخص الذي يرسل إليه المستخدم بريدًا إلكترونيًا. يقوم بتحميل الملاحظات الخاصة بجهة الاتصال هذه، ويتيح للمستخدم تدوين المزيد.
- **المواضيع الأخيرة مع هذا الشخص** — قائمة صغيرة بآخر خمس سلاسل رسائل مع جهة اتصال مفتوحة، منفصلة عن عرض البريد الوارد.
- **إثراء CRM** — يسحب حجم شركة جهة الاتصال، أو تاريخ الاجتماع الأخير، أو الصفقات المفتوحة من CRM.
- **اختصار جدولة الاجتماعات** — يحول عبارة "تحديد موعد الأسبوع المقبل" إلى أداة "إرسال هذه الفترات" بنقرة واحدة.
رسم — ملاحظات جهة الاتصال (يحفظ ملاحظة مرتبطة بالشخص الذي تراسله عبر البريد الإلكتروني):
```html
<div
class="p-4"
x-data="{
contactEmail: window.slotContext?.contactEmail,
note: '',
async init() {
if (!this.contactEmail) return;
const saved = await extensionData.get('notes', this.contactEmail);
if (saved) this.note = JSON.parse(saved.data).text;
},
async save() {
await extensionData.set('notes', this.contactEmail, { text: this.note });
}
}"
>
<p class="text-xs text-muted-foreground mb-2" x-text="contactEmail"></p>
<textarea
x-model="note"
@blur="save()"
class="w-full rounded-md border bg-background p-2 text-sm"
rows="4"
placeholder="Notes about this contact..."
></textarea>
</div>
```
### التحليلات
أحد المستخدمين يحدق في لوحة المعلومات. ما هو البلاط المفقود؟
- **مربع KPI مخصص** — رقم واحد كبير لمقياس ليس لوحة مدمجة. "بدأت التجارب هذا الأسبوع،" "MRR delta مقابل الشهر الماضي."
- **أداة تتبع الأهداف** — تسحب مقياسًا يختاره المستخدم ويعرض التقدم المحرز مقابل هدف كتبه المستخدم.
- **لوحة صدارة أهم العملاء** — لربط المقياس بجدول العملاء، وتصنيف العشرة الأوائل.
رسم — مربع KPI مخصص (يستدعي أحد استعلامات `appAction` الخاصة بنموذج التحليلات):
```html
<div
class="p-4"
x-data="{
value: null,
async init() {
const result = await appAction('query-agent-native-analytics', {
metric: 'trials_started',
range: '7d'
});
this.value = result?.total ?? 0;
}
}"
>
<p class="text-xs uppercase tracking-wider text-muted-foreground">
Trials this week
</p>
<p class="text-3xl font-bold mt-1" x-text="value ?? '—'"></p>
</div>
```
### التقويم
المستخدم لديه حدث مفتوح. ما الذي سيساعد في تلك اللحظة؟
- **قائمة التحقق من الإعداد للاجتماع** — التحميل التلقائي لعناصر جدول الأعمال والحاضرين وملخصات سلاسل المحادثات السابقة للحدث المفتوح.
- **وقت السفر** — "أمامك 35 دقيقة حتى اجتماعك التالي في موقع المهمة."
- **مساعد المنطقة الزمنية** — يعرض وقت الاجتماع بالتوقيت المحلي لكل حاضر في لمحة سريعة.
### مقاطع
يقوم المستخدم بمراجعة تسجيل الشاشة. ما الذي يعزز هذا الرأي؟
- **مستخرج عنصر العمل** — يقرأ نص المقطع (يجلبه الوكيل عبر `appAction`)، ويسرد المهام.
- **المشاركة التلقائية** — بنقرة واحدة "انشر رابط هذا المقطع على قناة #recordings Slack."
- **شريط التظليل** — يسحب الفصول التي أنشأها الوكيل ويحولها إلى قائمة تنقل سريعة.
### التصميم
يوجد لدى المستخدم مسودة صفحة Alpine/Tailwind مفتوحة. ما الذي من شأنه تسهيل حلقة النماذج الأولية؟
- **نموذج ألوان العلامة التجارية** — لوحة الألوان المأخوذة من تكوين العلامة التجارية للمستخدم، انقر لنسخ اللون إلى المحرر.
- **منتقي الأصول** — يسرد الصور التي قام المستخدم بتحميلها، ويسقط URL عند النقر.
- **مراقب التباعد** — يعرض رموز الفجوة/المساحة/الهامش التي تستخدمها الصفحة النشطة، حتى يتمكن المستخدم من الحفاظ على الاتساق.
النمط عبر كل هذه العناصر: تتعلق الإضافات بـ **اللحظة** التي يكون فيها المستخدم داخل القالب المضيف. يعرف الوكيل بالفعل جهة الاتصال ولوحة التحكم والحدث والمقطع - يستخدم الامتداد هذا السياق.
## كيف يقوم المستخدم بإنشاء واحدة {#building}
المسار البسيط:
1. افتح **Settings → Extensions** (أو اسأل فقط في الدردشة)، ثم انقر على **"ملحق جديد"**.
2. **صف ما تريده في جملة واحدة.** "لوحة ملاحظات لاصقة لجهة الاتصال التي أرسلها عبر البريد الإلكتروني." "بدأ صندوق KPI للتجارب هذا الأسبوع."
3. **يقوم الوكيل بكتابتها وتظهر في قائمة الملحقات لديك، جاهزة للاستخدام.**
لا يوجد ملف لتحريره، ولا يوجد نشر. يختار الوكيل المساعدين المناسبين (`appAction`، `extensionData`، `extensionFetch`) ويكتب Alpine.js HTML.
إذا كان الامتداد يحتاج إلى مفتاح API - رمز CRM، أو API للطقس - يخبرك الوكيل بما يجب إضافته ومكان إضافته. يتم تخزين المفاتيح مشفرة ومقفلة في نطاقات محددة.
إذا كنت تريد تغيير شيء ما لاحقًا، فما عليك سوى قول ذلك: "أضف مربع بحث إلى ملاحظات جهة الاتصال الخاصة بي." يقوم الوكيل بتحرير HTML في مكانه - دون تجديد كل شيء.
يتم إصدار كل تغيير. افتح عنصر التحكم في سجل عارض الإضافات لرؤية
الإصدارات المحفوظة، وفحص الفرق عن الإصدار السابق، واستعادة
الاسم/الوصف/الرمز/لقطة المحتوى القديمة دون تغيير الملكية أو
المشاركة.
## ما يمكن أن تفعله الإضافة {#capabilities}
داخل وضع حماية iframe، يحتوي كل ملحق على أدوات المساعدة التالية على `window`:
| المساعد | الغرض | مثال |
| ------------------------------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |
| `appAction(name, params)` | اتصل بأي من قوالب المضيف actions | `appAction('list-emails', { view: 'inbox' })` |
| `appFetch(path, options)` | استدعاء نقاط نهاية إطار العمل المسموح بها ضمن `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')` |
| `dbQuery(sql, args)` | القراءة من SQL (يتم تحديد نطاقها تلقائيًا للمستخدم) | `dbQuery('SELECT id, name FROM tools')` |
| `dbExec(sql, args)` | Legacy trusted SQL writes for editor/admin extensions | Prefer `appAction` for app data writes |
| `extensionFetch(url, options)` | اضغط على APIs الخارجية من خلال وكيل آمن به أسرار | `extensionFetch('https://api.github.com/user')` |
| `extensionData.set(collection, id, data, opts?)` | استمرار البيانات لكل ملحق (نطاق المستخدم/المؤسسة) | `extensionData.set('notes', id, { text: '...' })` |
| `extensionData.list(collection, opts?)` | قائمة العناصر المستمرة | `extensionData.list('notes', { scope: 'all' })` |
| `extensionData.get(collection, id, opts?)` | احصل على عنصر واحد | `extensionData.get('notes', 'note-1')` |
| `extensionData.remove(collection, id, opts?)` | حذف عنصر ثابت | `extensionData.remove('notes', 'note-1')` |
ثلاث قواعد أساسية:
- **تفضل `appAction` على `dbQuery`.** Actions هي السطح الرسمي للقالب - فهي تتولى التحكم في الوصول وتحديد النطاق والتحقق من الصحة نيابةً عنك. يمكنك الوصول إلى SQL الخام فقط عندما لا يكون هناك إجراء مناسب.
- **استخدم `appAction` لبيانات القالب.** يقتصر الامتداد `appFetch` على نقاط نهاية إطار العمل `/_agent-native/*`؛ تم حظر مسارات القالب `/api/*` بواسطة جسر iframe.
- ** تفضل `extensionData` على إنشاء جداول جديدة. ** يحصل كل ملحق على مخزن القيمة الرئيسية المعزول الخاص به. لا يوجد مخطط، لا الهجرة. قم بتعيين `{ scope: 'org' }` للمشاركة مع مؤسسة المستخدم، `'user'` (افتراضي) للخاص.
```html
<script>
// Private to me
await extensionData.set('notes', 'note-1', { title: 'My note' });
// Shared with my org
await extensionData.set('notes', 'team-note', { title: 'Team note' }, { scope: 'org' });
// List everything visible to me (mine + org)
const all = await extensionData.list('notes', { scope: 'all' });
</script>
```
تمر API الخارجية عبر `extensionFetch`، الذي يقوم بتوكيل جانب خادم الاتصال واستبدال الأسرار عبر قالب `${keys.NAME}`:
```html
<script>
const res = await extensionFetch('https://api.github.com/user', {
headers: { Authorization: 'Bearer ${keys.GITHUB_TOKEN}' },
});
</script>
```
المفتاح الفعلي لا يصل إلى المتصفح مطلقًا. يتم قفل كل مفتاح بقائمة مسموح بها من النطاقات، لذا لا يمكن للإضافة المسربة أن تقوم بتصفيتها إلى مكان آخر.
## الفتحات — وضع امتداد داخل المضيف UI {#slots}
يصف المعرض أعلاه _ما_ تفعله الإضافة. تصف الفتحات _مكان_ ظهورها.
افتراضيًا، تظل الإضافة موجودة في صفحتها الخاصة في قائمة الإضافات - افتحها كتطبيق صغير. وهذا أمر جيد بالنسبة للوحات المعلومات، والآلات الحاسبة، والأدوات المستقلة.
توجد الفتحات المسماة في المواضع التي يعرض فيها التطبيق المضيف `<ExtensionSlot>` ويمرر سياق الصفحة الحالي. تربط أهداف الفتحات وعمليات التثبيت الإضافات بهذه المواضع الموجودة. ولا تنشئ لوحة أو علامة تبويب أو مسارًا.
الفتحة هي منطقة عناصر واجهة مستخدم محددة يتم شحن القالب إليها:
| القالب | مثال للفتحة | مكان ظهوره |
| ----------- | ------------------------------ | ---------------------------------------------------- |
| **البريد** | `mail.contact-sidebar.bottom` | أسفل معلومات الاتصال في كل سلسلة رسائل بريد إلكتروني |
| **التقويم** | `calendar.event-detail.bottom` | أسفل الحدث المفتوح |
| **المحتوى** | `content.sidebar.bottom` | أسفل الشريط الجانبي للمستند |
عند تثبيت ملحق في إحدى الفتحات، يرسل المضيف سياقه المختار، مثل البريد الإلكتروني لجهة الاتصال أو معرف الحدث أو معرف المستند، إلى إطار iframe. يقرأ الامتداد `window.slotContext` لمعرفة ما ينظر إليه المستخدم.
<Diagram id="doc-block-u5g4nl" title={"فتحات تدفع السياق إلى القطعة"} summary={"يمتلك القالب المضيف فتحات مسماة؛ يؤدي تثبيت الامتداد إلى تغذيته window.slotContext لكل ما يشاهده المستخدم حاليًا."}>
```html
<div class="slot">
<div class="diagram-card">
<span class="diagram-pill">سلسلة بريد</span
><small class="diagram-muted"
>slot <code>mail.contact-sidebar.bottom</code></small
>
</div>
<div class="diagram-arrow diagram-accent" aria-hidden="true">→</div>
<div class="diagram-box accent">
<code>window.slotContext</code><br /><small class="diagram-muted"
>{ contactEmail }</small
>
</div>
<div class="diagram-arrow diagram-accent" aria-hidden="true">→</div>
<div class="diagram-card">
<span class="diagram-pill">ملاحظات جهة الاتصال</span
><small class="diagram-muted"
>loads notes for that contact — same widget, different
context</small
>
</div>
</div>
```
```css
.slot {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
.slot .diagram-card {
display: flex;
flex-direction: column;
gap: 4px;
padding: 14px 16px;
min-width: 180px;
}
.slot .diagram-arrow {
font-size: 22px;
}
```
</Diagram>
### مثال ملموس
تخيل ملحق ملاحظات جهة الاتصال من المعرض. إنها في حد ذاتها أداة مستقلة. لجعله يظهر داخل الشريط الجانبي لجهة اتصال البريد:
1. أنشئ الامتداد مرة واحدة. استخدم `window.slotContext.contactEmail` حتى تعرف جهة الاتصال التي يستخدمها المستخدم.
2. أخبره بالفتحة التي يمكنه ملؤها: `add-extension-slot-target { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
3. تثبيته: `install-extension { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
في المرة التالية التي تفتح فيها سلسلة رسائل بريد إلكتروني، تكون لوحة الملاحظات اللاصقة أسفل معلومات جهة الاتصال مباشرة - وهي مليئة بالملاحظات الخاصة بالشخص الذي تراسله عبر البريد الإلكتروني. قم بالتبديل إلى موضوع مختلف، وسيتم تحميل الملاحظات الخاصة بجهة الاتصال _that_. نفس الامتداد، سياق مختلف، لا توجد إعادة كتابة.
عمليًا، لا يمكنك تشغيل هذه الأوامر الثلاثة يدويًا. ما عليك سوى قول "تثبيت هذه الأداة على الشريط الجانبي لجهة الاتصال" وسيتولى الوكيل التعامل مع الهدف + التثبيت نيابةً عنك.
> **الفتحات عبارة عن قدرة \_مضافة، وليست شرطًا أساسيًا.** لا يتم تثبيت الكثير من الإضافات المفيدة في إحدى الفتحات أبدًا — فهي تعيش بسعادة على صفحتها الخاصة. يمكنك الوصول إلى الفتحات عندما يلزم أن تكون الأداة _بجوار_ ما يبحث عنه المستخدم في القالب المضيف.
للحصول على تفاصيل أعمق حول الفتحات — كيفية الإعلان عنها في القالب الخاص بك، وكيفية عمل عقد السياق، وكيفية تحديد نطاق عمليات التثبيت — راجع مهارة `extension-points`. يتم شحن Skills داخل كل قالب سقالة تحت `.agents/skills/`؛ راجع [Skills Guide](/docs/skills-guide) لمعرفة كيفية عملها.
## امتدادات الملفات المحلية {#local-file-extensions}
يتيح وضع الملف المحلي لمساحة العمل الاحتفاظ بالامتدادات في الريبو:
```text
extensions/
doc-status/
extension.json
index.html
```
```json
{
"id": "doc-status",
"name": "Doc Status",
"description": "Shows metadata for the selected Content file.",
"entry": "index.html",
"slots": ["content.sidebar.bottom"],
"permissions": {
"appActions": ["list-documents"],
"extensionData": true
}
}
```
أضف المجلد إلى التطبيق ذي الصلة في `agent-native.json`:
```json
{
"apps": {
"content": {
"mode": "local-files",
"roots": [{ "name": "Docs", "path": "docs", "extensions": [".mdx"] }],
"components": "components",
"extensions": "extensions"
}
}
}
```
يدرج التطبيق الامتدادات المدعومة بالملفات إلى جانب الإضافات والعروض المدعومة بقاعدة البيانات
من خلال iframe العادي لوضع الحماية. إعلانات الفتحات في `extension.json`
تثبيت الامتداد تلقائيًا في `ExtensionSlot`s المطابقة؛ لا يوجد لكل مستخدم
صف تثبيت SQL للإضافات المحلية.
تحتوي الإضافات المحلية على نموذج إذن v1 أكثر صرامة:
- يتوفر `extensionData` لحالة وقت التشغيل الصغيرة ما لم يتم تعطيله.
- يجب إدراج مكالمات `appAction` بوضوح في `permissions.appActions`.
- تم حظر `dbQuery` و`extensionFetch` في الوقت الحالي.
- يعرض التحديث المدعوم من SQL والحذف والمشاركة والمحفوظات actions رسالة مفادها
يشير مرة أخرى إلى ملف الإدخال المحلي.
استخدم الإضافات المدعومة بقاعدة البيانات عندما يتعين على المستخدمين إنشاء/مشاركة/تحرير الأدوات على
وقت التشغيل. استخدم امتدادات الملفات المحلية عندما يكون الامتداد جزءًا من الريبو أولاً
مساحة العمل ويجب أن تكون قابلة للمراجعة والتصحيح وإصدار الإصدارات مع بقية
الملفات.
## المشاركة {#sharing}
تعد الملحقات خاصة بالمستخدم الذي قام بإنشائها بشكل افتراضي. للمشاركة:
- **مؤسسة مرئية** — يمكن لجميع الأشخاص في المؤسسة رؤيتها واستخدامها.
- **المنح لكل مستخدم** — دعوة أشخاص محددين كمشاهدين/محررين/مشرفين.
تحتوي الملحقات المشتركة على URL الخاصة بها ويتم توصيلها بنفس مربع حوار المشاركة مثل المستندات والمجموعات ولوحات المعلومات. تكون عمليات تثبيت الفتحات دائمًا شخصية - فمشاركة الملحق تعني أنه بإمكان الآخرين تثبيته؛ ولا يقوم بتثبيته تلقائيًا على UI.
## هل أستخدم امتدادًا أم مسار مصدر التطبيق؟ {#vs-app-code}
لا يقوم الوكيل المضمّن بتحرير المصدر افتراضيًا؛ لا يتوفر ذلك إلا عندما يمنحه المضيف عمدًا أدوات كتابة repository/workspace. استخدم مسار المصدر لسلوك المنتج الدائم، والامتداد للتخصيص السريع في وقت التشغيل.
- **ابدأ برمز التطبيق** لسلوك المنتج أو واجهة المستخدم الأصلية أو التخطيط أو المسارات أو منطق الأعمال أو أي شيء سيُعاد استخدامه.
- **استخدم كتلة مخصصة فقط إذا فعّلها التطبيق** وطلب المستخدم صراحة تصورًا أو تفاعلًا لمرة واحدة في سطح موجود. إنها سريعة ولا تحتاج إلى نشر، لكنها تظل تصحيحًا معزولًا أنشأه الوكيل.
- **رقِّ الكتل الدائمة.** إذا أصبحت الكتلة مفيدة خارج سياقها الأصلي، فاستخدم **الترقية إلى رمز التطبيق** وأبقِ الكتلة الأصلية حتى مراجعة التغيير ونشره.
| | الامتداد | تعديل كود التطبيق |
| --------------------- | ----------------------------------- | ------------------------------------------ |
| **تم الإنشاء بواسطة** | الوكيل (أو المستخدم) في وقت التشغيل | المستخدم أو مسار قادر على التعامل مع الكود |
| **مخزن في** | قاعدة البيانات | مستودع git |
| **يتطلب إنشاء** | لا | نعم |
| **يتطلب النشر** | لا | نعم |
| **النطاق** | مستخدم واحد (أو مشترك مع المؤسسة) | المنتج بأكمله، لكل مستخدم |
| **الأفضل لـ** | كتل مخصصة صريحة ولمرة واحدة | سلوك منتج دائم |
القاعدة الأساسية: **استخدم رمز التطبيق افتراضيًا.** في تطبيق يفعّل الامتدادات، يمكن أن يكون التصور لمرة واحدة كتلة مخصصة؛ أما نوع المخطط الجديد الذي يجب أن يتوفر في جميع لوحات المعلومات فينتمي إلى رمز القالب.
لجلب بيانات مخصص يجب أن يغذّي رسومًا بيانية وجداولًا أصلية بدلاً من واجهة أداة مخصصة، راجع [برامج البيانات](/docs/data-programs) — نص `run-code` مخزَّن وقابل للتحديث ترتبط به لوحات dashboard مباشرة، دون أي iframe امتداد.
## الأمان {#security}
<Callout id="doc-block-frp4nq" tone="success">
**The raw secret never reaches the browser.** `extensionFetch` substitutes `${keys.NAME}` server-side and each key is locked to a URL allowlist, so even a leaked extension can't exfiltrate it elsewhere.
</Callout>
يتم تشغيل الامتدادات في إطار iframe معزول:
- **معزول** عن ملفات تعريف الارتباط والجلسة وDOM للتطبيق الأصلي.
- **الحقن السري من جانب الخادم** عبر قالب `${keys.NAME}` — قيمة المفتاح الفعلية لا تصل أبدًا إلى المتصفح.
- **أسرار النطاق المقفل** — يرتبط كل مفتاح بالقائمة المسموح بها URL؛ يرفض الوكيل الطلبات المقدمة إلى المضيفين الآخرين.
- **حماية الشبكة الخاصة** — لا يمكن للملحقات الوصول إلى العناوين الداخلية.
- **المصادقة مطلوبة** — يتم تشغيل الإضافات فقط للمستخدمين الذين قاموا بتسجيل الدخول، ويتم تحديد نطاق مكالمات `dbQuery` تلقائيًا.
## بعض الأشياء التي يجب معرفتها حول التسمية {#naming-back-compat}
إذا كنت تبحث حول SQL أو المصدر، فسترى مزيجًا من أسماء "الامتداد" و"الأداة". وحدة فك الترميز السريعة:
- كان يُطلق على البدائي الذي يواجه المستخدم اسم "الأدوات". أصبح الآن **الامتدادات**.
- تحتفظ جداول SQL الفعلية (`tools`، `tool_data`، `tool_shares`، `tool_slots`، `tool_slot_installs`) بأسمائها الأصلية - إعادة تسمية الجدول هي عملية ترحيل تدميرية، ولا يقوم إطار العمل بشحن عمليات ترحيل تدميرية.
- تستخدم صادرات Drizzle / TypeScript الأسماء الجديدة: `extensions`، `extensionData`، `extensionShares`، `extensionSlots`، `extensionSlotInstalls`.
- داخل إطار iframe الخاص بالامتداد، المساعدان الأساسيان هما `extensionFetch` و`extensionData`. لا يزال يتم حل الأسماء القديمة `toolFetch` و`toolData`، لذا يستمر الامتداد الأقدم HTML في العمل.
لن ترى هذا أيضًا في الاستخدام العادي، ولكن لدى الوكيل مفهوم ثالث ذو صلة يسمى "أدوات LLM" - مساحة سطح استدعاء الوظيفة في دورة النموذج (المحددة عبر `defineAction`، MCP، وما إلى ذلك). هذه هي الأدوات البدائية لاستدعاء الوظائف، وليست الأدوات التي تواجه المستخدم. عندما تقول هذه الصفحة "امتداد"، فهذا يعني الأداة التي تواجه المستخدم؛ عندما تقول المستندات الأخرى "أداة" بجانب `defineAction`، فهذا هو مفهوم LLM.
## ما هي الخطوة التالية
- [**Templates**](/docs/cloneable-saas) — تمتد امتدادات التطبيقات المضيفة
- [**Actions**](/docs/actions-overview) — العمليات التي يستدعيها الامتداد عبر `appAction`
- [**Sharing & Privacy**](/docs/sharing) — كيفية عمل رؤية الإضافات ومشاركة المؤسسة والمنح لكل مستخدم
- [**Onboarding & API Keys**](/docs/onboarding) — كيف تظهر الأسرار في الإعدادات UI
- [**Security**](/docs/security) — نموذج نطاق البيانات والوصول إليها
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |