راهنمای تصویری گام‌به‌گام مجموعه
مقاله آموزشی Smart Support Bot و Smart Support Manager
این راهنما هر دو نرم‌افزار به هم پیوسته مجموعه را پوشش می‌دهد: از مدیریت محلی کاتالوگ و عکس‌ها در Smart Support Manager تا نصب یکپارچه روی سرور لینوکس و پاسخ‌گویی هوشمند با Smart Support Bot در تلگرام.
همگام‌سازی دو برنامه در یک سیستم
- نقش Smart Support Manager: روی ویندوز با آدرس
http://127.0.0.1:8766باز می‌شود و وظیفه خواندن مستندات، تولید کاتالوگ AI، مرتب‌سازی عکس‌ها، مدیریت صف آپلود SSH و استقرار ربات را بر عهده دارد. - نقش Smart Support Bot: روی سرور لینوکس (مسیر
/opt/smart-support) به‌عنوان سرویس پس‌زمینه اجرا می‌شود و از کاتالوگ‌ها و تصاویر آپلودشده در/opt/smart-support/products/<id>/استفاده می‌کند. - نتیجه یکپارچگی: بدون نیاز به کدنویسی یا ویرایش دستی JSON، تیم پشتیبانی شما در مرورگر محلی محتوا را می‌سازد و کاربران در تلگرام پاسخ دقیق می‌گیرند.
ترتیب طلایی راه‌اندازی (از صفر تا اجرا)
- مرحله پیش‌نیاز: اجرای
Start-Smart-Support-Manager.bat(یا نصب PowerShell) و وارد کردن مشخصات SSH و کلیدهای AI در تبSettings. - مرحله آماده‌سازی محتوا: ثبت محصول در
Products← ساخت و تایید متن درCatalog← افزودن و اتصال تصاویر درMediaوCatalog photos. - مرحله اجرا و تست: استقرار از تب
Install botو تست دستور/startو دکمهAsk AIدر تلگرام همراه با رصد تاریخچه درHistory.
۱. داشبورد، نشانگرهای اتصال و راهنمای سریع (Dashboard)
بلافاصله پس از اجرای Start-Smart-Support-Manager.bat، پنل وب محلی روی http://127.0.0.1:8766 باز می‌شود. صفحه Dashboard نمای کلی وضعیت ارتباط با سرور و سلامت هوش مصنوعی را نمایش می‌دهد:
- سه نشانگر وضعیت در نوار بالا: قرص‌های رنگی
Server(اتصال SSH به VPS)،Expert + AI(اتصال Manager به موتور AI جهت ساخت کاتالوگ) وExpert + bot + AI(همگام‌سازی کامل با ربات روی سرور) در هر لحظه وضعیت را نشان می‌دهند. - تغییر زبان رابط پنل: در گوشه بالا می‌توانید زبان پنل Manager را بین
فارسی،English،Русскийو中文جابه‌جا کنید. - کارت‌های آماری: تعداد محصولات فعال روی سرور (مثلاً محصولات آماده در ربات)، وضعیت صف آپلود تصاویر و نقشه‌راه ۵ مرحله‌ای در پایین داشبورد در دسترس است.
نکته شروع: تا زمانی که نشانگر
Server سبز نشده است، تغییرات کاتالوگ به‌صورت پیش‌نویس محلی می‌مانند؛ برای انتشار مستقیم روی ربات ابتدا اتصال سرور را در Settings برقرار کنید.
۲. تعریف محصولات و پوشه مستندات (Products)
در تب Products مشخص می‌کنید ربات تلگرام درباره چه نرم‌افزارها یا سرویس‌هایی به کاربران پشتیبانی بدهد:
- ایجاد یا انتخاب محصول: برای هر محصول یک شناسه یکتا (
Product IDمثلvpn-installerیاconfig-builder) و نام نمایشی (Name shown in manager and bot) وارد کنید. - معرفی منبع دانش (
Sources): مسیر یک فایل یا پوشه روی کامپیوتر خود را بدهید. برنامه فایل‌هایTXT،MD،JSON،CSV،HTML،PDF،DOCX،GoوPythonرا می‌خواند تا کاتالوگ دقیق بسازد. - پوشه تصاویر و مسیر ثابت سرور: پوشه اسکرین‌شات‌های محلی (
Photo folder) را انتخاب کنید؛ مسیر مقصد روی سرور همیشه به‌شکل ایزوله در/opt/smart-support/products/<id>تنظیم می‌شود. - کلید فعال‌سازی (
Active / Disabled): با روشن کردنOnمحصول در منو و هوش مصنوعی ربات دیده می‌شود و باOffبدون پاک شدن فایل‌ها موقتاً مخفی می‌گردد.
۳. تولید کاتالوگ با هوش مصنوعی، ویرایش و انتشار (Catalog)
بخش Catalog مغز محتوایی ربات است؛ در اینجا هوش مصنوعی اسناد محصول را به زبان ساختاریافته برای ربات تبدیل می‌کند:
- ساخت خودکار کاتالوگ: محصول موردنظر را از فهرست انتخاب کرده و ساخت کاتالوگ با هوش مصنوعی را بزنید تا عنوان، خلاصه کوتاه، معرفی کامل و فهرست قابلیت‌ها تولید شود.
- ویرایش دقیق متن‌ها و ویژگی‌ها: متن هر بخش را مستقیماً در کادرهای صفحه بررسی و اصلاح کنید و در بخش پایین قابلیت‌های جدید اضافه یا موارد قدیمی را حذف کنید تا ربات فقط اطلاعات تاییدشده بگوید.
- انتشار در ربات (
Use catalog in bot): تنها پس از زدن این دکمه، فایل کاتالوگ روی سرور آپلود و بلافاصله در ربات تلگرام فعال می‌شود. با دکمهStop using catalogنیز نمایش آن متوقف می‌گردد.
تفکیک دانش محصولات: ربات هنگام پرسش درباره یک محصول، صرفاً از کاتالوگ همان محصول پاسخ می‌دهد تا توضیحات نرم‌افزارهای مختلف با هم تداخل نداشته باشند.
۴. صف آپلود، کتابخانه رسانه و اتصال عکس به قابلیت‌ها (Upload Queue / Media / Catalog photos)
یکی از برتری‌های این مجموعه، ارسال خودکار اسکرین‌شات مرتبط هنگام توضیح هر بخش در تلگرام است. این کار از طریق سه صفحه هماهنگ انجام می‌شود:
- صف آپلود (
Upload Queue): عکس‌های خارج از پوشه اصلی را باChoose filesبه صف اضافه کنید و باProcess waitingبه‌صورت تک‌به‌تک و منظم از طریق SSH به سرور بفرستید تا هیچی فایلی جا نماند. - کتابخانه رسانه (
Media): تمام تصاویر آپلودشده یا شناسایی‌شده برای محصول در این صفحه فهرست می‌شوند؛ می‌توانید تحلیل خودکار AI روی عکس‌ها را اجرا کنید یا آن‌ها را برای نگاشت آماده کنید. - مدیریت تصاویر کاتالوگ (
Catalog photos): هر عکس به کدام قابلیت کاتالوگ متصل شود؟ اینجا نگاشت را تایید یا تغییر دهید. با کلیک روی تصویر بندانگشتی، نمای بزرگ باز می‌شود (با کلیدEscبسته می‌شود) و در صورت نیاز می‌توانید عکس را بهMediaبرگردانید یا از سرور پاک کنید.
قاعده طلایی ارسال عکس: ربات تلگرام تنها عکس‌هایی را همراه راهنما ارسال می‌کند که وضعیت تایید و نگاشت‌شده در بخش
Catalog photos داشته باشند.
۵. نصب یک‌کلیکی ربات روی سرور و تنظیمات اتصال و AI (Install bot & Settings)
دیگر نیازی به نوشتن فایل‌های سرویس لینوکس نیست؛ استقرار ربات و سرویس Expert روی سرور مستقیماً از داخل پنل وب انجام می‌شود:
- برگه
Install bot— اطلاعات سرور و تلگرام: آی‌پی میزبان (Host)، پورت SSH (پیش‌فرض22)، نام کاربری و رمز/کلید SSH، مسیر پوشه محلیSmart Support Botروی کامپیوتر و توکن ربات از@BotFatherرا وارد کنید. - انتخاب روش دریافت آپدیت (Polling یا Webhook): برای ساده‌ترین راه‌اندازی روی هر سروری گزینه
Polling — no webhookرا انتخاب کنید. اگر دامنه با HTTPS و پراکسی معکوس (مثل Nginx/Caddy) دارید می‌توانید حالتWebhookو پورت داخلی (پیش‌فرض8080) را تنظیم نمایید. - مراحل سه‌گانه استقرار: به ترتیب دکمه‌های
1. Install bot(نصب کد و تنظیمات تلگرام)،2. Install Expert(نصب سرویس هماهنگ‌کننده کنار ربات) و3. Activate bot and Expert(اجرا و بررسی آمادگی هر دو سرویس) را بزنید. - برگه
Settings— موتور AI و قطع اضطراری: در این بخش اتصال سرور،API endpoint(سازگار با OpenAI)، نام مدل وAPI keyربات را ذخیره و تست کنید (Connect to AI)، همگام‌سازیConnect Expert to bot and AIرا بزنید و در صورت نیاز با دکمه قرمزStop allعملیات پنل را متوقف نمایید.
امنیت کلیدهای دسترسی: رمزهای SSH به‌شکل رمزنگاری‌شده فقط روی کامپیوتر شما ذخیره می‌شوند و در فایل
.env سرور با دسترسی محدود نگه داشته می‌شوند.
۶. کار با ربات در تلگرام، گزارش تاریخچه و راهنمای تماس (Telegram Bot, History & Contact)
پس از سبز شدن وضعیت ربات، کاربران در تلگرام تجربه‌ای ساختاریافته و بدون سردرگمی خواهند داشت و تیم شما تمام تغییرات را رصد می‌کند:
- شروع و انتخاب زبان در تلگرام: با ارسال
/startیا/langکاربر یکی از ۴ زبان (فارسی،English،Русский،中文) را انتخاب می‌کند؛ همچنین دستورات/menuو/helpهمیشه در دسترس هستند. - مرور کاتالوگ و پرسش هوشمند (
Ask AI): کاربر با دکمه‌های زیر صفحه، محصول را انتخاب کرده، راهنمای هر بخش را همراه با عکس تاییدشده دریافت می‌کند یا با زدنAsk AIسوال آزاد خود را می‌پرسد تا هوش مصنوعی دقیقاً بر پایه دانش همان محصول پاسخ دهد. - دستورات و کنترل ادمین در تلگرام: مدیران ربات می‌توانند با دستورات مدیریتی مانند
/agents،/active_agent،/failover،/safety_statusو/catalog_scanوضعیت مدل‌های AI و اسکن مجدد کاتالوگ را مستقیماً از تلگرام کنترل کنند. - برگه
Historyدر Manager: تمام عملیات‌ها از جمله اتصال سرور، ذخیره متن کاتالوگ، انتشار در ربات (publish_catalog_to_bot)، غیرفعال‌سازی و وضعیت خطاها (FAILED) با زمان دقیق (UTC) ثبت می‌شود. - برگه
Contact: دسترسی سریع به آدرس گیت‌هاب رسمی، سایت مرجع و دستور نصب سریع PowerShell ویندوز را یک‌جا نمایش می‌دهد.
بازاسکن فوری کاتالوگ: اگر تغییری مستقیماً روی فایل‌های سرور اعمال کردید، در چت خصوصی ادمین دستور
/catalog_scan را بزنید یا از پنل Manager دوباره روی Use catalog in bot کلیک کنید.
۷. سوالات متداول و عیب‌یابی (FAQ)
| سوال یا خطا | علت احتمالی | راه‌حل پیشنهادی |
|---|---|---|
| تغییرات جدید کاتالوگ در ربات تلگرام دیده نمی‌شود | ویرایش فقط در فرم محلی ذخیره شده و هنوز منتشر نشده یا محصول Off است. | در صفحه Products مطمئن شوید محصول روی On است؛ سپس در Catalog دکمه Use catalog in bot را بزنید. |
| ربات پاسخ متنی می‌دهد اما عکس راهنما ارسال نمی‌کند | تصویر هنوز فقط در بخش Media است و به عنوان قابلیت کاتالوگ نگاشت نشده. | در صفحه Media و Catalog photos تصویر را به قابلیت مربوطه متصل کنید و مطمئن شوید آپلود SSH کامل شده است. |
| حالت Webhook کار نمی‌کند یا خطای SSL می‌دهد | پراکسی HTTPS دامنه به پورت داخلی webhook (پیش‌فرض 8080) متصل نشده است. | برای شروع سریع در Install bot حالت Polling — no webhook را انتخاب کنید یا گواهی SSL و reverse proxy را بررسی نمایید. |
| نشانگر Server قرمز مانده و اتصال برقرار نمی‌شود | آی‌پی، پورت SSH، نام کاربری، رمز یا مسیر Private Key در Settings اشتباه است. | مشخصات Server connection را در تب Settings تصحیح و Save کرده، سپس دکمه Connect را بزنید. |
| ساخت کاتالوگ AI متوقف می‌شود یا پاسخ نمی‌دهد | API Endpoint، نام مدل یا API Key اعتبار ندارد یا اتصال اینترنت محدود است. | در تب Settings مقدار API endpoint و API key را بازبینی کرده و با Connect to AI تست بگیرید. |
| آیا می‌توان هم‌زمان چند محصول جدا را مدیریت کرد؟ | بله؛ معماری هر محصول بر پایه شناسه مجزا در سرور طراحی شده است. | در صفحه Products برای هر برنامه یک شناسه مجزا بسازید؛ ربات دانش هر محصول را کاملاً جدا نگه می‌دارد. |