Skip to content

BuilderIO/agent-native / packages/core/docs

agent-native-docs

Unverified

How 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.

FileKindSize
AGENTS.mdmarkdown6.0 KB
SKILL.mdskill md2.2 KB
content/a2a-protocol.mdxmarkdown37.6 KB
content/actions-access-control.mdxmarkdown28.9 KB
content/actions-advanced.mdxmarkdown13.1 KB
content/actions-agent-tools.mdxmarkdown5.6 KB
content/actions-defining.mdxmarkdown31.2 KB
content/actions-other-surfaces.mdxmarkdown10.3 KB
content/actions-overview.mdxmarkdown8.3 KB
content/actions-run-context.mdxmarkdown9.1 KB
content/add-ui-to-your-agent.mdxmarkdown5.0 KB
content/administered-deployments.mdxmarkdown7.7 KB
content/agent-mentions.mdxmarkdown10.2 KB
content/agent-native-config.mdxmarkdown34.9 KB
content/agent-native-toolkit.mdxmarkdown17.3 KB
content/agent-resources.mdxmarkdown27.0 KB
content/agent-surfaces.mdxmarkdown33.8 KB
content/agent-teams.mdxmarkdown13.4 KB
content/agent-web-surfaces.mdxmarkdown10.7 KB
content/agentkit.mdxmarkdown14.0 KB
content/audit-log.mdxmarkdown14.3 KB
content/authentication.mdxmarkdown30.7 KB
content/automation-connectors.mdxmarkdown7.8 KB
content/automations.mdxmarkdown26.7 KB
content/aws-amplify.mdxmarkdown10.7 KB
content/aws-lambda.mdxmarkdown13.9 KB
content/aws-rds.mdxmarkdown1.7 KB
content/azure-postgresql.mdxmarkdown1.8 KB
content/azure-static-web-apps.mdxmarkdown9.1 KB
content/blueprint-installer.mdxmarkdown6.3 KB
content/cli-adapters.mdxmarkdown5.7 KB
content/client-advanced.mdxmarkdown13.1 KB
content/client-agent-chat.mdxmarkdown17.7 KB
content/client-data.mdxmarkdown19.3 KB
content/client-entry-points.mdxmarkdown1.2 KB
content/client-overview.mdxmarkdown10.6 KB
content/client-routing.mdxmarkdown5.7 KB
content/client-sync-internals.mdxmarkdown5.2 KB
content/cloneable-saas.mdxmarkdown16.6 KB
content/cloud-sql.mdxmarkdown2.3 KB
content/cloudflare.mdxmarkdown8.3 KB
content/code-agents-ui.mdxmarkdown26.6 KB
content/components.mdxmarkdown42.9 KB
content/context-awareness.mdxmarkdown24.9 KB
content/create-with-an-agent.mdxmarkdown8.8 KB
content/creating-templates.mdxmarkdown21.6 KB
content/cross-app-connect-design.mdxmarkdown8.4 KB
content/cross-app-sso.mdxmarkdown8.7 KB
content/custom-design-system.mdxmarkdown17.3 KB
content/data-programs.mdxmarkdown25.0 KB
content/decisions.mdxmarkdown7.9 KB
content/deno-deploy.mdxmarkdown7.2 KB
content/deploy-an-app.mdxmarkdown5.0 KB
content/deployment-environment-variables.mdxmarkdown16.3 KB
content/deployment.mdxmarkdown11.3 KB
content/dispatch.mdxmarkdown18.6 KB
content/docker.mdxmarkdown8.1 KB
content/docs-components.mdxmarkdown28.9 KB
content/doctor.mdxmarkdown21.3 KB
content/drafts/clips-experimental-features.mdmarkdown5.4 KB
content/drop-in-agent.mdxmarkdown16.0 KB
content/durable-background-runs.mdxmarkdown13.8 KB
content/durable-resume.mdxmarkdown10.0 KB
content/embedding-sdk.mdxmarkdown31.3 KB
content/environment-variables.mdxmarkdown29.9 KB
content/evals.mdxmarkdown12.4 KB
content/extensions.mdxmarkdown34.8 KB
content/external-agents-catalog.mdxmarkdown40.5 KB
content/external-agents.mdxmarkdown29.3 KB
content/file-uploads.mdxmarkdown10.7 KB
content/generative-ui.mdxmarkdown10.8 KB
content/getting-started-actions.mdxmarkdown2.7 KB
content/getting-started-pages.mdxmarkdown2.6 KB
content/getting-started.mdxmarkdown7.2 KB
content/harness-agents.mdxmarkdown16.9 KB
content/http-api.mdxmarkdown20.9 KB
content/integrations.mdxmarkdown33.8 KB
content/internationalization.mdxmarkdown6.2 KB
content/key-concepts.mdxmarkdown30.6 KB
content/koyeb.mdxmarkdown7.3 KB
content/locales/ar-SA/a2a-protocol.mdxmarkdown48.5 KB
content/locales/ar-SA/actions-access-control.mdxmarkdown40.8 KB
content/locales/ar-SA/actions-advanced.mdxmarkdown16.3 KB
content/locales/ar-SA/actions-agent-tools.mdxmarkdown8.1 KB
content/locales/ar-SA/actions-defining.mdxmarkdown42.2 KB
content/locales/ar-SA/actions-other-surfaces.mdxmarkdown14.5 KB
content/locales/ar-SA/actions-overview.mdxmarkdown11.3 KB
content/locales/ar-SA/actions-run-context.mdxmarkdown11.1 KB
content/locales/ar-SA/add-ui-to-your-agent.mdxmarkdown3.7 KB
content/locales/ar-SA/administered-deployments.mdxmarkdown6.4 KB
content/locales/ar-SA/agent-mentions.mdxmarkdown11.8 KB
content/locales/ar-SA/agent-native-toolkit.mdxmarkdown17.3 KB
content/locales/ar-SA/agent-resources.mdxmarkdown36.8 KB
content/locales/ar-SA/agent-surfaces.mdxmarkdown48.4 KB
content/locales/ar-SA/agent-teams.mdxmarkdown18.5 KB
content/locales/ar-SA/agent-web-surfaces.mdxmarkdown14.3 KB
content/locales/ar-SA/audit-log.mdxmarkdown15.9 KB
content/locales/ar-SA/authentication.mdxmarkdown39.8 KB
content/locales/ar-SA/automations.mdxmarkdown31.3 KB
content/locales/ar-SA/aws-amplify.mdxmarkdown14.9 KB
content/locales/ar-SA/aws-lambda.mdxmarkdown18.9 KB
content/locales/ar-SA/aws-rds.mdxmarkdown319 B
content/locales/ar-SA/azure-postgresql.mdxmarkdown344 B
content/locales/ar-SA/azure-static-web-apps.mdxmarkdown12.4 KB
content/locales/ar-SA/blueprint-installer.mdxmarkdown8.4 KB
content/locales/ar-SA/cli-adapters.mdxmarkdown6.7 KB
content/locales/ar-SA/client-advanced.mdxmarkdown17.8 KB
content/locales/ar-SA/client-agent-chat.mdxmarkdown23.0 KB
content/locales/ar-SA/client-data.mdxmarkdown23.8 KB
content/locales/ar-SA/client-entry-points.mdxmarkdown1.6 KB
content/locales/ar-SA/client-overview.mdxmarkdown13.9 KB
content/locales/ar-SA/client-routing.mdxmarkdown7.2 KB
content/locales/ar-SA/client-sync-internals.mdxmarkdown7.3 KB
content/locales/ar-SA/cloneable-saas.mdxmarkdown23.2 KB
content/locales/ar-SA/cloud-sql.mdxmarkdown317 B
content/locales/ar-SA/cloudflare.mdxmarkdown11.9 KB
content/locales/ar-SA/code-agents-ui.mdxmarkdown34.2 KB
content/locales/ar-SA/components.mdxmarkdown51.5 KB
content/locales/ar-SA/context-awareness.mdxmarkdown33.1 KB
content/locales/ar-SA/create-with-an-agent.mdxmarkdown12.2 KB
content/locales/ar-SA/creating-templates.mdxmarkdown26.8 KB
content/locales/ar-SA/cross-app-connect-design.mdxmarkdown1.5 KB
content/locales/ar-SA/cross-app-sso.mdxmarkdown9.7 KB
content/locales/ar-SA/custom-design-system.mdxmarkdown21.6 KB
content/locales/ar-SA/data-programs.mdxmarkdown33.3 KB
content/locales/ar-SA/decisions.mdxmarkdown9.1 KB
content/locales/ar-SA/deno-deploy.mdxmarkdown10.1 KB
content/locales/ar-SA/deploy-an-app.mdxmarkdown7.1 KB
content/locales/ar-SA/deployment-environment-variables.mdxmarkdown21.3 KB
content/locales/ar-SA/deployment.mdxmarkdown13.9 KB
content/locales/ar-SA/dispatch.mdxmarkdown27.3 KB
content/locales/ar-SA/docker.mdxmarkdown11.3 KB
content/locales/ar-SA/doctor.mdxmarkdown3.4 KB
content/locales/ar-SA/drop-in-agent.mdxmarkdown20.8 KB
content/locales/ar-SA/durable-resume.mdxmarkdown15.4 KB
content/locales/ar-SA/embedding-sdk.mdxmarkdown41.3 KB
content/locales/ar-SA/evals.mdxmarkdown13.3 KB
content/locales/ar-SA/extensions.mdxmarkdown34.0 KB
content/locales/ar-SA/external-agents.mdxmarkdown89.3 KB
content/locales/ar-SA/file-uploads.mdxmarkdown13.4 KB
content/locales/ar-SA/getting-started-actions.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started-pages.mdxmarkdown3.2 KB
content/locales/ar-SA/getting-started.mdxmarkdown9.7 KB
content/locales/ar-SA/harness-agents.mdxmarkdown22.3 KB
content/locales/ar-SA/internationalization.mdxmarkdown8.2 KB
content/locales/ar-SA/key-concepts.mdxmarkdown42.0 KB
content/locales/ar-SA/koyeb.mdxmarkdown10.2 KB
content/locales/ar-SA/mcp-apps.mdxmarkdown33.7 KB
content/locales/ar-SA/mcp-clients.mdxmarkdown35.0 KB
content/locales/ar-SA/mcp-protocol.mdxmarkdown27.6 KB
content/locales/ar-SA/messaging.mdxmarkdown59.2 KB
content/locales/ar-SA/multi-app-workspace.mdxmarkdown36.2 KB
content/locales/ar-SA/multi-tenancy.mdxmarkdown7.5 KB
content/locales/ar-SA/native-chat-ui.mdxmarkdown21.3 KB
content/locales/ar-SA/neon.mdxmarkdown244 B
content/locales/ar-SA/netlify.mdxmarkdown15.2 KB
content/locales/ar-SA/node-docker.mdxmarkdown878 B
content/locales/ar-SA/node-js.mdxmarkdown8.4 KB
content/locales/ar-SA/notifications.mdxmarkdown16.2 KB
content/locales/ar-SA/observability.mdxmarkdown45.2 KB
content/locales/ar-SA/observational-memory.mdxmarkdown10.9 KB
content/locales/ar-SA/onboarding.mdxmarkdown16.9 KB
content/locales/ar-SA/organizations-teams-permissions.mdxmarkdown5.9 KB
content/locales/ar-SA/package-lifecycle.mdxmarkdown3.0 KB
content/locales/ar-SA/plan-plugin.mdxmarkdown23.0 KB
content/locales/ar-SA/portal.mdxmarkdown636 B
content/locales/ar-SA/postgres.mdxmarkdown487 B
content/locales/ar-SA/pr-visual-recap.mdxmarkdown53.9 KB
content/locales/ar-SA/privacy-and-data-rights.mdxmarkdown6.2 KB
content/locales/ar-SA/processors.mdxmarkdown8.7 KB
content/locales/ar-SA/progress.mdxmarkdown10.7 KB
content/locales/ar-SA/pure-agent-apps.mdxmarkdown5.0 KB
content/locales/ar-SA/real-time-collaboration.mdxmarkdown55.6 KB
content/locales/ar-SA/recorder.mdxmarkdown16.7 KB
content/locales/ar-SA/recurring-jobs.mdxmarkdown23.8 KB
content/locales/ar-SA/render.mdxmarkdown11.2 KB
content/locales/ar-SA/sandbox-adapters.mdxmarkdown18.0 KB
content/locales/ar-SA/security.mdxmarkdown31.5 KB
content/locales/ar-SA/server-database.mdxmarkdown27.6 KB
content/locales/ar-SA/server-middleware.mdxmarkdown7.9 KB
content/locales/ar-SA/server-overview.mdxmarkdown12.2 KB
content/locales/ar-SA/server-plugins.mdxmarkdown9.1 KB
content/locales/ar-SA/server-routes.mdxmarkdown14.3 KB
content/locales/ar-SA/sharing.mdxmarkdown28.6 KB
content/locales/ar-SA/skills-guide.mdxmarkdown27.0 KB
content/locales/ar-SA/ssr-caching.mdxmarkdown7.4 KB
content/locales/ar-SA/supabase.mdxmarkdown264 B
content/locales/ar-SA/syncing-template-changes.mdxmarkdown11.7 KB
content/locales/ar-SA/telemetry.mdxmarkdown21.9 KB
content/locales/ar-SA/template-analytics.mdxmarkdown26.4 KB
content/locales/ar-SA/template-assets.mdxmarkdown31.9 KB
content/locales/ar-SA/template-brain.mdxmarkdown29.7 KB
content/locales/ar-SA/template-calendar-agent.mdxmarkdown10.2 KB
content/locales/ar-SA/template-calendar-developers.mdxmarkdown33.4 KB
content/locales/ar-SA/template-calendar-features.mdxmarkdown14.4 KB
content/locales/ar-SA/template-calendar-integrations.mdxmarkdown6.2 KB
content/locales/ar-SA/template-calendar.mdxmarkdown4.4 KB
content/locales/ar-SA/template-chat-agent.mdxmarkdown4.7 KB
content/locales/ar-SA/template-chat-developers.mdxmarkdown31.3 KB
content/locales/ar-SA/template-chat-features.mdxmarkdown9.9 KB

content/locales/ar-SA/components.mdx

View on GitHub
---
title: "المكون API"
description: "العناصر الأساسية العامة React للوكيل المخصص UI، وحقول الدردشة، وعرض المحادثة، والتواجد في الوقت الفعلي، والمشاركة، والتقدم، والمحررين الغنيين."
---

# المكون API

يشحن Agent-Native شريطًا جانبيًا كاملاً، لكن الشريط الجانبي ليس العقد.
العقد هو وقت التشغيل: تدفق الدردشة، وحالة سلسلة المحادثات، actions، والسياق،
المرفقات واختيار النموذج وعمليات التشغيل والمزامنة المدعومة بـ SQL. استخدم المخزون
المكونات عندما تستطيع ذلك، وقم بإسقاط الطبقة عندما تحتاج إلى منتج مخصص UI.

استيراد المتصفح UI من مسارات العميل الفرعية المركزة:

```tsx
import { AgentSidebar } from "@agent-native/toolkit/app/chat";
import { PromptComposer } from "@agent-native/toolkit/app/chat/composer";
import { AgentConversation } from "@agent-native/toolkit/app/chat/conversation";
import { usePresence } from "@agent-native/core/client/collab";
import { SharedRichEditor } from "@agent-native/toolkit/editor";
import { ResourcesPanel } from "@agent-native/toolkit/app/resources";
```

تجنب استيراد مكونات UI من حزمة `@agent-native/core` العارية. استخدم
`@agent-native/core/client` أو مسار فرعي `@agent-native/core/client/*` مركّز
لذلك يختار القائمون على التجميع الإدخال الآمن للمتصفح.

استخدم `@agent-native/toolkit` للقطع القابلة لإعادة الاستخدام في بناء التطبيقات التي ليست جزءا من عقد وقت التشغيل الأساسي: عناصر UI بأسلوب shadcn، hooks المشتركة، مساعدات هيكل التطبيق البسيطة، ووحدات تركيب القوالب. يحتفظ Core بإعادة تصدير توافقية أثناء الانتقال.

يمكن للحزم القابلة لإعادة الاستخدام استيراد وحدات Toolkit مباشرة:

```tsx
import { Button } from "@agent-native/toolkit/ui/button";
import { Toaster } from "@agent-native/toolkit/ui/sonner";
import { useToast } from "@agent-native/toolkit/hooks/use-toast";
import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
```

داخل تطبيقات القوالب، فضّل adapters محلية للتطبيق حتى تتمكن الفرق من استبدال primitives مرة واحدة وتستخدم كل أسطح Toolkit المعاد استخدامها التنفيذ المحلي:

```tsx
import { Button } from "@/components/ui/button";
import { useToast } from "@/hooks/use-toast";
```

<Diagram id="doc-block-1vw6fvr" title={"المنسدلة طبقة، وليس خارج الإطار"} summary={"تحتفظ كل طبقة بنفس وقت التشغيل — الإجراءات، وحالة مؤشر الترابط، ومزامنة SQL-backed — بينما تمنحك مزيدًا من التحكم في Chrome."}>

```html
<div class="diagram-layers">
  <div class="diagram-card layer">
    <span class="diagram-pill accent">&lt;AgentSidebar&gt;</span
    ><small class="diagram-muted"
      >الشريط الجانبي بأكمله حول تطبيقك. حالة 80%.</small
    >
  </div>
  <div class="diagram-card layer l2">
    <span class="diagram-pill"
      >&lt;AgentPanel&gt; &middot; &lt;AgentChatSurface&gt;</span
    ><small class="diagram-muted"
      >اللوحة أو صفحة الدردشة في التخطيط الخاص بك.</small
    >
  </div>
  <div class="diagram-card layer l3">
    <span class="diagram-pill">&lt;AssistantChat&gt; + وقت التشغيل</span
    ><small class="diagram-muted"
      >امتلك الكروم؛ قم بتمرير BYO AgentChatRuntime بشكل اختياري.</small
    >
  </div>
  <div class="diagram-card layer l4">
    <span class="diagram-pill"
      >&lt;PromptComposer&gt; &middot; &lt;محادثة الوكيل&gt;</span
    ><small class="diagram-muted">الملحن والنسخة الأولية فقط.</small>
  </div>
  <div class="diagram-rail" data-rough>
    نفس وقت التشغيل: الإجراءات &middot; حالة الخيط &middot; BYO-backed مزامنة
  </div>
</div>
```

```css
.diagram-layers {
  display: flex;
  flex-direction: column;
  gap: 10px;
}
.diagram-layers .layer {
  display: flex;
  flex-direction: column;
  gap: 4px;
  padding: 12px 14px;
}
.diagram-layers .l2 {
  margin-inline-start: 24px;
}
.diagram-layers .l3 {
  margin-inline-start: 48px;
}
.diagram-layers .l4 {
  margin-inline-start: 72px;
}
.diagram-layers .diagram-rail {
  margin-top: 6px;
  padding: 10px 14px;
  text-align: center;
}
```

</Diagram>

## الصفحة الرئيسية للموجّه ومكتبات القوالب {#prompt-home}

تُصدَّر `PromptHome` و`PromptHomeLibrary` و`TemplateLibraryGrid` و`TemplateLibraryCard` من `@agent-native/toolkit/app-shell`. توحّد المسافات ومحررًا مركزيًا بعرض 700 بكسل ومكتبة متجاوبة من أربعة أعمدة. يحتفظ هيكل التطبيق بمعلم main. توفر التطبيقات بيانات فعلية وتسميات مترجمة ومعاينات وإجراءات وروابط.

تقبل `PromptHome` الخصائص `title` و`composer` و`children` للمكتبة، مع `mobileToolbar` و`connection` و`quickActions` الاختيارية. تستقبل `PromptHomeLibrary` قيمة `value` متحكمًا بها (`templates` أو `recent`) و`onValueChange` و`labels` و`showRecent` و`templates`، مع `recent` و`browseAll` و`recentActions` الاختيارية. عند غياب العناصر الحديثة تعرض القوالب دون تبويب صوري. يوفر التطبيق رابطًا حقيقيًا لـ `browseAll`. تضع فتحة `Tabs.headerActions` الدلالية الإجراءات النشطة بجانب التبويبات.

```tsx
import { PromptHome, PromptHomeLibrary } from "@agent-native/toolkit/app-shell";
import { Link } from "react-router";

<PromptHome
  title={labels.create}
  composer={composer}
  quickActions={quickActions}
>
  <PromptHomeLibrary
    value={tab}
    onValueChange={setTab}
    labels={labels.library}
    showRecent={hasOwnedWork}
    browseAll={<Link to="/templates">{labels.browseAll}</Link>}
    templates={templateGrid}
    recent={recentItems}
  />
</PromptHome>;
```

تقبل `TemplateLibraryGrid` عناصر `items` ذات نوع محدد تتضمن `id` و`title`، و`description` مخزّنًا و`disabled` اختياريين، مع `renderPreview`. تدعم `selectedId` و`pendingId` و`disabled` و`loading` و`error` و`onRetry` و`empty` الاختياري، و`labels` لحالات التحميل والفراغ وإعادة المحاولة. يُستخدم إما `onSelect(item, element)` أو `renderLink(item, children)`، وليس كلاهما. تشترك الصورة والتسمية في هدف تفعيل واحد. يبقى `renderActions` خارج هدف التفعيل، بجانب العنوان والوصف الاختياري في الصف نفسه. تتشارك البطاقات أبعادًا ثابتة للمعاينة والتسمية؛ يستخدم التفعيل المباشر القالب أو ينسخه، بينما تبقى المعاينة في قائمة التسمية فقط. تبقى العناصر المحمّلة ظاهرة بعد فشل التحديث. توفر `TemplateLibraryCard` السلوك نفسه لعنصر `item` واحد مع `preview` و`actions` و`selected` و`pending` و`disabled` الاختيارية.

```tsx
import { TemplateLibraryGrid } from "@agent-native/toolkit/app-shell";

<TemplateLibraryGrid
  items={templates}
  labels={labels.grid}
  renderPreview={renderTemplatePreview}
  onSelect={selectTemplate}
  selectedId={selectedId}
  pendingId={pendingId}
  loading={loading}
  error={error}
  onRetry={reloadTemplates}
/>;
```

تُصدَّر `TemplatePreviewDialog` من نقطة الدخول نفسها وتستخدم `Dialog` الدلالية بحجم `size="viewport"` افتراضيًا أو `size="large"`. تستقبل `open` و`onOpenChange` و`title` و`children` التي يرسمها التطبيق؛ لا يتضمن رأسها إجراء استخدام. تحتوي `thumbnails` الاختيارية على `{ id, title, preview, disabled? }` وتتطلب `selectedId` و`onSelectedIdChange`. يصبح شريط الصور أفقيًا على الشاشات الضيقة ويدعم الأسهم وHome وEnd.

حجم `viewport` نافذة حوار وسطية بهوامش، ارتفاعها 90dvh وعرضها الأقصى 96rem، مع هامش جانبي 1rem على الهاتف و1.5rem على الشاشات الأعرض. يحافظ على حد النافذة وزواياها وظلها وخلفيتها القياسية. تظهر قوائم التسمية عند تمرير المؤشر فوق البطاقة أو تركيز لوحة المفاتيح على الأجهزة الداعمة للتمرير، وتبقى ظاهرة على أجهزة اللمس؛ ولا تتغير المساحة المحجوزة لها.

مرّر `labels` المترجمة (`close` و`loading` و`empty` و`retry` و`thumbnails`)، مع `loading` و`error` و`empty` و`onRetry` الاختيارية لحالات جاهزية لا تتداخل. تتحكم `initialFocusRef` و`restoreFocusRef` بالتركيز. افتح العارض من قائمة التسمية بعد اكتمال إغلاقها؛ تبقى القراءة والإلغاء والتفويض والعرض المعزول الآمن مسؤولية التطبيق.

```tsx
import { TemplatePreviewDialog } from "@agent-native/toolkit/app-shell";

<TemplatePreviewDialog
  open={previewOpen}
  onOpenChange={setPreviewOpen}
  title={template.title}
  labels={labels.preview}
  loading={previewLoading}
  error={previewError}
  empty={!pages.length}
  onRetry={reloadPreview}
  restoreFocusRef={menuTriggerRef}
  thumbnails={pages.map((page) => ({
    id: page.id,
    title: page.title,
    preview: renderThumbnail(page),
  }))}
  selectedId={selectedPageId}
  onSelectedIdChange={setSelectedPageId}
>
  {renderSelectedPage(selectedPageId)}
</TemplatePreviewDialog>;
```

تتضمن أنماط Toolkit أبعاد التخطيط المشتركة. يصدر `@agent-native/toolkit/app-shell/prompt-home.css` ورقة الأنماط المخصصة. تشمل وحدة الإخراج الحالية `toolkit/app-shell` التخطيط وورقة الأنماط. يظل تحميل البيانات والتفويض والاستيراد وحالة المحرر مسؤولية التطبيق.

## الوكيل والدردشة UI {#agent-chat-ui}

| API                                  | مسار الاستيراد                         | استخدم عندما                                                                        |
| ------------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------- |
| `<AgentSidebar>`                     | `@agent-native/toolkit/app/chat`       | تريد الشريط الجانبي الكامل حول تطبيقك.                                              |
| `<AgentToggleButton>`                | `@agent-native/toolkit/app/chat`       | يمكنك عرض زر الرأس الخاص بك للشريط الجانبي.                                         |
| `<AgentPanel>`                       | `@agent-native/toolkit/app/chat`       | تريد اللوحة الكاملة في التخطيط أو المسار أو مربع الحوار أو العمود الجانبي الخاص بك. |
| `<AgentChatSurface>`                 | `@agent-native/toolkit/app/chat`       | تريد الدردشة في وضع اللوحة أو الصفحة بدون غلاف الشريط الجانبي.                      |
| `<AssistantChat>`                    | `@agent-native/toolkit/app/chat`       | تريد امتلاك Chrome المحيط مع الاحتفاظ بالمحادثة القياسية ووقت تشغيل الملحن.         |
| `<MultiTabAssistantChat>`            | `@agent-native/toolkit/app/chat`       | تريد علامات تبويب مؤشر ترابط إطار العمل بدون `AgentPanel` chrome.                   |
| `createHttpAgentChatRuntime()`       | `@agent-native/core/client/agent-chat` | لديك نقطة نهاية وكيل BYO تعمل على بث أحداث الدردشة الطبيعية.                        |
| `createOpenAIAgentsChatRuntime()`    | `@agent-native/core/client/agent-chat` | لديك ساحة بث OpenAI Agents SDK وتريد الدردشة القياسية UI حوله.                      |
| `createOpenAIResponsesChatRuntime()` | `@agent-native/core/client/agent-chat` | لديك تدفق أحداث ردود OpenAI وتريد تطبيعه في الدردشة UI.                             |
| `createAgUiChatRuntime()`            | `@agent-native/core/client/agent-chat` | لديك تدفق أحداث AG-UI وتريد تطبيعه في الدردشة UI.                                   |
| `createClaudeAgentChatRuntime()`     | `@agent-native/core/client/agent-chat` | لديك بث Claude Agent SDK وتريد تطبيعه في الدردشة UI.                                |
| `createVercelAiChatRuntime()`        | `@agent-native/core/client/agent-chat` | لديك بث Vercel AI SDK وتريد تطبيعه في الدردشة UI.                                   |
| `useChatThreads()`                   | `@agent-native/core/client/agent-chat` | تحتاج إلى قائمة سلاسل محادثات مخصصة، أو منتقي السجل، أو دردشة محددة النطاق UI.      |
| `sendToAgentChat()`                  | `@agent-native/core/client/agent-chat` | يجب أن يؤدي إجراء المنتج إلى تسليم العمل إلى دردشة الوكيل.                          |

`AgentChatRuntime` هو عقد وكيل BYO لقشرة الدردشة القياسية. تمرير
من `runtime` إلى `<AssistantChat>` عندما يتعين على وكيل خارجي تشغيل
المحادثة بينما يحتفظ Agent-Native بالملحن والنص وبطاقات الأدوات و
عرض القطعة الأصلية. الموصلات أعلاه هي سطح API؛ وقت التشغيل
يتم تدريس أشكال العقود والأحداث في
[Native واجهة الدردشة — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
إذا كنت تختار بين الوكلاء مقطوعي الرأس، والدردشة الغنية، والعربة الجانبية المضمنة، و
أشكال التطبيق الكاملة، راجع [Agent Surfaces](/docs/agent-surfaces).

لا يزال أقصر مسار مخصص سطحًا مزودًا بأسلاك مسبقًا:

```tsx
import { AgentChatSurface } from "@agent-native/toolkit/app/chat";

export default function ChatRoute() {
  return <AgentChatSurface mode="page" className="h-screen" />;
}
```

بالنسبة إلى Chrome المخصص في وقت التشغيل القياسي:

```tsx
import { AssistantChat } from "@agent-native/toolkit/app/chat";
import { useChatThreads } from "@agent-native/core/client/agent-chat";

function CustomChat({ projectSlug }: { projectSlug: string }) {
  const threads = useChatThreads(undefined, projectSlug);
  const threadId = threads.activeThreadId ?? undefined;

  return (
    <section className="grid h-full grid-cols-[260px_1fr]">
      <ThreadList
        threads={threads.threads}
        activeThreadId={threadId}
        onSelect={threads.switchThread}
      />
      <AssistantChat threadId={threadId} />
    </section>
  );
}
```

للحصول على نقطة نهاية إحضار الوكيل الخاص بك، أنشئ `AgentChatRuntime` باستخدام أحد
الموصلات أعلاه وتمريرها إلى `<AssistantChat runtime={...} />`. انظر
[Native واجهة الدردشة — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
لاستخدام الموصل، ودفق الأحداث الذي تمت تسويته، ومتى يجب الوصول إليه
`createHttpAgentChatRuntime()` مقابل موصل خاص بالبروتوكول.

## حقل الدردشة والملحن {#composer}

استخدم `@agent-native/toolkit/app/chat/composer` عندما تحتاج إلى حقل الدردشة نفسه
الذي يستخدمه الشريط الجانبي داخل UI مخصص. توفّر `@agent-native/toolkit/composer`
واجهة Tiptap ومكوّنات UI المحمولة المجردة؛ وعند استخدامها مع خدمات إطار العمل، غلّفها
بـ `ComposerRuntimeAdaptersProvider` وقدّم الخدمات. Core هو الغلاف الموصّل للمرفقات والإشارات والمهارات والصوت واختيار النموذج.

| API                               | استخدم عندما                                                                                                                                                     |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<PromptComposer>`                | تحتاج إلى حقل دردشة جاهز للإرسال يحتوي على المرفقات، وأوامر الشرطة المائلة، والمراجع، ومعالجة النص الملصق، واستمرارية المسودة، والإدخال الصوتي، ودلالات الإرسال. |
| `<AgentComposerFrame>`            | تريد الغلاف المرئي القياسي حول نص الملحن المخصص.                                                                                                                 |
| `<TiptapComposer>`                | أنت بحاجة إلى حقل الدردشة الغنية ذي المستوى الأدنى. ويجب أن يتم عرضه داخل واجهة المستخدم المساعدة `ThreadPrimitive.Root` / وقت تشغيل الملحن.                     |
| `buildPromptComposerSubmission()` | تحتاج إلى نفس المرفقات وتسوية النص الملصق قبل استدعاء معالج الإرسال الخاص بك.                                                                                    |
| `formatPromptWithAttachments()`   | تحتاج إلى عرض بيانات تعريف المرفقات المخفية في سلسلة مطالبة.                                                                                                     |

يجب أن تبدأ معظم UI المخصصة بـ `PromptComposer`:

```tsx
import { PromptComposer } from "@agent-native/toolkit/app/chat/composer";

<PromptComposer
  placeholder="Ask the agent..."
  onSubmit={async (text, files, references, options) => {
    await sendMessageToYourRuntime({ text, files, references, options });
  }}
/>;
```

استخدم `TiptapComposer` فقط إذا كنت تقوم بالفعل بتوصيل عناصر واجهة المستخدم المساعدة
نفسك. إنه الحقل، وليس وقت تشغيل الدردشة بالكامل.

### السياق المُجهّز في المحرر {#composer-context}

تقبل `PromptComposer` و`TiptapComposer` الخاصية `submissionDisabled` لمنع الإرسال مع إبقاء إعداد المسودة والملفات والسياق متاحًا. مع `requireAgentEngine`، يغلق عدم إعداد المزوّد `PromptComposer` أمام الكتابة ما دامت بطاقة الإعداد ظاهرة، وأي نقرة عليه تشير إلى البطاقة. إذا لم تكن هناك بطاقة ظاهرة، فإنه يمنع الإرسال فقط. تظل `disabled` تعطل المحرر بالكامل.

تقبل `PromptComposer` و`TiptapComposer` و`AgentKitComposer` الخاصيتين `contextItems` و`contextMenuItems`. تتولى التطبيقات قراءة المصادر وتسميات القوائم المترجمة.

يتضمن كل `AgentChatContextItem` الحقول `key` و`title` و`context`. قيمة `status` الاختيارية هي `ready` أو `pending` أو `error`. يوضح `statusMessage` سبب الفشل. تستقبل `onRemoveContextItem` و`onInspectContextItem` و`onRetryContextItem` مفتاح العنصر. تخفي `removable: false` الإزالة. تمنع العناصر المعلقة أو الفاشلة الإرسال ما لم تجعلها `blocksSubmission: false` معلوماتية صراحةً.

يمكن للمضيف تجهيز سياق مصرح بالوصول إليه واستلام لقطة ثابتة عند الإرسال:

```tsx
<PromptComposer
  contextItems={contextItems}
  onRemoveContextItem={removeContext}
  onSubmit={(text, files, references, options) =>
    submitPrompt({
      text,
      files,
      references,
      contextItems: options.contextItems,
    })
  }
/>
```

تسجّل مصادر السياق إجراءات مباشرة ذات أسماء واضحة في `ComposerContextMenuItem`. تعرض القائمة المشتركة إضافة سياق والتكاملات والأوامر كمجموعات منفصلة ميسّرة الوصول. يفتح اختيار واحد حوار تحديد المصدر. تظهر تكاملات مساحة العمل في مجموعتها، وتحتوي الأوامر على أنماط المهام قليلة الاستخدام. تُحمّل البيانات داخل الحوارات وتبقى صفوف القائمة الرئيسية ثابتة. تدعم القائمة الأسهم والبحث بالكتابة وEscape. تدير الحوارات البحث والنتائج المجمعة والتحميل والحالات الفارغة والأخطاء وإعادة المحاولة واستعادة التركيز.

تستخدم المساهمات `section: "context" | "integrations" | "commands"` و`order` تصاعديًا، ثم التسمية وid عند التعادل. يحافظ `renderLink(children)` على التنقل الأصلي للروابط. يمكن للتطبيقات ذات موفر إشارات محدود النطاق تسجيل `referencePicker: { source, referenceType }`. يُدرج الاختيار مرجعًا عاديًا في المحرر. يستبعد `referenceType` أنواع الموارد الخاصة بالتطبيق من حوار البحث المشترك في مساحة العمل لمنع التكرار. تُسجّل مساحة العمل عبر `resources.useWorkspaceMenu({ enabled, onSelectIntegration })`. يعيد `scopeKey` تعيين المحددات ويلغي الطلبات عند تغير الهوية. تبقى حالات فشل الموفر أخطاء ولا تتحول إلى نتائج فارغة.

يبقى مصدر مثل Figma ظاهرًا أثناء التحقق من الوصول. يعرض حواره التحميل أو خطأ مع إعادة المحاولة، ورابط اتصال حقيقيًا عند عدم الاتصال أو محدد URL المصرح به عند الاتصال. يختار إنشاء مهارة وضع المهارة مباشرةً. يفتح رفع ملف مهارة حوار مراجعة وحفظ بعد محدد الملفات الأصلي.

تقبل تهيئة المنتقي ما يلي:

- `searchPlaceholder` و`emptyMessage` الاختياري كنصوص مترجمة للتطبيق. تحدد `selectedIds` الصفوف المختارة. تتضمن العناصر `id` و`title` وحقلي `disabled` و`url` الاختياريين.
- إما `items` محلية مع `loading` و`error` و`onRetry()` اختيارية، أو `load(request)` للتحميل عن بُعد. لا يمكن الجمع بين النمطين.
- تستقبل `load(request)` كلًا من `search` و`page` التي تبدأ من واحد و`cursor` و`url` الاختياريين و`AbortSignal`. وتعيد `{ items, hasMore?, nextCursor? }`. يجب أن ترفض حالات الفشل الوعد بدلًا من إعادة نتيجة فارغة.
- تجهّز `onSelect(item, request)` المصدر ويمكن أن تعمل بشكل غير متزامن. تبقي إعادة `false` المنتقي مفتوحًا. يؤدي رمي خطأ إلى عرض خطأ مع إعادة المحاولة. توفّر `clearSelection` الاختيارية `label` مترجمًا ودالة `onSelect()`.
- توفّر `link` الاختيارية نصّي `placeholder` و`submitLabel` المترجمين. يمكن أن تعيد `validate(url)` رسالة خطأ. يتولى النموذج المشترك إدخال الرابط والتنقل.
- تعيد `scopeKey` ضبط جميع حالات المنتقي عند تغيّر الهوية أو نطاق الوصول. تبطل `refreshKey` الاستعلام الحالي عند تغيّر رمز المصدر أو الإصدار دون إعادة ضبط الرابط. يعيد تغيّر البحث الانتقال إلى الصفحة الأولى. تمرّر التطبيقات رموزًا محدثة عندما تغيّر كتابات الوكيل بيانات المصدر.

يمكن للتطبيق تسجيل خيارات مصرح بها مسبقًا. تحتوي `labels` هنا على نصوص التطبيق المترجمة، وتحدّث `stageReference` السياق المجهّز لدى المضيف:

```tsx
import type { ComposerContextMenuItem } from "@agent-native/toolkit/app/chat/composer";
import { Link } from "react-router";

const contextMenuItems: ComposerContextMenuItem[] = [
  {
    id: "references",
    label: labels.references,
    picker: {
      searchPlaceholder: labels.searchReferences,
      presentation: { type: "dialog", mode: "single" },
      items: authorizedReferences,
      selectedIds,
      onSelect: stageReference,
      footerAction: {
        label: labels.createReference,
        renderLink: (children) => (
          <Link to={createReferenceHref}>{children}</Link>
        ),
      },
    },
  },
];
```

لمصدر قابل للبحث أو يعتمد على رابط، يوفّر التطبيق دالة تحميل مصادقًا عليها. تطبّق `loadAuthorizedReferences` عقد الطلب والنتيجة أعلاه، وتحافظ على فحوص الوصول، وتمرّر إشارة الإلغاء إلى دالة العميل المساعدة:

```tsx
const contextMenuItems: ComposerContextMenuItem[] = [
  {
    id: "references",
    label: labels.references,
    picker: {
      searchPlaceholder: labels.searchReferences,
      scopeKey: accessScope,
      refreshKey: sourceVersion,
      load: loadAuthorizedReferences,
      presentation: {
        type: "dialog",
        mode: "multiple",
        onAttach: stageReferences,
      },
      link: {
        label: labels.referenceUrl,
        placeholder: labels.referenceLink,
        submitLabel: labels.findReferences,
        validate: validateReferenceLink,
      },
    },
  },
];
```

القيمة الافتراضية لـ `presentation` هي `"submenu"`. مع `{ type: "dialog", mode: "multiple", onAttach }`، يفتح عنصر قائمة عادي حوارًا مشتركًا بعنوان العنصر. يحدد `link.label` تسمية حقل URL. يتحقق زر المتابعة من عنوان HTTP(S) بلا بيانات اعتماد قبل تحميل النتائج. لا يستدعي الإدخال الفارغ أو غير الصالح المزوّد. يمكن لـ `link.validate()` فرض قواعد خاصة بالمزوّد. تستخدم أزرار الحوار تسميات مشتركة مترجمة، وليس `link.submitLabel`.

تستقبل `presentation.onAttach(items, request)` دفعة مجمّدة واحدة من العناصر المحددة حديثًا. لا يسمح هذا الوضع بـ `onSelect`. تُحفظ الاختيارات أثناء البحث والتنقل بين الصفحات، وتظهر عناصر `selectedIds` محددة ومعطّلة وتُستبعد من الدفعة. يجب أن تميّز المعرّفات بين ملفات المصادر المختلفة. يبقي إرجاع `false` الحوار مفتوحًا. يعرض الرفض خطأً مع إمكانية إعادة المحاولة. يؤدي الإلغاء أو تغيير `scopeKey` إلى إلغاء العمل المعلّق وتجاهل النتائج المتأخرة. تبدأ إعادة الفتح بعنوان URL جديد. يجب على المضيف مراعاة `request.signal` قبل تثبيت تغييرات الاستدعاءات غير المتزامنة. يبقى `footerAction` و`clearSelection` ضمن عناصر تحكم القائمة الفرعية.

يستخدم `{ type: "dialog", mode: "url" }` الإرفاق مباشرةً دون تحميل قائمة نتائج. تستقبل `onSelect(item, request)` القيمة `{ id: url, title: url, url }` و`request.url`:

```tsx
const websiteContextItem: ComposerContextMenuItem = {
  id: "website",
  label: labels.attachWebsite,
  picker: {
    searchPlaceholder: labels.searchReferences,
    scopeKey: accessScope,
    presentation: { type: "dialog", mode: "url" },
    link: {
      label: labels.websiteUrl,
      placeholder: labels.websiteUrl,
      submitLabel: labels.attach,
      validate: validateWebsiteUrl,
    },
    onSelect: stageWebsiteReference,
  },
};
```

تبني `readComposerWebsiteSource(url, extractCallback)` من `@agent-native/core/server` مراجع المواقع عبر مستخرج المضيف الحالي المحمي من SSRF. تقبل `composerSourceRequestSchema` من `@agent-native/core/shared` القيمة `source: "website"` فقط مع `operation: "read"` وعنوان `url` ببروتوكول HTTP(S) بلا بيانات اعتماد، بطول أقصاه 2,048 محرفًا. تعيد الدالة `{ id, title, url, context }` بمعرّف ثابت مشتق من تجزئة العنوان وسياق لا يتجاوز 20,000 محرف. تبقى حالة الاستخراج والتحذيرات وبيانات التصيير وأي علامة `[truncated]` ضمن نص السياق. يظل الاستخراج الجزئي واضحًا. يؤدي فشل الاستخراج أو غياب `designMd` صالح للاستخدام إلى خطأ ذي نوع محدد. يبقى التفويض مسؤولية [إجراء](/docs/actions-overview) المضيف.

لا تعرّف عناصر المنتقي أيضًا `render` أو `onSelect` على مستوى العنصر. تستخدم الفئات `children`. تحتفظ القائمة الرئيسية وكل فئة بحقل بحث في رأسها. يمكن للفئات توفير `searchPlaceholder` مترجم؛ وإلا تستخدم النص المشترك للبحث في السياق. يحدد `picker.searchPlaceholder` نص حقل البحث في قائمة المصادر. لا يمنح التسجيل وصولًا إلى المصدر. يتجاهل المنتقي المشترك استجابات التحميل التي حلّت محلها طلبات أحدث.

يبقى `footerAction` الاختياري أسفل النتائج حتى أثناء التحميل أو الخطأ أو فراغ القائمة. يقبل `label` مترجمًا و`icon` و`disabled` اختياريين، وإما `onSelect()` أو `renderLink(children)`. استخدم دالة لفتح نافذة حوار أو مسار آخر ذي حالة: تُبقي `false` القائمة مفتوحة، وتغلقها `true` أو `void`، ويعرض رفض الوعد خطأ مع إعادة المحاولة. للتنقل فقط، أعد من `renderLink` عنصر `Link` حقيقيًا من React Router أو رابط HTML؛ توفّر القائمة المشتركة الصف عبر `asChild` وتحافظ على `href` وسلوك تنقل المتصفح. اربط مسارات موجودة ومصرحًا بها، لا إجراءات شكلية.

تؤدي إضافة `addAttachment` إلى `ComposerContextMenu` إلى إضافة ملفات وصور في قسم المرفقات مع الحفاظ على دالة معالجة ملفات المضيف.

تقبل `PromptComposer` و`AgentKitComposer` الخاصية `attachmentAdapter` بالنوع العام `AttachmentAdapter` من `@assistant-ui/react`. قدّم عبر هذا المحوّل سياسة المضيف لقبول الملفات والتحقق من الحجم وتجهيز المرفقات؛ واحذفه للإبقاء على المحوّلات الافتراضية. يظل المحرر المشترك مسؤولًا عن أداة الرفع ومنتقي الملفات ومنتقي السياق وشرائح المرفقات. لا تستبدل هذه الأدوات لتخصيص تجهيز الملفات.

تكون `inlineTextAttachments` مساوية لـ`true` افتراضيًا في `PromptComposer` و`AgentKitComposer`. اضبطها على `false` عندما يستخرج المضيف الملفات النصية العادية بالفعل: يمرّر المحرر الملفات الأصلية إلى المضيف دون قراءة محتواها وإلحاقه بالطلب النصي. تظل المرفقات المصطنعة الناتجة عن النص الملصق جزءًا من نص الطلب. لا يغيّر هذا الخيار قبول المرفقات أو الأدوات المشتركة.

```tsx
<PromptComposer
  contextItems={contextItems}
  contextMenuItems={contextMenuItems}
  attachmentAdapter={hostAttachmentAdapter}
  onRetryContextItem={retryContext}
  onSubmit={submitPrompt}
/>
```

تميّز اللقطة بين `undefined` والمصفوفة الفارغة الصريحة. ترفض أكثر من 32 عنصرًا أو 64 KiB من بيانات UTF-8 المسلسلة دون اقتطاع. يُنتظر `AgentKitComposer.beforeSend(submission)` قبل الإرسال أو الإدراج في الطابور، ويتلقى السياق والمراجع والمرفقات المرفوعة وخيارات التشغيل الثابتة. يحافظ الرفض على المسودة. يُدرج السياق في نص الرسالة وبياناتها الوصفية.

تستخدم `composerRef.current.submitWithText(text)` مسار الإرسال نفسه بالملفات وإعدادات النموذج الحالية دون استبدال نص المحرر أولًا. تُرجع `true` بعد القبول أو `false` عند المنع أو الرفض. اختيار السياق ليس منحًا للوصول. يجب أن تعيد التطبيقات التحقق من وصول المصادر عبر إجراءاتها الموثقة.

## عرض المحادثة {#conversation}

استخدم `@agent-native/toolkit/app/chat/conversation` لعرض نمط النص
خارج وقت تشغيل الوكيل الكامل.

| API                                             | استخدم عندما                                             |
| ----------------------------------------------- | -------------------------------------------------------- |
| `<AgentConversation>`                           | عرض قائمة برسائل الوكيل التي تمت تسويتها.                |
| `<AgentConversationMessageView>`                | عرض رسالة واحدة تمت تسويتها.                             |
| `normalizeCodeAgentTranscriptForConversation()` | تحويل أحداث نص وكيل التعليمات البرمجية إلى رسائل محادثة. |

تعتمد هذه الطبقة على البيانات أولاً عمدًا: فأنت تملك المكان الذي تأتي منه الرسائل، و
يمتلك العارض تخفيضًا ثابتًا، ومرفقات، وإشعارات، وعناصر، و
عرض استدعاء الأداة.

## أدوات الأدوات الأصلية {#native-tool-widgets}

استخدم عناصر واجهة المستخدم للأداة الأصلية عندما يجب عرض نتيجة الإجراء بجودة التطبيق UI
داخل الدردشة بدلاً من JSON العادي. تتضمن المخرجات المدمجة القابلة لإعادة الاستخدام
`DataTableWidget`، و`DataChartWidget`، و`DataWidgetResult`؛ يتم تصديرها
من `@agent-native/core/client/widgets` وإدخال العميل الجذر. انظر
[Native واجهة الدردشة](/docs/native-chat-ui) لعقد نتيجة الإجراء.

| API                              | استخدم عندما                                                                     |
| -------------------------------- | -------------------------------------------------------------------------------- |
| `DataTableWidget`                | تريد نتيجة إجراء لعرض الصفوف والأعمدة في الدردشة الأصلية.                        |
| `DataChartWidget`                | تريد إخراج مخطط شريطي مضغوط أو خطي أو مخطط مساحي في الدردشة الأصلية.             |
| `DataWidgetResult`               | تريد شكل نتيجة مكتوبًا لـ `"data-table"` أو `"data-chart"` أو `"data-insights"`. |
| `registerActionChatRenderer()`   | تحتاج إلى عارض معلن عن الإجراء محدد بواسطة `chatUI.renderer` بالضبط.             |
| `registerToolRenderer()`         | أنت بحاجة إلى عارض أصلي خاص بالمنتج للحصول على نتيجة أداة غير أساسية.            |
| `registerReservedToolRenderer()` | يحتاج كود إطار العمل إلى عارض محجوز يفوز قبل عارضي القوالب.                      |

## التعاون والتواجد في الوقت الفعلي {#collab-presence}

استخدم `@agent-native/core/client/collab` للتواجد بنمط Liveblocks و
ربط المستندات التعاونية.

| API                                                 | استخدم عندما                                                               |
| --------------------------------------------------- | -------------------------------------------------------------------------- |
| `useCollaborativeDoc()`                             | اربط محرر نص منسق أو سطح Yjs مخصص بـ `/_agent-native/collab`.              |
| `usePresence()`                                     | نشر وعرض حقول الوعي العشوائية: المؤشرات، التحديدات، إطار العرض، الوضع.     |
| `<PresenceBar>`                                     | إظهار المتعاونين البشريين والوكلاء النشطين.                                |
| `<LiveCursorOverlay>`                               | عرض تسميات المؤشر عن بعد فوق حاوية موضوعة.                                 |
| `<RemoteSelectionRings>`                            | عرض الخطوط العريضة للاختيار عن بعد عبر عناصر DOM.                          |
| `useFollowUser()`                                   | اتبع إطار العرض أو التحديد لمشارك آخر.                                     |
| `useCollaborativeMap()` / `useCollaborativeArray()` | جرّب حالة Y.Map/Y.Array المنظمة عندما يكون تعاون نص النص المنسق غير مناسب. |
| `dedupeCollabUsersByEmail()`                        | إنشاء مجموعة صور رمزية مخصصة بدون علامات تبويب مكررة لنفس المستخدم.        |

<Diagram id="doc-block-dhg14q" title={"الحضور: يتشارك البشر والوكيل في طبقة وعي واحدة"} summary={"useCollaborativeDoc يمتلك مثيل الوعي؛ تقوم خطافات العميل بنشر المؤشرات والتحديدات؛ يسمح مساعدو الخادم بإجراء الوكيل بالظهور كمشارك مباشر."}>

```html
<div class="diagram-presence">
  <div class="diagram-col">
    <div class="diagram-node">
      البشر<br /><small class="diagram-muted"
        >usePresence &middot; المؤشرات، الاختيار</small
      >
    </div>
    <div class="diagram-node diagram-accent">
      عمل الوكيل<br /><small class="diagram-muted">وكيلUpdateSelection()</small>
    </div>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-panel center" data-rough>
    <span class="diagram-pill accent">useCollaborativeDoc</span
    ><small class="diagram-muted">طبقة الوعي</small>
  </div>
  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
  <div class="diagram-box">
    &lt;شريط الوجود&gt; &middot; &lt;LiveCursorOverlay&gt;<br /><small
      class="diagram-muted"
      >تقديم الجميع، بما في ذلك الوكيل</small
    >
  </div>
</div>
```

```css
.diagram-presence {
  display: flex;
  align-items: center;
  gap: 12px;
  flex-wrap: wrap;
}
.diagram-presence .diagram-col {
  display: flex;
  flex-direction: column;
  gap: 10px;
}
.diagram-presence .center {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
  padding: 14px;
}
.diagram-presence .diagram-arrow {
  font-size: 22px;
  line-height: 1;
}
```

</Diagram>

يستخدم الوكيل من جانب الخادم actions الذي يريد الظهور كمشارك مباشر
مساعدو حضور الوكيل `@agent-native/core/collab` ذو المستوى الأدنى:

```ts
import {
  agentEnterDocument,
  agentLeaveDocument,
  agentUpdateSelection,
} from "@agent-native/core/collab";
```

## محرر منسق {#rich-editor}

استخدم `@agent-native/toolkit/editor` عندما تحتاج إلى محرر Markdown المشترك
السطح الذي تستخدمه الخطط والمحتوى والموارد والمستندات التعاونية
التجارب.

| API                              | استخدم عندما                                                                                    |
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
| `<SharedRichEditor>`             | أنت بحاجة إلى المحرر الحالي القابل للتكوين مع تسلسل Markdown، وYjs الاختيارية، وإضافات التطبيق. |
| `<RichMarkdownEditor>`           | أنت بحاجة إلى الاسم المستعار المتوافق مع الإصدارات السابقة للمحرر الغني المشترك.                |
| `createSharedEditorExtensions()` | أنت تقوم بإنشاء محرر Tiptap الخاص بك ولكنك تريد مخطط إطار العمل ولهجات Markdown.                |
| `<SlashCommandMenu>`             | تحتاج إلى أمر الشرطة المائلة المشترك UI لسطح Tiptap مخصص.                                       |
| `<BubbleToolbar>`                | تحتاج إلى شريط أدوات التحديد المشترك للعلامات والروابط وactions المضمنة المخصصة.                |
| `createRegistryBlockNode()`      | تحتاج إلى عقد كتلة مدعومة بالتسجيل داخل محرر غني.                                               |
| `uploadEditorImage()`            | تريد إجراء تحميل صورة إطار العمل خلف كتلة الصور المشتركة للمحرر.                                |
| `useCollabReconcile()`           | أنت تقوم بربط سطح محرر مخصص بمستند Yjs مع الحفاظ على Markdown كحالة محفوظة.                     |

المحرر الأساسي الذي يتم التحكم فيه هو مجرد تخفيض للداخل وتخفيض للخارج:

```tsx
import { SharedRichEditor } from "@agent-native/toolkit/editor";

<SharedRichEditor
  value={markdown}
  onChange={setMarkdown}
  placeholder="Write notes..."
  features={{ tables: true, tasks: true, link: true }}
/>;
```

للتحرير في الوقت الفعلي، قم بإقرانه بمسار التعاون الفرعي:

```tsx
import {
  emailToColor,
  useCollaborativeDoc,
} from "@agent-native/core/client/collab";
import { SharedRichEditor } from "@agent-native/toolkit/editor";

const editorUser = {
  name: user.name,
  email: user.email,
  color: emailToColor(user.email),
};
const collab = useCollaborativeDoc({
  docId,
  user: editorUser,
});

<SharedRichEditor
  value={markdown}
  onChange={setMarkdown}
  ydoc={collab.ydoc}
  awareness={collab.awareness}
  user={editorUser}
/>;
```

## موارد مساحة العمل {#resources}

استخدم `@agent-native/core/client/resources` عندما تريد الكشف عن نفسه
نموذج مورد مساحة العمل الذي يعمل على تشغيل علامة تبويب مساحة العمل في لوحة الوكيل.

| API                                                                   | استخدم عندما                                                            |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `<ResourcesPanel>`                                                    | تريد علامة تبويب مساحة العمل الكاملة كصفحة أو درج أو لوحة مخصصة.        |
| `<ResourceTree>`                                                      | تريد عرض متصفح الموارد الخاص بك حول بيانات إطار العمل.                  |
| `<ResourceEditor>`                                                    | تريد محرر إطار العمل لمورد محدد.                                        |
| `useResourceTree()`                                                   | تحتاج إلى شجرة محددة النطاق للموارد الشخصية أو المشتركة أو مساحة العمل. |
| `useResource()`                                                       | أنت بحاجة إلى المحتوى والبيانات الوصفية لمورد واحد محدد.                |
| `useCreateResource()` / `useUpdateResource()` / `useDeleteResource()` | تحتاج إلى عناصر تحكم مخصصة حول دورة حياة المورد.                        |
| `useUploadResource()`                                                 | تحتاج إلى تحميل الملف إلى مخزن موارد إطار العمل.                        |

لا تحتاج اللوحة الكاملة إلى أي دعائم:

```tsx
import { ResourcesPanel } from "@agent-native/toolkit/app/resources";

<ResourcesPanel />;
```

بالنسبة لمورد Chrome المخصص، احتفظ بالخطافات والعناصر الأولية معًا:

```tsx
import { useState } from "react";
import {
  ResourceEditor,
  ResourceTree,
} from "@agent-native/toolkit/app/resources";
import {
  useResource,
  useResourceTree,
  useUpdateResource,
} from "@agent-native/core/client/resources";

function WorkspaceResources() {
  const tree = useResourceTree("workspace");
  const updateResource = useUpdateResource();
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const resource = useResource(selectedId);

  return (
    <div className="grid h-full grid-cols-[260px_1fr]">
      <ResourceTree
        tree={tree.data ?? []}
        selectedId={selectedId}
        onSelect={(item) => setSelectedId(item.id)}
        onCreateFile={() => {}}
        onCreateFolder={() => {}}
        onDelete={() => {}}
        onRename={() => {}}
        onDrop={() => {}}
      />
      {resource.data ? (
        <ResourceEditor
          resource={resource.data}
          saveContent={(attempt) => updateResource.mutateAsync(attempt)}
        />
      ) : null}
    </div>
  );
}
```

## UI عامة أخرى {#other-ui}

| المساحة         | APIs                                                       | مسار الاستيراد                                                              |
| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| المشاركة        | `<ShareButton>`, `<ShareDialog>`                           | `@agent-native/toolkit/app/sharing`                                         |
| Sharing UI      | `<VisibilityBadge>`                                        | `@agent-native/toolkit/sharing`                                             |
| الإشعارات       | `<NotificationsBell>`                                      | `@agent-native/toolkit/app/notifications`                                   |
| سجل التشغيل     | `<RunsTray>`، أنواع التشغيل ووظائف سجل التشغيل على الخادم  | `@agent-native/toolkit/app/progress + @agent-native/core/progress`          |
| التأهيل         | `useOnboarding()`، خطافات لوحة التثبيت                     | `@agent-native/core/client/onboarding`                                      |
| قابلية الملاحظة | `<ObservabilityDashboard>`, `<ThumbsFeedback>`             | `@agent-native/toolkit/app/observability`                                   |
| الموارد         | `<ResourcesPanel>`، `<ResourceTree>`، ربط الموارد          | `@agent-native/toolkit/app/resources + @agent-native/core/client/resources` |
| محرر غني        | `<SharedRichEditor>`، أوامر الشرطة المائلة، ربط عقدة الحظر | `@agent-native/toolkit/editor`                                              |

## إكمال النص لمرة واحدة {#one-off-text-completion}

إذا كنت تحتاج حقًا إلى نص خام/نص خارج، فاحتفظ به من جانب الخادم واستخدمه
`completeText()` من `@agent-native/core/server`. لف الاستخدام الذي يواجه المستخدم في
إجراء بحيث يتشارك UI والوكيل في نفس الإمكانية.

<Callout id="doc-block-11d6llv" tone="warning">

`completeText()` is the escape hatch, not the default. Reach for it only for true text-in/text-out (a label, a one-line rewrite). Anything needing tools, state, auditability, or steering belongs in an action plus `sendToAgentChat({ background: true })`.

</Callout>

```ts
import { defineAction } from "@agent-native/core/action";
import { completeText } from "@agent-native/core/server";
import { z } from "zod";

export default defineAction({
  description: "Classify a short message",
  schema: z.object({ body: z.string() }),
  run: async ({ body }) => {
    const result = await completeText({
      systemPrompt: "Return exactly one label.",
      input: body,
      maxOutputTokens: 12,
      temperature: 0,
    });
    return { label: result.text.trim() };
  },
});
```

استخدم `sendToAgentChat({ background: true, openSidebar: false })` بدلاً من ذلك عندما
يحتاج العمل إلى أدوات، أو حالة، أو إمكانية التدقيق، أو توجيه المستخدم، أو الخطوات المتعددة
الاستدلال.

## ما التالي {#whats-next}

- [**Drop-in Agent**](/docs/drop-in-agent) — ثبّت `<AgentSidebar>` و`<AgentPanel>` مع شرح إرشادي يبدأ بالبرنامج التعليمي
- [**Native Chat UI**](/docs/native-chat-ui) — عقد نتيجة الإجراء وراء عناصر واجهة البيانات وأدوات العرض المخصصة
- [**Actions**](/docs/actions-overview) — ‏`defineAction()` والمخططات وسطح الإجراءات الذي تستدعيه هذه المكونات
- [**Real-Time Collaboration**](/docs/real-time-collaboration) — تفاصيل ربط التعاون ومكونات الحضور
- [**Sharing**](/docs/sharing) — توصيل `<ShareButton>` و`<ShareDialog>` للموارد القابلة للامتلاك

## سجل المحادثات

يتيح شريط المحادثات المملوكة `useOwnershipChatHistory()` و`OwnershipChatHistoryRail` من `@agent-native/toolkit/app/chat/ownership-history` مع أقسام منفصلة للمحادثات المملوكة والمشتركة.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall