بهبود پرداخت تجارت الکترونیک با قابلیت‌های هوش مصنوعی مرورگر

۱. مقدمه

توسعه وب مدرن جایگزینی برای سفرهای رفت و برگشت مبتنی بر ابر برای استفاده از هوش مصنوعی ارائه می‌دهد. کروم شروع به ارائه APIهای هوش مصنوعی داخلی کرده است که به شما امکان می‌دهد از همه چیز، از مدل‌های تخصصی کوچک برای ترجمه گرفته تا مدل‌های زبانی کامل و قابل تقطیر ، بدون هیچ هزینه توکنی برای شما یا کاربرانتان، به صورت خصوصی روی دستگاه آنها اجرا کنید.

در عین حال، عامل‌های هوش مصنوعی روش جدیدی را برای تعامل کاربران با برنامه‌های وب ارائه می‌دهند و آماده‌سازی عامل تجربه وب شما با WebMCP می‌تواند به کاهش استفاده از توکن کمک کند و در عین حال نتایج دقیق‌تری نسبت به فعال‌سازی سنتی که نیاز به اسکرین‌شات و استخراج DOM دارد، ارائه دهد.

در این آزمایشگاه کد، شما روی Mont-Royal Plein Air ، یک سایت تجارت الکترونیک تجهیزات فضای باز، کار خواهید کرد. شما یاد خواهید گرفت که چگونه API های هوش مصنوعی داخلی و WebMCP را بسازید و ادغام کنید تا:

1. قصد مشتری را از تاریخچه مرور استنباط کنید و با استفاده از مدل‌های روی دستگاه، به صورت پویا توصیه‌هایی را برای آنها ایجاد کنید.
2. ابزارهای اکسپوز (Expose) که عامل‌ها و دستیاران مرورگر می‌توانند از آن‌ها برای پیمایش سایت، بررسی محصول و توصیه‌ها و مدیریت سبد خرید کاربر استفاده کنند.
3. (اختیاری) سایت خود را با استفاده از مدل‌های کوچک و حرفه‌ای روی دستگاه، به صورت آنی ترجمه کنید.
4. (اختیاری) جستجوی اولیه سایت را به یک عامل در محل تبدیل کنید که با استفاده از همان ابزارهایی که عوامل خارجی استفاده می‌کنند، کار می‌کند.

آنچه یاد خواهید گرفت

• نحوه استفاده از API Prompt و اعمال خروجی ساختاریافته JSON از آن.
• نحوه ثبت ابزارها و استراتژی‌های WebMCP برای تفکر در مورد ترکیب و جزئیات ابزار.
• (اختیاری) نحوه استفاده از رابط برنامه‌نویسی نرم‌افزار مترجم برای ترجمه سریع محتوا با استفاده از یک مدل متخصص روی دستگاه.
• (اختیاری) چگونه خودتان ابزارهای WebMCP را فراخوانی کنید.

پیش‌نیازها

• یک حساب گوگل شخصی و گوگل کلود.
• گوگل کروم نسخه ۱۵۰+ یا کانال‌های Canary، Dev یا Beta، با پرچم‌های #enable-webmcp-testing و #devtools-webmcp-support فعال.
• آشنایی با HTML، CSS، جاوا اسکریپت و TypeScript.
• آشنایی با طرحواره JSON .

۲. راه‌اندازی پروژه

حساب گوگل

اگر از قبل حساب گوگل شخصی ندارید، باید یک حساب گوگل ایجاد کنید .

وارد کنسول گوگل کلود شوید

با استفاده از یک حساب کاربری شخصی گوگل، وارد کنسول ابری گوگل شوید.

فعال کردن صورتحساب

نکته: اگر صورتحساب را با استفاده از اعتبارهای Google Cloud تنظیم کرده‌اید، می‌توانید از این مرحله صرف نظر کنید.

برای تنظیم یک حساب پرداخت شخصی، پرداخت را در کنسول ابری فعال کنید .

ایجاد پروژه (اختیاری)

اگر پروژه‌ی فعلی ندارید که بخواهید برای این آزمایشگاه از آن استفاده کنید، اینجا یک پروژه‌ی جدید ایجاد کنید .

ویرایشگر Cloud Shell را باز کنید

1. برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
2. اگر امروز در هر مرحله‌ای از شما خواسته شد که مجوز دهید، برای ادامه روی «مجوز دادن» کلیک کنید.
3. اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
   • روی مشاهده کلیک کنید.
   • روی ترمینال کلیک کنید.

پروژه خود را تنظیم کنید

1. در ترمینال، پروژه خود را با استفاده از این دستور تنظیم کنید:

   gcloud config set project [PROJECT_ID]
   

   مثال: gcloud config set project lab-project-id-example

   اگر نمی‌توانید شناسه پروژه خود را به خاطر بیاورید، می‌توانید تمام شناسه‌های پروژه خود را با استفاده از gcloud projects list فهرست کنید.

   
2. پیام زیر را مشاهده خواهید کرد: Updated property [core/project].

   اگر با پیغام WARNING مواجه شدید و از شما پرسیده شد Do you want to continue (Y/n)? احتمالاً شناسه پروژه را اشتباه وارد کرده‌اید. کلید n و سپس Enter را فشار دهید و دوباره سعی کنید دستور gcloud config set project اجرا کنید.

تنظیمات محلی و فضای کاری

1. در ترمینال خود (یا ترمینال Cloud Shell)، مخزن پروژه را کلون کنید و به دایرکتوری پروژه بروید:

   git clone https://github.com/GoogleChromeLabs/codelabs mont-royal
   cd mont-royal
   

2. به پوشه‌ی ecommerce-ai-enhancements/starter بروید:

   cd ecommerce-ai-enhancements/starter
   

3. وابستگی‌ها را با استفاده از pnpm نصب کنید:

   pnpm install
   

4. سرور توسعه محلی را شروع کنید:

   pnpm dev
   

   برای مشاهده فروشگاه Mont-Royal Plein Air، مرورگر خود را باز کرده و آدرس http://localhost:5173 را وارد کنید.

(اختیاری) افزونه‌ی WebMCP inspector را نصب کنید

برای آسان‌تر کردن کار با WebMCP، می‌توانید WebMCP Model Context Tool Inspector را نصب کنید. پس از نصب، برای استفاده از آن باید یک کلید API Gemini دریافت کنید:

• به استودیوی هوش مصنوعی بروید.
• برای ایجاد یک کلید API جدید Gemini که به پروژه‌ای که قبلاً در این مرحله راه‌اندازی کرده‌اید، مرتبط است، روی دکمه‌ی «ایجاد کلید API» کلیک کنید.
• ابزار WebMCP Model Context Tool Inspector را باز کنید (در پنل کناری باز می‌شود) و روی دکمه‌ی Update Gemini API Key کلیک کنید.
• کلید API خود را در پنجره باز شده قرار دهید و ذخیره کنید.

این افزونه یک عامل پایه دارد که می‌تواند از WebMCP استفاده کند و به شما امکان می‌دهد وب‌سایت خود را از طریق آن امتحان کنید، به جای اینکه ابزارهای WebMCP را مستقیماً از طریق DevTools فراخوانی کنید.

۳. مدل‌های هوش مصنوعی داخلی در وب

رابط برنامه‌نویسی کاربردی (API) پرومپ چیست؟

رابط برنامه‌نویسی کاربردی Prompt به برنامه‌های وب امکان دسترسی مستقیم به یک مدل زبانی کوچک و چندوجهی را می‌دهد که کاملاً روی دستگاه کاربر اجرا می‌شود. زیرا استنتاج به صورت محلی اجرا می‌شود:

• بدون تأخیر ابری : بدون رفت و برگشت شبکه یا صف‌بندی سرور backend.
• خصوصی به طور پیش‌فرض : اعلان‌ها و هر زمینه‌ای که به آنها ارسال می‌شود، هرگز دستگاه را ترک نمی‌کنند
• هزینه صفر : استنتاج بدون نیاز به پرداخت توکن یا هزینه‌های میزبانی ابری، روی سخت‌افزار کلاینت اجرا می‌شود.
• قابلیت آفلاین : حتی بدون اتصال فعال به اینترنت نیز به طور قابل اعتمادی کار می‌کند.

در کروم، API مربوط به Prompt از طریق رابط کاربری سراسری LanguageModel قابل دسترسی است.

// 1. Set your expected inputs and outputs. This is multimodal, so you can
// include other types here, too
const languages = {
   expectedInputs: [{type: "text", languages: ["en"]}],
   expectedOutputs: [{type: "text", languages: ["en"]}],
}

// 2. Check availability. Always pass in your expected inputs and outputs,
// as some models may only support some inputs and outputs
const availability = await LanguageModel.availability(languages);
// 'available', 'downloading', or 'unavailable'

// 3. Create an isolated session with system prompt and language constraints
const session = await LanguageModel.create({
  ...languages,
  // Optional: add initial context to your session, like a system prompt
  initialPrompts: [
   {
      role: 'system',
      content: 'You are an expert outdoors sales assistant...'
   }
  ]
});

// 4. Define your expected output as JSON Schema
const schema = {
   //...
}

// 5. Prompt the model (supports plain text or structured models)
const result = await session.prompt('Recommend a 3-season tent footprint.', {
  responseConstraint: schema,
});

بهترین شیوه‌های مدیریت حافظه:

• شما می‌توانید با clone() یک session، وضعیت کامل پنجره context آن را کپی کنید و از cloneها به صورت مستقل استفاده کنید و مدت زمان لازم برای راه‌اندازی یک session جدید را کاهش دهید.
• وقتی کارتان با یک جلسه تمام شد، آن را destroy() تا منابع آزاد شوند.

تمرین ۱: توصیه‌های مبتنی بر سفر

سایت‌های تجارت الکترونیک معمولاً دارای چرخ و فلک یا پیشنهادهای ویژه برای اقلامی هستند که «اغلب با هم خریداری می‌شوند». برای چیزی مانند یک سایت در زمینه فضای باز، ممکن است مفیدتر باشد که این توصیه‌ها را بر اساس سابقه مرور ایجاد کنید.

برای انجام این کار، شما یک خط تولید توصیه سه مرحله‌ای ایجاد خواهید کرد:

1. پروفایل سفر : با استفاده از API Prompt، جدول زمانی مرور مشتری را به ترتیب زمانی تجزیه و تحلیل می‌کنید تا سعی کنید قصد واقعی ماجراجویی کاربر را استنباط کنید.
2. پرس‌وجوی محصول : از این هدف، شما یک درخواست API به یک بک‌اند محصول جعلی ارسال می‌کنید تا موارد مرتبط را دریافت کنید.
3. پیشنهاد محصول : شما آن محصولات را به API محصول ارسال می‌کنید تا آنها را رتبه‌بندی کند و پنج محصول مرتبط‌تر را به آنچه کاربر مشاهده می‌کند، برمی‌گرداند.

وظیفه ۱.۱: مقداردهی اولیه API

به جای اینکه هر بار که می‌خواهید از API Prompt استفاده کنید، آن را به صورت جداگانه مقداردهی اولیه کنید، فراخوانی‌ها را در یک فایل واحد متمرکز می‌کنید و ایجاد آن توسط اعلان سیستم را به خاطر می‌سپارید تا زمان راه‌اندازی برای چندین فراخوانی به یک عامل کاهش یابد.

به فایل src/ai/prompt-api.ts بروید و تابع getPromptSession() در خطوط ۲۷ تا ۵۸ بررسی کنید:

export async function getPromptSession(
  systemPrompt: string = '',
  options: { signal?: AbortSignal } = {}
): Promise<LanguageModel>

1. استفاده مجدد از یک نشست پایه ذخیره شده. در حال حاضر یک نقشه حافظه پنهان در خط 21، baseSessions ، وجود دارد که توسط اعلان سیستم کلیدگذاری شده است. استفاده مجدد از مدل‌های پایه به جای clone() کردن مدل‌های جدید، زمان راه‌اندازی را کاهش می‌دهد و تنظیمات اصلی را بدون تداخل هر نشست با یکدیگر به ارث می‌برد. کلون را برگردانید - تماس‌گیرندگان می‌توانند با آن تعامل داشته باشند، از جمله destroy() آن، بدون اینکه پایگاه ذخیره شده شما را دور بریزند.
2. تشخیص ویژگی API. اگر API وجود داشته باشد، تشخیص ویژگی می‌دهد و در غیر این صورت خطا می‌دهد.
3. حالت‌ها و زبان‌های خود را اعلام کنید. مدل‌های داخلی می‌توانند از ورودی چندوجهی پشتیبانی کنند. شما باید حالت‌هایی را که نیاز دارید و زبان‌هایی را که می‌خواهید پشتیبانی کنید، اعلام کنید. تمام محتوایی که به LLM منتقل می‌کنید به زبان انگلیسی است.
4. قبل از ایجاد هر چیزی، در دسترس بودن آن را بررسی کنید. حتی اگر API وجود داشته باشد، ممکن است مدلی که از نیازهای شما پشتیبانی می‌کند، وجود نداشته باشد. بررسی کنید که آیا چنین API وجود دارد یا خیر. اگر وجود نداشت، خطا نمایش دهید. اگر هنوز دانلود نشده است، پیشرفت دانلود را گزارش دهید.
5. جلسه را ایجاد کنید. گزینه‌هایی را برای ایجاد یک جلسه API Prompt جدید با و اعلان سیستم، در صورت وجود، تنظیم کنید.

وظیفه ۱.۲: پیاده‌سازی پروفایل سفر مشتری

به فایل src/ai/journey-profiler.ts بروید و تابع هدف را در خطوط ۴۲ تا ۱۰۰ بررسی کنید:

export async function inferJourneyProfile(
  context: ProfilerInputContext,
  catalogMap: ReadonlyMap<string, Product>
): Promise<JourneyProfile>

1. از تابع وظیفه ۱ برای ایجاد یک جلسه اعلان جدید برای استفاده استفاده کنید.
2. مدل را با متن اعلان ارائه شده، با استفاده از journeyProfileSchema به عنوان طرحواره JSON برای بازگشت ساختاریافته، فراخوانی کنید.
3. خروجی اعلان را تجزیه کنید و دسته‌های هدف تکراری را حذف کنید.
4. رشته‌های برگشتیِ کدگذاری‌شده را با نتایج واقعیِ حاصل از اعلان خود جایگزین کنید.
5. پس از اتمام جلسه، آن را از بین ببرید تا حافظه آزاد شود.

برای مشاهده نحوه تبدیل جمع‌آوری اطلاعات زمینه به یک اعلان، src/utils/journey-helpers.ts را مطالعه کنید.

وظیفه ۱.۳: پیاده‌سازی رتبه‌بندی مجدد هم‌افزایی

به فایل src/ai/synergy-reranker.ts بروید و تابع هدف را در خطوط 30 تا 71 بررسی کنید:

export async function rankComplementaryGear(
  profile: JourneyProfile,
  candidates: readonly Product[],
  currentProduct?: Product | null,
  cartProducts?: readonly Product[],
  limit: number = 5
): Promise<readonly RecommendedItem[]>

1. از تابع وظیفه ۱ برای ایجاد یک جلسه اعلان جدید برای استفاده استفاده کنید.
2. مدل را با متن اعلان ارائه شده و طرحواره تولید شده فراخوانی کنید.
3. خروجی اعلان را تجزیه کنید.
4. لیست توصیه‌های مونتاژ شده را با استفاده از assembleRecommendations برگردانید.
5. پس از اتمام جلسه، آن را از بین ببرید تا حافظه آزاد شود.

برای مشاهده نحوه تولید اعلان و طرحواره و جمع‌آوری توصیه‌ها از نتایج اعلان src/utils/reranker-helpers.ts و src/utils/recommendation-schemas.ts را مطالعه کنید.

تأیید خط لوله توصیه

1. کروم را باز کنید و به http://localhost:5173/catalog/tent-mont-tremblant-3p .
2. به پایین اسکرول کنید تا به بخش «برای شما» برسید.
3. مشاهده کنید که چگونه ۵ کارت همراه، به جای محصولات تصادفی، برای انعکاس جفت‌سازی‌های هوشمند کیت (مانند ردپاهای زمینی، زیراندازهای خواب و میخ‌های سبک) به‌روزرسانی می‌شوند.
4. برای بررسی مدت زمان اجرای هر دو مرحله استنتاج در لحظه، کنسول DevTools کروم را باز کنید.

(اختیاری) وظیفه ۱.۴: بررسی مدل‌های هوش مصنوعی داخلی بیشتر

چندین مدل هوش مصنوعی داخلی دیگر نیز موجود است، از جمله مدل متخصص API مترجم . اجزای موجود در این کدبیس از قبل به سرویسی متصل شده‌اند که تغییرات در زبان فعلی را بررسی کرده و ترجمه آنها را درخواست می‌کند، و این وظیفه شماست که همه اینها را به هم متصل کنید.

به فایل src/ai/translator.ts بروید

تابع هدف createTranslator در خطوط ۲۹ تا ۴۵ بررسی کنید:

export async function createTranslator(
  targetLang: SupportedLanguage
): Promise<Translator | null>

1. پشتیبانی از رابط برنامه‌نویسی کاربردی مترجم (Translate API) را بررسی کنید و مطمئن شوید که زبان مقصد انگلیسی نیست (محتوا به طور پیش‌فرض به زبان انگلیسی است).
2. یک جفت زبانی، از انگلیسی به زبان مقصد، بسازید و بررسی کنید که آیا آن جفت زبانی موجود است یا خیر.
3. گزینه‌هایی برای مترجم ایجاد کنید و یک مانیتور ضمیمه کنید که پیشرفت دانلود مدل را نشان دهد.
4. مترجم مقداردهی اولیه شده را برمی‌گرداند.

سپس، تابع هدف translate در خطوط ۵۰ تا ۵۸ بررسی کنید:

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

5. بررسی کنید که آیا مترجمی با ارسال getCachedTranslator در targetLang موجود است یا خیر. اگر وجود نداشت، متن تمیز را برگردانید.
6. اگر وجود دارد، از مترجم برای ترجمه متن تمیز استفاده کنید.

به فایل src/ai/translator.ts بروید

render تابع هدف را در خطوط 204 بررسی کنید:

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

7. فعال کردن کامپوننت انتخاب زبان

برای مشاهده نحوه عملکرد حافظه پنهان ترجمه و اشتراک src/utils/translator-helpers.ts را مطالعه کنید.

۴. استفاده از WebMCP برای بهبود تجربه اپراتور

وب ام سی پی چیست؟

همزمان با شروع استفاده کاربران از عامل‌های خودکار و مرورگر مشترک، سازگاری وب‌سایت‌ها با این تغییرات اهمیت پیدا کرده است. عامل‌ها به‌طور سنتی برای تعیین نحوه تعامل با یک سایت، به فعال‌سازی - گرفتن اسکرین‌شات و استخراج DOM و درخت‌های دسترسی - متکی هستند. این روش کند، شکننده و مستعد خطا است و توکن‌های کاربر را هدر می‌دهد.

WebMCP با فراهم کردن امکان تعامل مستقیم توسعه‌دهندگان با عامل‌ها (Agents) برای تعامل با صفحه‌ای که در آن هستند، به حل این مشکل کمک می‌کند. عامل‌هایی که از آن‌ها پشتیبانی می‌کنند، می‌توانند از این ابزارها درست مانند ابزاری در سیستم کدنویسی شما، با ورودی‌های واضح و ساختاریافته و مقادیر بازگشتی دیکته شده توسط شما، استفاده کنند.

// Register a tool directly on document.modelContext
document.modelContext.registerTool({
  name: 'get_product_specs',
  title: 'Get Product Specs',
  description: 'Retrieve technical specifications for the active product.',
  inputSchema: {
    type: 'object',
    properties: {
      // ...
    },
  },
  annotations: {
    readOnlyHint: true, // Informs the agent this tool causes no side-effects
  },
  execute: async (input) => {
    return {
      weight: '1.8 kg',
      capacity: '3 persons',
      seasons: '3-season',
    };
  },
});

وقتی یک عامل به صفحه وب متصل می‌شود، از document.modelContext.getTools() پرس‌وجو می‌کند. هر ابزار ثبت‌شده موارد زیر را افشا می‌کند:

• name : شناسه ابزار برنامه‌نویسی که توسط عامل‌ها هنگام اجرای ابزارها استفاده می‌شود (مثلاً 'get_product_specs' ).
• title : برچسب نمایشی قابل خواندن توسط انسان که توسط بازرسان و رابط‌های عامل استفاده می‌شود (مثلاً 'Get Product Specs' ).
• description : توضیحات متنی ساده که به مدل اطلاع می‌دهد ابزار چه کاری انجام می‌دهد و چه زمانی باید آن را فراخوانی کند. اینگونه است که یک عامل تعیین می‌کند که آیا باید ابزار را فراخوانی کند یا خیر، بنابراین توصیفی باشد.
• inputSchema : طرحواره JSON که آرگومان‌های پذیرفته‌شده را تعریف می‌کند.
• annotations : نکات رفتاری، مانند { readOnlyHint: true } برای ابزارهای فقط خواندنی که هیچ عارضه جانبی وضعیتی ایجاد نمی‌کنند.
• execute : تابع ناهمزمان هنگام فراخوانی ابزار اجرا می‌شود.

بهترین شیوه‌ها: بهترین شیوه‌ها برای چگونگی ساخت ابزارها به صورت جزئی‌تر هنوز در حال تکامل است. به نظر می‌رسد ابزارهای جزئی‌تر که نمایندگان می‌توانند با آنها سفر کاربری خود را بسازند، به عنوان بهترین شیوه در حال ظهور هستند، نه ابزارهای جامع، بنابراین این همان چیزی است که در اینجا ارائه می‌شود.

وظیفه ۲.۱: ابزارهای توصیه و محصول

شما با ثبت ابزاری شروع می‌کنید که به عامل‌ها اجازه می‌دهد توصیه‌هایی را که در تمرین قبلی ساخته‌اید، بازیابی کنند.

به فایل src/components/product/ForYouSection.ts بروید.

تابع registerWebMCPTools() در خطوط ۷۱ تا ۹۴ بررسی کنید:

private registerWebMCPTools(): void

1. بررسی کنید که آیا WebMCP پشتیبانی می‌شود یا خیر.
2. اگر چنین است، ابزار را ثبت کنید.

• عنوان و توضیحی انتخاب کنید که یک عامل را به انتخاب ابزار ترغیب کند - در اینجا به مهندسی سریع فکر کنید.
• هیچ ورودی وجود ندارد، بنابراین فقط یک شیء خالی JSON Schema را وارد کنید.
• این یک ابزار فقط خواندنی است.
• در تابع اجرا، از recommendationStore برای دریافت مجموعه توصیه‌های فعلی استفاده کنید، سپس شناسه محصول فعلی و مجموعه توصیه‌های محصول را برگردانید.
• یک سیگنال لغو اضافه کنید و آن را دریافت کنید تا خطایی ایجاد نشود. این کار تضمین می‌کند که ابزار هنگام unmount شدن کامپوننت به درستی حذف شود.

به فایل src/views/ProductView.ts بروید.

3. همین فرآیند را برای ثبت ابزار get_current_product تکرار کنید، این بار محصول کامل و همچنین توصیه‌ها را برگردانید.

نکته: ثبت ابزار در سطح کامپوننت انجام می‌شود، بنابراین وقتی کامپوننت‌ها برای ایجاد یک صفحه با هم ترکیب می‌شوند، ابزارهای آنها نیز همراه آن می‌آیند.

وظیفه ۲.۲: ابزارهای کشوی سبد خرید

به فایل src/components/cart/CartDrawer.ts بروید.

تابع registerWebMCPTools() در خطوط ۸۳ تا ۱۱۴ بررسی کنید:

private registerWebMCPTools(): void

1. ابزار view_cart را ثبت کنید:

• inputSchema آن باید یک شیء با یک گزینه بولی واحد، openDrawer ، باشد.
• فقط باید خوانده شود.
• ورودی را به عنوان بخشی از تابع execute بخوانید، تصمیم بگیرید که سبد خرید را نمایش دهید یا پنهان کنید، recommendationStore رفرش کنید، سپس خلاصه سبد خرید را برگردانید

2. ابزار manage_cart را ثبت کنید:

• inputSchema آن باید یک شیء با items باشد که خود آرایه‌ای از اشیاء با productID ، add ، remove و update action enum و integer quantity است.
• تابع execute باید آیتم‌ها را به this.updateCart ارسال کند.

وظیفه ۲.۳: ابزار تغییر زبان

با قرار دادن یک ابزار زبانی در معرض عوامل خارجی، WebMCP را فراتر ببرید.

به فایل src/components/navigation/LanguagePicker.ts بروید.

تابع registerWebMCPTools() در خطوط ۶۱ تا ۶۳ بررسی کنید:

private registerWebMCPTools(): void

1. ابزار switch_language را ثبت کنید:
   • inputSchema باید یک ویژگی language داشته باشد که یک شمارشی از SUPPORTED_LANGUAGE_CODES است.
   • تابع execute آن باید this.switchLanguage را با زبان ارائه شده فراخوانی کند.

وظیفه ۲.۴: ابزارهای ناوبری فروشگاه

به نمایندگان مستقل اجازه دهید تا در فروشگاه پیمایش کنند، به صفحات محصول بروند، دسته‌ها را مرور کنند یا جستجوها را آغاز کنند.

به فایل src/components/navigation/SiteHeader.ts بروید.

تابع registerWebMCPTools() در خطوط ۱۵۵ تا ۱۷۱ بررسی کنید:

private registerWebMCPTools(): void

1. بررسی کنید که آیا WebMCP پشتیبانی می‌شود یا خیر.
2. ابزار search را ثبت کنید:
   • طرح ورودی یک رشته query string) می‌گیرد.
   • در هنگام execute ، this.search(input?.query) را فراخوانی کنید.
3. ابزار go_to_catalog را ثبت کنید:
   • طرح ورودی، activity اختیاری (تعدادی از ACTIVITIES ) و category (تعدادی از PRODUCT_CATEGORIES ) را می‌پذیرد.
   • در هنگام execute ، this.goToCatalog(input?.activity, input?.category) را فراخوانی کنید.
4. ابزار get_categories_and_activities را ثبت کنید:
   • ابزار فقط خواندنی بدون پارامتر ورودی.
   • در هنگام execute ، this.getCategoriesAndActivities() را فراخوانی کنید.
5. ابزار go_to_product را ثبت کنید:
   • طرح ورودی به یک رشته productId نیاز دارد.
   • در هنگام execute ، this.goToProduct(input?.productId) را فراخوانی کنید.

با بازرس WebMCP تأیید کنید

1. آدرس http://localhost:5173/catalog/tent-mont-tremblant-3p در کروم مجدداً بارگذاری کنید و به صفحه محصول بروید.
2. Chrome DevTools > Application > WebMCP را باز کنید.
3. شما باید ابزارهای WebMCP خود را ببینید: get_recommendations ، get_current_product ، view_cart ، manage_cart ، switch_language ، search ، go_to_catalog ، get_categories_and_activities و go_to_product .
4. برای مشاهده جزئیات و پارامترهای هر یک، روی یکی از آنها کلیک کنید.
5. یکی را با پارامترها انتخاب کنید، چند مورد را انتخاب کنید و روی اجرای ابزار کلیک کنید تا آن را در عمل ببینید.
6. (اختیاری) اگر WebMCP Model Context Tool Inspector را نصب و راه‌اندازی کرده‌اید، آن را باز کنید—در پنل کناری کروم باز می‌شود. از رابط چت استفاده کنید تا به اپراتور بگویید اقدامی را انجام دهد که به نظر شما باید یکی از ابزارهای شما را فراخوانی کند تا ببینید چگونه پاسخ می‌دهد.

۵. (اختیاری) ایجاد یک نماینده در محل

فراخوانی ابزارهای WebMCP در صفحه

ابزارهای WebMCP فقط برای افزونه‌های مرورگر خارجی یا ربات‌های شخص ثالث نیستند - برنامه خودتان می‌تواند مستقیماً آنها را فراخوانی کند . با پرس و جو از document.modelContext.getTools() ، کد سمت کلاینت شما می‌تواند ابزارها را به صورت پویا کشف و اجرا کند.

شما می‌توانید از این برای ساخت یک دستیار خرید هوش مصنوعی در محل استفاده کنید و نوار جستجو را به ابزاری برای کشف محصول بر اساس ورودی زبان طبیعی تبدیل کنید. به جای نوشتن کد دستوری سفارشی برای هماهنگ کردن فیلترهای وجهی متعدد، نوار جستجوی شما می‌تواند پرس‌وجوهای زبان طبیعی را به Prompt API تحویل دهد، که تصمیم می‌گیرد کدام ابزارهای WebMCP درون صفحه‌ای را فراخوانی کند.

بهترین شیوه‌ها: در حالی که عاملی که شما در حال ساخت آن هستید جایگزین نوار جستجو می‌شود، نباید از LLM برای جستجوی سایت استفاده کنید - الگوها و الگوریتم‌های بسیار کارآمدتر، دقیق‌تر و جاافتاده‌تری برای آن وجود دارد. این فقط برای نشان دادن فراخوانی ابزارهای WebMCP سایت خودتان به صورت غیرقطعی است.

برای کشف و فراخوانی یک ابزار WebMCP از جاوا اسکریپت:

// getTools() returns a Promise — it must be awaited.
const tools = await document.modelContext.getTools();
const tool = tools.find(t => t.name === 'list_items');

const json = await document.modelContext.executeTool(tool, args);
const result = JSON.parse(json); // executeTool resolves with a DOMString

وظیفه ۳.۱: ابزارهای وجهی نوار کناری

هر وجه نوار کناری کاتالوگ را در معرض WebMCP قرار دهید تا کارشناسان (و دستیار جستجوی درون صفحه‌ای شما) بتوانند فیلترها را به صورت برنامه‌نویسی‌شده تغییر دهند.

هر کامپوننت وجهی در src/components/facets/ از قبل یک متد کمکی در کلاس خود و یک طرحواره ورودی اکسپورت شده در src/utils/filter-schemas.ts ارائه می‌دهد:

1. در src/components/facets/ActivityFacet.ts :
   • با استفاده از activityFilterSchema activity_filter را ثبت کنید.
   • در هنگام execute ، this.filterActivity(input?.activity, input?.selected) را فراخوانی کنید.
2. در src/components/facets/CategoryFacet.ts :
   • با استفاده از categoryFilterSchema category_filter را ثبت کنید.
   • در هنگام execute ، this.filterCategory(input?.category, input?.selected) را فراخوانی کنید.
3. در src/components/facets/ConditionFacet.ts :
   • با استفاده از conditionFilterSchema condition_filter را ثبت کنید.
   • در هنگام execute ، this.filterCondition(input?.condition, input?.selected) را فراخوانی کنید.
4. در src/components/facets/PriceFacet.ts :
   • با استفاده از priceFilterSchema price_filter را ثبت کنید.
   • در هنگام execute ، this.filterPrice(input?.priceRange || input?.bracket, input?.selected) را فراخوانی کنید.
5. در src/components/facets/WeightFacet.ts :
   • با استفاده از weightFilterSchema weight_filter را ثبت کنید.
   • در هنگام execute ، this.filterWeight(input?.weightRange || input?.bracket, input?.selected) را فراخوانی کنید.
6. در src/components/facets/RatingFacet.ts :
   • با استفاده از ratingFilterSchema rating_filter را ثبت کنید.
   • در هنگام execute ، this.filterRating(input?.minRating || input?.rating, input?.selected) را فراخوانی کنید.
7. در src/components/facets/SearchFacet.ts :
   • با استفاده از keywordFilterSchema keyword_filter را ثبت کنید.
   • در هنگام execute ، this.updateKeyword(input?.keyword) را فراخوانی کنید.

به یاد داشته باشید که پشتیبانی WebMCP را بررسی کنید و { signal: this.signal } را همانطور که در مرحله 2 یاد گرفتید، با .catch(() => {}) ارسال کنید.

وظیفه ۳.۲: ابزارهای نمایش کاتالوگ

اکنون فهرست‌بندی در سطح کاتالوگ، تنظیم مجدد فیلتر و ابزارهای جستجوی معنایی را در document.modelContext ثبت کنید.

به فایل src/views/CatalogView.ts بروید.

تابع registerWebMCPTools() در خطوط ۱۲۵ تا ۱۴۰ بررسی کنید:

private registerWebMCPTools(): void

1. بررسی کنید که آیا WebMCP پشتیبانی می‌شود یا خیر.
2. ابزار list_items را ثبت کنید:
   • هیچ پارامتر ورودی نمی‌گیرد و فقط خواندنی است.
   • تابع execute آن باید this.getItemsSummary() را فراخوانی کند.
3. ابزار reset_filters را ثبت کنید:
   • هیچ پارامتر ورودی نمی‌گیرد.
   • تابع execute آن باید this.resetFilters() را فراخوانی کند.
4. ابزار semantic_catalog_filter را ثبت کنید:
   • از semanticCatalogFilterSchema استفاده کنید.
   • تابع execute آن باید interpretAndApplySemanticFilter(input.query) را فراخوانی کند.

وظیفه ۳.۳: هماهنگ‌سازی عامل فیلتر معنایی

حالا وقت آن رسیده که همه چیز را به هم وصل کنیم. این کار، جستجو را به یک خط لوله معنایی تبدیل می‌کند که ابزار semantic_catalog_filter را قدرت می‌دهد:

به فایل src/ai/catalog-semantic-filter.ts بروید

تابع prewarmSemanticFilterSession() در خطوط ۸۴ تا ۸۸ بررسی کنید:

export async function prewarmSemanticFilterSession(): Promise<void>

1. بررسی کنید که آیا warmSession از قبل وجود دارد یا خیر؛ اگر چنین است، زودتر برگردید.
2. یک سشن API مربوط به Prompt را با استفاده از SEMANTIC_FILTER_SYSTEM_PROMPT و با استفاده از getPromptSession() پیش گرمایش (Prewarm) کنید و آن را در warmSession ذخیره کنید. آن را در یک بلوک try/catch قرار دهید تا در صورت عدم موفقیت پیش گرمایش، ایجاد جستجو همچنان بتواند به راحتی به حالت اولیه خود بازگردد.

تابع inferSearchFacets() در خطوط ۹۳ تا ۱۳۴ بررسی کنید:

async function inferSearchFacets(
  searchTerm: string,
  cachedJourney: JourneyProfile | null
): Promise<{ parsed: SemanticFilterResponse; cacheHit: boolean }>

3. در صورت وجود، نشست از پیش گرم شده را از warmSession درخواست کنید (و warmSession به null تنظیم مجدد کنید)، یا با استفاده از getPromptSession(SEMANTIC_FILTER_SYSTEM_PROMPT) یک نشست جدید ایجاد کنید.
4. مدل را با promptText و با استفاده از semanticFilterSchema به عنوان responseConstraint فراخوانی کنید.
5. JSON برگردانده شده را تجزیه کن، نتیجه تجزیه شده را با cacheKey در حافظه پنهان دائمی ذخیره کن، و جلسه را در یک بلوک finally از بین ببر.

تابع applyFacetsViaWebMCP() در خطوط ۱۳٩ تا ۲٧٠ بررسی کنید:

async function applyFacetsViaWebMCP(
  searchTerm: string,
  parsed: SemanticFilterResponse
): Promise<{ appliedFilters: SemanticFilterResult['appliedFilters']; toolsExecuted: string[] }>

6. با استفاده از await document.modelContext.getTools() ابزارهای ثبت شده در document.modelContext را کشف کنید.
7. با فراخوانی تابع await executeFacet('reset_filters', {}) فیلترها را برای شروع با یک صفحه سفید، ریست کنید.
8. همزمان با استفاده از await Promise.all(facetTasks) جنبه‌های فعال را اعمال کنید.

تابع interpretAndApplySemanticFilter() در خطوط ۲۷۲ تا ۳۱۶ بررسی کنید:

export async function interpretAndApplySemanticFilter(
  searchTerm: string
): Promise<SemanticFilterResult>

9. با فراخوانی inferSearchFacets(searchTerm, cachedJourney) جنبه‌های جستجو را استنباط کنید.
10. با استفاده از applyFacetsViaWebMCP(searchTerm, parsed) وجوه استنباط شده را به کاتالوگ اعمال کنید.

عامل درون صفحه‌ای را تأیید کنید

1. به آدرس http://localhost:5173/catalog بروید.
2. در نوار جستجوی بالا، "lightweight 3 season tent for wet hikes" را وارد کنید.
3. ببینید که Prompt API درخواست را تجزیه می‌کند، activity_filter (Hiking)، category_filter (Tents) و condition_filter (Wet) را فراخوانی می‌کند و فوراً کاتالوگ را به تجهیزات منطبق، بدون هیچ کلیک دستی روی چک‌باکس، محدود می‌کند.

۶. آنچه آموختید

تبریک می‌گویم. شما یک اپلیکیشن تجارت الکترونیک را به یک تجربه هوشمند و مبتنی بر عامل تبدیل کرده‌اید که کاملاً توسط هوش مصنوعی روی دستگاه و APIهای استاندارد پلتفرم وب پشتیبانی می‌شود.

چیزی که ساختی:

• API اعلان روی دستگاه : جدول‌های زمانی مرور کاربر را با LanguageModel ترکیب کرد تا زمینه JourneyProfile به صورت بلادرنگ تولید کند و یک موتور هم‌افزایی rankComplementaryGear با استفاده از طرحواره‌های ساختاریافته JSON ( responseConstraint ) ساخت.
• ابزارهای کامپوننت WebMCP : ابزارهای ماژولار ثبت‌شده و کپسوله‌شده در سراسر کامپوننت‌های رابط کاربری ( get_recommendations ، get_current_product ، view_cart ، manage_cart ) از طریق document.modelContext .
• معماری عامل رو به جلو : اجرای ابزار با استفاده از افزونه Chrome WebMCP Inspector آزمایش و تأیید شده است.
• عامل درون صفحه‌ای در سایت : ابزارهای سمت کلاینت هماهنگ‌شده مستقیماً در مرورگر برای تقویت جستجوی کاتالوگ چندوجهی زبان طبیعی از نوار جستجوی سربرگ سایت.
• مدل‌های تخصصی هوش مصنوعی روی دستگاه : بررسی ترجمه پویا روی دستگاه با استفاده از Translator .

نکات کلیدی:

1. بدون تأخیر و حریم خصوصی بالا : مدل‌های روی دستگاه مانند Gemini Nano نگرانی‌های مربوط به کلیدهای API ابری، تأخیر شبکه و نشت داده‌ها را از بین می‌برند.
2. خروجی‌های ساختاریافته ضروری هستند : استفاده از طرحواره‌های JSON به همراه responseConstraint ، تولید متن خلاقانه را به منطق کاربردی قابل اعتماد و ایمن از نظر نوع تبدیل می‌کند.
3. WebMCP وب را برای عامل‌های هوش مصنوعی آماده می‌کند : ثبت مستقیم ابزارها در DOM، هم ویژگی‌های کمکی داخلی و هم عامل‌های مرورگر مستقل خارجی را با اقدامات قطعی و تأیید شده توانمند می‌سازد.
4. بگذارید مدل پیشنهاد دهد، نه اجرا کند : محدود کردن مدل به enum از ابزارهای ثبت‌شده و ارسال نتیجه توسط خودتان، رفتار عامل‌محور را قابل حسابرسی نگه می‌دارد و از ابداع اقدامات توسط آن جلوگیری می‌کند.