Brauzer layihəsində kitabxanalar və CDN

Claude Code-dan brauzerdə şahmat oyunu hazırlamağı xahiş edirsiniz. Səhifəni açırsınız: taxta yerindədir, fiqurlar düzülüb, piyada siçanın ardınca tərpənir. Oynamaq olar. Yoxlamaq üçün piyadanı birdən üç xana irəli çəkirsiniz - və o, orada qalır. Sonra qara fiqurlarla ardıcıl iki gediş etməyə çalışırsınız. Səhifə yenə etiraz etmir.

Bu iki gedişə qədər layihə az qala hazır görünürdü. İndi isə əsas şeyin hələ işləmədiyi aydın olur: qaydaları heç kim yoxlamır. Agentdən piyadanın belə gedişini qadağan etməyi istəyə bilərsiniz. Amma sonra növbənin kimdə olması, şah, rokirovka və piyadanın çevrilməsi məsələlərini də həll etmək lazım gələcək. Hər düzəlişdən sonra bir sual qalır: daha hansı şərti unutmusunuz?

Belə məqamda dayanıb bu iş üçün hazır kod axtarmaq faydalıdır. Şahmat qaydaları artıq chess.js kitabxanasında həyata keçirilib. Ona gedişi ötürüb yoxlamanın nəticəsini ala bilərsiniz. Beləliklə, öz kodunuz aydın bir əlaqəyə cavabdeh olur: taxtadan gedişi götürmək, kitabxana ilə yoxlamaq və fiqurların düzgün vəziyyətini göstərmək.

Kitabxananı brauzerə çatdırıb səhifənin işinə qoşmaq qalır. Bunun bir yolu onu CDN linki ilə yükləməkdir. Aşağıda bunun necə işlədiyinə və kodda link peyda olsa da, piyadanın niyə hələ istədiyi yerə gedə bildiyinə baxacağıq.

Kitabxana nə edir

Kitabxana başqasının yazdığı koddur; onu öz layihənizə qoşursunuz ki, artıq yazılmış şeyi yenidən yazmayasınız. chess.js məhz belə kitabxanadır: hər fiqurun necə getdiyini, şahın və rokirovkanın nə olduğunu bilir, hazırkı vəziyyətdə mümkün olan bütün gedişləri sadalaya və oyunun bitib-bitmədiyini deyə bilir.

Burada bir tələyə düşmək asandır: kitabxananı qoşub oyunun işləyəcəyini gözləmək. İşləməyəcək. Kitabxana qaydaları və oyunun vəziyyətini öz yaddaşında saxlayır, heç nə çəkmir və səhifədə taxtanın olmasından xəbərsizdir.

Adi gediş zamanı nə baş verdiyinə baxın. Piyadanı e2-dən birbaşa e5-ə çəkirsiniz. İnterfeys sürükləməni görür, əlaqələndirici kod kitabxanadan "belə gedişə icazə var?" deyə soruşur, kitabxana "yox" cavabını verir - əlaqələndirici kod da fiquru e2-yə qaytarır. Bu sualı heç kim verməsə, piyada rahatca e5-də qalacaq: səhifənin onu orada çəkməsinə heç nə mane olmur.

Hər iki qol eyni hərəkətlə bitir: əlaqələndirici kod kitabxanadakı vəziyyəti göstərir. Düzgün gedişdən sonra vəziyyət yenilənir, səhv gedişdən sonra isə dəyişməz qalır; buna görə fiqur ilkin xanasına qayıdır.

Buradan tapşırığın necə ifadə edilməsi barədə nəticə çıxır. "chess.js-i qoş" xahişini hərfi mənada yerinə yetirmək olar - yükləmə sətri əlavə edilər və bununla da iş bitər. Siz əlaqəni tapşırmalısınız: taxtadakı gediş kitabxanaya ötürülür, kitabxananın cavabı fiqurun hərəkət edib-etməyəcəyini müəyyən edir, gedişdən sonrakı vəziyyət isə siçanı buraxdığınız yerə yox, kitabxananın vəziyyətinə əsaslanır.

Brauzer kodu CDN vasitəsilə necə alır

Kitabxana faylını haradansa götürmək lazımdır. Onu endirib səhifənizin yanında saxlaya və ya səhifə kodunda xarici xidmətdəki fayla link göstərə bilərsiniz. Bunun üçün çox vaxt CDN (Content Delivery Network, məzmun çatdırma şəbəkəsi) istifadə olunur. Bu, müxtəlif yerlərdəki istifadəçilərə faylları çatdıran serverlər şəbəkəsidir. Məsələn, şəkillər, stillər və JavaScript kitabxanaları CDN vasitəsilə çatdırılır. Bizim nümunədə kitabxana faylını jsDelivr xidməti verir.

Səhifəni açanda brauzer onun kodunu oxuyur və kitabxananın linkinə rast gəlir. Həmin ünvana sorğu göndərir, faylı yükləyir, sonra isə kitabxanadan istifadə edən səhifə kodunu icra edir. Kitabxana istifadəçinin brauzerində işləyir. CDN onun kodunu çatdırır; şahmat gedişlərinin yoxlanması isə artıq sizin cihazınızda baş verir.

Sxemdəki çərçivə brauzeri xarici xidmətdən ayırır. Yükləndikdən sonra kitabxana səhifənin daxilində olur: əlaqələndirici kod elə oradaca ona müraciət edir. Hər gedişi CDN-ə göndərmək lazım deyil.

chess.js belə qoşulur:

<script type="module">
  import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'

  const chess = new Chess()
  console.log(chess.fen())
  // rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>

Burada üç məqam vacibdir. Birincisi - type="module". Kitabxana ES modulu kimi gəlir və Chess-i ondan yalnız import ilə götürmək olar; adi <script src="..."> teqi həmin faylı oxuya bilməyəcək - daxilindəki export sətrində xəta verəcək. Bəzi kitabxanaların modulsuz köhnə paylanma forması da var: orada adi teq kifayətdir və səhifədə qlobal dəyişən özü yaranır. chess.js üçün belə build yoxdur, yəni yalnız bu variant qalır.

İkinci məqam - versiya nömrəsinin birbaşa ünvanda olmasıdır: chess.js@1.4.0. Qoşulma üsulunu və metod adlarını linkdəki məhz həmin versiyanın sənədlərindən götürün. Nömrəsiz ünvan gec-tez başqa fayla aparacaq və köhnə sənədlərə əsasən yazılmış kod işləməyəcək.

Üçüncü və gözdən qaçması ən asan məqam ünvanın sonundakı /+esm hissəsidir. Bu, bəzək deyil, CDN-ə faylı məhz modul formasında yığmaq üçün verilən göstərişdir: bu hissə olmadan eyni ünvandan başqa build gələcək və import heç nə tapa bilməyəcək.

Bütün oyunu yığmadan da kitabxananın həqiqətən yükləndiyini yoxlaya bilərsiniz - həmin <script type="module"> blokuna bir neçə sətir əlavə edin və brauzerin konsolunu açın (developer tools-da Console bölməsi, F12 və ya Ctrl+Shift+I):

// ağ piyada e2-dən birbaşa e5-ə gedə bilməz
try {
  chess.move('e5')
} catch (error) {
  console.log('gediş rədd edildi:', error.message) // Invalid move: e5
}

chess.move('e4')          // kitabxana bu gedişi qəbul edir
console.log(chess.turn()) // b, qara fiqurların növbəsidir

Konsolda başlanğıc vəziyyəti, rədd edilmiş gediş və e4-dən sonra növbənin qaralara keçməsi faylın yükləndiyini, qaydaların da işlədiyini göstərir. İndi onları taxta ilə əlaqələndirmək qalır.

Bir qeydi də nəzərə alın ki, yanlış təsəvvür yaranmasın. CDN şəbəkədən asılılığı aradan qaldırmır. Brauzer faylın keşdəki, yəni özündə saxladığı nüsxəsindən yenidən istifadə edə bilər, buna görə onu səhifəni hər açanda təzədən yükləmək vacib deyil. Amma uyğun nüsxə yoxdursa və CDN əlçatan deyilsə, kitabxana yüklənməyəcək və oyun onun qaydaları ilə işləyə bilməyəcək.

Claude Code ilə birlikdə necə işləyir

"Kitabxananı CDN vasitəsilə qoş" xahişi agent üçün bir neçə qərarı açıq saxlayır: faylı haradan götürmək, hansı versiyanı seçmək, onu bu səhifəyə necə yükləmək və nəticəni necə təsdiqləmək. Bu qərarları birbaşa tapşırıqda göstərmək rahatdır. Aşağıda müxtəlif hallar üçün prompt-lar var; hamısını ard-arda göndərmək vacib deyil.

Qoşulma linkini seçin

Agent kitabxana təklif edirsə, əvvəlcə ondan kitabxananın layihənizdə necə qoşulacağını araşdırmasını xahiş edin. Beləliklə, konkret ünvan və onun haradan götürüldüyünə dair izah alacaqsınız.

Səhifəmin necə qurulduğuna bax və chess.js-in artıq qoşulub-qoşulmadığını yoxla.
Kitabxananın və jsDelivr-in sənədlərində brauzerə uyğun CDN yükləmə üsulunu
araşdır. Konkret versiyalı URL təklif et və ünvanın hissələrini izah et.
Sənədlərin linklərini ver. Hələlik kodu dəyişmə.
Sənədləri yoxlaya bilməsən, bunu bildir.

Cavabda versiya nömrəsini, qoşulma üsulunu və seçim səbəbini axtarın. Təkcə "işlək link budur" cavabı azdır: ondan agentin ünvanı sənədlərlə tutuşdurub-tutuşdurmadığı və faylın səhifənizə uyğun olub-olmadığı aydın olmur.

Kitabxananı taxtaya qoşun

Ünvan seçiləndən sonra agentə görünən nəticəsi olan tapşırıq verin. Sadə HTML səhifəsində mövcud işə salma üsulunu saxlamaq istədiyinizi də əvvəlcədən deyə bilərsiniz.

chess.js-i seçilmiş CDN ünvanından, sabit versiya ilə qoş.
Səhifəni işə salmağın mövcud üsulunu saxla. Kitabxananı taxta ilə əlaqələndir:
hər gedişi ona ötür və taxtada onun saxladığı vəziyyəti göstər.
Səhv gediş zamanı fiquru ilkin xanasına qaytar.
Qoşulmanın harada əlavə olunduğunu və kitabxananın cavabının harada
emal edildiyini göstər.

Burada iki ayrı nəticə var: brauzer kitabxananı aldı, taxtadakı hərəkətlər isə onun qaydaları ilə yoxlanmağa başladı. Kodda hər iki yeri göstərməsini xahiş etsəniz, agentin konkret nə əlavə etdiyini görə biləcəksiniz.

Nəticəni brauzerdə yoxlayın

HTML-də linkin olması yalnız faylın dəyişdirildiyini təsdiqləyir. Növbəti tapşırıq yükləməni və oyunun davranışını yoxlamağa kömək edir.

Səhifəni aç və developer tools-un Network bölməsində chess.js-in
yüklənməsini yoxla. Console-da xətalara bax. Sonra başlanğıc vəziyyətindən
e2-e5 gedişini etməyə çalış: gediş rədd edilməli, piyada e2-də qalmalıdır.
Ardınca e2-e4 et: gediş qəbul olunmalı, növbə qaralara keçməlidir.
Hər addımda nə müşahidə etdiyini bildir. Brauzerə girişin yoxdursa,
mənə qısa yoxlama addımları ver və bunu özün yoxlamadığını qeyd et.

Network bölməsində səhifənin şəbəkə sorğuları, Console-da isə kodunun mesaj və xətaları görünür. Fayl yüklənsə də piyada e5-ə gedirsə, səbəbi artıq gedişin emalında axtarmaq lazımdır. CDN linkini dəyişmək bu əlaqəni öz-özünə düzəltməyəcək.

Yükləmə xətasını araşdırın

Xəta baş verəndə Console-dakı dəqiq xəta mətnini və Network-də uğursuz sorğunun ünvanını agentə ötürün. Beləliklə, o, linkləri təkrar-təkrar sınamaq əvəzinə konkret səbəbi yoxlaya bilər.

Kitabxananı qoşduqdan sonra səhifədə xəta görünür.
Console-dakı mətn: [mesajı tam şəkildə bura yapışdırın].
Network-də URL və sorğunun nəticəsi: [ünvanı və statusu bura yazın].
Faylın əlçatan olub-olmadığını, formatının importumuza uyğun gəlib-gəlmədiyini
və koddakı adların seçilmiş versiyanın sənədlərinə uyğun olub-olmadığını yoxla.
Əvvəlcə bu məlumatlara əsasən səbəbi de, sonra minimal düzəliş et
və yoxlamanı təkrarla. CDN-i, versiyanı və oyun kodunu eyni vaxtda dəyişmə.

Kvadrat mötərizədəki mətni öz məlumatlarınızla əvəz edin. Network-də kitabxana sorğusu ümumiyyətlə yoxdursa, bunu da yazın: bu da faydalı ipucudur. Düzəlişdən sonra bütün əlaqənin işlədiyinə əmin olmaq üçün iki gedişin yoxlamasını təkrarlayın.

CDN-in əlçatmazlığını nəzərə alın

Kitabxana yüklənməyəndə aktiv görünən taxta hələ də oynamağın mümkün olduğu barədə yanlış təəssürat yarada bilər. Agentdən bu vəziyyəti istifadəçiyə aydın göstərməsini xahiş edin.

chess.js-in CDN-dən yüklənə bilmədiyi vəziyyəti emal et.
Kitabxana hazır olana qədər gedişlərə icazə vermə. Xəta zamanı
aydın mesaj və səhifəni yenidən yükləmək imkanı göstər.
CDN sorğusu bloklananda, sonra isə blok götürüləndə davranışı yoxla.
Keşi nəzərə al: şəbəkəni sadəcə söndürmək əvvəl yüklənmiş nüsxəni
əlçatan saxlaya bilər. Xətanı konkret necə yoxladığını təsvir et.

Bu yoxlamanı adi partiyadan ayrı aparmaq rahatdır. Nəticədə iki aydın vəziyyət görməlisiniz: kitabxana əlçatandır və gedişlər yoxlanır; yükləmə alınmayıb və səhifə hələ niyə oynamaq mümkün olmadığını izah edir.