دستیار برینو پشت صحنه

۱. ابزارها و نقش‌ها

• دستیار یک گفتگوی جدا (ai_chats.kind = 'agent') کنار چت درسی است. ابزارها فقط در دستیارند و چت درسی (راهنمای سقراطی، کتاب، ضدتقلب) دست‌نخورده می‌ماند.
• حدود ۴۵ ابزار در یک رجیستری مشترک (packages/shared) تعریف شده‌اند. هر ابزار نقش‌های مجاز، نوع خواندن یا نوشتن و ورودی اعتبارسنجی‌شده دارد. هر ابزار همان موتور (Engine) صفحه‌های اپ را با هویت خود کاربر صدا می‌زند، پس مجوزها دقیقاً همان مجوزهای اپ است.
• مجموعه‌ی ابزار هر نوبت = نقش‌های کاربر × ابزارهای روشن (agent_tool_permissions). دانش‌آموزِ دارای آزمون فعال، ابزارهای حل و خلاصه را ندارد.
• مدل شناسه حدس نمی‌زند: اول با ابزارهای کمکی (فهرست کلاس‌ها، پیدا کردن دانش‌آموز، گروه‌ها، معلم‌ها، کتاب‌ها) نام را به شناسه تبدیل می‌کند.

۲. کارت تأیید: هیچ نوشتنی بی‌تأیید نیست

• ابزار نوشتن هرگز خودش کاری انجام نمی‌دهد. فقط ورودی را می‌سنجد، پیش‌نمایش («چه، برای چه کسانی، کی») می‌سازد و یک کارت در انتظار با ۵ دقیقه اعتبار ذخیره می‌کند. مدل همین‌جا می‌ایستد.
• کار فقط وقتی انجام می‌شود که خود کاربر روی کارت «تأیید» بزند. سرور کارت را به‌صورت یکبارمصرف و اتمیک برمی‌دارد: فقط صاحب کارت، فقط پیش از انقضا، فقط یک بار. بعد همان ورودی ذخیره‌شده اجرا می‌شود، پس مدل نمی‌تواند پس از تأیید چیزی را عوض کند. تکرار، نفر دیگر و کارت منقضی یک پاسخ یکسان «کارت معتبر نیست» می‌گیرند.
• نقش یا خاموشی ابزار هنگام تأیید دوباره سنجیده می‌شود. نتیجه در همان پیام ذخیره می‌شود تا بارگذاری دوباره‌ی گفتگو وضعیت درست کارت را نشان دهد.
• پس از تأیید، اپ یک نوبت «ادامه» می‌فرستد تا مدل نتیجه را ببیند و گام بعد را برود. پس از لغو، اپ ادامه نمی‌فرستد.

۳. حلقه‌ی اجرا و ایمنی

• هر نوبت حداکثر ۱۰ قدم ابزار. خطای ورودی یا خطای موتور (با پیام فارسی) به‌صورت نتیجه‌ی ابزار به مدل برمی‌گردد تا خودش اصلاح کند. بعد از ۳ خطای پیاپی، همان ابزار برای بقیه‌ی نوبت کنار می‌رود.
• همان لایه‌های چت: گیت کیف پول و سقف روزانه، دسته‌بند ایمنی کودک روی ورودی و خروجی دانش‌آموز، و گارد نشت دستورالعمل. متن شبیه دستور در داده‌ها (مثلاً پاسخ آزاد دانش‌آموز) به پرامپت نمی‌رود یا داده حساب می‌شود.
• سقف ساعتی هر ابزار per کاربر به‌صورت اتمیک شمرده می‌شود (پیش‌فرض ۱۲۰ خواندن و ۳۰ نوشتن در ساعت). بعد از سقف، مدل خطای فارسی می‌گیرد.

۴. هزینه و لاگ

• هر نوبت مثل یک پیام چت از کیف پول کاربر کم می‌شود. تولید سؤال (question_generate) و تحلیل آزمون (exam_analysis) اکشن پولی جدا از کیف معلم دارند. تحلیل تا تغییر شرکت‌کننده یا نمره کش می‌شود.
• هر اجرای ابزار در agent_tool_executions ثبت می‌شود: کاربر، گفتگو، ابزار، نوع، وضعیت، کد خطا و مدت. ورودی و خروجی با ماسک شماره و کد ملی ذخیره و ۹۰ روز نگه داشته می‌شوند. ادمین آن را در «لاگ دستیار برینو» می‌بیند.
• UI با کامپوننت‌های AI Elements (Conversation، Message، Tool، Confirmation) با استایل برینو و راست‌به‌چپ ساخته شده است. پس از اجرای هر نوشتن، داده‌های همان بخش اپ (آزمون‌ها، گروه‌ها، اعلان‌ها…) تازه می‌شوند.