@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ar-SA/evals.md

@@ -0,0 +1,155 @@
+---
+title: "بوابة تقييم CI"
+description: "اكتب حالات اختبار *.eval.ts التي تقوم بتشغيل الوكيل الحقيقي مقابل المدخلات الثابتة، وسجل المخرجات باستخدام أدوات تسجيل قابلة للتركيب، وبوابة CI/النشر على عتبة."
+---
+
+# بوابة تقييم CI
+
+تعد عمليات التقييم اختبارًا بدائيًا من الدرجة الأولى: فأنت تعلن عن الموجه بالإضافة إلى السلوك الذي تتوقعه، ويقوم العداء **في الواقع بتشغيل حلقة الوكيل** مقابل هذا الإدخال، ويسجل المخرجات باستخدام أدوات تسجيل قابلة للتركيب، ويخرج من الصفر إذا سجلت أي حالة أقل من العتبة. هذا الخروج غير الصفري يجعل `agent-native eval` بوابة نشر CI منسدلة.
+
+هذا مكمل للتسجيل اللاحق في [Observability](/docs/observability):
+
+- **تقييمات إمكانية الملاحظة** (`observability/evals.ts`) — _"كيف كان أداء هذا التشغيل الحقيقي؟"_ السلبي، الذي يتم أخذ العينات منه، ويعيش بجوار الآثار.
+- **`*.eval.ts` (هذا البدائي)** — _"هل يفعل الوكيل الشيء الصحيح على هذا الإدخال الثابت؟"_ بوابة CI نشطة وحتمية يتم تشغيلها عبر CLI.
+
+يقوم المشغل بحل محرك/نموذج غير موفر الخدمة من السجل الحالي - لا يوجد نموذج مضمن - لذلك تعمل المجموعة نفسها على أي محرك تم تكوين التطبيق من أجله.
+
+```an-diagram title="From fixed input to deploy gate" summary="The runner actually runs the agent loop on each case, scores the output, and exits non-zero if any scorer falls below threshold — making it a drop-in CI gate."
+{
+  "html": "<div class=\"eval-flow\"><div class=\"diagram-node\">*.eval.ts<br><small class=\"diagram-muted\">prompt + expected behavior</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Run the agent loop<br><small class=\"diagram-muted\">real engine/model</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Scorers<br><small class=\"diagram-muted\">every one must pass threshold</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box ok\">exit 0 &rarr; deploy</div><div class=\"diagram-box warn\">exit 1 &rarr; block</div></div></div>",
+  "css": ".eval-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.eval-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.eval-flow .diagram-col{display:flex;flex-direction:column;gap:8px}.eval-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## كتابة التقييم {#writing}
+
+أسقط ملف `*.eval.ts` في أي مكان في التطبيق (أو ملف `evals/*.ts`). كل ملف `export default defineEval(...)` (أو يصدر مجموعة منهم):
+
+```ts
+// evals/greeting.eval.ts
+import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
+
+export default defineEval({
+  name: "greets the user by name",
+  input: { prompt: "Say hi to Ada." },
+  threshold: 0.7, // per-scorer pass bar; default 0.5
+  scorers: [
+    contains("Ada"),
+    llmJudge({ criteria: "friendliness", rubric: "1.0 = warm greeting" }),
+  ],
+});
+```
+
+يتم تمرير التقييم فقط عندما يصل **كل** المسجل إلى الحد الأدنى. حقول `defineEval` الرئيسية:
+
+| الحقل       | اكتب                  | ملاحظات                                                           |
+| ----------- | --------------------- | ----------------------------------------------------------------- |
+| `name`      | سلسلة                 | مطلوب. موضح في التقرير.                                           |
+| `input`     | `{ prompt, history }` | مطلوب `prompt`؛ المنعطفات الاختيارية السابقة لـ `{ role, text }`. |
+| `scorers`   | `Scorer[]`            | مطلوب، واحد على الأقل.                                            |
+| `threshold` | رقم `0..1`            | شريط التمرير لكل هداف. الافتراضي `0.5`؛ يمكن تجاوزه من CLI.       |
+| `run`       | الوظيفة               | تجاوز اختياري للإعداد المخصص (بيانات أولية، متعددة المنعطفات).    |
+
+إن عملية تشغيل الوكيل التي يتم تسليمها إلى الهدافين صغيرة الحجم وغير ملائمة للنقل:
+
+```ts
+interface AgentRunOutput {
+  text: string; // concatenated assistant text
+  toolCalls: readonly string[]; // tool/action names, in call order
+  ok: boolean; // completed without a terminal error
+  error?: string;
+  runId: string;
+  durationMs: number;
+}
+```
+
+## الهدافين المدمجين {#built-in}
+
+مستورد من `@agent-native/core/eval`:
+
+| هداف                     | النتيجة                                                              | النموذج؟ |
+| ------------------------ | -------------------------------------------------------------------- | -------- |
+| `exactMatch(expected)`   | `1.0` إذا كان النص يساوي `expected` (مقتطع، غير حساس لحالة الأحرف)   | لا       |
+| `contains(needles)`      | جزء من السلاسل الفرعية المطلوبة موجودة (لذلك تظهر النتائج الجزئية)   | لا       |
+| `usesTool(toolName)`     | `1.0` إذا قام الوكيل باستدعاء تلك الأداة/الإجراء مرة واحدة على الأقل | لا       |
+| `llmJudge({ criteria })` | سجل LLM كحكم مقابل قواعد تقييم اللغة الطبيعية، → `0..1`              | نعم      |
+
+يأخذ `exactMatch` و`contains` `{ caseSensitive }` اختياريًا. يأخذ `llmJudge` `{ criteria, rubric?, name?, scoreRange? }` - تتم تسوية مخرجاته إلى `[0, 1]`، ونموذج القاضي هو ما يحله العداء (ليس مزودًا مضمنًا على الإطلاق).
+
+## الهدافون المخصصون: المسار المكون من 4 خطوات {#custom}
+
+يبني `createScorer` هدافًا من أسلوب Mastra ذو 4 خطوات. مطلوب `generateScore` فقط:
+
+```an-diagram title="The 4-step scorer pipeline" summary="preprocess and analyze default to identity; only generateScore is required. analyze can run plain JS or call an LLM judge via ctx."
+{
+  "html": "<div class=\"scorer\"><div class=\"diagram-card\"><span class=\"diagram-pill\">preprocess(run)</span><small class=\"diagram-muted\">transform the run/output &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">analyze(x, ctx)</span><small class=\"diagram-muted\">plain JS or LLM judge &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">generateScore(a)</span><small class=\"diagram-muted\">&rarr; 0..1 normalized &middot; <strong>required</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">generateReason</span><small class=\"diagram-muted\">human-readable why &middot; optional</small></div></div>",
+  "css": ".scorer{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.scorer .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.scorer .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+```text
+preprocess(run)     → x          transform the run/output (optional)
+analyze(x, ctx)     → analysis   plain JS OR an LLM judge (optional)
+generateScore(a)    → 0..1       REQUIRED, normalized
+generateReason(...) → string     human-readable why (optional)
+```
+
+`preprocess` و`analyze` الافتراضيان للهوية (يرى الهداف `AgentRunOutput` الخام). تتلقى خطوة `analyze` `ctx` مع مساعد `judge()` غير الموفر للتسجيل المدعوم من LLM:
+
+```ts
+import { createScorer, clamp01 } from "@agent-native/core/eval";
+
+// A scorer that rewards short, tool-using answers.
+const concise = createScorer({
+  name: "concise_with_tool",
+  analyze(run) {
+    return {
+      words: run.text.trim().split(/\s+/).length,
+      usedTool: run.toolCalls.length > 0,
+    };
+  },
+  generateScore({ words, usedTool }) {
+    if (!usedTool) return 0;
+    return clamp01(1 - Math.max(0, words - 40) / 200);
+  },
+  generateReason({ analysis }) {
+    return `${analysis.words} words, tool used: ${analysis.usedTool}`;
+  },
+});
+```
+
+## تشغيل البوابة {#cli}
+
+```bash
+agent-native eval                    # run every *.eval.ts; non-zero exit on failure
+agent-native eval billing            # only files whose path contains "billing"
+agent-native eval --json             # machine-readable report (for CI)
+agent-native eval --threshold 0.8    # override every eval's pass threshold (0..1)
+```
+
+يكتشف الأمر `**/*.eval.ts` و`evals/*.ts` ضمن التطبيق الحالي، ويقوم بتشغيل الوكيل لكل إدخال، ويسجله، ويطبع جدولًا قابلاً للقراءة (أو JSON)، و**يخرج من الصفر في حالة وجود أي درجات تقييم أقل من الحد الخاص به**.
+
+رموز الخروج:
+
+| الرمز | المعنى                                                                              |
+| ----- | ----------------------------------------------------------------------------------- |
+| `0`   | تم اجتياز جميع عمليات التقييم — _or_ لم يتم العثور على ملفات تقييم (متوافقة مع CI). |
+| `1`   | تم تسجيل تقييم واحد على الأقل أقل من الحد الأدنى، أو حدث خطأ في المجموعة.           |
+| `2`   | وسيطات غير صالحة (على سبيل المثال، `--threshold` خارج `[0, 1]`).                    |
+
+### كبوابة نشر CI {#ci}
+
+قم بإضافته إلى المسار الذي يتم تشغيله قبل النشر:
+
+```yaml
+# .github/workflows/deploy.yml (excerpt)
+- run: npx agent-native eval --json
+```
+
+الانحدار الذي يسقط أي مسجل أقل من الحد يفشل في الخطوة ويمنع النشر. يخرج التطبيق الذي لا يحتوي على ملفات تقييم من `0`، لذا فإن اعتماد التقييمات يعد اختيارًا لكل تطبيق.
+
+## ما هي الخطوة التالية
+
+- [**Observability**](/docs/observability) — التسجيل اللاحق لعمليات الإنتاج الحقيقية (الطبقة التكميلية)
+- [**Actions**](/docs/actions) — الأدوات/actions التي تظهر في `toolCalls`
+- [**Agent Teams**](/docs/agent-teams) — الوكلاء الفرعيون الذين قد يمارسهم التقييم

package/docs/content/locales/ar-SA/extensions.md

@@ -0,0 +1,360 @@
+---
+title: "الامتدادات"
+description: "التطبيقات المصغرة التي ينشئها المستخدمون داخل القالب الخاص بك — لوحة KPI مخصصة في Analytics، وقائمة مرجعية للإعداد للاجتماع في التقويم، وأداة CRM لجهة الاتصال في البريد. لا توجد عمليات نشر، ولا تعديلات على التعليمات البرمجية، ولا تغييرات في المخطط."
+---
+
+# الامتدادات
+
+الإضافات هي **تطبيقات صغيرة ينشئها المستخدمون داخل القالب الخاص بك**.
+
+إذا كنت قد استخدمت QuickBooks Online، فقد رأيت النموذج: QBO يشحن منتجًا محاسبيًا أساسيًا، ويضع المستخدمون طبقة على عناصر واجهة مستخدم صغيرة مخصصة - تقرير مخصص، وآلة حاسبة لكشوف المرتبات، ومدقق قواعد الضرائب - التي تعيش داخل نفس التطبيق وتستخدم نفس البيانات. الإضافات هي نسخة الوكيل الأصلية لهذه الفكرة، باستثناء أن المستخدمين لديك لا يكتبون أي تعليمات برمجية. يصفون ما يريدون، والوكيل يبنيه.
+
+التأطير مهم: الإضافة ليست عبارة عن وضع حماية عام "افعل ما تريد". إنه **تطبيق صغير يعمل على توسيع قالب معين** - البريد والتحليلات والتقويم والقصاصات والتصميم - ويستخدم actions لهذا القالب وبياناته. ملحق البريد يقرأ رسائل البريد الإلكتروني. يقرأ ملحق Analytics مقاييس لوحة المعلومات. يعمل ملحق التقويم على الحدث المفتوح. إنهم يشعرون وكأنهم جزء من المنتج المضيف لأنهم _هم_ جزء من المنتج المضيف.
+
+هناك ثلاثة أشياء تجعل الإضافات تعمل:
+
+- **لا يوجد تعليمات برمجية، ولا يوجد نشر.** يكتبها الوكيل وستكون مباشرة في ثوانٍ. مخزنة في قاعدة البيانات، وليس الريبو.
+- **الوصول الكامل إلى بيانات القالب.** يمكن للإضافات استدعاء نفس actions الذي يستدعيه الوكيل - `list-emails` في البريد، و`list-decks` في الشرائح، و`list-recordings` في Clips - بحيث يكون لديهم كل ما يحتويه التطبيق المضيف.
+- **وحدة تخزين مدمجة.** يحتوي كل ملحق على مخزن قيمة مفتاح خاص به لكل مستخدم / لكل مؤسسة، لذا يمكنه حفظ الحالة دون إضافة جدول SQL جديد.
+
+إذا كان من المفترض ألا يعرض القالب الامتدادات التي كتبها المستخدم، فاضبط
+`extensionTools: false` على `createAgentChatPlugin()`. يؤدي ذلك إلى إزالة
+الملحق المواجه للوكيل actions والتوجيه الفوري أثناء مغادرة بقية
+وكيل التطبيق سليم.
+
+```an-diagram title="The sandbox bridge" summary="Extension HTML runs in an isolated iframe and reaches the host only through a fixed set of bridge helpers — every call is scoped and access-checked."
+{
+  "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 &middot; 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 / dbExec</span><span class=\"diagram-pill\">extensionData</span><span class=\"diagram-pill\">extensionFetch</span></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Host template<br><small class=\"diagram-muted\">actions, auto-scoped SQL</small></div><div class=\"diagram-box\">Secret proxy<br><small class=\"diagram-muted\"><code>${keys.NAME}</code>, domain-locked</small></div><div class=\"diagram-box\">External APIs<br><small class=\"diagram-muted\">via extensionFetch only</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}"
+}
+```
+
+يمكن أيضًا أن تكون الامتدادات ** مدعومة بالريبو في وضع الملف المحلي **. في سير العمل هذا،
+يعلن `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. **انقر على "ملحق جديد"** في الشريط الجانبي (أو اسأل فقط في الدردشة).
+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)`                              | اكتب إلى SQL                                                     | `dbExec('INSERT INTO ...')`                               |
+| `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}
+
+يصف المعرض أعلاه _ما_ تفعله الإضافة. تصف الفتحات _مكان_ ظهورها.
+
+افتراضيًا، تظل الإضافة موجودة في صفحتها الخاصة في قائمة الإضافات - افتحها كتطبيق صغير. وهذا أمر جيد بالنسبة للوحات المعلومات، والآلات الحاسبة، والأدوات المستقلة.
+
+لكن معظم حالات الاستخدام ذات الشكل QBO مختلفة: يريد المستخدم تثبيت الأداة الخاصة به _داخل_ UI للقالب - أسفل معلومات الاتصال في الشريط الجانبي للبريد، في زاوية لوحة تحكم Analytics، على الجانب الأيمن من حدث التقويم. هذا هو الغرض من **الفتحات**.
+
+الفتحة هي منطقة عناصر واجهة مستخدم محددة يتم شحن القالب إليها:
+
+| القالب        | مثال للفتحة                    | مكان ظهوره                                           |
+| ------------- | ------------------------------ | ---------------------------------------------------- |
+| **البريد**    | `mail.contact-sidebar.bottom`  | أسفل معلومات الاتصال في كل سلسلة رسائل بريد إلكتروني |
+| **التحليلات** | `analytics.dashboard.tiles`    | بجانب اللوحات المدمجة في لوحة القيادة                |
+| **التقويم**   | `calendar.event-detail.bottom` | أسفل الحدث المفتوح                                   |
+| **المقاطع**   | `clips.right-panel.tabs`       | علامة تبويب جديدة في لوحة مراجعة المقطع              |
+
+عند تثبيت ملحق في إحدى الفتحات\*\*، يدفع المضيف السياق ذي الصلة — البريد الإلكتروني لجهة الاتصال، ومعرف لوحة المعلومات، ومعرف الحدث — في إطار iframe. يقرأ الامتداد `window.slotContext` لمعرفة ما ينظر إليه المستخدم.
+
+```an-diagram title="Slots push context into the widget" summary="The host template owns named slots; installing an extension into one feeds it window.slotContext for whatever the user is currently viewing."
+{
+"html": "<div class=\"slot\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Mail thread</span><small class=\"diagram-muted\">slot <code>mail.contact-sidebar.bottom</code></small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</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\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Contact notes</span><small class=\"diagram-muted\">loads notes for that contact &mdash; 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}"
+}
+
+```
+
+### مثال ملموس
+
+تخيل ملحق ملاحظات جهة الاتصال من المعرض. إنها في حد ذاتها أداة مستقلة. لجعله يظهر داخل الشريط الجانبي لجهة اتصال البريد:
+
+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` و`dbExec` و`extensionFetch` في الوقت الحالي.
+- يعرض التحديث المدعوم من SQL والحذف والمشاركة والمحفوظات actions رسالة مفادها
+  يشير مرة أخرى إلى ملف الإدخال المحلي.
+
+استخدم الإضافات المدعومة بقاعدة البيانات عندما يتعين على المستخدمين إنشاء/مشاركة/تحرير الأدوات على
+وقت التشغيل. استخدم امتدادات الملفات المحلية عندما يكون الامتداد جزءًا من الريبو أولاً
+مساحة العمل ويجب أن تكون قابلة للمراجعة والتصحيح وإصدار الإصدارات مع بقية
+الملفات.
+
+## المشاركة {#sharing}
+
+تعد الملحقات خاصة بالمستخدم الذي قام بإنشائها بشكل افتراضي. للمشاركة:
+
+- **مؤسسة مرئية** — يمكن لجميع الأشخاص في المؤسسة رؤيتها واستخدامها.
+- **المنح لكل مستخدم** — دعوة أشخاص محددين كمشاهدين/محررين/مشرفين.
+
+تحتوي الملحقات المشتركة على URL الخاصة بها ويتم توصيلها بنفس مربع حوار المشاركة مثل المستندات والمجموعات ولوحات المعلومات. تكون عمليات تثبيت الفتحات دائمًا شخصية - فمشاركة الملحق تعني أنه بإمكان الآخرين تثبيته؛ ولا يقوم بتثبيته تلقائيًا على UI.
+
+## الإضافات مقابل تعديل رمز التطبيق {#vs-app-code}
+
+يسمح إطار العمل للوكيل بتحرير التعليمات البرمجية المصدر للتطبيق مباشرة - المكونات والمسارات والأنماط. إذن متى يجب عليك الوصول إلى التمديد بدلاً من ذلك؟
+
+|                       | الامتداد                                                                     | تعديل كود التطبيق                                  |
+| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------- |
+| **تم الإنشاء بواسطة** | الوكيل (أو المستخدم) في وقت التشغيل                                          | الوكيل يقوم بتحرير الملفات المصدرية                |
+| **مخزن في**           | قاعدة البيانات                                                               | مستودع git                                         |
+| **يتطلب إنشاء**       | لا                                                                           | نعم                                                |
+| **يتطلب النشر**       | لا                                                                           | نعم                                                |
+| **النطاق**            | مستخدم واحد (أو مشترك مع المؤسسة)                                            | المنتج بأكمله، لكل مستخدم                          |
+| **الأفضل لـ**         | الأدوات الشخصية، ومؤشرات الأداء الرئيسية المخصصة، والأدوات المساعدة لكل فريق | الميزات الأساسية التي يتم توفيرها لجميع المستخدمين |
+
+القاعدة الأساسية: **إذا كان ذلك لمستخدم واحد أو لفريق واحد، فهو امتداد. ** إذا كان كل مستخدم للقالب يريد الحصول عليه، قم بشحنه كميزة حقيقية.
+
+## الأمان {#security}
+
+```an-callout
+{ "tone": "success", "body": "**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." }
+```
+
+يتم تشغيل الامتدادات في إطار iframe معزول:
+
+- **معزول** عن ملفات تعريف الارتباط والجلسة وDOM للتطبيق الأصلي.
+- **الحقن السري من جانب الخادم** عبر قالب `${keys.NAME}` — قيمة المفتاح الفعلية لا تصل أبدًا إلى المتصفح.
+- **أسرار النطاق المقفل** — يرتبط كل مفتاح بالقائمة المسموح بها URL؛ يرفض الوكيل الطلبات المقدمة إلى المضيفين الآخرين.
+- **حماية الشبكة الخاصة** — لا يمكن للملحقات الوصول إلى العناوين الداخلية.
+- **المصادقة مطلوبة** — يتم تشغيل الإضافات فقط للمستخدمين الذين قاموا بتسجيل الدخول، ويتم تحديد نطاق مكالمات `dbQuery` / `dbExec` تلقائيًا.
+
+## بعض الأشياء التي يجب معرفتها حول التسمية {#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) — العمليات التي يستدعيها الامتداد عبر `appAction`
+- [**Sharing & Privacy**](/docs/sharing) — كيفية عمل رؤية الإضافات ومشاركة المؤسسة والمنح لكل مستخدم
+- [**Onboarding & API Keys**](/docs/onboarding) — كيف تظهر الأسرار في الإعدادات UI
+- [**Security**](/docs/security) — نموذج نطاق البيانات والوصول إليها