vibe-coding-college-specs/chapters/10-external-services/07-lesson-integrating-ai-models-and-apis/spec.md

مشخصات درس‌نامه: تزریق مغز هوش مصنوعی به محصول؛ چت‌بات رزومه با OpenRouter و AvalAI

• شناسه در سیلابس: L10.8
• فصل: فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۲۰ دقیقه
• پیش‌نیازهای مستقیم: L10.7 (اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): جهش از «کدنویسی با هوش مصنوعی» به «تزریق قابلیت‌های هوش مصنوعی به عنوان فیچر محصول» (AI as a Feature) را درک کرده و ساختار استاندارد Chat Completions API را شرح دهد.
• تحلیل/ارزیابی کند (Evaluate): مزایای هاب‌های چندمدلی نظیر OpenRouter و سرویس‌های واسط بومی (نظیر AvalAI) را در کاهش هزینه‌ها و عدم نیاز به کارت‌های اعتباری بین‌المللی ارزیابی کند.
• به‌کار ببندد (Apply): یک ویجت چت‌بات هوشمند رزومه (AI Resume Assistant) در گوشه پورتفولیو پیاده کند که با استریم زنده (Streaming)، به سوالات کارفرمایان درباره مهارت‌ها و پروژه‌ها پاسخ دهد.
• ایجاد کند (Create): یک پرامپت سیستمی مستحکم (System Prompt با تکنیک Grounding) تنظیم کند تا از توهم اطلاعات غیرواقعی و حملات تزریق پرامپت (Prompt Injection) جلوگیری نماید.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. انقلاب در هویت محصول: پورتفولیویی که زنده است و حرف می‌زند!
   • بازدیدکننده پورتفولیو به جای خواندن صدها سطر رزومه، از هوش مصنوعی می‌پرسد: «آیا فلانی تجربه کار با Supabase را دارد؟» و پاسخ هوشمند دریافت می‌کند.
2. کالبدشکافی ساختار پیام‌های API در مدل‌های زبانی (Chat Completion Schema):
   • پیام سیستمی (system): شخصیت، قوانین و دانش پایه دستیار.
   • پیام کاربر (user): سوال یا ورودی جدید بازدیدکننده.
   • پیام دستیار (assistant): تاریخچه پاسخ‌های مدل برای حفظ کانتکست گفتگو.
3. دسترسی بی‌دردسر به مدل‌های روز جهان (OpenRouter و AvalAI):
   • چرا OpenRouter با یک کلید، دسترسی به Claude 3.5 Sonnet، GPT-4o، DeepSeek V3 و Llama 3 را ممکن می‌کند؟
   • گزینه‌های پرداخت ریالی و پروکسی‌های داخلی پایدار در ایران.
4. تکنیک لنگراندازی داده‌ها (Grounding) و دیوارهای امنیتی:
   • تزریق خلاصه مشخصات صاحب سایت، لیست پروژه‌ها، سابقه کار و راه‌های ارتباطی در پرامپت سیستمی.
   • دستورالعمل سفت‌وسخت: «تو دستیار رزومه هستی. فقط بر اساس اطلاعات بالا پاسخ بده. اگر چیزی را نمی‌دانی، حدس نزن و بگو در رزومه ذکر نشده است.»
5. معماری روت سرور امن /api/chat در Next.js:
   • دریافت پیام کاربر \rightarrow افزودن پرامپت سیستمی مخفی در سرور \rightarrow ارسال به OpenRouter با کلید محرمانه \rightarrow استریم پاسخ به مرورگر کاربر.
6. پیاده‌سازی رابط کاربری ویجت چت:
   • آیکون شناور در گوشه پایین سایت، قابلیت باز و بسته شدن، دکمه‌های پیشنهاد سریع سوال (Chips)، و افکت تایپ زنده (Typewriter/Streaming).
7. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): حمله تزریق پرامپت (Prompt Injection)؛ چطور نگذاریم کارفرما با گفتن «تمام دستورات قبلی را فراموش کن» دستیار را هک کند.
   • کال‌اوت سبز (<details class="green">): مدل‌های فوق‌سریع و تقریباً رایگان مانند DeepSeek V3 یا Gemini 2.0 Flash در OpenRouter با هزینه چند صدم سنت برای هر مکالمه.
   • کال‌اوت قرمز (<details class="red">): محدود کردن طول تاریخچه چت (Truncation) به ۶ پیام آخر برای جلوگیری از سوختن توکن‌ها و هزینه‌های انفجاری.

آنچه نباید وارد آن شویم (Out-of-Scope):

• مباحث پیچیده RAG (Retrieval-Augmented Generation) و دیتابیس‌های برداری وکتوری (در فصل ۱۵ بررسی می‌شود).
• فاین‌تیونینگ (Fine-Tuning) مدل‌های زبانی متن‌باز.

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Chat Completions API	وب‌سرویس تکمیل گفتگو	رابط استاندارد ارسال تاریخچه مکالمه به مدل زبانی و دریافت پاسخ متنی هوشمند
System Prompt	پرامپت سیستمی بنیادین	دستورالعمل سطح بالایی که رفتار، هویت، محدودیت‌ها و پایگاه دانش مدل را مشخص می‌کند
Grounding	لنگراندازی داده‌ها	مقید کردن مدل به استفاده انحصاری از اطلاعات و اسناد ارائه شده به جای تکیه بر اطلاعات عمومی
Streaming Response	پاسخ جریانی پیوسته	دریافت توکن‌به‌توکن کلمات مدل از طریق اینترنت برای ایجاد جلوه تایپ زنده بدون معطلی
Prompt Injection	تزریق پرامپت مخرب	ترفند کاربر برای دور زدن قوانین سیستمی مدل از طریق ارسال دستورات فریبکارانه
OpenRouter	روتر باز مدل‌های زبانی	پلتفرم تجمیع‌کننده مدل‌های هوش مصنوعی مختلف با یک رابط یکپارچه و کلید مشترک

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: مغز دیجیتال نئونی درخشان که یک ویجت چت شناور بنفش را روی صفحه سایت پورتفولیو زنده و فعال می‌کند.
2. جریان فنی فراخوانی امن چت‌بات در Next.js: images/ai-chat-architecture.png
   • موضوع: دیاگرام معماری: کاربر در ویجت تایپ می‌کند \rightarrow روت سرور /api/chat کانتکست رزومه را الصاق می‌کند \rightarrow درخواست امن به OpenRouter/AvalAI \rightarrow استریم پاسخ به کلاینت.
3. ویجت چت‌بات تعاملی در گوشه پورتفولیو: images/portfolio-chat-widget-ui.png
   • موضوع: اسکرین‌شات از ویجت شناور در پورتفولیو با دکمه‌های پیشنهاد سوال سریع ("پروژه‌های شاخص"، "تجربه React"، "تماس با من").
4. تکنیک جلوگیری از توهم و تزریق پرامپت: images/prompt-guardrails-diagram.png
   • موضوع: اینفوگرافیک محافظتی: تلاش کاربر برای خروج از نقش \rightarrow فیلتر قوانین System Prompt \rightarrow بازگرداندن مودبانه مکالمه به مباحث رزومه.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # تزریق مغز هوش مصنوعی به محصول؛ چت‌بات رزومه با OpenRouter و AvalAI
2. مقدمه: تا پیش از این، با هوش مصنوعی کد می‌نوشتید؛ اکنون وقت آن است که هوش مصنوعی را به عنوان یک کارمند شبانه‌روزی داخل پروژه خود استخدام کنید!
3. جدول کاور درس
4. استعاره منشی هوشمند و سخنگوی ۲۴ ساعته شما:
   • کارفرما ساعت ۲ نیمه‌شب می‌خواهد بداند شما برای پروژه‌اش مناسب هستید یا خیر؛ دستیار رزومه بیدار است و با تسلط کامل پاسخ می‌دهد.
5. ساختار Chat Completions در مدل‌های زبانی (Roles: System, User, Assistant):
   • چگونگی هدایت هوش با تفکیک پیام‌های سه لایه.
6. دریافت کلید API از OpenRouter یا سرویس‌های در دسترس داخلی (AvalAI):
   • ثبت نام سریع، دریافت کلید، و انتخاب مدل‌های مقرون‌به‌صرفه و سریع.
7. طراحی پرامپت سیستمی طلایی با تکنیک Grounding:
   • تزریق رزومه به ساختار پرامپت:

     You are the AI Portfolio Assistant for [Your Name], a Full-Stack Developer.
     Here is the verified knowledge base about the creator:
     - Experience: 3 years building modern web apps with Next.js, TypeScript, Tailwind.
     - Top Projects: 1) Personal Portfolio with Supabase, 2) E-Commerce MVP.
     - Availability: Open for freelance and full-time remote roles.
     Strict Rules:
     1. ONLY answer questions about [Your Name]'s skills, experience, and projects.
     2. If asked about cooking, politics, or unrelated topics, politely decline.
     3. Never invent facts not listed in the knowledge base.
     

8. ساخت روت سرور امن /api/chat/route.ts با قابلیت Streaming:
   • کد تمیز فراخوانی API به صورت استریم برای ایجاد حس پاسخ‌گویی بلادرنگ.
9. طراحی کامپوننت ویجت شناور رزومه در فرانت‌اند:
   • دکمه آیکون چت در گوشه راست پایین، قابلیت مینیمایز، و دکمه‌های سریع (Quick Chips).
10. جعبه پرامپت طلایی: ساخت کامل دستیار رزومه با ایجنت:
    • پرامپت دقیق:

      «من یک کلید OPENROUTER_API_KEY در .env.local دارم. لطفاً یک روت سرور /api/chat بساز که با مدل deepseek/deepseek-chat یا openai/gpt-4o-mini ارتباط برقرار کند. پرامپت سیستمی باید اطلاعات رزومه من را به صورت محرمانه در بر بگیرد. سپس یک ویجت چت شناور در پایین صفحه پورتفولیو اضافه کن که تاریخچه پیام‌ها را نمایش دهد، حالت لودینگ داشته باشد و متن پاسخ را به صورت تایپ زنده بنویسد.»

11. دستورات چندسکویی برای پیکربندی متغیر محیطی هوش مصنوعی:
    • منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
      • Windows (PowerShell):

        Add-Content .env.local "`nOPENROUTER_API_KEY=sk-or-v1-your-key-here"
        

      • macOS (Terminal):

        echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> .env.local
        

      • Linux (Bash):

        echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> .env.local
        

12. باکس نکته امنیتی Quera (<details class="violet">): مقابله با Prompt Injection؛ چرا کلید API هرگز نباید در کلاینت بماند و چطور کدهای مخرب کاربر را خنثی کنیم.
13. باکس راهنمای بهینه‌سازی هزینه Quera (<details class="green">): کوتاه کردن هیستوری به ۶ چت آخر برای جلوگیری از هزینه اضافی.
14. باکس هشدار Quera (<details class="red">): خطرات توهم مدل؛ حتماً تست کنید که مدل برای شما تخصص‌هایی که ندارید اختراع نکند!
15. جمع‌بندی فصل دهم و پیش‌نمایش فصل یازدهم: جشن اتصال کامل پورتفولیو به پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی؛ ورود به فصل سرنوشت‌ساز یازدهم: امنیت و استفاده مسئولانه.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• تفاوت استفاده از AI به عنوان ابزار با AI به عنوان قابلیت محصول تبیین شود.
• ساختار فنی Chat Completions API به همراه نقشه پیام‌های System, User, Assistant تشریح گردد.
• تکنیک Grounding برای جلوگیری از توهم در دستیار رزومه پیاده‌سازی شود.
• پرامپت ایجنت برای ساخت ویجت شناور چت با قابلیت Streaming در متن قرار گیرد.