المساعد المضمن

هذه الصفحة مترجمة من الإنجليزية. اقرأ الصفحة الإنجليزية

الحالة: منفذ خلف ميزة Cargo المسماة assistant في zeyn.

يمكن أن يحمل تطبيق Zeyn مساعده الذكي الخاص: محادثة في كل صفحة تجيب ببيانات التطبيق وتعمل على شاشاته وواجهاته البرمجية (APIs) بصفة المستخدم المسجل الدخول. تستطيع التطبيقات المبنية بـ Zeyn تفعيله لعملائها، وربط النموذج الذي يريده هؤلاء العملاء، وحفظ سجل المحادثات حيث يحتاجون.

zeyn = { version = "0.0.2", features = ["assistant"] }

بدون الميزة لا يُصرَّف شيء منه: لا عميل HTTP ولا مسارات إضافية ولا ذاكرة إضافية.

1. الإعداد

use zeyn::assistant::{Assistant, OpenAiCompatible};

let model = OpenAiCompatible::new(config.require("assistant.base_url")?, config.require("assistant.model")?)
    .api_key(config.secret("assistant.api_key")?);

App::new("Lifts")
    .assistant(
        Assistant::new(model)
            .permission("lifts.assistant.use")
            .instructions("You help service engineers plan elevator maintenance.")
            .suggest(work_orders, "Which lifts are overdue for service?")
            .suggest_anywhere("What can you do?"),
    )

هذا كل شيء. تحصل كل صفحة على زر عائم يفتح المحادثة في لوحة جانبية. ويمكن لشاشة أن تعرض المحادثة بنفسها:

#[screen(route = "/assistant", permission = "lifts.assistant.use", ai = false)]
pub fn assistant_page() -> Screen {
    Screen::new("Assistant").body(AssistantChat::page())
}

AssistantChat::panel() يناسب الوضع بجوار محتوى آخر. وAssistant::launcher(false) يُسقط الزر العائم، فتظهر المحادثة حيث تضعها الشاشة فقط.

2. النماذج

يعمل أي نوع ينفّذ LlmProvider: دالة واحدة تبدأ جولة متدفقة وتعيد قناة محدودة من ChatEvent (قطع نصية واستدعاءات أدوات واستهلاك). المدمج منها:

تأتي المفاتيح من قيم Secret (Config::secret)، وتبقى على الخادم ولا تظهر أبداً في رسائل الخطأ. تُسجَّل أخطاء المزوّد على الخادم؛ ويرى المستخدم رسالة عامة.

توجيه showcase إلى نموذج حقيقي لا يتطلب إلا الإعداد:

NORTHWIND_ASSISTANT__PROVIDER=openai
NORTHWIND_ASSISTANT__BASE_URL=https://api.openai.com/v1
NORTHWIND_ASSISTANT__MODEL=gpt-4.1-mini
NORTHWIND_ASSISTANT__API_KEY=...

أو NORTHWIND_ASSISTANT__PROVIDER=anthropic مع NORTHWIND_ASSISTANT__MODEL=claude-opus-5-5، أو عنوان Ollama دون مفتاح. وNORTHWIND_ASSISTANT__PROVIDER=off يعطّله.

3. الكلام

افتراضياً يستخدم الميكروفون التعرف على الكلام في المتصفح، وتستخدم "القراءة بصوت عالٍ" تركيب الكلام في المتصفح: بلا كلفة على الخادم، ولا يغادر أي صوت المتصفح نحو التطبيق. أما للكلام عبر الخادم:

Assistant::new(model)
    .speech_to_text(OpenAiTranscription::new(base, "whisper-1").api_key(key.clone()))
    .text_to_speech(OpenAiSpeech::new(base, "tts-1", "alloy").api_key(key))

كلاهما يتحدث نقطتي النهاية /audio/transcriptions و/audio/speech المتوافقتين مع OpenAI، وهما ما تقدمه أيضاً خوادم Whisper والكلام المحلية. التسجيلات محدودة (4 ميغابايت و60 ثانية في المتصفح)؛ وصوت الكلام يتدفق إلى المتصفح فور وصوله.

4. السجل

يحفظ ChatStore المحادثات بمفتاح المستأجر والمستخدم (ChatKey)، فلا يتشارك مستأجران محادثة واحدة أبداً:

pub trait ChatStore: Send + Sync + 'static {
    fn load(&self, key: &ChatKey, limit: usize) -> BoxFuture<Result<Vec<ChatMessage>>>;
    fn append(&self, key: &ChatKey, messages: Vec<ChatMessage>) -> BoxFuture<Result<()>>;
    fn clear(&self, key: &ChatKey) -> BoxFuture<Result<()>>;
}

MemoryChatStore::new(max_users, max_messages) هو الافتراضي (1,000 محادثة من 60 رسالة، يخرج الأقل استخداماً مؤخراً أولاً، ويضيع عند إعادة التشغيل). لقاعدة بيانات، نفّذ الدوال الثلاث على جدول فيه المستأجر والمستخدم والموضع والرسالة بصيغة JSON. الرسائل للإضافة فقط؛ والمخزن هو من يقرر مدة الاحتفاظ. وتعيش التأكيدات المعلقة في السجل أيضاً، فلا يحتفظ الخادم بأي حالة أخرى لكل مستخدم.

5. الأدوات والإجراءات

يرى النموذج الأدوات نفسها التي يراها MCP وWebMCP (انظر docs/runtime-protocol.md القسم 9)، وتُبنى للمستخدم المسجل الدخول في كل مرة: عمليات بحث الشبكات وحفظ النماذج وإجراءات API التي يحق للمستخدم استخدامها، مطروحاً منها كل ما وُسم بـ ai = false، مع أوصاف من تعليقات /// وإرشادات ai = "...". وتُضاف أداتان مدمجتان:

• navigate: يفتح شاشة ذات مسار يحق للمستخدم فتحها، دون تحميل صفحة (zeyn:navigate)، ويستطيع ترشيح شبكتها (zeyn:filter). ثم تُحمَّل الشبكة عبر POST /_zeyn/grid، حيث يطبق الخادم فحوصه المعتادة.
• suggest: مطالبات متابعة تُعرض رقائق.

يمر كل استدعاء عبر مسار الإجراء العادي مع سياق موسوم بأنه وكيل (agent): وصول الشاشة، وحراس الميزة (Feature)، وصلاحية الإجراء، والمعترضات، وحدود المعدل، وحد الوقت، والتدقيق (يُسجَّل كل استدعاء من المساعد مع via_agent: true)، والتقنيع.

التأكيد. تعمل القراءات فوراً. أما أي شيء يكتب (حفظ النماذج، وإجراءات API التي مدخلها ليس DataQuery) وكل إجراء موسوم بـ #[action(confirm)] فيوقف الجولة ويعرض بطاقة تأكيد فيها ما سيُشغَّل ووسائطه. لا يشغّله إلا نقر المستخدم (POST /_zeyn/assistant/confirm، مع CSRF، لاستدعاء معلق في سجل ذلك المستخدم نفسه)، ومرة واحدة. رسالة مثل "I confirm" مجرد نص: الرسالة الجديدة تغلق الاستدعاء المعلق على أنه لم يُشغَّل.

6. نموذج الأمان

ما لا تفعله: الحكم بصحة إجابة النموذج. أخبر المستخدمين بذلك (واللوحة تفعل)، وأبقِ الإجراءات المهمة خلف confirm.

7. التضمين للعملاء

التطبيق الذي يبيع المساعد لعملائه يريد عادة:

• permission("app.assistant.use") وفحص وحدة الترخيص في حارس، حتى لا يراه إلا المستأجرون الدافعون؛
• نموذجاً لكل مستأجر: نفّذ LlmProvider موجّهاً صغيراً يختار مزوّد العميل من الإعداد بحسب مستأجر ctx، أو شغّل نموذجاً واحداً للجميع؛
• ChatStore على قاعدة بيانات التطبيق، بقواعد الاحتفاظ الخاصة بالعميل؛
• instructions(...) تصف المجال (شركة مصاعد: وحدات ومواقع وفواصل صيانة)، وإرشادات ai = "..." على الإجراءات التي تحتاجها؛
• token_limit مضبوطاً على الخطة التي يدفع العميل ثمنها.

8. نقاط النهاية

الأحداث، كائن JSON واحد في كل سطر: {t:"text",v} و{t:"tool",name,id} و{t:"navigate",url,screen,filters} و{t:"suggest",v} و{t:"confirm",id,tool,title,question,details} و{t:"resolved",id,approved} و{t:"error",message} و{t:"done"}.

يُحمَّل assistant.js وassistant.css فقط للمستخدمين الذين يحق لهم استخدام المساعد. سجل المحادثة منطقة حية role="log" (مع aria-busy أثناء تدفق الإجابة)، وEnter يرسل، وShift+Enter يبدأ سطراً جديداً، وEscape يغلق اللوحة الجانبية ويعيد التركيز إلى الزر، وبطاقة التأكيد تضع التركيز على إلغاء (Cancel) أولاً.

9. الكلفة

لا يحتفظ المساعد بأي حالة لكل مستخدم في الذاكرة سوى مخزن السجل المحدود والتدفقات الجارية. تتدفق الإجابات من طرف إلى طرف عبر قنوات من 32 عنصراً. القياس على showcase (بناء debug، Windows، في حالة خمول بعد خمس صفحات محملة): مجموعة عمل 14.4 ميغابايت وذاكرة خاصة 3.13 ميغابايت والمساعد معطل، و14.5 ميغابايت و3.19 ميغابايت وهو مفعّل (نحو 100 كيلوبايت زيادة).